aural-ui 4.0.1 → 4.1.0

package/dist/components/command/Command.stories.tsx

@@ -1,30 +1,30 @@
 import React from "react"
-import { Badge } from "@components/badge"
 import { Button } from "@components/button"
 import {
-  ArrowRightIcon,
-  BubbleCheckIcon,
-  BubbleSparkleIcon,
+  AudioBarIcon,
   ChevronLeftIcon,
-  ChevronUpIcon,
-  CommandIcon,
-  CrossCircleIcon,
+  ChevronRightIcon,
+  CircleTickIcon,
+  DownloadIcon,
   EditBigIcon,
-  EyeOpenIcon,
-  FeatureShineIcon,
-  FileChartIcon,
+  FileTextIcon,
+  HeartIcon,
   ImageIcon,
-  ImportFolderIcon,
-  LightBulbSimpleIcon,
-  MagicBookIcon,
   MaintenanceIcon,
+  MusicalNoteIcon,
   SearchIcon,
-  TickIcon,
+  ShareIcon,
+  SkipForwardIcon,
+  SparklesSoftIcon,
+  StarIcon,
   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 {
   Command,
   CommandDialog,
@@ -43,81 +43,29 @@ const meta: Meta<typeof Command> = {
   component: Command,
   parameters: {
     layout: "fullscreen",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# Command Component
-
-A fast, unstyled command menu component built on top of CMDK with integration to our design system's List components. Perfect for creating command palettes, search interfaces, and quick action menus.
-
-## Features
-
-- **Fast Fuzzy Search**: Built-in fuzzy search with instant results
-- **Keyboard Navigation**: Full keyboard support with arrow keys and Enter
-- **Grouping**: Organize commands into logical groups with labels
-- **Shortcuts**: Display keyboard shortcuts for commands
-- **Icon Support**: Rich icon support for visual command identification
-- **Customizable**: Extensive theming and styling options
-- **Accessible**: ARIA compliant with screen reader support
-- **Dialog Mode**: Can be used as a modal command palette
-- **Empty States**: Customizable empty state when no results found
-
-## Usage Examples
-
-### Basic Command Menu
-\`\`\`tsx
-<Command>
-  <CommandInput placeholder="Type a command..." />
-  <CommandList>
-    <CommandEmpty>No results found.</CommandEmpty>
-    <CommandGroup>
-      <CommandLabel>Suggestions</CommandLabel>
-      <CommandItem>
-        <FileChartIcon />
-        New File
-        <CommandShortcut>⌘N</CommandShortcut>
-      </CommandItem>
-    </CommandGroup>
-  </CommandList>
-</Command>
-\`\`\`
-
-### Command Dialog
-\`\`\`tsx
-<CommandDialog open={open} onOpenChange={setOpen}>
-  <CommandInput placeholder="Search commands..." />
-  <CommandList>
-    <CommandEmpty>No commands found.</CommandEmpty>
-    <CommandGroup>
-      <CommandLabel>Actions</CommandLabel>
-      <CommandItem>Save File</CommandItem>
-      <CommandItem>Export</CommandItem>
-    </CommandGroup>
-  </CommandList>
-</CommandDialog>
-\`\`\`
-
-### With Custom Styling
-\`\`\`tsx
-<Command 
-  listProps={{ variant: "elevated", size: "lg" }}
-  classes={{ list: "custom-command-list" }}
->
-  <CommandInput />
-  <CommandList>
-    <CommandItem variant="destructive">Delete</CommandItem>
-  </CommandList>
-</Command>
-\`\`\`
-        `,
+        component:
+          "A fast command palette component built on CMDK, integrated with the design system's List components. Supports inline and modal (CommandDialog) modes, grouped items, live fuzzy search, keyboard navigation, icon support, keyboard shortcuts, and a destructive variant for dangerous actions. Use it for global search, quick actions, and context-sensitive command menus in any audio-focused or general-purpose application.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Inline & Modal Modes",
+              description: "Palette or dialog overlay",
+            },
+            {
+              title: "Fuzzy Search",
+              description: "Live filtering built in",
+            },
+            {
+              title: "Keyboard Navigation",
+              description: "Arrow keys and shortcuts",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -126,172 +74,145 @@ A fast, unstyled command menu component built on top of CMDK with integration to
 export default meta
 type Story = StoryObj<typeof Command>
 
-// 1. Basic Command
-export const BasicCommand: Story = {
-  render: () => (
-    <div className="mx-auto max-w-lg p-8">
-      <h3 className="text-fm-primary mb-4 text-lg font-medium">
-        Basic Command Menu
-      </h3>
-      <Command className="border-fm-divider-secondary rounded-lg border">
-        <CommandInput placeholder="Type a command or search..." />
-        <CommandList>
-          <CommandEmpty>No results found.</CommandEmpty>
-          <CommandGroup>
-            <CommandLabel>Suggestions</CommandLabel>
-            <CommandItem>
-              <SearchIcon />
-              Search Files
-            </CommandItem>
-            <CommandItem>
-              <ImageIcon />
-              View Images
-            </CommandItem>
-            <CommandItem>
-              <FileChartIcon />
-              Open Reports
-            </CommandItem>
-          </CommandGroup>
-          <CommandSeparator />
-          <CommandGroup>
-            <CommandLabel>Settings</CommandLabel>
-            <CommandItem shortcut="⌘P">
-              <EyeOpenIcon />
-              View Profile
-            </CommandItem>
-            <CommandItem shortcut="⌘,">
-              <MaintenanceIcon />
-              Settings
-            </CommandItem>
-          </CommandGroup>
-        </CommandList>
-      </Command>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "A basic command menu with search input, grouped items, icons, and keyboard shortcuts.",
-      },
-    },
-  },
-}
+// ─── Configurations ──────────────────────────────────────────────────────────
 
-// 2. Command Dialog
-export const CommandDialogExample: Story = {
+export const Configurations: Story = {
   render: () => {
-    const [open, setOpen] = React.useState(false)
+    const [dialogOpen, setDialogOpen] = React.useState(false)
 
     React.useEffect(() => {
       const down = (e: KeyboardEvent) => {
         if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
           e.preventDefault()
-          setOpen((open) => !open)
+          setDialogOpen((v) => !v)
         }
       }
-
       document.addEventListener("keydown", down)
       return () => document.removeEventListener("keydown", down)
     }, [])
 
     return (
       <div className="space-y-8 p-8">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 text-lg font-medium">
-            Command Dialog
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Press{" "}
-            <kbd className="bg-muted text-muted-foreground pointer-events-none inline-flex h-5 items-center gap-1 rounded border px-1.5 font-mono text-[10px] font-medium opacity-100 select-none">
-              <span className="text-xs">⌘</span>K
-            </kbd>{" "}
-            to open the command dialog
-          </p>
+        {/* Inline palette */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Inline Command Palette
+          </h4>
+          <div className="mx-auto max-w-md">
+            <Command className="border-fm-divider-secondary rounded-lg border">
+              <CommandInput placeholder="Search tracks, artists, playlists…" />
+              <CommandList>
+                <CommandEmpty>No results found.</CommandEmpty>
+                <CommandGroup>
+                  <CommandLabel>Library</CommandLabel>
+                  <CommandItem>
+                    <MusicalNoteIcon />
+                    Browse Tracks
+                    <CommandShortcut>⌘T</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <StarIcon />
+                    Favourites
+                    <CommandShortcut>⌘F</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <DownloadIcon />
+                    Downloaded
+                    <CommandShortcut>⌘D</CommandShortcut>
+                  </CommandItem>
+                </CommandGroup>
+                <CommandSeparator />
+                <CommandGroup>
+                  <CommandLabel>Actions</CommandLabel>
+                  <CommandItem>
+                    <UploadIcon />
+                    Upload Track
+                    <CommandShortcut>⌘U</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem variant="destructive">
+                    <TrashIcon />
+                    Delete Selected
+                    <CommandShortcut>⌘⌫</CommandShortcut>
+                  </CommandItem>
+                </CommandGroup>
+              </CommandList>
+            </Command>
+          </div>
         </div>
 
-        <div className="flex justify-center">
-          <Button
-            variant="outline"
-            onClick={() => setOpen(true)}
-            className="relative w-80"
-            innerClassName="flex items-center justify-between gap-2"
+        {/* Dialog / modal palette */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Modal Command Dialog (⌘K)
+          </h4>
+          <div className="flex justify-center">
+            <Button
+              variant="outline"
+              onClick={() => setDialogOpen(true)}
+              innerClassName="flex items-center gap-2"
+            >
+              <SearchIcon className="size-4" />
+              Search commands…
+              <span className="font-fm-brand text-fm-secondary ml-2 text-xs tracking-widest opacity-60">
+                ⌘K
+              </span>
+            </Button>
+          </div>
+
+          <CommandDialog
+            open={dialogOpen}
+            onOpenChange={setDialogOpen}
+            title="Command Palette"
+            description="Search tracks, artists, and app actions"
           >
-            <span className="flex items-center gap-2">
-              <SearchIcon className="mr-2 h-4 w-4" />
-              Search commands...
-            </span>
-            <kbd className="font-fm-brand text-fm-xs pointer-events-none hidden h-5 items-center gap-1 rounded border px-1.5 font-medium opacity-100 select-none sm:flex">
-              <span className="text-xs">⌘</span>K
-            </kbd>
-          </Button>
+            <CommandInput placeholder="Search tracks, artists, actions…" />
+            <CommandList>
+              <CommandEmpty>No results found.</CommandEmpty>
+              <CommandGroup>
+                <CommandLabel>Quick Actions</CommandLabel>
+                <CommandItem onSelect={() => setDialogOpen(false)}>
+                  <MusicalNoteIcon />
+                  Play Next
+                  <CommandShortcut>⌘→</CommandShortcut>
+                </CommandItem>
+                <CommandItem onSelect={() => setDialogOpen(false)}>
+                  <HeartIcon />
+                  Like Current Track
+                  <CommandShortcut>⌘L</CommandShortcut>
+                </CommandItem>
+                <CommandItem onSelect={() => setDialogOpen(false)}>
+                  <ShareIcon />
+                  Share Track
+                  <CommandShortcut>⌘⇧S</CommandShortcut>
+                </CommandItem>
+              </CommandGroup>
+              <CommandSeparator />
+              <CommandGroup>
+                <CommandLabel>Navigation</CommandLabel>
+                <CommandItem onSelect={() => setDialogOpen(false)}>
+                  <ChevronRightIcon />
+                  Library
+                </CommandItem>
+                <CommandItem onSelect={() => setDialogOpen(false)}>
+                  <ChevronLeftIcon />
+                  Go Back
+                </CommandItem>
+              </CommandGroup>
+              <CommandSeparator />
+              <CommandGroup>
+                <CommandLabel>Danger Zone</CommandLabel>
+                <CommandItem
+                  variant="destructive"
+                  onSelect={() => setDialogOpen(false)}
+                >
+                  <TrashIcon />
+                  Remove from Library
+                  <CommandShortcut>⌘⌫</CommandShortcut>
+                </CommandItem>
+              </CommandGroup>
+            </CommandList>
+          </CommandDialog>
         </div>
-
-        <CommandDialog
-          open={open}
-          onOpenChange={setOpen}
-          title="Command Palette"
-          description="Search for commands and actions"
-        >
-          <CommandInput placeholder="Type a command or search..." />
-          <CommandList>
-            <CommandEmpty>No results found.</CommandEmpty>
-            <CommandGroup>
-              <CommandLabel>Quick Actions</CommandLabel>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <FileChartIcon />
-                New File
-                <CommandShortcut>⌘N</CommandShortcut>
-              </CommandItem>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <ImportFolderIcon />
-                Import Folder
-                <CommandShortcut>⌘⇧N</CommandShortcut>
-              </CommandItem>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <UploadIcon />
-                Upload
-                <CommandShortcut>⌘U</CommandShortcut>
-              </CommandItem>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <ImageIcon />
-                Add Image
-                <CommandShortcut>⌘I</CommandShortcut>
-              </CommandItem>
-            </CommandGroup>
-            <CommandSeparator />
-            <CommandGroup>
-              <CommandLabel>Navigation</CommandLabel>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <ArrowRightIcon />
-                Go Forward
-                <CommandShortcut>⌘→</CommandShortcut>
-              </CommandItem>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <ChevronLeftIcon />
-                Go Back
-                <CommandShortcut>⌘←</CommandShortcut>
-              </CommandItem>
-              <CommandItem onSelect={() => setOpen(false)}>
-                <ChevronUpIcon />
-                Go Up
-                <CommandShortcut>⌘↑</CommandShortcut>
-              </CommandItem>
-            </CommandGroup>
-            <CommandSeparator />
-            <CommandGroup>
-              <CommandLabel>Dangerous Actions</CommandLabel>
-              <CommandItem
-                variant="destructive"
-                onSelect={() => setOpen(false)}
-              >
-                <TrashIcon />
-                Delete
-                <CommandShortcut>⌘⌫</CommandShortcut>
-              </CommandItem>
-            </CommandGroup>
-          </CommandList>
-        </CommandDialog>
       </div>
     )
   },
@@ -299,258 +220,239 @@ export const CommandDialogExample: Story = {
     docs: {
       description: {
         story:
-          "A command dialog that can be opened with ⌘K. Includes multiple command groups and keyboard shortcuts.",
+          "Two configuration modes side by side: an inline Command palette always visible on the page, and a CommandDialog that opens as a modal overlay triggered by a button or ⌘K. Both share the same internal anatomy — input, list, groups, separator, shortcuts, and the destructive variant.",
       },
     },
   },
 }
 
-// 3. File Management Commands
-export const FileManagementCommands: Story = {
-  render: () => (
-    <div className="mx-auto max-w-lg space-y-8 p-8">
-      <h3 className="text-fm-primary text-lg font-medium">File Management</h3>
-      <Command className="border-fm-divider-secondary rounded-lg border">
-        <CommandInput placeholder="Search files and actions..." />
-        <CommandList>
-          <CommandEmpty>
-            <div className="py-6 text-center">
-              <SearchIcon className="text-fm-tertiary mx-auto h-8 w-8" />
-              <p className="text-fm-secondary mt-2 text-sm">
-                No files or actions found.
-              </p>
-            </div>
-          </CommandEmpty>
-
-          <CommandGroup>
-            <CommandLabel>Create</CommandLabel>
-            <CommandItem>
-              <FileChartIcon />
-              New Document
-              <CommandShortcut>⌘N</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <ImportFolderIcon />
-              New Folder
-              <CommandShortcut>⌘⇧N</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <EditBigIcon />
-              New Template
-              <CommandShortcut>⌘T</CommandShortcut>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>Actions</CommandLabel>
-            <CommandItem>
-              <BubbleCheckIcon />
-              Approve
-              <CommandShortcut>⌘A</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <EditBigIcon />
-              Edit
-              <CommandShortcut>⌘E</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <BubbleSparkleIcon />
-              Share
-              <CommandShortcut>⌘⇧S</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <TickIcon />
-              Mark Complete
-              <CommandShortcut>⌘⇧F</CommandShortcut>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>Import/Export</CommandLabel>
-            <CommandItem>
-              <UploadIcon />
-              Import Files
-              <CommandShortcut>⌘I</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <ArrowRightIcon />
-              Export Selection
-              <CommandShortcut>⌘E</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <MaintenanceIcon />
-              Sync
-              <CommandShortcut>⌘R</CommandShortcut>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>Danger Zone</CommandLabel>
-            <CommandItem variant="destructive">
-              <TrashIcon />
-              Move to Trash
-              <CommandShortcut>⌘⌫</CommandShortcut>
-            </CommandItem>
-          </CommandGroup>
-        </CommandList>
-      </Command>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "File management command palette with create, action, import/export, and destructive commands organized in groups.",
-      },
-    },
-  },
-}
+// ─── Interactive ──────────────────────────────────────────────────────────────
 
-// 4. Search and Filter Commands
-export const SearchAndFilterCommands: Story = {
+export const Interactive: Story = {
   render: () => {
-    const [searchTerm, setSearchTerm] = React.useState("")
+    const [search, setSearch] = React.useState("")
+    const [lastSelected, setLastSelected] = React.useState<string | null>(null)
 
-    const allItems = [
-      {
-        id: "recent",
-        label: "Recent Files",
-        icon: <FileChartIcon />,
-        group: "Quick Access",
-      },
-      {
-        id: "images",
-        label: "Images",
-        icon: <ImageIcon />,
-        group: "Quick Access",
-      },
-      {
-        id: "uploads",
-        label: "Uploads",
-        icon: <UploadIcon />,
-        group: "Quick Access",
-      },
-      {
-        id: "magic",
-        label: "Magic Book",
-        icon: <MagicBookIcon />,
-        group: "Quick Access",
-      },
-      {
-        id: "charts",
-        label: "Charts",
-        icon: <FileChartIcon />,
-        group: "Apps",
-      },
+    const tracks = [
       {
-        id: "search",
-        label: "Search",
-        icon: <SearchIcon />,
-        group: "Apps",
+        id: "t1",
+        label: "Midnight Echoes",
+        artist: "Luna Vex",
+        group: "Tracks",
       },
       {
-        id: "maintenance",
-        label: "Maintenance",
-        icon: <MaintenanceIcon />,
-        group: "Apps",
-      },
-      {
-        id: "profile",
-        label: "Profile",
-        icon: <EyeOpenIcon />,
-        group: "Account",
+        id: "t2",
+        label: "Solar Drift",
+        artist: "The Velvet Faders",
+        group: "Tracks",
       },
+      { id: "t3", label: "Neon Requiem", artist: "Axiom", group: "Tracks" },
+    ]
+    const artists = [
+      { id: "a1", label: "Luna Vex", genre: "Electronic", group: "Artists" },
       {
-        id: "features",
-        label: "Features",
-        icon: <FeatureShineIcon />,
-        group: "Account",
+        id: "a2",
+        label: "The Velvet Faders",
+        genre: "Indie",
+        group: "Artists",
       },
     ]
+    const playlists = [
+      { id: "p1", label: "Late Night Drive", count: 18, group: "Playlists" },
+      { id: "p2", label: "Focus Mode", count: 34, group: "Playlists" },
+      { id: "p3", label: "Morning Energy", count: 22, group: "Playlists" },
+    ]
 
-    const filteredItems = searchTerm
-      ? allItems.filter((item) =>
-          item.label.toLowerCase().includes(searchTerm.toLowerCase())
-        )
-      : allItems
+    const filterItems = <T extends { label: string }>(items: T[]) =>
+      search
+        ? items.filter((i) =>
+            i.label.toLowerCase().includes(search.toLowerCase())
+          )
+        : items
 
-    const groupedItems = filteredItems.reduce(
-      (acc, item) => {
-        if (!acc[item.group]) {
-          acc[item.group] = []
-        }
-        acc[item.group].push(item)
-        return acc
-      },
-      {} as Record<string, typeof allItems>
-    )
+    const filteredTracks = filterItems(tracks)
+    const filteredArtists = filterItems(artists)
+    const filteredPlaylists = filterItems(playlists)
+
+    const totalResults =
+      filteredTracks.length + filteredArtists.length + filteredPlaylists.length
 
     return (
-      <div className="mx-auto max-w-lg space-y-8 p-8">
-        <div className="space-y-2">
-          <h3 className="text-fm-primary text-lg font-medium">
-            Search and Filter
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Dynamic filtering based on search input
-          </p>
-        </div>
+      <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">
+                Search State
+              </p>
 
-        <Command className="border-fm-divider-secondary rounded-lg border">
-          <CommandInput
-            placeholder="Search apps, files, and more..."
-            value={searchTerm}
-            onValueChange={setSearchTerm}
-          />
-          <CommandList>
-            <CommandEmpty>
-              <div className="py-6 text-center">
-                <SearchIcon className="text-fm-tertiary mx-auto h-8 w-8" />
-                <p className="text-fm-secondary mt-2 text-sm">
-                  No results for "{searchTerm}"
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Query
                 </p>
-                <p className="text-fm-tertiary text-xs">
-                  Try searching for something else
+                <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md truncate font-medium">
+                  {search || "—"}
                 </p>
               </div>
-            </CommandEmpty>
 
-            {Object.entries(groupedItems).map(([group, items]) => (
-              <React.Fragment key={group}>
-                <CommandGroup>
-                  <CommandLabel>{group}</CommandLabel>
-                  {items.map((item) => (
-                    <CommandItem key={item.id}>
-                      {item.icon}
-                      {item.label}
-                    </CommandItem>
-                  ))}
-                </CommandGroup>
-                {Object.keys(groupedItems).indexOf(group) <
-                  Object.keys(groupedItems).length - 1 && <CommandSeparator />}
-              </React.Fragment>
-            ))}
-          </CommandList>
-        </Command>
-
-        {searchTerm && (
-          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-            <h4 className="text-fm-primary text-sm font-medium">
-              Search Stats
-            </h4>
-            <div className="text-fm-secondary mt-2 space-y-1 text-xs">
-              <p>Search term: "{searchTerm}"</p>
-              <p>Results found: {filteredItems.length}</p>
-              <p>Groups: {Object.keys(groupedItems).length}</p>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Results
+                </p>
+                <div className="space-y-1">
+                  <div className="flex justify-between">
+                    <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      Tracks
+                    </span>
+                    <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      {filteredTracks.length}
+                    </span>
+                  </div>
+                  <div className="flex justify-between">
+                    <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      Artists
+                    </span>
+                    <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      {filteredArtists.length}
+                    </span>
+                  </div>
+                  <div className="flex justify-between">
+                    <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      Playlists
+                    </span>
+                    <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      {filteredPlaylists.length}
+                    </span>
+                  </div>
+                </div>
+              </div>
+
+              <div className="border-fm-divider-secondary border-t pt-4" />
+
+              <div className="space-y-2">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                  Last Selected
+                </p>
+                <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md truncate font-medium">
+                  {lastSelected ?? "—"}
+                </p>
+              </div>
+
+              {search && (
+                <>
+                  <div className="border-fm-divider-secondary border-t pt-4" />
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={() => setSearch("")}
+                    className="w-full"
+                  >
+                    Clear search
+                  </Button>
+                </>
+              )}
+            </div>
+
+            {/* Preview stage */}
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <Command className="border-fm-divider-secondary rounded-lg border">
+                <CommandInput
+                  placeholder="Search tracks, artists, playlists…"
+                  value={search}
+                  onValueChange={setSearch}
+                />
+                <CommandList>
+                  <CommandEmpty>
+                    <div className="py-6 text-center">
+                      <SearchIcon className="text-fm-tertiary mx-auto size-8" />
+                      <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mt-2">
+                        No results for &quot;{search}&quot;
+                      </p>
+                    </div>
+                  </CommandEmpty>
+
+                  {filteredTracks.length > 0 && (
+                    <CommandGroup>
+                      <CommandLabel>Tracks</CommandLabel>
+                      {filteredTracks.map((t) => (
+                        <CommandItem
+                          key={t.id}
+                          onSelect={() => setLastSelected(t.label)}
+                        >
+                          <MusicalNoteIcon />
+                          <span className="flex flex-col">
+                            <span>{t.label}</span>
+                            <span className="text-fm-tertiary text-xs">
+                              {t.artist}
+                            </span>
+                          </span>
+                          <CommandShortcut>↵</CommandShortcut>
+                        </CommandItem>
+                      ))}
+                    </CommandGroup>
+                  )}
+
+                  {filteredTracks.length > 0 && filteredArtists.length > 0 && (
+                    <CommandSeparator />
+                  )}
+
+                  {filteredArtists.length > 0 && (
+                    <CommandGroup>
+                      <CommandLabel>Artists</CommandLabel>
+                      {filteredArtists.map((a) => (
+                        <CommandItem
+                          key={a.id}
+                          onSelect={() => setLastSelected(a.label)}
+                        >
+                          <StarIcon />
+                          <span className="flex flex-col">
+                            <span>{a.label}</span>
+                            <span className="text-fm-tertiary text-xs">
+                              {a.genre}
+                            </span>
+                          </span>
+                        </CommandItem>
+                      ))}
+                    </CommandGroup>
+                  )}
+
+                  {filteredArtists.length > 0 &&
+                    filteredPlaylists.length > 0 && <CommandSeparator />}
+
+                  {filteredPlaylists.length > 0 && (
+                    <CommandGroup>
+                      <CommandLabel>Playlists</CommandLabel>
+                      {filteredPlaylists.map((p) => (
+                        <CommandItem
+                          key={p.id}
+                          onSelect={() => setLastSelected(p.label)}
+                        >
+                          <AudioBarIcon />
+                          <span className="flex flex-col">
+                            <span>{p.label}</span>
+                            <span className="text-fm-tertiary text-xs">
+                              {p.count} tracks
+                            </span>
+                          </span>
+                        </CommandItem>
+                      ))}
+                    </CommandGroup>
+                  )}
+                </CommandList>
+              </Command>
+
+              <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)">
+                  {totalResults} result{totalResults !== 1 ? "s" : ""} —
+                  navigate with ↑↓ and confirm with ↵
+                </code>
+              </div>
             </div>
           </div>
-        )}
+        </div>
       </div>
     )
   },
@@ -558,442 +460,203 @@ export const SearchAndFilterCommands: Story = {
     docs: {
       description: {
         story:
-          "Dynamic command menu that filters results based on search input with real-time statistics.",
+          "Live search filtering across tracks, artists, and playlists in an audio app context. The left panel shows real-time result counts and the last selected item. Use the keyboard arrow keys to navigate and Enter to select — demonstrating CMDK's built-in keyboard navigation.",
       },
     },
   },
 }
 
-// 5. Custom Styling Variants
-export const CustomStylingVariants: Story = {
-  render: () => (
-    <div className="space-y-8 p-8">
-      <h3 className="text-fm-primary text-center text-lg font-medium">
-        Custom Styling Variants
-      </h3>
-
-      <div className="grid grid-cols-1 gap-6 lg:grid-cols-2">
-        {/* Elevated Command */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Elevated Style
+// ─── UseCases ─────────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
+  render: () => {
+    const [globalOpen, setGlobalOpen] = React.useState(false)
+
+    React.useEffect(() => {
+      const down = (e: KeyboardEvent) => {
+        if (e.key === "k" && (e.metaKey || e.ctrlKey)) {
+          e.preventDefault()
+          setGlobalOpen((v) => !v)
+        }
+      }
+      document.addEventListener("keydown", down)
+      return () => document.removeEventListener("keydown", down)
+    }, [])
+
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* 1 — Global app search */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Global App Search (⌘K)
           </h4>
-          <Command
-            className="border-fm-divider-secondary rounded-lg border"
-            listProps={{ variant: "elevated", size: "lg" }}
+          <div className="flex justify-center">
+            <Button
+              variant="outline"
+              onClick={() => setGlobalOpen(true)}
+              innerClassName="flex items-center gap-2"
+            >
+              <SearchIcon className="size-4" />
+              Search everything…
+              <span className="font-fm-brand text-fm-secondary ml-2 text-xs tracking-widest opacity-60">
+                ⌘K
+              </span>
+            </Button>
+          </div>
+          <CommandDialog
+            open={globalOpen}
+            onOpenChange={setGlobalOpen}
+            title="Global Search"
+            description="Search tracks, artists, playlists, and settings"
           >
-            <CommandInput placeholder="Elevated command menu..." />
+            <CommandInput placeholder="Search everything…" />
             <CommandList>
               <CommandEmpty>No results found.</CommandEmpty>
               <CommandGroup>
-                <CommandLabel>Premium Actions</CommandLabel>
-                <CommandItem>
-                  <FeatureShineIcon />
-                  Premium Feature
-                  <Badge color="positive" className="ml-auto">
-                    Pro
-                  </Badge>
+                <CommandLabel>Tracks</CommandLabel>
+                <CommandItem onSelect={() => setGlobalOpen(false)}>
+                  <MusicalNoteIcon />
+                  Midnight Echoes — Luna Vex
                 </CommandItem>
-                <CommandItem>
-                  <BubbleSparkleIcon />
-                  Favorite
+                <CommandItem onSelect={() => setGlobalOpen(false)}>
+                  <MusicalNoteIcon />
+                  Solar Drift — The Velvet Faders
                 </CommandItem>
               </CommandGroup>
-            </CommandList>
-          </Command>
-        </div>
-
-        {/* Compact Command */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Compact Style
-          </h4>
-          <Command
-            className="border-fm-divider-secondary rounded-lg border"
-            listProps={{ size: "sm" }}
-          >
-            <CommandInput
-              placeholder="Compact menu..."
-              classes={{ input: "text-xs" }}
-            />
-            <CommandList>
-              <CommandEmpty>No results found.</CommandEmpty>
+              <CommandSeparator />
               <CommandGroup>
-                <CommandLabel>Quick Actions</CommandLabel>
-                <CommandItem>
-                  <FileChartIcon />
-                  New
-                  <CommandShortcut>⌘N</CommandShortcut>
-                </CommandItem>
-                <CommandItem>
-                  <SearchIcon />
-                  Find
-                  <CommandShortcut>⌘F</CommandShortcut>
+                <CommandLabel>Playlists</CommandLabel>
+                <CommandItem onSelect={() => setGlobalOpen(false)}>
+                  <AudioBarIcon />
+                  Late Night Drive
                 </CommandItem>
-                <CommandItem>
-                  <MaintenanceIcon />
-                  Refresh
-                  <CommandShortcut>⌘R</CommandShortcut>
+                <CommandItem onSelect={() => setGlobalOpen(false)}>
+                  <AudioBarIcon />
+                  Focus Mode
                 </CommandItem>
               </CommandGroup>
-            </CommandList>
-          </Command>
-        </div>
-
-        {/* Flat Style */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">Flat Style</h4>
-          <Command
-            className="border-fm-divider-secondary rounded-lg border"
-            listProps={{ variant: "flat", rounded: "lg" }}
-          >
-            <CommandInput placeholder="Flat design menu..." />
-            <CommandList>
-              <CommandEmpty>No results found.</CommandEmpty>
+              <CommandSeparator />
               <CommandGroup>
-                <CommandLabel>Interface</CommandLabel>
-                <CommandItem>
+                <CommandLabel>Settings</CommandLabel>
+                <CommandItem onSelect={() => setGlobalOpen(false)}>
                   <MaintenanceIcon />
-                  Settings
-                </CommandItem>
-                <CommandItem>
-                  <EyeOpenIcon />
-                  Account
+                  Audio Quality
+                  <CommandShortcut>⌘,</CommandShortcut>
                 </CommandItem>
               </CommandGroup>
             </CommandList>
-          </Command>
+          </CommandDialog>
         </div>
 
-        {/* Custom Classes */}
-        <div className="space-y-4">
-          <h4 className="text-fm-secondary text-sm font-medium">
-            Custom Classes
+        {/* 2 — File management commands */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            File Management Commands
           </h4>
-          <Command
-            className="rounded-lg border border-purple-500/30 bg-purple-900/10"
-            classes={{
-              list: "bg-purple-900/20",
-            }}
-          >
-            <CommandInput
-              placeholder="Purple themed menu..."
-              classes={{
-                wrapper: "border-purple-500/30",
-                icon: "text-purple-400",
-              }}
-            />
-            <CommandList>
-              <CommandEmpty>No results found.</CommandEmpty>
-              <CommandGroup>
-                <CommandLabel>Custom Theme</CommandLabel>
-                <CommandItem classes={{ root: "hover:bg-purple-500/20" }}>
-                  <FeatureShineIcon />
-                  Special Action
-                </CommandItem>
-                <CommandItem classes={{ root: "hover:bg-purple-500/20" }}>
-                  <BubbleSparkleIcon />
-                  Another Action
-                </CommandItem>
-              </CommandGroup>
-            </CommandList>
-          </Command>
-        </div>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Various styling options including elevated, compact, flat styles and custom theming with purple color scheme.",
-      },
-    },
-  },
-}
-
-// 6. Complex Command Structure
-export const ComplexCommandStructure: Story = {
-  render: () => (
-    <div className="mx-auto max-w-lg space-y-8 p-8">
-      <h3 className="text-fm-primary text-lg font-medium">
-        Complex Command Structure
-      </h3>
-
-      <Command className="border-fm-divider-secondary rounded-lg border">
-        <CommandInput placeholder="Search all commands..." />
-        <CommandList>
-          <CommandEmpty>
-            <div className="py-8 text-center">
-              <SearchIcon className="text-fm-tertiary mx-auto h-12 w-12" />
-              <h4 className="text-fm-primary mt-2 text-sm font-medium">
-                No commands found
-              </h4>
-              <p className="text-fm-secondary mt-1 text-xs">
-                Try adjusting your search to find what you're looking for.
-              </p>
-            </div>
-          </CommandEmpty>
-
-          <CommandGroup>
-            <CommandLabel>
-              <FileChartIcon className="mr-2" />
-              File Operations
-            </CommandLabel>
-            <CommandItem>
-              <FileChartIcon />
-              New Document
-              <Badge color="info" className="ml-auto">
-                Ctrl+N
-              </Badge>
-            </CommandItem>
-            <CommandItem>
-              <ImportFolderIcon />
-              Open Folder
-              <CommandShortcut>⌘O</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <EditBigIcon />
-              Recent Files
-              <Badge color="neutral" className="ml-auto">
-                5
-              </Badge>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>
-              <EyeOpenIcon className="mr-2" />
-              User Management
-            </CommandLabel>
-            <CommandItem>
-              <EyeOpenIcon />
-              View Profile
-              <CommandShortcut>⌘P</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <MaintenanceIcon />
-              User Settings
-              <CommandShortcut>⌘,</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <BubbleSparkleIcon />
-              Share Profile
-              <Badge color="warning" className="ml-auto">
-                Beta
-              </Badge>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>
-              <UploadIcon className="mr-2" />
-              Data Management
-            </CommandLabel>
-            <CommandItem>
-              <ArrowRightIcon />
-              Export Data
-              <CommandShortcut>⌘E</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <UploadIcon />
-              Import Data
-              <CommandShortcut>⌘I</CommandShortcut>
-            </CommandItem>
-            <CommandItem>
-              <MaintenanceIcon />
-              Sync Data
-              <Badge color="positive" className="ml-auto">
-                Auto
-              </Badge>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>
-              <FeatureShineIcon className="mr-2" />
-              Features
-            </CommandLabel>
-            <CommandItem>
-              <MagicBookIcon />
-              Magic Features
-              <Badge color="neutral" className="ml-auto">
-                12
-              </Badge>
-            </CommandItem>
-            <CommandItem>
-              <LightBulbSimpleIcon />
-              Ideas
-              <Badge color="positive" className="ml-auto">
-                New
-              </Badge>
-            </CommandItem>
-            <CommandItem>
-              <FeatureShineIcon />
-              Special Features
-              <CommandShortcut>⌘⇧S</CommandShortcut>
-            </CommandItem>
-          </CommandGroup>
-
-          <CommandSeparator />
-
-          <CommandGroup>
-            <CommandLabel>
-              <TrashIcon className="mr-2" />
-              Dangerous Actions
-            </CommandLabel>
-            <CommandItem variant="destructive">
-              <TrashIcon />
-              Delete Account
-              <Badge color="negative" className="ml-auto">
-                !
-              </Badge>
-            </CommandItem>
-            <CommandItem variant="destructive">
-              <CrossCircleIcon />
-              Reset All Data
-              <CommandShortcut>⌘⇧R</CommandShortcut>
-            </CommandItem>
-          </CommandGroup>
-        </CommandList>
-      </Command>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Complex command structure with multiple groups, icons in labels, badges for additional context, and both regular and destructive actions.",
-      },
-    },
-  },
-}
-
-// 7. Performance Demo
-export const PerformanceDemo: Story = {
-  render: () => {
-    const [itemCount, setItemCount] = React.useState(100)
-
-    const generateItems = (count: number) => {
-      const categories = ["Files", "Actions", "Settings", "Images", "Tools"]
-      const icons = [
-        FileChartIcon,
-        EditBigIcon,
-        MaintenanceIcon,
-        ImageIcon,
-        CommandIcon,
-      ]
-      const items = []
-
-      for (let i = 0; i < count; i++) {
-        const categoryIndex = i % categories.length
-        items.push({
-          id: i,
-          label: `${categories[categoryIndex]} Item ${i + 1}`,
-          icon: icons[categoryIndex],
-          category: categories[categoryIndex],
-          shortcut: i % 10 === 0 ? `⌘${i / 10}` : undefined,
-        })
-      }
-
-      return items
-    }
-
-    const items = React.useMemo(() => generateItems(itemCount), [itemCount])
-    const groupedItems = React.useMemo(() => {
-      return items.reduce(
-        (acc, item) => {
-          if (!acc[item.category]) {
-            acc[item.category] = []
-          }
-          acc[item.category].push(item)
-          return acc
-        },
-        {} as Record<string, typeof items>
-      )
-    }, [items])
-
-    return (
-      <div className="space-y-8 p-8">
-        <div className="space-y-4 text-center">
-          <h3 className="text-fm-primary text-lg font-medium">
-            Performance Demo
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Test command menu performance with large datasets
-          </p>
-
-          <div className="flex items-center justify-center gap-4">
-            <label className="text-fm-secondary text-sm">Items:</label>
-            <select
-              value={itemCount}
-              onChange={(e) => setItemCount(Number(e.target.value))}
-              className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary rounded border px-3 py-1"
-            >
-              <option value={50}>50</option>
-              <option value={100}>100</option>
-              <option value={500}>500</option>
-              <option value={1000}>1000</option>
-            </select>
-            <Badge color="info">{itemCount} items</Badge>
+          <div className="mx-auto max-w-md">
+            <Command className="border-fm-divider-secondary rounded-lg border">
+              <CommandInput placeholder="Search file actions…" />
+              <CommandList>
+                <CommandEmpty>No file actions found.</CommandEmpty>
+                <CommandGroup>
+                  <CommandLabel>Create</CommandLabel>
+                  <CommandItem>
+                    <FileTextIcon />
+                    New Playlist
+                    <CommandShortcut>⌘N</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <UploadIcon />
+                    Upload Track
+                    <CommandShortcut>⌘U</CommandShortcut>
+                  </CommandItem>
+                </CommandGroup>
+                <CommandSeparator />
+                <CommandGroup>
+                  <CommandLabel>Manage</CommandLabel>
+                  <CommandItem>
+                    <EditBigIcon />
+                    Edit Metadata
+                    <CommandShortcut>⌘E</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <DownloadIcon />
+                    Download Offline
+                    <CommandShortcut>⌘D</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <ShareIcon />
+                    Share
+                    <CommandShortcut>⌘⇧S</CommandShortcut>
+                  </CommandItem>
+                </CommandGroup>
+                <CommandSeparator />
+                <CommandGroup>
+                  <CommandLabel>Danger Zone</CommandLabel>
+                  <CommandItem variant="destructive">
+                    <TrashIcon />
+                    Remove from Library
+                    <CommandShortcut>⌘⌫</CommandShortcut>
+                  </CommandItem>
+                </CommandGroup>
+              </CommandList>
+            </Command>
           </div>
         </div>
 
-        <div className="mx-auto max-w-lg">
-          <Command className="border-fm-divider-secondary rounded-lg border">
-            <CommandInput placeholder={`Search ${itemCount} items...`} />
-            <CommandList>
-              <CommandEmpty>
-                No results found in {itemCount} items.
-              </CommandEmpty>
-
-              {Object.entries(groupedItems).map(([category, categoryItems]) => (
-                <React.Fragment key={category}>
-                  <CommandGroup>
-                    <CommandLabel>
-                      {category} ({categoryItems.length})
-                    </CommandLabel>
-                    {categoryItems.map((item) => {
-                      const IconComponent = item.icon
-                      return (
-                        <CommandItem key={item.id}>
-                          <IconComponent />
-                          {item.label}
-                          {item.shortcut && (
-                            <CommandShortcut>{item.shortcut}</CommandShortcut>
-                          )}
-                        </CommandItem>
-                      )
-                    })}
-                  </CommandGroup>
-                  {Object.keys(groupedItems).indexOf(category) <
-                    Object.keys(groupedItems).length - 1 && (
-                    <CommandSeparator />
-                  )}
-                </React.Fragment>
-              ))}
-            </CommandList>
-          </Command>
-        </div>
-
-        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-lg rounded-lg border p-4">
-          <h4 className="text-fm-primary text-sm font-medium">
-            Performance Info
+        {/* 3 — Action shortcuts */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Playback Action Shortcuts
           </h4>
-          <div className="text-fm-secondary mt-2 grid grid-cols-2 gap-4 text-xs">
-            <div>Total Items: {itemCount}</div>
-            <div>Categories: {Object.keys(groupedItems).length}</div>
-            <div>
-              Avg per Category:{" "}
-              {Math.round(itemCount / Object.keys(groupedItems).length)}
-            </div>
-            <div>With Shortcuts: {items.filter((i) => i.shortcut).length}</div>
+          <div className="mx-auto max-w-md">
+            <Command className="border-fm-divider-secondary rounded-lg border">
+              <CommandInput placeholder="Search playback actions…" />
+              <CommandList>
+                <CommandEmpty>No playback actions found.</CommandEmpty>
+                <CommandGroup>
+                  <CommandLabel>Now Playing</CommandLabel>
+                  <CommandItem>
+                    <HeartIcon />
+                    Like Track
+                    <CommandShortcut>⌘L</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <SkipForwardIcon />
+                    Skip to Next
+                    <CommandShortcut>⌘→</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <AudioBarIcon />
+                    Add to Queue
+                    <CommandShortcut>⌘Q</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <SparklesSoftIcon />
+                    Start Radio
+                    <CommandShortcut>⌘R</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <CircleTickIcon />
+                    Mark as Listened
+                  </CommandItem>
+                </CommandGroup>
+                <CommandSeparator />
+                <CommandGroup>
+                  <CommandLabel>View</CommandLabel>
+                  <CommandItem>
+                    <ImageIcon />
+                    Show Album Art
+                    <CommandShortcut>⌘⇧A</CommandShortcut>
+                  </CommandItem>
+                  <CommandItem>
+                    <VerticalMenuIcon />
+                    Track Info
+                    <CommandShortcut>⌘I</CommandShortcut>
+                  </CommandItem>
+                </CommandGroup>
+              </CommandList>
+            </Command>
           </div>
         </div>
       </div>
@@ -1003,7 +666,7 @@ export const PerformanceDemo: Story = {
     docs: {
       description: {
         story:
-          "Performance demonstration with configurable item counts to test search and rendering performance with large datasets.",
+          "Three real-world use cases in a single export: (1) a global app search dialog triggered by ⌘K covering tracks, playlists, and settings; (2) a file-management command palette for create/manage/delete operations; (3) a playback action shortcut palette for controlling the currently playing track without leaving the keyboard.",
       },
     },
   },