aural-ui 4.0.1 → 4.1.0

package/dist/hooks/use-change-state/UseChangeState.stories.tsx

@@ -1,585 +1,294 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
-import { LightBulbSimpleIcon } from "src/ui/icons"
+import {
+  ChevronDownIcon,
+  EyeOpenIcon,
+  FeatureShineIcon,
+  LayoutColumnIcon,
+  LightBulbSimpleIcon,
+  NotepadIcon,
+  SettingIcon,
+} from "src/ui/icons"
+import {
+  HookCodeBlock,
+  HookControlButton,
+  HookPanel,
+  HookPlaygroundCanvas,
+  HookStateCard,
+  HookStateGrid,
+  HookUsageCanvas,
+  HookUsageSection,
+} from "src/ui/story-spec/hooks/hook-story-canvas"
+import { AuralHookDocsPage } from "src/ui/story-spec/hooks/hook-story-docs-page"
 
 import { useChangeState } from "."
 
-const ChangeStateDemo: React.FC<{
-  title?: string
-}> = ({ title = "useChangeState Demo" }) => {
+// ─────────────────────────────────────────────────────────────────────────────
+// Demo components
+// ─────────────────────────────────────────────────────────────────────────────
+
+const ChangeStatePlaygroundDemo: React.FC<{ label?: string }> = ({
+  label = "State Label",
+}) => {
   const { open, onOpenChange } = useChangeState()
 
   return (
-    <div className="!space-y-6 rounded-lg border border-white/10 bg-white/5 !p-6">
-      <h3 className="!text-xl font-semibold !text-white">{title}</h3>
-
-      {/* State Display */}
-      <div className="rounded-lg border border-blue-500/20 bg-blue-500/10 !p-4">
-        <h4 className="!mb-3 !text-lg font-semibold !text-blue-300">
-          Current State
-        </h4>
-        <div className="flex items-center justify-between rounded-lg bg-black/20 !p-3">
-          <span className="!text-sm !text-white/70">Open:</span>
-          <span
-            className={`font-mono !text-lg font-bold ${
-              open ? "!text-green-300" : "!text-red-300"
-            }`}
-          >
-            {String(open)}
-          </span>
-        </div>
+    <HookPlaygroundCanvas>
+      <div className="mx-auto w-full max-w-sm space-y-6 p-8">
+        <HookStateGrid>
+          <HookStateCard label="open" value={String(open)} />
+          <HookStateCard label={label} value={open ? "Active" : "Inactive"} />
+        </HookStateGrid>
+        <HookPanel title="Controls">
+          <div className="flex flex-wrap gap-3">
+            <HookControlButton onClick={() => onOpenChange()}>
+              Toggle
+            </HookControlButton>
+            <HookControlButton
+              onClick={() => onOpenChange(true)}
+              variant="positive"
+            >
+              Set True
+            </HookControlButton>
+            <HookControlButton
+              onClick={() => onOpenChange(false)}
+              variant="negative"
+            >
+              Set False
+            </HookControlButton>
+          </div>
+        </HookPanel>
       </div>
+    </HookPlaygroundCanvas>
+  )
+}
 
-      {/* Controls */}
-      <div className="!space-y-3">
-        <button
-          onClick={() => onOpenChange()}
-          className={`w-full rounded-lg border !px-4 !py-3 !text-sm font-medium transition-colors ${
-            open
-              ? "border-green-500/30 bg-green-500/20 !text-green-300 hover:bg-green-500/30"
-              : "border-red-500/30 bg-red-500/20 !text-red-300 hover:bg-red-500/30"
-          }`}
-        >
-          Toggle State ({open ? "ON" : "OFF"})
-        </button>
-
-        <div className="grid grid-cols-2 gap-3">
-          <button
-            onClick={() => onOpenChange(true)}
-            className="rounded-lg border border-green-500/30 bg-green-500/20 !px-3 !py-2 !text-sm !text-green-300 transition-colors hover:bg-green-500/30"
-          >
-            Set True
-          </button>
-          <button
-            onClick={() => onOpenChange(false)}
-            className="rounded-lg border border-red-500/30 bg-red-500/20 !px-3 !py-2 !text-sm !text-red-300 transition-colors hover:bg-red-500/30"
-          >
-            Set False
-          </button>
-        </div>
-      </div>
+const ChangeStateInteractiveDemo: React.FC = () => {
+  const { open, onOpenChange } = useChangeState()
 
-      {/* Usage Information */}
-      <div className="rounded-lg border border-white/10 bg-black/20 !p-4">
-        <h4 className="!mb-3 !text-lg font-semibold !text-white">Hook Usage</h4>
-        <div className="!space-y-2 !text-sm">
-          <div className="!text-white/70">
-            <span className="font-medium !text-white">Pattern:</span> const{" "}
-            {`{ open, onOpenChange }`} = useChangeState()
-          </div>
-          <div className="!text-white/70">
-            <span className="font-medium !text-white">Toggle:</span>{" "}
-            onOpenChange() - toggles current state
-          </div>
-          <div className="!text-white/70">
-            <span className="font-medium !text-white">Set value:</span>{" "}
-            onOpenChange(true/false) - sets specific value
+  return (
+    <HookPlaygroundCanvas>
+      <div className="mx-auto w-full max-w-lg space-y-6 p-8">
+        <HookStateGrid>
+          <HookStateCard label="open" value={String(open)} />
+          <HookStateCard label="Status" value={open ? "Open" : "Closed"} />
+        </HookStateGrid>
+
+        <HookPanel title="Controls">
+          <div className="flex flex-wrap gap-3">
+            <HookControlButton
+              onClick={() => onOpenChange()}
+              className="flex-1"
+            >
+              Toggle
+            </HookControlButton>
+            <HookControlButton
+              onClick={() => onOpenChange(true)}
+              variant="positive"
+              className="flex-1"
+            >
+              Set True
+            </HookControlButton>
+            <HookControlButton
+              onClick={() => onOpenChange(false)}
+              variant="negative"
+              className="flex-1"
+            >
+              Set False
+            </HookControlButton>
           </div>
-        </div>
+        </HookPanel>
+
+        <HookCodeBlock
+          code={`const { open, onOpenChange } = useChangeState()
+
+onOpenChange()        // toggles current state
+onOpenChange(true)    // sets open = true
+onOpenChange(false)   // sets open = false`}
+        />
       </div>
-    </div>
+    </HookPlaygroundCanvas>
   )
 }
 
-const meta: Meta<typeof ChangeStateDemo> = {
+// ─────────────────────────────────────────────────────────────────────────────
+// Meta
+// ─────────────────────────────────────────────────────────────────────────────
+
+const meta: Meta<typeof ChangeStatePlaygroundDemo> = {
   title: "Hooks/useChangeState",
-  component: ChangeStateDemo,
+  component: ChangeStatePlaygroundDemo,
   parameters: {
     layout: "fullscreen",
     backgrounds: {
       default: "dark",
       values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "darker", value: "#000000" },
-        { name: "light", value: "#ffffff" },
+        { name: "dark", value: "var(--color-fm-surface-primary)" },
+        { name: "darker", value: "var(--color-fm-neutral-0)" },
+        { name: "light", value: "var(--color-fm-neutral-1100)" },
       ],
     },
     docs: {
       page: () => (
-        <>
-          {/* Override default docs styling */}
-          <style>
-            {`
-              .sbdocs-wrapper {
-                padding: 0 !important;
-                max-width: none !important;
-                background: transparent !important;
-              }
-              .sbdocs-content {
-                max-width: none !important;
-                padding: 0 !important;
-                margin: 0 !important;
-                background: transparent !important;
-              }
-              .docs-story {
-                background: transparent !important;
-              }
-              .sbdocs {
-                background: transparent !important;
-              }
-              body {
-                background: #0a0a0a !important;
-              }
-              #storybook-docs {
-                background: #0a0a0a !important;
-              }
-              .sbdocs-preview {
-                background: transparent !important;
-                border: none !important;
-              }
-              .sbdocs-h1, .sbdocs-h2, .sbdocs-h3, .sbdocs-h4, .sbdocs-h5, .sbdocs-h6 {
-                color: white !important;
-              }
-              .sbdocs-p, .sbdocs-li {
-                color: rgba(255, 255, 255, 0.7) !important;
-              }
-              .sbdocs-code {
-                background: rgba(255, 255, 255, 0.1) !important;
-                color: rgba(168, 85, 247, 1) !important;
-                border: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-pre {
-                background: rgba(0, 0, 0, 0.4) !important;
-                border: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-table {
-                background: rgba(255, 255, 255, 0.05) !important;
-                border: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-table th {
-                background: rgba(255, 255, 255, 0.05) !important;
-                color: white !important;
-                border-bottom: 1px solid rgba(255, 255, 255, 0.1) !important;
-              }
-              .sbdocs-table td {
-                color: rgba(255, 255, 255, 0.7) !important;
-                border-bottom: 1px solid rgba(255, 255, 255, 0.05) !important;
-              }
-            `}
-          </style>
-
-          <div className="min-h-screen bg-gradient-to-br from-gray-900 via-purple-900/20 to-gray-900">
-            {/* Header */}
-            <div className="relative overflow-hidden border-b border-white/10 bg-black/20 backdrop-blur-xl">
-              <div className="absolute inset-0 bg-gradient-to-r from-purple-500/10 via-transparent to-indigo-500/10" />
-              <div className="relative !mx-auto max-w-7xl !px-6 !py-16">
-                <div className="!space-y-6 text-center">
-                  <div className="!mx-auto flex !h-24 !w-24 items-center justify-center rounded-2xl border border-purple-500/30 bg-gradient-to-br from-purple-500/20 to-indigo-500/20">
-                    <span className="!text-4xl">
-                      <LightBulbSimpleIcon className="text-fm-primary size-10" />
-                    </span>
-                  </div>
-                  <h1 className="!text-fm-primary !text-5xl font-bold">
-                    useChangeState
-                  </h1>
-                  <p className="!mx-auto max-w-3xl !text-xl leading-relaxed !text-white/70">
-                    A versatile React hook that manages boolean state with a
-                    flexible toggle function. Perfect for modals, dropdowns,
-                    accordions, and any component that needs show/hide
-                    functionality with customizable state control.
-                  </p>
-
-                  {/* Stats */}
-                  <div className="flex items-center justify-center gap-8 !pt-8">
-                    <div className="text-center">
-                      <div className="!text-3xl font-bold !text-purple-300">
-                        Flexible
-                      </div>
-                      <div className="!text-sm !text-white/60">
-                        Toggle or set specific value
-                      </div>
-                    </div>
-                    <div className="!h-8 !w-px bg-white/20" />
-                    <div className="text-center">
-                      <div className="!text-3xl font-bold !text-indigo-300">
-                        Optimized
-                      </div>
-                      <div className="!text-sm !text-white/60">
-                        Memoized callbacks
-                      </div>
-                    </div>
-                    <div className="!h-8 !w-px bg-white/20" />
-                    <div className="text-center">
-                      <div className="!text-3xl font-bold !text-cyan-300">
-                        Intuitive
-                      </div>
-                      <div className="!text-sm !text-white/60">
-                        Natural API design
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              </div>
-            </div>
-
-            {/* Content */}
-            <div className="!mx-auto max-w-7xl !space-y-16 !px-6 !py-12">
-              {/* Quick Usage */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Quick Start
-                </h2>
-                <div className="grid grid-cols-1 gap-8 lg:grid-cols-2">
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-purple-300">
-                      Basic Usage
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`import { useChangeState } from "@hooks/use-change-state"
+        <AuralHookDocsPage
+          icon={LightBulbSimpleIcon}
+          features={[
+            { title: "Flexible", description: "Toggle or set specific value" },
+            { title: "Optimized", description: "Memoized callbacks" },
+            { title: "Intuitive", description: "Natural API design" },
+          ]}
+          quickStart={{
+            codeExample: `import { useChangeState } from "src/ui/hooks/use-change-state"
 
 function Modal() {
   const { open, onOpenChange } = useChangeState()
 
   return (
     <>
-      <button onClick={() => onOpenChange(true)}>
-        Open Modal
-      </button>
-      
+      <button onClick={() => onOpenChange(true)}>Open Modal</button>
+
       {open && (
-        <div className="modal-overlay">
-          <div className="modal-content">
-            <h2>Modal Title</h2>
-            <button onClick={() => onOpenChange(false)}>
-              Close
-            </button>
-            <button onClick={() => onOpenChange()}>
-              Toggle
-            </button>
-          </div>
+        <div>
+          <h2>Modal Title</h2>
+          <button onClick={() => onOpenChange(false)}>Close</button>
+          <button onClick={() => onOpenChange()}>Toggle</button>
         </div>
       )}
     </>
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-purple-300">
-                      Hook Properties
-                    </h3>
-                    <div className="!space-y-3 rounded-lg border border-white/10 bg-white/5 !p-4">
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Returns:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Object with state & handler
-                        </span>
-                      </div>
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Initial state:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          false
-                        </span>
-                      </div>
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Toggle behavior:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Smart default
-                        </span>
-                      </div>
-                      <div className="flex justify-between">
-                        <span className="!text-sm !text-white/70">
-                          Performance:
-                        </span>
-                        <span className="!text-sm font-medium !text-white">
-                          Memoized callback
-                        </span>
-                      </div>
-                    </div>
-                  </div>
-                </div>
-              </div>
-
-              {/* API Documentation */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  API Reference
-                </h2>
-
-                <div className="overflow-hidden rounded-lg border border-white/10 bg-white/5">
-                  <div className="bg-white/5 !p-4">
-                    <h3 className="!text-xl font-semibold !text-white">
-                      Hook Signature
-                    </h3>
-                  </div>
-                  <div className="!p-6">
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="!text-sm !text-green-300">
-                        {`function useChangeState(): {
+}`,
+            hookProperties: [
+              { label: "Returns", value: "Object with state & handler" },
+              { label: "Initial state", value: "false" },
+              { label: "Toggle behavior", value: "Smart default" },
+              { label: "Performance", value: "Memoized callback" },
+            ],
+          }}
+          hookSignature={`function useChangeState(): {
   open: boolean
   onOpenChange: (value?: boolean) => void
 }`}
-                      </pre>
-                    </div>
-                  </div>
-                </div>
-
-                <div className="overflow-hidden rounded-lg border border-white/10 bg-white/5">
-                  <div className="bg-white/5 !p-4">
-                    <h3 className="!text-xl font-semibold !text-white">
-                      Return Value & Methods
-                    </h3>
-                  </div>
-                  <table className="!my-0 w-full">
-                    <thead className="bg-white/5">
-                      <tr className="border-b border-white/10">
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Property
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Type
-                        </th>
-                        <th className="!px-6 !py-4 text-left !text-sm font-semibold !text-white">
-                          Description
-                        </th>
-                      </tr>
-                    </thead>
-                    <tbody>
-                      <tr className="border-b border-white/5">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-purple-300">
-                          open
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          boolean
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Current state value (initially false)
-                        </td>
-                      </tr>
-                      <tr className="!bg-black/10">
-                        <td className="!px-6 !py-4 font-mono !text-sm !text-purple-300">
-                          onOpenChange
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          (value?: boolean) ={">"} void
-                        </td>
-                        <td className="!px-6 !py-4 !text-sm !text-white/70">
-                          Function to update state. Toggles if no value
-                          provided, sets specific value if provided
-                        </td>
-                      </tr>
-                    </tbody>
-                  </table>
-                </div>
-              </div>
-
-              {/* Use Cases */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Common Use Cases
-                </h2>
-                <div className="grid grid-cols-1 gap-6 md:grid-cols-2 lg:grid-cols-3">
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-blue-500/20">
-                      <span className="!text-2xl">🪟</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Modals & Dialogs
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Control modal visibility with precise open/close
-                      functionality and smooth toggle behavior.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-green-500/20">
-                      <span className="!text-2xl">📋</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Dropdowns
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Manage dropdown menu states with intelligent toggle and
-                      explicit control methods.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-purple-500/20">
-                      <span className="!text-2xl">📖</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Accordions
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Handle expand/collapse states for accordion components and
-                      collapsible content sections.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-orange-500/20">
-                      <span className="!text-2xl">👁️</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Show/Hide Content
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Toggle visibility of any content with flexible control
-                      over show and hide operations.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-cyan-500/20">
-                      <span className="!text-2xl">🎛️</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      UI Controls
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Power switches, toggles, and other boolean-based UI
-                      components with optimized state management.
-                    </p>
-                  </div>
-
-                  <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                    <div className="!mb-4 flex !h-12 !w-12 items-center justify-center rounded-lg bg-pink-500/20">
-                      <span className="!text-2xl">🔧</span>
-                    </div>
-                    <h3 className="!mb-2 !text-lg font-semibold !text-white">
-                      Feature Flags
-                    </h3>
-                    <p className="!text-sm !text-white/70">
-                      Implement feature toggles and conditional rendering with
-                      clean state management patterns.
-                    </p>
-                  </div>
-                </div>
-              </div>
-
-              {/* Usage Patterns */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Usage Patterns
-                </h2>
-                <div className="grid grid-cols-1 gap-8 lg:grid-cols-2">
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-purple-300">
-                      Modal with Backdrop Close
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`function ConfirmDialog({ message, onConfirm }) {
+          returns={[
+            {
+              name: "open",
+              type: "boolean",
+              description: "Current state value, initially false.",
+            },
+            {
+              name: "onOpenChange",
+              type: "(value?: boolean) => void",
+              description:
+                "Toggles the state when called with no argument; sets a specific value when a boolean is passed.",
+            },
+          ]}
+          useCases={[
+            {
+              icon: NotepadIcon,
+              title: "Modals & Dialogs",
+              description:
+                "Control modal visibility with precise open/close and toggle behavior.",
+            },
+            {
+              icon: ChevronDownIcon,
+              title: "Dropdowns",
+              description:
+                "Manage dropdown menu states with intelligent toggle and explicit control.",
+            },
+            {
+              icon: LayoutColumnIcon,
+              title: "Accordions",
+              description:
+                "Handle expand/collapse states for accordion and collapsible sections.",
+            },
+            {
+              icon: EyeOpenIcon,
+              title: "Show / Hide",
+              description:
+                "Toggle visibility of any content with flexible show and hide control.",
+            },
+            {
+              icon: SettingIcon,
+              title: "UI Controls",
+              description:
+                "Power switches, toggles, and other boolean-based UI components.",
+            },
+            {
+              icon: FeatureShineIcon,
+              title: "Feature Flags",
+              description:
+                "Implement feature toggles and conditional rendering patterns.",
+            },
+          ]}
+          usagePatterns={[
+            {
+              title: "Modal with Backdrop Close",
+              code: `function ConfirmDialog({ message, onConfirm }) {
   const { open, onOpenChange } = useChangeState()
 
   const handleBackdropClick = (e) => {
-    if (e.target === e.currentTarget) {
-      onOpenChange(false)
-    }
+    if (e.target === e.currentTarget) onOpenChange(false)
   }
 
   return (
     <>
-      <button onClick={() => onOpenChange(true)}>
-        Delete Item
-      </button>
-      
+      <button onClick={() => onOpenChange(true)}>Delete Item</button>
+
       {open && (
-        <div 
-          className="modal-overlay" 
-          onClick={handleBackdropClick}
-        >
+        <div className="modal-overlay" onClick={handleBackdropClick}>
           <div className="modal-content">
             <p>{message}</p>
             <button onClick={onConfirm}>Confirm</button>
-            <button onClick={() => onOpenChange(false)}>
-              Cancel
-            </button>
+            <button onClick={() => onOpenChange(false)}>Cancel</button>
           </div>
         </div>
       )}
     </>
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-purple-300">
-                      Collapsible Section
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`function CollapsibleCard({ title, children }) {
+}`,
+            },
+            {
+              title: "Collapsible Section",
+              code: `function CollapsibleCard({ title, children }) {
   const { open, onOpenChange } = useChangeState()
 
   return (
     <div className="card">
-      <div 
-        className="card-header"
-        onClick={() => onOpenChange()}
-      >
+      <div className="card-header" onClick={() => onOpenChange()}>
         <h3>{title}</h3>
-        <span className={\`icon \${open ? 'rotate' : ''}\`}>
-          ▼
-        </span>
+        <span className={\`icon \${open ? "rotate" : ""}\`}>▼</span>
       </div>
-      
-      {open && (
-        <div className="card-content">
-          {children}
-        </div>
-      )}
+
+      {open && <div className="card-content">{children}</div>}
     </div>
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-purple-300">
-                      Controlled Dropdown Menu
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`function DropdownMenu({ trigger, items }) {
+}`,
+            },
+            {
+              title: "Controlled Dropdown",
+              code: `function DropdownMenu({ trigger, items }) {
   const { open, onOpenChange } = useChangeState()
   const menuRef = useRef()
 
   useEffect(() => {
-    const handleClickOutside = (event) => {
-      if (menuRef.current && 
-          !menuRef.current.contains(event.target)) {
+    const handleOutside = (e) => {
+      if (menuRef.current && !menuRef.current.contains(e.target)) {
         onOpenChange(false)
       }
     }
-
     if (open) {
-      document.addEventListener('click', handleClickOutside)
-      return () => document.removeEventListener('click', handleClickOutside)
+      document.addEventListener("click", handleOutside)
+      return () => document.removeEventListener("click", handleOutside)
     }
   }, [open, onOpenChange])
 
   return (
-    <div className="dropdown" ref={menuRef}>
-      <button onClick={() => onOpenChange()}>
-        {trigger}
-      </button>
-      
+    <div ref={menuRef}>
+      <button onClick={() => onOpenChange()}>{trigger}</button>
       {open && (
         <div className="dropdown-menu">
-          {items.map(item => (
-            <div 
-              key={item.id}
-              onClick={() => {
-                item.onClick()
-                onOpenChange(false)
-              }}
-            >
+          {items.map((item) => (
+            <div key={item.id} onClick={() => { item.onClick(); onOpenChange(false) }}>
               {item.label}
             </div>
           ))}
@@ -587,73 +296,41 @@ function Modal() {
       )}
     </div>
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-
-                  <div className="!space-y-4">
-                    <h3 className="!text-xl font-semibold !text-purple-300">
-                      Conditional Form Section
-                    </h3>
-                    <div className="rounded-lg bg-black/40 !p-4">
-                      <pre className="overflow-x-auto !text-sm !text-green-300">
-                        {`function ProfileForm() {
+}`,
+            },
+            {
+              title: "Conditional Form Section",
+              code: `function ProfileForm() {
   const { open: showAdvanced, onOpenChange } = useChangeState()
   const [formData, setFormData] = useState({})
 
-  const toggleAdvancedOptions = () => {
-    onOpenChange()
-    
-    // Reset advanced fields when hiding
+  const toggleAdvanced = () => {
     if (showAdvanced) {
-      setFormData(prev => ({
-        ...prev,
-        advancedField1: '',
-        advancedField2: ''
-      }))
+      setFormData((prev) => ({ ...prev, advField1: "", advField2: "" }))
     }
+    onOpenChange()
   }
 
   return (
     <div>
       <input placeholder="Name" />
       <input placeholder="Email" />
-      
-      <button 
-        type="button" 
-        onClick={toggleAdvancedOptions}
-      >
-        {showAdvanced ? 'Hide' : 'Show'} Advanced Options
+      <button type="button" onClick={toggleAdvanced}>
+        {showAdvanced ? "Hide" : "Show"} Advanced Options
       </button>
-      
       {showAdvanced && (
-        <div className="advanced-section">
+        <div>
           <input placeholder="Advanced Field 1" />
           <input placeholder="Advanced Field 2" />
         </div>
       )}
     </div>
   )
-}`}
-                      </pre>
-                    </div>
-                  </div>
-                </div>
-              </div>
-
-              {/* Implementation Details */}
-              <div className="!space-y-8">
-                <h2 className="text-center !text-3xl font-bold !text-white">
-                  Implementation
-                </h2>
-                <div className="rounded-lg border border-white/10 bg-white/5 !p-6">
-                  <h3 className="!mb-4 !text-xl font-semibold !text-white">
-                    Hook Implementation
-                  </h3>
-                  <div className="rounded-lg bg-black/40 !p-4">
-                    <pre className="overflow-x-auto !text-sm !text-blue-300">
-                      {`import React from "react"
+}`,
+            },
+          ]}
+          implementation={{
+            code: `import React from "react"
 
 export const useChangeState = () => {
   const [open, setOpen] = React.useState(false)
@@ -669,61 +346,22 @@ export const useChangeState = () => {
     open,
     onOpenChange,
   }
-}`}
-                    </pre>
-                  </div>
-                  <div className="!mt-4 !space-y-2 !text-sm !text-white/70">
-                    <p className="!text-white">
-                      The hook combines{" "}
-                      <code className="!text-purple-300">useState</code> for
-                      boolean state management with{" "}
-                      <code className="!text-purple-300">useCallback</code> for
-                      optimized performance.
-                    </p>
-                    <p className="!text-white">
-                      The <code className="!text-purple-300">onOpenChange</code>{" "}
-                      function defaults to toggling the current state when no
-                      parameter is provided, or sets the exact value when a
-                      boolean is passed.
-                    </p>
-                    <p className="!text-white">
-                      <code className="!text-purple-300">useCallback</code>{" "}
-                      prevents unnecessary re-renders by memoizing the state
-                      updater function.
-                    </p>
-                  </div>
-                </div>
-              </div>
-            </div>
-
-            {/* Footer */}
-            <div className="border-t border-white/10 bg-black/20 backdrop-blur-xl">
-              <div className="!mx-auto max-w-7xl !px-6 !py-8">
-                <div className="!space-y-4 text-center">
-                  <p className="!text-white/60">
-                    useChangeState provides an elegant solution for boolean
-                    state management with intelligent defaults and flexible
-                    control options, perfect for any show/hide UI pattern in
-                    React applications.
-                  </p>
-                  <p className="!text-sm !text-white/40">
-                    Optimized, intuitive, and versatile - the essential hook for
-                    managing toggleable component states with precision.
-                  </p>
-                </div>
-              </div>
-            </div>
-          </div>
-        </>
+}`,
+            notes: [
+              "Combines useState for boolean state management with useCallback to produce a stable, memoized handler that avoids unnecessary re-renders.",
+              "onOpenChange toggles the current state when called with no argument, or sets the exact boolean value when one is passed — a single function covers both use cases.",
+              "Because the default parameter is evaluated at call time, passing undefined explicitly also triggers the toggle behavior, keeping the API predictable.",
+            ],
+          }}
+        />
       ),
     },
   },
-
   tags: ["autodocs"],
   argTypes: {
-    title: {
+    label: {
       control: "text",
-      description: "Title for the demo component",
+      description: "Label shown on the status card in the playground",
     },
   },
 }
@@ -731,14 +369,79 @@ export const useChangeState = () => {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    title: "useChangeState Demo",
-  },
-}
+// ─────────────────────────────────────────────────────────────────────────────
+// Story exports
+// ─────────────────────────────────────────────────────────────────────────────
 
 export const Playground: Story = {
   args: {
-    title: "Toggle State Hook",
+    label: "State Label",
   },
+  render: (args) => <ChangeStatePlaygroundDemo {...args} />,
+}
+
+export const Interactive: Story = {
+  render: () => <ChangeStateInteractiveDemo />,
+}
+
+export const UseCases: Story = {
+  render: () => (
+    <HookUsageCanvas>
+      <HookUsageSection title="Modal with Backdrop Close">
+        <HookCodeBlock
+          code={`function Modal() {
+  const { open, onOpenChange } = useChangeState()
+  return (
+    <>
+      <button onClick={() => onOpenChange(true)}>Open</button>
+      {open && (
+        <div onClick={(e) => e.target === e.currentTarget && onOpenChange(false)}>
+          <div>
+            <h2>Modal</h2>
+            <button onClick={() => onOpenChange(false)}>Close</button>
+          </div>
+        </div>
+      )}
+    </>
+  )
+}`}
+        />
+      </HookUsageSection>
+
+      <HookUsageSection title="Collapsible Section">
+        <HookCodeBlock
+          code={`function Collapsible({ title, children }) {
+  const { open, onOpenChange } = useChangeState()
+  return (
+    <div>
+      <button onClick={() => onOpenChange()}>{title} {open ? "▲" : "▼"}</button>
+      {open && <div>{children}</div>}
+    </div>
+  )
+}`}
+        />
+      </HookUsageSection>
+
+      <HookUsageSection title="Feature Flag Toggle">
+        <HookCodeBlock
+          code={`function FeatureGate({ children }) {
+  const { open: enabled, onOpenChange } = useChangeState()
+  return (
+    <div>
+      <label>
+        <input
+          type="checkbox"
+          checked={enabled}
+          onChange={(e) => onOpenChange(e.target.checked)}
+        />
+        Enable feature
+      </label>
+      {enabled && children}
+    </div>
+  )
+}`}
+        />
+      </HookUsageSection>
+    </HookUsageCanvas>
+  ),
 }