aural-ui 4.0.1 → 4.2.0

package/dist/components/select/Select.stories.tsx

@@ -15,89 +15,38 @@ import {
 } from "@/ui/components/select"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
-import { Button } from "../button"
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
+// ─── Meta ─────────────────────────────────────────────────────────────────────
 
 const meta: Meta<typeof SelectField> = {
   title: "Components/UI/Select",
   component: SelectField,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-A customizable select component built on top of Radix UI Select primitives with atomic design principles. 
-Provides a dropdown selection interface with support for multiple styling variants, decorations, 
-required fields, helper text, grouping, separators, scroll buttons, and comprehensive keyboard navigation.
-
-## Features
-- Built on Radix UI for accessibility
-- Multiple styling variants (default, error, warning, success)
-- Multiple decorations (underline, outline, filled)
-- Required field support with visual indicators
-- Helper text support with variant styling
-- Support for grouped options
-- Scroll buttons for long lists
-- Keyboard navigation
-- Disabled states
-- Atomic design composition
-- Unstyled mode for custom styling
-- CVA-based styling system
-- Custom icons (ChevronDown, ChevronUp, Tick)
-- Full accessibility support (ARIA attributes)
-
-## Usage
-
-### Simple Usage with SelectField
-\`\`\`tsx
-import { SelectField, SelectItem } from '@/ui/components/select'
-
-<SelectField
-  label="Country"
-  placeholder="Select a country..."
-  required
-  helperText="Please select your country"
->
-  <SelectItem value="us">United States</SelectItem>
-  <SelectItem value="ca">Canada</SelectItem>
-</SelectField>
-\`\`\`
-
-### Atomic Composition
-\`\`\`tsx
-import {
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectRoot,
-  SelectTrigger,
-  SelectValue,
-  SelectWrapper,
-} from '@/ui/components/select'
-
-<SelectRoot fullWidth>
-  <SelectLabel required>Country</SelectLabel>
-  <SelectWrapper>
-    <Select>
-      <SelectTrigger>
-        <SelectValue placeholder="Select..." />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value="us">United States</SelectItem>
-      </SelectContent>
-    </Select>
-  </SelectWrapper>
-  <SelectHelperText>Please select your country</SelectHelperText>
-</SelectRoot>
-\`\`\`
-        `,
+        component:
+          "A customisable select built on Radix UI primitives with atomic composition support. Provides a dropdown selection interface with validation variants (default, error, warning, success), three decoration styles (underline, outline, filled), label, helper text, grouping, separators, scroll buttons, and full keyboard navigation and ARIA accessibility.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Validation States",
+              description: "Default to success",
+            },
+            {
+              title: "3 Decoration Styles",
+              description: "Underline, outline, filled",
+            },
+            {
+              title: "Groups & Separators",
+              description: "Organised option lists",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -105,108 +54,36 @@ import {
     label: {
       control: { type: "text" },
       description: "Label text for the select",
-      table: {
-        type: { summary: "ReactNode" },
-        defaultValue: { summary: "undefined" },
-      },
     },
     placeholder: {
       control: { type: "text" },
-      description: "Placeholder text shown when no option is selected",
-      table: {
-        type: { summary: "string" },
-        defaultValue: { summary: "undefined" },
-      },
+      description: "Placeholder shown when no option is selected",
     },
     helperText: {
       control: { type: "text" },
       description: "Helper text displayed below the select",
-      table: {
-        type: { summary: "ReactNode" },
-        defaultValue: { summary: "undefined" },
-      },
     },
     variant: {
       control: { type: "select" },
       options: ["default", "error", "warning", "success"],
-      description: "Visual variant affecting border and helper text colors",
-      table: {
-        type: { summary: '"default" | "error" | "warning" | "success"' },
-        defaultValue: { summary: '"default"' },
-      },
+      description: "Visual validation state",
     },
     decoration: {
       control: { type: "select" },
       options: ["underline", "outline", "filled"],
-      description: "Visual style of the select border and background",
-      table: {
-        type: { summary: '"underline" | "outline" | "filled"' },
-        defaultValue: { summary: '"underline"' },
-      },
+      description: "Border and background style",
     },
     required: {
       control: { type: "boolean" },
-      description: "Whether the select is required (adds asterisk to label)",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
+      description: "Adds an asterisk to the label and aria-required",
     },
     disabled: {
       control: { type: "boolean" },
-      description: "Whether the select is disabled and non-interactive",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
+      description: "Disables the select entirely",
     },
     fullWidth: {
       control: { type: "boolean" },
-      description: "Whether the select takes full width of its container",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
-    },
-    value: {
-      control: { type: "text" },
-      description: "Controlled value of the select",
-      table: {
-        type: { summary: "string" },
-        defaultValue: { summary: "undefined" },
-      },
-    },
-    onValueChange: {
-      action: "valueChanged",
-      description: "Callback fired when the value changes",
-      table: {
-        type: { summary: "(value: string) => void" },
-      },
-    },
-    classes: {
-      control: { type: "object" },
-      description: "Override classes for different parts of the component",
-      table: {
-        type: {
-          summary:
-            "{ root?: string; label?: string; wrapper?: string; trigger?: string; content?: string; helperText?: string }",
-        },
-        defaultValue: { summary: "{}" },
-      },
-    },
-    name: {
-      control: "text",
-      description: "The name attribute for form submission",
-      table: {
-        type: { summary: "string" },
-      },
-    },
-    id: {
-      control: "text",
-      description: "The id attribute for the select",
-      table: {
-        type: { summary: "string" },
-      },
+      description: "Expands the select to fill its container",
     },
   },
   args: {
@@ -215,757 +92,775 @@ import {
     required: false,
     disabled: false,
     fullWidth: false,
+    label: "Label",
+    placeholder: "Select an option…",
   },
 }
 
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    label: "Fruit Selection",
-    placeholder: "Select a fruit",
-    decoration: "underline",
-    fullWidth: true,
-  },
-  render: (args) => (
-    <SelectField {...args}>
-      <SelectItem value="apple">Apple</SelectItem>
-      <SelectItem value="banana">Banana</SelectItem>
-      <SelectItem value="orange">Orange</SelectItem>
-      <SelectItem value="grape">Grape</SelectItem>
-      <SelectItem value="strawberry">Strawberry</SelectItem>
-    </SelectField>
-  ),
-}
+// ─── 1. Playground ───────────────────────────────────────────────────────────
 
-// Decoration variants
-export const DecorationVariants: Story = {
-  render: () => (
-    <div className="max-w-md space-y-6">
-      <div>
-        <h3 className="text-fm-primary mb-2 text-sm font-medium">Underline</h3>
-        <SelectField
-          label="Underline Style"
-          placeholder="Minimalist underline style..."
-          decoration="underline"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-          <SelectItem value="option3">Option 3</SelectItem>
-        </SelectField>
-      </div>
-
-      <div>
-        <h3 className="text-fm-primary mb-2 text-sm font-medium">Outline</h3>
-        <SelectField
-          label="Outline Style"
-          placeholder="Traditional outlined style..."
-          decoration="outline"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-          <SelectItem value="option3">Option 3</SelectItem>
-        </SelectField>
-      </div>
-
-      <div>
-        <h3 className="text-fm-primary mb-2 text-sm font-medium">Filled</h3>
-        <SelectField
-          label="Filled Style"
-          placeholder="Modern filled style..."
-          decoration="filled"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-          <SelectItem value="option3">Option 3</SelectItem>
-        </SelectField>
-      </div>
-    </div>
-  ),
+export const Playground: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Three decoration styles available: underline (minimalist), outline (traditional), and filled (modern with background).",
+          "Use the Storybook controls panel to configure every prop. The select below reflects your selections live.",
       },
     },
   },
-}
-
-export const WithRequiredField: Story = {
-  args: {
-    label: "Required Selection",
-    placeholder: "Please select an option",
-    required: true,
-    helperText: "This field is required",
-    decoration: "outline",
-    fullWidth: true,
-  },
   render: (args) => (
-    <SelectField {...args}>
-      <SelectItem value="option1">Option 1</SelectItem>
-      <SelectItem value="option2">Option 2</SelectItem>
-      <SelectItem value="option3">Option 3</SelectItem>
-    </SelectField>
+    <div className="w-80 space-y-4">
+      <SelectField {...args} fullWidth>
+        <SelectItem value="option1">Option 1</SelectItem>
+        <SelectItem value="option2">Option 2</SelectItem>
+        <SelectItem value="option3">Option 3</SelectItem>
+        <SelectItem value="option4">Option 4</SelectItem>
+      </SelectField>
+      <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)">
+          {`<SelectField variant="${args.variant}" decoration="${args.decoration}"${args.required ? " required" : ""}${args.disabled ? " disabled" : ""} />`}
+        </code>
+      </div>
+    </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: "Select field with required indicator (asterisk) in the label.",
-      },
-    },
-  },
 }
 
-export const Variants: Story = {
+// ─── 2. AllVariants ──────────────────────────────────────────────────────────
+
+export const AllVariants: Story = {
   parameters: {
     docs: {
       description: {
-        story: `
-Different visual variants of the select component. Each variant uses different colors 
-to communicate different states or purposes:
-- **Default**: Standard styling
-- **Error**: Red styling for error states
-- **Warning**: Yellow/orange styling for warnings
-- **Success**: Green styling for success states
-        `,
+        story:
+          "Full matrix of all four validation variants (default, error, warning, success) across all three decoration styles (underline, outline, filled).",
       },
     },
   },
-  render: () => (
-    <div className="max-w-md space-y-6">
-      <SelectField
-        label="Default Variant"
-        placeholder="Select an option..."
-        variant="default"
-        decoration="outline"
-        helperText="This is the default variant"
-        fullWidth
-      >
-        <SelectItem value="option1">Option 1</SelectItem>
-        <SelectItem value="option2">Option 2</SelectItem>
-        <SelectItem value="option3">Option 3</SelectItem>
-      </SelectField>
-
-      <SelectField
-        label="Error Variant"
-        placeholder="Select an option..."
-        variant="error"
-        decoration="outline"
-        helperText="Something went wrong"
-        fullWidth
-      >
-        <SelectItem value="option1">Option 1</SelectItem>
-        <SelectItem value="option2">Option 2</SelectItem>
-        <SelectItem value="option3">Option 3</SelectItem>
-      </SelectField>
-
-      <SelectField
-        label="Warning Variant"
-        placeholder="Select an option..."
-        variant="warning"
-        decoration="outline"
-        helperText="Please double-check your selection"
-        fullWidth
-      >
-        <SelectItem value="option1">Option 1</SelectItem>
-        <SelectItem value="option2">Option 2</SelectItem>
-        <SelectItem value="option3">Option 3</SelectItem>
-      </SelectField>
-
-      <SelectField
-        label="Success Variant"
-        placeholder="Select an option..."
-        variant="success"
-        decoration="outline"
-        helperText="Great choice!"
-        fullWidth
-      >
-        <SelectItem value="option1">Option 1</SelectItem>
-        <SelectItem value="option2">Option 2</SelectItem>
-        <SelectItem value="option3">Option 3</SelectItem>
-      </SelectField>
-    </div>
-  ),
-}
+  render: () => {
+    const variants = [
+      {
+        variant: "default" as const,
+        label: "Default",
+        helperText: "Helper text",
+      },
+      {
+        variant: "error" as const,
+        label: "Error",
+        helperText: "Something went wrong",
+      },
+      {
+        variant: "warning" as const,
+        label: "Warning",
+        helperText: "Double-check your selection",
+      },
+      {
+        variant: "success" as const,
+        label: "Success",
+        helperText: "Great choice!",
+      },
+    ]
+    const decorations = [
+      { decoration: "underline" as const, label: "Underline" },
+      { decoration: "outline" as const, label: "Outline" },
+      { decoration: "filled" as const, label: "Filled" },
+    ]
 
-export const WithHelperText: Story = {
-  args: {
-    label: "Framework Selection",
-    placeholder: "Choose your preferred framework",
-    helperText: "Select the framework you're most comfortable with",
-    decoration: "filled",
-    fullWidth: true,
+    return (
+      <div className="space-y-10">
+        {decorations.map(({ decoration, label: decLabel }) => (
+          <div key={decoration}>
+            <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+              {decLabel}
+            </h4>
+            <div className="flex flex-wrap gap-6">
+              {variants.map(({ variant, label, helperText }) => (
+                <div key={variant} className="w-48 space-y-2 text-center">
+                  <SelectField
+                    label={label}
+                    placeholder="Select…"
+                    variant={variant}
+                    decoration={decoration}
+                    helperText={helperText}
+                    fullWidth
+                  >
+                    <SelectItem value="opt1">Option 1</SelectItem>
+                    <SelectItem value="opt2">Option 2</SelectItem>
+                    <SelectItem value="opt3">Option 3</SelectItem>
+                  </SelectField>
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    {label}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+    )
   },
-  render: (args) => (
-    <SelectField {...args}>
-      <SelectItem value="react">React</SelectItem>
-      <SelectItem value="vue">Vue.js</SelectItem>
-      <SelectItem value="angular">Angular</SelectItem>
-      <SelectItem value="svelte">Svelte</SelectItem>
-    </SelectField>
-  ),
 }
 
-export const Controlled: Story = {
+// ─── 3. Configurations ───────────────────────────────────────────────────────
+
+export const Configurations: Story = {
   parameters: {
     docs: {
       description: {
-        story: `
-Example of a controlled select component. The value is managed by the parent component state.
-Use this pattern when you need to control the select value programmatically.
-        `,
+        story:
+          "Non-variant configuration axes: required field indicator, disabled whole select, individual disabled options, and grouped options with separators.",
       },
     },
   },
-  render: function ControlledSelect() {
-    const [value, setValue] = React.useState<string>("")
+  render: () => (
+    <div className="w-full max-w-sm space-y-10">
+      {/* Required */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Required
+        </h4>
+        <div className="space-y-2 text-center">
+          <SelectField
+            label="Country"
+            placeholder="Select your country…"
+            required
+            helperText="This field is required"
+            decoration="outline"
+            fullWidth
+          >
+            <SelectItem value="us">United States</SelectItem>
+            <SelectItem value="ca">Canada</SelectItem>
+            <SelectItem value="uk">United Kingdom</SelectItem>
+          </SelectField>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            required — asterisk added to label
+          </p>
+        </div>
+      </div>
 
-    return (
-      <div className="max-w-md space-y-4">
-        <div>
-          <p className="text-fm-primary mb-2 text-sm">
-            Selected value:{" "}
-            <code className="bg-fm-surface-secondary rounded px-1">
-              {value || "none"}
-            </code>
+      {/* Disabled whole select */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Disabled
+        </h4>
+        <div className="space-y-2 text-center">
+          <SelectField
+            label="Region"
+            placeholder="Not available"
+            disabled
+            helperText="This option is not available"
+            decoration="outline"
+            fullWidth
+          >
+            <SelectItem value="r1">Region 1</SelectItem>
+            <SelectItem value="r2">Region 2</SelectItem>
+          </SelectField>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            disabled — entire select is non-interactive
           </p>
+        </div>
+      </div>
+
+      {/* Disabled items */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Disabled Items
+        </h4>
+        <div className="space-y-2 text-center">
           <SelectField
-            label="Controlled Select"
-            placeholder="Select a fruit"
-            value={value}
-            onValueChange={setValue}
-            helperText="This select is controlled by React state"
+            label="Plan"
+            placeholder="Choose a plan…"
+            helperText="Some plans are not available in your region"
             decoration="outline"
             fullWidth
           >
-            <SelectItem value="apple">Apple</SelectItem>
-            <SelectItem value="banana">Banana</SelectItem>
-            <SelectItem value="orange">Orange</SelectItem>
-            <SelectItem value="grape">Grape</SelectItem>
-            <SelectItem value="strawberry">Strawberry</SelectItem>
+            <SelectItem value="starter">Starter — Free</SelectItem>
+            <SelectItem value="pro">Pro — $9/mo</SelectItem>
+            <SelectItem value="enterprise" disabled>
+              Enterprise — Contact sales
+            </SelectItem>
           </SelectField>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            disabled items — individual options unavailable
+          </p>
         </div>
-        <div className="flex gap-2">
-          <Button size="sm" onClick={() => setValue("apple")}>
-            Set to Apple
-          </Button>
-          <Button size="sm" variant="outline" onClick={() => setValue("")}>
-            Clear
-          </Button>
+      </div>
+
+      {/* Grouped options */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Grouped Options
+        </h4>
+        <div className="space-y-2 text-center">
+          <SelectField
+            label="Technology"
+            placeholder="Choose a technology…"
+            helperText="Frontend and backend options"
+            decoration="outline"
+            fullWidth
+          >
+            <SelectGroup>
+              <SelectLabel className="px-2 pt-2 pb-1">Frontend</SelectLabel>
+              <SelectItem value="react">React</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="vue">Vue</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="svelte">Svelte</SelectItem>
+            </SelectGroup>
+            <SelectSeparator />
+            <SelectGroup>
+              <SelectLabel className="px-2 pt-2 pb-1">Backend</SelectLabel>
+              <SelectItem value="node">Node.js</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="python">Python</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="go">Go</SelectItem>
+            </SelectGroup>
+          </SelectField>
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            SelectGroup + SelectLabel + SelectSeparator
+          </p>
         </div>
       </div>
-    )
-  },
+    </div>
+  ),
 }
 
-export const DisabledStates: Story = {
-  render: () => (
-    <div className="max-w-md space-y-6">
-      <SelectField
-        label="Disabled Select"
-        placeholder="This select is disabled"
-        disabled
-        helperText="This select cannot be interacted with"
-        decoration="outline"
-        fullWidth
-      >
-        <SelectItem value="option1">Option 1</SelectItem>
-        <SelectItem value="option2">Option 2</SelectItem>
-      </SelectField>
+// ─── 4. States ───────────────────────────────────────────────────────────────
 
-      <SelectField
-        label="Select with Disabled Items"
-        placeholder="Some items are disabled"
-        helperText="Some options may be unavailable"
-        decoration="filled"
-        fullWidth
-      >
-        <SelectItem value="available1">Available Option 1</SelectItem>
-        <SelectItem value="disabled1" disabled>
-          Disabled Option 1
-        </SelectItem>
-        <SelectItem value="available2">Available Option 2</SelectItem>
-        <SelectItem value="disabled2" disabled>
-          Disabled Option 2
-        </SelectItem>
-      </SelectField>
-    </div>
-  ),
+export const States: Story = {
   parameters: {
     docs: {
       description: {
-        story: "Examples of disabled select and individual disabled options.",
+        story:
+          "All five states side by side: default (idle), disabled, error (validation failure), warning (advisory), and success (validated).",
       },
     },
   },
-}
-
-export const WithGroups: Story = {
   render: () => (
-    <SelectField
-      label="Technology Stack"
-      placeholder="Select a technology"
-      decoration="outline"
-      helperText="Choose from frontend or backend technologies"
-      fullWidth
-    >
-      <SelectGroup>
-        <SelectLabel className="px-2 pt-2 pb-1">Frontend</SelectLabel>
-        <SelectItem value="react">React</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="vue">Vue</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="angular">Angular</SelectItem>
-      </SelectGroup>
-      <SelectSeparator />
-      <SelectGroup>
-        <SelectLabel className="px-2 pt-2 pb-1">Backend</SelectLabel>
-        <SelectItem value="nodejs">Node.js</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="python">Python</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="java">Java</SelectItem>
-      </SelectGroup>
-    </SelectField>
+    <div className="w-full max-w-sm space-y-8">
+      {[
+        {
+          label: "Default",
+          props: {
+            label: "Default",
+            placeholder: "Select an option…",
+            variant: "default" as const,
+            helperText: "Helper text",
+          },
+        },
+        {
+          label: "Disabled",
+          props: {
+            label: "Disabled",
+            placeholder: "Not available",
+            variant: "default" as const,
+            disabled: true,
+            helperText: "This field cannot be changed",
+          },
+        },
+        {
+          label: "Error",
+          props: {
+            label: "Error",
+            placeholder: "Select an option…",
+            variant: "error" as const,
+            helperText: "Please select a valid option",
+          },
+        },
+        {
+          label: "Warning",
+          props: {
+            label: "Warning",
+            placeholder: "Select an option…",
+            variant: "warning" as const,
+            helperText: "Double-check your selection",
+          },
+        },
+        {
+          label: "Success",
+          props: {
+            label: "Success",
+            placeholder: "Select an option…",
+            variant: "success" as const,
+            helperText: "Looks good!",
+          },
+        },
+      ].map(({ label, props }) => (
+        <div key={label}>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            {label}
+          </h4>
+          <SelectField decoration="outline" fullWidth {...props}>
+            <SelectItem value="opt1">Option 1</SelectItem>
+            <SelectItem value="opt2">Option 2</SelectItem>
+            <SelectItem value="opt3">Option 3</SelectItem>
+          </SelectField>
+        </div>
+      ))}
+    </div>
   ),
+}
+
+// ─── 5. Interactive ──────────────────────────────────────────────────────────
+
+export const Interactive: Story = {
   parameters: {
     docs: {
       description: {
-        story: `
-Select with grouped options using \`SelectGroup\`, \`SelectLabel\`, and \`SelectSeparator\` components.
-Useful for organizing related options into categories.
-        `,
+        story:
+          "Live controlled select demo. Use the preset buttons to jump between states, or pick values directly from the dropdowns. The variant and helper text update dynamically based on selection.",
       },
     },
   },
-}
+  render: function InteractiveSelect() {
+    const [country, setCountry] = React.useState("")
+    const [framework, setFramework] = React.useState("")
+    const [decoration, setDecoration] = React.useState<
+      "underline" | "outline" | "filled"
+    >("outline")
 
-export const FormIntegration: Story = {
-  render: () => (
-    <form
-      className="max-w-md space-y-4 rounded-lg border p-4"
-      onSubmit={(e) => {
-        e.preventDefault()
-        const formData = new FormData(e.currentTarget)
-        alert(
-          `Selected values:\nFruit: ${formData.get("fruit")}\nColor: ${formData.get("color")}`
-        )
-      }}
-    >
-      <SelectField
-        label="Favorite Fruit"
-        placeholder="Select a fruit"
-        name="fruit"
-        required
-        helperText="Required field"
-        decoration="outline"
-        fullWidth
-      >
-        <SelectItem value="apple">Apple</SelectItem>
-        <SelectItem value="banana">Banana</SelectItem>
-        <SelectItem value="orange">Orange</SelectItem>
-      </SelectField>
+    const countryVariant = country ? "success" : "default"
+    const countryHelper = country
+      ? "Country selected successfully"
+      : "Please select your country"
 
-      <SelectField
-        label="Favorite Color"
-        placeholder="Select a color"
-        name="color"
-        helperText="Optional field"
-        decoration="filled"
-        fullWidth
-      >
-        <SelectItem value="red">Red</SelectItem>
-        <SelectItem value="blue">Blue</SelectItem>
-        <SelectItem value="green">Green</SelectItem>
-      </SelectField>
+    const presets = [
+      { label: "Select country", country: "us", framework: "" },
+      { label: "Select both", country: "ca", framework: "react" },
+      { label: "Clear all", country: "", framework: "" },
+    ]
 
-      <Button type="submit" className="w-full">
-        Submit Form
-      </Button>
-    </form>
-  ),
+    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">
+                Presets
+              </p>
+              <div className="space-y-2">
+                {presets.map(({ label, country: c, framework: f }) => (
+                  <button
+                    key={label}
+                    onClick={() => {
+                      setCountry(c)
+                      setFramework(f)
+                    }}
+                    className="border-fm-divider-secondary text-fm-primary font-fm-text text-fm-sm leading-fm-sm hover:bg-fm-surface-primary w-full rounded-lg border px-3 py-2 text-left transition-colors"
+                  >
+                    {label}
+                  </button>
+                ))}
+              </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Decoration
+              </p>
+              <div className="space-y-2">
+                {(["underline", "outline", "filled"] as const).map((d) => (
+                  <button
+                    key={d}
+                    onClick={() => setDecoration(d)}
+                    className={`border-fm-divider-secondary text-fm-primary font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border px-3 py-2 text-left capitalize transition-colors ${decoration === d ? "bg-fm-surface-primary" : "hover:bg-fm-surface-primary"}`}
+                  >
+                    {d}
+                  </button>
+                ))}
+              </div>
+            </div>
+
+            {/* Preview stage */}
+            <div className="flex flex-col gap-4 lg:col-span-2">
+              <SelectField
+                label="Country"
+                placeholder="Select your country…"
+                value={country}
+                onValueChange={setCountry}
+                required
+                variant={countryVariant}
+                helperText={countryHelper}
+                decoration={decoration}
+                fullWidth
+              >
+                <SelectItem value="us">United States</SelectItem>
+                <SelectItem value="ca">Canada</SelectItem>
+                <SelectItem value="uk">United Kingdom</SelectItem>
+                <SelectItem value="de">Germany</SelectItem>
+                <SelectItem value="fr">France</SelectItem>
+              </SelectField>
+
+              <SelectField
+                label="Framework"
+                placeholder="Choose your framework…"
+                value={framework}
+                onValueChange={setFramework}
+                helperText="This will personalise your experience"
+                decoration={decoration}
+                fullWidth
+              >
+                <SelectGroup>
+                  <SelectLabel className="px-2 pt-2 pb-1">Popular</SelectLabel>
+                  <SelectItem value="react">React</SelectItem>
+                  <SelectSeparator />
+                  <SelectItem value="vue">Vue.js</SelectItem>
+                  <SelectSeparator />
+                  <SelectItem value="angular">Angular</SelectItem>
+                </SelectGroup>
+                <SelectSeparator />
+                <SelectGroup>
+                  <SelectLabel className="px-2 pt-2 pb-1">Others</SelectLabel>
+                  <SelectItem value="svelte">Svelte</SelectItem>
+                  <SelectSeparator />
+                  <SelectItem value="solid">SolidJS</SelectItem>
+                </SelectGroup>
+              </SelectField>
+
+              <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)">
+                  {`country="${country || "(none)"}" framework="${framework || "(none)"}"`}
+                </code>
+              </div>
+            </div>
+          </div>
+        </div>
+      </div>
+    )
+  },
+}
+
+// ─── 6. Parts ────────────────────────────────────────────────────────────────
+
+export const Parts: Story = {
   parameters: {
     docs: {
       description: {
-        story: `
-Select components integrated with a form. Shows how to use \`name\` and \`required\` props 
-for form validation and submission. The select values will be included in form data.
-        `,
+        story:
+          "Each atomic sub-component shown individually: SelectField (convenience wrapper), SelectRoot + SelectWrapper + Select + SelectTrigger + SelectContent (atomic composition), SelectLabel (Radix label bridged to the design system Label), SelectHelperText, SelectItem with tick indicator, SelectSeparator (Divider-based), and SelectGroup for categorising options.",
       },
     },
   },
-}
-
-export const AtomicComposition: Story = {
   render: () => {
-    const [value, setValue] = React.useState("")
+    const [atomicValue, setAtomicValue] = React.useState("")
 
     return (
-      <SelectRoot fullWidth className="max-w-md">
-        <SelectLabel required>Custom Composed Select</SelectLabel>
-
-        <SelectWrapper>
-          <Select value={value} onValueChange={setValue}>
-            <SelectTrigger
+      <div className="w-full max-w-lg space-y-10">
+        {/* SelectField */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            SelectField — convenience wrapper
+          </h4>
+          <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-sm leading-fm-sm mb-3">
+              Combines SelectRoot, SelectLabel, SelectWrapper, Select,
+              SelectTrigger, SelectContent, and SelectHelperText into a single
+              component.
+            </p>
+            <SelectField
+              label="Framework"
+              placeholder="Select a framework…"
+              helperText="Pick your preferred stack"
               decoration="outline"
-              variant="default"
-              aria-describedby="custom-select-helper"
+              fullWidth
             >
-              <SelectValue placeholder="Built with atomic components..." />
-            </SelectTrigger>
+              <SelectItem value="react">React</SelectItem>
+              <SelectItem value="vue">Vue</SelectItem>
+            </SelectField>
+          </div>
+        </div>
 
-            <SelectContent>
-              <SelectItem value="atomic">Atomic Design</SelectItem>
+        {/* Atomic composition */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Atomic Composition
+          </h4>
+          <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-sm leading-fm-sm mb-3">
+              Build the same result manually using individual primitives for
+              full layout control.
+            </p>
+            <SelectRoot fullWidth>
+              <SelectLabel required>Custom Select</SelectLabel>
+              <SelectWrapper>
+                <Select value={atomicValue} onValueChange={setAtomicValue}>
+                  <SelectTrigger decoration="outline" variant="default">
+                    <SelectValue placeholder="Built with atomic parts…" />
+                  </SelectTrigger>
+                  <SelectContent>
+                    <SelectItem value="atomic">Atomic Design</SelectItem>
+                    <SelectSeparator />
+                    <SelectItem value="flexible">
+                      Flexible Composition
+                    </SelectItem>
+                    <SelectSeparator />
+                    <SelectItem value="accessible">
+                      Accessible by Default
+                    </SelectItem>
+                  </SelectContent>
+                </Select>
+              </SelectWrapper>
+              <SelectHelperText variant="default">
+                Full control via individual primitives
+              </SelectHelperText>
+            </SelectRoot>
+          </div>
+        </div>
+
+        {/* SelectSeparator */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            SelectSeparator
+          </h4>
+          <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-sm leading-fm-sm mb-3">
+              A Divider-based separator rendered between SelectItems to visually
+              group related options.
+            </p>
+            <SelectField
+              label="Fruit"
+              placeholder="Choose a fruit…"
+              decoration="outline"
+              fullWidth
+            >
+              <SelectItem value="apple">Apple</SelectItem>
               <SelectSeparator />
-              <SelectItem value="flexible">Flexible Composition</SelectItem>
+              <SelectItem value="banana">Banana</SelectItem>
               <SelectSeparator />
-              <SelectItem value="accessible">Accessible</SelectItem>
-            </SelectContent>
-          </Select>
-        </SelectWrapper>
-
-        <SelectHelperText id="custom-select-helper" variant="default">
-          This is built using atomic components for maximum flexibility
-        </SelectHelperText>
-      </SelectRoot>
+              <SelectItem value="cherry">Cherry</SelectItem>
+            </SelectField>
+          </div>
+        </div>
+      </div>
     )
   },
+}
+
+// ─── 7. UseCases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "This example shows how to compose the Select using individual atomic components for maximum flexibility. This pattern allows for custom layouts and advanced use cases.",
+          "Real product-shaped examples: a user profile form with country and language selection, a subscription plan picker with disabled options, and a dynamic filter with grouped content categories.",
       },
     },
   },
-}
+  render: function UseCasesSelect() {
+    const [country, setCountry] = React.useState("")
+    const [language, setLanguage] = React.useState("")
+    const [plan, setPlan] = React.useState("")
+    const [category, setCategory] = React.useState("")
 
-export const AllVariantsAllDecorations: Story = {
-  render: () => (
-    <div className="grid max-w-6xl grid-cols-1 gap-6 lg:grid-cols-3">
-      {/* Underline decoration */}
-      <div className="space-y-4">
-        <h3 className="text-fm-primary text-lg font-semibold">Underline</h3>
-        <SelectField
-          label="Default"
-          placeholder="Default underline..."
-          variant="default"
-          decoration="underline"
-          helperText="Default variant"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Error"
-          placeholder="Error underline..."
-          variant="error"
-          decoration="underline"
-          helperText="Something went wrong"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Warning"
-          placeholder="Warning underline..."
-          variant="warning"
-          decoration="underline"
-          helperText="Please check selection"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Success"
-          placeholder="Success underline..."
-          variant="success"
-          decoration="underline"
-          helperText="Great choice!"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-      </div>
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* Profile settings */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Profile Settings
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-md space-y-4 rounded-xl border p-5">
+            <SelectField
+              label="Country"
+              placeholder="Select your country…"
+              value={country}
+              onValueChange={setCountry}
+              required
+              variant={country ? "success" : "default"}
+              helperText={
+                country ? "Country saved" : "Used for regional content"
+              }
+              decoration="outline"
+              fullWidth
+            >
+              <SelectItem value="us">United States</SelectItem>
+              <SelectItem value="ca">Canada</SelectItem>
+              <SelectItem value="uk">United Kingdom</SelectItem>
+              <SelectItem value="de">Germany</SelectItem>
+              <SelectItem value="fr">France</SelectItem>
+              <SelectItem value="au">Australia</SelectItem>
+            </SelectField>
+
+            <SelectField
+              label="Language"
+              placeholder="Select your language…"
+              value={language}
+              onValueChange={setLanguage}
+              helperText="Preferred display language"
+              decoration="outline"
+              fullWidth
+            >
+              <SelectItem value="en">English</SelectItem>
+              <SelectItem value="de">Deutsch</SelectItem>
+              <SelectItem value="fr">Français</SelectItem>
+              <SelectItem value="es">Español</SelectItem>
+              <SelectItem value="ja">日本語</SelectItem>
+            </SelectField>
+          </div>
+        </div>
 
-      {/* Outline decoration */}
-      <div className="space-y-4">
-        <h3 className="text-fm-primary text-lg font-semibold">Outline</h3>
-        <SelectField
-          label="Default"
-          placeholder="Default outline..."
-          variant="default"
-          decoration="outline"
-          helperText="Default variant"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Error"
-          placeholder="Error outline..."
-          variant="error"
-          decoration="outline"
-          helperText="Something went wrong"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Warning"
-          placeholder="Warning outline..."
-          variant="warning"
-          decoration="outline"
-          helperText="Please check selection"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Success"
-          placeholder="Success outline..."
-          variant="success"
-          decoration="outline"
-          helperText="Great choice!"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-      </div>
+        {/* Subscription plan picker */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Subscription Plan
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-md rounded-xl border p-5">
+            <SelectField
+              label="Plan"
+              placeholder="Choose a plan…"
+              value={plan}
+              onValueChange={setPlan}
+              required
+              variant={plan ? "success" : "default"}
+              helperText={
+                plan === "enterprise"
+                  ? "Contact sales to complete upgrade"
+                  : "You can change your plan at any time"
+              }
+              decoration="filled"
+              fullWidth
+            >
+              <SelectItem value="starter">Starter — Free forever</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="pro">Pro — $9 / month</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="team">Team — $29 / month</SelectItem>
+              <SelectSeparator />
+              <SelectItem value="enterprise" disabled>
+                Enterprise — Contact sales
+              </SelectItem>
+            </SelectField>
+          </div>
+        </div>
 
-      {/* Filled decoration */}
-      <div className="space-y-4">
-        <h3 className="text-fm-primary text-lg font-semibold">Filled</h3>
-        <SelectField
-          label="Default"
-          placeholder="Default filled..."
-          variant="default"
-          decoration="filled"
-          helperText="Default variant"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Error"
-          placeholder="Error filled..."
-          variant="error"
-          decoration="filled"
-          helperText="Something went wrong"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Warning"
-          placeholder="Warning filled..."
-          variant="warning"
-          decoration="filled"
-          helperText="Please check selection"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
-        <SelectField
-          label="Success"
-          placeholder="Success filled..."
-          variant="success"
-          decoration="filled"
-          helperText="Great choice!"
-          fullWidth
-        >
-          <SelectItem value="option1">Option 1</SelectItem>
-          <SelectItem value="option2">Option 2</SelectItem>
-        </SelectField>
+        {/* Content filter */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Content Filter
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-md rounded-xl border p-5">
+            <SelectField
+              label="Category"
+              placeholder="Browse by category…"
+              value={category}
+              onValueChange={setCategory}
+              helperText="Filter the podcast library by topic"
+              decoration="underline"
+              fullWidth
+            >
+              <SelectGroup>
+                <SelectLabel className="px-2 pt-2 pb-1">
+                  News & Culture
+                </SelectLabel>
+                <SelectItem value="news">News</SelectItem>
+                <SelectSeparator />
+                <SelectItem value="politics">Politics</SelectItem>
+                <SelectSeparator />
+                <SelectItem value="history">History</SelectItem>
+              </SelectGroup>
+              <SelectSeparator />
+              <SelectGroup>
+                <SelectLabel className="px-2 pt-2 pb-1">
+                  Science & Tech
+                </SelectLabel>
+                <SelectItem value="science">Science</SelectItem>
+                <SelectSeparator />
+                <SelectItem value="technology">Technology</SelectItem>
+                <SelectSeparator />
+                <SelectItem value="ai">Artificial Intelligence</SelectItem>
+              </SelectGroup>
+              <SelectSeparator />
+              <SelectGroup>
+                <SelectLabel className="px-2 pt-2 pb-1">Lifestyle</SelectLabel>
+                <SelectItem value="health">Health & Fitness</SelectItem>
+                <SelectSeparator />
+                <SelectItem value="comedy">Comedy</SelectItem>
+                <SelectSeparator />
+                <SelectItem value="true-crime">True Crime</SelectItem>
+              </SelectGroup>
+            </SelectField>
+          </div>
+        </div>
       </div>
-    </div>
-  ),
+    )
+  },
+}
+
+// ─── 8. Accessibility ────────────────────────────────────────────────────────
+
+export const Accessibility: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Complete showcase of all visual variants across all decoration styles.",
+          "Accessibility-focused examples demonstrating ARIA attributes, required field announcements, error state with aria-invalid, and keyboard navigation support. The select is fully operable via keyboard: Space/Enter opens, arrow keys move through options, Escape closes.",
       },
     },
   },
-}
-
-export const ComplexFormExample: Story = {
-  render: () => {
-    const [country, setCountry] = React.useState("")
-    const [framework, setFramework] = React.useState("")
-
-    return (
-      <div className="max-w-lg space-y-6">
+  render: () => (
+    <div className="w-full max-w-lg space-y-8">
+      {/* Required + aria-required */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+          Required Field
+        </h4>
         <SelectField
           label="Country"
-          placeholder="Select your country"
-          value={country}
-          onValueChange={setCountry}
+          placeholder="Select your country…"
           required
-          helperText={
-            country
-              ? "Country selected successfully"
-              : "Please select your country"
-          }
-          variant={country ? "success" : "default"}
+          helperText="Required — used for regional settings"
           decoration="outline"
           fullWidth
         >
           <SelectItem value="us">United States</SelectItem>
           <SelectItem value="ca">Canada</SelectItem>
           <SelectItem value="uk">United Kingdom</SelectItem>
-          <SelectItem value="de">Germany</SelectItem>
-          <SelectItem value="fr">France</SelectItem>
         </SelectField>
+      </div>
 
+      {/* Error + aria-invalid */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+          Error State (aria-invalid)
+        </h4>
         <SelectField
-          label="Preferred Framework"
-          placeholder="Choose your framework"
-          value={framework}
-          onValueChange={setFramework}
-          helperText="This will help us customize your experience"
-          decoration="filled"
+          label="Plan"
+          placeholder="Select a plan…"
+          variant="error"
+          helperText="Please select a plan to continue"
+          decoration="outline"
           fullWidth
         >
-          <SelectGroup>
-            <SelectLabel className="px-2 pt-2 pb-1">Popular</SelectLabel>
-            <SelectItem value="react">React</SelectItem>
-            <SelectSeparator />
-            <SelectItem value="vue">Vue.js</SelectItem>
-            <SelectSeparator />
-            <SelectItem value="angular">Angular</SelectItem>
-          </SelectGroup>
-          <SelectSeparator />
-          <SelectGroup>
-            <SelectLabel className="px-2 pt-2 pb-1">Others</SelectLabel>
-            <SelectItem value="svelte">Svelte</SelectItem>
-            <SelectSeparator />
-            <SelectItem value="solid">SolidJS</SelectItem>
-          </SelectGroup>
+          <SelectItem value="starter">Starter</SelectItem>
+          <SelectItem value="pro">Pro</SelectItem>
         </SelectField>
       </div>
-    )
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "An example showing multiple SelectField components in a form with different configurations, decorations, and dynamic states based on user input.",
-      },
-    },
-  },
-}
 
-// Legacy stories for backward compatibility with the old API
-export const LegacyDefault: Story = {
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Legacy API example using the atomic Select components directly (for backward compatibility).",
-      },
-    },
-  },
-  render: () => (
-    <Select>
-      <SelectTrigger
-        className="w-[180px]"
-        variant="default"
-        decoration="underline"
-      >
-        <SelectValue placeholder="Select a fruit" />
-      </SelectTrigger>
-      <SelectContent>
-        <SelectItem value="apple">Apple</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="banana">Banana</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="orange">Orange</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="grape">Grape</SelectItem>
-        <SelectSeparator />
-        <SelectItem value="strawberry">Strawberry</SelectItem>
-      </SelectContent>
-    </Select>
-  ),
-}
-
-export const LongList: Story = {
-  render: () => (
-    <SelectField
-      label="Country Selection"
-      placeholder="Select a country"
-      helperText="Scroll to see more options"
-      decoration="outline"
-      fullWidth
-    >
-      <SelectItem value="us">United States</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="ca">Canada</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="uk">United Kingdom</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="fr">France</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="de">Germany</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="it">Italy</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="es">Spain</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="au">Australia</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="jp">Japan</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="kr">South Korea</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="in">India</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="br">Brazil</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="mx">Mexico</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="ar">Argentina</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="cl">Chile</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="pe">Peru</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="co">Colombia</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="ve">Venezuela</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="ec">Ecuador</SelectItem>
-      <SelectSeparator />
-      <SelectItem value="uy">Uruguay</SelectItem>
-    </SelectField>
+      {/* Keyboard navigation info */}
+      <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-sm leading-fm-sm mb-2 font-medium">
+          Keyboard Navigation
+        </p>
+        <ul className="space-y-1">
+          {[
+            "Space / Enter — opens the dropdown",
+            "Arrow Up / Arrow Down — moves between options",
+            "Home / End — jumps to first or last option",
+            "Escape — closes the dropdown without selection",
+            "Tab — moves focus to the next focusable element",
+          ].map((item) => (
+            <li
+              key={item}
+              className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm"
+            >
+              {item}
+            </li>
+          ))}
+        </ul>
+      </div>
+    </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story: `
-Select with many options that demonstrates scrolling behavior. 
-The content area becomes scrollable when it exceeds the maximum height, 
-and scroll buttons appear automatically at the top and bottom.
-        `,
-      },
-    },
-  },
 }