aural-ui 4.0.1 → 4.1.0

package/dist/components/input/Input.stories.tsx

@@ -1,21 +1,42 @@
 import React from "react"
-import HelperText from "@components/helper-text"
+import { EmailIcon } from "@icons/email-icon"
 import { AlertIcon, CrossIcon, TickIcon } from "@icons/index"
 import type { Meta, StoryObj } from "@storybook/react-vite"
 
+import { AuralComponentDocsPage } from "src/ui/story-spec/components/component-story-docs-page"
+
 import Input from "."
 
+// ─── Meta ─────────────────────────────────────────────────────────────────────
+
 const meta: Meta<typeof Input> = {
   title: "Components/UI/Input",
   component: Input,
   parameters: {
     layout: "centered",
-    backgrounds: {
-      default: "dark",
-      values: [
-        { name: "dark", value: "#0a0a0a" },
-        { name: "light", value: "#ffffff" },
-      ],
+    docs: {
+      description: {
+        component:
+          "A flexible text input built with atomic design principles. Supports four validation variants (default, error, warning, success), three decoration styles (underline, outline, filled), start/end icon slots, password toggle, character counting, and full accessibility via ARIA attributes.",
+      },
+      page: () => (
+        <AuralComponentDocsPage
+          features={[
+            {
+              title: "4 Validation States",
+              description: "Default to success",
+            },
+            {
+              title: "3 Decoration Styles",
+              description: "Underline, outline, filled",
+            },
+            {
+              title: "Icon Slots",
+              description: "Start and end icons",
+            },
+          ]}
+        />
+      ),
     },
   },
   tags: ["autodocs"],
@@ -23,419 +44,466 @@ const meta: Meta<typeof Input> = {
     variant: {
       control: { type: "select" },
       options: ["default", "error", "warning", "success"],
+      description: "Visual validation state",
+    },
+    decoration: {
+      control: { type: "select" },
+      options: ["underline", "outline", "filled"],
+      description: "Border and background style",
     },
     type: {
       control: { type: "select" },
       options: ["text", "email", "password", "number", "tel", "url"],
+      description: "HTML input type",
     },
-    disabled: {
-      control: { type: "boolean" },
-    },
-    required: {
-      control: { type: "boolean" },
-    },
-    fullWidth: {
-      control: { type: "boolean" },
-    },
-    transparentOnAutofill: {
-      control: { type: "boolean" },
-    },
+    disabled: { control: { type: "boolean" } },
+    required: { control: { type: "boolean" } },
+    fullWidth: { control: { type: "boolean" } },
+    label: { control: { type: "text" } },
+    placeholder: { control: { type: "text" } },
+    helperText: { control: { type: "text" } },
   },
-}
-
-export default meta
-type Story = StoryObj<typeof Input>
-
-// Basic variants
-export const Default: Story = {
-  args: {
-    label: "Default Input",
-    placeholder: "Enter text here...",
-    variant: "default",
-  },
-}
-
-export const WithValue: Story = {
   args: {
-    label: "Input with Value",
-    value: "Pre-filled value",
     variant: "default",
+    decoration: "underline",
+    type: "text",
+    disabled: false,
+    required: false,
+    fullWidth: false,
+    label: "Label",
+    placeholder: "Placeholder…",
   },
 }
 
-export const Required: Story = {
-  args: {
-    label: "Required Field",
-    placeholder: "This field is required",
-    required: true,
-    variant: "default",
-  },
-}
-
-// Variants
-export const Error: Story = {
-  args: {
-    label: "Error Input",
-    placeholder: "Enter valid email",
-    variant: "error",
-    helperText: "This field contains an error",
-    value: "invalid-email",
-  },
-}
-
-export const Warning: Story = {
-  args: {
-    label: "Warning Input",
-    placeholder: "Enter password",
-    variant: "warning",
-    helperText: "Password strength is weak",
-    value: "123",
-  },
-}
+export default meta
+type Story = StoryObj<typeof Input>
 
-export const Success: Story = {
-  args: {
-    label: "Success Input",
-    placeholder: "Enter email",
-    variant: "success",
-    helperText: "Email is valid",
-    value: "user@example.com",
-  },
-}
+// ─── 1. Playground ────────────────────────────────────────────────────────────
 
-// States
-export const Disabled: Story = {
-  args: {
-    label: "Disabled Input",
-    placeholder: "Cannot type here",
-    disabled: true,
-    value: "Disabled value",
-  },
-}
-
-export const FullWidth: Story = {
-  args: {
-    label: "Full Width Input",
-    placeholder: "This input takes full width",
-    fullWidth: true,
-  },
+export const Playground: Story = {
   parameters: {
-    layout: "padded",
-  },
-}
-
-// Input types
-export const EmailInput: Story = {
-  args: {
-    label: "Email",
-    type: "email",
-    placeholder: "Enter your email",
-    helperText: "We'll never share your email",
+    docs: {
+      description: {
+        story:
+          "Use the Storybook controls panel to configure every prop. The input below reflects your selections live.",
+      },
+    },
   },
+  render: (args) => (
+    <div className="w-full max-w-sm space-y-4">
+      <Input {...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)">
+          {`<Input variant="${args.variant}" decoration="${args.decoration}" type="${args.type}"${args.disabled ? " disabled" : ""}${args.required ? " required" : ""} />`}
+        </code>
+      </div>
+    </div>
+  ),
 }
 
-export const PasswordInput: Story = {
-  args: {
-    label: "Password",
-    type: "password",
-    placeholder: "Enter your password",
-    helperText: "Password must be at least 8 characters",
-  },
-}
+// ─── 2. AllVariants ───────────────────────────────────────────────────────────
 
-export const NumberInput: Story = {
-  args: {
-    label: "Age",
-    type: "number",
-    placeholder: "Enter your age",
+export const AllVariants: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "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" },
+      { variant: "error" as const, label: "Error" },
+      { variant: "warning" as const, label: "Warning" },
+      { variant: "success" as const, label: "Success" },
+    ]
+    const decorations = [
+      { decoration: "underline" as const, label: "Underline" },
+      { decoration: "outline" as const, label: "Outline" },
+      { decoration: "filled" as const, label: "Filled" },
+    ]
 
-export const TelInput: Story = {
-  args: {
-    label: "Phone Number",
-    type: "tel",
-    placeholder: "Enter your phone number",
+    return (
+      <div className="space-y-8">
+        {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 }) => (
+                <div key={variant} className="w-48 space-y-2 text-center">
+                  <Input
+                    label={label}
+                    placeholder={`${label}…`}
+                    variant={variant}
+                    decoration={decoration}
+                    helperText={
+                      variant === "error"
+                        ? "Something went wrong"
+                        : variant === "warning"
+                          ? "Double-check this value"
+                          : variant === "success"
+                            ? "Looks great!"
+                            : "Helper text"
+                    }
+                    fullWidth
+                  />
+                  <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+                    {label}
+                  </p>
+                </div>
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+    )
   },
 }
 
-export const UrlInput: Story = {
-  args: {
-    label: "Website",
-    type: "url",
-    placeholder: "https://example.com",
-  },
-}
+// ─── 3. Configurations ────────────────────────────────────────────────────────
 
-// With icons
-export const WithStartIcon: Story = {
-  args: {
-    label: "Search",
-    placeholder: "Search for items...",
-    startIcon: <TickIcon className="h-4 w-4 text-gray-400" />,
+export const Configurations: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Non-variant configuration axes: start icon, end icon, both icons together, and different input types (email, password with toggle, number).",
+      },
+    },
   },
-}
+  render: () => (
+    <div className="w-full max-w-sm space-y-8">
+      {/* Start icon */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Start Icon
+        </h4>
+        <div className="flex flex-wrap gap-4">
+          <div className="w-full space-y-2 text-center">
+            <Input
+              label="Search"
+              placeholder="Search…"
+              decoration="outline"
+              startIcon={<AlertIcon className="text-fm-secondary h-4 w-4" />}
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              startIcon
+            </p>
+          </div>
+        </div>
+      </div>
 
-export const WithEndIcon: Story = {
-  args: {
-    label: "Verified Field",
-    placeholder: "Enter verified information",
-    endIcon: <TickIcon className="h-4 w-4 text-green-500" />,
-    variant: "success",
-  },
-}
+      {/* End icon */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          End Icon
+        </h4>
+        <div className="w-full space-y-2 text-center">
+          <Input
+            label="Verified email"
+            placeholder="you@example.com"
+            decoration="outline"
+            variant="success"
+            endIcon={<TickIcon className="text-fm-positive h-4 w-4" />}
+            helperText="Email is valid"
+            fullWidth
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            endIcon
+          </p>
+        </div>
+      </div>
 
-export const WithBothIcons: Story = {
-  args: {
-    label: "Username",
-    placeholder: "Enter username",
-    startIcon: <AlertIcon className="h-4 w-4 text-red-400" />,
-    endIcon: <CrossIcon className="h-4 w-4 text-red-500" />,
-    variant: "error",
-    helperText: "Username is already taken",
-  },
-}
+      {/* Both icons */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Both Icons
+        </h4>
+        <div className="w-full space-y-2 text-center">
+          <Input
+            label="Username"
+            placeholder="your_handle"
+            decoration="outline"
+            variant="error"
+            startIcon={<AlertIcon className="text-fm-negative h-4 w-4" />}
+            endIcon={<CrossIcon className="text-fm-negative h-4 w-4" />}
+            helperText="Username already taken"
+            fullWidth
+          />
+          <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+            startIcon + endIcon
+          </p>
+        </div>
+      </div>
 
-// Complex examples
-export const LoginForm: Story = {
-  render: () => (
-    <div className="w-80 space-y-4">
-      <Input
-        label="Email"
-        type="email"
-        placeholder="Enter your email"
-        required
-        fullWidth
-      />
-      <Input
-        label="Password"
-        type="password"
-        placeholder="Enter your password"
-        required
-        fullWidth
-      />
+      {/* Input types */}
+      <div>
+        <h4 className="text-fm-secondary font-fm-text text-fm-md leading-fm-md mb-4 font-medium">
+          Input Types
+        </h4>
+        <div className="space-y-4">
+          <div className="space-y-2 text-center">
+            <Input
+              label="Email"
+              type="email"
+              placeholder="you@example.com"
+              decoration="outline"
+              startIcon={<EmailIcon className="text-fm-secondary h-4 w-4" />}
+              helperText="We'll never share your email"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              type="email"
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Input
+              label="Password"
+              type="password"
+              placeholder="Min 8 characters"
+              decoration="outline"
+              helperText="Password toggle appears automatically"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              type="password" (toggle built-in)
+            </p>
+          </div>
+          <div className="space-y-2 text-center">
+            <Input
+              label="Age"
+              type="number"
+              placeholder="25"
+              decoration="outline"
+              fullWidth
+            />
+            <p className="text-fm-secondary font-fm-text text-fm-sm leading-fm-sm">
+              type="number"
+            </p>
+          </div>
+        </div>
+      </div>
     </div>
   ),
-  parameters: {
-    layout: "centered",
-  },
 }
 
-export const ValidationStates: Story = {
-  render: () => (
-    <div className="w-80 space-y-4">
-      <Input
-        label="Valid Email"
-        type="email"
-        value="user@example.com"
-        variant="success"
-        helperText="Email is valid"
-        endIcon={<TickIcon className="h-4 w-4 text-green-500" />}
-        fullWidth
-      />
-      <Input
-        label="Invalid Email"
-        type="email"
-        value="invalid-email"
-        variant="error"
-        helperText="Please enter a valid email address"
-        endIcon={<CrossIcon className="h-4 w-4 text-red-500" />}
-        fullWidth
-      />
-      <Input
-        label="Weak Password"
-        type="password"
-        value="123"
-        variant="warning"
-        helperText="Password is too weak. Use at least 8 characters"
-        fullWidth
-      />
-    </div>
-  ),
+// ─── 4. States ────────────────────────────────────────────────────────────────
+
+export const States: Story = {
   parameters: {
-    layout: "centered",
+    docs: {
+      description: {
+        story:
+          "All five input states side by side: default (idle), disabled (non-interactive), error, warning, and success.",
+      },
+    },
   },
-}
-
-export const DifferentSizes: Story = {
   render: () => (
-    <div className="space-y-4">
-      <div className="w-60">
-        <Input label="Small Width" placeholder="60 units wide" />
-      </div>
-      <div className="w-80">
-        <Input label="Medium Width" placeholder="80 units wide" />
-      </div>
-      <div className="w-96">
-        <Input label="Large Width" placeholder="96 units wide" />
-      </div>
-      <div className="w-full">
-        <Input
-          label="Full Width"
-          placeholder="Full container width"
-          fullWidth
-        />
-      </div>
+    <div className="w-full max-w-sm space-y-8">
+      {[
+        {
+          label: "Default",
+          props: {
+            label: "Default",
+            placeholder: "Enter a value…",
+            variant: "default" as const,
+          },
+        },
+        {
+          label: "Disabled",
+          props: {
+            label: "Disabled",
+            value: "Cannot edit this",
+            disabled: true,
+            variant: "default" as const,
+          },
+        },
+        {
+          label: "Error",
+          props: {
+            label: "Error",
+            value: "invalid-email",
+            variant: "error" as const,
+            helperText: "Please enter a valid email address.",
+          },
+        },
+        {
+          label: "Warning",
+          props: {
+            label: "Warning",
+            value: "abc",
+            variant: "warning" as const,
+            helperText: "Password is too short (min 8 characters).",
+          },
+        },
+        {
+          label: "Success",
+          props: {
+            label: "Success",
+            value: "user@example.com",
+            variant: "success" as const,
+            helperText: "Email is valid.",
+          },
+        },
+      ].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>
+          <Input decoration="outline" fullWidth {...props} />
+        </div>
+      ))}
     </div>
   ),
-  parameters: {
-    layout: "padded",
-  },
 }
 
-// Atomic components showcase
-export const AtomicComponents: Story = {
-  render: () => (
-    <div className="space-y-6">
-      <div>
-        <h3 className="text-fm-primary mb-3 text-lg font-semibold">
-          Using Atomic Components
-        </h3>
-
-        <Input.Root className="w-80">
-          <Input.Label htmlFor="custom-input" required>
-            Custom Composed Input
-          </Input.Label>
-
-          <Input.Wrapper>
-            <Input.StartIcon>
-              <AlertIcon className="text-fm-secondary h-4 w-4" />
-            </Input.StartIcon>
-
-            <Input.Base
-              id="custom-input"
-              className="block w-full rounded-md border border-gray-300 py-2 pr-10 pl-10 transition-all duration-200 focus:border-blue-500 focus:ring-2 focus:ring-blue-500/20 focus:outline-none"
-              placeholder="Custom composition"
-            />
-
-            <Input.EndIcon>
-              <TickIcon className="h-4 w-4 text-green-500" />
-            </Input.EndIcon>
-          </Input.Wrapper>
+// ─── 5. Interactive ───────────────────────────────────────────────────────────
 
-          <HelperText variant="success">
-            Built using atomic components
-          </HelperText>
-        </Input.Root>
-      </div>
-    </div>
-  ),
+export const Interactive: Story = {
   parameters: {
-    layout: "centered",
+    docs: {
+      description: {
+        story:
+          "Live validation demo. The email and password inputs update their variant and helper text in real time as you type. Preset buttons let you jump to predefined states.",
+      },
+    },
   },
-}
-
-// Interactive example
-export const InteractiveExample: Story = {
   render: () => {
     const [email, setEmail] = React.useState("")
     const [password, setPassword] = React.useState("")
+    const [decoration, setDecoration] = React.useState<
+      "underline" | "outline" | "filled"
+    >("outline")
 
     const emailVariant =
-      email.includes("@") && email.includes(".")
-        ? "success"
-        : email.length > 0
-          ? "error"
-          : "default"
+      email.length === 0
+        ? "default"
+        : email.includes("@") && email.includes(".")
+          ? "success"
+          : "error"
+
     const passwordVariant =
-      password.length >= 8
-        ? "success"
-        : password.length > 0
-          ? "warning"
-          : "default"
+      password.length === 0
+        ? "default"
+        : password.length >= 8
+          ? "success"
+          : password.length >= 4
+            ? "warning"
+            : "error"
+
+    const presets: Array<{ label: string; email: string; password: string }> = [
+      {
+        label: "Valid credentials",
+        email: "user@example.com",
+        password: "securepass1",
+      },
+      {
+        label: "Invalid email",
+        email: "not-an-email",
+        password: "securepass1",
+      },
+      { label: "Weak password", email: "user@example.com", password: "abc" },
+      { label: "Clear", email: "", password: "" },
+    ]
 
     return (
-      <div className="w-80 space-y-4">
-        <Input
-          label="Email"
-          type="email"
-          placeholder="Enter your email"
-          value={email}
-          onChange={(e) => setEmail(e.target.value)}
-          variant={emailVariant}
-          helperText={
-            emailVariant === "success"
-              ? "Email looks good!"
-              : emailVariant === "error"
-                ? "Please enter a valid email"
-                : "Enter your email address"
-          }
-          endIcon={
-            emailVariant === "success" ? (
-              <TickIcon className="h-4 w-4 text-green-500" />
-            ) : undefined
-          }
-          required
-          fullWidth
-        />
-
-        <Input
-          label="Password"
-          type="password"
-          placeholder="Enter your password"
-          value={password}
-          onChange={(e) => setPassword(e.target.value)}
-          variant={passwordVariant}
-          helperText={
-            passwordVariant === "success"
-              ? "Password strength is good"
-              : passwordVariant === "warning"
-                ? "Password is too short (min 8 characters)"
-                : "Enter your password"
-          }
-          required
-          fullWidth
-        />
-
-        <div className="text-fm-secondary text-sm">
-          Email: {email || "(empty)"}
-          <br />
-          Password: {"*".repeat(password.length) || "(empty)"}
+      <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, email: e, password: p }) => (
+                  <button
+                    key={label}
+                    onClick={() => {
+                      setEmail(e)
+                      setPassword(p)
+                    }}
+                    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>
+
+            {/* Preview stage */}
+            <div className="flex flex-col gap-4 lg:col-span-2">
+              <Input
+                label="Email"
+                type="email"
+                placeholder="you@example.com"
+                value={email}
+                onChange={(e) => setEmail(e.target.value)}
+                variant={emailVariant as "default" | "error" | "success"}
+                decoration={decoration}
+                helperText={
+                  emailVariant === "success"
+                    ? "Email looks good!"
+                    : emailVariant === "error"
+                      ? "Please enter a valid email address."
+                      : "Enter your email address"
+                }
+                required
+                fullWidth
+              />
+
+              <Input
+                label="Password"
+                type="password"
+                placeholder="Min 8 characters"
+                value={password}
+                onChange={(e) => setPassword(e.target.value)}
+                variant={
+                  passwordVariant as "default" | "error" | "warning" | "success"
+                }
+                decoration={decoration}
+                helperText={
+                  passwordVariant === "success"
+                    ? "Password strength is strong."
+                    : passwordVariant === "warning"
+                      ? "Password is too short — use at least 8 characters."
+                      : passwordVariant === "error"
+                        ? "Password is far too short."
+                        : "Enter your password"
+                }
+                required
+                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)">
+                  {`email variant="${emailVariant}" | password variant="${passwordVariant}"`}
+                </code>
+              </div>
+            </div>
+          </div>
         </div>
       </div>
     )
   },
-  parameters: {
-    layout: "centered",
-  },
-}
-
-// Edge cases
-export const EdgeCases: Story = {
-  render: () => (
-    <div className="w-80 space-y-4">
-      <Input
-        label="Very Long Label That Might Wrap to Multiple Lines in Some Cases"
-        placeholder="Long label test"
-        helperText="This demonstrates how the component handles very long labels and helper text that might wrap to multiple lines in constrained spaces"
-        variant="default"
-        fullWidth
-      />
-
-      <Input
-        label=""
-        placeholder="No label provided"
-        helperText="Input without label"
-        fullWidth
-      />
-
-      <Input label="No Helper Text" placeholder="Clean input" fullWidth />
-
-      <Input placeholder="No label, no helper text" fullWidth />
-
-      <Input
-        label="All Features"
-        placeholder="Everything enabled"
-        startIcon={<AlertIcon className="h-4 w-4 text-blue-500" />}
-        endIcon={<TickIcon className="h-4 w-4 text-green-500" />}
-        helperText="This input has all features enabled"
-        variant="success"
-        required
-        fullWidth
-      />
-    </div>
-  ),
-  parameters: {
-    layout: "centered",
-  },
 }