aural-ui 4.0.1 → 4.1.0

package/dist/components/otp-inputs/OtpInputs.stories.tsx

@@ -1,6 +1,8 @@
 import React, { useState } from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import OtpInputs from "."
 
 const meta: Meta<typeof OtpInputs> = {
@@ -8,58 +10,29 @@ const meta: Meta<typeof OtpInputs> = {
   component: OtpInputs,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
-        component: `
-# OTP Input Component
-
-A flexible and accessible OTP (One-Time Password) input component that allows users to enter verification codes with individual input fields.
-
-## Features
-
-- **Customizable Length**: Configure the number of input fields (default: 6)
-- **Number/Text Input**: Support for both numeric and alphanumeric OTP codes
-- **Keyboard Navigation**: Full keyboard support with arrow keys, backspace, and delete
-- **Auto-focus Management**: Automatic focus progression when typing
-- **Accessibility**: Proper ARIA attributes and keyboard navigation
-- **Custom Styling**: Flexible styling options for inputs and container
-- **Disabled State**: Support for disabled state
-
-## Usage Examples
-
-### Basic OTP Input
-\`\`\`tsx
-<OtpInputs 
-  length={6} 
-  onChangeOTP={(otp) => console.log(otp)} 
-/>
-\`\`\`
-
-### Alphanumeric OTP
-\`\`\`tsx
-<OtpInputs 
-  length={6}
-  isNumberInput={false}
-  onChangeOTP={(otp) => console.log(otp)}
-/>
-\`\`\`
-
-## Props Overview
-
-- **length**: Number of input fields (required)
-- **isNumberInput**: Whether to restrict input to numbers only (default: true)
-- **disabled**: Disable all inputs (default: false)
-- **onChangeOTP**: Callback when OTP value changes (required)
-- **inputStyle**: Inline styles for individual inputs
-        `,
+        component:
+          "An accessible OTP (One-Time Password) input that renders individual character boxes for entering verification codes. Supports configurable length, numeric or alphanumeric modes, keyboard navigation with auto-focus progression, paste handling, disabled state, and live validation feedback via helper text.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "Configurable Length",
+              description: "1–10 digit boxes",
+            },
+            {
+              title: "Auto-focus & Paste",
+              description: "Keyboard nav built in",
+            },
+            {
+              title: "Numeric or Alpha",
+              description: "isNumberInput toggle",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -70,7 +43,7 @@ A flexible and accessible OTP (One-Time Password) input component that allows us
     },
     isNumberInput: {
       control: { type: "boolean" },
-      description: "Whether to restrict input to numbers only",
+      description: "Restrict input to digits only",
     },
     disabled: {
       control: { type: "boolean" },
@@ -78,7 +51,7 @@ A flexible and accessible OTP (One-Time Password) input component that allows us
     },
     onChangeOTP: {
       action: "otpChanged",
-      description: "Callback when OTP value changes",
+      description: "Callback fired when the composed OTP string changes",
     },
   },
 }
@@ -86,417 +59,374 @@ A flexible and accessible OTP (One-Time Password) input component that allows us
 export default meta
 type Story = StoryObj<typeof OtpInputs>
 
-export const Default: Story = {
-  args: {
-    length: 6,
-    isNumberInput: true,
-    disabled: false,
-    onChangeOTP: (otp: string) => console.log("OTP changed:", otp),
-  },
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-export const FourDigits: Story = {
+export const Playground: Story = {
   args: {
-    length: 4,
+    length: 6,
     isNumberInput: true,
     disabled: false,
-    onChangeOTP: (otp: string) => console.log("OTP changed:", otp),
-  },
-}
-
-export const EightDigits: Story = {
-  args: {
-    length: 8,
-    isNumberInput: true,
-    onChangeOTP: (otp: string) => console.log("OTP changed:", otp),
-  },
-}
-
-export const Alphanumeric: Story = {
-  args: {
-    length: 6,
-    isNumberInput: false,
-    onChangeOTP: (otp: string) => console.log("OTP changed:", otp),
+    onChangeOTP: (otp: string) => console.log("OTP:", otp),
   },
-}
-
-export const Disabled: Story = {
-  args: {
-    length: 6,
-    isNumberInput: true,
-    disabled: true,
-    onChangeOTP: (otp: string) => console.log("OTP changed:", otp),
+  render: (args) => (
+    <div className="w-full max-w-sm space-y-4">
+      <OtpInputs {...args} />
+      <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)">
+          {`<OtpInputs length={${args.length}} isNumberInput={${args.isNumberInput}} disabled={${args.disabled}} />`}
+        </code>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the sidebar controls to adjust length, numeric mode, and disabled state. The code snippet updates to reflect the current props.",
+      },
+    },
   },
 }
 
-export const Interactive: Story = {
-  render: () => {
-    const [otpValue, setOtpValue] = useState("")
+// ─── 2. Configurations ────────────────────────────────────────────────────────
 
-    return (
+export const Configurations: Story = {
+  render: () => (
+    <div className="space-y-8">
+      {/* Length variants */}
       <div className="space-y-4">
-        <OtpInputs length={6} onChangeOTP={setOtpValue} />
-        <p className="text-fm-secondary text-sm">
-          Current OTP: {otpValue || "Empty"}
-        </p>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Length
+        </h4>
+        <div className="space-y-6">
+          <div className="space-y-2 text-center">
+            <OtpInputs
+              length={4}
+              isNumberInput={true}
+              onChangeOTP={(otp) => console.log("4-digit OTP:", otp)}
+              messages={{ neutral: "4-digit code" }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              4-digit — common for SMS PIN
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <OtpInputs
+              length={6}
+              isNumberInput={true}
+              onChangeOTP={(otp) => console.log("6-digit OTP:", otp)}
+              messages={{ neutral: "6-digit code" }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              6-digit — standard authenticator / email
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <OtpInputs
+              length={8}
+              isNumberInput={true}
+              onChangeOTP={(otp) => console.log("8-digit OTP:", otp)}
+              messages={{ neutral: "8-digit code" }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              8-digit — extended security token
+            </p>
+          </div>
+        </div>
       </div>
-    )
-  },
-}
-
-export const WithValidation: Story = {
-  render: () => {
-    const [isValid, setIsValid] = useState<boolean | null>(null)
 
-    const handleOtpChange = (otp: string) => {
-      if (otp.length === 6) {
-        setIsValid(otp === "123456")
-      } else {
-        setIsValid(null)
-      }
-    }
-
-    return (
-      <OtpInputs
-        length={6}
-        onChangeOTP={handleOtpChange}
-        isValid={isValid}
-        messages={{
-          error: "Invalid OTP, try: 123456",
-        }}
-      />
-    )
+      {/* Input type */}
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Input Type
+        </h4>
+        <div className="space-y-6">
+          <div className="space-y-2 text-center">
+            <OtpInputs
+              length={6}
+              isNumberInput={true}
+              onChangeOTP={(otp) => console.log("Numeric OTP:", otp)}
+              messages={{ neutral: "Digits only (0–9)" }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Numeric — accepts digits only
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <OtpInputs
+              length={6}
+              isNumberInput={false}
+              onChangeOTP={(otp) => console.log("Alphanumeric OTP:", otp)}
+              messages={{ neutral: "Letters + numbers" }}
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Alphanumeric — accepts letters and digits
+            </p>
+          </div>
+        </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Two configuration axes: code length (4 / 6 / 8 digits) and input type (numeric vs alphanumeric). Combine both axes to cover every common OTP use case.",
+      },
+    },
   },
 }
 
-export const AllVariants: Story = {
-  render: () => {
-    const [otp4, setOtp4] = useState("")
-    const [otp6, setOtp6] = useState("")
-    const [otp8, setOtp8] = useState("")
-    const [alphanumericOtp, setAlphanumericOtp] = useState("")
-    const [validatedOtp, setValidatedOtp] = useState("")
-    const [isValid, setIsValid] = useState<boolean | null>(null)
-
-    const handleValidation = (otp: string) => {
-      setValidatedOtp(otp)
-      if (otp.length === 6) {
-        setIsValid(otp === "123456")
-      } else {
-        setIsValid(null)
-      }
-    }
+// ─── 3. States ────────────────────────────────────────────────────────────────
 
-    return (
-      <div className="max-w-4xl space-y-8 p-6">
-        <div className="space-y-2">
-          <h2 className="text-fm-primary text-2xl font-bold">
-            OTP Input - All Variants
-          </h2>
-          <p className="text-fm-secondary">
-            Comprehensive showcase of all OTP input configurations, states, and
-            use cases.
+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
+        </h4>
+        <div className="space-y-2 text-center">
+          <OtpInputs
+            length={6}
+            isNumberInput={true}
+            onChangeOTP={(otp) => console.log("Default OTP:", otp)}
+            messages={{ neutral: "Enter your 6-digit verification code" }}
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Ready to receive input
           </p>
         </div>
+      </div>
 
-        {/* Basic Length Variants */}
-        <div className="space-y-4">
-          <h3 className="text-fm-primary text-xl font-semibold">
-            Length Variants
-          </h3>
-
-          <div className="space-y-3">
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                4-Digit OTP (Common for SMS)
-              </label>
-              <OtpInputs
-                length={4}
-                isNumberInput={true}
-                onChangeOTP={setOtp4}
-              />
-              <p className="text-fm-tertiary mt-1 text-xs">
-                Current: {otp4 || "Empty"}
-              </p>
-            </div>
-
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                6-Digit OTP (Standard)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={setOtp6}
-              />
-              <p className="text-fm-tertiary mt-1 text-xs">
-                Current: {otp6 || "Empty"}
-              </p>
-            </div>
-
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                8-Digit OTP (Extended Security)
-              </label>
-              <OtpInputs
-                length={8}
-                isNumberInput={true}
-                onChangeOTP={setOtp8}
-              />
-              <p className="text-fm-tertiary mt-1 text-xs">
-                Current: {otp8 || "Empty"}
-              </p>
-            </div>
-          </div>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Disabled
+        </h4>
+        <div className="space-y-2 text-center">
+          <OtpInputs
+            length={6}
+            isNumberInput={true}
+            disabled={true}
+            onChangeOTP={() => {}}
+            messages={{ neutral: "Input is currently disabled" }}
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            All fields locked — no interaction possible
+          </p>
         </div>
+      </div>
 
-        {/* Input Type Variants */}
-        <div className="space-y-4">
-          <h3 className="text-fm-primary text-xl font-semibold">
-            Input Type Variants
-          </h3>
-
-          <div className="space-y-3">
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Numeric Only (Default)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Numeric OTP:", otp)}
-              />
-              <p className="text-fm-tertiary mt-1 text-xs">
-                Accepts only numbers (0-9)
-              </p>
-            </div>
-
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Alphanumeric (Letters + Numbers)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={false}
-                onChangeOTP={setAlphanumericOtp}
-              />
-              <p className="text-fm-tertiary mt-1 text-xs">
-                Current: {alphanumericOtp || "Empty"} | Accepts letters and
-                numbers
-              </p>
-            </div>
-          </div>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Validation — Success
+        </h4>
+        <div className="space-y-2 text-center">
+          <OtpInputs
+            length={6}
+            isNumberInput={true}
+            onChangeOTP={() => {}}
+            isValid={true}
+            messages={{ success: "Verification successful" }}
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Code accepted
+          </p>
         </div>
+      </div>
 
-        {/* State Variants */}
-        <div className="space-y-4">
-          <h3 className="text-fm-primary text-xl font-semibold">
-            State Variants
-          </h3>
-
-          <div className="space-y-3">
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Enabled State (Default)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Enabled OTP:", otp)}
-              />
-            </div>
-
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Disabled State
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                disabled={true}
-                onChangeOTP={(otp) => console.log("Disabled OTP:", otp)}
-              />
-            </div>
-          </div>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Validation — Error
+        </h4>
+        <div className="space-y-2 text-center">
+          <OtpInputs
+            length={6}
+            isNumberInput={true}
+            onChangeOTP={() => {}}
+            isValid={false}
+            messages={{ error: "Invalid code. Please try again." }}
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            Code rejected — helper text turns negative
+          </p>
         </div>
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Four states: default (awaiting input), disabled (locked), validation success, and validation error. Each state drives distinct helper text and visual feedback.",
+      },
+    },
+  },
+}
 
-        {/* Validation States */}
-        <div className="space-y-4">
-          <h3 className="text-fm-primary text-xl font-semibold">
-            Validation States
-          </h3>
-
-          <div className="space-y-3">
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Neutral State (No validation)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Neutral OTP:", otp)}
-                isValid={null}
-                messages={{
-                  neutral: "Enter your 6-digit verification code",
-                }}
-              />
-            </div>
-
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Success State (Valid OTP)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Success OTP:", otp)}
-                isValid={true}
-                messages={{
-                  success: "✓ Verification successful!",
-                }}
-              />
-            </div>
-
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Error State (Invalid OTP)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Error OTP:", otp)}
-                isValid={false}
-                messages={{
-                  error: "✗ Invalid code. Please try again.",
-                }}
-              />
-            </div>
+// ─── 4. Interactive ───────────────────────────────────────────────────────────
 
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Interactive Validation (Try: 123456)
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={handleValidation}
-                isValid={isValid}
-                messages={{
-                  neutral: "Enter 6-digit code",
-                  success: "✓ Code verified successfully!",
-                  error: "✗ Invalid code. Try: 123456",
-                }}
-              />
-              <p className="text-fm-tertiary mt-1 text-xs">
-                Current: {validatedOtp || "Empty"} | Status:{" "}
-                {isValid === null
-                  ? "Neutral"
-                  : isValid === true
-                    ? "Valid"
-                    : "Invalid"}
-              </p>
-            </div>
-          </div>
-        </div>
+export const Interactive: Story = {
+  render: () => {
+    type Step = "idle" | "sent" | "verified" | "failed"
 
-        {/* Custom Styling Examples */}
-        <div className="space-y-4">
-          <h3 className="text-fm-primary text-xl font-semibold">
-            Custom Styling
-          </h3>
+    const VALID_CODE = "123456"
 
-          <div className="space-y-3">
-            <div>
-              <label className="text-fm-secondary mb-2 block text-sm font-medium">
-                Custom Input Styling
-              </label>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Custom styled OTP:", otp)}
-                inputStyle={{
-                  backgroundColor: "#1f2937",
-                  borderColor: "#374151",
-                  color: "#f9fafb",
-                }}
-                inputClassName="border-2 border-blue-500 focus:border-blue-400"
-              />
-            </div>
-          </div>
-        </div>
+    const InteractiveDemo = () => {
+      const [step, setStep] = useState<Step>("idle")
+      const [isValid, setIsValid] = useState<boolean | null>(null)
 
-        {/* Usage Examples */}
-        <div className="space-y-4">
-          <h3 className="text-fm-primary text-xl font-semibold">
-            Common Use Cases
-          </h3>
+      const handleSend = () => {
+        setStep("sent")
+        setIsValid(null)
+      }
 
-          <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
-            <div className="bg-fm-surface-secondary rounded-lg p-4">
-              <h4 className="text-fm-primary mb-2 font-medium">
-                SMS Verification
-              </h4>
-              <OtpInputs
-                length={4}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("SMS OTP:", otp)}
-                messages={{
-                  neutral: "Enter SMS code",
-                }}
-              />
-            </div>
+      const handleOtpChange = (value: string) => {
+        if (value.length === 6) {
+          const valid = value === VALID_CODE
+          setIsValid(valid)
+          setStep(valid ? "verified" : "failed")
+        } else {
+          setIsValid(null)
+          if (step === "verified" || step === "failed") {
+            setStep("sent")
+          }
+        }
+      }
 
-            <div className="bg-fm-surface-secondary rounded-lg p-4">
-              <h4 className="text-fm-primary mb-2 font-medium">
-                Email Verification
-              </h4>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("Email OTP:", otp)}
-                messages={{
-                  neutral: "Enter email code",
-                }}
-              />
-            </div>
+      const handleReset = () => {
+        setStep("idle")
+        setIsValid(null)
+      }
 
-            <div className="bg-fm-surface-secondary rounded-lg p-4">
-              <h4 className="text-fm-primary mb-2 font-medium">
-                2FA Authentication
-              </h4>
-              <OtpInputs
-                length={6}
-                isNumberInput={true}
-                onChangeOTP={(otp) => console.log("2FA OTP:", otp)}
-                messages={{
-                  neutral: "Enter authenticator code",
-                }}
-              />
-            </div>
+      const stepMessages = {
+        neutral: "Enter the 6-digit code (hint: 123456)",
+        success: "Identity verified — welcome back!",
+        error: "Incorrect code. Try again or resend.",
+      }
 
-            <div className="bg-fm-surface-secondary rounded-lg p-4">
-              <h4 className="text-fm-primary mb-2 font-medium">
-                Alphanumeric Code
-              </h4>
-              <OtpInputs
-                length={6}
-                isNumberInput={false}
-                onChangeOTP={(otp) => console.log("Alphanumeric OTP:", otp)}
-                messages={{
-                  neutral: "Enter alphanumeric code",
-                }}
-              />
+      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">
+                  Flow
+                </p>
+
+                <div className="space-y-2">
+                  <button
+                    onClick={handleSend}
+                    disabled={step === "sent" || step === "verified"}
+                    className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border px-4 py-2.5 font-medium transition-opacity disabled:opacity-40"
+                  >
+                    {step === "idle" ? "Send Code" : "Code Sent"}
+                  </button>
+                  <button
+                    onClick={handleReset}
+                    className="border-fm-divider-secondary text-fm-secondary font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border px-4 py-2.5 font-medium"
+                  >
+                    Reset
+                  </button>
+                </div>
+
+                <div className="border-fm-divider-secondary border-t pt-4" />
+
+                <div className="space-y-1">
+                  <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                    Status
+                  </p>
+                  <div className="space-y-1">
+                    {(
+                      [
+                        { key: "idle", label: "Waiting for send" },
+                        { key: "sent", label: "Code dispatched" },
+                        { key: "verified", label: "Verified" },
+                        { key: "failed", label: "Failed attempt" },
+                      ] as const
+                    ).map(({ key, label }) => (
+                      <div key={key} className="flex items-center gap-2">
+                        <span
+                          className={
+                            step === key
+                              ? key === "verified"
+                                ? "text-fm-positive"
+                                : key === "failed"
+                                  ? "text-fm-negative"
+                                  : "text-fm-primary"
+                              : "text-fm-tertiary"
+                          }
+                        >
+                          {step === key ? "●" : "○"}
+                        </span>
+                        <p
+                          className={`font-fm-text text-fm-sm leading-fm-sm ${step === key ? "text-fm-primary font-medium" : "text-fm-tertiary"}`}
+                        >
+                          {label}
+                        </p>
+                      </div>
+                    ))}
+                  </div>
+                </div>
+              </div>
+
+              {/* Preview stage */}
+              <div className="flex flex-col gap-3 lg:col-span-2">
+                <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-xl border p-6">
+                  <div className="space-y-4">
+                    <div className="space-y-1">
+                      <p className="text-fm-primary font-fm-text text-fm-md leading-fm-md font-semibold">
+                        Verify your identity
+                      </p>
+                      <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                        {step === "idle"
+                          ? 'Click "Send Code" to begin.'
+                          : "A 6-digit code has been sent. Enter it below."}
+                      </p>
+                    </div>
+
+                    {step !== "idle" && (
+                      <OtpInputs
+                        length={6}
+                        isNumberInput={true}
+                        disabled={step === "verified"}
+                        onChangeOTP={handleOtpChange}
+                        isValid={isValid}
+                        messages={stepMessages}
+                      />
+                    )}
+
+                    {step === "idle" && (
+                      <div className="border-fm-divider-secondary rounded-lg border px-4 py-3">
+                        <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+                          OTP input will appear after sending the code.
+                        </p>
+                      </div>
+                    )}
+                  </div>
+                </div>
+
+                <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)">
+                    {`<OtpInputs length={6} isNumberInput isValid={${isValid === null ? "null" : isValid}} />`}
+                  </code>
+                </div>
+              </div>
             </div>
           </div>
         </div>
-      </div>
-    )
+      )
+    }
+
+    return <InteractiveDemo />
   },
   parameters: {
+    layout: "fullscreen",
     docs: {
       description: {
-        story: `
-This comprehensive story demonstrates all available variants, states, and configurations of the OTP Input component:`,
+        story:
+          'A three-step verification flow: click "Send Code" to reveal the OTP input, type the 6-digit code (hint: 123456) to trigger live validation, and watch the helper text transition between neutral, success, and error states. Reset returns to step one.',
       },
     },
   },