# Fusion Storybook

A component library built with a modern tech stack for maximum reusability across multiple projects.

Phone fields are treated as canonical digits-only values in data state and are formatted only for presentation in read-only views and inputs.

## Tech Stack

- **[Next.js 16](https://nextjs.org/)** - React framework with App Router
- **[TypeScript](https://www.typescriptlang.org/)** - Type-safe JavaScript
- **[Tailwind CSS v4](https://tailwindcss.com/)** - Utility-first CSS framework
- **[ShadcnUI](https://ui.shadcn.com/)** - Accessible component library built on Radix UI
- **[Storybook 10](https://storybook.js.org/)** - Component development and documentation
- **[ESLint](https://eslint.org/)** - Code linting with Next.js rules
- **[Prettier](https://prettier.io/)** - Code formatting with Tailwind class sorting
- **[Husky](https://typicode.github.io/husky/)** - Git hooks for quality enforcement
- **[lint-staged](https://github.com/okonet/lint-staged)** - Run linters on staged files
- **[commitlint](https://commitlint.js.org/)** - Enforce conventional commit messages
- **[Jest](https://jestjs.io/)** - Unit and integration testing
- **[Playwright](https://playwright.dev/)** - End-to-end browser testing

## Getting Started

### Prerequisites

- Node.js 20+
- npm 10+

### Installation

```bash
npm install
```

### Development

```bash
npm run dev
```

Open [http://localhost:3000](http://localhost:3000) to view the app.

### Storybook

```bash
npm run storybook
```

Open [http://localhost:6006](http://localhost:6006) to view the Storybook.

## Scripts

| Script                    | Description                      |
| ------------------------- | -------------------------------- |
| `npm run dev`             | Start Next.js development server |
| `npm run build`           | Build for production             |
| `npm run start`           | Start production server          |
| `npm run lint`            | Run ESLint                       |
| `npm run lint:fix`        | Run ESLint with auto-fix         |
| `npm run format`          | Format all files with Prettier   |
| `npm run format:check`    | Check formatting without writing |
| `npm run storybook`       | Start Storybook dev server       |
| `npm run build-storybook` | Build Storybook for production   |
| `npm run test`            | Run Jest unit tests              |
| `npm run test:watch`      | Run Jest in watch mode           |
| `npm run test:ci`         | Run Jest with coverage (CI mode) |
| `npm run test:e2e`        | Run Playwright e2e tests         |
| `npm run test:e2e:ui`     | Run Playwright with UI           |
| `npm run test:e2e:report` | Open Playwright HTML report      |

## Git Workflow

This project enforces code quality via Husky git hooks:

### Pre-commit

- Runs `lint-staged` which lints and formats only staged files

### Commit Message

- Enforces [Conventional Commits](https://www.conventionalcommits.org/) format via commitlint
- Examples:
  - `feat: add new button component`
  - `fix: resolve responsive layout issue`
  - `docs: update README`
  - `test: add unit tests for button`

### Pre-push

- Runs the full Jest test suite before pushing

## Project Structure

```
fusion-storybook/
├── src/
│   ├── app/              # Next.js App Router
│   │   ├── globals.css   # Global styles with ShadcnUI CSS variables
│   │   ├── layout.tsx    # Root layout
│   │   └── page.tsx      # Home page
│   ├── components/
│   │   └── ui/           # ShadcnUI components
│   │       └── button.tsx
│   ├── lib/
│   │   └── utils.ts      # Utility functions (cn helper)
│   ├── hooks/            # Custom React hooks
│   ├── stories/          # Storybook stories
│   └── __tests__/        # Jest unit tests
├── tests/
│   └── e2e/              # Playwright e2e tests
├── .husky/               # Husky git hooks
├── .storybook/           # Storybook configuration
├── .vscode/              # VS Code settings
├── components.json       # ShadcnUI configuration
├── jest.config.ts        # Jest configuration
├── jest.setup.ts         # Jest setup (testing-library/jest-dom)
├── playwright.config.ts  # Playwright configuration
├── commitlint.config.ts  # Commitlint configuration
└── .prettierrc           # Prettier configuration
```

## Adding ShadcnUI Components

Once the `shadcn` CLI can reach the registry, use:

```bash
npx shadcn@latest add button
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
```

## VS Code Integration

Install recommended extensions for the best development experience:

- **Prettier** - Code formatting
- **ESLint** - Code linting
- **Tailwind CSS IntelliSense** - Tailwind class hints
- **Storybook** - Storybook integration
- **Playwright** - Test runner integration

Format on save is enabled by default via `.vscode/settings.json`.

## Code Quality

- **ESLint** enforces Next.js and TypeScript best practices
- **Prettier** with `prettier-plugin-tailwindcss` auto-sorts Tailwind classes
- **lint-staged** runs linters only on staged files (fast!)
- **commitlint** ensures consistent commit message format