@tribepad/themis 1.0.0

package/src/elements/ButtonGroup/ButtonGroup.stories.tsx

@@ -0,0 +1,658 @@
+/**
+ * ButtonGroup Component Stories
+ * Storybook stories demonstrating all ButtonGroup variants, orientations, and features
+ *
+ * @see buttongroup-prd.md for requirements
+ * @see spec.md FR-045 (Storybook stories requirement)
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import {
+  Bold,
+  Italic,
+  Underline,
+  AlignLeft,
+  AlignCenter,
+  AlignRight,
+  AlignJustify,
+  Undo,
+  Redo,
+  Copy,
+  Scissors,
+  Clipboard,
+  Grid,
+  List,
+  Table,
+  Settings,
+  User,
+  LogOut,
+} from 'lucide-react';
+import { ButtonGroup, ButtonGroupSeparator } from './ButtonGroup';
+import { Button } from '../Button/Button';
+
+const meta = {
+  title: 'Elements/ButtonGroup',
+  component: ButtonGroup,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Groups related buttons with connected styling, keyboard navigation (arrow keys), and WCAG 2.2 AAA compliance. Built on React Aria Toolbar for accessible toolbar patterns.',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    orientation: {
+      control: 'radio',
+      options: ['horizontal', 'vertical'],
+      description: 'Layout direction of the button group',
+      table: {
+        defaultValue: { summary: 'horizontal' },
+      },
+    },
+    variant: {
+      control: 'select',
+      options: ['default', 'destructive', 'outline', 'secondary', 'ghost'],
+      description: 'Default variant for all buttons (can be overridden per-button)',
+    },
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg', 'icon'],
+      description: 'Default size for all buttons (can be overridden per-button)',
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disable all buttons in the group',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: 'Accessible label for the toolbar (required for accessibility)',
+    },
+  },
+} satisfies Meta<typeof ButtonGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Basic Examples
+// =============================================================================
+
+export const Default: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Left</Button>
+      <Button variant="outline">Center</Button>
+      <Button variant="outline">Right</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Text alignment',
+  },
+};
+
+export const TwoButtons: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Previous</Button>
+      <Button variant="outline">Next</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Pagination',
+  },
+};
+
+export const SingleButton: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Only Button</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Single action',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Single button in a group has no border radius modifications.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Orientation
+// =============================================================================
+
+export const Horizontal: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">First</Button>
+      <Button variant="outline">Second</Button>
+      <Button variant="outline">Third</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    orientation: 'horizontal',
+    'aria-label': 'Horizontal group',
+  },
+};
+
+export const Vertical: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">View Profile</Button>
+      <Button variant="outline">Settings</Button>
+      <Button variant="outline">Sign Out</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    orientation: 'vertical',
+    'aria-label': 'Account actions',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Vertical orientation for stacked layouts. Use Up/Down arrow keys to navigate.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Variants (Inherited from Group)
+// =============================================================================
+
+export const OutlineVariant: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button>Bold</Button>
+      <Button>Italic</Button>
+      <Button>Underline</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    variant: 'outline',
+    'aria-label': 'Text formatting',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Group-level variant applies to all child buttons.',
+      },
+    },
+  },
+};
+
+export const SecondaryVariant: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button>Option A</Button>
+      <Button>Option B</Button>
+      <Button>Option C</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    variant: 'secondary',
+    'aria-label': 'Options',
+  },
+};
+
+export const GhostVariant: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button><Undo /></Button>
+      <Button><Redo /></Button>
+    </ButtonGroup>
+  ),
+  args: {
+    variant: 'ghost',
+    'aria-label': 'Undo/Redo',
+  },
+};
+
+export const MixedVariants: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button>Save</Button>
+      <Button variant="outline">Cancel</Button>
+      <Button variant="destructive">Delete</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Actions',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Individual buttons can override the group variant. Here, Save uses default, Cancel uses outline, Delete uses destructive.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Sizes
+// =============================================================================
+
+export const SmallSize: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Small</Button>
+      <Button variant="outline">Buttons</Button>
+      <Button variant="outline">Here</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    size: 'sm',
+    'aria-label': 'Small buttons',
+  },
+};
+
+export const LargeSize: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Large</Button>
+      <Button variant="outline">Buttons</Button>
+      <Button variant="outline">Here</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    size: 'lg',
+    'aria-label': 'Large buttons',
+  },
+};
+
+export const IconSize: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline" aria-label="Bold"><Bold /></Button>
+      <Button variant="outline" aria-label="Italic"><Italic /></Button>
+      <Button variant="outline" aria-label="Underline"><Underline /></Button>
+    </ButtonGroup>
+  ),
+  args: {
+    size: 'icon',
+    'aria-label': 'Text formatting',
+  },
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Small (sm)</span>
+        <ButtonGroup size="sm" aria-label="Small buttons">
+          <Button variant="outline">A</Button>
+          <Button variant="outline">B</Button>
+          <Button variant="outline">C</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Default</span>
+        <ButtonGroup aria-label="Default buttons">
+          <Button variant="outline">A</Button>
+          <Button variant="outline">B</Button>
+          <Button variant="outline">C</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Large (lg)</span>
+        <ButtonGroup size="lg" aria-label="Large buttons">
+          <Button variant="outline">A</Button>
+          <Button variant="outline">B</Button>
+          <Button variant="outline">C</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Icon</span>
+        <ButtonGroup size="icon" aria-label="Icon buttons">
+          <Button variant="outline" aria-label="Grid"><Grid /></Button>
+          <Button variant="outline" aria-label="List"><List /></Button>
+          <Button variant="outline" aria-label="Table"><Table /></Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All size variants in one view.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Separators
+// =============================================================================
+
+export const WithSeparators: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="ghost" aria-label="Undo"><Undo /></Button>
+      <Button variant="ghost" aria-label="Redo"><Redo /></Button>
+      <ButtonGroupSeparator />
+      <Button variant="ghost" aria-label="Cut"><Scissors /></Button>
+      <Button variant="ghost" aria-label="Copy"><Copy /></Button>
+      <Button variant="ghost" aria-label="Paste"><Clipboard /></Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Editor actions',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Separators visually divide related button groups. They are purely decorative (aria-hidden) and excluded from position calculations.',
+      },
+    },
+  },
+};
+
+export const MultipleSeparators: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline" aria-label="Bold"><Bold /></Button>
+      <Button variant="outline" aria-label="Italic"><Italic /></Button>
+      <Button variant="outline" aria-label="Underline"><Underline /></Button>
+      <ButtonGroupSeparator />
+      <Button variant="outline" aria-label="Align left"><AlignLeft /></Button>
+      <Button variant="outline" aria-label="Align center"><AlignCenter /></Button>
+      <Button variant="outline" aria-label="Align right"><AlignRight /></Button>
+      <Button variant="outline" aria-label="Justify"><AlignJustify /></Button>
+      <ButtonGroupSeparator />
+      <Button variant="outline" aria-label="Undo"><Undo /></Button>
+      <Button variant="outline" aria-label="Redo"><Redo /></Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Text editor toolbar',
+  },
+};
+
+export const VerticalWithSeparator: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline"><User className="mr-2" /> Profile</Button>
+      <Button variant="outline"><Settings className="mr-2" /> Settings</Button>
+      <ButtonGroupSeparator />
+      <Button variant="outline"><LogOut className="mr-2" /> Sign Out</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    orientation: 'vertical',
+    'aria-label': 'User menu',
+  },
+};
+
+// =============================================================================
+// Disabled States
+// =============================================================================
+
+export const Disabled: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Can&apos;t</Button>
+      <Button variant="outline">Click</Button>
+      <Button variant="outline">These</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    isDisabled: true,
+    'aria-label': 'Disabled group',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'All buttons are disabled when isDisabled is set on the group.',
+      },
+    },
+  },
+};
+
+export const MixedDisabledStates: Story = {
+  render: (args) => (
+    <ButtonGroup {...args}>
+      <Button variant="outline">Cut</Button>
+      <Button variant="outline">Copy</Button>
+      <Button variant="outline" isDisabled>Paste (Disabled)</Button>
+    </ButtonGroup>
+  ),
+  args: {
+    'aria-label': 'Clipboard actions',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Individual buttons can be disabled. Disabled buttons are skipped during keyboard navigation.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Real-World Examples
+// =============================================================================
+
+export const TextFormattingToolbar: Story = {
+  render: () => (
+    <div className="rounded-lg border border-[var(--border)] p-4">
+      <div className="mb-4">
+        <ButtonGroup aria-label="Text formatting" size="icon">
+          <Button variant="outline" aria-label="Bold"><Bold /></Button>
+          <Button variant="outline" aria-label="Italic"><Italic /></Button>
+          <Button variant="outline" aria-label="Underline"><Underline /></Button>
+        </ButtonGroup>
+      </div>
+      <textarea
+        className="w-full h-24 rounded-md border border-[var(--input-border)] p-2 text-sm"
+        placeholder="Type some text here..."
+        defaultValue="Select text and click formatting buttons..."
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Text formatting toolbar like you would find in a rich text editor.',
+      },
+    },
+  },
+};
+
+export const ViewSwitcher: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4">
+      <ButtonGroup aria-label="View mode" size="icon">
+        <Button variant="secondary" aria-label="Grid view"><Grid /></Button>
+        <Button variant="outline" aria-label="List view"><List /></Button>
+        <Button variant="outline" aria-label="Table view"><Table /></Button>
+      </ButtonGroup>
+      <p className="text-sm text-[var(--muted-foreground)]">
+        Grid view selected (shows as secondary variant)
+      </p>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'View switcher pattern. The active view uses a different variant to indicate selection.',
+      },
+    },
+  },
+};
+
+export const PaginationControls: Story = {
+  render: () => (
+    <div className="flex items-center gap-4">
+      <span className="text-sm text-[var(--muted-foreground)]">Page 3 of 10</span>
+      <ButtonGroup aria-label="Pagination" variant="outline">
+        <Button>&laquo; First</Button>
+        <Button>&lsaquo; Prev</Button>
+        <Button>Next &rsaquo;</Button>
+        <Button>Last &raquo;</Button>
+      </ButtonGroup>
+    </div>
+  ),
+};
+
+export const AlignmentControls: Story = {
+  render: () => (
+    <ButtonGroup aria-label="Text alignment" variant="outline" size="icon">
+      <Button aria-label="Align left"><AlignLeft /></Button>
+      <Button aria-label="Align center"><AlignCenter /></Button>
+      <Button aria-label="Align right"><AlignRight /></Button>
+      <Button aria-label="Justify"><AlignJustify /></Button>
+    </ButtonGroup>
+  ),
+};
+
+export const AccountActions: Story = {
+  render: () => (
+    <div className="w-64">
+      <ButtonGroup orientation="vertical" variant="ghost" aria-label="Account">
+        <Button className="justify-start"><User className="mr-2" /> View Profile</Button>
+        <Button className="justify-start"><Settings className="mr-2" /> Account Settings</Button>
+        <ButtonGroupSeparator />
+        <Button className="justify-start text-[var(--destructive-background)]">
+          <LogOut className="mr-2" /> Sign Out
+        </Button>
+      </ButtonGroup>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Vertical button group for account dropdown menus.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Accessibility
+// =============================================================================
+
+export const KeyboardNavigation: Story = {
+  render: (args) => (
+    <div className="flex flex-col gap-4">
+      <ButtonGroup {...args}>
+        <Button variant="outline">First (Tab here)</Button>
+        <Button variant="outline">Second (ArrowRight)</Button>
+        <Button variant="outline">Third (ArrowRight)</Button>
+      </ButtonGroup>
+      <div className="text-sm text-[var(--muted-foreground)]">
+        <p><strong>Keyboard shortcuts:</strong></p>
+        <ul className="list-disc pl-4 mt-2">
+          <li><kbd>Tab</kbd> - Enter/exit the button group</li>
+          <li><kbd>Arrow Right/Left</kbd> - Navigate between buttons</li>
+          <li><kbd>Enter</kbd> or <kbd>Space</kbd> - Activate focused button</li>
+        </ul>
+      </div>
+    </div>
+  ),
+  args: {
+    'aria-label': 'Keyboard navigation demo',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use Tab to focus the group, then arrow keys to navigate between buttons. The group acts as a single tab stop (roving tabindex pattern).',
+      },
+    },
+  },
+};
+
+export const VerticalKeyboardNavigation: Story = {
+  render: (args) => (
+    <div className="flex gap-8">
+      <ButtonGroup {...args}>
+        <Button variant="outline">First (Tab here)</Button>
+        <Button variant="outline">Second (ArrowDown)</Button>
+        <Button variant="outline">Third (ArrowDown)</Button>
+      </ButtonGroup>
+      <div className="text-sm text-[var(--muted-foreground)]">
+        <p><strong>Vertical shortcuts:</strong></p>
+        <ul className="list-disc pl-4 mt-2">
+          <li><kbd>Arrow Down</kbd> - Next button</li>
+          <li><kbd>Arrow Up</kbd> - Previous button</li>
+        </ul>
+      </div>
+    </div>
+  ),
+  args: {
+    orientation: 'vertical',
+    'aria-label': 'Vertical keyboard navigation demo',
+  },
+};
+
+// =============================================================================
+// All Variants Grid
+// =============================================================================
+
+export const AllVariants: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Default</span>
+        <ButtonGroup aria-label="Default variant">
+          <Button>One</Button>
+          <Button>Two</Button>
+          <Button>Three</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Outline</span>
+        <ButtonGroup variant="outline" aria-label="Outline variant">
+          <Button>One</Button>
+          <Button>Two</Button>
+          <Button>Three</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Secondary</span>
+        <ButtonGroup variant="secondary" aria-label="Secondary variant">
+          <Button>One</Button>
+          <Button>Two</Button>
+          <Button>Three</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Ghost</span>
+        <ButtonGroup variant="ghost" aria-label="Ghost variant">
+          <Button>One</Button>
+          <Button>Two</Button>
+          <Button>Three</Button>
+        </ButtonGroup>
+      </div>
+      <div className="flex flex-col gap-2">
+        <span className="text-sm text-[var(--muted-foreground)]">Destructive</span>
+        <ButtonGroup variant="destructive" aria-label="Destructive variant">
+          <Button>One</Button>
+          <Button>Two</Button>
+          <Button>Three</Button>
+        </ButtonGroup>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All variant types demonstrated with 3-button groups.',
+      },
+    },
+  },
+};