# Storybook Configuration

## Overview / Tổng quan

This Storybook setup is configured for the GoodGo web-client application with support for:

- **Next.js 14+** with App Router
- **TypeScript** with strict type checking
- **Tailwind CSS** with custom theme variables
- **Theme switching** (dark/light mode) with Context API
- **Accessibility testing** with @storybook/addon-a11y
- **Documentation** with @storybook/addon-docs

## Getting Started / Bắt đầu

### Running Storybook / Chạy Storybook

```bash
# From the web-client directory / Từ thư mục web-client
pnpm storybook

# Or from the root / Hoặc từ thư mục gốc
cd apps/web-client && pnpm storybook
```

Storybook will start on `http://localhost:6006`

### Building Storybook / Build Storybook

```bash
pnpm build-storybook
```

This creates a static build in the `storybook-static` directory.

## Configuration / Cấu hình

### Main Configuration (`main.ts`)

- **Stories location**: `../src/**/*.stories.@(js|jsx|mjs|ts|tsx)`
- **Framework**: `@storybook/nextjs-vite`
- **Path aliases**: `@/*` maps to `./src/*`

### Preview Configuration (`preview.ts`)

- **Theme Provider**: All stories are wrapped with `ThemeProvider` for theme support
- **Global Styles**: Imports `globals.css` for Tailwind CSS and theme variables
- **Accessibility**: Configured with a11y addon for accessibility testing
- **Backgrounds**: Pre-configured dark and light backgrounds

## Writing Stories / Viết Stories

### Basic Story Example / Ví dụ Story cơ bản

```tsx
import type { Meta, StoryObj } from '@storybook/react';
import { Button } from './button';

const meta: Meta<typeof Button> = {
  title: 'UI/Button',
  component: Button,
  tags: ['autodocs'],
};

export default meta;
type Story = StoryObj<typeof Button>;

export const Primary: Story = {
  args: {
    variant: 'primary',
    children: 'Button',
  },
};
```

### Story with Theme Context / Story với Theme Context

All stories automatically have access to the `ThemeProvider`, so theme-dependent components work out of the box.

```tsx
export const Themed: Story = {
  render: () => (
    <div className="bg-secondary p-4 rounded-lg">
      <Button>Theme-aware Button</Button>
    </div>
  ),
};
```

## Addons / Tiện ích

### Available Addons / Các addon có sẵn

1. **@storybook/addon-docs**: Automatic documentation generation
2. **@storybook/addon-a11y**: Accessibility testing
3. **@storybook/addon-vitest**: Test integration
4. **@chromatic-com/storybook**: Visual testing (optional)

### Using Accessibility Addon / Sử dụng Addon Accessibility

The a11y addon is automatically configured. Use the "Accessibility" tab in the Storybook UI to check for accessibility issues.

## Best Practices / Thực hành tốt nhất

1. **Bilingual Comments**: Always include EN/VI comments in stories
2. **Accessibility**: Test all components with the a11y addon
3. **Theme Testing**: Test components in both light and dark modes
4. **Documentation**: Use the `docs` parameter to add component descriptions
5. **Story Organization**: Organize stories by feature/component type

## Troubleshooting / Khắc phục sự cố

### Path Alias Issues / Vấn đề Path Alias

If you encounter import errors with `@/*` paths, ensure:
- The `viteFinal` configuration in `main.ts` is correct
- TypeScript path mapping in `tsconfig.json` matches

### Theme Not Working / Theme không hoạt động

Ensure:
- `ThemeProvider` is imported in `preview.ts`
- `globals.css` is imported in `preview.ts`
- Components use CSS variables from the theme

### Tailwind Classes Not Working / Tailwind Classes không hoạt động

Check:
- `tailwind.config.js` includes Storybook paths
- `globals.css is imported in `preview.ts`
- PostCSS is configured correctly

## Resources / Tài nguyên

- [Storybook Documentation](https://storybook.js.org/docs)
- [Next.js + Storybook Guide](https://storybook.js.org/docs/get-started/nextjs)
- [Accessibility Testing](https://storybook.js.org/docs/writing-tests/accessibility-testing)