@fpkit/acss 1.0.0-beta.1 → 1.0.0

package/docs/guides/storybook.md

@@ -0,0 +1,828 @@
+# Storybook Guide
+
+## Overview
+
+This guide shows how to document custom components and compositions built with @fpkit/acss using Storybook. Whether you're building an internal component library or documenting your application components, Storybook provides an excellent development and documentation environment.
+
+---
+
+## Setup
+
+### Installation
+
+```bash
+npm install -D @storybook/react @storybook/react-vite @storybook/test storybook
+```
+
+### Initialize Storybook
+
+```bash
+npx storybook init
+```
+
+### Configuration
+
+```javascript
+// .storybook/main.ts
+import type { StorybookConfig } from '@storybook/react-vite'
+
+const config: StorybookConfig = {
+  stories: ['../src/**/*.stories.@(js|jsx|ts|tsx|mdx)'],
+  addons: [
+    '@storybook/addon-links',
+    '@storybook/addon-essentials',
+    '@storybook/addon-interactions',
+  ],
+  framework: {
+    name: '@storybook/react-vite',
+    options: {},
+  },
+}
+
+export default config
+```
+
+### Import fpkit Styles
+
+```javascript
+// .storybook/preview.ts
+import '@fpkit/acss/libs/index.css'
+
+export default {
+  parameters: {
+    actions: { argTypesRegex: '^on.*' },
+    controls: {
+      matchers: {
+        color: /(background|color)$/i,
+        date: /Date$/,
+      },
+    },
+  },
+}
+```
+
+---
+
+## Basic Story Structure
+
+### Creating Your First Story
+
+```typescript
+// components/CustomButton.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { Button } from '@fpkit/acss'
+
+// Your custom composed component
+const CustomButton = ({ loading, children, ...props }) => (
+  <Button {...props} disabled={loading}>
+    {loading ? 'Loading...' : children}
+  </Button>
+)
+
+const meta = {
+  title: 'Components/CustomButton',
+  component: CustomButton,
+  tags: ['autodocs'],
+  args: {
+    children: 'Click me',
+    loading: false,
+  },
+  argTypes: {
+    loading: {
+      control: 'boolean',
+      description: 'Shows loading state',
+    },
+    onClick: {
+      action: 'clicked',
+    },
+  },
+} satisfies Meta<typeof CustomButton>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const Loading: Story = {
+  args: {
+    loading: true,
+  },
+}
+```
+
+---
+
+## Story Patterns
+
+### Default Story
+
+The simplest story uses the default args from `meta`:
+
+```typescript
+export const Default: Story = {}
+```
+
+### Story with Custom Args
+
+Override specific args for different variants:
+
+```typescript
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+    children: 'Primary Action',
+  },
+}
+
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+    children: 'Secondary Action',
+  },
+}
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+    children: 'Disabled Button',
+  },
+}
+```
+
+### Story with Custom Render
+
+For complex compositions:
+
+```typescript
+import { Button, Badge } from '@fpkit/acss'
+
+export const WithBadge: Story = {
+  render: (args) => (
+    <Button {...args}>
+      <span>{args.children}</span>
+      <Badge>New</Badge>
+    </Button>
+  ),
+  args: {
+    children: 'Featured',
+  },
+}
+
+export const MultipleButtons: Story = {
+  render: () => (
+    <div style={{ display: 'flex', gap: '1rem' }}>
+      <Button variant="primary">Save</Button>
+      <Button variant="secondary">Cancel</Button>
+      <Button variant="tertiary">Reset</Button>
+    </div>
+  ),
+}
+```
+
+---
+
+## Documenting Composed Components
+
+### Card Composition Example
+
+```typescript
+// components/ActionCard.stories.tsx
+import type { Meta, StoryObj } from '@storybook/react'
+import { Card, Button } from '@fpkit/acss'
+
+const ActionCard = ({ title, children, actions }) => (
+  <Card>
+    <Card.Header>
+      <Card.Title>{title}</Card.Title>
+    </Card.Header>
+    <Card.Content>{children}</Card.Content>
+    <Card.Footer>
+      {actions.map((action, i) => (
+        <Button key={i} {...action} />
+      ))}
+    </Card.Footer>
+  </Card>
+)
+
+const meta = {
+  title: 'Compositions/ActionCard',
+  component: ActionCard,
+  tags: ['autodocs'],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+ActionCard is a composition of fpkit Card, Button, and sub-components.
+It provides a consistent layout for cards with title, content, and action buttons.
+
+**Composed from:**
+- Card (fpkit)
+- Card.Header (fpkit)
+- Card.Title (fpkit)
+- Card.Content (fpkit)
+- Card.Footer (fpkit)
+- Button (fpkit)
+        `,
+      },
+    },
+  },
+} satisfies Meta<typeof ActionCard>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {
+  args: {
+    title: 'Confirm Action',
+    children: 'Are you sure you want to proceed with this action?',
+    actions: [
+      { children: 'Cancel', variant: 'secondary' },
+      { children: 'Confirm', variant: 'primary' },
+    ],
+  },
+}
+
+export const SingleAction: Story = {
+  args: {
+    title: 'Notification',
+    children: 'Your changes have been saved successfully.',
+    actions: [
+      { children: 'OK', variant: 'primary' },
+    ],
+  },
+}
+```
+
+---
+
+## CSS Variable Customization Stories
+
+Show how users can customize your components:
+
+```typescript
+export const CustomStyling: Story = {
+  render: () => (
+    <div
+      style={{
+        '--btn-primary-bg': '#7c3aed',
+        '--btn-primary-color': 'white',
+        '--btn-radius': '2rem',
+        '--btn-padding-inline': '3rem',
+      } as React.CSSProperties}
+    >
+      <Button variant="primary">Custom Styled Button</Button>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: `
+Customize appearance using CSS variables:
+- \`--btn-primary-bg\`: Background color
+- \`--btn-primary-color\`: Text color
+- \`--btn-radius\`: Border radius
+- \`--btn-padding-inline\`: Horizontal padding
+
+See the [CSS Variables Guide](/docs/guides/css-variables.md) for all available variables.
+        `,
+      },
+    },
+  },
+}
+
+export const ThemeExample: Story = {
+  render: () => (
+    <>
+      <div
+        className="light-theme"
+        style={{
+          '--btn-bg': 'white',
+          '--btn-color': '#333',
+          padding: '2rem',
+          background: '#f9f9f9',
+        } as React.CSSProperties}
+      >
+        <Button>Light Theme Button</Button>
+      </div>
+
+      <div
+        className="dark-theme"
+        style={{
+          '--btn-bg': '#2d2d2d',
+          '--btn-color': '#f0f0f0',
+          padding: '2rem',
+          background: '#1a1a1a',
+          marginTop: '1rem',
+        } as React.CSSProperties}
+      >
+        <Button>Dark Theme Button</Button>
+      </div>
+    </>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Theme-based customization using scoped CSS variables.',
+      },
+    },
+  },
+}
+```
+
+---
+
+## Interactive Testing with Play Functions
+
+Play functions enable automated interaction testing in Storybook:
+
+```typescript
+import { within, userEvent, expect } from '@storybook/test'
+
+export const InteractiveTest: Story = {
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement)
+    const button = canvas.getByRole('button')
+
+    await step('Button is rendered', async () => {
+      expect(button).toBeInTheDocument()
+      expect(button).toHaveTextContent('Click me')
+    })
+
+    await step('Button responds to click', async () => {
+      await userEvent.click(button)
+      // Check for expected behavior
+    })
+
+    await step('Button is keyboard accessible', async () => {
+      await userEvent.tab()
+      expect(button).toHaveFocus()
+    })
+  },
+}
+```
+
+### Form Interaction Example
+
+```typescript
+export const FormInteraction: Story = {
+  render: () => {
+    const [value, setValue] = useState('')
+    const [submitted, setSubmitted] = useState(false)
+
+    return (
+      <div>
+        <Input
+          value={value}
+          onChange={(e) => setValue(e.target.value)}
+          placeholder="Enter email..."
+        />
+        <Button
+          onClick={() => setSubmitted(true)}
+          disabled={!value}
+        >
+          Submit
+        </Button>
+        {submitted && <Alert variant="success">Form submitted!</Alert>}
+      </div>
+    )
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement)
+    const input = canvas.getByPlaceholderText('Enter email...')
+    const button = canvas.getByRole('button')
+
+    await step('User types into input', async () => {
+      await userEvent.type(input, 'test@example.com')
+      expect(input).toHaveValue('test@example.com')
+    })
+
+    await step('Submit button becomes enabled', async () => {
+      expect(button).not.toHaveAttribute('aria-disabled', 'true')
+    })
+
+    await step('User submits form', async () => {
+      await userEvent.click(button)
+      expect(canvas.getByRole('alert')).toHaveTextContent('Form submitted!')
+    })
+  },
+}
+```
+
+---
+
+## ArgTypes Configuration
+
+Control how props appear in Storybook controls:
+
+```typescript
+const meta = {
+  component: CustomButton,
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['primary', 'secondary', 'tertiary'],
+      description: 'Visual style variant',
+      table: {
+        defaultValue: { summary: 'primary' },
+        type: { summary: 'string' },
+      },
+    },
+    size: {
+      control: 'radio',
+      options: ['small', 'medium', 'large'],
+      description: 'Button size',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the button',
+    },
+    loading: {
+      control: 'boolean',
+      description: 'Shows loading state',
+    },
+    onClick: {
+      action: 'clicked',
+      description: 'Click event handler',
+    },
+    // Hide internal props
+    ref: { table: { disable: true } },
+    as: { table: { disable: true } },
+  },
+} satisfies Meta<typeof CustomButton>
+```
+
+---
+
+## Documentation Parameters
+
+### Component Description
+
+```typescript
+const meta = {
+  title: 'Components/StatusButton',
+  component: StatusButton,
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# StatusButton
+
+A button component with an integrated status badge.
+
+## Features
+- Built on fpkit Button
+- Includes Badge for status indication
+- Fully accessible
+- Customizable via CSS variables
+
+## Usage
+\`\`\`tsx
+<StatusButton status="active" onClick={handleClick}>
+  Server Status
+</StatusButton>
+\`\`\`
+
+## Composed Components
+- **Button** - Base interactive element
+- **Badge** - Status indicator
+
+See [Composition Guide](/docs/guides/composition.md) for composition patterns.
+        `,
+      },
+    },
+  },
+} satisfies Meta<typeof StatusButton>
+```
+
+### Story Description
+
+```typescript
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Primary variant for high-emphasis actions.',
+      },
+    },
+  },
+}
+```
+
+---
+
+## Organizing Stories
+
+### Title Hierarchy
+
+```typescript
+// Group by category
+title: 'Components/Buttons/CustomButton'
+title: 'Components/Forms/SearchInput'
+title: 'Compositions/Cards/ActionCard'
+
+// Or by feature
+title: 'Features/Authentication/LoginForm'
+title: 'Features/Dashboard/StatsCard'
+
+// Or by page
+title: 'Pages/Home/HeroSection'
+title: 'Pages/Settings/ProfileCard'
+```
+
+### Tags
+
+```typescript
+tags: ['autodocs']      // Auto-generate documentation
+tags: ['stable']        // Production-ready
+tags: ['beta']          // Testing phase
+tags: ['composition']   // fpkit composition
+```
+
+---
+
+## Accessibility Testing in Storybook
+
+### Basic Accessibility Test
+
+```typescript
+export const AccessibilityTest: Story = {
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement)
+    const button = canvas.getByRole('button')
+
+    await step('Has accessible name', async () => {
+      expect(button).toHaveAccessibleName()
+    })
+
+    await step('Is keyboard navigable', async () => {
+      await userEvent.tab()
+      expect(button).toHaveFocus()
+    })
+
+    await step('Activates with Enter key', async () => {
+      await userEvent.keyboard('{Enter}')
+    })
+
+    await step('Activates with Space key', async () => {
+      button.focus()
+      await userEvent.keyboard(' ')
+    })
+  },
+}
+```
+
+### ARIA Attributes Test
+
+```typescript
+export const AriaAttributesTest: Story = {
+  args: {
+    'aria-label': 'Close dialog',
+    'aria-describedby': 'hint',
+  },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement)
+    const button = canvas.getByRole('button')
+
+    await step('Has ARIA label', async () => {
+      expect(button).toHaveAttribute('aria-label', 'Close dialog')
+    })
+
+    await step('Has ARIA description', async () => {
+      expect(button).toHaveAttribute('aria-describedby', 'hint')
+    })
+  },
+}
+```
+
+---
+
+## State Comparison Stories
+
+Show different states side-by-side:
+
+```typescript
+export const AllStates: Story = {
+  render: () => (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem' }}>
+      <div>
+        <h3>Default</h3>
+        <Button>Default Button</Button>
+      </div>
+
+      <div>
+        <h3>Hover</h3>
+        <Button className="hover">Hover State</Button>
+      </div>
+
+      <div>
+        <h3>Focus</h3>
+        <Button className="focus">Focus State</Button>
+      </div>
+
+      <div>
+        <h3>Disabled</h3>
+        <Button disabled>Disabled Button</Button>
+      </div>
+
+      <div>
+        <h3>Loading</h3>
+        <Button disabled>Loading...</Button>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Comparison of all button states',
+      },
+    },
+  },
+}
+```
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+- **Document compositions** - Show which fpkit components you're using
+- **Include play functions** - Test interactions automatically
+- **Show CSS customization** - Demonstrate variable usage
+- **Test accessibility** - Keyboard navigation, ARIA attributes
+- **Use descriptive titles** - Clear hierarchy and organization
+- **Add component descriptions** - Explain purpose and usage
+- **Show state variants** - Default, hover, disabled, loading, error
+- **Document props** - Use argTypes for prop documentation
+- **Include usage examples** - Code snippets in descriptions
+
+### ❌ Don't
+
+- **Don't duplicate fpkit stories** - Focus on your custom logic
+- **Don't overcomplicate** - Keep stories simple and focused
+- **Don't skip accessibility** - Always test keyboard and screen readers
+- **Don't forget CSS imports** - Import fpkit styles in preview
+- **Don't use vague titles** - Be specific about what's being demonstrated
+
+---
+
+## Running Storybook
+
+```bash
+# Start Storybook dev server
+npm run storybook
+
+# Build Storybook static site
+npm run build-storybook
+
+# Serve built Storybook
+npx http-server storybook-static
+```
+
+---
+
+## Example: Complete Story File
+
+```typescript
+import type { Meta, StoryObj } from '@storybook/react'
+import { within, userEvent, expect, fn } from '@storybook/test'
+import { Button, Badge } from '@fpkit/acss'
+
+// Your composed component
+const NotificationButton = ({ count, onClick }) => (
+  <Button onClick={onClick} aria-label={`Notifications (${count} unread)`}>
+    <span aria-hidden="true">🔔</span>
+    {count > 0 && (
+      <Badge aria-hidden="true">{count}</Badge>
+    )}
+  </Button>
+)
+
+const meta = {
+  title: 'Compositions/NotificationButton',
+  component: NotificationButton,
+  tags: ['autodocs', 'composition'],
+  args: {
+    count: 3,
+    onClick: fn(),
+  },
+  argTypes: {
+    count: {
+      control: 'number',
+      description: 'Number of unread notifications',
+    },
+    onClick: {
+      action: 'clicked',
+      description: 'Click handler',
+    },
+  },
+  parameters: {
+    docs: {
+      description: {
+        component: `
+# NotificationButton
+
+A button displaying notification count with a badge.
+
+**Composed from:**
+- Button (fpkit)
+- Badge (fpkit)
+
+**Accessibility:**
+- Uses \`aria-label\` to announce count to screen readers
+- Visual elements hidden from screen readers with \`aria-hidden\`
+        `,
+      },
+    },
+  },
+} satisfies Meta<typeof NotificationButton>
+
+export default meta
+type Story = StoryObj<typeof meta>
+
+export const Default: Story = {}
+
+export const NoNotifications: Story = {
+  args: {
+    count: 0,
+  },
+}
+
+export const ManyNotifications: Story = {
+  args: {
+    count: 99,
+  },
+}
+
+export const CustomStyling: Story = {
+  render: (args) => (
+    <div
+      style={{
+        '--btn-padding-inline': '1.5rem',
+        '--badge-bg': '#ef4444',
+      } as React.CSSProperties}
+    >
+      <NotificationButton {...args} />
+    </div>
+  ),
+  args: {
+    count: 5,
+  },
+}
+
+export const InteractiveTest: Story = {
+  args: {
+    count: 3,
+  },
+  play: async ({ canvasElement, step, args }) => {
+    const canvas = within(canvasElement)
+    const button = canvas.getByRole('button')
+
+    await step('Has accessible label with count', async () => {
+      expect(button).toHaveAttribute('aria-label', 'Notifications (3 unread)')
+    })
+
+    await step('Shows badge with count', async () => {
+      expect(canvas.getByText('3')).toBeInTheDocument()
+    })
+
+    await step('Calls onClick when clicked', async () => {
+      await userEvent.click(button)
+      expect(args.onClick).toHaveBeenCalledTimes(1)
+    })
+
+    await step('Is keyboard accessible', async () => {
+      await userEvent.tab()
+      expect(button).toHaveFocus()
+
+      await userEvent.keyboard('{Enter}')
+      expect(args.onClick).toHaveBeenCalledTimes(2)
+    })
+  },
+}
+```
+
+---
+
+## Additional Resources
+
+- **[Storybook Documentation](https://storybook.js.org/docs)** - Official Storybook docs
+- **[Testing with Storybook](https://storybook.js.org/docs/writing-tests)** - Play functions and interaction testing
+- **[Storybook Addons](https://storybook.js.org/addons)** - Extend functionality
+- **[Component Story Format](https://storybook.js.org/docs/api/csf)** - CSF 3.0 specification
+
+---
+
+## Related Guides
+
+- **[Composition Guide](./composition.md)** - Component composition patterns
+- **[Testing Guide](./testing.md)** - Testing composed components
+- **[Accessibility Guide](./accessibility.md)** - Accessibility testing patterns
+- **[CSS Variables Guide](./css-variables.md)** - Styling customization
+
+---
+
+**Remember**: Storybook is for documenting **your components and compositions**. fpkit components already have stories in the fpkit Storybook - focus on showcasing how you use and compose them in your application.