@tribepad/themis 1.0.0

package/src/elements/TextField/TextField.stories.tsx

@@ -0,0 +1,1878 @@
+/**
+ * TextField Component Stories
+ * Storybook stories for TextField component demonstrating all variants, sizes, and states
+ *
+ * @see spec.md FR-009 to FR-014 (Accessibility Requirements - WCAG 2.2 AAA)
+ */
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+import { TextField } from './TextField';
+
+const meta = {
+  title: 'Elements/TextField',
+  component: TextField,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'Accessible text input component with label, description, and error handling. Built with React Aria TextField primitive, CVA variant styling, and WCAG 2.2 AAA compliance (7:1 contrast ratio, proper ARIA attributes).',
+      },
+    },
+  },
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg'],
+      description: 'TextField size',
+      table: {
+        defaultValue: { summary: 'default' },
+      },
+    },
+    label: {
+      control: 'text',
+      description: 'Label text for the input',
+    },
+    description: {
+      control: 'text',
+      description: 'Helper text displayed below the input',
+    },
+    errorMessage: {
+      control: 'text',
+      description: 'Error message displayed when isInvalid is true',
+    },
+    type: {
+      control: 'select',
+      options: ['text', 'email', 'password', 'tel', 'url', 'search'],
+      description: 'HTML input type',
+      table: {
+        defaultValue: { summary: 'text' },
+      },
+    },
+    isRequired: {
+      control: 'boolean',
+      description: 'Shows required indicator and sets aria-required',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isReadOnly: {
+      control: 'boolean',
+      description: 'Makes input read-only',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isDisabled: {
+      control: 'boolean',
+      description: 'Disables the input',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    isInvalid: {
+      control: 'boolean',
+      description: 'Shows error styling and displays error message',
+      table: {
+        defaultValue: { summary: 'false' },
+      },
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Placeholder text for the input',
+    },
+  },
+} satisfies Meta<typeof TextField>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+// Basic stories
+export const Default: Story = {
+  args: {
+    label: 'Username',
+    placeholder: 'Enter your username',
+  },
+};
+
+export const WithDescription: Story = {
+  args: {
+    label: 'Email',
+    description: "We'll never share your email with anyone.",
+    placeholder: 'you@example.com',
+    type: 'email',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    label: 'Username',
+    errorMessage: 'Username is required',
+    isInvalid: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Error state with validation message. Description text is hidden when error is shown.',
+      },
+    },
+  },
+};
+
+export const Required: Story = {
+  args: {
+    label: 'Email',
+    description: 'This field is required',
+    isRequired: true,
+    type: 'email',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Required field with visual indicator (*) and aria-required attribute.',
+      },
+    },
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    label: 'Username',
+    value: 'john.doe',
+    isDisabled: true,
+  },
+};
+
+export const ReadOnly: Story = {
+  args: {
+    label: 'Username',
+    value: 'john.doe',
+    isReadOnly: true,
+    description: 'This field cannot be edited',
+  },
+};
+
+export const WithoutLabel: Story = {
+  args: {
+    placeholder: 'Search...',
+    type: 'search',
+    'aria-label': 'Search',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'TextField without visible label. aria-label is required for accessibility.',
+      },
+    },
+  },
+};
+
+// Size variants
+export const Small: Story = {
+  args: {
+    label: 'Username',
+    size: 'sm',
+    placeholder: 'Small input',
+  },
+};
+
+export const Large: Story = {
+  args: {
+    label: 'Username',
+    size: 'lg',
+    placeholder: 'Large input',
+  },
+};
+
+export const AllSizes: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <TextField label="Small" size="sm" placeholder="Small input" />
+      <TextField label="Default" size="default" placeholder="Default input" />
+      <TextField label="Large" size="lg" placeholder="Large input" />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All 3 size variants: sm (h-9), default (h-10), lg (h-11).',
+      },
+    },
+  },
+};
+
+// Input type variants
+export const TextType: Story = {
+  args: {
+    label: 'Full Name',
+    type: 'text',
+    placeholder: 'John Doe',
+  },
+};
+
+export const EmailType: Story = {
+  args: {
+    label: 'Email Address',
+    type: 'email',
+    placeholder: 'you@example.com',
+    description: 'We respect your privacy',
+  },
+};
+
+export const PasswordType: Story = {
+  args: {
+    label: 'Password',
+    type: 'password',
+    placeholder: 'Enter your password',
+    description: 'At least 8 characters',
+  },
+};
+
+// NOTE: TelType removed (breaking change) - use TelField component instead
+
+export const UrlType: Story = {
+  args: {
+    label: 'Website',
+    type: 'url',
+    placeholder: 'https://example.com',
+  },
+};
+
+export const SearchType: Story = {
+  args: {
+    label: 'Search',
+    type: 'search',
+    placeholder: 'Search...',
+  },
+};
+
+// AutoComplete Examples (Phase 2)
+export const AutoCompleteEmail: Story = {
+  args: {
+    label: 'Email Address',
+    type: 'email',
+    autoComplete: 'email',
+    placeholder: 'you@example.com',
+    description: 'Browser will suggest previously entered emails',
+  },
+};
+
+export const AutoCompleteName: Story = {
+  args: {
+    label: 'Full Name',
+    type: 'text',
+    autoComplete: 'name',
+    placeholder: 'John Doe',
+    description: 'Browser will suggest your name from previous entries',
+  },
+};
+
+export const AutoCompleteCurrentPassword: Story = {
+  args: {
+    label: 'Password',
+    type: 'password',
+    autoComplete: 'current-password',
+    placeholder: 'Enter your password',
+    description: 'Password manager will offer to fill this field',
+  },
+};
+
+export const AutoCompleteNewPassword: Story = {
+  args: {
+    label: 'New Password',
+    type: 'password',
+    autoComplete: 'new-password',
+    placeholder: 'Create a strong password',
+    description: 'Password manager will offer to generate and save',
+  },
+};
+
+export const AutoCompleteAddressLine1: Story = {
+  args: {
+    label: 'Street Address',
+    type: 'text',
+    autoComplete: 'address-line1',
+    placeholder: '123 Main St',
+    description: 'Browser will suggest street address',
+  },
+};
+
+export const AutoCompleteCreditCard: Story = {
+  args: {
+    label: 'Card Number',
+    type: 'text',
+    autoComplete: 'cc-number',
+    placeholder: '1234 5678 9012 3456',
+    description: 'Browser may offer saved card numbers',
+  },
+};
+
+export const AutoCompleteOff: Story = {
+  args: {
+    label: 'One-Time Code',
+    type: 'text',
+    autoComplete: 'off',
+    placeholder: 'Enter code',
+    description: 'Browser autocomplete disabled for security',
+  },
+};
+
+export const LoginFormWithAutoComplete: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-sm">
+      <h3 className="text-lg font-semibold">Login Form with AutoComplete</h3>
+      <TextField
+        label="Email"
+        type="email"
+        autoComplete="email"
+        placeholder="you@example.com"
+        isRequired
+      />
+      <TextField
+        label="Password"
+        type="password"
+        autoComplete="current-password"
+        placeholder="Enter your password"
+        isRequired
+      />
+      <p className="text-sm text-muted-foreground">
+        Browser will remember and suggest your credentials
+      </p>
+    </div>
+  ),
+};
+
+export const SignupFormWithAutoComplete: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-sm">
+      <h3 className="text-lg font-semibold">Signup Form with AutoComplete</h3>
+      <TextField
+        label="Full Name"
+        type="text"
+        autoComplete="name"
+        placeholder="John Doe"
+        isRequired
+      />
+      <TextField
+        label="Email"
+        type="email"
+        autoComplete="email"
+        placeholder="you@example.com"
+        isRequired
+      />
+      <TextField
+        label="Create Password"
+        type="password"
+        autoComplete="new-password"
+        placeholder="Create a strong password"
+        description="Password manager will offer to generate and save"
+        isRequired
+      />
+    </div>
+  ),
+};
+
+export const AddressFormWithAutoComplete: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-sm">
+      <h3 className="text-lg font-semibold">Address Form with AutoComplete</h3>
+      <TextField
+        label="Street Address"
+        type="text"
+        autoComplete="address-line1"
+        placeholder="123 Main St"
+        isRequired
+      />
+      <TextField
+        label="Apartment/Suite"
+        type="text"
+        autoComplete="address-line2"
+        placeholder="Apt 4B"
+      />
+      <TextField
+        label="City"
+        type="text"
+        autoComplete="address-level2"
+        placeholder="New York"
+        isRequired
+      />
+      <TextField
+        label="Postal Code"
+        type="text"
+        autoComplete="postal-code"
+        placeholder="10001"
+        isRequired
+      />
+      <p className="text-sm text-muted-foreground">
+        Browser will suggest your saved address details
+      </p>
+    </div>
+  ),
+};
+
+// Copy/Paste Restriction Examples (Phase 3)
+export const PasswordConfirmationNoPaste: Story = {
+  args: {
+    label: 'Confirm Password',
+    type: 'password',
+    disableCopyPaste: true,
+    description: 'Please type your password again (pasting is not allowed)',
+    isRequired: true,
+  },
+};
+
+export const EmailConfirmationNoPaste: Story = {
+  args: {
+    label: 'Confirm Email',
+    type: 'email',
+    disableCopyPaste: true,
+    description: 'Please type your email again to confirm',
+    isRequired: true,
+  },
+};
+
+export const SecureFieldWithShakeDemo: Story = {
+  args: {
+    label: 'One-Time Code',
+    type: 'text',
+    disableCopyPaste: true,
+    description: 'Try to paste - the field will shake to indicate pasting is not allowed',
+    placeholder: 'Enter code manually',
+  },
+};
+
+export const CopyPastePasswordConfirmation: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-sm">
+      <h3 className="text-lg font-semibold">Password Confirmation Example</h3>
+      <TextField
+        label="New Password"
+        type="password"
+        autoComplete="new-password"
+        placeholder="Create password"
+        description="Create a strong password"
+        isRequired
+      />
+      <TextField
+        label="Confirm Password"
+        type="password"
+        disableCopyPaste={true}
+        placeholder="Type password again"
+        description="Please type your password again (pasting is not allowed for security)"
+        isRequired
+      />
+      <p className="text-sm text-muted-foreground">
+        The confirmation field prevents pasting to ensure you typed the password correctly.
+        If you try to paste, the field will shake and announce the restriction to screen readers.
+      </p>
+    </div>
+  ),
+};
+
+export const EmailConfirmationForm: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-sm">
+      <h3 className="text-lg font-semibold">Email Confirmation Example</h3>
+      <TextField
+        label="Email Address"
+        type="email"
+        autoComplete="email"
+        placeholder="you@example.com"
+        isRequired
+      />
+      <TextField
+        label="Confirm Email"
+        type="email"
+        disableCopyPaste={true}
+        placeholder="Type email again"
+        description="Re-enter your email address to confirm"
+        isRequired
+      />
+      <p className="text-sm text-muted-foreground">
+        Pasting is disabled in the confirmation field to prevent accidental errors.
+      </p>
+    </div>
+  ),
+};
+
+// Pattern Validation Examples (Phase 4)
+export const USZipCodePattern: Story = {
+  args: {
+    label: 'ZIP Code',
+    type: 'text',
+    pattern: String.raw`\d{5}`,
+    patternDescription: '5-digit ZIP code (e.g., 12345)',
+    placeholder: '12345',
+    isRequired: true,
+  },
+};
+
+export const UsernamePattern: Story = {
+  args: {
+    label: 'Username',
+    type: 'text',
+    pattern: '[a-zA-Z0-9_]{3,16}',
+    patternDescription: '3-16 characters: letters, numbers, or underscores',
+    placeholder: 'john_doe123',
+    isRequired: true,
+  },
+};
+
+export const HexColorPattern: Story = {
+  args: {
+    label: 'Brand Color',
+    type: 'text',
+    pattern: '^#[0-9A-Fa-f]{6}$',
+    patternDescription: 'Hex color code (e.g., #FF5733)',
+    placeholder: '#FF5733',
+    defaultValue: '#',
+  },
+};
+
+export const PhoneNumberPattern: Story = {
+  args: {
+    label: 'Phone Number',
+    type: 'text',
+    pattern: String.raw`\d{3}-\d{3}-\d{4}`,
+    patternDescription: 'Format: 123-456-7890',
+    placeholder: '123-456-7890',
+    isRequired: true,
+  },
+};
+
+export const CanadianPostalCodePattern: Story = {
+  args: {
+    label: 'Postal Code',
+    type: 'text',
+    pattern: '[A-Z]\\d[A-Z] \\d[A-Z]\\d',
+    patternDescription: 'Format: A1A 1A1 (uppercase letters and digits)',
+    placeholder: 'K1A 0B1',
+    isRequired: true,
+  },
+};
+
+export const SlugPattern: Story = {
+  args: {
+    label: 'URL Slug',
+    type: 'text',
+    pattern: '^[a-z0-9]+(?:-[a-z0-9]+)*$',
+    patternDescription: 'Lowercase letters, numbers, and hyphens (e.g., my-blog-post)',
+    placeholder: 'my-article-title',
+    description: 'This will be used in your article URL',
+  },
+};
+
+export const CreditCardPattern: Story = {
+  args: {
+    label: 'Card Number',
+    type: 'text',
+    pattern: String.raw`\d{4} \d{4} \d{4} \d{4}`,
+    patternDescription: '16 digits in groups of 4 (e.g., 1234 5678 9012 3456)',
+    placeholder: '1234 5678 9012 3456',
+    autoComplete: 'cc-number',
+    isRequired: true,
+  },
+};
+
+export const PatternValidationForm: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-md">
+      <h3 className="text-lg font-semibold">Registration Form with Pattern Validation</h3>
+      <TextField
+        label="Username"
+        pattern="[a-z0-9_]{3,16}"
+        patternDescription="3-16 lowercase letters, numbers, or underscores"
+        placeholder="john_doe"
+        description="Choose a unique username"
+        isRequired
+      />
+      <TextField
+        label="Phone Number"
+        pattern={String.raw`\(\d{3}\) \d{3}-\d{4}`}
+        patternDescription="Format: (555) 123-4567"
+        placeholder="(555) 123-4567"
+        autoComplete="tel"
+        isRequired
+      />
+      <TextField
+        label="Website"
+        type="url"
+        pattern="https?://.+"
+        patternDescription="Must start with http:// or https://"
+        placeholder="https://example.com"
+        autoComplete="url"
+      />
+      <TextField
+        label="Promo Code"
+        pattern="[A-Z]{4}\\d{4}"
+        patternDescription="4 uppercase letters followed by 4 digits (e.g., SAVE2024)"
+        placeholder="SAVE2024"
+      />
+      <p className="text-sm text-muted-foreground">
+        All fields use HTML5 pattern validation. Invalid entries will be highlighted when you submit or move to the next field.
+      </p>
+    </div>
+  ),
+};
+
+// Success Validation Examples (Phase 5)
+export const SuccessfulEmailValidation: Story = {
+  args: {
+    label: 'Email Address',
+    type: 'email',
+    isValid: true,
+    successMessage: 'Email is available!',
+    defaultValue: 'john@example.com',
+  },
+};
+
+export const SuccessfulUsernameCheck: Story = {
+  args: {
+    label: 'Username',
+    type: 'text',
+    pattern: '[a-z0-9_]{3,16}',
+    patternDescription: '3-16 lowercase letters, numbers, or underscores',
+    isValid: true,
+    successMessage: 'Username is available!',
+    defaultValue: 'john_doe',
+  },
+};
+
+export const SuccessfulPasswordStrength: Story = {
+  args: {
+    label: 'Password',
+    type: 'password',
+    isValid: true,
+    successMessage: 'Strong password!',
+    description: 'Use at least 8 characters with letters, numbers, and symbols',
+  },
+};
+
+export const SuccessfulZipCodeValidation: Story = {
+  args: {
+    label: 'ZIP Code',
+    pattern: String.raw`\d{5}`,
+    patternDescription: '5-digit ZIP code',
+    isValid: true,
+    successMessage: 'Valid ZIP code',
+    defaultValue: '94102',
+  },
+};
+
+export const SuccessWithoutMessage: Story = {
+  args: {
+    label: 'Email',
+    type: 'email',
+    isValid: true,
+    defaultValue: 'verified@example.com',
+    description: 'This field is validated',
+  },
+};
+
+export const RegistrationFormWithValidation: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-md">
+      <h3 className="text-lg font-semibold">Registration Form with Success States</h3>
+      <TextField
+        label="Username"
+        pattern="[a-z0-9_]{3,16}"
+        patternDescription="3-16 lowercase letters, numbers, or underscores"
+        isValid={true}
+        successMessage="Username is available!"
+        defaultValue="john_doe"
+        isRequired
+      />
+      <TextField
+        label="Email Address"
+        type="email"
+        isValid={true}
+        successMessage="Email verified!"
+        defaultValue="john@example.com"
+        autoComplete="email"
+        isRequired
+      />
+      <TextField
+        label="Password"
+        type="password"
+        isValid={true}
+        successMessage="Strong password!"
+        autoComplete="new-password"
+        isRequired
+      />
+      <TextField
+        label="Referral Code"
+        pattern="[A-Z]{4}\\d{4}"
+        patternDescription="4 letters + 4 digits (e.g., SAVE2024)"
+        placeholder="SAVE2024"
+      />
+      <p className="text-sm text-muted-foreground">
+        Fields with green borders and checkmarks indicate successful validation.
+      </p>
+    </div>
+  ),
+};
+
+// Expand on Focus Examples (Phase 6)
+export const SearchFieldExpandOnFocus: Story = {
+  args: {
+    label: 'Search',
+    type: 'search',
+    expandOnFocus: true,
+    collapsedWidth: '150px',
+    placeholder: 'Search...',
+  },
+};
+
+export const CompactEmailField: Story = {
+  args: {
+    label: 'Email',
+    type: 'email',
+    expandOnFocus: true,
+    collapsedWidth: '200px',
+    placeholder: 'you@example.com',
+    autoComplete: 'email',
+  },
+};
+
+export const CustomCollapsedWidth: Story = {
+  args: {
+    label: 'Username',
+    expandOnFocus: true,
+    collapsedWidth: '120px',
+    placeholder: 'Enter username',
+  },
+};
+
+export const ExpandWithDefaultValue: Story = {
+  args: {
+    label: 'Search Query',
+    type: 'search',
+    expandOnFocus: true,
+    collapsedWidth: '150px',
+    defaultValue: 'React components',
+    description: 'Field stays expanded when it has a value',
+  },
+};
+
+export const MultipleExpandableFields: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-md">
+      <h3 className="text-lg font-semibold">Compact Form with Expand on Focus</h3>
+      <div className="flex gap-2">
+        <TextField
+          label="First Name"
+          expandOnFocus={true}
+          collapsedWidth="100px"
+          placeholder="John"
+        />
+        <TextField
+          label="Last Name"
+          expandOnFocus={true}
+          collapsedWidth="100px"
+          placeholder="Doe"
+        />
+      </div>
+      <TextField
+        label="Email Address"
+        type="email"
+        expandOnFocus={true}
+        collapsedWidth="150px"
+        placeholder="john@example.com"
+        autoComplete="email"
+      />
+      <TextField
+        label="Search"
+        type="search"
+        expandOnFocus={true}
+        collapsedWidth="120px"
+        placeholder="Search..."
+      />
+      <p className="text-sm text-muted-foreground">
+        Click on any field to see it smoothly expand. Fields collapse when you leave them empty.
+      </p>
+    </div>
+  ),
+};
+
+// State combinations
+export const RequiredWithDescription: Story = {
+  args: {
+    label: 'Email',
+    description: 'Required field - please provide your email address',
+    isRequired: true,
+    type: 'email',
+    placeholder: 'you@example.com',
+  },
+};
+
+export const ErrorWithDescription: Story = {
+  args: {
+    label: 'Password',
+    description: 'At least 8 characters, one uppercase, one number',
+    errorMessage: 'Password must contain at least one uppercase letter',
+    isInvalid: true,
+    type: 'password',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'When both description and error are provided, error takes precedence.',
+      },
+    },
+  },
+};
+
+export const RequiredAndInvalid: Story = {
+  args: {
+    label: 'Email',
+    errorMessage: 'Email is required',
+    isRequired: true,
+    isInvalid: true,
+    type: 'email',
+  },
+};
+
+export const AllStates: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-80">
+      <TextField label="Default" placeholder="Default state" />
+      <TextField label="Required" isRequired description="This field is required" />
+      <TextField
+        label="Invalid"
+        errorMessage="This field is invalid"
+        isInvalid
+      />
+      <TextField label="Disabled" isDisabled value="Disabled value" />
+      <TextField label="Read-only" isReadOnly value="Read-only value" />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'All state variants in one view.',
+      },
+    },
+  },
+};
+
+// Theme integration stories
+export const LightTheme: Story = {
+  args: {
+    label: 'Username',
+    description: 'Light theme styling',
+    placeholder: 'Enter username',
+  },
+  parameters: {
+    backgrounds: { default: 'light' },
+  },
+};
+
+export const DarkTheme: Story = {
+  args: {
+    label: 'Username',
+    description: 'Dark theme styling with Themis semantic tokens',
+    placeholder: 'Enter username',
+  },
+  parameters: {
+    backgrounds: { default: 'dark' },
+    docs: {
+      description: {
+        story: 'TextField adapts to dark theme via semantic tokens.',
+      },
+    },
+  },
+};
+
+export const HighContrast: Story = {
+  args: {
+    label: 'Username',
+    description: 'Enhanced contrast for accessibility',
+    placeholder: 'Enter username',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'TextField with enhanced contrast for high contrast mode (WCAG 2.2 AAA).',
+      },
+    },
+  },
+};
+
+export const ColorblindTheme: Story = {
+  args: {
+    label: 'Email',
+    errorMessage: 'Invalid email format',
+    isInvalid: true,
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Error styling visible in colorblind mode (deuteranopia, protanopia, tritanopia support).',
+      },
+    },
+  },
+};
+
+// Real-world examples
+export const RealWorldLoginForm: Story = {
+  render: () => (
+    <form
+      className="flex flex-col gap-4 w-80"
+      onSubmit={(e) => {
+        e.preventDefault();
+        alert('Login submitted!');
+      }}
+    >
+      <TextField
+        label="Email"
+        type="email"
+        placeholder="you@example.com"
+        isRequired
+        description="We'll never share your email"
+      />
+      <TextField
+        label="Password"
+        type="password"
+        placeholder="Enter your password"
+        isRequired
+        description="At least 8 characters"
+      />
+      <button
+        type="submit"
+        className="mt-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground"
+      >
+        Sign In
+      </button>
+    </form>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Complete login form with email and password fields.',
+      },
+    },
+  },
+};
+
+export const ContactForm: Story = {
+  render: () => (
+    <form
+      className="flex flex-col gap-4 w-80"
+      onSubmit={(e) => {
+        e.preventDefault();
+        alert('Contact form submitted!');
+      }}
+    >
+      <TextField label="Name" isRequired placeholder="John Doe" />
+      <TextField
+        label="Email"
+        type="email"
+        isRequired
+        placeholder="you@example.com"
+      />
+      <TextField
+        label="Website"
+        type="url"
+        placeholder="https://example.com"
+        description="Optional"
+      />
+      <button
+        type="submit"
+        className="mt-2 rounded-md bg-primary px-4 py-2 text-sm font-medium text-primary-foreground"
+      >
+        Submit
+      </button>
+    </form>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Contact form with multiple field types and validation.',
+      },
+    },
+  },
+};
+
+export const ValidationExample: Story = {
+  render: () => {
+    const [email, setEmail] = useState('');
+    const [isInvalid, setIsInvalid] = useState(false);
+
+    const validateEmail = (value: string) => {
+      const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+      setIsInvalid(!emailRegex.test(value) && value.length > 0);
+    };
+
+    return (
+      <div className="w-80">
+        <TextField
+          label="Email"
+          type="email"
+          value={email}
+          onChange={(value) => {
+            setEmail(value);
+            validateEmail(value);
+          }}
+          isInvalid={isInvalid}
+          errorMessage="Please enter a valid email address"
+          description="We'll send you a confirmation email"
+          isRequired
+        />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Live validation example with controlled component pattern.',
+      },
+    },
+  },
+};
+
+export const MultiFieldForm: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6 w-96">
+      <div className="grid grid-cols-2 gap-4">
+        <TextField label="First Name" isRequired placeholder="John" />
+        <TextField label="Last Name" isRequired placeholder="Doe" />
+      </div>
+      <TextField
+        label="Email"
+        type="email"
+        isRequired
+        placeholder="you@example.com"
+      />
+      <TextField
+        label="Company"
+        placeholder="Acme Inc."
+        description="Optional"
+      />
+      <div className="grid grid-cols-2 gap-4">
+        <TextField label="City" placeholder="New York" />
+        <TextField label="ZIP Code" placeholder="10001" />
+      </div>
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Multi-field form layout with grid positioning.',
+      },
+    },
+  },
+};
+
+// Accessibility stories
+export const FocusVisible: Story = {
+  args: {
+    label: 'Focus Me',
+    placeholder: 'Tab to see focus ring',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Press Tab to see the focus ring. Meets WCAG 2.2 AAA standards with visible focus indicator.',
+      },
+    },
+  },
+};
+
+export const KeyboardNavigation: Story = {
+  render: () => (
+    <div className="flex flex-col gap-4 w-80">
+      <TextField label="First Field" placeholder="Tab to next" />
+      <TextField label="Second Field" placeholder="Tab to next" />
+      <TextField label="Third Field" placeholder="Tab to next" />
+      <TextField label="Disabled Field" isDisabled placeholder="Skipped" />
+      <TextField label="Fourth Field" placeholder="Last field" />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use Tab/Shift+Tab to navigate. Disabled fields are skipped automatically.',
+      },
+    },
+  },
+};
+
+export const ScreenReaderSupport: Story = {
+  args: {
+    label: 'Email Address',
+    description: 'This description is announced by screen readers',
+    isRequired: true,
+    type: 'email',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'All TextField elements are properly linked via ARIA: label, description (aria-describedby), error (aria-errormessage), required (aria-required).',
+      },
+    },
+  },
+};
+
+/**
+ * Phase 8: Prefix/Suffix Feature Stories
+ * Demonstrates prefix and suffix for currency, units, and icons
+ */
+
+// Currency prefix
+export const CurrencyInput: Story = {
+  args: {
+    label: 'Price',
+    prefix: '$',
+    type: 'text',
+    placeholder: '0.00',
+    description: 'Enter the price in USD',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use prefix for currency symbols. The input automatically adds padding to accommodate the prefix.',
+      },
+    },
+  },
+};
+
+// Unit suffix
+export const UnitInput: Story = {
+  args: {
+    label: 'Weight',
+    suffix: 'kg',
+    type: 'text',
+    placeholder: '0',
+    description: 'Enter the weight in kilograms',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use suffix for units of measurement. The input automatically adds padding to accommodate the suffix.',
+      },
+    },
+  },
+};
+
+// Both prefix and suffix
+export const PrefixAndSuffix: Story = {
+  args: {
+    label: 'Amount',
+    prefix: '$',
+    suffix: 'USD',
+    type: 'text',
+    placeholder: '0.00',
+    description: 'Enter the amount with currency code',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Combine prefix and suffix for complex input formats like currency with codes.',
+      },
+    },
+  },
+};
+
+// Icon prefix (search)
+export const IconPrefix: Story = {
+  render: () => {
+    const SearchIcon = () => (
+      <svg
+        width="16"
+        height="16"
+        viewBox="0 0 16 16"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="7" cy="7" r="5" />
+        <path d="M11 11l3 3" />
+      </svg>
+    );
+
+    return (
+      <TextField
+        label="Search"
+        prefix={<SearchIcon />}
+        prefixSize={16}
+        type="search"
+        placeholder="Search..."
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use ReactNode (like SVG icons) as prefix. Set prefixSize to control icon dimensions.',
+      },
+    },
+  },
+};
+
+// Icon suffix (status indicator)
+export const IconSuffix: Story = {
+  render: () => {
+    const CheckIcon = () => (
+      <svg
+        width="16"
+        height="16"
+        viewBox="0 0 16 16"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M13 4L6 11L3 8" />
+      </svg>
+    );
+
+    return (
+      <TextField
+        label="Username"
+        suffix={<CheckIcon />}
+        suffixSize={16}
+        type="text"
+        placeholder="username"
+        isValid={true}
+        successMessage="Username is available"
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Use ReactNode (like SVG icons) as suffix for status indicators or actions.',
+      },
+    },
+  },
+};
+
+// Multiple fields with prefixes/suffixes
+export const FormWithPrefixSuffix: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-md">
+      <h3 className="text-lg font-semibold">Product Details Form</h3>
+      <TextField
+        label="Product Name"
+        type="text"
+        placeholder="Enter product name"
+        isRequired={true}
+      />
+      <TextField
+        label="Price"
+        prefix="$"
+        suffix="USD"
+        type="text"
+        placeholder="0.00"
+        description="Retail price in US dollars"
+      />
+      <TextField
+        label="Weight"
+        suffix="kg"
+        type="text"
+        placeholder="0.0"
+        description="Shipping weight"
+      />
+      <TextField
+        label="Discount"
+        suffix="%"
+        type="text"
+        placeholder="0"
+        description="Percentage discount (0-100)"
+      />
+      <TextField
+        label="SKU"
+        prefix="#"
+        type="text"
+        placeholder="ABC123"
+        description="Stock keeping unit"
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'A complete form demonstrating various prefix/suffix combinations for different data types.',
+      },
+    },
+  },
+};
+
+// Prefix/suffix with different sizes
+export const PrefixSuffixSizes: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-md">
+      <h3 className="text-lg font-semibold">Prefix/Suffix with Size Variants</h3>
+      <TextField
+        label="Small Amount"
+        prefix="$"
+        size="sm"
+        type="text"
+        placeholder="0.00"
+      />
+      <TextField
+        label="Default Amount"
+        prefix="$"
+        size="default"
+        type="text"
+        placeholder="0.00"
+      />
+      <TextField
+        label="Large Amount"
+        prefix="$"
+        size="lg"
+        type="text"
+        placeholder="0.00"
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Prefix and suffix work seamlessly with all input size variants (sm, default, lg).',
+      },
+    },
+  },
+};
+
+/**
+ * Phase 7: Password Toggle Feature Stories
+ * Demonstrates password visibility toggle for password fields
+ */
+
+// Basic password with toggle
+export const PasswordWithToggle: Story = {
+  args: {
+    label: 'Password',
+    type: 'password',
+    showPasswordToggle: true,
+    placeholder: 'Enter your password',
+    description: 'Click the eye icon to toggle password visibility',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Enable showPasswordToggle to add a visibility toggle button. Click the eye icon or use keyboard (Tab + Space/Enter) to toggle.',
+      },
+    },
+  },
+};
+
+// Password toggle with validation
+export const PasswordToggleWithValidation: Story = {
+  render: () => {
+    const [password, setPassword] = useState('');
+    const [isValid, setIsValid] = useState<boolean | undefined>(undefined);
+    const [errorMessage, setErrorMessage] = useState('');
+
+    const validatePassword = (value: string) => {
+      if (value.length === 0) {
+        setIsValid(undefined);
+        setErrorMessage('');
+        return;
+      }
+
+      if (value.length < 8) {
+        setIsValid(false);
+        setErrorMessage('Password must be at least 8 characters');
+        return;
+      }
+
+      if (!/[A-Z]/.test(value)) {
+        setIsValid(false);
+        setErrorMessage('Password must contain at least one uppercase letter');
+        return;
+      }
+
+      if (!/[0-9]/.test(value)) {
+        setIsValid(false);
+        setErrorMessage('Password must contain at least one number');
+        return;
+      }
+
+      setIsValid(true);
+      setErrorMessage('');
+    };
+
+    return (
+      <TextField
+        label="New Password"
+        type="password"
+        showPasswordToggle={true}
+        value={password}
+        onChange={(val) => {
+          setPassword(val);
+          validatePassword(val);
+        }}
+        isInvalid={isValid === false}
+        isValid={isValid === true}
+        errorMessage={errorMessage}
+        successMessage="Password meets all requirements"
+        description="Must be 8+ characters with uppercase and number"
+      />
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Password toggle works seamlessly with validation. Toggle visibility to verify password while typing.',
+      },
+    },
+  },
+};
+
+// Password confirmation form
+export const PasswordToggleConfirmation: Story = {
+  render: () => {
+    const [password, setPassword] = useState('');
+    const [confirmPassword, setConfirmPassword] = useState('');
+    const [passwordsMatch, setPasswordsMatch] = useState<boolean | undefined>(undefined);
+
+    useEffect(() => {
+      if (confirmPassword.length > 0) {
+        setPasswordsMatch(password === confirmPassword);
+      } else {
+        setPasswordsMatch(undefined);
+      }
+    }, [password, confirmPassword]);
+
+    return (
+      <div className="space-y-4 max-w-md">
+        <h3 className="text-lg font-semibold">Create Account</h3>
+        <TextField
+          label="Password"
+          type="password"
+          showPasswordToggle={true}
+          value={password}
+          onChange={setPassword}
+          placeholder="Enter password"
+          description="At least 8 characters"
+        />
+        <TextField
+          label="Confirm Password"
+          type="password"
+          showPasswordToggle={true}
+          value={confirmPassword}
+          onChange={setConfirmPassword}
+          placeholder="Re-enter password"
+          isInvalid={passwordsMatch === false}
+          isValid={passwordsMatch === true}
+          errorMessage="Passwords do not match"
+          successMessage="Passwords match"
+        />
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Common use case: password confirmation. Toggle visibility on either field independently.',
+      },
+    },
+  },
+};
+
+// Password toggle with size variants
+export const PasswordToggleSizes: Story = {
+  render: () => (
+    <div className="space-y-4 max-w-md">
+      <h3 className="text-lg font-semibold">Password Toggle with Size Variants</h3>
+      <TextField
+        label="Small Password"
+        type="password"
+        showPasswordToggle={true}
+        size="sm"
+        placeholder="Enter password"
+      />
+      <TextField
+        label="Default Password"
+        type="password"
+        showPasswordToggle={true}
+        size="default"
+        placeholder="Enter password"
+      />
+      <TextField
+        label="Large Password"
+        type="password"
+        showPasswordToggle={true}
+        size="lg"
+        placeholder="Enter password"
+      />
+    </div>
+  ),
+  parameters: {
+    docs: {
+      description: {
+        story: 'Password toggle works with all input size variants (sm, default, lg).',
+      },
+    },
+  },
+};
+
+// Password with disabled state
+export const PasswordToggleDisabled: Story = {
+  args: {
+    label: 'Password',
+    type: 'password',
+    showPasswordToggle: true,
+    isDisabled: true,
+    value: 'disabled-password',
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'When disabled, the password field and toggle button are both non-interactive.',
+      },
+    },
+  },
+};
+
+// Login form example
+export const PasswordToggleLoginForm: Story = {
+  render: () => {
+    const [email, setEmail] = useState('');
+    const [password, setPassword] = useState('');
+
+    return (
+      <div className="space-y-4 max-w-md">
+        <h3 className="text-lg font-semibold">Login</h3>
+        <TextField
+          label="Email"
+          type="email"
+          value={email}
+          onChange={setEmail}
+          placeholder="you@example.com"
+          autoComplete="email"
+          isRequired={true}
+        />
+        <TextField
+          label="Password"
+          type="password"
+          showPasswordToggle={true}
+          value={password}
+          onChange={setPassword}
+          placeholder="Enter your password"
+          autoComplete="current-password"
+          isRequired={true}
+        />
+        <button
+          type="button"
+          className="w-full bg-[var(--themis-primary)] text-[var(--themis-primary-foreground)] py-2 px-4 rounded-md hover:opacity-90 transition-opacity"
+        >
+          Log In
+        </button>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Complete login form with password toggle. Notice proper autoComplete attributes for password managers.',
+      },
+    },
+  },
+};
+
+/**
+ * Phase 9: Integration & Polish Stories
+ * Comprehensive examples combining multiple features
+ */
+
+// All features combined
+export const AllFeaturesCombined: Story = {
+  render: () => {
+    const [searchQuery, setSearchQuery] = useState('');
+    const [email, setEmail] = useState('');
+    const [password, setPassword] = useState('');
+    const [amount, setAmount] = useState('');
+    const [emailValid, setEmailValid] = useState<boolean | undefined>(undefined);
+
+    useEffect(() => {
+      if (email.length > 0) {
+        const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+        setEmailValid(emailRegex.test(email));
+      } else {
+        setEmailValid(undefined);
+      }
+    }, [email]);
+
+    return (
+      <div className="space-y-6 max-w-2xl">
+        <h2 className="text-2xl font-bold">All TextField Features</h2>
+        <p className="text-sm text-muted-foreground">
+          This showcase demonstrates all TextField enhancement features working together:
+          AutoComplete, Copy/Paste Restriction, Pattern Validation, Success Validation,
+          Expand on Focus, Prefix/Suffix, and Password Toggle.
+        </p>
+
+        <div className="space-y-4">
+          {/* Feature 2: AutoComplete + Feature 6: Expand on Focus */}
+          <TextField
+            label="Search"
+            type="search"
+            prefix={
+              <svg width="16" height="16" viewBox="0 0 16 16" fill="none" stroke="currentColor" strokeWidth="2">
+                <circle cx="7" cy="7" r="5" />
+                <path d="M11 11l3 3" />
+              </svg>
+            }
+            value={searchQuery}
+            onChange={setSearchQuery}
+            placeholder="Search..."
+            expandOnFocus={true}
+            collapsedWidth="200px"
+            description="Expands when focused, collapses when empty"
+            autoComplete="off"
+          />
+
+          {/* Feature 2: AutoComplete + Feature 4: Pattern Validation + Feature 5: Success Validation */}
+          <TextField
+            label="Email"
+            type="email"
+            value={email}
+            onChange={setEmail}
+            placeholder="you@example.com"
+            autoComplete="email"
+            pattern="[^\s@]+@[^\s@]+\.[^\s@]+"
+            patternDescription="Must be a valid email format"
+            isValid={emailValid === true}
+            isInvalid={emailValid === false}
+            successMessage="Valid email address"
+            errorMessage="Please enter a valid email"
+            isRequired={true}
+          />
+
+          {/* Feature 7: Password Toggle + Feature 3: Copy/Paste Restriction + Feature 2: AutoComplete */}
+          <TextField
+            label="Password"
+            type="password"
+            showPasswordToggle={true}
+            value={password}
+            onChange={setPassword}
+            placeholder="Enter secure password"
+            autoComplete="new-password"
+            description="Password cannot be copied or pasted for security"
+            disableCopyPaste={true}
+            isRequired={true}
+          />
+
+          {/* Feature 8: Prefix/Suffix + Feature 4: Pattern Validation */}
+          <TextField
+            label="Amount"
+            type="text"
+            prefix="$"
+            suffix="USD"
+            value={amount}
+            onChange={setAmount}
+            placeholder="0.00"
+            pattern="^\d+(\.\d{1,2})?$"
+            patternDescription="Enter a valid amount (e.g., 10.50)"
+            description="Currency amount with validation"
+          />
+        </div>
+
+        <div className="mt-6 p-4 bg-muted rounded-md">
+          <h3 className="font-semibold mb-2">Feature Summary:</h3>
+          <ul className="text-sm space-y-1 list-disc list-inside">
+            <li>Search field: Prefix icon, expand on focus, autocomplete</li>
+            <li>Email: Pattern validation, success/error states, autocomplete</li>
+            <li>Password: Visibility toggle, copy/paste prevention, autocomplete</li>
+            <li>Amount: Prefix/suffix, pattern validation</li>
+          </ul>
+        </div>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Comprehensive showcase of all TextField enhancement features working together seamlessly.',
+      },
+    },
+  },
+};
+
+// Complex form with all features
+export const CompleteRegistrationForm: Story = {
+  render: () => {
+    const [formData, setFormData] = useState({
+      username: '',
+      email: '',
+      password: '',
+      confirmPassword: '',
+      amount: '',
+      code: '',
+    });
+
+    const [validation, setValidation] = useState({
+      usernameValid: undefined as boolean | undefined,
+      emailValid: undefined as boolean | undefined,
+      passwordValid: undefined as boolean | undefined,
+      passwordsMatch: undefined as boolean | undefined,
+      codeValid: undefined as boolean | undefined,
+    });
+
+    const updateField = (field: string, value: string) => {
+      setFormData(prev => ({ ...prev, [field]: value }));
+    };
+
+    useEffect(() => {
+      // Username validation
+      if (formData.username.length > 0) {
+        setValidation(prev => ({
+          ...prev,
+          usernameValid: /^[a-zA-Z0-9_]{3,16}$/.test(formData.username),
+        }));
+      }
+
+      // Email validation
+      if (formData.email.length > 0) {
+        setValidation(prev => ({
+          ...prev,
+          emailValid: /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(formData.email),
+        }));
+      }
+
+      // Password validation
+      if (formData.password.length > 0) {
+        setValidation(prev => ({
+          ...prev,
+          passwordValid: formData.password.length >= 8 && /[A-Z]/.test(formData.password) && /[0-9]/.test(formData.password),
+        }));
+      }
+
+      // Password match
+      if (formData.confirmPassword.length > 0) {
+        setValidation(prev => ({
+          ...prev,
+          passwordsMatch: formData.password === formData.confirmPassword,
+        }));
+      }
+
+      // Code validation
+      if (formData.code.length > 0) {
+        setValidation(prev => ({
+          ...prev,
+          codeValid: /^[A-Z]{3}$/.test(formData.code),
+        }));
+      }
+    }, [formData]);
+
+    return (
+      <div className="space-y-4 max-w-md">
+        <h3 className="text-lg font-semibold">Complete Registration</h3>
+
+        <TextField
+          label="Username"
+          type="text"
+          value={formData.username}
+          onChange={(val) => updateField('username', val)}
+          placeholder="username"
+          pattern="^[a-zA-Z0-9_]{3,16}$"
+          patternDescription="3-16 characters, letters, numbers, underscore"
+          isValid={validation.usernameValid === true}
+          isInvalid={validation.usernameValid === false}
+          successMessage="Username available"
+          errorMessage="Invalid username format"
+          autoComplete="username"
+          isRequired={true}
+        />
+
+        <TextField
+          label="Email"
+          type="email"
+          value={formData.email}
+          onChange={(val) => updateField('email', val)}
+          placeholder="you@example.com"
+          isValid={validation.emailValid === true}
+          isInvalid={validation.emailValid === false}
+          successMessage="Valid email"
+          errorMessage="Invalid email format"
+          autoComplete="email"
+          isRequired={true}
+        />
+
+        <TextField
+          label="Password"
+          type="password"
+          showPasswordToggle={true}
+          value={formData.password}
+          onChange={(val) => updateField('password', val)}
+          placeholder="Enter password"
+          description="8+ chars, uppercase, number"
+          isValid={validation.passwordValid === true}
+          isInvalid={validation.passwordValid === false}
+          successMessage="Strong password"
+          errorMessage="Password too weak"
+          autoComplete="new-password"
+          isRequired={true}
+        />
+
+        <TextField
+          label="Confirm Password"
+          type="password"
+          showPasswordToggle={true}
+          value={formData.confirmPassword}
+          onChange={(val) => updateField('confirmPassword', val)}
+          placeholder="Re-enter password"
+          disableCopyPaste={true}
+          description="Type password again (no paste)"
+          isValid={validation.passwordsMatch === true}
+          isInvalid={validation.passwordsMatch === false}
+          successMessage="Passwords match"
+          errorMessage="Passwords don't match"
+          autoComplete="new-password"
+          isRequired={true}
+        />
+
+        <TextField
+          label="Referral Code"
+          type="text"
+          prefix="#"
+          value={formData.code}
+          onChange={(val) => updateField('code', val.toUpperCase())}
+          placeholder="ABC"
+          pattern="^[A-Z]{3}$"
+          patternDescription="3 uppercase letters"
+          description="Optional referral code"
+        />
+
+        <TextField
+          label="Initial Deposit"
+          type="text"
+          prefix="$"
+          suffix="USD"
+          value={formData.amount}
+          onChange={(val) => updateField('amount', val)}
+          placeholder="0.00"
+          description="Minimum $10.00"
+        />
+
+        <button
+          type="button"
+          className="w-full bg-[var(--themis-primary)] text-[var(--themis-primary-foreground)] py-2 px-4 rounded-md hover:opacity-90 transition-opacity"
+        >
+          Create Account
+        </button>
+      </div>
+    );
+  },
+  parameters: {
+    docs: {
+      description: {
+        story: 'Complete registration form showcasing real-world usage of all TextField features.',
+      },
+    },
+  },
+};
+
+// Import React for validation example
+import { useState, useEffect } from 'react';