aural-ui 4.0.1 → 4.2.0

package/dist/components/dropdown/Dropdown.stories.tsx

@@ -1,29 +1,31 @@
 import React, { useState } from "react"
 import { Button } from "@components/button"
-import { IconButton } from "@components/icon-button"
 import {
-  AlertIcon,
   AngleDownIcon,
-  ArrowRightIcon,
   AudioBarIcon,
   ChevronDownIcon,
-  CrossIcon,
+  CircleTickIcon,
+  DownloadIcon,
   EditBigIcon,
-  EyeCloseIcon,
   EyeOpenIcon,
-  FileChartIcon,
-  ImageIcon,
+  FileTextIcon,
+  HeartIcon,
+  MaintenanceIcon,
+  MusicalNoteIcon,
   PlusIcon,
   SearchIcon,
-  SiteLogoIcon,
+  ShareIcon,
+  StarIcon,
   TickIcon,
   TrashIcon,
   UploadIcon,
+  VerticalMenuIcon,
 } from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
-  DropdownArrow,
   DropdownMenu,
   DropdownMenuCheckboxItem,
   DropdownMenuContent,
@@ -45,86 +47,29 @@ const meta: Meta<typeof DropdownMenu> = {
   component: DropdownMenu,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Dropdown Menu Component
-
-A comprehensive dropdown menu component system built on Radix UI with dark theme optimization and frosted glass effects.
-
-## Features
-
-- **Dark Theme Optimized**: Frosted glass background with gradient borders
-- **Flexible Content**: Support for items, labels, separators, checkboxes, and radio groups
-- **Nested Menus**: Sub-menu support with hover triggers
-- **Icon Integration**: Built-in icon support with proper sizing and theming
-- **Keyboard Navigation**: Full accessibility with arrow keys and shortcuts
-- **Custom Styling**: Granular control via \`classes\` prop
-- **Smooth Animations**: Direction-aware entrance/exit animations
-- **Portal Rendering**: Proper z-index layering and positioning
-- **Logical Grouping**: Use \`DropdownMenuGroup\` for semantic organization
-
-## Component Structure
-
-- **DropdownMenu**: Root container managing state
-- **DropdownMenuTrigger**: Interactive element that opens the menu
-- **DropdownMenuContent**: The floating menu panel with frosted glass effect
-- **DropdownMenuItem**: Standard menu item with optional variants
-- **DropdownMenuGroup**: Groups related menu items together
-- **DropdownMenuLabel**: Section headers and labels
-- **DropdownMenuSeparator**: Visual dividers between sections
-- **DropdownMenuCheckboxItem**: Checkable items with indicators
-- **DropdownMenuRadioGroup/RadioItem**: Radio button groups
-- **DropdownMenuSub/SubTrigger/SubContent**: Nested sub-menus
-- **DropdownMenuShortcut**: Keyboard shortcut display
-
-## Usage Examples
-
-### Basic Menu with Groups
-\`\`\`tsx
-<DropdownMenu>
-  <DropdownMenuTrigger asChild>
-    <Button>Open Menu</Button>
-  </DropdownMenuTrigger>
-  <DropdownMenuContent>
-    <DropdownMenuGroup>
-      <DropdownMenuItem>Edit</DropdownMenuItem>
-      <DropdownMenuItem>Copy</DropdownMenuItem>
-    </DropdownMenuGroup>
-    <DropdownMenuSeparator />
-    <DropdownMenuGroup>
-      <DropdownMenuItem variant="destructive">Delete</DropdownMenuItem>
-    </DropdownMenuGroup>
-  </DropdownMenuContent>
-</DropdownMenu>
-\`\`\`
-
-### With Custom Styling
-\`\`\`tsx
-<DropdownMenuContent 
-  classes={{
-    root: "bg-blue-900/20",
-    border: "bg-gradient-to-r from-blue-500 to-purple-500"
-  }}
->
-  <DropdownMenuItem 
-    classes={{
-      root: "text-blue-400 hover:bg-blue-500/20"
-    }}
-  >
-    Custom Item
-  </DropdownMenuItem>
-</DropdownMenuContent>
-\`\`\`
-        `,
+        component:
+          "A comprehensive dropdown menu system built on Radix UI with a frosted-glass aesthetic and gradient top border. Supports standard items, checkboxes, radio groups, nested sub-menus, separators, keyboard shortcuts, and a destructive variant. All item types accept a `classes` prop for granular style overrides. Animations are direction-aware and the menu renders into a portal for correct z-index layering.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Rich Item Types",
+              description: "Checkbox, radio, sub-menu",
+            },
+            {
+              title: "Keyboard Shortcuts",
+              description: "Shortcut slot per item",
+            },
+            {
+              title: "Destructive Variant",
+              description: "Red danger action style",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -133,678 +78,497 @@ A comprehensive dropdown menu component system built on Radix UI with dark theme
 export default meta
 type Story = StoryObj<typeof DropdownMenu>
 
-// 1. Basic Dropdown Examples
-export const BasicDropdown: Story = {
+// ─── Configurations ───────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   render: () => (
     <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Basic Dropdown Menus
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Simple dropdown menus with different trigger styles and grouped
-          content
-        </p>
-      </div>
-
-      <div className="flex flex-wrap items-start justify-center gap-4">
-        {/* Basic Button Trigger */}
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="outline" className="gap-2">
-              <SiteLogoIcon className="h-4 w-4" />
-              Options
-              <ChevronDownIcon className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <EditBigIcon className="h-4 w-4" />
-                Edit
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <TickIcon className="h-4 w-4" />
-                Copy
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem variant="destructive">
-                <TrashIcon className="h-4 w-4" />
-                Delete
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-
-        {/* Icon Button Trigger */}
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <IconButton variant="ghost" icon={<AlertIcon />} label="" />
-          </DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <ArrowRightIcon className="h-4 w-4" />
-                Share
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <TickIcon className="h-4 w-4" />
-                Favorite
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <TickIcon className="h-4 w-4" />
-                Copy Link
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-
-        {/* User Menu */}
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="text" className="gap-2">
-              <SiteLogoIcon className="h-4 w-4" />
-              Account
-              <ChevronDownIcon className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent align="end">
-            <DropdownMenuLabel>My Account</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <SiteLogoIcon className="h-4 w-4" />
-                Profile
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <SiteLogoIcon className="h-4 w-4" />
-                Settings
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem variant="destructive">
-                <CrossIcon className="h-4 w-4" />
-                Log out
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Basic dropdown menu examples with different trigger styles and grouped content using DropdownMenuGroup.",
-      },
-    },
-  },
-}
-
-// 2. Interactive States
-export const InteractiveStates: Story = {
-  render: () => {
-    const [notifications, setNotifications] = useState(true)
-    const [marketing, setMarketing] = useState(false)
-    const [theme, setTheme] = useState("dark")
-
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            Interactive States
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Checkboxes, radio groups, and stateful interactions with logical
-            grouping
-          </p>
-        </div>
-
+      {/* Basic item */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Basic Items
+        </h4>
         <div className="flex flex-wrap justify-center gap-4">
-          {/* Checkbox Menu */}
           <DropdownMenu>
             <DropdownMenuTrigger asChild>
-              <Button variant="outline" className="gap-2">
-                <AlertIcon className="h-4 w-4" />
-                Notifications
-                <ChevronDownIcon className="h-4 w-4" />
+              <Button
+                variant="outline"
+                innerClassName="flex items-center gap-2"
+              >
+                Options
+                <ChevronDownIcon className="size-4" />
               </Button>
             </DropdownMenuTrigger>
             <DropdownMenuContent>
-              <DropdownMenuLabel>Email Preferences</DropdownMenuLabel>
+              <DropdownMenuGroup>
+                <DropdownMenuItem>
+                  <EditBigIcon />
+                  Edit
+                </DropdownMenuItem>
+                <DropdownMenuItem>
+                  <TickIcon />
+                  Duplicate
+                </DropdownMenuItem>
+                <DropdownMenuItem>
+                  <ShareIcon />
+                  Share
+                  <DropdownMenuShortcut>⌘⇧S</DropdownMenuShortcut>
+                </DropdownMenuItem>
+              </DropdownMenuGroup>
               <DropdownMenuSeparator />
               <DropdownMenuGroup>
-                <DropdownMenuCheckboxItem
-                  checked={notifications}
-                  onCheckedChange={setNotifications}
-                >
-                  System Notifications
-                </DropdownMenuCheckboxItem>
-                <DropdownMenuCheckboxItem
-                  checked={marketing}
-                  onCheckedChange={setMarketing}
-                >
-                  Marketing Emails
-                </DropdownMenuCheckboxItem>
+                <DropdownMenuItem variant="destructive">
+                  <TrashIcon />
+                  Delete
+                  <DropdownMenuShortcut>⌘⌫</DropdownMenuShortcut>
+                </DropdownMenuItem>
               </DropdownMenuGroup>
             </DropdownMenuContent>
           </DropdownMenu>
+        </div>
+      </div>
 
-          {/* Radio Group Menu */}
+      {/* Inset items */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Inset Items
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
           <DropdownMenu>
             <DropdownMenuTrigger asChild>
-              <Button variant="outline" className="gap-2">
-                Theme: {theme}
-                <ChevronDownIcon className="h-4 w-4" />
+              <Button
+                variant="outline"
+                innerClassName="flex items-center gap-2"
+              >
+                With Inset
+                <ChevronDownIcon className="size-4" />
               </Button>
             </DropdownMenuTrigger>
-            <DropdownMenuContent>
-              <DropdownMenuLabel>Appearance</DropdownMenuLabel>
+            <DropdownMenuContent className="w-48">
+              <DropdownMenuLabel>Account</DropdownMenuLabel>
               <DropdownMenuSeparator />
               <DropdownMenuGroup>
-                <DropdownMenuRadioGroup value={theme} onValueChange={setTheme}>
-                  <DropdownMenuRadioItem value="light">
-                    Light
-                  </DropdownMenuRadioItem>
-                  <DropdownMenuRadioItem value="dark">
-                    Dark
-                  </DropdownMenuRadioItem>
-                  <DropdownMenuRadioItem value="system">
-                    System
-                  </DropdownMenuRadioItem>
-                </DropdownMenuRadioGroup>
+                <DropdownMenuItem inset>Profile</DropdownMenuItem>
+                <DropdownMenuItem inset>Settings</DropdownMenuItem>
+                <DropdownMenuItem inset>Billing</DropdownMenuItem>
+              </DropdownMenuGroup>
+              <DropdownMenuSeparator />
+              <DropdownMenuGroup>
+                <DropdownMenuItem inset variant="destructive">
+                  Log out
+                </DropdownMenuItem>
               </DropdownMenuGroup>
             </DropdownMenuContent>
           </DropdownMenu>
         </div>
-
-        {/* State Display */}
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary inline-block rounded-lg border p-4">
-            <h4 className="text-fm-primary mb-2 text-sm font-medium">
-              Current State
-            </h4>
-            <div className="text-fm-secondary space-y-1 text-xs">
-              <div>Notifications: {notifications ? "On" : "Off"}</div>
-              <div>Marketing: {marketing ? "On" : "Off"}</div>
-              <div>Theme: {theme}</div>
-            </div>
-          </div>
-        </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Interactive dropdown menus with checkboxes, radio groups, and state management using proper grouping.",
-      },
-    },
-  },
-}
-
-// 3. Nested Sub-menus
-export const NestedMenus: Story = {
-  render: () => (
-    <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">Nested Sub-menus</h3>
-        <p className="text-fm-secondary text-sm">
-          Multi-level menus with sub-menu navigation and logical grouping
-        </p>
-      </div>
-
-      <div className="flex justify-center">
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="outline" className="gap-2">
-              <PlusIcon className="h-4 w-4" />
-              Create New
-              <ChevronDownIcon className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent>
-            <DropdownMenuLabel>Create</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-
-            <DropdownMenuGroup>
-              <DropdownMenuSub>
-                <DropdownMenuSubTrigger>
-                  <FileChartIcon className="h-4 w-4" />
-                  Folder
-                </DropdownMenuSubTrigger>
-                <DropdownMenuSubContent>
-                  <DropdownMenuGroup>
-                    <DropdownMenuItem>
-                      <FileChartIcon className="h-4 w-4" />
-                      Project Folder
-                    </DropdownMenuItem>
-                    <DropdownMenuItem>
-                      <FileChartIcon className="h-4 w-4" />
-                      Asset Folder
-                    </DropdownMenuItem>
-                    <DropdownMenuItem>
-                      <FileChartIcon className="h-4 w-4" />
-                      Template Folder
-                    </DropdownMenuItem>
-                  </DropdownMenuGroup>
-                </DropdownMenuSubContent>
-              </DropdownMenuSub>
-
-              <DropdownMenuSub>
-                <DropdownMenuSubTrigger>
-                  <FileChartIcon className="h-4 w-4" />
-                  Document
-                </DropdownMenuSubTrigger>
-                <DropdownMenuSubContent>
-                  <DropdownMenuGroup>
-                    <DropdownMenuItem>
-                      <FileChartIcon className="h-4 w-4" />
-                      Text Document
-                    </DropdownMenuItem>
-                    <DropdownMenuItem>
-                      <FileChartIcon className="h-4 w-4" />
-                      Spreadsheet
-                    </DropdownMenuItem>
-                    <DropdownMenuItem>
-                      <FileChartIcon className="h-4 w-4" />
-                      Presentation
-                    </DropdownMenuItem>
-                  </DropdownMenuGroup>
-                  <DropdownMenuSeparator />
-                  <DropdownMenuGroup>
-                    <DropdownMenuItem>
-                      <ImageIcon className="h-4 w-4" />
-                      From Template
-                    </DropdownMenuItem>
-                  </DropdownMenuGroup>
-                </DropdownMenuSubContent>
-              </DropdownMenuSub>
-            </DropdownMenuGroup>
-
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <UploadIcon className="h-4 w-4" />
-                Upload File
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Nested dropdown menus with sub-menu triggers and multi-level navigation using DropdownMenuGroup for organization.",
-      },
-    },
-  },
-}
-
-// 4. Keyboard Shortcuts
-export const KeyboardShortcuts: Story = {
-  render: () => (
-    <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">Keyboard Shortcuts</h3>
-        <p className="text-fm-secondary text-sm">
-          Menu items with keyboard shortcut indicators and logical grouping
-        </p>
-      </div>
-
-      <div className="flex justify-center">
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="outline" className="gap-2">
-              <EditBigIcon className="h-4 w-4" />
-              Edit Menu
-              <ChevronDownIcon className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent className="w-56">
-            <DropdownMenuLabel>Edit</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <EditBigIcon className="h-4 w-4" />
-                Undo
-                <DropdownMenuShortcut>⌘Z</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <EditBigIcon className="h-4 w-4" />
-                Redo
-                <DropdownMenuShortcut>⌘⇧Z</DropdownMenuShortcut>
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-
-            <DropdownMenuSeparator />
-
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <TickIcon className="h-4 w-4" />
-                Cut
-                <DropdownMenuShortcut>⌘X</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <TickIcon className="h-4 w-4" />
-                Copy
-                <DropdownMenuShortcut>⌘C</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <TickIcon className="h-4 w-4" />
-                Paste
-                <DropdownMenuShortcut>⌘V</DropdownMenuShortcut>
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-
-            <DropdownMenuSeparator />
-
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                Select All
-                <DropdownMenuShortcut>⌘A</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <SearchIcon className="h-4 w-4" />
-                Find
-                <DropdownMenuShortcut>⌘F</DropdownMenuShortcut>
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Dropdown menu with keyboard shortcut indicators for common actions, organized with DropdownMenuGroup.",
-      },
-    },
-  },
-}
-
-// 5. Custom Styling
-export const CustomStyling: Story = {
-  render: () => (
-    <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">Custom Styling</h3>
-        <p className="text-fm-secondary text-sm">
-          Dropdown menus with custom styling using the classes prop
-        </p>
-      </div>
-
-      <div className="flex flex-wrap justify-center gap-4">
-        {/* Blue Theme */}
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button>Blue Theme</Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent
-            classes={{
-              root: "bg-blue-900/40 border-blue-500/20",
-              border: "bg-gradient-to-r from-blue-500 to-cyan-500",
-            }}
-          >
-            <DropdownMenuGroup>
-              <DropdownMenuItem
-                classes={{
-                  root: "text-blue-200 hover:bg-blue-500/20 focus:bg-blue-500/20",
-                }}
-              >
-                <TickIcon className="h-4 w-4" />
-                Blue Item
-              </DropdownMenuItem>
-              <DropdownMenuItem
-                classes={{
-                  root: "text-blue-200 hover:bg-blue-500/20 focus:bg-blue-500/20",
-                }}
-              >
-                <AudioBarIcon className="h-4 w-4" />
-                Another Item
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-
-        {/* Green Theme */}
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button>Green Theme</Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent
-            classes={{
-              root: "bg-green-900/40 border-green-500/20",
-              border: "bg-gradient-to-r from-green-500 to-emerald-500",
-            }}
-          >
-            <DropdownMenuGroup>
-              <DropdownMenuItem
-                classes={{
-                  root: "text-green-200 hover:bg-green-500/20 focus:bg-green-500/20",
-                }}
-              >
-                <TickIcon className="h-4 w-4" />
-                Green Item
-              </DropdownMenuItem>
-              <DropdownMenuItem
-                classes={{
-                  root: "text-green-200 hover:bg-green-500/20 focus:bg-green-500/20",
-                }}
-              >
-                <AudioBarIcon className="h-4 w-4" />
-                Success Action
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-
-        {/* Purple Theme */}
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button>Purple Theme</Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent
-            classes={{
-              root: "bg-purple-900/40 border-purple-500/20",
-              border: "bg-gradient-to-r from-purple-500 to-pink-500",
-            }}
-          >
-            <DropdownMenuGroup>
-              <DropdownMenuItem
-                classes={{
-                  root: "text-purple-200 hover:bg-purple-500/20 focus:bg-purple-500/20",
-                }}
-              >
-                <TickIcon className="h-4 w-4" />
-                Purple Item
-              </DropdownMenuItem>
-              <DropdownMenuItem
-                classes={{
-                  root: "text-purple-200 hover:bg-purple-500/20 focus:bg-purple-500/20",
-                }}
-              >
-                <AudioBarIcon className="h-4 w-4" />
-                Creative Action
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Custom styled dropdown menus using the classes prop for theme variations with logical grouping.",
-      },
-    },
-  },
-}
-
-// 6. Complex Menu Example
-export const ComplexMenu: Story = {
-  render: () => {
-    const [bookmarked, setBookmarked] = useState(false)
-    const [notifications, setNotifications] = useState(true)
-    const [viewMode, setViewMode] = useState("grid")
 
-    return (
-      <div className="space-y-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">Complex Menu</h3>
-          <p className="text-fm-secondary text-sm">
-            Full-featured dropdown menu with all component types and logical
-            grouping
-          </p>
-        </div>
-
-        <div className="flex justify-center">
+      {/* Group + separator */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Groups &amp; Separators
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
           <DropdownMenu>
             <DropdownMenuTrigger asChild>
-              <Button variant="outline" className="gap-2">
-                <AlertIcon className="h-4 w-4" />
-                More Actions
-                <ChevronDownIcon className="h-4 w-4" />
+              <Button
+                variant="outline"
+                innerClassName="flex items-center gap-2"
+              >
+                Grouped
+                <ChevronDownIcon className="size-4" />
               </Button>
             </DropdownMenuTrigger>
-            <DropdownMenuContent className="w-64">
-              {/* Basic Actions Group */}
-              <DropdownMenuLabel>Quick Actions</DropdownMenuLabel>
+            <DropdownMenuContent className="w-52">
+              <DropdownMenuLabel>File</DropdownMenuLabel>
               <DropdownMenuSeparator />
               <DropdownMenuGroup>
                 <DropdownMenuItem>
-                  <EditBigIcon className="h-4 w-4" />
-                  Edit Item
-                  <DropdownMenuShortcut>⌘E</DropdownMenuShortcut>
+                  <FileTextIcon />
+                  New
+                  <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
                 </DropdownMenuItem>
                 <DropdownMenuItem>
-                  <TickIcon className="h-4 w-4" />
-                  Duplicate
-                  <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
+                  <UploadIcon />
+                  Upload
+                  <DropdownMenuShortcut>⌘U</DropdownMenuShortcut>
                 </DropdownMenuItem>
+              </DropdownMenuGroup>
+              <DropdownMenuSeparator />
+              <DropdownMenuLabel>Edit</DropdownMenuLabel>
+              <DropdownMenuSeparator />
+              <DropdownMenuGroup>
                 <DropdownMenuItem>
-                  <ArrowRightIcon className="h-4 w-4" />
-                  Share
-                  <DropdownMenuShortcut>⌘⇧S</DropdownMenuShortcut>
+                  <EditBigIcon />
+                  Rename
+                  <DropdownMenuShortcut>⌘R</DropdownMenuShortcut>
+                </DropdownMenuItem>
+                <DropdownMenuItem>
+                  <DownloadIcon />
+                  Download
+                  <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
                 </DropdownMenuItem>
               </DropdownMenuGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+      </div>
 
-              <DropdownMenuSeparator />
-
-              {/* Options Group */}
-              <DropdownMenuLabel>Options</DropdownMenuLabel>
+      {/* Checkbox items */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Checkbox Items
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                variant="outline"
+                innerClassName="flex items-center gap-2"
+              >
+                Preferences
+                <ChevronDownIcon className="size-4" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuLabel>Display</DropdownMenuLabel>
               <DropdownMenuSeparator />
               <DropdownMenuGroup>
-                <DropdownMenuCheckboxItem
-                  checked={bookmarked}
-                  onCheckedChange={setBookmarked}
-                >
-                  <TickIcon className="h-4 w-4" />
-                  Bookmark
+                <DropdownMenuCheckboxItem checked>
+                  Show artwork
                 </DropdownMenuCheckboxItem>
-                <DropdownMenuCheckboxItem
-                  checked={notifications}
-                  onCheckedChange={setNotifications}
-                >
-                  <AlertIcon className="h-4 w-4" />
-                  Enable Notifications
+                <DropdownMenuCheckboxItem checked={false}>
+                  Show lyrics
+                </DropdownMenuCheckboxItem>
+                <DropdownMenuCheckboxItem checked>
+                  Show queue
                 </DropdownMenuCheckboxItem>
               </DropdownMenuGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+      </div>
 
-              <DropdownMenuSeparator />
-
-              {/* View Mode Group */}
-              <DropdownMenuLabel>View Mode</DropdownMenuLabel>
+      {/* Radio items */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Radio Items
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                variant="outline"
+                innerClassName="flex items-center gap-2"
+              >
+                Sort by
+                <AngleDownIcon className="size-4" />
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
+              <DropdownMenuLabel>Sort Order</DropdownMenuLabel>
               <DropdownMenuSeparator />
               <DropdownMenuGroup>
-                <DropdownMenuRadioGroup
-                  value={viewMode}
-                  onValueChange={setViewMode}
-                >
-                  <DropdownMenuRadioItem value="grid">
-                    Grid View
+                <DropdownMenuRadioGroup value="recent">
+                  <DropdownMenuRadioItem value="recent">
+                    Most Recent
                   </DropdownMenuRadioItem>
-                  <DropdownMenuRadioItem value="list">
-                    List View
+                  <DropdownMenuRadioItem value="alpha">
+                    Alphabetical
                   </DropdownMenuRadioItem>
-                  <DropdownMenuRadioItem value="card">
-                    Card View
+                  <DropdownMenuRadioItem value="plays">
+                    Most Played
                   </DropdownMenuRadioItem>
                 </DropdownMenuRadioGroup>
               </DropdownMenuGroup>
+            </DropdownMenuContent>
+          </DropdownMenu>
+        </div>
+      </div>
 
-              <DropdownMenuSeparator />
-
-              {/* Collections Group */}
+      {/* Sub-menus */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Nested Sub-menu
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          <DropdownMenu>
+            <DropdownMenuTrigger asChild>
+              <Button
+                variant="outline"
+                innerClassName="flex items-center gap-2"
+              >
+                <PlusIcon className="size-4" />
+                Add to…
+              </Button>
+            </DropdownMenuTrigger>
+            <DropdownMenuContent>
               <DropdownMenuGroup>
                 <DropdownMenuSub>
                   <DropdownMenuSubTrigger>
-                    <PlusIcon className="h-4 w-4" />
-                    Add to Collection
+                    <AudioBarIcon />
+                    Playlist
                   </DropdownMenuSubTrigger>
                   <DropdownMenuSubContent>
                     <DropdownMenuGroup>
                       <DropdownMenuItem>
-                        <FileChartIcon className="h-4 w-4" />
-                        Favorites
+                        <MusicalNoteIcon />
+                        Late Night Drive
                       </DropdownMenuItem>
                       <DropdownMenuItem>
-                        <FileChartIcon className="h-4 w-4" />
-                        Work Projects
+                        <MusicalNoteIcon />
+                        Focus Mode
                       </DropdownMenuItem>
                       <DropdownMenuItem>
-                        <FileChartIcon className="h-4 w-4" />
-                        Personal
+                        <MusicalNoteIcon />
+                        Morning Energy
                       </DropdownMenuItem>
                     </DropdownMenuGroup>
                     <DropdownMenuSeparator />
                     <DropdownMenuGroup>
                       <DropdownMenuItem>
-                        <PlusIcon className="h-4 w-4" />
-                        Create New Collection
+                        <PlusIcon />
+                        New Playlist…
                       </DropdownMenuItem>
                     </DropdownMenuGroup>
                   </DropdownMenuSubContent>
                 </DropdownMenuSub>
-              </DropdownMenuGroup>
-
-              <DropdownMenuSeparator />
-
-              {/* Danger Group */}
-              <DropdownMenuGroup>
-                <DropdownMenuItem variant="destructive">
-                  <TrashIcon className="h-4 w-4" />
-                  Delete Item
-                  <DropdownMenuShortcut>⌘⌫</DropdownMenuShortcut>
+                <DropdownMenuItem>
+                  <AudioBarIcon />
+                  Queue
+                  <DropdownMenuShortcut>⌘Q</DropdownMenuShortcut>
                 </DropdownMenuItem>
               </DropdownMenuGroup>
             </DropdownMenuContent>
           </DropdownMenu>
         </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "All item type configurations displayed in separate labeled groups: basic items with keyboard shortcuts, inset items, group+separator layouts, checkbox items, radio items, and a nested sub-menu trigger. Each section can be opened independently to inspect how that item type renders.",
+      },
+    },
+  },
+}
+
+// ─── Interactive ──────────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
+  render: () => {
+    const [showArtwork, setShowArtwork] = useState(true)
+    const [showLyrics, setShowLyrics] = useState(false)
+    const [showQueue, setShowQueue] = useState(true)
+    const [audioQuality, setAudioQuality] = useState("high")
+    const [sortOrder, setSortOrder] = useState("recent")
+    const [lastAction, setLastAction] = useState<string | null>(null)
+
+    const qualityLabels: Record<string, string> = {
+      low: "Normal (96 kbps)",
+      high: "High (320 kbps)",
+      lossless: "Lossless (FLAC)",
+    }
+    const sortLabels: Record<string, string> = {
+      recent: "Most Recent",
+      alpha: "Alphabetical",
+      plays: "Most Played",
+    }
+
+    return (
+      <div className="w-full p-8">
+        <div className="mx-auto max-w-3xl space-y-6">
+          <div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+            {/* Controls panel */}
+            <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-5 rounded-xl border p-5">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Live State
+              </p>
+
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Display Toggles
+                </p>
+                <div className="space-y-1">
+                  {[
+                    { label: "Artwork", value: showArtwork },
+                    { label: "Lyrics", value: showLyrics },
+                    { label: "Queue", value: showQueue },
+                  ].map(({ label, value }) => (
+                    <div key={label} className="flex justify-between">
+                      <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                        {label}
+                      </span>
+                      <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                        {value ? "On" : "Off"}
+                      </span>
+                    </div>
+                  ))}
+                </div>
+              </div>
+
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-1">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Audio Quality
+                </p>
+                <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-medium">
+                  {qualityLabels[audioQuality]}
+                </p>
+              </div>
+
+              <div className="space-y-1">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Sort Order
+                </p>
+                <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-medium">
+                  {sortLabels[sortOrder]}
+                </p>
+              </div>
+
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-1">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Last Action
+                </p>
+                <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md truncate font-medium">
+                  {lastAction ?? "—"}
+                </p>
+              </div>
+            </div>
 
-        {/* State Display */}
-        <div className="text-center">
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary inline-block rounded-lg border p-4">
-            <h4 className="text-fm-primary mb-2 text-sm font-medium">
-              Current Settings
-            </h4>
-            <div className="text-fm-secondary space-y-1 text-xs">
-              <div>Bookmarked: {bookmarked ? "Yes" : "No"}</div>
-              <div>Notifications: {notifications ? "Enabled" : "Disabled"}</div>
-              <div>View Mode: {viewMode}</div>
+            {/* Preview stage */}
+            <div className="flex flex-col gap-4 lg:col-span-2">
+              <div className="flex flex-wrap justify-center gap-4">
+                {/* Checkbox preferences */}
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      variant="outline"
+                      innerClassName="flex items-center gap-2"
+                    >
+                      Display
+                      <ChevronDownIcon className="size-4" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent>
+                    <DropdownMenuLabel>Display Options</DropdownMenuLabel>
+                    <DropdownMenuSeparator />
+                    <DropdownMenuGroup>
+                      <DropdownMenuCheckboxItem
+                        checked={showArtwork}
+                        onCheckedChange={(v) => {
+                          setShowArtwork(v)
+                          setLastAction(`Show Artwork → ${v ? "On" : "Off"}`)
+                        }}
+                      >
+                        Show Artwork
+                      </DropdownMenuCheckboxItem>
+                      <DropdownMenuCheckboxItem
+                        checked={showLyrics}
+                        onCheckedChange={(v) => {
+                          setShowLyrics(v)
+                          setLastAction(`Show Lyrics → ${v ? "On" : "Off"}`)
+                        }}
+                      >
+                        Show Lyrics
+                      </DropdownMenuCheckboxItem>
+                      <DropdownMenuCheckboxItem
+                        checked={showQueue}
+                        onCheckedChange={(v) => {
+                          setShowQueue(v)
+                          setLastAction(`Show Queue → ${v ? "On" : "Off"}`)
+                        }}
+                      >
+                        Show Queue
+                      </DropdownMenuCheckboxItem>
+                    </DropdownMenuGroup>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+
+                {/* Radio — audio quality */}
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      variant="outline"
+                      innerClassName="flex items-center gap-2"
+                    >
+                      Quality: {qualityLabels[audioQuality].split(" ")[0]}
+                      <AngleDownIcon className="size-4" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent>
+                    <DropdownMenuLabel>Audio Quality</DropdownMenuLabel>
+                    <DropdownMenuSeparator />
+                    <DropdownMenuGroup>
+                      <DropdownMenuRadioGroup
+                        value={audioQuality}
+                        onValueChange={(v) => {
+                          setAudioQuality(v)
+                          setLastAction(`Quality → ${qualityLabels[v]}`)
+                        }}
+                      >
+                        <DropdownMenuRadioItem value="low">
+                          Normal (96 kbps)
+                        </DropdownMenuRadioItem>
+                        <DropdownMenuRadioItem value="high">
+                          High (320 kbps)
+                        </DropdownMenuRadioItem>
+                        <DropdownMenuRadioItem value="lossless">
+                          Lossless (FLAC)
+                        </DropdownMenuRadioItem>
+                      </DropdownMenuRadioGroup>
+                    </DropdownMenuGroup>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+
+                {/* Radio — sort order */}
+                <DropdownMenu>
+                  <DropdownMenuTrigger asChild>
+                    <Button
+                      variant="outline"
+                      innerClassName="flex items-center gap-2"
+                    >
+                      Sort
+                      <AngleDownIcon className="size-4" />
+                    </Button>
+                  </DropdownMenuTrigger>
+                  <DropdownMenuContent>
+                    <DropdownMenuLabel>Sort Library By</DropdownMenuLabel>
+                    <DropdownMenuSeparator />
+                    <DropdownMenuGroup>
+                      <DropdownMenuRadioGroup
+                        value={sortOrder}
+                        onValueChange={(v) => {
+                          setSortOrder(v)
+                          setLastAction(`Sort → ${sortLabels[v]}`)
+                        }}
+                      >
+                        <DropdownMenuRadioItem value="recent">
+                          Most Recent
+                        </DropdownMenuRadioItem>
+                        <DropdownMenuRadioItem value="alpha">
+                          Alphabetical
+                        </DropdownMenuRadioItem>
+                        <DropdownMenuRadioItem value="plays">
+                          Most Played
+                        </DropdownMenuRadioItem>
+                      </DropdownMenuRadioGroup>
+                    </DropdownMenuGroup>
+                  </DropdownMenuContent>
+                </DropdownMenu>
+              </div>
+
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                <code className="text-fm-secondary text-fm-md leading-fm-md font-(--font-fm-mono)">
+                  Checkbox and radio selections update state immediately — open
+                  the left panel to see live values.
+                </code>
+              </div>
             </div>
           </div>
         </div>
@@ -815,405 +579,256 @@ export const ComplexMenu: Story = {
     docs: {
       description: {
         story:
-          "Complex dropdown menu example showcasing all component features with proper logical grouping using DropdownMenuGroup for better organization and accessibility.",
+          "Stateful dropdown story demonstrating live checkbox and radio item selection. Three separate menus manage display toggle preferences, audio quality (radio single-select), and library sort order (radio single-select). The left panel reflects every state change in real time so the interaction loop is visible without opening browser DevTools.",
       },
     },
   },
 }
 
-// 7. Positioning Examples
-export const PositioningExamples: Story = {
-  render: () => (
-    <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Positioning Examples
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different positioning and alignment options with grouped content
-        </p>
-      </div>
+// ─── UseCases ─────────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
+  render: () => {
+    const [liked, setLiked] = useState(false)
 
-      <div className="grid grid-cols-2 gap-8">
-        {/* Top Row */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Alignment Options
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* 1 — Track action menu */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Track Action Menu
           </h4>
-          <div className="flex gap-2">
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary flex items-center justify-between rounded-xl border p-4">
+            <div className="flex items-center gap-3">
+              <div className="bg-fm-surface-tertiary size-10 shrink-0 rounded-lg" />
+              <div className="space-y-0.5">
+                <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-medium">
+                  Midnight Echoes
+                </p>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Luna Vex · 4:12
+                </p>
+              </div>
+            </div>
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  Align Start
+                <Button variant="text" size="sm">
+                  <VerticalMenuIcon />
                 </Button>
               </DropdownMenuTrigger>
-              <DropdownMenuContent align="start">
+              <DropdownMenuContent align="end" className="w-52">
                 <DropdownMenuGroup>
-                  <DropdownMenuItem>Left aligned</DropdownMenuItem>
-                  <DropdownMenuItem>Content</DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <AudioBarIcon />
+                    Add to Queue
+                    <DropdownMenuShortcut>⌘Q</DropdownMenuShortcut>
+                  </DropdownMenuItem>
+                  <DropdownMenuItem onSelect={() => setLiked((v) => !v)}>
+                    <HeartIcon />
+                    {liked ? "Unlike Track" : "Like Track"}
+                    <DropdownMenuShortcut>⌘L</DropdownMenuShortcut>
+                  </DropdownMenuItem>
                 </DropdownMenuGroup>
-              </DropdownMenuContent>
-            </DropdownMenu>
-
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  Align Center
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="center">
+                <DropdownMenuSeparator />
                 <DropdownMenuGroup>
-                  <DropdownMenuItem>Center aligned</DropdownMenuItem>
-                  <DropdownMenuItem>Content</DropdownMenuItem>
+                  <DropdownMenuSub>
+                    <DropdownMenuSubTrigger>
+                      <MusicalNoteIcon />
+                      Add to Playlist
+                    </DropdownMenuSubTrigger>
+                    <DropdownMenuSubContent>
+                      <DropdownMenuGroup>
+                        <DropdownMenuItem>
+                          <CircleTickIcon />
+                          Late Night Drive
+                        </DropdownMenuItem>
+                        <DropdownMenuItem>
+                          <CircleTickIcon />
+                          Focus Mode
+                        </DropdownMenuItem>
+                        <DropdownMenuItem>
+                          <CircleTickIcon />
+                          Morning Energy
+                        </DropdownMenuItem>
+                      </DropdownMenuGroup>
+                      <DropdownMenuSeparator />
+                      <DropdownMenuGroup>
+                        <DropdownMenuItem>
+                          <PlusIcon />
+                          New Playlist…
+                        </DropdownMenuItem>
+                      </DropdownMenuGroup>
+                    </DropdownMenuSubContent>
+                  </DropdownMenuSub>
+                  <DropdownMenuItem>
+                    <ShareIcon />
+                    Share Track
+                    <DropdownMenuShortcut>⌘⇧S</DropdownMenuShortcut>
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <DownloadIcon />
+                    Download Offline
+                    <DropdownMenuShortcut>⌘D</DropdownMenuShortcut>
+                  </DropdownMenuItem>
                 </DropdownMenuGroup>
-              </DropdownMenuContent>
-            </DropdownMenu>
-
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  Align End
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent align="end">
+                <DropdownMenuSeparator />
                 <DropdownMenuGroup>
-                  <DropdownMenuItem>Right aligned</DropdownMenuItem>
-                  <DropdownMenuItem>Content</DropdownMenuItem>
+                  <DropdownMenuItem variant="destructive">
+                    <TrashIcon />
+                    Remove from Library
+                  </DropdownMenuItem>
                 </DropdownMenuGroup>
               </DropdownMenuContent>
             </DropdownMenu>
           </div>
+          {liked && (
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm text-center">
+              Track liked — heart state toggles via the menu above.
+            </p>
+          )}
         </div>
 
-        {/* Bottom Row */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Side Offset</h4>
-          <div className="flex gap-2">
+        {/* 2 — User account menu */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            User Account Menu
+          </h4>
+          <div className="flex justify-center">
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  No Offset
+                <Button
+                  variant="outline"
+                  innerClassName="flex items-center gap-2"
+                >
+                  <div className="bg-fm-surface-tertiary size-6 rounded-full" />
+                  Alex Rivera
+                  <ChevronDownIcon className="size-4" />
                 </Button>
               </DropdownMenuTrigger>
-              <DropdownMenuContent sideOffset={0}>
+              <DropdownMenuContent align="end" className="w-52">
+                <DropdownMenuLabel>My Account</DropdownMenuLabel>
+                <DropdownMenuSeparator />
                 <DropdownMenuGroup>
-                  <DropdownMenuItem>No spacing</DropdownMenuItem>
-                  <DropdownMenuItem>From trigger</DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <EyeOpenIcon />
+                    View Profile
+                    <DropdownMenuShortcut>⌘P</DropdownMenuShortcut>
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <StarIcon />
+                    Subscription
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <MaintenanceIcon />
+                    Settings
+                    <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
+                  </DropdownMenuItem>
                 </DropdownMenuGroup>
-              </DropdownMenuContent>
-            </DropdownMenu>
-
-            <DropdownMenu>
-              <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  Default
-                </Button>
-              </DropdownMenuTrigger>
-              <DropdownMenuContent>
+                <DropdownMenuSeparator />
+                <DropdownMenuGroup>
+                  <DropdownMenuItem>
+                    <SearchIcon />
+                    Help &amp; Support
+                  </DropdownMenuItem>
+                </DropdownMenuGroup>
+                <DropdownMenuSeparator />
                 <DropdownMenuGroup>
-                  <DropdownMenuItem>Default spacing</DropdownMenuItem>
-                  <DropdownMenuItem>4px offset</DropdownMenuItem>
+                  <DropdownMenuItem variant="destructive">
+                    Log Out
+                    <DropdownMenuShortcut>⌘⇧Q</DropdownMenuShortcut>
+                  </DropdownMenuItem>
                 </DropdownMenuGroup>
               </DropdownMenuContent>
             </DropdownMenu>
+          </div>
+        </div>
 
+        {/* 3 — Settings context menu */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Settings Context Menu
+          </h4>
+          <div className="flex justify-center">
             <DropdownMenu>
               <DropdownMenuTrigger asChild>
-                <Button variant="outline" size="sm">
-                  Large Offset
+                <Button
+                  variant="outline"
+                  innerClassName="flex items-center gap-2"
+                >
+                  <MaintenanceIcon className="size-4" />
+                  Settings
+                  <AngleDownIcon className="size-4" />
                 </Button>
               </DropdownMenuTrigger>
-              <DropdownMenuContent sideOffset={12}>
+              <DropdownMenuContent className="w-56">
+                <DropdownMenuLabel>Application</DropdownMenuLabel>
+                <DropdownMenuSeparator />
+                <DropdownMenuGroup>
+                  <DropdownMenuSub>
+                    <DropdownMenuSubTrigger>
+                      <AudioBarIcon />
+                      Audio Settings
+                    </DropdownMenuSubTrigger>
+                    <DropdownMenuSubContent>
+                      <DropdownMenuGroup>
+                        <DropdownMenuItem>
+                          Equaliser
+                          <DropdownMenuShortcut>⌘E</DropdownMenuShortcut>
+                        </DropdownMenuItem>
+                        <DropdownMenuItem>Crossfade</DropdownMenuItem>
+                        <DropdownMenuItem>Normalisation</DropdownMenuItem>
+                      </DropdownMenuGroup>
+                    </DropdownMenuSubContent>
+                  </DropdownMenuSub>
+                  <DropdownMenuSub>
+                    <DropdownMenuSubTrigger>
+                      <MusicalNoteIcon />
+                      Library Settings
+                    </DropdownMenuSubTrigger>
+                    <DropdownMenuSubContent>
+                      <DropdownMenuGroup>
+                        <DropdownMenuItem>
+                          <UploadIcon />
+                          Import Music
+                        </DropdownMenuItem>
+                        <DropdownMenuItem>
+                          <EditBigIcon />
+                          Manage Storage
+                        </DropdownMenuItem>
+                      </DropdownMenuGroup>
+                    </DropdownMenuSubContent>
+                  </DropdownMenuSub>
+                </DropdownMenuGroup>
+                <DropdownMenuSeparator />
                 <DropdownMenuGroup>
-                  <DropdownMenuItem>Large spacing</DropdownMenuItem>
-                  <DropdownMenuItem>12px offset</DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <FileTextIcon />
+                    Privacy Policy
+                  </DropdownMenuItem>
+                  <DropdownMenuItem>
+                    <ShareIcon />
+                    Terms of Service
+                  </DropdownMenuItem>
+                </DropdownMenuGroup>
+                <DropdownMenuSeparator />
+                <DropdownMenuGroup>
+                  <DropdownMenuItem variant="destructive">
+                    <TrashIcon />
+                    Reset All Settings
+                  </DropdownMenuItem>
                 </DropdownMenuGroup>
               </DropdownMenuContent>
             </DropdownMenu>
           </div>
         </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Examples of different positioning options including alignment and offset configurations with proper content grouping.",
-      },
-    },
-  },
-}
-
-// 8. Grouping Showcase
-export const GroupingShowcase: Story = {
-  render: () => (
-    <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          DropdownMenuGroup Showcase
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Demonstrating logical grouping for better organization and
-          accessibility
-        </p>
-      </div>
-
-      <div className="flex justify-center">
-        <DropdownMenu>
-          <DropdownMenuTrigger asChild>
-            <Button variant="outline" className="gap-2">
-              <SiteLogoIcon className="h-4 w-4" />
-              Grouped Menu
-              <AngleDownIcon className="h-4 w-4" />
-            </Button>
-          </DropdownMenuTrigger>
-          <DropdownMenuContent className="w-56">
-            {/* File Operations Group */}
-            <DropdownMenuLabel>File Operations</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <FileChartIcon className="h-4 w-4" />
-                New File
-                <DropdownMenuShortcut>⌘N</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <UploadIcon className="h-4 w-4" />
-                Upload
-                <DropdownMenuShortcut>⌘U</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <ImageIcon className="h-4 w-4" />
-                Import
-                <DropdownMenuShortcut>⌘I</DropdownMenuShortcut>
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-
-            <DropdownMenuSeparator />
-
-            {/* View Options Group */}
-            <DropdownMenuLabel>View Options</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <EyeOpenIcon className="h-4 w-4" />
-                Show Hidden Files
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <EyeCloseIcon className="h-4 w-4" />
-                Hide Preview
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <SearchIcon className="h-4 w-4" />
-                Search
-                <DropdownMenuShortcut>⌘F</DropdownMenuShortcut>
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-
-            <DropdownMenuSeparator />
-
-            {/* Settings Group */}
-            <DropdownMenuLabel>Settings</DropdownMenuLabel>
-            <DropdownMenuSeparator />
-            <DropdownMenuGroup>
-              <DropdownMenuItem>
-                <SiteLogoIcon className="h-4 w-4" />
-                Preferences
-                <DropdownMenuShortcut>⌘,</DropdownMenuShortcut>
-              </DropdownMenuItem>
-              <DropdownMenuItem>
-                <SiteLogoIcon className="h-4 w-4" />
-                Account
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-
-            <DropdownMenuSeparator />
-
-            {/* Danger Zone Group */}
-            <DropdownMenuGroup>
-              <DropdownMenuItem variant="destructive">
-                <CrossIcon className="h-4 w-4" />
-                Reset All Settings
-              </DropdownMenuItem>
-            </DropdownMenuGroup>
-          </DropdownMenuContent>
-        </DropdownMenu>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Showcase of DropdownMenuGroup component demonstrating how to logically group related menu items for better organization, navigation, and accessibility. Each group represents a semantic category of actions.",
-      },
-    },
+    )
   },
-}
-
-// 9. Arrow Showcase
-export const ArrowShowcase: Story = {
-  render: () => (
-    <div className="space-y-8">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          DropdownArrow Showcase
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Dropdown menus with arrow pointers for better visual connection to
-          triggers
-        </p>
-      </div>
-
-      <div className="flex flex-wrap justify-center gap-8">
-        {/* Basic Arrow */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-center text-sm font-medium">
-            Basic Arrow
-          </h4>
-          <DropdownMenu>
-            <DropdownMenuTrigger asChild>
-              <Button variant="outline" className="gap-2">
-                <SiteLogoIcon className="h-4 w-4" />
-                With Arrow
-                <ChevronDownIcon className="h-4 w-4" />
-              </Button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent>
-              <DropdownArrow className="h-4 w-6" />
-              <DropdownMenuGroup>
-                <DropdownMenuItem>
-                  <EditBigIcon className="h-4 w-4" />
-                  Edit Item
-                </DropdownMenuItem>
-                <DropdownMenuItem>
-                  <TickIcon className="h-4 w-4" />
-                  Copy Item
-                </DropdownMenuItem>
-                <DropdownMenuItem>
-                  <ArrowRightIcon className="h-4 w-4" />
-                  Share Item
-                </DropdownMenuItem>
-              </DropdownMenuGroup>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </div>
-
-        {/* Custom Styled Arrow */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-center text-sm font-medium">
-            Custom Styled Arrow
-          </h4>
-          <DropdownMenu>
-            <DropdownMenuTrigger asChild>
-              <Button>
-                <AlertIcon className="h-4 w-4" />
-                Blue Theme
-                <AngleDownIcon className="h-4 w-4" />
-              </Button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent
-              classes={{
-                root: "bg-blue-900/40 border-blue-500/20",
-                border: "bg-gradient-to-r from-blue-500 to-cyan-500",
-              }}
-            >
-              <DropdownArrow className="h-4 w-6 fill-blue-900" />
-              <DropdownMenuGroup>
-                <DropdownMenuItem
-                  classes={{
-                    root: "text-blue-200 hover:bg-blue-500/20 focus:bg-blue-500/20",
-                  }}
-                >
-                  <TickIcon className="h-4 w-4" />
-                  Blue Action
-                </DropdownMenuItem>
-                <DropdownMenuItem
-                  classes={{
-                    root: "text-blue-200 hover:bg-blue-500/20 focus:bg-blue-500/20",
-                  }}
-                >
-                  <AudioBarIcon className="h-4 w-4" />
-                  Another Action
-                </DropdownMenuItem>
-              </DropdownMenuGroup>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </div>
-
-        {/* Arrow with Sub-menu */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-center text-sm font-medium">
-            Arrow with Sub-menu
-          </h4>
-          <DropdownMenu>
-            <DropdownMenuTrigger asChild>
-              <Button variant="text" className="gap-2">
-                <PlusIcon className="h-4 w-4" />
-                Create Menu
-                <ChevronDownIcon className="h-4 w-4" />
-              </Button>
-            </DropdownMenuTrigger>
-            <DropdownMenuContent>
-              <DropdownArrow className="fill-fm-surface-frosted h-4 w-6" />
-              <DropdownMenuLabel>Create New</DropdownMenuLabel>
-              <DropdownMenuSeparator />
-              <DropdownMenuGroup>
-                <DropdownMenuItem>
-                  <FileChartIcon className="h-4 w-4" />
-                  New Document
-                </DropdownMenuItem>
-                <DropdownMenuSub>
-                  <DropdownMenuSubTrigger>
-                    <ImageIcon className="h-4 w-4" />
-                    Import From
-                  </DropdownMenuSubTrigger>
-                  <DropdownMenuSubContent>
-                    <DropdownArrow className="fill-fm-surface-frosted h-4 w-4" />
-                    <DropdownMenuGroup>
-                      <DropdownMenuItem>
-                        <UploadIcon className="h-4 w-4" />
-                        Local File
-                      </DropdownMenuItem>
-                      <DropdownMenuItem>
-                        <ArrowRightIcon className="h-4 w-4" />
-                        URL
-                      </DropdownMenuItem>
-                      <DropdownMenuItem>
-                        <SiteLogoIcon className="h-4 w-4" />
-                        Cloud Service
-                      </DropdownMenuItem>
-                    </DropdownMenuGroup>
-                  </DropdownMenuSubContent>
-                </DropdownMenuSub>
-              </DropdownMenuGroup>
-            </DropdownMenuContent>
-          </DropdownMenu>
-        </div>
-      </div>
-
-      <div className="text-center">
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary inline-block max-w-lg rounded-lg border p-4">
-          <h4 className="text-fm-primary mb-2 text-sm font-medium">
-            Arrow Usage
-          </h4>
-          <p className="text-fm-secondary text-xs leading-relaxed">
-            The DropdownArrow component creates a visual pointer from the menu
-            to its trigger. It automatically inherits the menu's background
-            color and can be customized with the className prop. Use it to
-            improve the visual connection between triggers and their associated
-            menus.
-          </p>
-        </div>
-      </div>
-    </div>
-  ),
   parameters: {
     docs: {
       description: {
         story:
-          "Demonstration of DropdownArrow component showing how to add visual arrows that point from dropdown menus to their triggers. Includes basic usage, custom styling, and usage with sub-menus.",
+          "Three product-realistic use cases in one export: (1) a track action menu attached to a track row — add to queue, like/unlike (stateful), add to playlist via sub-menu, share, download, remove; (2) a user account menu in a top-nav context with profile, subscription, settings, and log-out; (3) a settings context menu with nested sub-menus for audio and library configuration plus a destructive reset option.",
       },
     },
   },