aural-ui 3.0.7 → 4.1.0

package/dist/components/checkbox/Checkbox.stories.tsx

@@ -1,8 +1,9 @@
-import React from "react"
-import { Button } from "@components/button"
+import React, { useState } from "react"
 import { Label } from "@components/label"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import { Checkbox } from "."
 
 const meta: Meta<typeof Checkbox> = {
@@ -10,12 +11,29 @@ const meta: Meta<typeof Checkbox> = {
   component: Checkbox,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A Radix-based checkbox with unchecked, checked, and indeterminate states. Supports disabled variants and integrates with Label for accessible form controls in settings, preferences, and multi-select UIs.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "3 States",
+              description: "Check, partial, unchecked",
+            },
+            {
+              title: "Indeterminate",
+              description: "Partial selection support",
+            },
+            {
+              title: "Label Integration",
+              description: "Works with Label element",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -24,193 +42,317 @@ const meta: Meta<typeof Checkbox> = {
 export default meta
 type Story = StoryObj<typeof Checkbox>
 
-export const Default: Story = {
-  render: () => (
-    <div className="flex items-center space-x-2">
-      <Checkbox id="terms" />
-      <Label htmlFor="terms">Accept terms and conditions</Label>
-    </div>
-  ),
-}
+// ─── 1. States ────────────────────────────────────────────────────────────────
 
 export const States: Story = {
   render: () => (
-    <div className="text-fm-primary flex flex-col space-y-8">
-      {/* Unchecked */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">Unchecked</h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="unchecked" />
-          <Label htmlFor="unchecked">Unchecked</Label>
-        </div>
-      </div>
-
-      {/* Checked */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">Checked</h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="checked" defaultChecked />
-          <Label htmlFor="checked">Checked</Label>
-        </div>
-      </div>
-
-      {/* Indeterminate */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">Indeterminate</h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="indeterminate" indeterminate />
-          <Label htmlFor="indeterminate">Indeterminate</Label>
-        </div>
-      </div>
-
-      {/* Disabled Unchecked */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">Disabled Unchecked</h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="disabled" disabled />
-          <Label htmlFor="disabled" disabled>
-            Disabled Unchecked
-          </Label>
-        </div>
-      </div>
-
-      {/* Disabled Checked */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">Disabled Checked</h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="disabled-checked" disabled defaultChecked />
-          <Label htmlFor="disabled-checked" disabled>
-            Disabled Checked
-          </Label>
+    <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">
+          Active States
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <Checkbox id="s-unchecked" />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Unchecked
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <Checkbox id="s-checked" defaultChecked />
+            </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">
+              <Checkbox id="s-indeterminate" indeterminate defaultChecked />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Indeterminate
+            </p>
+          </div>
         </div>
       </div>
 
-      {/* Disabled Indeterminate Unchecked */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">
-          Disabled Indeterminate Unchecked
-        </h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="disabled-indeterminate" disabled indeterminate />
-          <Label htmlFor="disabled-indeterminate" disabled>
-            Disabled Indeterminate Unchecked
-          </Label>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Disabled States
+        </h4>
+        <div className="flex flex-wrap gap-6">
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <Checkbox id="s-disabled-unchecked" disabled />
+            </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">
+              <Checkbox id="s-disabled-checked" disabled defaultChecked />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled Checked
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <div className="flex justify-center">
+              <Checkbox
+                id="s-disabled-indeterminate"
+                disabled
+                indeterminate
+                defaultChecked
+              />
+            </div>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled Indeterminate
+            </p>
+          </div>
         </div>
       </div>
 
-      {/* Disabled Indeterminate Checked */}
-      <div className="space-y-2">
-        <h3 className="text-lg font-medium">Disabled Indeterminate Checked</h3>
-        <div className="flex items-center space-x-2">
-          <Checkbox
-            id="disabled-indeterminate"
-            disabled
-            indeterminate
-            defaultChecked
-          />
-          <Label htmlFor="disabled-indeterminate" disabled>
-            Disabled Indeterminate Checked
-          </Label>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          With Labels
+        </h4>
+        <div className="space-y-3">
+          <div className="flex items-center gap-3">
+            <Checkbox id="sl-unchecked" />
+            <Label htmlFor="sl-unchecked">Unchecked option</Label>
+          </div>
+          <div className="flex items-center gap-3">
+            <Checkbox id="sl-checked" defaultChecked />
+            <Label htmlFor="sl-checked">Checked option</Label>
+          </div>
+          <div className="flex items-center gap-3">
+            <Checkbox id="sl-indeterminate" indeterminate defaultChecked />
+            <Label htmlFor="sl-indeterminate">Indeterminate option</Label>
+          </div>
+          <div className="flex items-center gap-3">
+            <Checkbox id="sl-disabled" disabled />
+            <Label htmlFor="sl-disabled" disabled>
+              Disabled option
+            </Label>
+          </div>
         </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "All checkbox states — unchecked, checked, indeterminate, and their disabled counterparts — shown as item cards and with label pairings.",
+      },
+    },
+  },
 }
 
-export const WithForm: Story = {
-  render: () => (
-    <form
-      onSubmit={(e) => {
-        e.preventDefault()
-        alert("Form submitted!")
-      }}
-      className="space-y-6"
-    >
-      <div className="space-y-4">
-        <div className="flex items-center space-x-2">
-          <Checkbox id="newsletter" />
-          <Label htmlFor="newsletter">Subscribe to newsletter</Label>
-        </div>
-        <div className="flex items-center space-x-2">
-          <Checkbox id="marketing" />
-          <Label htmlFor="marketing">Receive marketing emails</Label>
-        </div>
-      </div>
-      <Button type="submit">Submit</Button>
-    </form>
-  ),
-}
+// ─── 2. Use Cases ─────────────────────────────────────────────────────────────
 
-export const IndeterminateExample: Story = {
+export const UseCases: Story = {
   render: () => {
-    // This example shows a parent-child relationship where the parent checkbox
-    // becomes indeterminate when some but not all children are checked
-    const [checkedItems, setCheckedItems] = React.useState({
-      option1: false,
-      option2: false,
-      option3: false,
+    const [notifications, setNotifications] = useState({
+      newReleases: true,
+      playlistUpdates: false,
+      liveEvents: true,
+      weeklyDigest: false,
     })
 
-    const allChecked = Object.values(checkedItems).every(Boolean)
-    const indeterminate =
-      Object.values(checkedItems).some(Boolean) && !allChecked
+    const [quality, setQuality] = useState({
+      lossless: false,
+      spatialAudio: true,
+      offlineDownloads: true,
+    })
 
-    const handleParentChange = () => {
-      const newValue = !allChecked
-      setCheckedItems({
-        option1: newValue,
-        option2: newValue,
-        option3: newValue,
-      })
-    }
+    const allNotificationsChecked = Object.values(notifications).every(Boolean)
+    const someNotificationsChecked =
+      Object.values(notifications).some(Boolean) && !allNotificationsChecked
 
-    const handleChildChange = (option: keyof typeof checkedItems) => {
-      setCheckedItems((prev) => ({
-        ...prev,
-        [option]: !prev[option],
-      }))
+    const handleAllNotifications = () => {
+      const next = !allNotificationsChecked
+      setNotifications({
+        newReleases: next,
+        playlistUpdates: next,
+        liveEvents: next,
+        weeklyDigest: next,
+      })
     }
 
     return (
-      <div className="space-y-4">
-        <div className="flex items-center space-x-2">
-          <Checkbox
-            id="parent"
-            checked={allChecked || indeterminate}
-            indeterminate={indeterminate}
-            onCheckedChange={handleParentChange}
-          />
-          <Label htmlFor="parent" className="font-medium">
-            Select all options
-          </Label>
-        </div>
-        <div className="ml-6 space-y-2">
-          <div className="flex items-center space-x-2">
-            <Checkbox
-              id="option1"
-              checked={checkedItems.option1}
-              onCheckedChange={() => handleChildChange("option1")}
-            />
-            <Label htmlFor="option1">Option 1</Label>
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* Notification Preferences */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Notification Preferences
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-1 rounded-xl border p-5">
+            {/* Select all */}
+            <div className="flex items-center gap-3 pb-3">
+              <Checkbox
+                id="uc-all-notifications"
+                checked={allNotificationsChecked || someNotificationsChecked}
+                indeterminate={someNotificationsChecked}
+                onCheckedChange={handleAllNotifications}
+              />
+              <Label
+                htmlFor="uc-all-notifications"
+                className="text-fm-primary font-medium"
+              >
+                All notifications
+              </Label>
+            </div>
+            <div className="border-fm-divider-secondary border-t pt-3">
+              <div className="space-y-3 pl-4">
+                <div className="flex items-center gap-3">
+                  <Checkbox
+                    id="uc-new-releases"
+                    checked={notifications.newReleases}
+                    onCheckedChange={(v) =>
+                      setNotifications((p) => ({
+                        ...p,
+                        newReleases: v === true,
+                      }))
+                    }
+                  />
+                  <div>
+                    <Label htmlFor="uc-new-releases">New Releases</Label>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                      Artists you follow drop new tracks
+                    </p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-3">
+                  <Checkbox
+                    id="uc-playlist-updates"
+                    checked={notifications.playlistUpdates}
+                    onCheckedChange={(v) =>
+                      setNotifications((p) => ({
+                        ...p,
+                        playlistUpdates: v === true,
+                      }))
+                    }
+                  />
+                  <div>
+                    <Label htmlFor="uc-playlist-updates">
+                      Playlist Updates
+                    </Label>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                      Collaborative playlists you&apos;re part of
+                    </p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-3">
+                  <Checkbox
+                    id="uc-live-events"
+                    checked={notifications.liveEvents}
+                    onCheckedChange={(v) =>
+                      setNotifications((p) => ({
+                        ...p,
+                        liveEvents: v === true,
+                      }))
+                    }
+                  />
+                  <div>
+                    <Label htmlFor="uc-live-events">Live Events</Label>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                      Concerts and live streams near you
+                    </p>
+                  </div>
+                </div>
+                <div className="flex items-center gap-3">
+                  <Checkbox
+                    id="uc-weekly-digest"
+                    checked={notifications.weeklyDigest}
+                    onCheckedChange={(v) =>
+                      setNotifications((p) => ({
+                        ...p,
+                        weeklyDigest: v === true,
+                      }))
+                    }
+                  />
+                  <div>
+                    <Label htmlFor="uc-weekly-digest">Weekly Digest</Label>
+                    <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                      Your personalised listening summary
+                    </p>
+                  </div>
+                </div>
+              </div>
+            </div>
           </div>
-          <div className="flex items-center space-x-2">
-            <Checkbox
-              id="option2"
-              checked={checkedItems.option2}
-              onCheckedChange={() => handleChildChange("option2")}
-            />
-            <Label htmlFor="option2">Option 2</Label>
-          </div>
-          <div className="flex items-center space-x-2">
-            <Checkbox
-              id="option3"
-              checked={checkedItems.option3}
-              onCheckedChange={() => handleChildChange("option3")}
-            />
-            <Label htmlFor="option3">Option 3</Label>
+        </div>
+
+        {/* Playback Quality */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Playback Quality Settings
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-3 rounded-xl border p-5">
+            <div className="flex items-center justify-between gap-4">
+              <div>
+                <Label htmlFor="uc-lossless">Lossless Audio</Label>
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                  Stream at full CD-quality resolution
+                </p>
+              </div>
+              <Checkbox
+                id="uc-lossless"
+                checked={quality.lossless}
+                onCheckedChange={(v) =>
+                  setQuality((p) => ({ ...p, lossless: v === true }))
+                }
+              />
+            </div>
+            <div className="border-fm-divider-secondary border-t" />
+            <div className="flex items-center justify-between gap-4">
+              <div>
+                <Label htmlFor="uc-spatial">Spatial Audio</Label>
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                  Immersive 3D sound on supported tracks
+                </p>
+              </div>
+              <Checkbox
+                id="uc-spatial"
+                checked={quality.spatialAudio}
+                onCheckedChange={(v) =>
+                  setQuality((p) => ({ ...p, spatialAudio: v === true }))
+                }
+              />
+            </div>
+            <div className="border-fm-divider-secondary border-t" />
+            <div className="flex items-center justify-between gap-4">
+              <div>
+                <Label htmlFor="uc-offline">Offline Downloads</Label>
+                <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm mt-0.5">
+                  Save tracks for listening without internet
+                </p>
+              </div>
+              <Checkbox
+                id="uc-offline"
+                checked={quality.offlineDownloads}
+                onCheckedChange={(v) =>
+                  setQuality((p) => ({ ...p, offlineDownloads: v === true }))
+                }
+              />
+            </div>
           </div>
         </div>
       </div>
     )
   },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real-world audio app scenarios: a notification preferences panel with a parent indeterminate 'select all' checkbox, and a playback quality settings form.",
+      },
+    },
+  },
 }