aural-ui 4.0.1 → 4.2.0

package/dist/components/sheet/Sheet.stories.tsx

@@ -1,24 +1,20 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import React, { useState } from "react"
-import { Badge } from "@components/badge"
 import { Button } from "@components/button"
 import { Checkbox } from "@components/checkbox"
-import { IconButton } from "@components/icon-button"
 import Input from "@components/input"
 import { Label } from "@components/label"
-import Textarea from "@components/textarea"
 import { AlertIcon } from "@icons/alert-icon"
-import { ArrowRightIcon } from "@icons/arrow-right-icon"
 import { ChevronRightIcon } from "@icons/chevron-right-icon"
-import { FeatureShineIcon } from "@icons/feature-shine-icon"
-import { FileChartIcon } from "@icons/file-chart-icon"
-import { MagicBookIcon } from "@icons/magic-book-icon"
 import { MaintenanceIcon } from "@icons/maintenance-icon"
+import { MusicalNoteIcon } from "@icons/musical-note-icon"
 import { SearchIcon } from "@icons/search-icon"
 import { SiteLogoIcon } from "@icons/site-logo-icon"
 import { TickCircleIcon } from "@icons/tick-circle-icon"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import {
   Sheet,
   SheetClose,
@@ -34,115 +30,30 @@ const meta: Meta<typeof Sheet> = {
   title: "Components/UI/Sheet",
   component: Sheet,
   parameters: {
-    layout: "fullscreen",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
+    layout: "centered",
     docs: {
       description: {
-        component: `
-# Sheet Component
-
-A slide-out panel component built on Radix UI Dialog primitives that provides a drawer-like interface for displaying content from different sides of the screen.
-
-## Features
-
-- **Multiple Sides**: Sheet can slide in from top, right, bottom, or left
-- **Variant Colors**: Neutral, positive, negative, warning, and info color variants
-- **Customizable Overlays**: Configurable opacity, glass effects, and noise textures
-- **Smooth Animations**: Slide animations with proper easing for each direction
-- **Accessible**: Full keyboard navigation and screen reader support
-- **Flexible Content**: Header, footer, and body sections with custom styling
-- **Auto Close Button**: Positioned close button with CrossIcon
-- **Portal Rendering**: Renders outside normal DOM hierarchy
-- **Focus Management**: Automatic focus trapping and restoration
-- **Border Accents**: Colored borders that match the variant
-
-## Component Structure
-
-- **Sheet**: Root component that manages sheet state
-- **SheetTrigger**: Button or element that opens the sheet
-- **SheetContent**: Main sheet container with overlay, content, and close button
-- **SheetHeader**: Header section for title and description
-- **SheetFooter**: Footer section for action buttons
-- **SheetTitle**: Accessible title element
-- **SheetDescription**: Optional description text
-- **SheetClose**: Close button component
-
-## Usage Examples
-
-### Basic Sheet
-\`\`\`tsx
-<Sheet>
-  <SheetTrigger asChild>
-    <Button>Open Sheet</Button>
-  </SheetTrigger>
-  <SheetContent>
-    <SheetHeader>
-      <SheetTitle>Sheet Title</SheetTitle>
-      <SheetDescription>Sheet description text.</SheetDescription>
-    </SheetHeader>
-    <div>Sheet content goes here.</div>
-    <SheetFooter>
-      <SheetClose asChild>
-        <Button variant="outline">Cancel</Button>
-      </SheetClose>
-      <Button>Confirm</Button>
-    </SheetFooter>
-  </SheetContent>
-</Sheet>
-\`\`\`
-
-### Sheet from Different Sides
-\`\`\`tsx
-<SheetContent side="left">
-  {/* Left side sheet */}
-</SheetContent>
-
-<SheetContent side="right">
-  {/* Right side sheet (default) */}
-</SheetContent>
-
-<SheetContent side="top">
-  {/* Top side sheet */}
-</SheetContent>
-
-<SheetContent side="bottom">
-  {/* Bottom side sheet */}
-</SheetContent>
-\`\`\`
-
-### Colored Variants
-\`\`\`tsx
-<SheetContent variant="positive">
-  {/* Success/positive themed sheet */}
-</SheetContent>
-
-<SheetContent variant="negative">
-  {/* Error/negative themed sheet */}
-</SheetContent>
-
-<SheetContent variant="warning">
-  {/* Warning themed sheet */}
-</SheetContent>
-
-<SheetContent variant="info">
-  {/* Info themed sheet */}
-</SheetContent>
-\`\`\`
-
-### Custom Overlay
-\`\`\`tsx
-<SheetContent opacity="high" glass="medium" noise="low">
-  {/* High opacity overlay with glass effect and subtle noise */}
-</SheetContent>
-\`\`\`
-        `,
+        component:
+          "A slide-out panel built on Radix UI Dialog primitives. Supports four entry sides, five semantic variants with matching gradient border accents, and configurable glass/noise overlays. Ideal for navigation drawers, detail panels, filter sidebars, and contextual action sheets.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Entry Sides",
+              description: "Top, bottom, left, right",
+            },
+            {
+              title: "5 Variant Borders",
+              description: "Neutral to negative",
+            },
+            {
+              title: "Glass & Noise",
+              description: "Overlay blur and grain",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -151,914 +62,724 @@ A slide-out panel component built on Radix UI Dialog primitives that provides a
 export default meta
 type Story = StoryObj<typeof Sheet>
 
-// Demo background content
-const BackgroundContent = () => (
-  <div className="min-h-screen bg-gradient-to-br from-blue-900 via-purple-900 to-pink-900 p-8">
-    <div className="mx-auto max-w-4xl space-y-8">
-      <header className="text-center">
-        <h1 className="mb-4 text-4xl font-bold text-white">
-          Main Content Area
-        </h1>
-        <p className="text-white/80">
-          This is the main content that sits behind the sheet overlay
-        </p>
-      </header>
+// ─── Configurations ────────────────────────────────────────────────────────────
 
-      <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-        {Array.from({ length: 6 }, (_, i) => (
-          <div
-            key={i}
-            className="rounded-lg border border-white/20 bg-white/10 p-6"
-          >
-            <h3 className="mb-2 text-lg font-semibold text-white">
-              Content Block {i + 1}
-            </h3>
-            <p className="mb-4 text-sm text-white/70">
-              Sample content that demonstrates the sheet overlay effect
-            </p>
-            <Button size="sm" variant="outline">
-              Action
+export const Configurations: Story = {
+  render: () => {
+    const SideSheet = ({ side, variant, label, description }: any) => (
+      <div className="space-y-2 text-center">
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="outline" size="sm">
+              {label}
             </Button>
-          </div>
-        ))}
+          </SheetTrigger>
+          <SheetContent side={side} variant={variant} container={null}>
+            <SheetHeader>
+              <SheetTitle>{label} Sheet</SheetTitle>
+              <SheetDescription>{description}</SheetDescription>
+            </SheetHeader>
+            <div className="py-4">
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                  side="{side}" variant="{variant}"
+                </code>
+              </div>
+            </div>
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button>Close</Button>
+              </SheetClose>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+        <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+          {label}
+        </p>
       </div>
-    </div>
-  </div>
-)
-
-// 1. Sheet Sides and Variants
-export const SidesAndVariants: Story = {
-  render: () => (
-    <div className="relative">
-      <BackgroundContent />
-
-      {/* Control Panel */}
-      <div className="fixed top-4 left-1/2 z-50 -translate-x-1/2 transform">
-        <div className="space-y-4 rounded-lg bg-black/80 p-6 backdrop-blur-sm">
-          <h3 className="text-fm-primary text-center text-sm font-medium">
-            Sheet Sides & Variants
-          </h3>
-
-          {/* Sides */}
-          <div className="space-y-2">
-            <h4 className="text-fm-secondary text-xs font-medium tracking-wide uppercase">
-              Sides
-            </h4>
-            <div className="grid grid-cols-2 gap-2">
-              {/* Left Sheet - Neutral */}
-              <Sheet>
-                <SheetTrigger asChild>
-                  <Button size="sm" variant="outline">
-                    Left
-                  </Button>
-                </SheetTrigger>
-                <SheetContent side="left" variant="neutral">
-                  <SheetHeader>
-                    <SheetTitle>Left Side Sheet</SheetTitle>
-                    <SheetDescription>
-                      Slides in from the left with neutral styling
-                    </SheetDescription>
-                  </SheetHeader>
-                  <div className="py-4">
-                    <div className="space-y-4">
-                      <div className="bg-fm-surface-secondary rounded-lg p-4">
-                        <h4 className="text-fm-primary mb-2 font-medium">
-                          Navigation Menu
-                        </h4>
-                        <div className="space-y-2">
-                          {["Dashboard", "Projects", "Team", "Settings"].map(
-                            (item) => (
-                              <div
-                                key={item}
-                                className="hover:bg-fm-surface-tertiary flex items-center gap-3 rounded p-2"
-                              >
-                                <SiteLogoIcon className="text-fm-secondary h-4 w-4" />
-                                <span className="text-fm-primary">{item}</span>
-                              </div>
-                            )
-                          )}
-                        </div>
-                      </div>
-                    </div>
-                  </div>
-                </SheetContent>
-              </Sheet>
+    )
 
-              {/* Right Sheet - Positive */}
-              <Sheet>
-                <SheetTrigger asChild>
-                  <Button size="sm" variant="outline">
-                    Right
-                  </Button>
-                </SheetTrigger>
-                <SheetContent side="right" variant="positive">
-                  <SheetHeader>
-                    <SheetTitle>Right Side Sheet</SheetTitle>
-                    <SheetDescription>
-                      Slides in from the right with positive styling
-                    </SheetDescription>
-                  </SheetHeader>
-                  <div className="py-4">
-                    <div className="border-fm-divider-positive bg-fm-surface-positive-sec rounded-lg border p-4">
-                      <div className="mb-2 flex items-center gap-2">
-                        <TickCircleIcon className="text-fm-icon-positive h-5 w-5" />
-                        <h4 className="text-fm-primary font-medium">
-                          Success Panel
-                        </h4>
-                      </div>
-                      <p className="text-fm-secondary text-sm">
-                        This demonstrates the positive variant with green accent
-                        border.
-                      </p>
-                    </div>
-                  </div>
-                </SheetContent>
-              </Sheet>
+    const OverlaySheet = ({ label, opacity, glass, noise }: any) => (
+      <div className="space-y-2 text-center">
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="outline" size="sm">
+              {label}
+            </Button>
+          </SheetTrigger>
+          <SheetContent
+            side="right"
+            variant="neutral"
+            opacity={opacity}
+            glass={glass}
+            noise={noise}
+            container={null}
+          >
+            <SheetHeader>
+              <SheetTitle>{label}</SheetTitle>
+              <SheetDescription>Overlay configuration demo.</SheetDescription>
+            </SheetHeader>
+            <div className="py-4">
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                  {[
+                    opacity && `opacity="${opacity}"`,
+                    glass && `glass="${glass}"`,
+                    noise && `noise="${noise}"`,
+                  ]
+                    .filter(Boolean)
+                    .join(" ")}
+                </code>
+              </div>
+            </div>
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button>Close</Button>
+              </SheetClose>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+        <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+          {label}
+        </p>
+      </div>
+    )
 
-              {/* Top Sheet - Warning */}
-              <Sheet>
-                <SheetTrigger asChild>
-                  <Button size="sm" variant="outline">
-                    Top
-                  </Button>
-                </SheetTrigger>
-                <SheetContent side="top" variant="warning">
-                  <SheetHeader>
-                    <SheetTitle>Top Side Sheet</SheetTitle>
-                    <SheetDescription>
-                      Slides down from the top with warning styling
-                    </SheetDescription>
-                  </SheetHeader>
-                  <div className="py-4">
-                    <div className="border-fm-divider-warning bg-fm-surface-warning-sec rounded-lg border p-4">
-                      <div className="mb-2 flex items-center gap-2">
-                        <AlertIcon className="text-fm-warning h-5 w-5" />
-                        <h4 className="text-fm-primary font-medium">
-                          Warning Notice
-                        </h4>
-                      </div>
-                      <p className="text-fm-secondary text-sm">
-                        Top sheets are great for notifications and warnings.
-                      </p>
-                    </div>
-                  </div>
-                </SheetContent>
-              </Sheet>
+    return (
+      <div className="space-y-8">
+        {/* All four sides */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            All Four Sides
+          </h4>
+          <div className="flex flex-wrap gap-6">
+            <SideSheet
+              side="left"
+              variant="neutral"
+              label="Left"
+              description="Slides in from the left — navigation and filter panels."
+            />
+            <SideSheet
+              side="right"
+              variant="neutral"
+              label="Right"
+              description="Slides in from the right — detail and settings panels."
+            />
+            <SideSheet
+              side="top"
+              variant="neutral"
+              label="Top"
+              description="Slides down from the top — notifications and alerts."
+            />
+            <SideSheet
+              side="bottom"
+              variant="neutral"
+              label="Bottom"
+              description="Slides up from the bottom — mobile-style action sheets."
+            />
+          </div>
+        </div>
 
-              {/* Bottom Sheet - Info */}
-              <Sheet>
-                <SheetTrigger asChild>
-                  <Button size="sm" variant="outline">
-                    Bottom
-                  </Button>
-                </SheetTrigger>
-                <SheetContent side="bottom" variant="info">
-                  <SheetHeader>
-                    <SheetTitle>Bottom Side Sheet</SheetTitle>
-                    <SheetDescription>
-                      Slides up from the bottom with info styling
-                    </SheetDescription>
-                  </SheetHeader>
-                  <div className="py-4">
-                    <div className="border-fm-divider-secondary bg-fm-surface-info-sec rounded-lg border p-4">
-                      <div className="mb-2 flex items-center gap-2">
-                        <FileChartIcon className="text-fm-icon-info h-5 w-5" />
-                        <h4 className="text-fm-primary font-medium">
-                          Information Panel
-                        </h4>
-                      </div>
-                      <p className="text-fm-secondary text-sm">
-                        Bottom sheets work well for mobile-style interactions.
-                      </p>
-                    </div>
-                  </div>
-                </SheetContent>
-              </Sheet>
-            </div>
+        {/* Variant types */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Semantic Variants
+          </h4>
+          <div className="flex flex-wrap gap-6">
+            <SideSheet
+              side="right"
+              variant="neutral"
+              label="Neutral"
+              description="Default neutral border accent."
+            />
+            <SideSheet
+              side="right"
+              variant="positive"
+              label="Positive"
+              description="Green border accent for success states."
+            />
+            <SideSheet
+              side="right"
+              variant="negative"
+              label="Negative"
+              description="Red border accent for error states."
+            />
+            <SideSheet
+              side="right"
+              variant="warning"
+              label="Warning"
+              description="Yellow border accent for cautionary states."
+            />
+            <SideSheet
+              side="right"
+              variant="info"
+              label="Info"
+              description="Blue border accent for informational states."
+            />
           </div>
+        </div>
 
-          {/* Error Variant */}
-          <div className="space-y-2">
-            <h4 className="text-fm-secondary text-xs font-medium tracking-wide uppercase">
-              Error Variant
-            </h4>
-            <Sheet>
-              <SheetTrigger asChild>
-                <Button size="sm" variant="outline">
-                  Error Sheet
-                </Button>
-              </SheetTrigger>
-              <SheetContent side="right" variant="negative">
-                <SheetHeader>
-                  <SheetTitle>Error Sheet</SheetTitle>
-                  <SheetDescription>
-                    Demonstrates the negative variant for error states
-                  </SheetDescription>
-                </SheetHeader>
-                <div className="py-4">
-                  <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
-                    <div className="mb-2 flex items-center gap-2">
-                      <AlertIcon className="text-fm-icon-negative h-5 w-5" />
-                      <h4 className="text-fm-primary font-medium">
-                        Error Details
-                      </h4>
-                    </div>
-                    <p className="text-fm-secondary mb-3 text-sm">
-                      Something went wrong. Please check the details below.
-                    </p>
-                    <div className="space-y-2">
-                      <div className="text-fm-secondary text-xs">
-                        • Network connection failed
-                      </div>
-                      <div className="text-fm-secondary text-xs">
-                        • Invalid response format
-                      </div>
-                    </div>
-                  </div>
-                </div>
-                <SheetFooter>
-                  <Button variant="outline" size="sm">
-                    Retry
-                  </Button>
-                  <SheetClose asChild>
-                    <Button size="sm">Close</Button>
-                  </SheetClose>
-                </SheetFooter>
-              </SheetContent>
-            </Sheet>
+        {/* Overlay options */}
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Glass &amp; Noise Overlay Options
+          </h4>
+          <div className="flex flex-wrap gap-6">
+            <OverlaySheet label="Low opacity" opacity="low" />
+            <OverlaySheet label="High opacity" opacity="high" />
+            <OverlaySheet label="High glass" glass="high" />
+            <OverlaySheet label="Noise texture" noise="medium" />
           </div>
         </div>
       </div>
-    </div>
-  ),
+    )
+  },
   parameters: {
     docs: {
       description: {
         story:
-          "Comprehensive demonstration of all sheet sides (left, right, top, bottom) and color variants (neutral, positive, negative, warning, info) with colored border accents.",
+          "Comparison of all four slide sides, all five semantic variants with gradient border accents, and overlay configuration options (opacity, glass, noise).",
       },
     },
   },
 }
 
-// 2. Navigation Sheet
-export const NavigationSheet: Story = {
-  render: () => (
-    <div className="relative">
-      <BackgroundContent />
-
-      {/* Mobile-style header */}
-      <div className="fixed top-0 right-0 left-0 z-40 bg-black/80 backdrop-blur-sm">
-        <div className="flex items-center justify-between p-4">
-          <Sheet>
-            <SheetTrigger asChild>
-              <IconButton
-                variant="ghost"
-                icon={<SiteLogoIcon />}
-                label="Menu"
-              />
-            </SheetTrigger>
-            <SheetContent side="left" className="w-80">
-              <SheetHeader>
-                <SheetTitle>Navigation Menu</SheetTitle>
-                <SheetDescription>
-                  Main navigation for the application
-                </SheetDescription>
-              </SheetHeader>
+// ─── Interactive ───────────────────────────────────────────────────────────────
 
-              <div className="py-4">
-                <nav className="space-y-2">
-                  {[
-                    {
-                      label: "Dashboard",
-                      icon: SiteLogoIcon,
-                      active: true,
-                      badge: null,
-                    },
-                    {
-                      label: "Projects",
-                      icon: FeatureShineIcon,
-                      active: false,
-                      badge: "3",
-                    },
-                    {
-                      label: "Analytics",
-                      icon: FileChartIcon,
-                      active: false,
-                      badge: null,
-                    },
-                    {
-                      label: "Team",
-                      icon: TickCircleIcon,
-                      active: false,
-                      badge: "New",
-                    },
-                    {
-                      label: "Settings",
-                      icon: MaintenanceIcon,
-                      active: false,
-                      badge: null,
-                    },
-                  ].map((item) => (
-                    <a
-                      key={item.label}
-                      href="#"
-                      className={`flex items-center gap-3 rounded-lg p-3 transition-colors ${
-                        item.active
-                          ? "bg-fm-surface-info-sec text-fm-info"
-                          : "text-fm-primary hover:bg-fm-surface-secondary"
-                      }`}
-                    >
-                      <item.icon className="h-5 w-5" />
-                      <span className="flex-1">{item.label}</span>
-                      {item.badge && (
-                        <Badge
-                          color={item.badge === "New" ? "positive" : "neutral"}
-                          size="sm"
-                        >
-                          {item.badge}
-                        </Badge>
-                      )}
-                      <ChevronRightIcon className="h-4 w-4" />
-                    </a>
-                  ))}
-                </nav>
+export const Interactive: Story = {
+  render: () => {
+    const InteractiveDemo = () => {
+      const [side, setSide] = useState<"top" | "bottom" | "left" | "right">(
+        "right"
+      )
+      const [variant, setVariant] = useState<
+        "neutral" | "positive" | "negative" | "warning" | "info"
+      >("neutral")
+      const [opacity, setOpacity] = useState<
+        "high" | "medium" | "low" | "none"
+      >("medium")
+      const [glass, setGlass] = useState<"high" | "medium" | "low" | "none">(
+        "none"
+      )
+      const [noise, setNoise] = useState<"high" | "medium" | "low" | "none">(
+        "none"
+      )
+      const [lastAction, setLastAction] = useState<string | null>(null)
+
+      const sides = ["left", "right", "top", "bottom"] as const
+      const variants = [
+        "neutral",
+        "positive",
+        "negative",
+        "warning",
+        "info",
+      ] as const
+      const levels = ["none", "low", "medium", "high"] as const
+
+      const btnCls = (active: boolean) =>
+        `font-fm-text text-fm-sm leading-fm-sm rounded px-2 py-1 outline-none transition-colors ${
+          active
+            ? "bg-fm-surface-contrast text-fm-contrast"
+            : "bg-fm-surface-secondary text-fm-secondary hover:text-fm-primary"
+        }`
+
+      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">
+                  Configuration
+                </p>
 
-                <div className="mt-8 space-y-4">
-                  <div className="bg-fm-surface-secondary rounded-lg p-4">
-                    <h4 className="text-fm-primary mb-2 text-sm font-medium">
-                      Quick Actions
-                    </h4>
-                    <div className="space-y-2">
-                      <Button
-                        size="sm"
-                        variant="outline"
-                        className="w-full justify-start"
-                      >
-                        <SearchIcon className="mr-2 h-4 w-4" />
-                        Search
-                      </Button>
-                      <Button
-                        size="sm"
-                        variant="outline"
-                        className="w-full justify-start"
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Side
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {sides.map((s) => (
+                      <button
+                        key={s}
+                        onClick={() => setSide(s)}
+                        className={btnCls(side === s)}
                       >
-                        <MagicBookIcon className="mr-2 h-4 w-4" />
-                        Help & Support
-                      </Button>
-                    </div>
+                        {s}
+                      </button>
+                    ))}
                   </div>
                 </div>
-              </div>
 
-              <SheetFooter>
-                <div className="w-full space-y-2">
-                  <div className="bg-fm-surface-secondary flex items-center gap-3 rounded-lg p-3">
-                    <div className="h-8 w-8 rounded-full bg-gradient-to-r from-blue-500 to-purple-500"></div>
-                    <div>
-                      <p className="text-fm-primary text-sm font-medium">
-                        John Doe
-                      </p>
-                      <p className="text-fm-secondary text-xs">
-                        john@example.com
-                      </p>
-                    </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">
+                    Variant
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {variants.map((v) => (
+                      <button
+                        key={v}
+                        onClick={() => setVariant(v)}
+                        className={btnCls(variant === v)}
+                      >
+                        {v}
+                      </button>
+                    ))}
                   </div>
-                  <SheetClose asChild>
-                    <Button variant="outline" className="w-full">
-                      Close Menu
-                    </Button>
-                  </SheetClose>
                 </div>
-              </SheetFooter>
-            </SheetContent>
-          </Sheet>
-
-          <h1 className="text-fm-primary text-lg font-semibold">App Title</h1>
 
-          <IconButton
-            variant="ghost"
-            icon={<MaintenanceIcon />}
-            label="Settings"
-          />
-        </div>
-      </div>
+                <div className="border-fm-divider-secondary border-t pt-4" />
 
-      {/* Add padding top to account for fixed header */}
-      <div className="pt-16">
-        <BackgroundContent />
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Mobile-style navigation sheet with menu items, badges, user profile, and quick actions demonstrating common mobile app patterns.",
-      },
-    },
-  },
-}
-
-// 3. Form Sheet
-export const FormSheet: Story = {
-  render: () => {
-    const [formData, setFormData] = useState({
-      name: "",
-      email: "",
-      subject: "",
-      message: "",
-      newsletter: false,
-    })
-
-    return (
-      <div className="relative">
-        <BackgroundContent />
-
-        <div className="fixed right-4 bottom-4 z-50">
-          <Sheet>
-            <SheetTrigger asChild>
-              <Button className="rounded-full shadow-lg">
-                <SearchIcon className="mr-2 h-4 w-4" />
-                Contact Us
-              </Button>
-            </SheetTrigger>
-            <SheetContent side="right" className="w-96">
-              <SheetHeader>
-                <SheetTitle>Contact Form</SheetTitle>
-                <SheetDescription>
-                  Send us a message and we'll get back to you soon.
-                </SheetDescription>
-              </SheetHeader>
-
-              <div className="py-4">
-                <form className="space-y-4">
-                  <div className="space-y-2">
-                    <Label htmlFor="name">Name</Label>
-                    <Input
-                      id="name"
-                      placeholder="Your full name"
-                      value={formData.name}
-                      onChange={(e: any) =>
-                        setFormData((prev) => ({
-                          ...prev,
-                          name: e.target.value,
-                        }))
-                      }
-                    />
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Opacity
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {levels.map((l) => (
+                      <button
+                        key={l}
+                        onClick={() => setOpacity(l)}
+                        className={btnCls(opacity === l)}
+                      >
+                        {l}
+                      </button>
+                    ))}
                   </div>
+                </div>
 
-                  <div className="space-y-2">
-                    <Label htmlFor="email">Email</Label>
-                    <Input
-                      id="email"
-                      type="email"
-                      placeholder="your.email@example.com"
-                      value={formData.email}
-                      onChange={(e: any) =>
-                        setFormData((prev) => ({
-                          ...prev,
-                          email: e.target.value,
-                        }))
-                      }
-                    />
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Glass
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {levels.map((l) => (
+                      <button
+                        key={l}
+                        onClick={() => setGlass(l)}
+                        className={btnCls(glass === l)}
+                      >
+                        {l}
+                      </button>
+                    ))}
                   </div>
+                </div>
 
-                  <div className="space-y-2">
-                    <Label htmlFor="subject">Subject</Label>
-                    <Input
-                      id="subject"
-                      placeholder="Message subject"
-                      value={formData.subject}
-                      onChange={(e: any) =>
-                        setFormData((prev) => ({
-                          ...prev,
-                          subject: e.target.value,
-                        }))
-                      }
-                    />
+                <div className="space-y-2">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Noise
+                  </p>
+                  <div className="flex flex-wrap gap-1">
+                    {levels.map((l) => (
+                      <button
+                        key={l}
+                        onClick={() => setNoise(l)}
+                        className={btnCls(noise === l)}
+                      >
+                        {l}
+                      </button>
+                    ))}
                   </div>
+                </div>
+              </div>
 
-                  <div className="space-y-2">
-                    <Label htmlFor="message">Message</Label>
-                    <Textarea
-                      id="message"
-                      placeholder="Your message..."
-                      rows={4}
-                      value={formData.message}
-                      onChange={(e: any) =>
-                        setFormData((prev) => ({
-                          ...prev,
-                          message: e.target.value,
-                        }))
-                      }
-                    />
-                  </div>
+              {/* Preview stage */}
+              <div className="flex flex-col gap-3 lg:col-span-2">
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary flex min-h-48 flex-col items-center justify-center gap-4 rounded-xl border p-8">
+                  {lastAction && (
+                    <div
+                      className={`rounded-lg border px-4 py-2 ${
+                        lastAction === "confirmed"
+                          ? "border-fm-divider-positive bg-fm-surface-positive-sec"
+                          : "border-fm-divider-secondary bg-fm-surface-secondary"
+                      }`}
+                    >
+                      <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                        Last action:{" "}
+                        <span className="text-fm-primary font-medium">
+                          {lastAction}
+                        </span>
+                      </p>
+                    </div>
+                  )}
 
-                  <div className="flex items-center space-x-2">
-                    <Checkbox
-                      id="newsletter"
-                      checked={formData.newsletter}
-                      onCheckedChange={(checked) =>
-                        setFormData((prev) => ({
-                          ...prev,
-                          newsletter: checked as boolean,
-                        }))
-                      }
-                    />
-                    <Label htmlFor="newsletter" className="text-sm">
-                      Subscribe to newsletter
-                    </Label>
-                  </div>
+                  <Sheet>
+                    <SheetTrigger asChild>
+                      <Button onClick={() => setLastAction(null)}>
+                        Open Sheet
+                      </Button>
+                    </SheetTrigger>
+                    <SheetContent
+                      side={side}
+                      variant={variant}
+                      opacity={opacity}
+                      glass={glass}
+                      noise={noise}
+                      container={null}
+                    >
+                      <SheetHeader>
+                        <SheetTitle>Sheet Preview</SheetTitle>
+                        <SheetDescription>
+                          Interact with content inside the sheet, then confirm
+                          or cancel.
+                        </SheetDescription>
+                      </SheetHeader>
+
+                      <div className="py-4">
+                        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                          <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                            {`side="${side}" variant="${variant}" opacity="${opacity}" glass="${glass}" noise="${noise}"`}
+                          </code>
+                        </div>
+                      </div>
 
-                  <div className="bg-fm-surface-info-sec rounded-lg p-3">
-                    <p className="text-fm-info text-xs">
-                      We typically respond within 24 hours. For urgent matters,
-                      please call our support line.
-                    </p>
-                  </div>
-                </form>
-              </div>
+                      <SheetFooter>
+                        <Button
+                          variant="outline"
+                          onClick={() => setLastAction("cancelled")}
+                        >
+                          Cancel
+                        </Button>
+                        <SheetClose asChild>
+                          <Button onClick={() => setLastAction("confirmed")}>
+                            Confirm
+                          </Button>
+                        </SheetClose>
+                      </SheetFooter>
+                    </SheetContent>
+                  </Sheet>
+                </div>
 
-              <SheetFooter>
-                <div className="flex w-full gap-2">
-                  <SheetClose asChild>
-                    <Button variant="outline" className="flex-1">
-                      Cancel
-                    </Button>
-                  </SheetClose>
-                  <Button
-                    className="flex-1"
-                    disabled={
-                      !formData.name || !formData.email || !formData.message
-                    }
-                  >
-                    Send Message
-                  </Button>
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border px-4 py-3">
+                  <code className="text-fm-secondary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                    {`<SheetContent side="${side}" variant="${variant}" opacity="${opacity}" glass="${glass}" noise="${noise}" />`}
+                  </code>
                 </div>
-              </SheetFooter>
-            </SheetContent>
-          </Sheet>
+              </div>
+            </div>
+          </div>
         </div>
-      </div>
-    )
+      )
+    }
+
+    return <InteractiveDemo />
   },
   parameters: {
     docs: {
       description: {
         story:
-          "Contact form sheet with form validation, checkbox input, and user feedback elements.",
+          "Live configurator — pick side, variant, opacity, glass, and noise, then open the sheet and confirm or cancel to see state feedback.",
       },
     },
   },
 }
 
-// 4. Settings Panel Sheet
-export const SettingsPanelSheet: Story = {
-  render: () => {
-    const [settings, setSettings] = useState({
-      notifications: true,
-      darkMode: true,
-      analytics: false,
-      autoSave: true,
-      emailUpdates: false,
-    })
-
-    const toggleSetting = (key: string) => {
-      setSettings((prev) => ({
-        ...prev,
-        [key]: !prev[key as keyof typeof prev],
-      }))
-    }
-
-    return (
-      <div className="relative">
-        <BackgroundContent />
-
-        <div className="fixed top-4 right-4 z-50">
-          <Sheet>
-            <SheetTrigger asChild>
-              <Button variant="outline">
-                <MaintenanceIcon className="mr-2 h-4 w-4" />
-                Settings
-              </Button>
-            </SheetTrigger>
-            <SheetContent side="right" className="w-80">
-              <SheetHeader>
-                <SheetTitle>Application Settings</SheetTitle>
-                <SheetDescription>
-                  Customize your experience and preferences
-                </SheetDescription>
-              </SheetHeader>
-
-              <div className="py-4">
-                <div className="space-y-6">
-                  {/* Notifications Section */}
-                  <div className="space-y-3">
-                    <h4 className="text-fm-primary text-sm font-medium">
-                      Notifications
-                    </h4>
-                    <div className="space-y-3">
-                      <div className="flex items-center justify-between">
-                        <span className="text-fm-primary text-sm">
-                          Push Notifications
-                        </span>
-                        <Checkbox
-                          checked={settings.notifications}
-                          onCheckedChange={() => toggleSetting("notifications")}
-                        />
-                      </div>
-
-                      <div className="flex items-center justify-between">
-                        <span className="text-fm-primary text-sm">
-                          Email Updates
-                        </span>
-                        <Checkbox
-                          checked={settings.emailUpdates}
-                          onCheckedChange={() => toggleSetting("emailUpdates")}
-                        />
-                      </div>
-
-                      <div className="flex items-center justify-between">
-                        <span className="text-fm-primary text-sm">
-                          Analytics
-                        </span>
-                        <Checkbox
-                          checked={settings.analytics}
-                          onCheckedChange={() => toggleSetting("analytics")}
-                        />
-                      </div>
-                    </div>
-                  </div>
+// ─── UseCases ─────────────────────────────────────────────────────────────────
 
-                  {/* Appearance Section */}
-                  <div className="space-y-3">
-                    <h4 className="text-fm-primary text-sm font-medium">
-                      Appearance
-                    </h4>
-                    <div className="space-y-3">
-                      <div className="flex items-center justify-between">
-                        <span className="text-fm-primary text-sm">
-                          Dark Mode
-                        </span>
-                        <Checkbox
-                          checked={settings.darkMode}
-                          onCheckedChange={() => toggleSetting("darkMode")}
-                        />
-                      </div>
+export const UseCases: Story = {
+  render: () => {
+    // Left: Filter panel
+    const FilterPanel = () => {
+      const [genre, setGenre] = useState<string[]>([])
+      const [mood, setMood] = useState<string[]>([])
+
+      const toggleFilter = (
+        list: string[],
+        set: (v: string[]) => void,
+        item: string
+      ) => {
+        set(
+          list.includes(item) ? list.filter((i) => i !== item) : [...list, item]
+        )
+      }
+
+      const genres = ["Lo-fi", "Jazz", "Electronic", "Acoustic", "Classical"]
+      const moods = ["Chill", "Focus", "Energetic", "Melancholic"]
+
+      return (
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="outline" size="sm">
+              Filter panel
+            </Button>
+          </SheetTrigger>
+          <SheetContent side="left" variant="neutral" container={null}>
+            <SheetHeader>
+              <SheetTitle>Filter Tracks</SheetTitle>
+              <SheetDescription>
+                Narrow your library by genre and mood.
+              </SheetDescription>
+            </SheetHeader>
+
+            <div className="space-y-6 py-4">
+              <div className="space-y-3">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  Genre
+                </p>
+                <div className="space-y-2">
+                  {genres.map((g) => (
+                    <div key={g} className="flex items-center gap-3">
+                      <Checkbox
+                        id={`genre-${g}`}
+                        checked={genre.includes(g)}
+                        onCheckedChange={() => toggleFilter(genre, setGenre, g)}
+                      />
+                      <Label
+                        htmlFor={`genre-${g}`}
+                        className="text-fm-primary font-fm-text text-fm-md leading-fm-md"
+                      >
+                        {g}
+                      </Label>
                     </div>
-                  </div>
-
-                  {/* Advanced Section */}
-                  <div className="space-y-3">
-                    <h4 className="text-fm-primary text-sm font-medium">
-                      Advanced
-                    </h4>
-                    <div className="space-y-3">
-                      <div className="flex items-center justify-between">
-                        <span className="text-fm-primary text-sm">
-                          Auto Save
-                        </span>
-                        <Checkbox
-                          checked={settings.autoSave}
-                          onCheckedChange={() => toggleSetting("autoSave")}
-                        />
-                      </div>
+                  ))}
+                </div>
+              </div>
 
-                      <Button variant="outline" size="sm" className="w-full">
-                        <FileChartIcon className="mr-2 h-4 w-4" />
-                        Clear Cache
-                      </Button>
+              <div className="border-fm-divider-secondary border-t" />
 
-                      <Button variant="outline" size="sm" className="w-full">
-                        <ArrowRightIcon className="mr-2 h-4 w-4" />
-                        Export Data
-                      </Button>
+              <div className="space-y-3">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  Mood
+                </p>
+                <div className="space-y-2">
+                  {moods.map((m) => (
+                    <div key={m} className="flex items-center gap-3">
+                      <Checkbox
+                        id={`mood-${m}`}
+                        checked={mood.includes(m)}
+                        onCheckedChange={() => toggleFilter(mood, setMood, m)}
+                      />
+                      <Label
+                        htmlFor={`mood-${m}`}
+                        className="text-fm-primary font-fm-text text-fm-md leading-fm-md"
+                      >
+                        {m}
+                      </Label>
                     </div>
-                  </div>
+                  ))}
                 </div>
               </div>
 
-              <SheetFooter>
-                <div className="flex w-full gap-2">
-                  <Button variant="outline" size="sm" className="flex-1">
-                    Reset
-                  </Button>
-                  <SheetClose asChild>
-                    <Button size="sm" className="flex-1">
-                      Save Changes
-                    </Button>
-                  </SheetClose>
+              {(genre.length > 0 || mood.length > 0) && (
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-3">
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Active filters:{" "}
+                    <span className="text-fm-primary font-medium">
+                      {[...genre, ...mood].join(", ")}
+                    </span>
+                  </p>
                 </div>
-              </SheetFooter>
-            </SheetContent>
-          </Sheet>
-        </div>
-      </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Settings panel sheet with checkboxes, sections, and action buttons demonstrating configuration interfaces.",
-      },
-    },
-  },
-}
+              )}
+            </div>
 
-// 5. Overlay Variations
-export const OverlayVariations: Story = {
-  render: () => (
-    <div className="relative">
-      <BackgroundContent />
+            <SheetFooter>
+              <Button
+                variant="outline"
+                onClick={() => {
+                  setGenre([])
+                  setMood([])
+                }}
+              >
+                Clear all
+              </Button>
+              <SheetClose asChild>
+                <Button>Apply filters</Button>
+              </SheetClose>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+      )
+    }
 
-      <div className="fixed bottom-4 left-1/2 z-50 -translate-x-1/2 transform">
-        <div className="space-y-2 rounded-lg bg-black/80 p-4 backdrop-blur-sm">
-          <h3 className="text-fm-primary text-center text-sm font-medium">
-            Overlay Variations
-          </h3>
-          <div className="flex gap-2">
-            {/* Low Opacity */}
-            <Sheet>
-              <SheetTrigger asChild>
-                <Button size="sm" variant="outline">
-                  Low Opacity
-                </Button>
-              </SheetTrigger>
-              <SheetContent side="right" opacity="low">
-                <SheetHeader>
-                  <SheetTitle>Low Opacity</SheetTitle>
-                  <SheetDescription>
-                    Subtle background overlay that maintains visibility
-                  </SheetDescription>
-                </SheetHeader>
-                <div className="py-4">
-                  <p className="text-fm-secondary text-sm">
-                    This sheet uses low opacity overlay, allowing more of the
-                    background content to remain visible.
-                  </p>
-                </div>
-              </SheetContent>
-            </Sheet>
+    // Right: Track details
+    const TrackDetails = () => {
+      const [liked, setLiked] = useState(false)
+      const [queued, setQueued] = useState(false)
 
-            {/* High Opacity */}
-            <Sheet>
-              <SheetTrigger asChild>
-                <Button size="sm" variant="outline">
-                  High Opacity
-                </Button>
-              </SheetTrigger>
-              <SheetContent side="right" opacity="high">
-                <SheetHeader>
-                  <SheetTitle>High Opacity</SheetTitle>
-                  <SheetDescription>
-                    Strong background overlay for maximum focus
-                  </SheetDescription>
-                </SheetHeader>
-                <div className="py-4">
-                  <p className="text-fm-secondary text-sm">
-                    This sheet uses high opacity overlay, creating strong focus
-                    on the sheet content by dimming the background
-                    significantly.
-                  </p>
-                </div>
-              </SheetContent>
-            </Sheet>
+      return (
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="outline" size="sm">
+              Track details
+            </Button>
+          </SheetTrigger>
+          <SheetContent side="right" variant="info" container={null}>
+            <SheetHeader>
+              <SheetTitle>Midnight Drive</SheetTitle>
+              <SheetDescription>
+                Lo-fi Chill · Album: Late Nights · 3:42
+              </SheetDescription>
+            </SheetHeader>
+
+            <div className="space-y-4 py-4">
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm mb-3 font-semibold tracking-widest uppercase">
+                  About this track
+                </p>
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+                  A smooth lo-fi track perfect for late-night focus sessions.
+                  Released in 2024 as part of the Late Nights collection.
+                </p>
+              </div>
 
-            {/* Glass Effect */}
-            <Sheet>
-              <SheetTrigger asChild>
-                <Button size="sm" variant="outline">
-                  Glass Effect
-                </Button>
-              </SheetTrigger>
-              <SheetContent side="right" glass="high">
-                <SheetHeader>
-                  <SheetTitle>Glass Effect</SheetTitle>
-                  <SheetDescription>
-                    Frosted glass overlay for modern aesthetics
-                  </SheetDescription>
-                </SheetHeader>
-                <div className="py-4">
-                  <p className="text-fm-secondary text-sm">
-                    This sheet includes a glass effect with backdrop blur,
-                    creating a modern frosted glass appearance.
-                  </p>
-                </div>
-              </SheetContent>
-            </Sheet>
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary space-y-3 rounded-lg border p-4">
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  Track info
+                </p>
+                {[
+                  { label: "Artist", value: "Chill Collective" },
+                  { label: "BPM", value: "85" },
+                  { label: "Key", value: "F Minor" },
+                  { label: "Plays", value: "124,381" },
+                ].map((row) => (
+                  <div
+                    key={row.label}
+                    className="flex items-center justify-between"
+                  >
+                    <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                      {row.label}
+                    </span>
+                    <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium">
+                      {row.value}
+                    </span>
+                  </div>
+                ))}
+              </div>
 
-            {/* Noise Texture */}
-            <Sheet>
-              <SheetTrigger asChild>
-                <Button size="sm" variant="outline">
-                  Noise Texture
+              <div className="flex gap-2">
+                <Button
+                  variant="outline"
+                  size="sm"
+                  className="flex-1 gap-2"
+                  onClick={() => setLiked((v) => !v)}
+                >
+                  <TickCircleIcon className="h-4 w-4" />
+                  {liked ? "Liked" : "Like"}
                 </Button>
-              </SheetTrigger>
-              <SheetContent side="right" noise="medium">
-                <SheetHeader>
-                  <SheetTitle>Noise Texture</SheetTitle>
-                  <SheetDescription>
-                    Textured overlay for enhanced visual depth
-                  </SheetDescription>
-                </SheetHeader>
-                <div className="py-4">
-                  <p className="text-fm-secondary text-sm">
-                    This sheet includes noise texture overlay, adding visual
-                    interest and depth to the background.
-                  </p>
-                </div>
-              </SheetContent>
-            </Sheet>
-          </div>
-        </div>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Different overlay configurations showing opacity levels, glass effects, and noise textures for various visual requirements.",
-      },
-    },
-  },
-}
+                <Button
+                  variant="outline"
+                  size="sm"
+                  className="flex-1 gap-2"
+                  onClick={() => setQueued((v) => !v)}
+                >
+                  <MusicalNoteIcon className="h-4 w-4" />
+                  {queued ? "In queue" : "Add to queue"}
+                </Button>
+              </div>
+            </div>
 
-// 6. Mobile Bottom Sheet
-export const MobileBottomSheet: Story = {
-  render: () => {
-    const [selectedOption, setSelectedOption] = useState<string | null>(null)
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button variant="outline">Close</Button>
+              </SheetClose>
+              <Button>Play now</Button>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+      )
+    }
 
-    return (
-      <div className="relative">
-        <BackgroundContent />
+    // Bottom: Quick action sheet
+    const QuickActions = () => {
+      const [search, setSearch] = useState("")
+      const actions = [
+        { label: "Add to playlist", icon: MusicalNoteIcon },
+        { label: "Go to artist", icon: ChevronRightIcon },
+        { label: "Find similar tracks", icon: SearchIcon },
+        { label: "Report issue", icon: AlertIcon },
+        { label: "Share", icon: SiteLogoIcon },
+        { label: "Settings", icon: MaintenanceIcon },
+      ]
+      const filtered = actions.filter((a) =>
+        a.label.toLowerCase().includes(search.toLowerCase())
+      )
+
+      return (
+        <Sheet>
+          <SheetTrigger asChild>
+            <Button variant="outline" size="sm">
+              Quick actions
+            </Button>
+          </SheetTrigger>
+          <SheetContent side="bottom" variant="neutral" container={null}>
+            <SheetHeader>
+              <SheetTitle>Quick Actions</SheetTitle>
+              <SheetDescription>
+                Search and pick an action for this track.
+              </SheetDescription>
+            </SheetHeader>
+
+            <div className="space-y-4 py-4">
+              <Input
+                placeholder="Search actions..."
+                value={search}
+                onChange={(e) => setSearch(e.target.value)}
+              />
+              <div className="space-y-1">
+                {filtered.length === 0 && (
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm py-2 text-center">
+                    No actions match your search.
+                  </p>
+                )}
+                {filtered.map((action) => (
+                  <button
+                    key={action.label}
+                    className="text-fm-primary hover:bg-fm-surface-secondary flex w-full items-center gap-3 rounded-lg px-3 py-3 text-left transition-colors"
+                  >
+                    <action.icon className="text-fm-secondary h-5 w-5 shrink-0" />
+                    <span className="font-fm-text text-fm-md leading-fm-md">
+                      {action.label}
+                    </span>
+                  </button>
+                ))}
+              </div>
+            </div>
 
-        {/* Simulate mobile content */}
-        <div className="fixed bottom-4 left-1/2 z-50 -translate-x-1/2 transform">
-          <Sheet>
-            <SheetTrigger asChild>
-              <Button>Share Options</Button>
-            </SheetTrigger>
-            <SheetContent side="bottom" className="h-auto max-h-96">
-              <SheetHeader>
-                <SheetTitle>Share</SheetTitle>
-                <SheetDescription>
-                  Choose how you'd like to share this content
-                </SheetDescription>
-              </SheetHeader>
+            <SheetFooter>
+              <SheetClose asChild>
+                <Button variant="outline" className="w-full">
+                  Dismiss
+                </Button>
+              </SheetClose>
+            </SheetFooter>
+          </SheetContent>
+        </Sheet>
+      )
+    }
 
-              <div className="py-4">
-                <div className="mb-6 grid grid-cols-4 gap-4">
-                  {[
-                    { name: "Message", icon: SearchIcon },
-                    { name: "Email", icon: AlertIcon },
-                    { name: "Copy Link", icon: TickCircleIcon },
-                    { name: "More", icon: SiteLogoIcon },
-                  ].map((option) => (
-                    <button
-                      key={option.name}
-                      onClick={() => setSelectedOption(option.name)}
-                      className={`flex flex-col items-center gap-2 rounded-lg p-3 transition-colors ${
-                        selectedOption === option.name
-                          ? "bg-fm-surface-info-sec text-fm-info"
-                          : "text-fm-primary hover:bg-fm-surface-secondary"
-                      }`}
-                    >
-                      <option.icon className="h-6 w-6" />
-                      <span className="text-xs">{option.name}</span>
-                    </button>
-                  ))}
-                </div>
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Filter Panel — Left Side
+          </h4>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+            A left-side filter panel for narrowing a music library by genre and
+            mood. Selected filters are summarised and can be cleared.
+          </p>
+          <FilterPanel />
+        </div>
 
-                <div className="space-y-2">
-                  <h4 className="text-fm-primary text-sm font-medium">
-                    Recent Contacts
-                  </h4>
-                  {Array.from({ length: 3 }, (_, i) => (
-                    <div
-                      key={i}
-                      className="hover:bg-fm-surface-secondary flex items-center gap-3 rounded-lg p-2"
-                    >
-                      <div className="h-8 w-8 rounded-full bg-gradient-to-r from-blue-500 to-purple-500"></div>
-                      <span className="text-fm-primary text-sm">
-                        Contact {i + 1}
-                      </span>
-                    </div>
-                  ))}
-                </div>
-              </div>
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Track Details — Right Side
+          </h4>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+            A right-side detail panel showing metadata, stats, and contextual
+            actions for the currently selected track.
+          </p>
+          <TrackDetails />
+        </div>
 
-              <SheetFooter>
-                <SheetClose asChild>
-                  <Button variant="outline" className="w-full">
-                    Cancel
-                  </Button>
-                </SheetClose>
-              </SheetFooter>
-            </SheetContent>
-          </Sheet>
+        <div className="space-y-3">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Quick Action Sheet — Bottom
+          </h4>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-xl">
+            A searchable bottom action sheet for quickly finding and triggering
+            contextual commands on a track.
+          </p>
+          <QuickActions />
         </div>
       </div>
     )
@@ -1067,7 +788,7 @@ export const MobileBottomSheet: Story = {
     docs: {
       description: {
         story:
-          "Mobile-style bottom sheet with share options and contact list, demonstrating common mobile interaction patterns.",
+          "Three realistic product scenarios: a left filter panel for library browsing, a right track-details panel, and a searchable bottom quick-action sheet.",
       },
     },
   },