aural-ui 4.0.1 → 4.1.0

package/dist/components/helper-text/HelperText.stories.tsx

@@ -1,6 +1,8 @@
 import React from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import HelperText from "."
 
 const meta: Meta<typeof HelperText> = {
@@ -8,12 +10,29 @@ const meta: Meta<typeof HelperText> = {
   component: HelperText,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A form helper text component that communicates field-level feedback in four semantic variants — default, error, warning, and success — plus a disabled state. It uses the Tag primitive internally and integrates with ARIA via the id prop.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Semantic Variants",
+              description: "Default to success",
+            },
+            {
+              title: "Disabled State",
+              description: "Muted disabled style",
+            },
+            {
+              title: "ARIA Integration",
+              description: "Links via aria-describedby",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -38,7 +57,7 @@ const meta: Meta<typeof HelperText> = {
     },
     id: {
       control: { type: "text" },
-      description: "HTML id attribute for accessibility",
+      description: "HTML id attribute for accessibility (aria-describedby)",
     },
   },
 }
@@ -46,216 +65,196 @@ const meta: Meta<typeof HelperText> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    variant: "default",
-    children: "This is helpful information about the field above.",
-    disabled: false,
-  },
-}
-
-export const Error: Story = {
-  args: {
-    variant: "error",
-    children: "This field contains an error that needs to be fixed.",
-    disabled: false,
-  },
-}
+// ─── 1. AllVariants ───────────────────────────────────────────────────────────
 
-export const Warning: Story = {
-  args: {
-    variant: "warning",
-    children: "Please review this field before continuing.",
-    disabled: false,
-  },
-}
-
-export const Success: Story = {
-  args: {
-    variant: "success",
-    children: "This field has been validated successfully.",
-    disabled: false,
-  },
-}
-
-export const Disabled: Story = {
-  args: {
-    variant: "default",
-    children: "This helper text is in a disabled state.",
-    disabled: true,
-  },
-}
-
-export const LongText: Story = {
-  args: {
-    variant: "default",
-    children:
-      "This is a longer helper text that demonstrates how the component handles more extensive content that might wrap to multiple lines in certain layouts.",
-    disabled: false,
-  },
-}
-
-export const WithCustomClassName: Story = {
-  args: {
-    variant: "default",
-    children: "Helper text with custom styling.",
-    className: "!text-blue-600 font-semibold",
-    disabled: false,
-  },
-}
-
-// Showcase all variants together
 export const AllVariants: Story = {
   render: () => (
-    <div className="w-96 space-y-4">
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Default</h3>
-        <HelperText variant="default">
-          This is helpful information about the field above.
-        </HelperText>
-      </div>
-
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Error</h3>
-        <HelperText variant="error">
-          This field contains an error that needs to be fixed.
-        </HelperText>
-      </div>
-
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Warning</h3>
-        <HelperText variant="warning">
-          Please review this field before continuing.
-        </HelperText>
-      </div>
-
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Success</h3>
-        <HelperText variant="success">
-          This field has been validated successfully.
-        </HelperText>
-      </div>
-
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Disabled</h3>
-        <HelperText variant="default" disabled>
-          This helper text is in a disabled state.
-        </HelperText>
+    <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">
+          Variants
+        </h4>
+        <div className="flex w-80 flex-col gap-4">
+          <div className="space-y-2 text-center">
+            <HelperText variant="default">
+              We will never share your email with anyone else.
+            </HelperText>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Default
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <HelperText variant="error">
+              This field is required and cannot be empty.
+            </HelperText>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Error
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <HelperText variant="warning">
+              This username may already be in use.
+            </HelperText>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Warning
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <HelperText variant="success">
+              Your password meets all requirements.
+            </HelperText>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Success
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <HelperText variant="default" disabled>
+              This field is not editable in read-only mode.
+            </HelperText>
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Disabled
+            </p>
+          </div>
+        </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "All four semantic variants (default, error, warning, success) plus the disabled state, shown as individual itemCards.",
+      },
+    },
+  },
 }
 
-// Interactive examples with form fields
-export const WithFormField: Story = {
-  render: () => (
-    <div className="w-96 space-y-6">
-      <div>
-        <label className="mb-2 block text-sm font-medium">Email Address</label>
-        <input
-          type="email"
-          className="border-fm-divider-secondary w-full rounded-md border px-3 py-2 focus:ring-2 focus:ring-blue-500 focus:outline-none"
-          placeholder="Enter your email"
-        />
-        <div className="mt-1">
-          <HelperText variant="default">
-            We'll never share your email with anyone else.
-          </HelperText>
-        </div>
-      </div>
+// ─── 2. UseCases ──────────────────────────────────────────────────────────────
 
-      <div>
-        <label className="mb-2 block text-sm font-medium">Password</label>
-        <input
-          type="password"
-          className="w-full rounded-md border border-red-300 px-3 py-2 focus:ring-2 focus:ring-red-500 focus:outline-none"
-          placeholder="Enter your password"
-        />
-        <div className="mt-1">
-          <HelperText variant="error">
-            Password must be at least 8 characters long.
-          </HelperText>
-        </div>
-      </div>
+export const UseCases: Story = {
+  render: () => (
+    <div className="mx-auto max-w-3xl space-y-8 p-8">
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Account Setup Form
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-5 rounded-xl border p-6">
+          {/* Default — neutral hint */}
+          <div className="space-y-1">
+            <label
+              htmlFor="uc-email"
+              className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-medium tracking-wider uppercase"
+            >
+              Email Address
+            </label>
+            <input
+              id="uc-email"
+              type="email"
+              className="border-fm-divider-secondary bg-fm-surface-primary text-fm-primary placeholder:text-fm-tertiary w-full rounded-md border px-3 py-2 text-sm focus:outline-none"
+              placeholder="jane@example.com"
+            />
+            <HelperText variant="default" id="uc-email-helper">
+              We will use this address for account-related notices only.
+            </HelperText>
+          </div>
 
-      <div>
-        <label className="mb-2 block text-sm font-medium">Username</label>
-        <input
-          type="text"
-          className="w-full rounded-md border border-yellow-300 px-3 py-2 focus:ring-2 focus:ring-yellow-500 focus:outline-none"
-          placeholder="Enter your username"
-          value="john123"
-        />
-        <div className="mt-1">
-          <HelperText variant="warning">
-            This username is already taken. Consider adding numbers.
-          </HelperText>
-        </div>
-      </div>
+          {/* Error */}
+          <div className="space-y-1">
+            <label
+              htmlFor="uc-password"
+              className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-medium tracking-wider uppercase"
+            >
+              Password
+            </label>
+            <input
+              id="uc-password"
+              type="password"
+              className="border-fm-divider-negative bg-fm-surface-primary text-fm-primary placeholder:text-fm-tertiary w-full rounded-md border px-3 py-2 text-sm focus:outline-none"
+              placeholder="Min. 8 characters"
+              aria-describedby="uc-password-error"
+              aria-invalid="true"
+            />
+            <HelperText variant="error" id="uc-password-error">
+              Password must be at least 8 characters long.
+            </HelperText>
+          </div>
 
-      <div>
-        <label className="mb-2 block text-sm font-medium">Display Name</label>
-        <input
-          type="text"
-          className="w-full rounded-md border border-green-300 px-3 py-2 focus:ring-2 focus:ring-green-500 focus:outline-none"
-          placeholder="Enter your display name"
-          value="John Doe"
-        />
-        <div className="mt-1">
-          <HelperText variant="success">
-            Perfect! This display name is available.
-          </HelperText>
-        </div>
-      </div>
-    </div>
-  ),
-}
+          {/* Warning */}
+          <div className="space-y-1">
+            <label
+              htmlFor="uc-username"
+              className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-medium tracking-wider uppercase"
+            >
+              Username
+            </label>
+            <input
+              id="uc-username"
+              type="text"
+              className="border-fm-divider-warning bg-fm-surface-primary text-fm-primary placeholder:text-fm-tertiary w-full rounded-md border px-3 py-2 text-sm focus:outline-none"
+              defaultValue="john123"
+              aria-describedby="uc-username-warning"
+            />
+            <HelperText variant="warning" id="uc-username-warning">
+              This username is already taken. Try adding numbers or symbols.
+            </HelperText>
+          </div>
 
-export const AccessibilityExample: Story = {
-  render: () => (
-    <div className="w-96 space-y-4">
-      <div>
-        <label
-          htmlFor="accessible-input"
-          className="mb-2 block text-sm font-medium"
-        >
-          Email Address *
-        </label>
-        <input
-          id="accessible-input"
-          type="email"
-          className="border-fm-divider-secondary w-full rounded-md border px-3 py-2 focus:ring-2 focus:ring-blue-500 focus:outline-none"
-          placeholder="Enter your email"
-          aria-describedby="email-helper"
-          required
-        />
-        <div className="mt-1">
-          <HelperText variant="default" id="email-helper">
-            We'll use this email to send you important account updates.
-          </HelperText>
+          {/* Success */}
+          <div className="space-y-1">
+            <label
+              htmlFor="uc-display-name"
+              className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-medium tracking-wider uppercase"
+            >
+              Display Name
+            </label>
+            <input
+              id="uc-display-name"
+              type="text"
+              className="border-fm-divider-positive bg-fm-surface-primary text-fm-primary placeholder:text-fm-tertiary w-full rounded-md border px-3 py-2 text-sm focus:outline-none"
+              defaultValue="Jane Doe"
+              aria-describedby="uc-display-name-success"
+            />
+            <HelperText variant="success" id="uc-display-name-success">
+              This display name is available.
+            </HelperText>
+          </div>
         </div>
       </div>
 
-      <div>
-        <label htmlFor="error-input" className="mb-2 block text-sm font-medium">
-          Password *
-        </label>
-        <input
-          id="error-input"
-          type="password"
-          className="w-full rounded-md border border-red-300 px-3 py-2 focus:ring-2 focus:ring-red-500 focus:outline-none"
-          placeholder="Enter your password"
-          aria-describedby="password-error"
-          aria-invalid="true"
-          required
-        />
-        <div className="mt-1">
-          <HelperText variant="error" id="password-error">
-            Password must contain at least one uppercase letter, one lowercase
-            letter, and one number.
-          </HelperText>
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Read-only Settings
+        </h4>
+        <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md space-y-5 rounded-xl border p-6">
+          <div className="space-y-1">
+            <label
+              htmlFor="uc-account-id"
+              className="text-fm-inactive font-fm-brand text-fm-sm leading-fm-sm font-medium tracking-wider uppercase"
+            >
+              Account ID
+            </label>
+            <input
+              id="uc-account-id"
+              type="text"
+              className="border-fm-divider-secondary bg-fm-surface-tertiary text-fm-tertiary w-full cursor-not-allowed rounded-md border px-3 py-2 text-sm"
+              value="ACC-0001-XYZ"
+              disabled
+              readOnly
+            />
+            <HelperText variant="default" disabled id="uc-account-id-hint">
+              This field is managed by the system and cannot be changed.
+            </HelperText>
+          </div>
         </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "HelperText paired with real form inputs in an account setup flow — all four variants and the disabled state shown in realistic product context with proper ARIA linkage.",
+      },
+    },
+  },
 }