@tribepad/themis 1.0.0

package/src/elements/Toast/Toast.stories.tsx

@@ -0,0 +1,971 @@
+/**
+ * Toast Component Stories
+ * Storybook stories for Toast component demonstrating all variants, positions, and features
+ *
+ * @see toast-prd.md - Product Requirements Document
+ * @see plan.md - Implementation Plan
+ * @see constitution.md Principle IV (Accessibility First - WCAG 2.2 AAA)
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { useEffect, useState, type ReactElement } from 'react';
+import { Bell, CheckCircle2, AlertTriangle, Info, Download, Trash2 } from 'lucide-react';
+import { ToastProvider } from './ToastProvider';
+import { Toaster } from './Toaster';
+import { toast, toastQueue } from './Toast';
+import { Button } from '../Button';
+import type { ToasterPosition, ToastVariant } from './Toast.types';
+
+// =============================================================================
+// Story Wrapper Component
+// =============================================================================
+
+interface ToastStoryWrapperProps {
+  position?: ToasterPosition;
+  maxVisibleToasts?: number;
+  children: ReactElement;
+}
+
+/**
+ * Wrapper component that provides ToastProvider and Toaster for stories
+ */
+function ToastStoryWrapper({
+  position = 'bottom-right',
+  maxVisibleToasts = 3,
+  children,
+}: ToastStoryWrapperProps): ReactElement {
+  // Clear toasts on unmount to prevent leaks between stories
+  useEffect(() => {
+    return () => {
+      toastQueue.closeAll();
+    };
+  }, []);
+
+  return (
+    <ToastProvider maxVisibleToasts={maxVisibleToasts}>
+      <div className="min-h-[400px] w-full p-8">
+        {children}
+      </div>
+      <Toaster position={position} aria-label="Notifications" />
+    </ToastProvider>
+  );
+}
+
+// =============================================================================
+// Meta Configuration
+// =============================================================================
+
+const meta = {
+  title: 'Elements/Toast',
+  component: Toaster,
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: `Accessible toast notification system built with React Aria toast primitives, CVA variant styling, and WCAG 2.2 AAA compliance.
+
+**Key Features:**
+- 4 semantic variants (default, primary, destructive, accent)
+- 6 position options
+- Programmatic API via \`toast()\` function
+- Queue management with configurable limit
+- Swipe-to-dismiss on touch devices
+- Full keyboard navigation
+- Reduced motion support
+- "Clear All" button for bulk dismissal`,
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    position: {
+      control: 'select',
+      options: ['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'],
+      description: 'Position of the toast container',
+      table: {
+        defaultValue: { summary: 'bottom-right' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: 'Accessible label for the toast region',
+      table: {
+        defaultValue: { summary: 'Notifications' },
+      },
+    },
+  },
+} satisfies Meta<typeof Toaster>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// =============================================================================
+// Basic Stories
+// =============================================================================
+
+/**
+ * Default toast with simple string content
+ */
+export const Default: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Click the button to show a toast notification.
+        </p>
+        <Button onPress={() => toast('This is a default toast notification')}>
+          Show Toast
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+};
+
+/**
+ * All 4 variant styles in one view
+ */
+export const AllVariants: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Click each button to see different toast variants.
+        </p>
+        <div className="flex flex-wrap gap-4">
+          <Button
+            variant="outline"
+            onPress={() => toast('Default notification', { variant: 'default' })}
+          >
+            Default
+          </Button>
+          <Button
+            variant="default"
+            onPress={() => toast('Primary notification', { variant: 'primary' })}
+          >
+            Primary
+          </Button>
+          <Button
+            variant="destructive"
+            onPress={() => toast('Destructive notification', { variant: 'destructive' })}
+          >
+            Destructive
+          </Button>
+          <Button
+            variant="secondary"
+            onPress={() => toast('Accent notification', { variant: 'accent' })}
+          >
+            Accent
+          </Button>
+        </div>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Four semantic variants that map to theme tokens: default, primary, destructive, and accent.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Custom Content Stories
+// =============================================================================
+
+/**
+ * Toast with custom ReactNode content including icons and actions
+ */
+export const WithCustomContent: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Toasts can contain custom content including icons and interactive elements.
+        </p>
+        <div className="flex flex-wrap gap-4">
+          <Button
+            variant="outline"
+            onPress={() =>
+              toast(
+                <div className="flex items-center gap-2">
+                  <CheckCircle2 className="h-4 w-4 text-green-500" />
+                  <span>Changes saved successfully!</span>
+                </div>
+              )
+            }
+          >
+            With Success Icon
+          </Button>
+          <Button
+            variant="outline"
+            onPress={() =>
+              toast(
+                <div className="flex items-center gap-2">
+                  <AlertTriangle className="h-4 w-4 text-yellow-500" />
+                  <span>Your session will expire in 5 minutes</span>
+                </div>,
+                { variant: 'accent' }
+              )
+            }
+          >
+            With Warning Icon
+          </Button>
+          <Button
+            variant="outline"
+            onPress={() =>
+              toast(
+                <div className="flex items-center gap-2">
+                  <Info className="h-4 w-4" />
+                  <span>New version available</span>
+                  <button
+                    type="button"
+                    className="ml-2 text-xs underline hover:no-underline"
+                    onClick={() => alert('Updating...')}
+                  >
+                    Update now
+                  </button>
+                </div>
+              )
+            }
+          >
+            With Action Button
+          </Button>
+        </div>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Custom ReactNode content allows icons, styled text, and interactive elements within toasts.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Timing Stories
+// =============================================================================
+
+/**
+ * Auto-dismiss behavior with default 5 second timeout
+ */
+export const AutoDismiss: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Toasts auto-dismiss after 5 seconds (minimum for accessibility).
+        </p>
+        <Button onPress={() => toast('This will auto-dismiss in 5 seconds')}>
+          Show Auto-Dismiss Toast
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toasts enforce a minimum 5-second timeout for WCAG 2.2 accessibility compliance, giving users adequate time to read.',
+      },
+    },
+  },
+};
+
+/**
+ * Persistent toast that stays until manually dismissed
+ */
+export const Persistent: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Set timeout to 0 for persistent toasts that require user action.
+        </p>
+        <Button
+          onPress={() =>
+            toast('This toast will stay until you dismiss it', { timeout: 0 })
+          }
+        >
+          Show Persistent Toast
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use `timeout: 0` for important notifications that require user acknowledgment.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Callback Stories
+// =============================================================================
+
+/**
+ * Toast with onClose callback for tracking
+ */
+export const WithCallback: Story = {
+  render: function WithCallbackStory() {
+    const [log, setLog] = useState<string[]>([]);
+
+    return (
+      <ToastStoryWrapper>
+        <div className="flex flex-col items-start gap-4">
+          <p className="text-sm text-[var(--muted-foreground)]">
+            The onClose callback receives the toast key and dismissal reason.
+          </p>
+          <Button
+            onPress={() =>
+              toast('Dismiss me to see the callback', {
+                timeout: 0,
+                onClose: (key, reason) => {
+                  setLog((prev) => [...prev, `Toast ${key.slice(0, 8)}... dismissed: ${reason}`]);
+                },
+              })
+            }
+          >
+            Show Toast with Callback
+          </Button>
+          {log.length > 0 && (
+            <div className="mt-4 rounded border border-[var(--border)] bg-[var(--muted)] p-4">
+              <p className="mb-2 text-sm font-medium">Callback Log:</p>
+              {log.map((entry, i) => (
+                <p key={i} className="text-xs font-mono">{entry}</p>
+              ))}
+            </div>
+          )}
+        </div>
+      </ToastStoryWrapper>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'The `onClose` callback is invoked with the toast key and reason (`timeout`, `user`, or `programmatic`) for analytics and state management.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Position Stories
+// =============================================================================
+
+/**
+ * All 6 position options
+ */
+export const AllPositions: Story = {
+  render: function AllPositionsStory() {
+    const [position, setPosition] = useState<ToasterPosition>('bottom-right');
+
+    return (
+      <ToastStoryWrapper position={position}>
+        <div className="flex flex-col items-start gap-4">
+          <p className="text-sm text-[var(--muted-foreground)]">
+            Select a position and click "Show Toast" to see it in action.
+          </p>
+          <div className="flex flex-wrap gap-2">
+            {(['top-left', 'top-center', 'top-right', 'bottom-left', 'bottom-center', 'bottom-right'] as const).map(
+              (pos) => (
+                <Button
+                  key={pos}
+                  variant={position === pos ? 'default' : 'outline'}
+                  size="sm"
+                  onPress={() => setPosition(pos)}
+                >
+                  {pos}
+                </Button>
+              )
+            )}
+          </div>
+          <Button onPress={() => toast(`Toast at ${position}`, { timeout: 0 })}>
+            Show Toast
+          </Button>
+        </div>
+      </ToastStoryWrapper>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Six position options allow placement at any corner or center edge of the viewport.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Queue Management Stories
+// =============================================================================
+
+/**
+ * Multiple toasts with queue management
+ */
+export const MultipleToasts: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Click rapidly to see multiple toasts stack and queue.
+        </p>
+        <div className="flex flex-wrap gap-4">
+          <Button
+            onPress={() => {
+              const variants: ToastVariant[] = ['default', 'primary', 'destructive', 'accent'];
+              const variant = variants[Math.floor(Math.random() * variants.length)];
+              toast(`Toast #${Date.now() % 1000}`, { variant, timeout: 0 });
+            }}
+          >
+            Add Random Toast
+          </Button>
+          <Button variant="outline" onPress={() => toastQueue.closeAll()}>
+            Clear All
+          </Button>
+        </div>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Multiple toasts stack vertically with the newest at the bottom. Excess toasts are queued.',
+      },
+    },
+  },
+};
+
+/**
+ * Queue limit demonstration
+ */
+export const QueueManagement: Story = {
+  render: () => (
+    <ToastStoryWrapper maxVisibleToasts={3}>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Default maxVisibleToasts is 3. Additional toasts are queued and shown when space is available.
+        </p>
+        <Button
+          onPress={() => {
+            for (let i = 1; i <= 6; i++) {
+              toast(`Toast ${i} of 6`, { timeout: 0 });
+            }
+          }}
+        >
+          Add 6 Toasts (3 visible, 3 queued)
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'The `maxVisibleToasts` prop limits visible toasts. Additional toasts are queued and appear when others are dismissed.',
+      },
+    },
+  },
+};
+
+/**
+ * Collapsed stack indicator
+ */
+export const CollapsedStack: Story = {
+  render: () => (
+    <ToastStoryWrapper maxVisibleToasts={2}>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          When toasts exceed maxVisibleToasts, a collapsed stack indicator shows the queue count.
+        </p>
+        <Button
+          onPress={() => {
+            for (let i = 1; i <= 5; i++) {
+              toast(`Notification ${i}`, { timeout: 0 });
+            }
+          }}
+        >
+          Add 5 Toasts (maxVisible=2)
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'A "+N more" indicator appears below visible toasts when additional notifications are queued, using `aria-live="polite"` for screen reader announcement.',
+      },
+    },
+  },
+};
+
+/**
+ * Clear All button demonstration
+ */
+export const ClearAllButton: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          When 2+ toasts are visible, a "Clear All" button appears to dismiss all at once.
+        </p>
+        <Button
+          onPress={() => {
+            toast('First notification', { timeout: 0 });
+            toast('Second notification', { timeout: 0 });
+            toast('Third notification', { timeout: 0 });
+          }}
+        >
+          Add 3 Toasts
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'The "Clear All" button provides a quick way to dismiss all visible toasts. It appears only when 2+ toasts are visible.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Accessibility Stories
+// =============================================================================
+
+/**
+ * Keyboard navigation instructions
+ */
+export const KeyboardNavigation: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <div className="rounded border border-[var(--border)] bg-[var(--muted)] p-4">
+          <p className="mb-2 font-medium">Keyboard Controls:</p>
+          <ul className="space-y-1 text-sm">
+            <li><kbd className="rounded bg-[var(--background)] px-1">F6</kbd> - Navigate to toast region</li>
+            <li><kbd className="rounded bg-[var(--background)] px-1">Tab</kbd> - Move between toasts and buttons</li>
+            <li><kbd className="rounded bg-[var(--background)] px-1">Escape</kbd> - Dismiss focused toast</li>
+            <li><kbd className="rounded bg-[var(--background)] px-1">Enter</kbd> - Activate focused button</li>
+          </ul>
+        </div>
+        <Button onPress={() => toast('Try navigating with keyboard!', { timeout: 0 })}>
+          Show Toast (then use F6 to focus)
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Full keyboard navigation support for users who cannot use a mouse. The toast region is an ARIA landmark accessible via F6.',
+      },
+    },
+  },
+};
+
+/**
+ * Touch target size demonstration
+ */
+export const TouchTarget: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Close buttons have 44x44px minimum touch targets (WCAG 2.2 AAA compliant).
+        </p>
+        <Button onPress={() => toast('Close button has 44x44px touch target', { timeout: 0 })}>
+          Show Toast
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All interactive elements meet WCAG 2.2 AAA 44x44px minimum touch target requirement.',
+      },
+    },
+  },
+};
+
+/**
+ * Swipe-to-dismiss on touch devices
+ */
+export const SwipeToDismiss: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          On touch devices, swipe right to dismiss a toast (50px threshold).
+        </p>
+        <div className="rounded border border-[var(--border)] bg-[var(--accent-background)] p-4 text-sm">
+          <p>Try on a touch device or enable touch emulation in DevTools.</p>
+        </div>
+        <Button onPress={() => toast('Swipe me right to dismiss!', { timeout: 0 })}>
+          Show Toast
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Touch users can swipe toasts to the right to dismiss them. A 50px threshold prevents accidental dismissals.',
+      },
+    },
+  },
+};
+
+/**
+ * Reduced motion support
+ */
+export const ReducedMotion: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          When <code>prefers-reduced-motion: reduce</code> is set, animations are disabled.
+        </p>
+        <div className="rounded border border-[var(--border)] bg-[var(--muted)] p-4 text-sm">
+          <p>To test: Enable "Reduce motion" in your OS accessibility settings,</p>
+          <p>or use DevTools → Rendering → Emulate CSS media feature → prefers-reduced-motion: reduce</p>
+        </div>
+        <Button onPress={() => toast('This toast respects reduced motion preferences')}>
+          Show Toast
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toasts respect `prefers-reduced-motion` media query. When enabled, slide animations are disabled and toasts appear/disappear instantly.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Theme Stories
+// =============================================================================
+
+/**
+ * All themes demonstration
+ */
+export const AllThemes: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Toasts automatically adapt to the current theme via CSS custom properties.
+        </p>
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Use the theme switcher in the Storybook toolbar to see different themes.
+        </p>
+        <div className="flex flex-wrap gap-4">
+          <Button
+            variant="outline"
+            onPress={() => toast('Default variant', { variant: 'default', timeout: 0 })}
+          >
+            Default
+          </Button>
+          <Button
+            variant="default"
+            onPress={() => toast('Primary variant', { variant: 'primary', timeout: 0 })}
+          >
+            Primary
+          </Button>
+          <Button
+            variant="destructive"
+            onPress={() => toast('Destructive variant', { variant: 'destructive', timeout: 0 })}
+          >
+            Destructive
+          </Button>
+          <Button
+            variant="secondary"
+            onPress={() => toast('Accent variant', { variant: 'accent', timeout: 0 })}
+          >
+            Accent
+          </Button>
+        </div>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Toast variants use semantic CSS tokens that automatically adapt to light, dark, high-contrast, and colorblind themes.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// Real-World Example Stories
+// =============================================================================
+
+/**
+ * File upload progress notification
+ */
+export const FileUploadExample: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Real-world example: File upload progress and completion notifications.
+        </p>
+        <div className="flex flex-wrap gap-4">
+          <Button
+            variant="outline"
+            onPress={() => {
+              toast(
+                <div className="flex items-center gap-2">
+                  <Download className="h-4 w-4 animate-pulse" />
+                  <span>Uploading document.pdf...</span>
+                </div>,
+                { timeout: 0 }
+              );
+            }}
+          >
+            <Download className="h-4 w-4 mr-2" />
+            Start Upload
+          </Button>
+          <Button
+            variant="outline"
+            onPress={() => {
+              toast(
+                <div className="flex items-center gap-2">
+                  <CheckCircle2 className="h-4 w-4 text-green-500" />
+                  <span>Upload complete! File saved.</span>
+                </div>,
+                { variant: 'primary' }
+              );
+            }}
+          >
+            <CheckCircle2 className="h-4 w-4 mr-2" />
+            Complete Upload
+          </Button>
+        </div>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example of using toasts for file upload progress and completion feedback.',
+      },
+    },
+  },
+};
+
+/**
+ * Delete confirmation notification
+ */
+export const DeleteConfirmationExample: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Real-world example: Destructive action confirmation with undo option.
+        </p>
+        <Button
+          variant="destructive"
+          onPress={() => {
+            const key = toast(
+              <div className="flex items-center gap-2">
+                <Trash2 className="h-4 w-4" />
+                <span>Item deleted.</span>
+                <button
+                  type="button"
+                  className="ml-2 underline hover:no-underline"
+                  onClick={() => {
+                    toastQueue.close(key);
+                    toast('Item restored!', { variant: 'primary' });
+                  }}
+                >
+                  Undo
+                </button>
+              </div>,
+              { variant: 'destructive', timeout: 8000 }
+            );
+          }}
+        >
+          <Trash2 className="h-4 w-4 mr-2" />
+          Delete Item
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example of a destructive notification with an inline undo action.',
+      },
+    },
+  },
+};
+
+/**
+ * Notification center pattern
+ */
+export const NotificationCenterExample: Story = {
+  render: () => (
+    <ToastStoryWrapper>
+      <div className="flex flex-col items-start gap-4">
+        <p className="text-sm text-[var(--muted-foreground)]">
+          Real-world example: Multiple notification types in a notification center pattern.
+        </p>
+        <Button
+          onPress={() => {
+            toast(
+              <div className="flex items-center gap-2">
+                <Bell className="h-4 w-4" />
+                <span>New message from John Doe</span>
+              </div>,
+              { timeout: 0 }
+            );
+            setTimeout(() => {
+              toast(
+                <div className="flex items-center gap-2">
+                  <CheckCircle2 className="h-4 w-4 text-green-500" />
+                  <span>Interview scheduled for tomorrow</span>
+                </div>,
+                { variant: 'primary', timeout: 0 }
+              );
+            }, 500);
+            setTimeout(() => {
+              toast(
+                <div className="flex items-center gap-2">
+                  <AlertTriangle className="h-4 w-4 text-yellow-500" />
+                  <span>Document review required</span>
+                </div>,
+                { variant: 'accent', timeout: 0 }
+              );
+            }, 1000);
+          }}
+        >
+          <Bell className="h-4 w-4 mr-2" />
+          Show Notifications
+        </Button>
+      </div>
+    </ToastStoryWrapper>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Example of multiple notification types appearing in sequence, demonstrating the queue and stack behavior.',
+      },
+    },
+  },
+};
+
+// =============================================================================
+// API Reference Story
+// =============================================================================
+
+/**
+ * Programmatic API demonstration
+ */
+export const APIReference: Story = {
+  render: function APIReferenceStory() {
+    const [keys, setKeys] = useState<string[]>([]);
+
+    return (
+      <ToastStoryWrapper>
+        <div className="flex flex-col gap-6">
+          <div className="rounded border border-[var(--border)] p-4">
+            <h4 className="mb-2 font-medium">toast() Function</h4>
+            <pre className="rounded bg-[var(--muted)] p-2 text-xs overflow-x-auto">
+{`// Simple string
+toast("Hello world!");
+
+// With options
+toast("Error occurred", {
+  variant: "destructive",
+  timeout: 0,
+  onClose: (key, reason) => console.log(reason)
+});
+
+// Custom content
+toast(<div className="flex items-center gap-2">
+  <Icon /><span>Custom content</span>
+</div>);`}
+            </pre>
+          </div>
+
+          <div className="rounded border border-[var(--border)] p-4">
+            <h4 className="mb-2 font-medium">toastQueue Methods</h4>
+            <div className="flex flex-wrap gap-2">
+              <Button
+                size="sm"
+                variant="outline"
+                onPress={() => {
+                  const key = toast('New toast', { timeout: 0 });
+                  setKeys((prev) => [...prev, key]);
+                }}
+              >
+                add() - Returns key
+              </Button>
+              <Button
+                size="sm"
+                variant="outline"
+                onPress={() => {
+                  if (keys.length > 0) {
+                    toastQueue.close(keys[keys.length - 1] ?? '');
+                    setKeys((prev) => prev.slice(0, -1));
+                  }
+                }}
+              >
+                close(key)
+              </Button>
+              <Button
+                size="sm"
+                variant="outline"
+                onPress={() => {
+                  toastQueue.closeAll();
+                  setKeys([]);
+                }}
+              >
+                closeAll()
+              </Button>
+              <Button
+                size="sm"
+                variant="outline"
+                onPress={() => toastQueue.pauseAll()}
+              >
+                pauseAll()
+              </Button>
+              <Button
+                size="sm"
+                variant="outline"
+                onPress={() => toastQueue.resumeAll()}
+              >
+                resumeAll()
+              </Button>
+            </div>
+          </div>
+
+          {keys.length > 0 && (
+            <div className="rounded border border-[var(--border)] bg-[var(--muted)] p-4">
+              <p className="mb-2 text-sm font-medium">Active Toast Keys:</p>
+              {keys.map((key, i) => (
+                <p key={i} className="text-xs font-mono">{key}</p>
+              ))}
+            </div>
+          )}
+        </div>
+      </ToastStoryWrapper>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Interactive demonstration of the programmatic toast API and queue management methods.',
+      },
+    },
+  },
+};