@tribepad/themis 1.0.0

package/src/elements/Panel/Panel.stories.tsx

@@ -0,0 +1,769 @@
+/**
+ * Panel Component - Storybook Stories
+ *
+ * Interactive examples and documentation for the Panel component
+ *
+ * IMPORTANT: The Panel component must be a SIBLING of <main>, not a child.
+ * This allows it to participate in the CSS Grid layout and appear beside
+ * the main content, not inside it.
+ *
+ * @see panel-prd.md DOC-002 (Storybook Stories Requirements)
+ * @see ADR 0007 (Accessibility Decisions)
+ * @see Storybook (when running)
+ */
+
+import { useState, type ReactElement } from 'react';
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { Panel } from './Panel';
+import { Button } from '../Button';
+
+const meta = {
+  title: 'Elements/Panel',
+  component: Panel,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component:
+          'Accessible non-modal sidebar panel using the disclosure pattern with a complementary region for WCAG 2.2 AAA compliance. Designed for master-detail patterns where panel content supplements main content without blocking interaction.\n\n**Important:** The Panel must be a sibling of your main content in the grid layout, not nested inside it.',
+      },
+    },
+  },
+  argTypes: {
+    position: {
+      control: 'select',
+      options: ['left', 'right'],
+      description: 'Panel position (left or right side)',
+    },
+    width: {
+      control: 'select',
+      options: ['sm', 'md', 'lg', 'xl', 'auto'],
+      description:
+        'Panel width: sm=300px, md=400px, lg=500px, xl=600px, auto=content',
+    },
+    defaultOpen: {
+      control: 'boolean',
+      description: 'Default open state (uncontrolled mode)',
+    },
+    mobileBreakpoint: {
+      control: 'number',
+      description: 'Width in pixels below which panel renders as modal',
+    },
+  },
+} satisfies Meta<typeof Panel>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// ============================================================================
+// Default Story
+// ============================================================================
+
+/**
+ * Default Panel
+ * Basic panel with trigger, header, body, and footer.
+ * Note: Panel is a sibling of main in the grid, with trigger inside main.
+ */
+export const Default: Story = {
+  render: function DefaultPanel(): ReactElement {
+    const [isOpen, setIsOpen] = useState(false);
+
+    return (
+      <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+        <main className="p-4">
+          <h1 className="text-2xl font-bold mb-4">Main Content</h1>
+          <p className="text-[var(--muted-foreground)] mb-4">
+            Click the button to open the panel. The panel renders beside this
+            content, not over it.
+          </p>
+          <Button onClick={() => setIsOpen(true)}>Open Panel</Button>
+        </main>
+        <Panel isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Panel.Content>
+            <Panel.Header>
+              <Panel.Title>Panel Title</Panel.Title>
+              <Panel.Description>
+                This is a description of the panel content.
+              </Panel.Description>
+            </Panel.Header>
+            <Panel.Body>
+              <p>Panel body content goes here. This area is scrollable.</p>
+            </Panel.Body>
+            <Panel.Footer>
+              <Panel.Close>
+                <Button variant="outline">Cancel</Button>
+              </Panel.Close>
+              <Button>Save</Button>
+            </Panel.Footer>
+          </Panel.Content>
+        </Panel>
+      </div>
+    );
+  },
+};
+
+// ============================================================================
+// Position Variants
+// ============================================================================
+
+/**
+ * Position Left
+ * Panel appears on the left side
+ */
+export const PositionLeft: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[auto_1fr]">
+      <Panel position="left" defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Left Panel</Panel.Title>
+            <Panel.Description>
+              This panel opens on the left side.
+            </Panel.Description>
+          </Panel.Header>
+          <Panel.Body>
+            <p>Content for the left-positioned panel.</p>
+          </Panel.Body>
+        </Panel.Content>
+      </Panel>
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Main Content</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel is on the left side of this content.
+        </p>
+      </main>
+    </div>
+  ),
+};
+
+// ============================================================================
+// Width Variants
+// ============================================================================
+
+/**
+ * Width Small (300px)
+ */
+export const WidthSmall: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Small Width Panel</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel on the right is 300px wide.
+        </p>
+      </main>
+      <Panel width="sm" defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Small Panel</Panel.Title>
+          </Panel.Header>
+          <Panel.Body>
+            <p>300px width panel content.</p>
+          </Panel.Body>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+/**
+ * Width Large (500px)
+ */
+export const WidthLarge: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Large Width Panel</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel on the right is 500px wide.
+        </p>
+      </main>
+      <Panel width="lg" defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Large Panel</Panel.Title>
+          </Panel.Header>
+          <Panel.Body>
+            <p>500px width panel content.</p>
+          </Panel.Body>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+/**
+ * Width Extra Large (600px)
+ */
+export const WidthXLarge: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Extra Large Width Panel</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel on the right is 600px wide.
+        </p>
+      </main>
+      <Panel width="xl" defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Extra Large Panel</Panel.Title>
+          </Panel.Header>
+          <Panel.Body>
+            <p>600px width panel content.</p>
+          </Panel.Body>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+// ============================================================================
+// Controlled Mode
+// ============================================================================
+
+/**
+ * Controlled Mode
+ * External state management with isOpen and onOpenChange
+ */
+export const Controlled: Story = {
+  render: function ControlledPanel(): ReactElement {
+    const [isOpen, setIsOpen] = useState(false);
+
+    return (
+      <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+        <main className="p-4">
+          <h1 className="text-2xl font-bold mb-4">Controlled Panel</h1>
+          <p className="mb-4 text-[var(--muted-foreground)]">
+            Panel state: {isOpen ? 'Open' : 'Closed'}
+          </p>
+          <div className="flex gap-2">
+            <Button onClick={() => setIsOpen(true)}>Open Panel</Button>
+            <Button variant="outline" onClick={() => setIsOpen(false)}>
+              Close Panel
+            </Button>
+          </div>
+        </main>
+        <Panel
+          isOpen={isOpen}
+          onOpenChange={setIsOpen}
+          onClose={() => console.log('Panel closed!')}
+        >
+          <Panel.Content>
+            <Panel.Header>
+              <Panel.Title>Controlled Panel</Panel.Title>
+              <Panel.Description>
+                This panel is controlled externally.
+              </Panel.Description>
+            </Panel.Header>
+            <Panel.Body>
+              <p>State managed outside the component.</p>
+            </Panel.Body>
+            <Panel.Footer>
+              <Panel.Close>
+                <Button>Done</Button>
+              </Panel.Close>
+            </Panel.Footer>
+          </Panel.Content>
+        </Panel>
+      </div>
+    );
+  },
+};
+
+// ============================================================================
+// No Close Button
+// ============================================================================
+
+/**
+ * No Close Button
+ * Panel without the built-in close button
+ */
+export const NoCloseButton: Story = {
+  render: function NoCloseButtonPanel(): ReactElement {
+    const [isOpen, setIsOpen] = useState(true);
+
+    return (
+      <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+        <main className="p-4">
+          <h1 className="text-2xl font-bold mb-4">Panel Without Close Button</h1>
+          <p className="text-[var(--muted-foreground)] mb-4">
+            Use the button below or press Escape to toggle.
+          </p>
+          <Button onClick={() => setIsOpen(!isOpen)}>Toggle Panel</Button>
+        </main>
+        <Panel isOpen={isOpen} onOpenChange={setIsOpen}>
+          <Panel.Content showClose={false}>
+            <Panel.Header>
+              <Panel.Title>No Close Button</Panel.Title>
+              <Panel.Description>
+                Use the trigger or footer button to close.
+              </Panel.Description>
+            </Panel.Header>
+            <Panel.Body>
+              <p>
+                This panel has no built-in close button. Press Escape or click
+                the trigger to close.
+              </p>
+            </Panel.Body>
+            <Panel.Footer>
+              <Panel.Close>
+                <Button variant="outline">Close</Button>
+              </Panel.Close>
+            </Panel.Footer>
+          </Panel.Content>
+        </Panel>
+      </div>
+    );
+  },
+};
+
+// ============================================================================
+// Content Variants
+// ============================================================================
+
+/**
+ * With Header
+ * Panel with title and description in header
+ */
+export const WithHeader: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Panel with Header</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel shows a header with title and description.
+        </p>
+      </main>
+      <Panel defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Panel Header</Panel.Title>
+            <Panel.Description>
+              The header contains the title and an optional description. It
+              provides context for the panel content.
+            </Panel.Description>
+          </Panel.Header>
+          <Panel.Body>
+            <p>Main panel content here.</p>
+          </Panel.Body>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+/**
+ * With Footer
+ * Panel with action buttons in footer
+ */
+export const WithFooter: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Panel with Footer</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel has action buttons in the footer.
+        </p>
+      </main>
+      <Panel defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Footer Actions</Panel.Title>
+          </Panel.Header>
+          <Panel.Body>
+            <p>Panel content with action buttons below.</p>
+          </Panel.Body>
+          <Panel.Footer>
+            <Panel.Close>
+              <Button variant="outline">Cancel</Button>
+            </Panel.Close>
+            <Button variant="destructive">Delete</Button>
+            <Button>Save</Button>
+          </Panel.Footer>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+/**
+ * Full Structure
+ * Panel with header, body, and footer
+ */
+export const FullStructure: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Full Panel Structure</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel demonstrates header, body, and footer components.
+        </p>
+      </main>
+      <Panel defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Complete Panel</Panel.Title>
+            <Panel.Description>
+              This panel demonstrates all structural components.
+            </Panel.Description>
+          </Panel.Header>
+          <Panel.Body>
+            <div className="space-y-4">
+              <p>
+                The body contains the main content of the panel. It can include
+                any elements.
+              </p>
+              <ul className="list-disc pl-4 space-y-2">
+                <li>Lists</li>
+                <li>Forms</li>
+                <li>Images</li>
+                <li>Tables</li>
+              </ul>
+            </div>
+          </Panel.Body>
+          <Panel.Footer>
+            <Panel.Close>
+              <Button variant="outline">Cancel</Button>
+            </Panel.Close>
+            <Button>Confirm</Button>
+          </Panel.Footer>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+// ============================================================================
+// Scrollable Content
+// ============================================================================
+
+/**
+ * Scrollable Content
+ * Panel with long scrollable body content
+ */
+export const ScrollableContent: Story = {
+  render: () => (
+    <div className="grid h-[500px] grid-cols-[1fr_auto]">
+      <main className="p-4 overflow-auto">
+        <h1 className="text-2xl font-bold mb-4">Scrollable Panel</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel body scrolls when content exceeds available height.
+        </p>
+      </main>
+      <Panel defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Scrollable Body</Panel.Title>
+          </Panel.Header>
+          <Panel.Body>
+            <div className="space-y-4">
+              {Array.from({ length: 20 }, (_, i) => (
+                <div key={i} className="p-4 border rounded">
+                  <h3 className="font-semibold">Item {i + 1}</h3>
+                  <p className="text-[var(--muted-foreground)]">
+                    Lorem ipsum dolor sit amet, consectetur adipiscing elit.
+                  </p>
+                </div>
+              ))}
+            </div>
+          </Panel.Body>
+          <Panel.Footer>
+            <Button>Done</Button>
+          </Panel.Footer>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+// ============================================================================
+// Form Content
+// ============================================================================
+
+/**
+ * Form Content
+ * Panel with form elements inside
+ */
+export const FormContent: Story = {
+  render: () => (
+    <div className="grid min-h-[500px] grid-cols-[1fr_auto]">
+      <main className="p-4">
+        <h1 className="text-2xl font-bold mb-4">Panel with Form</h1>
+        <p className="text-[var(--muted-foreground)]">
+          The panel contains a form for editing settings.
+        </p>
+      </main>
+      <Panel defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Edit Settings</Panel.Title>
+            <Panel.Description>
+              Make changes to your settings here.
+            </Panel.Description>
+          </Panel.Header>
+          <Panel.Body>
+            <form
+              id="settings-form"
+              onSubmit={(e) => {
+                e.preventDefault();
+                alert('Form submitted!');
+              }}
+            >
+              <div className="space-y-4">
+                <div>
+                  <label
+                    htmlFor="name"
+                    className="block text-sm font-medium mb-1"
+                  >
+                    Name
+                  </label>
+                  <input
+                    id="name"
+                    type="text"
+                    className="w-full px-3 py-2 border rounded-md bg-[var(--background)] border-[var(--border)]"
+                    defaultValue="John Smith"
+                  />
+                </div>
+                <div>
+                  <label
+                    htmlFor="email"
+                    className="block text-sm font-medium mb-1"
+                  >
+                    Email
+                  </label>
+                  <input
+                    id="email"
+                    type="email"
+                    className="w-full px-3 py-2 border rounded-md bg-[var(--background)] border-[var(--border)]"
+                    defaultValue="john@example.com"
+                  />
+                </div>
+                <div>
+                  <label
+                    htmlFor="role"
+                    className="block text-sm font-medium mb-1"
+                  >
+                    Role
+                  </label>
+                  <select
+                    id="role"
+                    className="w-full px-3 py-2 border rounded-md bg-[var(--background)] border-[var(--border)]"
+                  >
+                    <option>Admin</option>
+                    <option>User</option>
+                    <option>Guest</option>
+                  </select>
+                </div>
+              </div>
+            </form>
+          </Panel.Body>
+          <Panel.Footer>
+            <Panel.Close>
+              <Button variant="outline">Cancel</Button>
+            </Panel.Close>
+            <Button type="submit" form="settings-form">
+              Save Changes
+            </Button>
+          </Panel.Footer>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+// ============================================================================
+// Master-Detail Pattern
+// ============================================================================
+
+interface Candidate {
+  id: string;
+  name: string;
+  role: string;
+  status: string;
+  email: string;
+  phone: string;
+}
+
+const candidates: Candidate[] = [
+  {
+    id: '1',
+    name: 'John Smith',
+    role: 'Software Engineer',
+    status: 'Interview',
+    email: 'john@example.com',
+    phone: '+1 555-0101',
+  },
+  {
+    id: '2',
+    name: 'Jane Doe',
+    role: 'Product Manager',
+    status: 'Screening',
+    email: 'jane@example.com',
+    phone: '+1 555-0102',
+  },
+  {
+    id: '3',
+    name: 'Bob Wilson',
+    role: 'UX Designer',
+    status: 'Offer',
+    email: 'bob@example.com',
+    phone: '+1 555-0103',
+  },
+];
+
+/**
+ * Candidate Profile (Master-Detail)
+ * Real-world example: clicking a candidate shows their profile in panel
+ */
+export const CandidateProfile: Story = {
+  render: function CandidateProfilePanel(): ReactElement {
+    const [selected, setSelected] = useState<Candidate | null>(null);
+
+    return (
+      <div className="grid min-h-[500px] grid-cols-[1fr_auto]">
+        <main className="p-4">
+          <h1 className="text-2xl font-bold mb-4">Candidates</h1>
+          <p className="text-[var(--muted-foreground)] mb-4">
+            Click a candidate to view their profile. The panel opens beside the
+            list without covering it.
+          </p>
+          <div className="space-y-2">
+            {candidates.map((candidate) => (
+              <div
+                key={candidate.id}
+                className="p-4 border rounded cursor-pointer hover:bg-[var(--accent)]"
+                onClick={() => setSelected(candidate)}
+              >
+                <div className="font-semibold">{candidate.name}</div>
+                <div className="text-sm text-[var(--muted-foreground)]">
+                  {candidate.role} - {candidate.status}
+                </div>
+              </div>
+            ))}
+          </div>
+        </main>
+        <Panel
+          isOpen={!!selected}
+          onOpenChange={(open) => !open && setSelected(null)}
+        >
+          <Panel.Content>
+            <Panel.Header>
+              <Panel.Title>{selected?.name ?? 'Candidate'}</Panel.Title>
+              <Panel.Description>{selected?.role}</Panel.Description>
+            </Panel.Header>
+            <Panel.Body>
+              {selected && (
+                <div className="space-y-4">
+                  <div>
+                    <div className="text-sm font-medium text-[var(--muted-foreground)]">
+                      Status
+                    </div>
+                    <div>{selected.status}</div>
+                  </div>
+                  <div>
+                    <div className="text-sm font-medium text-[var(--muted-foreground)]">
+                      Email
+                    </div>
+                    <div>{selected.email}</div>
+                  </div>
+                  <div>
+                    <div className="text-sm font-medium text-[var(--muted-foreground)]">
+                      Phone
+                    </div>
+                    <div>{selected.phone}</div>
+                  </div>
+                </div>
+              )}
+            </Panel.Body>
+            <Panel.Footer>
+              <Panel.Close>
+                <Button variant="outline">Close</Button>
+              </Panel.Close>
+              <Button>Send Email</Button>
+            </Panel.Footer>
+          </Panel.Content>
+        </Panel>
+      </div>
+    );
+  },
+};
+
+// ============================================================================
+// Grid Layout
+// ============================================================================
+
+/**
+ * Grid Layout
+ * Panel in CSS Grid layout demonstrating Focus Not Obscured (WCAG 2.4.12)
+ */
+export const GridLayout: Story = {
+  render: () => (
+    <div className="grid min-h-[400px] grid-cols-[1fr_auto] gap-4 p-4 bg-[var(--background)]">
+      <main className="border border-dashed border-[var(--border)] p-4 rounded">
+        <h2 className="font-bold mb-2">Main Content Area</h2>
+        <p className="text-[var(--muted-foreground)] mb-4">
+          The panel is a CSS Grid sibling, not an overlay. Both areas remain
+          fully interactive.
+        </p>
+        <Button variant="outline">Focusable Button</Button>
+      </main>
+      <Panel defaultOpen>
+        <Panel.Content>
+          <Panel.Header>
+            <Panel.Title>Side Panel</Panel.Title>
+          </Panel.Header>
+          <Panel.Body>
+            <p>
+              This panel participates in the grid layout. Main content is never
+              obscured.
+            </p>
+          </Panel.Body>
+        </Panel.Content>
+      </Panel>
+    </div>
+  ),
+};
+
+// ============================================================================
+// All Themes
+// ============================================================================
+
+/**
+ * All Themes
+ * Preview panel in all 4 themes
+ */
+export const AllThemes: Story = {
+  parameters: {
+    layout: 'padded',
+  },
+  render: () => (
+    <div className="grid grid-cols-2 gap-8">
+      {(['light', 'dark', 'highContrast', 'colorblind'] as const).map(
+        (theme) => (
+          <div
+            key={theme}
+            data-theme={theme}
+            className="p-4 border rounded bg-[var(--background)] text-[var(--foreground)]"
+          >
+            <h3 className="font-bold mb-2 capitalize">{theme} Theme</h3>
+            <div className="grid grid-cols-[1fr_auto] min-h-[200px]">
+              <div className="p-2 text-sm">Main content</div>
+              <Panel defaultOpen width="sm">
+                <Panel.Content>
+                  <Panel.Header>
+                    <Panel.Title as="h4">Panel</Panel.Title>
+                  </Panel.Header>
+                  <Panel.Body>
+                    <p className="text-sm">Theme: {theme}</p>
+                  </Panel.Body>
+                </Panel.Content>
+              </Panel>
+            </div>
+          </div>
+        )
+      )}
+    </div>
+  ),
+};