@neynar/ui 0.4.0 → 0.5.0

package/src/components/ui/stories/toggle-group.stories.tsx

@@ -1,336 +1,493 @@
-import type { Meta, StoryObj } from "@storybook/react-vite";
+import type { Meta, StoryObj } from "@storybook/react";
+import { fn } from "storybook/test";
 import {
-  Bold,
-  Italic,
-  Underline,
-  AlignLeft,
-  AlignCenter,
-  AlignRight,
-  AlignJustify,
+  AlignCenterIcon,
+  AlignJustifyIcon,
+  AlignLeftIcon,
+  AlignRightIcon,
+  BoldIcon,
+  CalendarIcon,
+  GridIcon,
+  ItalicIcon,
+  ListIcon,
+  UnderlineIcon,
 } from "lucide-react";
+import { useState } from "react";
+
 import { ToggleGroup, ToggleGroupItem } from "../toggle-group";
 
-const meta = {
-  title: "Interactive Controls/ToggleGroup",
+const meta: Meta<typeof ToggleGroup> = {
+  title: "Components/Core Inputs/ToggleGroup",
   component: ToggleGroup,
   parameters: {
     layout: "centered",
-    docs: {
-      description: {
-        component:
-          "A versatile toggle group component for grouping related toggle buttons with single or multiple selection modes. Built on Radix UI primitives with full keyboard navigation, accessibility support, and customizable variants. Perfect for toolbars, formatting controls, and option selection interfaces.",
-      },
-    },
+  },
+  args: {
+    onValueChange: fn(),
   },
   argTypes: {
-    type: {
-      control: { type: "select" },
-      options: ["single", "multiple"],
-      description:
-        "Selection mode: 'single' for radio-like behavior, 'multiple' for checkbox-like behavior",
-    },
     variant: {
-      control: { type: "select" },
+      control: "select",
       options: ["default", "outline"],
-      description:
-        "Visual style variant: 'default' for subtle styling, 'outline' for bordered appearance",
+      description: "Visual style variant inherited by all items",
     },
     size: {
-      control: { type: "select" },
-      options: ["sm", "default", "lg"],
-      description:
-        "Size of toggle group items: 'sm' (compact), 'default' (standard), 'lg' (large)",
-    },
-    disabled: {
-      control: { type: "boolean" },
-      description:
-        "Whether the entire toggle group is disabled and non-interactive",
+      control: "select",
+      options: ["default", "sm", "lg"],
+      description: "Size variant inherited by all items",
     },
-    defaultValue: {
-      control: false,
-      description:
-        "Initial selected value(s) - string for single type, array for multiple type",
+    spacing: {
+      control: "number",
+      description: "Gap between items in pixels (0 = joined buttons)",
     },
-    value: {
-      control: false,
-      description:
-        "Controlled selected value(s) - string for single type, array for multiple type",
-    },
-    onValueChange: {
-      control: false,
-      description: "Callback function called when the selection changes",
+    orientation: {
+      control: "select",
+      options: ["horizontal", "vertical"],
+      description: "Layout direction of the toggle group",
     },
   },
-} satisfies Meta<typeof ToggleGroup>;
+};
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof ToggleGroup>;
 
 /**
- * Interactive playground story for testing all ToggleGroup props and variants
+ * Analytics Dashboard - Time range selector for viewing metrics across different periods.
+ * Demonstrates realistic usage in the Neynar Dashboard with single selection mode.
  */
-export const Interactive: Story = {
-  args: {
-    type: "multiple",
-    variant: "outline",
-    size: "default",
-    disabled: false,
-  },
-  render: (args) => (
-    <ToggleGroup {...args}>
-      <ToggleGroupItem value="bold" aria-label="Toggle bold">
-        <Bold className="size-4" />
-      </ToggleGroupItem>
-      <ToggleGroupItem value="italic" aria-label="Toggle italic">
-        <Italic className="size-4" />
-      </ToggleGroupItem>
-      <ToggleGroupItem value="underline" aria-label="Toggle underline">
-        <Underline className="size-4" />
-      </ToggleGroupItem>
-    </ToggleGroup>
-  ),
+export const InContext: Story = {
   parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive playground for testing all ToggleGroup properties. Use the controls panel to experiment with different combinations of type, variant, size, and disabled state.",
-      },
-    },
+    layout: "padded",
+  },
+  render: () => {
+    function AnalyticsDashboard() {
+      const [timeRange, setTimeRange] = useState(["7d"]);
+      const [view, setView] = useState(["grid"]);
+
+      return (
+        <div className="w-full max-w-2xl space-y-6">
+          {/* Header with Time Range Selector */}
+          <div className="space-y-4">
+            <div className="flex items-center justify-between">
+              <div>
+                <h2 className="text-lg font-semibold">Cast Analytics</h2>
+                <p className="text-muted-foreground text-sm">
+                  Track engagement metrics across your Farcaster casts
+                </p>
+              </div>
+            </div>
+
+            <div className="flex items-center justify-between">
+              <ToggleGroup
+                value={timeRange}
+                onValueChange={(value) => {
+                  if (value) setTimeRange(value);
+                }}
+                variant="outline"
+                spacing={0}
+              >
+                <ToggleGroupItem value="1d">1D</ToggleGroupItem>
+                <ToggleGroupItem value="7d">7D</ToggleGroupItem>
+                <ToggleGroupItem value="30d">30D</ToggleGroupItem>
+                <ToggleGroupItem value="90d">90D</ToggleGroupItem>
+              </ToggleGroup>
+
+              <ToggleGroup
+                value={view}
+                onValueChange={(value) => {
+                  if (value) setView(value);
+                }}
+                variant="outline"
+                spacing={0}
+              >
+                <ToggleGroupItem value="grid" aria-label="Grid view">
+                  <GridIcon />
+                </ToggleGroupItem>
+                <ToggleGroupItem value="list" aria-label="List view">
+                  <ListIcon />
+                </ToggleGroupItem>
+              </ToggleGroup>
+            </div>
+          </div>
+
+          {/* Metrics Cards */}
+          <div className="grid grid-cols-3 gap-4">
+            <div className="bg-card border-border rounded-lg border p-4">
+              <p className="text-muted-foreground text-sm">Impressions</p>
+              <p className="mt-1 text-2xl font-semibold">
+                {timeRange.includes("1d") && "1,234"}
+                {timeRange.includes("7d") && "8,567"}
+                {timeRange.includes("30d") && "32,145"}
+                {timeRange.includes("90d") && "98,234"}
+              </p>
+              <p className="text-muted-foreground mt-1 text-xs">
+                {timeRange.includes("1d") && "Last 24 hours"}
+                {timeRange.includes("7d") && "Last 7 days"}
+                {timeRange.includes("30d") && "Last 30 days"}
+                {timeRange.includes("90d") && "Last 90 days"}
+              </p>
+            </div>
+            <div className="bg-card border-border rounded-lg border p-4">
+              <p className="text-muted-foreground text-sm">Engagement</p>
+              <p className="mt-1 text-2xl font-semibold">
+                {timeRange.includes("1d") && "234"}
+                {timeRange.includes("7d") && "1,567"}
+                {timeRange.includes("30d") && "5,234"}
+                {timeRange.includes("90d") && "15,890"}
+              </p>
+              <p className="text-muted-foreground mt-1 text-xs">
+                Likes + Recasts + Replies
+              </p>
+            </div>
+            <div className="bg-card border-border rounded-lg border p-4">
+              <p className="text-muted-foreground text-sm">New Followers</p>
+              <p className="mt-1 text-2xl font-semibold">
+                {timeRange.includes("1d") && "+12"}
+                {timeRange.includes("7d") && "+89"}
+                {timeRange.includes("30d") && "+234"}
+                {timeRange.includes("90d") && "+567"}
+              </p>
+              <p className="text-muted-foreground mt-1 text-xs">Net growth</p>
+            </div>
+          </div>
+
+          {/* Text Formatting Toolbar */}
+          <div className="bg-card border-border space-y-3 rounded-lg border p-4">
+            <p className="text-sm font-medium">Compose Cast</p>
+            <div className="flex items-center gap-3">
+              <ToggleGroup variant="outline" spacing={0}>
+                <ToggleGroupItem value="bold" aria-label="Bold">
+                  <BoldIcon />
+                </ToggleGroupItem>
+                <ToggleGroupItem value="italic" aria-label="Italic">
+                  <ItalicIcon />
+                </ToggleGroupItem>
+                <ToggleGroupItem value="underline" aria-label="Underline">
+                  <UnderlineIcon />
+                </ToggleGroupItem>
+              </ToggleGroup>
+
+              <ToggleGroup variant="outline" spacing={0}>
+                <ToggleGroupItem value="left" aria-label="Align left">
+                  <AlignLeftIcon />
+                </ToggleGroupItem>
+                <ToggleGroupItem value="center" aria-label="Align center">
+                  <AlignCenterIcon />
+                </ToggleGroupItem>
+                <ToggleGroupItem value="right" aria-label="Align right">
+                  <AlignRightIcon />
+                </ToggleGroupItem>
+                <ToggleGroupItem value="justify" aria-label="Justify">
+                  <AlignJustifyIcon />
+                </ToggleGroupItem>
+              </ToggleGroup>
+            </div>
+          </div>
+        </div>
+      );
+    }
+
+    return <AnalyticsDashboard />;
   },
 };
 
 /**
- * Showcase of all available variants and sizes in a systematic layout
+ * Complete design system reference showing all toggle group variants,
+ * sizes, orientations, and spacing options.
  */
 export const Variants: Story = {
-  args: {
-    type: "single",
-    variant: "default",
-    size: "default",
-    disabled: false,
+  parameters: {
+    layout: "padded",
   },
   render: () => (
-    <div className="space-y-8">
-      <div className="space-y-4">
-        <h3 className="text-lg font-semibold">Variants</h3>
-
-        <div className="space-y-3">
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">
-              Default variant (subtle styling)
-            </p>
-            <ToggleGroup type="single" variant="default" defaultValue="center">
-              <ToggleGroupItem value="left">Left</ToggleGroupItem>
-              <ToggleGroupItem value="center">Center</ToggleGroupItem>
-              <ToggleGroupItem value="right">Right</ToggleGroupItem>
+    <div className="w-full max-w-5xl space-y-10">
+      {/* Visual Variants */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Visual Variants</h3>
+          <p className="text-muted-foreground text-sm">
+            Different styles for different contexts and emphasis levels.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-6">
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Default</p>
+            <ToggleGroup variant="default" spacing={0}>
+              <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+              <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+              <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
-
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">
-              Outline variant (bordered)
-            </p>
-            <ToggleGroup type="single" variant="outline" defaultValue="center">
-              <ToggleGroupItem value="left">Left</ToggleGroupItem>
-              <ToggleGroupItem value="center">Center</ToggleGroupItem>
-              <ToggleGroupItem value="right">Right</ToggleGroupItem>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Outline</p>
+            <ToggleGroup variant="outline" spacing={0}>
+              <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+              <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+              <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
         </div>
-      </div>
-
-      <div className="space-y-4">
-        <h3 className="text-lg font-semibold">Sizes</h3>
+      </section>
 
-        <div className="space-y-3">
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">Small (sm)</p>
-            <ToggleGroup type="single" size="sm" variant="outline">
-              <ToggleGroupItem value="xs">XS</ToggleGroupItem>
-              <ToggleGroupItem value="sm">SM</ToggleGroupItem>
-              <ToggleGroupItem value="md">MD</ToggleGroupItem>
+      {/* Sizes */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Sizes</h3>
+          <p className="text-muted-foreground text-sm">
+            Multiple sizes for different density and emphasis needs.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-6">
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Small</p>
+            <ToggleGroup variant="outline" size="sm" spacing={0}>
+              <ToggleGroupItem value="sm1">Small 1</ToggleGroupItem>
+              <ToggleGroupItem value="sm2">Small 2</ToggleGroupItem>
+              <ToggleGroupItem value="sm3">Small 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
-
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">Default</p>
-            <ToggleGroup type="single" size="default" variant="outline">
-              <ToggleGroupItem value="small">Small</ToggleGroupItem>
-              <ToggleGroupItem value="medium">Medium</ToggleGroupItem>
-              <ToggleGroupItem value="large">Large</ToggleGroupItem>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Default</p>
+            <ToggleGroup variant="outline" size="default" spacing={0}>
+              <ToggleGroupItem value="default1">Default 1</ToggleGroupItem>
+              <ToggleGroupItem value="default2">Default 2</ToggleGroupItem>
+              <ToggleGroupItem value="default3">Default 3</ToggleGroupItem>
+            </ToggleGroup>
+          </div>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Large</p>
+            <ToggleGroup variant="outline" size="lg" spacing={0}>
+              <ToggleGroupItem value="lg1">Large 1</ToggleGroupItem>
+              <ToggleGroupItem value="lg2">Large 2</ToggleGroupItem>
+              <ToggleGroupItem value="lg3">Large 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
+        </div>
+      </section>
 
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">Large (lg)</p>
-            <ToggleGroup type="single" size="lg" variant="outline">
-              <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
-              <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
-              <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
+      {/* Spacing */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Spacing</h3>
+          <p className="text-muted-foreground text-sm">
+            Control the gap between items - 0 creates joined buttons.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-6">
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Joined (spacing=0)</p>
+            <ToggleGroup variant="outline" spacing={0}>
+              <ToggleGroupItem value="joined1">Joined 1</ToggleGroupItem>
+              <ToggleGroupItem value="joined2">Joined 2</ToggleGroupItem>
+              <ToggleGroupItem value="joined3">Joined 3</ToggleGroupItem>
+            </ToggleGroup>
+          </div>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Gap (spacing=2)</p>
+            <ToggleGroup variant="outline" spacing={2}>
+              <ToggleGroupItem value="gap1">Gap 1</ToggleGroupItem>
+              <ToggleGroupItem value="gap2">Gap 2</ToggleGroupItem>
+              <ToggleGroupItem value="gap3">Gap 3</ToggleGroupItem>
+            </ToggleGroup>
+          </div>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Spaced (spacing=4)</p>
+            <ToggleGroup variant="outline" spacing={4}>
+              <ToggleGroupItem value="space1">Spaced 1</ToggleGroupItem>
+              <ToggleGroupItem value="space2">Spaced 2</ToggleGroupItem>
+              <ToggleGroupItem value="space3">Spaced 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
         </div>
-      </div>
+      </section>
 
-      <div className="space-y-4">
-        <h3 className="text-lg font-semibold">Selection Types</h3>
+      {/* Orientation */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Orientation</h3>
+          <p className="text-muted-foreground text-sm">
+            Horizontal or vertical layout for different use cases.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-start gap-6">
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Horizontal</p>
+            <ToggleGroup variant="outline" spacing={0} orientation="horizontal">
+              <ToggleGroupItem value="h1">Horizontal 1</ToggleGroupItem>
+              <ToggleGroupItem value="h2">Horizontal 2</ToggleGroupItem>
+              <ToggleGroupItem value="h3">Horizontal 3</ToggleGroupItem>
+            </ToggleGroup>
+          </div>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Vertical</p>
+            <ToggleGroup variant="outline" spacing={0} orientation="vertical">
+              <ToggleGroupItem value="v1">Vertical 1</ToggleGroupItem>
+              <ToggleGroupItem value="v2">Vertical 2</ToggleGroupItem>
+              <ToggleGroupItem value="v3">Vertical 3</ToggleGroupItem>
+            </ToggleGroup>
+          </div>
+        </div>
+      </section>
 
-        <div className="space-y-3">
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">
-              Single selection (radio-like behavior)
+      {/* Selection Types */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Selection Types</h3>
+          <p className="text-muted-foreground text-sm">
+            Single selection or multiple items can be active at once.
+          </p>
+        </div>
+        <div className="flex flex-wrap items-center gap-6">
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">
+              Single (type="single")
             </p>
-            <ToggleGroup type="single" variant="outline" defaultValue="center">
-              <ToggleGroupItem value="left" aria-label="Align left">
-                <AlignLeft className="size-4" />
-              </ToggleGroupItem>
-              <ToggleGroupItem value="center" aria-label="Align center">
-                <AlignCenter className="size-4" />
-              </ToggleGroupItem>
-              <ToggleGroupItem value="right" aria-label="Align right">
-                <AlignRight className="size-4" />
-              </ToggleGroupItem>
+            <ToggleGroup variant="outline" spacing={0}>
+              <ToggleGroupItem value="single1">Option 1</ToggleGroupItem>
+              <ToggleGroupItem value="single2">Option 2</ToggleGroupItem>
+              <ToggleGroupItem value="single3">Option 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
-
-          <div>
-            <p className="text-sm text-muted-foreground mb-2">
-              Multiple selection (checkbox-like behavior)
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">
+              Multiple (type="multiple")
             </p>
-            <ToggleGroup
-              type="multiple"
-              variant="outline"
-              defaultValue={["bold", "italic"]}
-            >
-              <ToggleGroupItem value="bold" aria-label="Toggle bold">
-                <Bold className="size-4" />
-              </ToggleGroupItem>
-              <ToggleGroupItem value="italic" aria-label="Toggle italic">
-                <Italic className="size-4" />
-              </ToggleGroupItem>
-              <ToggleGroupItem value="underline" aria-label="Toggle underline">
-                <Underline className="size-4" />
-              </ToggleGroupItem>
+            <ToggleGroup variant="outline" spacing={0}>
+              <ToggleGroupItem value="multi1">Option 1</ToggleGroupItem>
+              <ToggleGroupItem value="multi2">Option 2</ToggleGroupItem>
+              <ToggleGroupItem value="multi3">Option 3</ToggleGroupItem>
             </ToggleGroup>
           </div>
         </div>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Comprehensive showcase of all ToggleGroup variants, sizes, and selection types. This demonstrates the component's flexibility and visual appearance across different configurations.",
-      },
-    },
-  },
-};
+      </section>
 
-/**
- * Real-world usage example showing ToggleGroup in a practical UI context
- */
-export const InContext: Story = {
-  args: {
-    type: "single",
-    variant: "default",
-    size: "default",
-    disabled: false,
-  },
-  render: () => (
-    <div className="w-full max-w-2xl mx-auto p-6 border rounded-lg bg-card">
-      <div className="space-y-6">
+      {/* Icon-Only Toggles */}
+      <section className="space-y-4">
         <div>
-          <h2 className="text-xl font-semibold mb-2">Document Editor</h2>
-          <p className="text-sm text-muted-foreground mb-4">
-            Use the formatting tools below to style your document.
+          <h3 className="text-lg font-semibold">Icon-Only</h3>
+          <p className="text-muted-foreground text-sm">
+            Common pattern for formatting toolbars and view switchers.
           </p>
         </div>
-
-        <div className="space-y-4">
-          <div>
-            <label className="text-sm font-medium mb-2 block">
-              Text Formatting
-            </label>
-            <ToggleGroup
-              type="multiple"
-              variant="outline"
-              className="justify-start"
-            >
-              <ToggleGroupItem value="bold" aria-label="Toggle bold">
-                <Bold className="size-4" />
-                <span className="ml-1">Bold</span>
+        <div className="flex flex-wrap items-center gap-6">
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Text Formatting</p>
+            <ToggleGroup variant="outline" spacing={0}>
+              <ToggleGroupItem value="bold" aria-label="Bold">
+                <BoldIcon />
               </ToggleGroupItem>
-              <ToggleGroupItem value="italic" aria-label="Toggle italic">
-                <Italic className="size-4" />
-                <span className="ml-1">Italic</span>
+              <ToggleGroupItem value="italic" aria-label="Italic">
+                <ItalicIcon />
               </ToggleGroupItem>
-              <ToggleGroupItem value="underline" aria-label="Toggle underline">
-                <Underline className="size-4" />
-                <span className="ml-1">Underline</span>
+              <ToggleGroupItem value="underline" aria-label="Underline">
+                <UnderlineIcon />
               </ToggleGroupItem>
             </ToggleGroup>
           </div>
-
-          <div>
-            <label className="text-sm font-medium mb-2 block">
-              Text Alignment
-            </label>
-            <ToggleGroup
-              type="single"
-              variant="outline"
-              defaultValue="left"
-              className="justify-start"
-            >
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">Text Alignment</p>
+            <ToggleGroup variant="outline" spacing={0}>
               <ToggleGroupItem value="left" aria-label="Align left">
-                <AlignLeft className="size-4" />
+                <AlignLeftIcon />
               </ToggleGroupItem>
               <ToggleGroupItem value="center" aria-label="Align center">
-                <AlignCenter className="size-4" />
+                <AlignCenterIcon />
               </ToggleGroupItem>
               <ToggleGroupItem value="right" aria-label="Align right">
-                <AlignRight className="size-4" />
+                <AlignRightIcon />
               </ToggleGroupItem>
-              <ToggleGroupItem value="justify" aria-label="Justify text">
-                <AlignJustify className="size-4" />
+              <ToggleGroupItem value="justify" aria-label="Justify">
+                <AlignJustifyIcon />
               </ToggleGroupItem>
             </ToggleGroup>
           </div>
-
-          <div>
-            <label className="text-sm font-medium mb-2 block">
-              Document Status
-            </label>
-            <ToggleGroup
-              type="single"
-              variant="default"
-              defaultValue="draft"
-              className="justify-start"
-            >
-              <ToggleGroupItem value="draft">Draft</ToggleGroupItem>
-              <ToggleGroupItem value="review">In Review</ToggleGroupItem>
-              <ToggleGroupItem value="published">Published</ToggleGroupItem>
+          <div className="space-y-2">
+            <p className="text-muted-foreground text-sm">View Mode</p>
+            <ToggleGroup variant="outline" spacing={0}>
+              <ToggleGroupItem value="grid" aria-label="Grid view">
+                <GridIcon />
+              </ToggleGroupItem>
+              <ToggleGroupItem value="list" aria-label="List view">
+                <ListIcon />
+              </ToggleGroupItem>
+              <ToggleGroupItem value="calendar" aria-label="Calendar view">
+                <CalendarIcon />
+              </ToggleGroupItem>
             </ToggleGroup>
           </div>
         </div>
+      </section>
 
-        <div className="pt-4 border-t">
-          <div className="h-32 bg-muted/30 rounded border-2 border-dashed border-muted-foreground/20 flex items-center justify-center">
-            <p className="text-sm text-muted-foreground">
-              Document content area
-            </p>
-          </div>
+      {/* Variant × Size Matrix */}
+      <section className="space-y-4">
+        <div>
+          <h3 className="text-lg font-semibold">Variant × Size Matrix</h3>
+          <p className="text-muted-foreground text-sm">
+            Complete combination reference for design system.
+          </p>
+        </div>
+        <div className="overflow-x-auto">
+          <table className="w-full border-collapse">
+            <thead>
+              <tr className="text-muted-foreground border-b text-left text-sm">
+                <th className="pb-3 pr-4 font-medium">Variant</th>
+                <th className="pb-3 pr-4 font-medium">Small</th>
+                <th className="pb-3 pr-4 font-medium">Default</th>
+                <th className="pb-3 pr-4 font-medium">Large</th>
+              </tr>
+            </thead>
+            <tbody className="align-middle">
+              {(["default", "outline"] as const).map((variant) => (
+                <tr key={variant} className="border-b last:border-0">
+                  <td className="py-3 pr-4 font-mono text-sm capitalize">
+                    {variant}
+                  </td>
+                  <td className="py-3 pr-4">
+                    <ToggleGroup variant={variant} size="sm" spacing={0}>
+                      <ToggleGroupItem value="1">One</ToggleGroupItem>
+                      <ToggleGroupItem value="2">Two</ToggleGroupItem>
+                      <ToggleGroupItem value="3">Three</ToggleGroupItem>
+                    </ToggleGroup>
+                  </td>
+                  <td className="py-3 pr-4">
+                    <ToggleGroup variant={variant} size="default" spacing={0}>
+                      <ToggleGroupItem value="1">One</ToggleGroupItem>
+                      <ToggleGroupItem value="2">Two</ToggleGroupItem>
+                      <ToggleGroupItem value="3">Three</ToggleGroupItem>
+                    </ToggleGroup>
+                  </td>
+                  <td className="py-3 pr-4">
+                    <ToggleGroup variant={variant} size="lg" spacing={0}>
+                      <ToggleGroupItem value="1">One</ToggleGroupItem>
+                      <ToggleGroupItem value="2">Two</ToggleGroupItem>
+                      <ToggleGroupItem value="3">Three</ToggleGroupItem>
+                    </ToggleGroup>
+                  </td>
+                </tr>
+              ))}
+            </tbody>
+          </table>
         </div>
-      </div>
+      </section>
     </div>
   ),
-  parameters: {
-    layout: "padded",
-    docs: {
-      description: {
-        story:
-          "Real-world example showing ToggleGroup components in a document editor interface. This demonstrates how toggle groups work together to provide intuitive formatting controls for users.",
-      },
-    },
+};
+
+/**
+ * Interactive playground for testing toggle group props.
+ */
+export const Interactive: Story = {
+  args: {
+    variant: "outline",
+    size: "default",
+    spacing: 0,
+    orientation: "horizontal",
   },
+  render: (args) => (
+    <ToggleGroup {...args}>
+      <ToggleGroupItem value="option1">Option 1</ToggleGroupItem>
+      <ToggleGroupItem value="option2">Option 2</ToggleGroupItem>
+      <ToggleGroupItem value="option3">Option 3</ToggleGroupItem>
+    </ToggleGroup>
+  ),
 };