aural-ui 4.0.1 → 4.1.0

package/dist/components/char-count/CharCount.stories.tsx

@@ -1,19 +1,38 @@
 import React, { useState } from "react"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
-import CharCount from "."
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
+import CharCount, { type CharCountProps } from "."
 
 const meta: Meta<typeof CharCount> = {
   title: "Components/UI/CharCount",
   component: CharCount,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A compact character counter that displays current length against an optional maximum, transitioning through neutral, warning, and error states as the user types. Use it alongside any text input or textarea to give users at-a-glance feedback on their remaining characters.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "3 Color States",
+              description: "Neutral, warning, error",
+            },
+            {
+              title: "Live ARIA",
+              description: "Announces state changes",
+            },
+            {
+              title: "maxLength Optional",
+              description: "Works without a cap",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -26,10 +45,6 @@ const meta: Meta<typeof CharCount> = {
       control: { type: "number", min: 0 },
       description: "Maximum allowed characters (optional)",
     },
-    className: {
-      control: { type: "text" },
-      description: "Additional CSS classes to apply",
-    },
     "aria-live": {
       control: { type: "select" },
       options: ["polite", "assertive", "off"],
@@ -37,7 +52,7 @@ const meta: Meta<typeof CharCount> = {
     },
     id: {
       control: { type: "text" },
-      description: "HTML id attribute for accessibility",
+      description: "HTML id attribute for accessibility linkage",
     },
   },
 }
@@ -45,297 +60,384 @@ const meta: Meta<typeof CharCount> = {
 export default meta
 type Story = StoryObj<typeof meta>
 
-export const Default: Story = {
-  args: {
-    currentLength: 25,
-    maxLength: 100,
-    "aria-live": "polite",
-  },
-}
+function getCharCountColorClassName(
+  currentLength: number,
+  maxLength?: number
+): string {
+  if (typeof maxLength !== "number") {
+    return "!text-fm-tertiary"
+  }
 
-export const WithoutMaxLength: Story = {
-  args: {
-    currentLength: 42,
-    "aria-live": "polite",
-  },
-}
+  if (currentLength > maxLength) {
+    return "!text-fm-negative"
+  }
 
-export const NearLimit: Story = {
-  args: {
-    currentLength: 92,
-    maxLength: 100,
-    "aria-live": "polite",
-  },
-}
-
-export const OverLimit: Story = {
-  args: {
-    currentLength: 105,
-    maxLength: 100,
-    "aria-live": "assertive",
-  },
-}
+  if (currentLength > maxLength * 0.9) {
+    return "!text-fm-warning"
+  }
 
-export const Zero: Story = {
-  args: {
-    currentLength: 0,
-    maxLength: 50,
-    "aria-live": "polite",
-  },
+  return "!text-fm-tertiary"
 }
 
-export const ExactLimit: Story = {
-  args: {
-    currentLength: 100,
-    maxLength: 100,
-    "aria-live": "polite",
-  },
+function StoryCharCount({
+  className,
+  currentLength,
+  maxLength,
+  ...props
+}: CharCountProps) {
+  return (
+    <CharCount
+      currentLength={currentLength}
+      maxLength={maxLength}
+      className={[
+        getCharCountColorClassName(currentLength, maxLength),
+        className,
+      ]
+        .filter(Boolean)
+        .join(" ")}
+      {...props}
+    />
+  )
 }
 
-export const LargeNumbers: Story = {
-  args: {
-    currentLength: 2847,
-    maxLength: 5000,
-    "aria-live": "polite",
-  },
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-export const WithCustomClassName: Story = {
+export const Playground: Story = {
   args: {
-    currentLength: 30,
+    currentLength: 25,
     maxLength: 100,
-    className: "!text-blue-600 !text-lg",
     "aria-live": "polite",
   },
-}
-
-// Showcase all states together
-export const AllStates: Story = {
-  render: () => (
-    <div className="w-96 space-y-6">
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Normal State (25/100)</h3>
-        <CharCount currentLength={25} maxLength={100} />
+  render: (args) => (
+    <div className="w-full max-w-sm space-y-4">
+      <div className="flex justify-center">
+        <StoryCharCount {...args} />
       </div>
-
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Warning State (92/100)</h3>
-        <CharCount currentLength={92} maxLength={100} />
-      </div>
-
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Error State (105/100)</h3>
-        <CharCount currentLength={105} maxLength={100} />
+      <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)">
+          {`<CharCount currentLength={${args.currentLength}}${args.maxLength !== undefined ? ` maxLength={${args.maxLength}}` : ""} />`}
+        </code>
       </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Adjust currentLength and maxLength in the sidebar controls to watch the counter change state in real time.",
+      },
+    },
+  },
+}
 
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Without Max Length (42)</h3>
-        <CharCount currentLength={42} />
-      </div>
+// ─── 2. States ────────────────────────────────────────────────────────────────
 
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Zero Characters (0/50)</h3>
-        <CharCount currentLength={0} maxLength={50} />
+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">
+          Count States
+        </h4>
+        <div className="flex flex-wrap items-center gap-8">
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={0} maxLength={100} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Zero (0/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={35} maxLength={100} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Low (35/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={92} maxLength={100} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Near limit (92/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount
+              currentLength={105}
+              maxLength={100}
+              aria-live="assertive"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Over limit (105/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={42} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              No maxLength (42)
+            </p>
+          </div>
+        </div>
       </div>
 
-      <div>
-        <h3 className="mb-2 text-sm font-medium">Exact Limit (100/100)</h3>
-        <CharCount currentLength={100} maxLength={100} />
+      <div className="space-y-4">
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+          Boundary Values
+        </h4>
+        <div className="flex flex-wrap items-center gap-8">
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={89} maxLength={100} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Just below warning (89/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={91} maxLength={100} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Warning state (91/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount currentLength={100} maxLength={100} />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              Exact limit (100/100)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <StoryCharCount
+              currentLength={101}
+              maxLength={100}
+              aria-live="assertive"
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              One over (101/100)
+            </p>
+          </div>
+        </div>
       </div>
     </div>
   ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "All five states from left to right: zero, low, near-limit (≥90%), over-limit, and no-maxLength. Boundary values below show the exact thresholds where color transitions occur.",
+      },
+    },
+  },
 }
 
-// Interactive example with textarea
-export const WithTextarea: Story = {
+// ─── 3. Use Cases ─────────────────────────────────────────────────────────────
+
+export const UseCases: Story = {
   render: () => {
-    const [text, setText] = useState("")
-    const maxLength = 140
+    const BioField = () => {
+      const [bio, setBio] = useState("")
+      const maxLength = 160
+      const isOver = bio.length > maxLength
 
-    return (
-      <div className="w-96 space-y-4">
-        <div>
-          <label className="mb-2 block text-sm font-medium">
-            Tweet Message
-          </label>
+      return (
+        <div className="space-y-2">
+          <div className="flex items-baseline justify-between">
+            <label
+              htmlFor="bio-field"
+              className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium"
+            >
+              Bio
+            </label>
+            <StoryCharCount
+              currentLength={bio.length}
+              maxLength={maxLength}
+              id="bio-count"
+              aria-live={isOver ? "assertive" : "polite"}
+            />
+          </div>
           <textarea
-            value={text}
-            onChange={(e) => setText(e.target.value)}
-            className="border-fm-divider-secondary w-full resize-none rounded-md border px-3 py-2 focus:ring-2 focus:ring-blue-500 focus:outline-none"
-            placeholder="What's happening?"
+            id="bio-field"
+            value={bio}
+            onChange={(e) => setBio(e.target.value)}
+            aria-describedby="bio-count"
+            className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-placeholder font-fm-text text-fm-md leading-fm-xl w-full resize-none rounded-lg border px-3 py-2 focus:outline-none"
+            placeholder="Tell people about yourself…"
             rows={4}
-            aria-describedby="tweet-count"
           />
-          <div className="mt-2 flex justify-end">
-            <CharCount
-              currentLength={text.length}
+          {isOver && (
+            <p className="text-fm-negative font-fm-text text-fm-sm leading-fm-sm">
+              Bio is too long. Please shorten it.
+            </p>
+          )}
+        </div>
+      )
+    }
+
+    const UsernameField = () => {
+      const [username, setUsername] = useState("")
+      const maxLength = 20
+
+      return (
+        <div className="space-y-2">
+          <div className="flex items-baseline justify-between">
+            <label
+              htmlFor="username-field"
+              className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium"
+            >
+              Username
+            </label>
+            <StoryCharCount
+              currentLength={username.length}
               maxLength={maxLength}
-              id="tweet-count"
+              id="username-count"
               aria-live="polite"
             />
           </div>
-        </div>
-      </div>
-    )
-  },
-}
-
-// Interactive example with input
-export const WithInput: Story = {
-  render: () => {
-    const [username, setUsername] = useState("")
-    const maxLength = 20
-
-    return (
-      <div className="w-96 space-y-4">
-        <div>
-          <label className="mb-2 block text-sm font-medium">Username</label>
           <input
+            id="username-field"
             type="text"
             value={username}
             onChange={(e) => setUsername(e.target.value)}
-            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 username"
             aria-describedby="username-count"
+            className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-placeholder font-fm-text text-fm-md leading-fm-md w-full rounded-lg border px-3 py-2 focus:outline-none"
+            placeholder="Choose a unique handle"
           />
-          <div className="mt-2 flex items-center justify-between">
-            <span className="text-fm-secondary text-sm">
-              Must be unique and memorable
-            </span>
-            <CharCount
-              currentLength={username.length}
-              maxLength={maxLength}
-              id="username-count"
-              aria-live="polite"
-            />
-          </div>
+          <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+            Must be unique and memorable
+          </p>
         </div>
-      </div>
-    )
-  },
-}
+      )
+    }
 
-// Multiple inputs with different limits
-export const MultipleInputs: Story = {
-  render: () => {
-    const [title, setTitle] = useState("")
-    const [description, setDescription] = useState("")
-    const [tags, setTags] = useState("")
+    const MultipleFields = () => {
+      const [title, setTitle] = useState("")
+      const [description, setDescription] = useState("")
+      const [tags, setTags] = useState("")
 
-    return (
-      <div className="w-96 space-y-6">
-        <div>
-          <label className="mb-2 block text-sm font-medium">Post Title</label>
-          <input
-            type="text"
-            value={title}
-            onChange={(e) => setTitle(e.target.value)}
-            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 post title"
-            aria-describedby="title-count"
-          />
-          <div className="mt-1 flex justify-end">
-            <CharCount
-              currentLength={title.length}
-              maxLength={60}
-              id="title-count"
+      return (
+        <div className="space-y-5">
+          {/* Title */}
+          <div className="space-y-2">
+            <div className="flex items-baseline justify-between">
+              <label
+                htmlFor="title-field"
+                className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium"
+              >
+                Post Title
+              </label>
+              <StoryCharCount
+                currentLength={title.length}
+                maxLength={60}
+                id="title-count"
+                aria-live="polite"
+              />
+            </div>
+            <input
+              id="title-field"
+              type="text"
+              value={title}
+              onChange={(e) => setTitle(e.target.value)}
+              aria-describedby="title-count"
+              className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-placeholder font-fm-text text-fm-md leading-fm-md w-full rounded-lg border px-3 py-2 focus:outline-none"
+              placeholder="Enter post title"
             />
           </div>
-        </div>
 
-        <div>
-          <label className="mb-2 block text-sm font-medium">Description</label>
-          <textarea
-            value={description}
-            onChange={(e) => setDescription(e.target.value)}
-            className="border-fm-divider-secondary w-full resize-none rounded-md border px-3 py-2 focus:ring-2 focus:ring-blue-500 focus:outline-none"
-            placeholder="Describe your post"
-            rows={3}
-            aria-describedby="description-count"
-          />
-          <div className="mt-1 flex justify-end">
-            <CharCount
-              currentLength={description.length}
-              maxLength={200}
-              id="description-count"
+          {/* Description */}
+          <div className="space-y-2">
+            <div className="flex items-baseline justify-between">
+              <label
+                htmlFor="description-field"
+                className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium"
+              >
+                Description
+              </label>
+              <StoryCharCount
+                currentLength={description.length}
+                maxLength={200}
+                id="description-count"
+                aria-live="polite"
+              />
+            </div>
+            <textarea
+              id="description-field"
+              value={description}
+              onChange={(e) => setDescription(e.target.value)}
+              aria-describedby="description-count"
+              className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-placeholder font-fm-text text-fm-md leading-fm-xl w-full resize-none rounded-lg border px-3 py-2 focus:outline-none"
+              placeholder="Describe your post"
+              rows={3}
             />
           </div>
-        </div>
 
-        <div>
-          <label className="mb-2 block text-sm font-medium">
-            Tags (comma separated)
-          </label>
-          <input
-            type="text"
-            value={tags}
-            onChange={(e) => setTags(e.target.value)}
-            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="react, typescript, ui"
-            aria-describedby="tags-count"
-          />
-          <div className="mt-1 flex items-center justify-between">
-            <span className="text-fm-secondary text-xs">
-              Separate tags with commas
-            </span>
-            <CharCount
-              currentLength={tags.length}
-              maxLength={50}
-              id="tags-count"
+          {/* Tags */}
+          <div className="space-y-2">
+            <div className="flex items-baseline justify-between">
+              <label
+                htmlFor="tags-field"
+                className="text-fm-primary font-fm-text text-fm-sm leading-fm-sm font-medium"
+              >
+                Tags
+              </label>
+              <StoryCharCount
+                currentLength={tags.length}
+                maxLength={50}
+                id="tags-count"
+                aria-live="polite"
+              />
+            </div>
+            <input
+              id="tags-field"
+              type="text"
+              value={tags}
+              onChange={(e) => setTags(e.target.value)}
+              aria-describedby="tags-count"
+              className="border-fm-divider-secondary bg-fm-surface-secondary text-fm-primary placeholder:text-fm-placeholder font-fm-text text-fm-md leading-fm-md w-full rounded-lg border px-3 py-2 focus:outline-none"
+              placeholder="react, typescript, ui"
             />
+            <p className="text-fm-tertiary font-fm-text text-fm-sm leading-fm-sm">
+              Separate tags with commas
+            </p>
           </div>
         </div>
-      </div>
-    )
-  },
-}
-
-// Accessibility demonstration
-export const AccessibilityExample: Story = {
-  render: () => {
-    const [message, setMessage] = useState("")
-    const maxLength = 100
-    const isOverLimit = message.length > maxLength
+      )
+    }
 
     return (
-      <div className="w-96 space-y-4">
-        <div>
-          <label
-            htmlFor="accessible-message"
-            className="mb-2 block text-sm font-medium"
-          >
-            Message *
-          </label>
-          <textarea
-            id="accessible-message"
-            value={message}
-            onChange={(e) => setMessage(e.target.value)}
-            className={`w-full resize-none rounded-md border px-3 py-2 focus:ring-2 focus:outline-none ${
-              isOverLimit
-                ? "border-red-300 focus:ring-red-500"
-                : "border-fm-divider-secondary focus:ring-blue-500"
-            }`}
-            placeholder="Enter your message"
-            rows={4}
-            aria-describedby="message-count message-help"
-            aria-invalid={isOverLimit}
-            required
-          />
-          <div className="mt-2 flex items-start justify-between">
-            <div id="message-help" className="text-fm-secondary text-sm">
-              {isOverLimit
-                ? "Message is too long. Please shorten it."
-                : "Share your thoughts with the community."}
-            </div>
-            <CharCount
-              currentLength={message.length}
-              maxLength={maxLength}
-              id="message-count"
-              aria-live={isOverLimit ? "assertive" : "polite"}
-            />
+      <div className="mx-auto max-w-3xl space-y-8 p-8">
+        {/* Bio + Textarea */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Paired with Textarea — Bio Field
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+            <BioField />
+          </div>
+        </div>
+
+        {/* Username + Input */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Paired with Input — Username Field
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+            <UsernameField />
+          </div>
+        </div>
+
+        {/* Multiple fields */}
+        <div className="space-y-4">
+          <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md font-medium">
+            Multiple Fields with Independent Counts
+          </h4>
+          <div className="border-fm-divider-secondary bg-fm-surface-secondary mx-auto max-w-md rounded-xl border p-5">
+            <MultipleFields />
           </div>
         </div>
       </div>
     )
   },
+  parameters: {
+    layout: "fullscreen",
+    docs: {
+      description: {
+        story:
+          "Real-world usage scenarios: CharCount paired with a textarea bio field (with overflow error message), an input username field, and a multi-field form where each counter tracks its own input independently.",
+      },
+    },
+  },
 }