aural-ui 4.0.1 → 4.1.0

package/dist/components/radio/Radio.stories.tsx

@@ -1,6 +1,8 @@
-import React from "react"
+import React, { useState } from "react"
 import { Label } from "@components/label"
-import type { Meta } from "@storybook/react-vite"
+import type { Meta, StoryObj } from "@storybook/react-vite"
+
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
 
 import { RadioGroup, RadioGroupItem } from "."
 
@@ -9,145 +11,451 @@ const meta: Meta<typeof RadioGroup> = {
   component: RadioGroup,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A Radix RadioGroup providing single-selection from a set of mutually exclusive options. Supports vertical and horizontal orientations, description text, required state, and disabled items.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Single Select",
+              description: "Mutually exclusive items",
+            },
+            {
+              title: "Orientations",
+              description: "Vertical or horizontal",
+            },
+            {
+              title: "Disabled Items",
+              description: "Per-item disable support",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
 }
 
 export default meta
+type Story = StoryObj<typeof RadioGroup>
 
-export const Default = () => (
-  <RadioGroup defaultValue="option-1">
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-1" id="option-1" />
-      <Label htmlFor="option-1">Option 1</Label>
-    </div>
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-2" id="option-2" />
-      <Label htmlFor="option-2">Option 2</Label>
-    </div>
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-3" id="option-3" />
-      <Label htmlFor="option-3">Option 3</Label>
-    </div>
-  </RadioGroup>
-)
-
-export const States = () => (
-  <div className="text-fm-primary flex flex-col space-y-8">
-    {/* Unselected */}
-    <div className="space-y-2">
-      <h3 className="text-lg font-medium">Unselected</h3>
-      <RadioGroup defaultValue="">
-        <div className="flex items-center space-x-2">
-          <RadioGroupItem value="unselected" id="unselected" />
-          <Label htmlFor="unselected">Unselected Radio</Label>
+// ─── 1. Configurations ────────────────────────────────────────────────────────
+
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Vertical orientation */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Vertical (Default)
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2 text-center">
+            <RadioGroup defaultValue="opt-1" className="gap-3">
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="opt-1" id="c-v-opt-1" />
+                <Label htmlFor="c-v-opt-1">Option One</Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="opt-2" id="c-v-opt-2" />
+                <Label htmlFor="c-v-opt-2">Option Two</Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="opt-3" id="c-v-opt-3" />
+                <Label htmlFor="c-v-opt-3">Option Three</Label>
+              </div>
+            </RadioGroup>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Vertical
+            </p>
+          </div>
         </div>
-      </RadioGroup>
-    </div>
+      </div>
 
-    {/* Selected */}
-    <div className="space-y-2">
-      <h3 className="text-lg font-medium">Selected</h3>
-      <RadioGroup defaultValue="selected">
-        <div className="flex items-center space-x-2">
-          <RadioGroupItem value="selected" id="selected" />
-          <Label htmlFor="selected">Selected Radio</Label>
+      {/* Horizontal orientation */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Horizontal
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2 text-center">
+            <RadioGroup
+              defaultValue="h-opt-1"
+              className="flex flex-row gap-6"
+              orientation="horizontal"
+            >
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="h-opt-1" id="c-h-opt-1" />
+                <Label htmlFor="c-h-opt-1">Option One</Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="h-opt-2" id="c-h-opt-2" />
+                <Label htmlFor="c-h-opt-2">Option Two</Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="h-opt-3" id="c-h-opt-3" />
+                <Label htmlFor="c-h-opt-3">Option Three</Label>
+              </div>
+            </RadioGroup>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Horizontal
+            </p>
+          </div>
         </div>
-      </RadioGroup>
-    </div>
+      </div>
 
-    {/* Disabled */}
-    <div className="space-y-2">
-      <h3 className="text-lg font-medium">Disabled</h3>
-      <RadioGroup defaultValue="">
-        <div className="flex items-center space-x-2">
-          <RadioGroupItem value="disabled" id="disabled" disabled />
-          <Label htmlFor="disabled" disabled>
-            Disabled Radio
-          </Label>
+      {/* With description text */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With Description Text
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2">
+            <RadioGroup defaultValue="desc-opt-1" className="gap-4">
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="desc-opt-1"
+                  id="c-d-opt-1"
+                  className="mt-0.5"
+                />
+                <div>
+                  <Label htmlFor="c-d-opt-1">Standard Quality</Label>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    128 kbps — lower data usage
+                  </p>
+                </div>
+              </div>
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="desc-opt-2"
+                  id="c-d-opt-2"
+                  className="mt-0.5"
+                />
+                <div>
+                  <Label htmlFor="c-d-opt-2">High Quality</Label>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    320 kbps — recommended for headphones
+                  </p>
+                </div>
+              </div>
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="desc-opt-3"
+                  id="c-d-opt-3"
+                  className="mt-0.5"
+                />
+                <div>
+                  <Label htmlFor="c-d-opt-3">Lossless</Label>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    FLAC / ALAC — best for audiophiles
+                  </p>
+                </div>
+              </div>
+            </RadioGroup>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm pt-1">
+              With description
+            </p>
+          </div>
         </div>
-      </RadioGroup>
-    </div>
+      </div>
 
-    {/* Selected Disabled */}
-    <div className="space-y-2">
-      <h3 className="text-lg font-medium">Selected Disabled</h3>
-      <RadioGroup defaultValue="selected-disabled">
-        <div className="flex items-center space-x-2">
-          <RadioGroupItem
-            value="selected-disabled"
-            id="selected-disabled"
-            disabled
-          />
-          <Label htmlFor="selected-disabled" disabled>
-            Selected Disabled Radio
-          </Label>
+      {/* Required */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Required Field
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2 text-center">
+            <RadioGroup className="gap-3" required>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="r-opt-1" id="c-r-opt-1" />
+                <Label htmlFor="c-r-opt-1" required>
+                  Agree to terms
+                </Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="r-opt-2" id="c-r-opt-2" />
+                <Label htmlFor="c-r-opt-2" required>
+                  Disagree
+                </Label>
+              </div>
+            </RadioGroup>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Required
+            </p>
+          </div>
         </div>
-      </RadioGroup>
-    </div>
-  </div>
-)
-
-export const Horizontal = () => (
-  <RadioGroup defaultValue="option-1" className="flex space-x-8">
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-1" id="h-option-1" />
-      <Label htmlFor="h-option-1">Option 1</Label>
-    </div>
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-2" id="h-option-2" />
-      <Label htmlFor="h-option-2">Option 2</Label>
-    </div>
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-3" id="h-option-3" />
-      <Label htmlFor="h-option-3">Option 3</Label>
-    </div>
-  </RadioGroup>
-)
-
-export const Required = () => (
-  <RadioGroup defaultValue="option-1" required>
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-1" id="r-option-1" />
-      <Label htmlFor="r-option-1">Required Option 1</Label>
-    </div>
-    <div className="flex items-center space-x-2">
-      <RadioGroupItem value="option-2" id="r-option-2" />
-      <Label htmlFor="r-option-2">Required Option 2</Label>
+      </div>
     </div>
-  </RadioGroup>
-)
-
-export const WithDescription = () => (
-  <RadioGroup defaultValue="option-1">
-    <div className="space-y-2">
-      <div className="flex items-center space-x-2">
-        <RadioGroupItem value="option-1" id="d-option-1" />
-        <div className="grid gap-1">
-          <Label htmlFor="d-option-1">Option with Description</Label>
-          <p className="text-fm-secondary text-sm">
-            This option has a helpful description.
-          </p>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Configuration axes for RadioGroup: vertical (default) and horizontal orientations, options with description text, and the required field marker.",
+      },
+    },
+  },
+}
+
+// ─── 2. States ────────────────────────────────────────────────────────────────
+
+export const States: Story = {
+  render: () => (
+    <div className="space-y-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Default (Unselected)
+        </h4>
+        <div className="flex flex-wrap gap-8">
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <RadioGroup defaultValue="" className="gap-3">
+                <div className="flex items-center gap-3">
+                  <RadioGroupItem value="st-u-1" id="st-u-1" />
+                  <Label htmlFor="st-u-1">Unselected</Label>
+                </div>
+              </RadioGroup>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Default
+            </p>
+          </div>
+
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <RadioGroup defaultValue="st-c-1" className="gap-3">
+                <div className="flex items-center gap-3">
+                  <RadioGroupItem value="st-c-1" id="st-c-1" />
+                  <Label htmlFor="st-c-1">Selected</Label>
+                </div>
+              </RadioGroup>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Checked
+            </p>
+          </div>
+
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <RadioGroup defaultValue="" className="gap-3">
+                <div className="flex items-center gap-3">
+                  <RadioGroupItem value="st-d-1" id="st-d-1" disabled />
+                  <Label htmlFor="st-d-1" disabled>
+                    Disabled
+                  </Label>
+                </div>
+              </RadioGroup>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
+          </div>
+
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <RadioGroup defaultValue="st-dc-1" className="gap-3">
+                <div className="flex items-center gap-3">
+                  <RadioGroupItem value="st-dc-1" id="st-dc-1" disabled />
+                  <Label htmlFor="st-dc-1" disabled>
+                    Disabled Checked
+                  </Label>
+                </div>
+              </RadioGroup>
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled Checked
+            </p>
+          </div>
         </div>
       </div>
-    </div>
-    <div className="space-y-2">
-      <div className="flex items-center space-x-2">
-        <RadioGroupItem value="option-2" id="d-option-2" />
-        <div className="grid gap-1">
-          <Label htmlFor="d-option-2">Another Option</Label>
-          <p className="text-fm-secondary text-sm">
-            With its own explanation text.
-          </p>
+
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Mixed Group States
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2 text-center">
+            <RadioGroup defaultValue="mix-2" className="gap-3">
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="mix-1" id="mix-1" />
+                <Label htmlFor="mix-1">Active — unselected</Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="mix-2" id="mix-2" />
+                <Label htmlFor="mix-2">Active — selected</Label>
+              </div>
+              <div className="flex items-center gap-3">
+                <RadioGroupItem value="mix-3" id="mix-3" disabled />
+                <Label htmlFor="mix-3" disabled>
+                  Disabled — unavailable
+                </Label>
+              </div>
+            </RadioGroup>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Mixed group
+            </p>
+          </div>
         </div>
       </div>
     </div>
-  </RadioGroup>
-)
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Individual radio item states — default, checked, disabled, and disabled-checked — plus a mixed group demonstrating all states together.",
+      },
+    },
+  },
+}
+
+// ─── 3. Use Cases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
+  render: () => {
+    const [audioQuality, setAudioQuality] = useState("high")
+    const [crossfade, setCrossfade] = useState("short")
+
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* Audio Quality Selector */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Audio Quality
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+            <RadioGroup
+              value={audioQuality}
+              onValueChange={setAudioQuality}
+              className="gap-4"
+            >
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="standard"
+                  id="uc-aq-standard"
+                  className="mt-0.5"
+                />
+                <div className="flex-1">
+                  <div className="flex items-center justify-between">
+                    <Label htmlFor="uc-aq-standard">Standard</Label>
+                    <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      128 kbps
+                    </span>
+                  </div>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    Saves data on mobile connections
+                  </p>
+                </div>
+              </div>
+              <div className="border-fm-divider-secondary border-t" />
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="high"
+                  id="uc-aq-high"
+                  className="mt-0.5"
+                />
+                <div className="flex-1">
+                  <div className="flex items-center justify-between">
+                    <Label htmlFor="uc-aq-high">High</Label>
+                    <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      320 kbps
+                    </span>
+                  </div>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    Recommended for headphones and speakers
+                  </p>
+                </div>
+              </div>
+              <div className="border-fm-divider-secondary border-t" />
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="lossless"
+                  id="uc-aq-lossless"
+                  className="mt-0.5"
+                />
+                <div className="flex-1">
+                  <div className="flex items-center justify-between">
+                    <Label htmlFor="uc-aq-lossless">Lossless</Label>
+                    <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      FLAC
+                    </span>
+                  </div>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    Studio-quality — uses more storage
+                  </p>
+                </div>
+              </div>
+              <div className="border-fm-divider-secondary border-t" />
+              <div className="flex items-start gap-3">
+                <RadioGroupItem
+                  value="spatial"
+                  id="uc-aq-spatial"
+                  className="mt-0.5"
+                  disabled
+                />
+                <div className="flex-1">
+                  <div className="flex items-center justify-between">
+                    <Label htmlFor="uc-aq-spatial" disabled>
+                      Spatial Audio
+                    </Label>
+                    <span className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                      Dolby Atmos
+                    </span>
+                  </div>
+                  <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                    Requires a compatible device
+                  </p>
+                </div>
+              </div>
+            </RadioGroup>
+          </div>
+        </div>
+
+        {/* Crossfade / Playback Settings */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Crossfade Between Tracks
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+            <RadioGroup
+              value={crossfade}
+              onValueChange={setCrossfade}
+              className="flex flex-row flex-wrap gap-4"
+              orientation="horizontal"
+            >
+              {(
+                [
+                  { value: "none", label: "None" },
+                  { value: "short", label: "2 sec" },
+                  { value: "medium", label: "5 sec" },
+                  { value: "long", label: "12 sec" },
+                ] as const
+              ).map(({ value, label }) => (
+                <div key={value} className="flex items-center gap-2">
+                  <RadioGroupItem value={value} id={`uc-cf-${value}`} />
+                  <Label htmlFor={`uc-cf-${value}`}>{label}</Label>
+                </div>
+              ))}
+            </RadioGroup>
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-4">
+              Current: <span className="text-fm-secondary">{crossfade}</span>
+            </p>
+          </div>
+        </div>
+      </div>
+    )
+  },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real-world audio app scenarios: an audio quality selector with descriptions and a disabled option, and a horizontal crossfade duration picker for playback settings.",
+      },
+    },
+  },
+}