aural-ui 4.0.1 → 4.1.0

package/dist/components/textarea/TextArea.stories.tsx

@@ -1,25 +1,40 @@
 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 TextArea from "."
 
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
 const meta: Meta<typeof TextArea> = {
   title: "Components/UI/TextArea",
   component: TextArea,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
-    },
     docs: {
       description: {
         component:
-          "A flexible textarea component built with atomic design principles. Supports multiple decoration styles (underline, outline, filled), auto-growing height, character counting, and comprehensive accessibility features. Can be used as a complete component or composed from individual atomic parts.",
+          "A flexible textarea built with atomic design principles. Supports three decoration styles (underline, outline, filled), four validation variants, auto-growing height, character counting, and full ARIA accessibility. Can be used as a single convenience component or composed from individual atomic parts.",
       },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Validation States",
+              description: "Default to success",
+            },
+            {
+              title: "Auto-growing Height",
+              description: "Expands with content",
+            },
+            {
+              title: "3 Decoration Styles",
+              description: "Underline, outline, filled",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -27,704 +42,748 @@ const meta: Meta<typeof TextArea> = {
     label: {
       control: { type: "text" },
       description: "Label text for the textarea",
-      table: {
-        type: { summary: "ReactNode" },
-        defaultValue: { summary: "undefined" },
-      },
     },
     placeholder: {
       control: { type: "text" },
-      description: "Placeholder text shown when textarea is empty",
-      table: {
-        type: { summary: "string" },
-        defaultValue: { summary: '""' },
-      },
+      description: "Placeholder shown when the textarea is empty",
     },
     helperText: {
       control: { type: "text" },
       description: "Helper text displayed below the textarea",
-      table: {
-        type: { summary: "ReactNode" },
-        defaultValue: { summary: "undefined" },
-      },
     },
     variant: {
       control: { type: "select" },
       options: ["default", "error", "warning", "success"],
-      description: "Visual variant affecting border and helper text colors",
-      table: {
-        type: { summary: '"default" | "error" | "warning" | "success"' },
-        defaultValue: { summary: '"default"' },
-      },
+      description: "Visual validation state",
     },
     decoration: {
       control: { type: "select" },
       options: ["underline", "outline", "filled"],
-      description: "Visual style of the textarea border and background",
-      table: {
-        type: { summary: '"underline" | "outline" | "filled"' },
-        defaultValue: { summary: '"filled"' },
-      },
+      description: "Border and background style",
     },
     disabled: {
       control: { type: "boolean" },
-      description: "Whether the textarea is disabled and non-interactive",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
+      description: "Disables the textarea",
     },
     required: {
       control: { type: "boolean" },
-      description: "Whether the textarea is required (adds asterisk to label)",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
+      description: "Adds asterisk to label and aria-required",
     },
     fullWidth: {
       control: { type: "boolean" },
-      description: "Whether the textarea takes full width of its container",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
+      description: "Expands the textarea to fill its container",
     },
     showCharCount: {
       control: { type: "boolean" },
-      description: "Whether to show character count (requires maxLength)",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
-    },
-    value: {
-      control: { type: "text" },
-      description: "Controlled value of the textarea",
-      table: {
-        type: { summary: "string" },
-        defaultValue: { summary: "undefined" },
-      },
+      description: "Shows remaining character count (requires maxLength)",
     },
     maxLength: {
       control: { type: "number" },
       description: "Maximum number of characters allowed",
-      table: {
-        type: { summary: "number" },
-        defaultValue: { summary: "undefined" },
-      },
     },
     rows: {
       control: { type: "number", min: 1, max: 10 },
-      description: "Number of visible rows when autoGrow is false",
-      table: {
-        type: { summary: "number" },
-        defaultValue: { summary: "3" },
-      },
+      description: "Visible rows when autoGrow is false",
     },
     autoGrow: {
       control: { type: "boolean" },
-      description:
-        "Whether the textarea should automatically grow/shrink based on content",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "true" },
-      },
+      description: "Textarea grows/shrinks automatically with content",
     },
     minHeight: {
       control: { type: "number" },
-      description: "Minimum height in pixels (only with autoGrow)",
-      table: {
-        type: { summary: "number" },
-        defaultValue: { summary: "undefined" },
-      },
+      description: "Minimum height in pixels (autoGrow only)",
     },
     maxHeight: {
       control: { type: "number" },
-      description: "Maximum height in pixels (only with autoGrow)",
-      table: {
-        type: { summary: "number" },
-        defaultValue: { summary: "undefined" },
-      },
-    },
-    onChange: {
-      action: "changed",
-      description: "Callback fired when the value changes",
-      table: {
-        type: {
-          summary: "(e: React.ChangeEvent<HTMLTextAreaElement>) => void",
-        },
-      },
-    },
-    onFocus: {
-      action: "focused",
-      description: "Callback fired when the textarea receives focus",
-      table: {
-        type: { summary: "(e: React.FocusEvent<HTMLTextAreaElement>) => void" },
-      },
-    },
-    onBlur: {
-      action: "blurred",
-      description: "Callback fired when the textarea loses focus",
-      table: {
-        type: { summary: "(e: React.FocusEvent<HTMLTextAreaElement>) => void" },
-      },
-    },
-    unstyled: {
-      control: { type: "boolean" },
-      description: "Whether to remove all default styling",
-      table: {
-        type: { summary: "boolean" },
-        defaultValue: { summary: "false" },
-      },
-    },
-    classes: {
-      control: { type: "object" },
-      description: "Override classes for different parts of the component",
-      table: {
-        type: {
-          summary:
-            "{ root?: string; label?: string; wrapper?: string; textarea?: string; helperText?: string; charCount?: string }",
-        },
-        defaultValue: { summary: "{}" },
-      },
+      description: "Maximum height in pixels (autoGrow only)",
     },
   },
-}
-
-export default meta
-type Story = StoryObj<typeof meta>
-
-// Default story
-export const Default: Story = {
   args: {
-    label: "Message",
-    placeholder: "Enter your message here...",
+    variant: "default",
     decoration: "filled",
-    fullWidth: true,
+    disabled: false,
+    required: false,
+    fullWidth: false,
+    showCharCount: false,
+    autoGrow: true,
+    label: "Label",
+    placeholder: "Enter text…",
   },
 }
 
-// Decoration variants
-export const DecorationVariants: Story = {
-  render: () => (
-    <div className="max-w-lg space-y-6">
-      <div>
-        <h3 className="text-fm-primary mb-2 text-sm font-medium">Underline</h3>
-        <TextArea
-          label="Underline Style"
-          placeholder="Minimalist underline style..."
-          decoration="underline"
-          fullWidth
-        />
-      </div>
+export default meta
+type Story = StoryObj<typeof meta>
 
-      <div>
-        <h3 className="text-fm-primary mb-2 text-sm font-medium">Outline</h3>
-        <TextArea
-          label="Outline Style"
-          placeholder="Traditional outlined style..."
-          decoration="outline"
-          fullWidth
-        />
-      </div>
+// ─── 1. Playground ───────────────────────────────────────────────────────────
 
-      <div>
-        <h3 className="text-fm-primary mb-2 text-sm font-medium">Filled</h3>
-        <TextArea
-          label="Filled Style"
-          placeholder="Modern filled style..."
-          decoration="filled"
-          fullWidth
-        />
+export const Playground: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Use the Storybook controls panel to configure every prop. The textarea below reflects your selections live.",
+      },
+    },
+  },
+  render: (args) => (
+    <div className="w-96 space-y-4">
+      <TextArea {...args} fullWidth />
+      <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)">
+          {`<TextArea variant="${args.variant}" decoration="${args.decoration}"${args.disabled ? " disabled" : ""}${args.required ? " required" : ""}${args.showCharCount ? " showCharCount" : ""} />`}
+        </code>
       </div>
     </div>
   ),
+}
+
+// ─── 2. AllVariants ──────────────────────────────────────────────────────────
+
+export const AllVariants: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Three decoration styles available: underline (minimalist), outline (traditional), and filled (modern with background).",
+          "Full matrix of all four validation variants (default, error, warning, success) across all three decoration styles (underline, outline, filled).",
       },
     },
   },
-}
+  render: () => {
+    const variants = [
+      {
+        variant: "default" as const,
+        label: "Default",
+        helperText: "Helper text",
+      },
+      {
+        variant: "error" as const,
+        label: "Error",
+        helperText: "Something went wrong",
+      },
+      {
+        variant: "warning" as const,
+        label: "Warning",
+        helperText: "Double-check this value",
+      },
+      {
+        variant: "success" as const,
+        label: "Success",
+        helperText: "Looks great!",
+      },
+    ]
+    const decorations = [
+      { decoration: "underline" as const, label: "Underline" },
+      { decoration: "outline" as const, label: "Outline" },
+      { decoration: "filled" as const, label: "Filled" },
+    ]
 
-// Controlled component story
-export const Controlled: Story = {
-  render: (args) => {
-    const [value, setValue] = useState("")
     return (
-      <TextArea
-        {...args}
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-      />
+      <div className="space-y-10">
+        {decorations.map(({ decoration, label: decLabel }) => (
+          <div key={decoration}>
+            <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+              {decLabel}
+            </h4>
+            <div className="flex flex-wrap gap-6">
+              {variants.map(({ variant, label, helperText }) => (
+                <div key={variant} className="w-52 space-y-2 text-center">
+                  <TextArea
+                    label={label}
+                    placeholder={`${label} state…`}
+                    variant={variant}
+                    decoration={decoration}
+                    helperText={helperText}
+                    fullWidth
+                  />
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    {label}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
     )
   },
-  args: {
-    label: "Controlled TextArea",
-    placeholder: "Type something...",
-    decoration: "filled",
-    fullWidth: true,
-  },
-}
-
-// With helper text
-export const WithHelperText: Story = {
-  args: {
-    label: "Description",
-    placeholder: "Enter a description...",
-    helperText: "Please provide a detailed description",
-    decoration: "outline",
-    fullWidth: true,
-  },
 }
 
-// With character count
-export const WithCharCount: Story = {
-  args: {
-    label: "Comment",
-    placeholder: "Share your thoughts...",
-    maxLength: 280,
-    showCharCount: true,
-    decoration: "filled",
-    fullWidth: true,
-  },
-}
+// ─── 3. Configurations ───────────────────────────────────────────────────────
 
-// Error state with different decorations
-export const ErrorStates: Story = {
-  render: () => (
-    <div className="max-w-lg space-y-4">
-      <TextArea
-        label="Underline Error"
-        placeholder="Error with underline..."
-        variant="error"
-        decoration="underline"
-        helperText="This field is required"
-        fullWidth
-      />
-      <TextArea
-        label="Outline Error"
-        placeholder="Error with outline..."
-        variant="error"
-        decoration="outline"
-        helperText="This field is required"
-        fullWidth
-      />
-      <TextArea
-        label="Filled Error"
-        placeholder="Error with filled..."
-        variant="error"
-        decoration="filled"
-        helperText="This field is required"
-        fullWidth
-      />
-    </div>
-  ),
+export const Configurations: Story = {
   parameters: {
     docs: {
       description: {
-        story: "Error state examples across all decoration variants.",
+        story:
+          "Non-variant configuration axes: character count with maxLength, fixed height with autoGrow disabled, height constraints (minHeight + maxHeight), and required field indicator.",
       },
     },
   },
-}
+  render: () => {
+    const [tweetValue, setTweetValue] = useState("")
+    const [bioValue, setBioValue] = useState("")
 
-// Warning state
-export const WarningState: Story = {
-  args: {
-    label: "Message",
-    placeholder: "Enter your message...",
-    variant: "warning",
-    decoration: "outline",
-    helperText: "Please double-check your input",
-    fullWidth: true,
-  },
-}
+    return (
+      <div className="w-full max-w-sm space-y-10">
+        {/* Character count */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Character Count
+          </h4>
+          <div className="space-y-2 text-center">
+            <TextArea
+              label="Tweet"
+              placeholder="What's happening?"
+              value={tweetValue}
+              onChange={(e) => setTweetValue(e.target.value)}
+              maxLength={280}
+              showCharCount
+              decoration="underline"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              showCharCount + maxLength={280}
+            </p>
+          </div>
+        </div>
 
-// Success state
-export const SuccessState: Story = {
-  args: {
-    label: "Message",
-    placeholder: "Enter your message...",
-    variant: "success",
-    decoration: "filled",
-    helperText: "Looks good!",
-    fullWidth: true,
-  },
-}
+        {/* Fixed height */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Fixed Height
+          </h4>
+          <div className="space-y-2 text-center">
+            <TextArea
+              label="Notes"
+              placeholder="Type your notes here…"
+              autoGrow={false}
+              rows={5}
+              decoration="outline"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              autoGrow=false + rows={5}
+            </p>
+          </div>
+        </div>
 
-// Disabled state
-export const Disabled: Story = {
-  args: {
-    label: "Message",
-    placeholder: "Enter your message...",
-    disabled: true,
-    value: "This textarea is disabled",
-    decoration: "filled",
-    fullWidth: true,
-  },
-}
+        {/* Height constraints */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Height Constraints
+          </h4>
+          <div className="space-y-2 text-center">
+            <TextArea
+              label="Bio"
+              placeholder="Tell us about yourself (grows up to 200 px)…"
+              value={bioValue}
+              onChange={(e) => setBioValue(e.target.value)}
+              autoGrow
+              minHeight={60}
+              maxHeight={200}
+              decoration="filled"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              autoGrow + minHeight=60 + maxHeight=200
+            </p>
+          </div>
+        </div>
 
-// Required field
-export const Required: Story = {
-  args: {
-    label: "Required Message",
-    placeholder: "This field is required...",
-    required: true,
-    helperText: "This field is required",
-    decoration: "outline",
-    fullWidth: true,
+        {/* Required */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Required
+          </h4>
+          <div className="space-y-2 text-center">
+            <TextArea
+              label="Feedback"
+              placeholder="Your feedback is required…"
+              required
+              helperText="This field is required"
+              decoration="outline"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              required — asterisk added to label
+            </p>
+          </div>
+        </div>
+      </div>
+    )
   },
 }
 
-// With auto-grow disabled
-export const FixedHeight: Story = {
-  args: {
-    label: "Fixed Height TextArea",
-    placeholder: "This textarea has a fixed height...",
-    autoGrow: false,
-    rows: 5,
-    decoration: "outline",
-    fullWidth: true,
-  },
-}
+// ─── 4. States ───────────────────────────────────────────────────────────────
 
-// With min and max height
-export const WithHeightLimits: Story = {
-  args: {
-    label: "Height Limited TextArea",
-    placeholder: "This textarea has height constraints...",
-    autoGrow: true,
-    minHeight: 80,
-    maxHeight: 200,
-    decoration: "filled",
-    fullWidth: true,
+export const States: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "All five textarea states side by side: default (idle), disabled (non-interactive with pre-filled content), error, warning, and success.",
+      },
+    },
   },
+  render: () => (
+    <div className="w-full max-w-sm space-y-8">
+      {[
+        {
+          label: "Default",
+          props: {
+            label: "Default",
+            placeholder: "Enter your message…",
+            variant: "default" as const,
+            helperText: "Helper text",
+          },
+        },
+        {
+          label: "Disabled",
+          props: {
+            label: "Disabled",
+            value: "This textarea cannot be edited",
+            variant: "default" as const,
+            disabled: true,
+            helperText: "Read-only content",
+          },
+        },
+        {
+          label: "Error",
+          props: {
+            label: "Error",
+            placeholder: "Enter your message…",
+            variant: "error" as const,
+            helperText: "This field is required",
+          },
+        },
+        {
+          label: "Warning",
+          props: {
+            label: "Warning",
+            value: "Short",
+            variant: "warning" as const,
+            helperText: "Please provide more detail",
+          },
+        },
+        {
+          label: "Success",
+          props: {
+            label: "Success",
+            value:
+              "This is a detailed and valid message that meets all requirements.",
+            variant: "success" as const,
+            helperText: "Looks great!",
+          },
+        },
+      ].map(({ label, props }) => (
+        <div key={label}>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+            {label}
+          </h4>
+          <TextArea decoration="outline" fullWidth {...props} />
+        </div>
+      ))}
+    </div>
+  ),
 }
 
-// With character limit and warning
-export const CharacterLimitWithWarning: Story = {
-  render: (args) => {
-    const [value, setValue] = useState("")
-    const isNearLimit = value.length > 250
-    const isOverHalfway = value.length > 140
+// ─── 5. Interactive ──────────────────────────────────────────────────────────
 
-    return (
-      <TextArea
-        {...args}
-        value={value}
-        onChange={(e) => setValue(e.target.value)}
-        variant={
-          isNearLimit ? "warning" : isOverHalfway ? "default" : "default"
-        }
-        helperText={
-          isNearLimit
-            ? "You're approaching the character limit"
-            : "Share what's on your mind"
-        }
-      />
-    )
-  },
-  args: {
-    label: "Tweet",
-    placeholder: "What's happening?",
-    maxLength: 280,
-    showCharCount: true,
-    decoration: "underline",
-    fullWidth: true,
+export const Interactive: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Live textarea demo with real-time character counting, dynamic variant changes based on content length, and preset buttons for quickly populating different content lengths. The variant and helper text update as you type.",
+      },
+    },
   },
-}
-
-// Atomic composition story - demonstrates how to use individual components
-export const AtomicComposition: Story = {
-  render: () => {
+  render: function InteractiveTextArea() {
     const [value, setValue] = useState("")
-    const maxLength = 100
+    const [decoration, setDecoration] = useState<
+      "underline" | "outline" | "filled"
+    >("outline")
+    const maxLength = 280
+
+    const variant =
+      value.length === 0
+        ? "default"
+        : value.length > 240
+          ? "warning"
+          : value.length > 10
+            ? "success"
+            : "default"
+
+    const helperText =
+      value.length === 0
+        ? "Start typing…"
+        : value.length > 240
+          ? "Approaching the character limit"
+          : "Looks good!"
+
+    const presets = [
+      { label: "Short", text: "Hello world." },
+      {
+        label: "Medium",
+        text: "This is a medium-length message that provides some context and detail about the topic at hand.",
+      },
+      {
+        label: "Long",
+        text: "This is a longer message that demonstrates what happens when content approaches the character limit. Keep writing to see the warning state activate as you get closer to 280 characters. Almost there now — just a few more words should do it to trigger the warning.",
+      },
+      { label: "Clear", text: "" },
+    ]
 
     return (
-      <TextArea.Root fullWidth className="max-w-md">
-        <TextArea.Label htmlFor="atomic-textarea" required>
-          Custom Composed TextArea
-        </TextArea.Label>
-
-        <TextArea.Wrapper>
-          <TextArea.Base
-            id="atomic-textarea"
-            placeholder="Built with atomic components..."
-            value={value}
-            onChange={(e) => setValue(e.target.value)}
-            maxLength={maxLength}
-            variant="default"
-            decoration="outline"
-          />
-        </TextArea.Wrapper>
-
-        <div className="flex items-center justify-between gap-2">
-          <TextArea.HelperText variant="default">
-            This is built using atomic components
-          </TextArea.HelperText>
-
-          <TextArea.CharCount
-            currentLength={value.length}
-            maxLength={maxLength}
-          />
+      <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">
+                Presets
+              </p>
+              <div className="space-y-2">
+                {presets.map(({ label, text }) => (
+                  <button
+                    key={label}
+                    onClick={() => setValue(text)}
+                    className="border-fm-divider-secondary text-fm-primary font-fm-text text-fm-sm leading-fm-sm hover:bg-fm-surface-primary w-full rounded-lg border px-3 py-2 text-left transition-colors"
+                  >
+                    {label}
+                  </button>
+                ))}
+              </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+              <p className="text-fm-primary font-fm-brand text-fm-sm leading-fm-sm font-semibold tracking-widest uppercase">
+                Decoration
+              </p>
+              <div className="space-y-2">
+                {(["underline", "outline", "filled"] as const).map((d) => (
+                  <button
+                    key={d}
+                    onClick={() => setDecoration(d)}
+                    className={`border-fm-divider-secondary text-fm-primary font-fm-text text-fm-sm leading-fm-sm w-full rounded-lg border px-3 py-2 text-left capitalize transition-colors ${decoration === d ? "bg-fm-surface-primary" : "hover:bg-fm-surface-primary"}`}
+                  >
+                    {d}
+                  </button>
+                ))}
+              </div>
+              <div className="border-fm-divider-secondary border-t pt-4" />
+              <div className="border-fm-divider-secondary bg-fm-surface-primary rounded-lg border p-3">
+                <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mb-1 font-medium">
+                  Characters
+                </p>
+                <p className="text-fm-primary text-fm-sm leading-fm-sm font-(--font-fm-mono)">
+                  {value.length} / {maxLength}
+                </p>
+              </div>
+            </div>
+
+            {/* Preview stage */}
+            <div className="flex flex-col gap-3 lg:col-span-2">
+              <TextArea
+                label="Message"
+                placeholder="Start typing to see real-time validation…"
+                value={value}
+                onChange={(e) => setValue(e.target.value)}
+                variant={variant as "default" | "warning" | "success"}
+                helperText={helperText}
+                decoration={decoration}
+                maxLength={maxLength}
+                showCharCount
+                autoGrow
+                minHeight={80}
+                fullWidth
+              />
+              <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)">
+                  {`variant="${variant}" | ${value.length}/${maxLength} chars`}
+                </code>
+              </div>
+            </div>
+          </div>
         </div>
-      </TextArea.Root>
+      </div>
     )
   },
+}
+
+// ─── 6. Parts ────────────────────────────────────────────────────────────────
+
+export const Parts: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "This example shows how to compose the TextArea using individual atomic components for maximum flexibility. This pattern allows for custom layouts and advanced use cases.",
+          "Each atomic sub-component shown individually: TextArea (convenience wrapper), and the atomic TextArea.Root + TextArea.Label + TextArea.Wrapper + TextArea.Base + TextArea.HelperText + TextArea.CharCount composition for full layout control.",
       },
     },
   },
-}
-
-// Complex form example
-export const ComplexFormExample: Story = {
   render: () => {
-    const [feedback, setFeedback] = useState("")
-    const [description, setDescription] = useState("")
+    const [atomicValue, setAtomicValue] = useState("")
+    const maxLength = 100
 
     return (
-      <div className="max-w-lg space-y-6">
-        <TextArea
-          label="Product Description"
-          placeholder="Describe your product..."
-          value={description}
-          onChange={(e) => setDescription(e.target.value)}
-          helperText="Provide a clear and concise description"
-          maxLength={500}
-          showCharCount
-          decoration="outline"
-          fullWidth
-        />
+      <div className="w-full max-w-lg space-y-10">
+        {/* Convenience component */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            TextArea — convenience wrapper
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mb-3">
+              The default export combines all atomic parts into a single
+              component with label, textarea, helper text, and optional
+              character count.
+            </p>
+            <TextArea
+              label="Description"
+              placeholder="Tell us more…"
+              helperText="Provide a clear description"
+              maxLength={200}
+              showCharCount
+              decoration="outline"
+              fullWidth
+            />
+          </div>
+        </div>
 
-        <TextArea
-          label="Customer Feedback"
-          placeholder="Share your experience..."
-          value={feedback}
-          onChange={(e) => setFeedback(e.target.value)}
-          variant={feedback.length > 10 ? "success" : "default"}
-          helperText={
-            feedback.length > 10
-              ? "Thank you for the detailed feedback!"
-              : "Please provide detailed feedback"
-          }
-          required
-          autoGrow
-          minHeight={60}
-          maxHeight={150}
-          decoration="filled"
-          fullWidth
-        />
+        {/* Atomic composition */}
+        <div>
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+            Atomic Composition
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mb-3">
+              Build the same result using individual primitives for full control
+              over layout and positioning.
+            </p>
+            <TextArea.Root fullWidth>
+              <TextArea.Label htmlFor="atomic-textarea" required>
+                Custom Composed TextArea
+              </TextArea.Label>
+              <TextArea.Wrapper>
+                <TextArea.Base
+                  id="atomic-textarea"
+                  placeholder="Built with atomic components…"
+                  value={atomicValue}
+                  onChange={(e) => setAtomicValue(e.target.value)}
+                  maxLength={maxLength}
+                  variant="default"
+                  decoration="outline"
+                />
+              </TextArea.Wrapper>
+              <div className="flex items-center justify-between gap-2">
+                <TextArea.HelperText variant="default">
+                  Full control via atomic parts
+                </TextArea.HelperText>
+                <TextArea.CharCount
+                  currentLength={atomicValue.length}
+                  maxLength={maxLength}
+                />
+              </div>
+            </TextArea.Root>
+          </div>
+        </div>
       </div>
     )
   },
+}
+
+// ─── 7. UseCases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "An example showing multiple TextArea components in a form with different configurations, decorations, and dynamic states based on user input.",
+          "Real product-shaped examples: a social post composer with character counter and dynamic warnings, a support ticket form with required feedback, and a profile bio editor with success validation.",
       },
     },
   },
-}
+  render: function UseCasesTextArea() {
+    const [post, setPost] = useState("")
+    const [ticket, setTicket] = useState("")
+    const [bio, setBio] = useState("")
+
+    const postVariant =
+      post.length === 0 ? "default" : post.length > 240 ? "warning" : "success"
+    const postHelper =
+      post.length > 240
+        ? "Approaching the 280-character limit"
+        : post.length > 0
+          ? "Ready to post"
+          : "What's on your mind?"
+
+    const bioVariant =
+      bio.length > 10 ? "success" : bio.length > 0 ? "default" : "default"
+    const bioHelper =
+      bio.length > 10 ? "Looking good!" : "Tell listeners a bit about yourself"
 
-// Sizing variations with different decorations
-export const SizingVariations: Story = {
-  render: () => (
-    <div className="text-fm-primary space-y-4">
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Small (3 rows) - Underline</h3>
-        <TextArea
-          placeholder="Small textarea..."
-          rows={3}
-          autoGrow={false}
-          decoration="underline"
-          className="max-w-sm"
-        />
-      </div>
+    return (
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* Social post composer */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Post Composer
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-md rounded-xl border p-5">
+            <TextArea
+              label="New Post"
+              placeholder="What's happening?"
+              value={post}
+              onChange={(e) => setPost(e.target.value)}
+              variant={postVariant}
+              helperText={postHelper}
+              maxLength={280}
+              showCharCount
+              decoration="underline"
+              fullWidth
+            />
+          </div>
+        </div>
 
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Medium (5 rows) - Outline</h3>
-        <TextArea
-          placeholder="Medium textarea..."
-          rows={5}
-          autoGrow={false}
-          decoration="outline"
-          className="max-w-md"
-        />
-      </div>
+        {/* Support ticket */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Support Ticket
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-md rounded-xl border p-5">
+            <TextArea
+              label="Describe your issue"
+              placeholder="Please describe what happened in as much detail as possible…"
+              value={ticket}
+              onChange={(e) => setTicket(e.target.value)}
+              variant={
+                ticket.length > 20
+                  ? "success"
+                  : ticket.length > 0
+                    ? "default"
+                    : "default"
+              }
+              helperText={
+                ticket.length > 20
+                  ? "Thank you — our team will review this"
+                  : "Required — minimum 20 characters for a useful report"
+              }
+              required
+              autoGrow
+              minHeight={80}
+              maxHeight={240}
+              decoration="outline"
+              fullWidth
+            />
+          </div>
+        </div>
 
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Large (8 rows) - Filled</h3>
-        <TextArea
-          placeholder="Large textarea..."
-          rows={8}
-          autoGrow={false}
-          decoration="filled"
-          className="max-w-lg"
-        />
+        {/* Profile bio */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Profile Bio Editor
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary max-w-md rounded-xl border p-5">
+            <TextArea
+              label="Bio"
+              placeholder="I'm a podcast creator who loves…"
+              value={bio}
+              onChange={(e) => setBio(e.target.value)}
+              variant={bioVariant}
+              helperText={bioHelper}
+              maxLength={160}
+              showCharCount
+              decoration="filled"
+              fullWidth
+            />
+          </div>
+        </div>
       </div>
-    </div>
-  ),
+    )
+  },
+}
+
+// ─── 8. Accessibility ────────────────────────────────────────────────────────
+
+export const Accessibility: Story = {
   parameters: {
     docs: {
       description: {
         story:
-          "Different sizing options for the TextArea component with fixed heights, showcasing different decoration styles.",
+          "Accessibility-focused examples covering ARIA attributes, required field announcements, error state with aria-invalid, and the character count linked via aria-describedby. All interactive elements are keyboard-reachable and screen-reader friendly.",
       },
     },
   },
-}
-
-// All variants with all decorations
-export const AllVariantsAllDecorations: Story = {
   render: () => (
-    <div className="grid max-w-6xl grid-cols-1 gap-6 lg:grid-cols-3">
-      {/* Underline decoration */}
-      <div className="space-y-4">
-        <h3 className="text-fm-primary text-lg font-semibold">Underline</h3>
-        <TextArea
-          label="Default"
-          placeholder="Default underline..."
-          variant="default"
-          decoration="underline"
-          helperText="Default variant"
-          fullWidth
-        />
-        <TextArea
-          label="Error"
-          placeholder="Error underline..."
-          variant="error"
-          decoration="underline"
-          helperText="Something went wrong"
-          fullWidth
-        />
-        <TextArea
-          label="Warning"
-          placeholder="Warning underline..."
-          variant="warning"
-          decoration="underline"
-          helperText="Please check input"
-          fullWidth
-        />
+    <div className="w-full max-w-lg space-y-8">
+      {/* Required */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+          Required Field
+        </h4>
         <TextArea
-          label="Success"
-          placeholder="Success underline..."
-          variant="success"
-          decoration="underline"
-          helperText="Looks good!"
+          label="Feedback"
+          placeholder="Your feedback is required…"
+          required
+          helperText="Required — helps us improve the product"
+          decoration="outline"
           fullWidth
         />
       </div>
 
-      {/* Outline decoration */}
-      <div className="space-y-4">
-        <h3 className="text-fm-primary text-lg font-semibold">Outline</h3>
-        <TextArea
-          label="Default"
-          placeholder="Default outline..."
-          variant="default"
-          decoration="outline"
-          helperText="Default variant"
-          fullWidth
-        />
+      {/* Error + aria-invalid */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+          Error State (aria-invalid)
+        </h4>
         <TextArea
-          label="Error"
-          placeholder="Error outline..."
+          label="Description"
+          placeholder="Enter a description…"
           variant="error"
+          helperText="This field cannot be empty"
           decoration="outline"
-          helperText="Something went wrong"
-          fullWidth
-        />
-        <TextArea
-          label="Warning"
-          placeholder="Warning outline..."
-          variant="warning"
-          decoration="outline"
-          helperText="Please check input"
           fullWidth
         />
+      </div>
+
+      {/* Character count + aria-describedby */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-3 font-medium">
+          Character Count (aria-describedby)
+        </h4>
         <TextArea
-          label="Success"
-          placeholder="Success outline..."
-          variant="success"
+          label="Short Bio"
+          placeholder="A brief introduction…"
+          maxLength={160}
+          showCharCount
+          helperText="The character count is announced to screen readers via aria-describedby"
           decoration="outline"
-          helperText="Looks good!"
           fullWidth
         />
       </div>
 
-      {/* Filled decoration */}
-      <div className="space-y-4">
-        <h3 className="text-fm-primary text-lg font-semibold">Filled</h3>
-        <TextArea
-          label="Default"
-          placeholder="Default filled..."
-          variant="default"
-          decoration="filled"
-          helperText="Default variant"
-          fullWidth
-        />
-        <TextArea
-          label="Error"
-          placeholder="Error filled..."
-          variant="error"
-          decoration="filled"
-          helperText="Something went wrong"
-          fullWidth
-        />
-        <TextArea
-          label="Warning"
-          placeholder="Warning filled..."
-          variant="warning"
-          decoration="filled"
-          helperText="Please check input"
-          fullWidth
-        />
-        <TextArea
-          label="Success"
-          placeholder="Success filled..."
-          variant="success"
-          decoration="filled"
-          helperText="Looks good!"
-          fullWidth
-        />
+      {/* Accessibility best practices */}
+      <div className="border-fm-divider-secondary bg-fm-surface-secondary rounded-lg border p-4">
+        <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm mb-2 font-medium">
+          Accessibility Best Practices
+        </p>
+        <ul className="space-y-1">
+          {[
+            "Always provide a label — the Label is linked via htmlFor/id",
+            "Use helperText to add context; it is linked via aria-describedby",
+            "The error variant sets aria-invalid automatically",
+            "required adds aria-required and an asterisk to the label",
+            "The character count element is also linked via aria-describedby",
+            "Tab moves focus into the textarea; Shift+Tab moves out",
+          ].map((item) => (
+            <li
+              key={item}
+              className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm"
+            >
+              {item}
+            </li>
+          ))}
+        </ul>
       </div>
     </div>
   ),
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Complete showcase of all visual variants across all decoration styles.",
-      },
-    },
-  },
-}
-
-// Unstyled example
-export const Unstyled: Story = {
-  args: {
-    placeholder: "Completely unstyled textarea...",
-    unstyled: true,
-    className:
-      "border-2 border-dashed border-fm-divider-secondary p-4 rounded-lg bg-fm-surface-secondary",
-    fullWidth: true,
-  },
-  parameters: {
-    docs: {
-      description: {
-        story:
-          "Example of using the unstyled prop to create completely custom styling.",
-      },
-    },
-  },
 }