aural-ui 4.0.1 → 4.2.0

package/dist/components/popover/Popover.stories.tsx

@@ -1,10 +1,10 @@
-import React from "react"
+import React, { useState } from "react"
 import { Button } from "@components/button"
 import Input from "@components/input"
 import { Label } from "@components/label"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
-import { FeatureShineIcon } from "src/ui/icons"
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
 
 import {
   Popover,
@@ -14,43 +14,35 @@ import {
   PopoverContent,
   PopoverTrigger,
 } from "."
-import { IconButton } from "../icon-button"
 
 const meta: Meta<typeof Popover> = {
   title: "Components/UI/Popover",
   component: Popover,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-A comprehensive popover component system built on Radix UI with dark theme optimization.
-
-## Components Overview
-
-- **Popover**: Root container managing state and context
-- **PopoverTrigger**: Interactive element that opens the popover
-- **PopoverContent**: The floating content panel with frosted glass effect
-- **PopoverAnchor**: Custom positioning anchor point
-- **PopoverArrow**: Optional arrow pointer to trigger
-- **PopoverClose**: Button to close popover from within content
-
-## Features
-- Dark theme optimized with frosted glass effect
-- Smooth CSS animations with direction awareness
-- Comprehensive accessibility support
-- Flexible positioning and anchoring
-- Self-contained content management
-- Portal rendering for proper stacking
-        `,
+        component:
+          "A compound floating panel built on Radix UI. Composed of Popover (root state), PopoverTrigger (toggle element), PopoverContent (frosted-glass panel with gradient top stroke), PopoverClose (dismiss button inside content), PopoverArrow (optional pointer), and PopoverAnchor (custom positioning reference). Portal-rendered for proper z-index stacking.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Floating Panel",
+              description: "Portal z-index layering",
+            },
+            {
+              title: "Compound Parts",
+              description: "Trigger, content, arrow",
+            },
+            {
+              title: "Glass Aesthetic",
+              description: "Frosted top gradient",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -59,1005 +51,598 @@ A comprehensive popover component system built on Radix UI with dark theme optim
 export default meta
 type Story = StoryObj<typeof meta>
 
-// 1. Popover Root Component Example
-export const PopoverRoot: Story = {
-  render: () => (
-    <div className="space-y-4">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Popover Root Component
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          The root Popover component manages state and provides context
-        </p>
-      </div>
-
-      <div className="flex justify-center gap-4">
-        {/* Uncontrolled Popover */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Uncontrolled</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-4">
-              <p className="text-fm-primary text-sm">
-                This popover manages its own open/close state internally.
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
+// ─── Parts ───────────────────────────────────────────────────────────────────
 
-        {/* Controlled Popover */}
-        <Popover defaultOpen={false}>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Default Closed</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-4">
-              <p className="text-fm-primary text-sm">
-                This popover starts in a closed state by default.
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Modal Popover */}
-        <Popover modal>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Modal Mode</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-4">
-              <p className="text-fm-primary text-sm">
-                This is a modal popover that captures focus and blocks
-                interaction.
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-      </div>
-    </div>
-  ),
+export const Parts: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "The Popover root component with different configuration options: uncontrolled, default state, and modal behavior.",
+          "Every sub-component shown individually with a description of its role in the compound pattern.",
       },
     },
   },
-}
-
-// 2. PopoverTrigger Component Examples
-export const PopoverTriggerVariants: Story = {
   render: () => (
-    <div className="space-y-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          PopoverTrigger Variants
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different types of trigger elements using asChild prop
-        </p>
-      </div>
-
-      <div className="grid grid-cols-2 gap-4">
-        {/* Button Trigger */}
+    <div className="w-full max-w-2xl space-y-10">
+      {/* PopoverTrigger */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PopoverTrigger
+        </h4>
         <Popover>
           <PopoverTrigger asChild>
-            <Button>Button Trigger</Button>
+            <Button variant="outline">Open Popover</Button>
           </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Triggered by a Button component
-              </p>
-            </div>
+          <PopoverContent className="rounded-lg p-4">
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+              Triggered by the button above.
+            </p>
           </PopoverContent>
         </Popover>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            The element that toggles the popover open/closed. Pass{" "}
+            <code>asChild</code> to render as any child element. Without{" "}
+            <code>asChild</code> it renders a plain <code>&lt;button&gt;</code>.
+          </p>
+        </div>
+      </div>
 
-        {/* Text Link Trigger */}
-        <Popover>
+      {/* PopoverContent */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PopoverContent
+        </h4>
+        <Popover defaultOpen>
           <PopoverTrigger asChild>
-            <Button
-              variant="text"
-              className="text-fm-info hover:text-fm-info-sec text-sm underline"
-            >
-              Click this link
-            </Button>
+            <Button variant="outline">Content panel (open)</Button>
           </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Triggered by a text link
-              </p>
-            </div>
+          <PopoverContent className="rounded-lg p-4">
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+              Frosted-glass panel with a gradient top stroke. Default width{" "}
+              <code>w-72</code>, max height <code>max-h-96</code>. Rendered in a
+              portal — safe across any stacking context.
+            </p>
           </PopoverContent>
         </Popover>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            Accepts <code>align</code> (start / center / end), <code>side</code>{" "}
+            (top / right / bottom / left), and <code>sideOffset</code>. The
+            gradient top-stroke is always rendered automatically.
+          </p>
+        </div>
+      </div>
 
-        {/* Icon Trigger */}
-        <Popover>
+      {/* PopoverClose */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PopoverClose
+        </h4>
+        <Popover defaultOpen>
           <PopoverTrigger asChild>
-            <IconButton
-              label="Icon Popover Button"
-              icon={<FeatureShineIcon />}
-            />
+            <Button variant="outline">Open (with close button)</Button>
           </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Triggered by an icon button
+          <PopoverContent className="rounded-lg p-4">
+            <div className="flex items-center justify-between gap-4">
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                Click × to dismiss.
               </p>
+              <PopoverClose asChild>
+                <Button variant="text" size="sm">
+                  ×
+                </Button>
+              </PopoverClose>
             </div>
           </PopoverContent>
         </Popover>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            Closes the popover from within the content panel. Use with{" "}
+            <code>asChild</code> to render as any button or icon. Must be placed
+            inside <code>PopoverContent</code>.
+          </p>
+        </div>
+      </div>
 
-        {/* Image Trigger */}
-        <Popover>
+      {/* PopoverArrow */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PopoverArrow
+        </h4>
+        <Popover defaultOpen>
           <PopoverTrigger asChild>
-            <IconButton
-              label="Profile Popover"
-              icon={null}
-              className="overflow-hidden"
-            >
-              <img
-                src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=40&h=40&fit=crop&crop=face"
-                alt="Profile"
-                className="h-12 w-12 object-cover"
-              />
-            </IconButton>
+            <Button variant="outline">Open (with arrow)</Button>
           </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Triggered by an avatar image
-              </p>
-            </div>
+          <PopoverContent className="rounded-lg p-4" sideOffset={8}>
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+              An arrow points back at the trigger.
+            </p>
+            <PopoverArrow className="fill-fm-surface-frosted/20" />
           </PopoverContent>
         </Popover>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            Optional SVG arrow rendered inside <code>PopoverContent</code>.
+            Inherits positioning from the content and rotates automatically
+            based on side.
+          </p>
+        </div>
+      </div>
+
+      {/* PopoverAnchor */}
+      <div className="space-y-3">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          PopoverAnchor
+        </h4>
+        <Popover defaultOpen>
+          <div className="flex items-center gap-4">
+            <PopoverAnchor asChild>
+              <div className="border-fm-divider-secondary rounded-lg border px-4 py-2">
+                <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                  Anchor element
+                </span>
+              </div>
+            </PopoverAnchor>
+            <PopoverTrigger asChild>
+              <Button variant="outline" size="sm">
+                Trigger
+              </Button>
+            </PopoverTrigger>
+          </div>
+          <PopoverContent className="rounded-lg p-4">
+            <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+              Positioned relative to the anchor box, not the trigger.
+            </p>
+          </PopoverContent>
+        </Popover>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+          <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-xl">
+            Decouples the visual anchor from the trigger. The popover positions
+            itself relative to <code>PopoverAnchor</code> while the trigger
+            retains click behavior. Useful for inline text flows or custom
+            layouts.
+          </p>
+        </div>
       </div>
     </div>
   ),
+}
+
+// ─── Configurations ──────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "PopoverTrigger examples showing different interactive elements: buttons, links, icons, and images.",
+          "Positioning axes (side + align), sideOffset values, with close button, with arrow, and the anchored variant — all as live examples.",
       },
     },
   },
-}
-
-// 3. PopoverContent Component Examples
-export const PopoverContentVariants: Story = {
   render: () => (
-    <div className="space-y-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          PopoverContent Variants
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different content layouts and styling options
-        </p>
-      </div>
-
-      <div className="flex flex-wrap justify-center gap-4">
-        {/* Simple Content */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline" size="sm">
-              Simple Content
-            </Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-56 rounded-lg border shadow-2xl">
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Simple text content in a popover.
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Rich Content */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline" size="sm">
-              Rich Content
-            </Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-72 rounded-lg border shadow-2xl">
-            <div className="space-y-3 p-4">
-              <div className="flex items-center gap-3">
-                <div className="flex h-10 w-10 items-center justify-center rounded-full bg-blue-600">
-                  <span className="text-fm-primary text-sm font-medium">
-                    JD
-                  </span>
-                </div>
-                <div>
-                  <h4 className="text-fm-primary font-medium">John Doe</h4>
-                  <p className="text-fm-secondary text-xs">
-                    Software Developer
+    <div className="w-full max-w-3xl space-y-8">
+      {/* Side positioning */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Side — side prop
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          {(["top", "right", "bottom", "left"] as const).map((side) => (
+            <div key={side} className="space-y-2 text-center">
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button variant="outline" size="sm">
+                    {side}
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent side={side} className="w-40 rounded-lg p-3">
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                    Opens to the <strong>{side}</strong>.
                   </p>
-                </div>
-              </div>
-              <p className="text-fm-secondary text-sm">
-                Rich content with avatar, title, and description.
+                </PopoverContent>
+              </Popover>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                {side}
               </p>
             </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Custom Styled Content */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline" size="sm">
-              Custom Style
-            </Button>
-          </PopoverTrigger>
-          <PopoverContent className="w-64 rounded-lg border border-purple-500/30 bg-gradient-to-b from-purple-900/90 to-blue-900/90 shadow-2xl">
-            <div className="p-4">
-              <h4 className="text-fm-primary mb-2 font-medium">Custom Theme</h4>
-              <p className="text-fm-secondary text-sm">
-                PopoverContent with custom gradient background and purple theme.
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
+          ))}
+        </div>
+      </div>
 
-        {/* No Border Content */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline" size="sm">
-              No Border
-            </Button>
-          </PopoverTrigger>
-          <PopoverContent className="bg-fm-surface-primary w-56 rounded-xl shadow-2xl">
-            <div className="p-4">
-              <p className="text-fm-primary text-sm">
-                Content without border, just shadow and background.
+      {/* Alignment */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Alignment — align prop
+        </h4>
+        <div className="flex flex-wrap justify-center gap-4">
+          {(["start", "center", "end"] as const).map((align) => (
+            <div key={align} className="space-y-2 text-center">
+              <Popover>
+                <PopoverTrigger asChild>
+                  <Button variant="outline" size="sm">
+                    {align}
+                  </Button>
+                </PopoverTrigger>
+                <PopoverContent align={align} className="rounded-lg p-3">
+                  <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                    Aligned <strong>{align}</strong> to trigger.
+                  </p>
+                </PopoverContent>
+              </Popover>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                {align}
               </p>
             </div>
-          </PopoverContent>
-        </Popover>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "PopoverContent examples with different styling approaches: simple, rich content, custom themes, and borderless variants.",
-      },
-    },
-  },
-}
-
-// 4. PopoverAnchor Component Example
-export const PopoverAnchorExample: Story = {
-  render: () => {
-    const [anchorEl, setAnchorEl] = React.useState<HTMLDivElement | null>(null)
-
-    return (
-      <div className="space-y-6">
-        <div className="text-center">
-          <h3 className="text-fm-primary mb-2 font-medium">
-            PopoverAnchor Component
-          </h3>
-          <p className="text-fm-secondary text-sm">
-            Position popover relative to a different element than the trigger
-          </p>
+          ))}
         </div>
+      </div>
 
-        <div className="flex items-center justify-center gap-8">
-          {/* Anchor Target */}
-          <div
-            ref={setAnchorEl}
-            className="flex h-20 w-20 items-center justify-center rounded-lg border-2 border-dashed border-blue-400 bg-gradient-to-br from-blue-500 to-purple-600"
-          >
-            <span className="text-fm-primary text-center text-xs font-medium">
-              Anchor
-              <br />
-              Point
-            </span>
-          </div>
-
-          {/* Trigger (separate from anchor) */}
+      {/* With close button */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With Close Button
+        </h4>
+        <div className="flex justify-center">
           <Popover>
-            <PopoverAnchor
-              style={{
-                position: "absolute",
-                left: anchorEl?.offsetLeft || 0,
-                top: anchorEl?.offsetTop || 0,
-                width: anchorEl?.offsetWidth || 0,
-                height: anchorEl?.offsetHeight || 0,
-              }}
-            />
             <PopoverTrigger asChild>
-              <Button variant="outline">Open at Anchor</Button>
+              <Button variant="outline">Open panel</Button>
             </PopoverTrigger>
-            <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-              <PopoverArrow className="fill-white/10" />
-              <div className="space-y-2 p-4">
-                <h4 className="text-fm-primary font-medium">
-                  Anchored Popover
-                </h4>
-                <p className="text-fm-secondary text-sm">
-                  This popover is positioned relative to the blue anchor box,
-                  not the trigger button.
-                </p>
-                <div className="bg-fm-surface-secondary text-fm-tertiary rounded p-2 text-xs">
-                  <strong>Note:</strong> The popover appears near the anchor
-                  point even though the trigger is elsewhere.
+            <PopoverContent className="w-64 rounded-lg p-4">
+              <div className="flex items-start justify-between gap-3">
+                <div className="space-y-1">
+                  <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-semibold">
+                    Quick note
+                  </p>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Dismiss with the × button.
+                  </p>
                 </div>
+                <PopoverClose asChild>
+                  <button className="text-fm-tertiary hover:text-fm-primary text-lg leading-none transition-colors outline-none">
+                    ×
+                  </button>
+                </PopoverClose>
               </div>
             </PopoverContent>
           </Popover>
         </div>
-
-        {/* Multiple Anchors Example */}
-        <div className="mt-8">
-          <h4 className="text-fm-primary mb-4 text-center font-medium">
-            Multiple Anchor Points
-          </h4>
-          <div className="flex justify-center gap-4">
-            {["Anchor A", "Anchor B", "Anchor C"].map((label) => {
-              const [anchor, setAnchor] = React.useState<HTMLDivElement | null>(
-                null
-              )
-
-              return (
-                <div key={label} className="space-y-2 text-center">
-                  <div
-                    ref={setAnchor}
-                    className="flex h-16 w-16 items-center justify-center rounded-lg border border-green-400 bg-green-600"
-                  >
-                    <span className="text-fm-primary text-xs font-medium">
-                      {label}
-                    </span>
-                  </div>
-
-                  <Popover>
-                    <PopoverAnchor
-                      style={{
-                        position: "absolute",
-                        left: anchor?.offsetLeft || 0,
-                        top: anchor?.offsetTop || 0,
-                        width: anchor?.offsetWidth || 0,
-                        height: anchor?.offsetHeight || 0,
-                      }}
-                    />
-                    <PopoverTrigger asChild>
-                      <Button size="sm" variant="outline">
-                        Open {label}
-                      </Button>
-                    </PopoverTrigger>
-                    <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-                      <div className="p-3">
-                        <p className="text-fm-primary text-sm">
-                          Content for {label}
-                        </p>
-                      </div>
-                    </PopoverContent>
-                  </Popover>
-                </div>
-              )
-            })}
-          </div>
-        </div>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "PopoverAnchor examples showing how to position popovers relative to different elements than their triggers, including single and multiple anchor scenarios.",
-      },
-    },
-  },
-}
 
-// 5. PopoverArrow Component Examples
-export const PopoverArrowVariants: Story = {
-  render: () => (
-    <div className="space-y-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          PopoverArrow Variants
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different arrow styles and positioning options
-        </p>
-      </div>
-
-      <div className="grid grid-cols-2 gap-6">
-        {/* Default Arrow */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Default Arrow</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Default semi-transparent arrow
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Solid Arrow */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Solid Arrow</Button>
-          </PopoverTrigger>
-          <PopoverContent className="bg-fm-surface-primary rounded-lg border border-gray-600 shadow-2xl">
-            <PopoverArrow className="fill-gray-800" />
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Solid arrow matching background
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Colored Arrow */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Colored Arrow</Button>
-          </PopoverTrigger>
-          <PopoverContent className="rounded-lg border border-blue-700 bg-blue-900 shadow-2xl">
-            <PopoverArrow className="fill-blue-700" />
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Colored arrow with theme accent
-              </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Large Arrow */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Large Arrow</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <PopoverArrow className="h-4 w-4 fill-white/10" />
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">Larger arrow size</p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Gradient Arrow */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Gradient Arrow</Button>
-          </PopoverTrigger>
-          <PopoverContent className="rounded-lg border border-purple-600 bg-gradient-to-b from-purple-800 to-pink-800 shadow-2xl">
-            <PopoverArrow className="fill-purple-700" />
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">
-                Arrow with gradient background
+      {/* With arrow */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With Arrow
+        </h4>
+        <div className="flex justify-center">
+          <Popover>
+            <PopoverTrigger asChild>
+              <Button variant="outline">Open with arrow</Button>
+            </PopoverTrigger>
+            <PopoverContent className="w-56 rounded-lg p-4" sideOffset={10}>
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                The arrow points back at the trigger.
               </p>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* No Arrow */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">No Arrow</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary rounded-lg border shadow-2xl">
-            <div className="p-3">
-              <p className="text-fm-primary text-sm">Popover without arrow</p>
-            </div>
-          </PopoverContent>
-        </Popover>
+              <PopoverArrow className="fill-fm-surface-frosted/20" />
+            </PopoverContent>
+          </Popover>
+        </div>
       </div>
 
-      {/* Arrow Positioning */}
-      <div className="mt-8">
-        <h4 className="text-fm-primary mb-4 text-center font-medium">
-          Arrow Positioning
+      {/* Anchored variant */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Anchored Variant
         </h4>
-        <div className="flex justify-center gap-4">
-          {(["top", "right", "bottom", "left"] as const).map((side) => (
-            <Popover key={side}>
+        <div className="flex justify-center">
+          <Popover>
+            <div className="flex items-center gap-3">
+              <PopoverAnchor asChild>
+                <div className="border-fm-divider-secondary min-w-32 rounded-lg border px-3 py-2">
+                  <span className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    Search field
+                  </span>
+                </div>
+              </PopoverAnchor>
               <PopoverTrigger asChild>
-                <Button variant="outline" size="sm">
-                  {side}
-                </Button>
+                <Button size="sm">Suggest</Button>
               </PopoverTrigger>
-              <PopoverContent
-                side={side}
-                className="border-fm-divider-secondary rounded-lg border shadow-2xl"
-              >
-                <PopoverArrow className="fill-white/10" />
-                <div className="p-3">
-                  <p className="text-fm-primary text-sm">Arrow on {side}</p>
-                </div>
-              </PopoverContent>
-            </Popover>
-          ))}
+            </div>
+            <PopoverContent className="w-64 rounded-lg p-4">
+              <p className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                Positioned over the anchor, not the trigger button.
+              </p>
+            </PopoverContent>
+          </Popover>
         </div>
       </div>
     </div>
   ),
+}
+
+// ─── Interactive ──────────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "PopoverArrow examples showing different styling options: default, solid, colored, large, gradient, and positioning on different sides.",
+          "Live popovers with action panels inside — add to playlist and share options — demonstrating real audio-app workflows with controlled state.",
       },
     },
   },
-}
-
-// 6. PopoverClose Component Examples
-export const PopoverCloseVariants: Story = {
-  render: () => (
-    <div className="space-y-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          PopoverClose Variants
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          Different ways to implement close functionality
-        </p>
-      </div>
-
-      <div className="grid grid-cols-2 gap-4">
-        {/* Close Button in Header */}
+  render: () => {
+    const AddToPlaylist = () => {
+      const [selected, setSelected] = useState<string[]>([])
+      const [newName, setNewName] = useState("")
+
+      const playlists = [
+        "Late Night Drives",
+        "Morning Workout",
+        "Focus Mode",
+        "Weekend Vibes",
+      ]
+
+      const toggle = (name: string) =>
+        setSelected((prev) =>
+          prev.includes(name) ? prev.filter((p) => p !== name) : [...prev, name]
+        )
+
+      return (
         <Popover>
           <PopoverTrigger asChild>
-            <Button variant="outline">Header Close</Button>
+            <Button variant="outline" size="sm">
+              + Add to Playlist
+            </Button>
           </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-72 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="p-4">
-              <div className="mb-3 flex items-center justify-between">
-                <h4 className="text-fm-primary font-medium">Settings</h4>
-                <PopoverClose asChild>
-                  <Button variant="text" size="sm">
-                    ✕
-                  </Button>
-                </PopoverClose>
-              </div>
-              <p className="text-fm-secondary text-sm">
-                Close button in the header
+          <PopoverContent className="w-72 rounded-xl">
+            <div className="space-y-4 p-4">
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Add to Playlist
               </p>
-            </div>
-          </PopoverContent>
-        </Popover>
 
-        {/* Close Button in Footer */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Footer Close</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-72 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="space-y-3 p-4">
-              <h4 className="text-fm-primary font-medium">Confirmation</h4>
-              <p className="text-fm-secondary text-sm">
-                Are you sure you want to continue?
-              </p>
-              <div className="flex gap-2">
-                <Button size="sm">Confirm</Button>
-                <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Cancel
-                  </Button>
-                </PopoverClose>
+              <div className="space-y-1">
+                {playlists.map((pl) => (
+                  <button
+                    key={pl}
+                    onClick={() => toggle(pl)}
+                    className="hover:bg-fm-surface-secondary flex w-full items-center justify-between rounded-lg px-3 py-2 transition-colors"
+                  >
+                    <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                      {pl}
+                    </span>
+                    {selected.includes(pl) && (
+                      <span className="text-fm-positive font-fm-text text-fm-xs leading-fm-xs">
+                        ✓
+                      </span>
+                    )}
+                  </button>
+                ))}
+              </div>
+
+              <div className="border-fm-divider-secondary space-y-2 border-t pt-3">
+                <Label className="text-fm-secondary font-fm-text text-fm-xs leading-fm-xs">
+                  New playlist
+                </Label>
+                <div className="flex gap-2">
+                  <Input
+                    value={newName}
+                    onChange={(e) => setNewName(e.target.value)}
+                    placeholder="Playlist name…"
+                    className="text-fm-sm flex-1"
+                  />
+                  <PopoverClose asChild>
+                    <Button
+                      size="sm"
+                      disabled={!newName.trim()}
+                      onClick={() => setNewName("")}
+                    >
+                      Create
+                    </Button>
+                  </PopoverClose>
+                </div>
               </div>
             </div>
           </PopoverContent>
         </Popover>
+      )
+    }
+
+    const ShareOptions = () => {
+      const [copied, setCopied] = useState(false)
+
+      const copy = () => {
+        setCopied(true)
+        setTimeout(() => setCopied(false), 1500)
+      }
 
-        {/* Multiple Close Options */}
+      return (
         <Popover>
           <PopoverTrigger asChild>
-            <Button variant="outline">Multiple Close</Button>
+            <Button variant="outline" size="sm">
+              Share Track
+            </Button>
           </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-80 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
+          <PopoverContent className="w-72 rounded-xl">
             <div className="space-y-4 p-4">
               <div className="flex items-center justify-between">
-                <h4 className="text-fm-primary font-medium">Actions</h4>
-                <PopoverClose asChild>
-                  <Button variant="text" size="sm">
-                    ✕
-                  </Button>
-                </PopoverClose>
-              </div>
-
-              <div className="space-y-2">
-                <PopoverClose asChild>
-                  <button className="text-fm-primary hover:bg-fm-surface-secondary w-full rounded px-3 py-2 text-left text-sm">
-                    Save and Close
-                  </button>
-                </PopoverClose>
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  Share
+                </p>
                 <PopoverClose asChild>
-                  <button className="text-fm-primary hover:bg-fm-surface-secondary w-full rounded px-3 py-2 text-left text-sm">
-                    Discard and Close
+                  <button className="text-fm-tertiary hover:text-fm-primary text-lg leading-none transition-colors outline-none">
+                    ×
                   </button>
                 </PopoverClose>
-                <button className="text-fm-primary hover:bg-fm-surface-secondary w-full rounded px-3 py-2 text-left text-sm">
-                  Keep Open
-                </button>
               </div>
-            </div>
-          </PopoverContent>
-        </Popover>
 
-        {/* Icon Close Button */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Icon Close</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-64 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="p-4">
-              <div className="mb-3 flex items-start justify-between">
-                <div>
-                  <h4 className="text-fm-primary font-medium">Notification</h4>
-                  <p className="text-fm-secondary mt-1 text-sm">
-                    New message received
-                  </p>
-                </div>
-                <PopoverClose asChild>
-                  <Button variant="text" size="sm">
-                    <svg
-                      className="h-4 w-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M6 18L18 6M6 6l12 12"
-                      />
-                    </svg>
-                  </Button>
-                </PopoverClose>
-              </div>
-            </div>
-          </PopoverContent>
-        </Popover>
-
-        {/* Text Close Link */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Text Close</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-64 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="space-y-3 p-4">
-              <h4 className="text-fm-primary font-medium">Quick Tip</h4>
-              <p className="text-fm-secondary text-sm">
-                Use keyboard shortcuts to speed up your workflow.
-              </p>
-              <div className="text-right">
-                <PopoverClose asChild>
-                  <button className="text-fm-info hover:text-fm-info-sec text-sm underline">
-                    Got it, thanks!
+              <div className="space-y-2">
+                {[
+                  "Copy Link",
+                  "Share to Profile",
+                  "Send to Friend",
+                  "Embed",
+                ].map((action) => (
+                  <button
+                    key={action}
+                    onClick={action === "Copy Link" ? copy : undefined}
+                    className="hover:bg-fm-surface-secondary flex w-full items-center gap-3 rounded-lg px-3 py-2 text-left transition-colors"
+                  >
+                    <span className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm">
+                      {action === "Copy Link" && copied ? "Copied!" : action}
+                    </span>
                   </button>
-                </PopoverClose>
+                ))}
               </div>
-            </div>
-          </PopoverContent>
-        </Popover>
 
-        {/* Auto-close on Action */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button variant="outline">Auto Close</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-72 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="space-y-3 p-4">
-              <h4 className="text-fm-primary font-medium">Quick Actions</h4>
-              <div className="grid grid-cols-2 gap-2">
-                <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Copy
-                  </Button>
-                </PopoverClose>
-                <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Share
-                  </Button>
-                </PopoverClose>
-                <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Download
-                  </Button>
-                </PopoverClose>
-                <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Delete
-                  </Button>
-                </PopoverClose>
+              <div className="border-fm-divider-secondary border-t pt-3">
+                <p className="text-fm-tertiary font-fm-text text-fm-xs leading-fm-xs">
+                  Midnight Rain · Taylor Swift · Midnights
+                </p>
               </div>
-              <p className="text-fm-tertiary text-xs">
-                Actions will close the popover automatically
-              </p>
             </div>
           </PopoverContent>
         </Popover>
-      </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "PopoverClose examples showing different implementation patterns: header close, footer close, multiple options, icon buttons, text links, and auto-close actions.",
-      },
-    },
-  },
-}
-
-// 7. Complete Integration Example
-export const CompleteIntegration: Story = {
-  render: () => (
-    <div className="space-y-6">
-      <div className="text-center">
-        <h3 className="text-fm-primary mb-2 font-medium">
-          Complete Integration
-        </h3>
-        <p className="text-fm-secondary text-sm">
-          All components working together in real-world scenarios
-        </p>
-      </div>
-
-      <div className="flex justify-center gap-4">
-        {/* Complete User Menu */}
+      )
+    }
+
+    const EQSettings = () => {
+      const bands = [
+        { label: "Bass", freq: "80 Hz", default: 3 },
+        { label: "Low Mid", freq: "500 Hz", default: 0 },
+        { label: "High Mid", freq: "3 kHz", default: -1 },
+        { label: "Treble", freq: "10 kHz", default: -2 },
+      ]
+      const [values, setValues] = useState<Record<string, number>>(
+        Object.fromEntries(bands.map(({ label, default: d }) => [label, d]))
+      )
+
+      return (
         <Popover>
           <PopoverTrigger asChild>
-            <Button variant="text">
-              <img
-                src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=32&h=32&fit=crop&crop=face"
-                alt="Profile"
-                className="border-fm-divider-secondary h-8 w-8 rounded-full border"
-              />
-              <span className="text-sm">John Doe</span>
-              <svg
-                className="text-fm-secondary h-4 w-4"
-                fill="none"
-                stroke="currentColor"
-                viewBox="0 0 24 24"
-              >
-                <path
-                  strokeLinecap="round"
-                  strokeLinejoin="round"
-                  strokeWidth={2}
-                  d="M19 9l-7 7-7-7"
-                />
-              </svg>
+            <Button variant="outline" size="sm">
+              EQ Settings
             </Button>
           </PopoverTrigger>
-          <PopoverContent
-            align="end"
-            className="border-fm-divider-secondary w-80 rounded-lg border shadow-2xl"
-          >
-            <PopoverArrow className="fill-white/10" />
+          <PopoverContent className="w-72 rounded-xl">
             <div className="space-y-4 p-4">
-              {/* Header with close */}
               <div className="flex items-center justify-between">
-                <h4 className="text-fm-primary font-medium">Account Menu</h4>
-                <PopoverClose asChild>
-                  <Button variant="text" size="sm">
-                    ✕
-                  </Button>
-                </PopoverClose>
+                <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                  Equalizer
+                </p>
+                <button
+                  onClick={() =>
+                    setValues(
+                      Object.fromEntries(
+                        bands.map(({ label, default: d }) => [label, d])
+                      )
+                    )
+                  }
+                  className="text-fm-tertiary hover:text-fm-primary font-fm-text text-fm-xs leading-fm-xs transition-colors"
+                >
+                  Reset
+                </button>
               </div>
 
-              {/* User Info */}
-              <div className="bg-fm-surface-secondary flex items-center gap-3 rounded-lg p-3">
-                <img
-                  src="https://images.unsplash.com/photo-1472099645785-5658abf4ff4e?w=48&h=48&fit=crop&crop=face"
-                  alt="Profile"
-                  className="border-fm-divider-secondary h-12 w-12 rounded-full border"
-                />
-                <div>
-                  <div className="text-fm-primary font-medium">John Doe</div>
-                  <div className="text-fm-secondary text-sm">
-                    john@example.com
+              <div className="space-y-3">
+                {bands.map(({ label, freq }) => (
+                  <div key={label} className="space-y-1">
+                    <div className="flex items-center justify-between">
+                      <span className="text-fm-secondary font-fm-text text-fm-xs leading-fm-xs">
+                        {label} · {freq}
+                      </span>
+                      <span className="text-fm-primary font-fm-text text-fm-xs leading-fm-xs w-12 text-right">
+                        {values[label] > 0 ? "+" : ""}
+                        {values[label]} dB
+                      </span>
+                    </div>
+                    <input
+                      type="range"
+                      min={-12}
+                      max={12}
+                      step={1}
+                      value={values[label]}
+                      onChange={(e) =>
+                        setValues((v) => ({
+                          ...v,
+                          [label]: Number(e.target.value),
+                        }))
+                      }
+                      className="accent-fm-primary h-1 w-full"
+                    />
                   </div>
-                </div>
+                ))}
               </div>
 
-              {/* Quick Actions */}
-              <div className="grid grid-cols-2 gap-2">
+              <div className="flex gap-2 pt-1">
                 <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Profile
+                  <Button size="sm" className="flex-1">
+                    Apply
                   </Button>
                 </PopoverClose>
                 <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Settings
+                  <Button variant="outline" size="sm">
+                    Cancel
                   </Button>
                 </PopoverClose>
               </div>
-
-              {/* Menu Items */}
-              <div className="space-y-1">
-                <PopoverClose asChild>
-                  <button className="text-fm-primary hover:bg-fm-surface-secondary flex w-full items-center gap-2 rounded px-3 py-2 text-left text-sm">
-                    <svg
-                      className="h-4 w-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M9 12h6m-6 4h6m2 5H7a2 2 0 01-2-2V5a2 2 0 012-2h5.586a1 1 0 01.707.293l5.414 5.414a1 1 0 01.293.707V19a2 2 0 01-2 2z"
-                      />
-                    </svg>
-                    My Documents
-                  </button>
-                </PopoverClose>
-                <PopoverClose asChild>
-                  <button className="text-fm-primary hover:bg-fm-surface-secondary flex w-full items-center gap-2 rounded px-3 py-2 text-left text-sm">
-                    <svg
-                      className="h-4 w-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M3 10h18M7 15h1m4 0h1m-7 4h12a3 3 0 003-3V8a3 3 0 00-3-3H6a3 3 0 00-3 3v8a3 3 0 003 3z"
-                      />
-                    </svg>
-                    Billing
-                  </button>
-                </PopoverClose>
-                <PopoverClose asChild>
-                  <button className="text-fm-primary hover:bg-fm-surface-secondary flex w-full items-center gap-2 rounded px-3 py-2 text-left text-sm">
-                    <svg
-                      className="h-4 w-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M18.364 5.636l-3.536 3.536m0 5.656l3.536 3.536M9.172 9.172L5.636 5.636m3.536 9.192l-3.536 3.536M21 12a9 9 0 11-18 0 9 9 0 0118 0zm-5 0a4 4 0 11-8 0 4 4 0 018 0z"
-                      />
-                    </svg>
-                    Help & Support
-                  </button>
-                </PopoverClose>
-              </div>
-
-              {/* Sign Out */}
-              <div className="border-fm-divider-secondary border-t pt-3">
-                <PopoverClose asChild>
-                  <button className="text-fm-icon-negative hover:bg-fm-surface-secondary flex w-full items-center gap-2 rounded px-3 py-2 text-left text-sm">
-                    <svg
-                      className="h-4 w-4"
-                      fill="none"
-                      stroke="currentColor"
-                      viewBox="0 0 24 24"
-                    >
-                      <path
-                        strokeLinecap="round"
-                        strokeLinejoin="round"
-                        strokeWidth={2}
-                        d="M17 16l4-4m0 0l-4-4m4 4H7m6 4v1a3 3 0 01-3 3H6a3 3 0 01-3-3V7a3 3 0 013-3h4a3 3 0 013 3v1"
-                      />
-                    </svg>
-                    Sign Out
-                  </button>
-                </PopoverClose>
-              </div>
             </div>
           </PopoverContent>
         </Popover>
+      )
+    }
 
-        {/* Complete Form Editor */}
-        <Popover>
-          <PopoverTrigger asChild>
-            <Button>Edit Profile</Button>
-          </PopoverTrigger>
-          <PopoverContent className="border-fm-divider-secondary w-96 rounded-lg border shadow-2xl">
-            <PopoverArrow className="fill-white/10" />
-            <div className="space-y-4 p-4">
-              {/* Header */}
-              <div className="flex items-center justify-between">
-                <h4 className="text-fm-primary font-medium">Edit Profile</h4>
-                <PopoverClose asChild>
-                  <Button variant="text" size="sm">
-                    ✕
-                  </Button>
-                </PopoverClose>
+    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">
+                Track Actions
+              </p>
+              <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                Open any popover to interact with a live action panel.
+              </p>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+              <div className="space-y-3">
+                <AddToPlaylist />
+                <ShareOptions />
+                <EQSettings />
               </div>
+            </div>
 
-              {/* Form Fields */}
-              <div className="space-y-3">
-                <div>
-                  <Label htmlFor="name" className="text-fm-primary text-sm">
-                    Full Name
-                  </Label>
-                  <Input
-                    id="name"
-                    defaultValue="John Doe"
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-tertiary"
-                  />
-                </div>
-                <div>
-                  <Label htmlFor="email" className="text-fm-primary text-sm">
-                    Email
-                  </Label>
-                  <Input
-                    id="email"
-                    defaultValue="john@example.com"
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-tertiary"
-                  />
-                </div>
-                <div>
-                  <Label htmlFor="role" className="text-fm-primary text-sm">
-                    Role
-                  </Label>
-                  <select
-                    id="role"
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary focus-visible:ring-fm-divider-secondary w-full rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:outline-none"
-                  >
-                    <option value="developer">Developer</option>
-                    <option value="designer">Designer</option>
-                    <option value="manager">Manager</option>
-                  </select>
+            {/* Preview stage */}
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <div className="border-fm-divider-secondary bg-fm-surface-secondary flex-1 space-y-3 rounded-xl border p-5">
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                  Now playing
+                </p>
+                <div className="space-y-1">
+                  <p className="text-fm-primary font-fm-brand text-fm-xl leading-fm-xl font-semibold">
+                    Midnight Rain
+                  </p>
+                  <p className="text-fm-secondary font-fm-text text-fm-md leading-fm-md">
+                    Taylor Swift · Midnights · 2022
+                  </p>
                 </div>
-                <div>
-                  <Label htmlFor="bio" className="text-fm-primary text-sm">
-                    Bio
-                  </Label>
-                  <textarea
-                    id="bio"
-                    rows={3}
-                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-tertiary focus-visible:ring-fm-divider-secondary w-full rounded-md border px-3 py-2 text-sm focus-visible:ring-2 focus-visible:outline-none"
-                    defaultValue="Software developer passionate about creating great user experiences."
-                  />
+                <div className="border-fm-divider-secondary border-t pt-3">
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                    Use the action buttons on the left to open interactive
+                    popovers: add this track to a playlist, share it, or adjust
+                    the equalizer.
+                  </p>
                 </div>
               </div>
-
-              {/* Action Buttons */}
-              <div className="flex gap-2 pt-2">
-                <PopoverClose asChild>
-                  <Button size="sm">Save Changes</Button>
-                </PopoverClose>
-                <PopoverClose asChild>
-                  <Button size="sm" variant="outline">
-                    Cancel
-                  </Button>
-                </PopoverClose>
+              <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)">
+                  {`<Popover><PopoverTrigger asChild>…</PopoverTrigger><PopoverContent>…<PopoverClose /></PopoverContent></Popover>`}
+                </code>
               </div>
             </div>
-          </PopoverContent>
-        </Popover>
+          </div>
+        </div>
       </div>
-    </div>
-  ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Complete integration examples showing all popover components working together in realistic user interface scenarios.",
-      },
-    },
+    )
   },
 }