@tribepad/themis 1.0.0

package/src/elements/Breadcrumbs/Breadcrumbs.stories.tsx

@@ -0,0 +1,623 @@
+/**
+ * Breadcrumbs Component Stories
+ * Storybook stories for Breadcrumbs component demonstrating all variants and states
+ *
+ * @see breadcrumbs-prd.md FR-001 to FR-011 (Breadcrumbs Component Requirements)
+ */
+
+import type { ReactNode } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { Home, FolderOpen, FileText, Settings, Users, Package } from 'lucide-react';
+import { Breadcrumbs } from './Breadcrumbs';
+import type { BreadcrumbItemData } from './Breadcrumbs.types';
+
+const meta = {
+  title: 'Elements/Breadcrumbs',
+  component: Breadcrumbs,
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Accessible breadcrumb navigation with array-based API and ellipsis collapse. WCAG 2.2 AAA compliant with 7:1 contrast ratio and 44x44px touch targets.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    items: {
+      description: 'Array of breadcrumb items',
+      table: {
+        type: { summary: 'BreadcrumbItemData[]' },
+      },
+    },
+    separator: {
+      control: 'select',
+      options: ['chevron', 'slash'],
+      description: 'Separator between breadcrumb items',
+      table: {
+        defaultValue: { summary: 'chevron' },
+      },
+    },
+    maxItems: {
+      control: { type: 'number', min: 1, max: 10 },
+      description: 'Maximum items before collapsing with ellipsis',
+      table: {
+        defaultValue: { summary: '4' },
+      },
+    },
+    itemsBeforeCollapse: {
+      control: { type: 'number', min: 0, max: 5 },
+      description: 'Items to show before ellipsis',
+      table: {
+        defaultValue: { summary: '1' },
+      },
+    },
+    itemsAfterCollapse: {
+      control: { type: 'number', min: 1, max: 5 },
+      description: 'Items to show after ellipsis',
+      table: {
+        defaultValue: { summary: '2' },
+      },
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disable all breadcrumb interactions',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: 'Accessible label for the navigation landmark',
+      table: {
+        defaultValue: { summary: 'Breadcrumb' },
+      },
+    },
+  },
+} satisfies Meta<typeof Breadcrumbs>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Basic items for stories
+const basicItems: BreadcrumbItemData[] = [
+  { id: 'home', label: 'Home', href: '/' },
+  { id: 'products', label: 'Products', href: '/products' },
+  { id: 'category', label: 'Electronics', href: '/products/electronics' },
+  { id: 'current', label: 'Laptops' },
+];
+
+const itemsWithIcons: BreadcrumbItemData[] = [
+  { id: 'home', label: 'Home', href: '/', icon: <Home className="h-4 w-4" /> },
+  {
+    id: 'settings',
+    label: 'Settings',
+    href: '/settings',
+    icon: <Settings className="h-4 w-4" />,
+  },
+  { id: 'current', label: 'Profile', icon: <Users className="h-4 w-4" /> },
+];
+
+const longPathItems: BreadcrumbItemData[] = [
+  { id: 'home', label: 'Home', href: '/' },
+  { id: 'docs', label: 'Documentation', href: '/docs' },
+  { id: 'guides', label: 'Guides', href: '/docs/guides' },
+  { id: 'getting-started', label: 'Getting Started', href: '/docs/guides/getting-started' },
+  { id: 'installation', label: 'Installation', href: '/docs/guides/getting-started/installation' },
+  { id: 'current', label: 'Configuration' },
+];
+
+// Default story
+export const Default: Story = {
+  args: {
+    items: basicItems,
+  },
+};
+
+// Single item
+export const SingleItem: Story = {
+  args: {
+    items: [{ id: 'home', label: 'Home' }],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Single breadcrumb item showing only the current page.',
+      },
+    },
+  },
+};
+
+// Two items
+export const TwoItems: Story = {
+  args: {
+    items: [
+      { id: 'home', label: 'Home', href: '/' },
+      { id: 'current', label: 'Dashboard' },
+    ],
+  },
+};
+
+// With icons
+export const WithIcons: Story = {
+  args: {
+    items: itemsWithIcons,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Breadcrumb items can include icons for visual identification.',
+      },
+    },
+  },
+};
+
+// Separator variants
+export const SlashSeparator: Story = {
+  args: {
+    items: basicItems,
+    separator: 'slash',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Using slash separator instead of default chevron.',
+      },
+    },
+  },
+};
+
+export const CustomSeparator: Story = {
+  args: {
+    items: basicItems,
+    separator: <span className="text-[var(--muted-foreground)]">{'>'}</span>,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom ReactNode can be used as separator.',
+      },
+    },
+  },
+};
+
+// Collapsed state
+export const Collapsed: Story = {
+  args: {
+    items: longPathItems,
+    maxItems: 4,
+    itemsBeforeCollapse: 1,
+    itemsAfterCollapse: 2,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'When items exceed maxItems, middle items collapse into an ellipsis dropdown. Click the ellipsis to see collapsed items.',
+      },
+    },
+  },
+};
+
+export const CollapsedMoreBefore: Story = {
+  args: {
+    items: longPathItems,
+    maxItems: 4,
+    itemsBeforeCollapse: 2,
+    itemsAfterCollapse: 1,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom collapse configuration with 2 items before and 1 after the ellipsis.',
+      },
+    },
+  },
+};
+
+// Disabled state
+export const Disabled: Story = {
+  args: {
+    items: basicItems,
+    isDisabled: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Disabled breadcrumbs prevent all navigation interactions.',
+      },
+    },
+  },
+};
+
+export const IndividualDisabled: Story = {
+  args: {
+    items: [
+      { id: 'home', label: 'Home', href: '/' },
+      { id: 'products', label: 'Products', href: '/products', isDisabled: true },
+      { id: 'current', label: 'Electronics' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Individual breadcrumb items can be disabled.',
+      },
+    },
+  },
+};
+
+// Theme stories
+export const LightTheme: Story = {
+  args: {
+    items: basicItems,
+  },
+  parameters: {
+    backgrounds: { default: 'light' },
+  },
+};
+
+export const DarkTheme: Story = {
+  args: {
+    items: basicItems,
+  },
+  parameters: {
+    backgrounds: { default: 'dark' },
+    docs: {
+      description: {
+        story: 'Breadcrumbs adapt to dark theme via semantic tokens.',
+      },
+    },
+  },
+};
+
+export const HighContrast: Story = {
+  args: {
+    items: basicItems,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'High contrast mode with 7:1 contrast ratio for WCAG AAA compliance.',
+      },
+    },
+  },
+};
+
+export const ColorblindTheme: Story = {
+  args: {
+    items: basicItems,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Colorblind-friendly theme (deuteranopia, protanopia, tritanopia support).',
+      },
+    },
+  },
+};
+
+// Accessibility stories
+export const FocusVisible: Story = {
+  args: {
+    items: basicItems,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Press Tab to navigate through breadcrumb links. Focus ring is clearly visible for keyboard users.',
+      },
+    },
+  },
+};
+
+export const TouchTarget: Story = {
+  args: {
+    items: basicItems,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All breadcrumb links have a minimum 44x44px touch target, exceeding WCAG 2.2 AAA requirements.',
+      },
+    },
+  },
+};
+
+// Real-world examples
+export const FileExplorer: Story = {
+  args: {
+    items: [
+      { id: 'root', label: 'Documents', href: '/documents', icon: <FolderOpen className="h-4 w-4" /> },
+      {
+        id: 'projects',
+        label: 'Projects',
+        href: '/documents/projects',
+        icon: <FolderOpen className="h-4 w-4" />,
+      },
+      {
+        id: 'design',
+        label: 'Design System',
+        href: '/documents/projects/design-system',
+        icon: <FolderOpen className="h-4 w-4" />,
+      },
+      { id: 'current', label: 'components.md', icon: <FileText className="h-4 w-4" /> },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'File explorer style breadcrumbs with folder and file icons.',
+      },
+    },
+  },
+};
+
+export const ECommerce: Story = {
+  args: {
+    items: [
+      { id: 'home', label: 'Shop', href: '/' },
+      { id: 'category', label: 'Clothing', href: '/clothing' },
+      { id: 'subcategory', label: "Men's", href: '/clothing/mens' },
+      { id: 'type', label: 'Shirts', href: '/clothing/mens/shirts' },
+      { id: 'current', label: 'Blue Oxford Shirt' },
+    ],
+    maxItems: 4,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'E-commerce product navigation with automatic collapse.',
+      },
+    },
+  },
+};
+
+export const AdminDashboard: Story = {
+  args: {
+    items: [
+      { id: 'admin', label: 'Admin', href: '/admin', icon: <Settings className="h-4 w-4" /> },
+      { id: 'users', label: 'Users', href: '/admin/users', icon: <Users className="h-4 w-4" /> },
+      { id: 'current', label: 'John Doe' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Admin dashboard navigation with icons.',
+      },
+    },
+  },
+};
+
+export const Documentation: Story = {
+  args: {
+    items: longPathItems,
+    separator: 'slash',
+    maxItems: 5,
+    itemsBeforeCollapse: 2,
+    itemsAfterCollapse: 2,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Documentation site navigation with slash separators and collapse.',
+      },
+    },
+  },
+};
+
+// Edge cases
+export const LongLabels: Story = {
+  args: {
+    items: [
+      { id: 'home', label: 'Home', href: '/' },
+      {
+        id: 'category',
+        label: 'Very Long Category Name That Might Wrap',
+        href: '/category',
+      },
+      { id: 'current', label: 'Another Extremely Long Page Title' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Breadcrumbs handle long labels with proper wrapping.',
+      },
+    },
+  },
+};
+
+export const ManyItems: Story = {
+  args: {
+    items: [
+      { id: '1', label: 'Level 1', href: '/1' },
+      { id: '2', label: 'Level 2', href: '/1/2' },
+      { id: '3', label: 'Level 3', href: '/1/2/3' },
+      { id: '4', label: 'Level 4', href: '/1/2/3/4' },
+      { id: '5', label: 'Level 5', href: '/1/2/3/4/5' },
+      { id: '6', label: 'Level 6', href: '/1/2/3/4/5/6' },
+      { id: '7', label: 'Level 7', href: '/1/2/3/4/5/6/7' },
+      { id: 'current', label: 'Current Page' },
+    ],
+    maxItems: 4,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Many items collapse into ellipsis dropdown when exceeding maxItems.',
+      },
+    },
+  },
+};
+
+export const NoHrefItems: Story = {
+  args: {
+    items: [
+      { id: 'root', label: 'Root' },
+      { id: 'parent', label: 'Parent Category' },
+      { id: 'current', label: 'Current Page' },
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Items without href are rendered as non-interactive spans (not as links).',
+      },
+    },
+  },
+};
+
+// All separators grid
+export const AllSeparators: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm font-medium">Chevron (default)</p>
+        <Breadcrumbs items={basicItems} separator="chevron" />
+      </div>
+      <div>
+        <p className="mb-2 text-sm font-medium">Slash</p>
+        <Breadcrumbs items={basicItems} separator="slash" />
+      </div>
+      <div>
+        <p className="mb-2 text-sm font-medium">Custom (arrow)</p>
+        <Breadcrumbs
+          items={basicItems}
+          separator={<span className="mx-2 text-[var(--muted-foreground)]">→</span>}
+        />
+      </div>
+      <div>
+        <p className="mb-2 text-sm font-medium">Custom (pipe)</p>
+        <Breadcrumbs
+          items={basicItems}
+          separator={<span className="mx-2 text-[var(--muted-foreground)]">|</span>}
+        />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All available separator options: chevron, slash, and custom ReactNode.',
+      },
+    },
+  },
+};
+
+// Collapse configurations
+export const CollapseConfigurations: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div>
+        <p className="mb-2 text-sm font-medium">Default (1 before, 2 after)</p>
+        <Breadcrumbs
+          items={longPathItems}
+          maxItems={4}
+          itemsBeforeCollapse={1}
+          itemsAfterCollapse={2}
+        />
+      </div>
+      <div>
+        <p className="mb-2 text-sm font-medium">2 before, 1 after</p>
+        <Breadcrumbs
+          items={longPathItems}
+          maxItems={4}
+          itemsBeforeCollapse={2}
+          itemsAfterCollapse={1}
+        />
+      </div>
+      <div>
+        <p className="mb-2 text-sm font-medium">0 before, 3 after</p>
+        <Breadcrumbs
+          items={longPathItems}
+          maxItems={4}
+          itemsBeforeCollapse={0}
+          itemsAfterCollapse={3}
+        />
+      </div>
+      <div>
+        <p className="mb-2 text-sm font-medium">No collapse (maxItems: 10)</p>
+        <Breadcrumbs items={longPathItems} maxItems={10} />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Different collapse configurations showing how itemsBeforeCollapse and itemsAfterCollapse affect layout.',
+      },
+    },
+  },
+};
+
+// Polymorphic link example
+export const WithNextJsLink: Story = {
+  render: () => {
+    // Simulated Next.js Link behavior
+    const MockNextLink = ({
+      href,
+      className,
+      children,
+    }: {
+      href: string;
+      className?: string;
+      children: ReactNode;
+    }) => (
+      <a
+        href={href}
+        className={className}
+        onClick={(e) => {
+          e.preventDefault();
+          console.log(`Next.js navigation to: ${href}`);
+        }}
+      >
+        {children}
+      </a>
+    );
+
+    return (
+      <Breadcrumbs
+        items={basicItems}
+        linkComponent={MockNextLink}
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use linkComponent prop to integrate with Next.js Link, React Router Link, or any custom link component.',
+      },
+    },
+  },
+};
+
+// Interactive playground
+export const Playground: Story = {
+  args: {
+    items: [
+      { id: 'home', label: 'Home', href: '/', icon: <Home className="h-4 w-4" /> },
+      { id: 'products', label: 'Products', href: '/products', icon: <Package className="h-4 w-4" /> },
+      { id: 'category', label: 'Electronics', href: '/products/electronics' },
+      { id: 'subcategory', label: 'Computers', href: '/products/electronics/computers' },
+      { id: 'current', label: 'Laptops' },
+    ],
+    separator: 'chevron',
+    maxItems: 4,
+    itemsBeforeCollapse: 1,
+    itemsAfterCollapse: 2,
+    isDisabled: false,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive playground to test all Breadcrumbs props.',
+      },
+    },
+  },
+};