npm package: @marketnode/mnxp
Description: Shared React and Tailwind CSS components
Latest version: 3.0.1

# MarketNode Experience

## Overview

The MarketNode Experience project aims to provide a consistent, high quality experience for users of all products on the MarketNode platform, facilitating rapid user interface delivery on our React projects.

## Getting Started

To get started with the MarketNode Experience project, follow these steps:

1. Clone the repository
2. Install the required dependencies using pnpm: `pnpm install`
3. Start the development server: `pnpm storybook`
4. Run tests: `pnpm test`
5. Run tests with coverage: `pnpm coverage`

## Usage

Once the development server is up and running, you can access the MarketNode Experience application by navigating to `http://localhost:6006` in your web browser. From there, you can explore the different features and functionalities of the application.

Ensure your application's root elements are wrapped in the `HeroUIProvider` component.

### Using default themes

Themes are configured in the tailwind.config.ts for both tailwind and HeroUI, allowing overrides for general classes and specific HeroUI implementations. An example `tailwind.config.ts` might look like this, where themes and layouts are imported directly from the `@marketnode/mnxp` library:

```typescript
import type { Config } from "tailwindcss"
import { heroui } from "@heroui/react"
import { heroLayout, heroThemes, tailwindTheme } from "@marketnode/mnxp"

const config: Config = {
  "tailwindCSS.experimental.configFile": {
    "./tailwind.config.js": "./**",
  },
  content: [
    "./src/**/*.{js,ts,jsx,tsx,mdx}",
    "./node_modules/@heroui/theme/dist/**/*.{js,ts,jsx,tsx}",
  ],
  theme: {
    extend: tailwindTheme, // Override the tailwind base theme
  },
  plugins: [
    heroui({
      defaultTheme: "light",
      defaultExtendTheme: "light",
      themes: heroThemes, // Override HeroUI theme (dark/light) values
      layout: heroLayout, // Override HeroUI layout values
    }),
  ],
  darkMode: "class",
}
```

## Contributing

We welcome contributions from the community! If you'd like to contribute to the MarketNode Experience project, please follow our [contribution guidelines](CONTRIBUTING.md) and submit a pull request.

## Rationale

Creating and maintaining a component library offers several key advantages for small teams:

1. **Consistency**: A component library ensures UI consistency across projects, reducing design discrepancies and improving the overall user experience.

2. **Efficiency**: Reusable components significantly speed up development time. Developers can focus on application logic rather than recreating basic UI elements.

3. **Maintainability**: Centralising UI components makes updates and bug fixes easier to manage. Changes can be made in one place and propagated across all projects using the library.

4. **Onboarding**: New team members can quickly understand and utilize the existing UI ecosystem, reducing the learning curve and improving productivity.

5. **Quality Control**: Standardised components can be thoroughly tested, ensuring higher quality and reducing bugs in the UI layer.

6. **Design-Development Collaboration**: A component library serves as a shared language between designers and developers, streamlining communication and reducing misunderstandings.

7. **Scalability**: As the team or number of projects grows, a component library becomes increasingly valuable, providing a solid foundation for expansion.

8. **Best Practices**: Encapsulating accessibility, performance, and responsive design considerations into reusable components ensures these best practices are consistently applied.

By investing in a component library, small teams can work more efficiently, maintain higher quality standards, and scale their development processes more effectively.

## 2. Technical Requirements

### 2.1 Development

- Use TypeScript for type safety
- Implement functional components with hooks
- Ensure components are accessible (WCAG 2.1 AA compliant where possible)
- Write unit tests for each component (minimum 80% coverage)

### 2.2 Styling

- Use Tailwind CSS for styling
- Leverage HeroUI components and utilities
- Implement a theming system compatible with Tailwind and HeroUI
- Ensure responsiveness across screen sizes

### 2.3 Documentation

- Provide usage examples for each component
- Include prop documentation
- Create Storybook stories for visual testing and documentation

### 2.4 Performance

- Optimize for tree-shaking
- Aim for a maximum bundle size of 100KB (gzipped)

## 3. Component API Structure

Each component should follow this general structure:

```typescript
interface ComponentProps {
  // Required props
  required: string;
  // Optional props with default values
  optional?: boolean;
  // Event handlers
  onClick?: (event: React.MouseEvent) => void;
  // Children
  children?: React.ReactNode;
}

const Component: React.FC<ComponentProps> = ({
  required,
  optional = false,
  onClick,
  children
}) => {
  // Component logic here
};

export Component;
```

## 4. Versioning and Release Strategy

- Follow [Semantic Versioning (SemVer)](https://semver.org/)
- Maintain a changelog
- Provide migration guides for major version updates

### 4.1 SemVer Summary

#### Major Version (X.y.z)

Increment when making incompatible API changes. Examples include:

- Removing or renaming a component
- Changing a component's API in a way that breaks existing usage
- Removing a prop from a component
- Changing the type of a prop in a non-backward compatible way
- Updating to a new major version of a core dependency (e.g., React, HeroUI)
- Dropping support for a major browser version

#### Minor Version (x.Y.z)

Increment when adding functionality in a backward-compatible manner. Examples include:

- Adding a new component
- Adding new props to existing components
- Expanding the accepted values for a prop
- Adding new variants or sizes to a component
- Implementing new features that don't break existing functionality
- Adding new utility functions or hooks

#### Patch Version (x.y.Z)

Increment for backward-compatible bug fixes. Examples include:

- Fixing a bug in a component's behavior
- Correcting styling issues
- Improving performance without changing the API
- Updating dependencies for security patches
- Refactoring internal code without changing the public API

### 4.2 Pre-release Versions

For deploying test versions, use pre-release versions:

- Release Candidate: `x.y.z-rc.n` where `n` is an incrementing integer

### 4.3 Changelog

Maintain a CHANGELOG.md file in the root of the project:

- Group changes by version number
- Within each version, subgroup by "Added", "Changed", "Deprecated", "Removed", "Fixed", and "Security"
- Include the date of the release
- Link to the full diff on GitHub between each release

### 4.4 Release Process

1. Update the CHANGELOG.md
2. Update the version in package.json
3. Create a git `release/` branch for the version
4. Push to the repository
5. Publish to nexus

### 4.5 Migration Guides

For major version updates, provide a migration guide that includes:

- Summary of breaking changes
- Step-by-step instructions for updating
- Examples of before and after code for common use cases
- Any new features or improvements in the new version

By following these guidelines, we ensure that users of the library can understand the impact of updates and manage their dependencies effectively.

## 5. Accessibility Guidelines

- Ensure proper ARIA attributes
- Maintain default browser keyboard navigation or reimplement where you break it
- Provide sufficient color contrast

## 6. Browser Support

- Latest two versions of Chrome, Firefox, Safari, and Edge

## 7. Performance Benchmarks

- Time to Interactive: < 100ms for simple components

## 8. Contribution Guidelines

- Adhere to the established code style (follow ESLint and Prettier configurations)
- Create feature branches for new components or major changes
- Conduct thorough self-review before opening Pull Requests
- Update documentation and tests alongside code changes
- Use conventional commit messages for clear version control

## Ownership

The repository is owned by the frontend community, who will review all contributions.