@arbor-education/design-system.components 0.13.0 → 0.13.1

package/src/components/formField/inputs/text/TextInput.stories.tsx

@@ -1,42 +1,802 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { useRef, useState } from 'react';
 import { fn } from 'storybook/test';
-
+import { FormField } from '../../FormField';
 import { TextInput } from './TextInput';
 
+// ---------------------------------------------------------------------------
+// Component description — built as joined arrays to avoid no-useless-escape
+// on backtick code spans inside template literals.
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'The **TextInput** is the single-line text entry control in the Arbor design system.',
+  'It wraps a native `<input>` element with `forwardRef` support, two size variants,',
+  'an error state, and full pass-through of HTML input attributes.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Free-form single-line text: student names, year group labels, search queries, notes',
+  '- Any field where the valid input is a short string the user types directly',
+  '- As the underlying input inside a `FormField` with `inputType="text"` (the recommended pattern in real forms)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Instead of TextInput... | Use... | Why |',
+  '|---|---|---|',
+  '| Multi-line text | [`TextArea`](?path=/docs/components-formfield-inputs-textarea--docs) | Expands vertically; better UX for long content |',
+  '| Numeric values | [`NumberInput`](?path=/docs/components-formfield-inputs-numeric--docs) | Precision handling, stepper UI, better browser chrome |',
+  '| Time values | [`TimeInput`](?path=/docs/components-formfield-inputs-timeinput--docs) | Granularity controls, clock UI, better validation |',
+  '| Date selection | `DatePicker` | Calendar UI; avoids inconsistent native date picker chrome |',
+  '| Search / filter | [`SearchBar`](?path=/docs/components-searchbar--docs) | Search semantics, clear button, correct ARIA role |',
+  '| Selecting from a list | `SelectDropdown` or `Combobox` | Constrained selection; better keyboard and screen reader UX |',
+  '| Inline editable text | [`EditableText`](?path=/docs/components-editabletext--docs) | Uses TextInput internally; adds toggle-to-edit affordance |',
+  '',
+  '---',
+  '',
+  '### Design guidance',
+  '',
+  '- **Width is always 100%** — the input always fills its container. Control width by sizing the wrapper, not the input.',
+  '- **Stack sizes vertically** when comparing M and S — the 0.25rem height difference is subtle and easier to perceive when stacked.',
+  '- **Use FormField in real forms** — `FormField` automatically wires `hasError`, `aria-invalid`, and `aria-describedby`.',
+  '  On a bare `TextInput`, you are responsible for those attributes yourself.',
+  '- **hasError + disabled is an anti-pattern** — a user cannot correct an error on a field they cannot edit.',
+  '  Never show this combination.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical gotchas',
+  '',
+  '#### 1. `aria-invalid` is NOT automatic on bare TextInput',
+  '`hasError={true}` only adds the visual red border class (`ds-input--error`).',
+  'It carries no ARIA semantics. When using TextInput outside FormField,',
+  'you must also pass `aria-invalid="true"` so assistive technologies announce the error state.',
+  'FormField handles this automatically when `errorText` is present.',
+  '',
+  '```tsx',
+  '// BAD — visually red, but screen reader does not know there is an error',
+  '<TextInput hasError />',
+  '',
+  '// GOOD — both the visual class and the ARIA attribute are set',
+  '<TextInput hasError aria-invalid="true" aria-describedby="my-field-error" />',
+  '<span id="my-field-error">Enter a valid email address</span>',
+  '```',
+  '',
+  '#### 2. `id` is required for label association',
+  'Without an `id`, a `<label>` element cannot use `htmlFor` to associate with the input.',
+  'Outside FormField, wiring `id` and `htmlFor` is your responsibility.',
+  '`FormField` passes `id` through automatically.',
+  '',
+  '#### 3. `type="number"` and `type="time"` — use purpose-built inputs instead',
+  'TextInput passes `type` through to the native `<input>`, but `NumberInput` and `TimeInput`',
+  'provide better experiences: precision handling, stepper UI, granularity controls.',
+  'Only use `type="number"` on bare TextInput as a last resort.',
+  '',
+  '#### 4. Width is always 100%',
+  'The component always fills its container. Size the wrapper, not the input.',
+  'Never set a `width` or `max-width` directly on the TextInput element.',
+  '',
+  '#### 5. `hasError + disabled` is an anti-pattern',
+  'Visually ambiguous and semantically incorrect — a user cannot correct an error on a field',
+  'they cannot edit. Do not combine these two props.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **Label association** — always wire `id` on the input and `htmlFor` on the label.',
+  '  `FormField` does this automatically; bare TextInput consumers must do it manually.',
+  '- **Error state** — pair `hasError={true}` with `aria-invalid="true"` and',
+  '  `aria-describedby` pointing to the error message element.',
+  '  `FormField` handles all of this automatically when `errorText` is present.',
+  '- **Description text** — use `aria-describedby` pointing to any helper text element.',
+  '  `FormField` wires this via `${id}-description` automatically.',
+  '- **disabled vs readOnly** — `disabled` removes the field from tab order entirely.',
+  '  Use `readOnly` instead when the value must remain accessible and copyable,',
+  '  or when a screen reader user needs to reach the field. readOnly fields ARE submitted',
+  '  in forms; disabled fields are NOT.',
+  '- **Focus ring** — 3px outline using `--focus-border` and `--color-brand-500`.',
+  '  Do not suppress focus rings — they are the primary keyboard navigation cue.',
+  '- **Placeholder is not a label** — never use placeholder as the only visible label.',
+  '  It disappears on input and has poor colour contrast by default.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { TextInput } from '@arbor-education/design-system.components';",
+  '',
+  'function MyField(props: TextInput.Props) { ... }',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `TextInput.Props` | Full props interface — `size`, `hasError`, plus all `InputHTMLAttributes<HTMLInputElement>` (minus the HTML `size` attribute) |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[FormField](?path=/docs/components-formfield--docs)',
+  '· [TextArea](?path=/docs/components-formfield-inputs-textarea--docs)',
+  '· [NumberInput](?path=/docs/components-formfield-inputs-numeric--docs)',
+  '· [TimeInput](?path=/docs/components-formfield-inputs-timeinput--docs)',
+  '· [SearchBar](?path=/docs/components-searchbar--docs)',
+  '· [EditableText](?path=/docs/components-editabletext--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
+
+function TextInputDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
 const meta = {
   title: 'Components/FormField/Inputs/TextInput',
   component: TextInput,
   parameters: {
     layout: 'centered',
+    docs: {
+      page: TextInputDocsPage,
+    },
   },
   tags: ['autodocs'],
   args: {
     onChange: fn(),
+    onBlur: fn(),
   },
   argTypes: {
-    size: {
+    'size': {
       control: 'select',
       options: ['M', 'S'],
-      description: 'Input size',
+      description: [
+        'Controls the height of the input via the `ds-input--M` / `ds-input--S` modifier class.',
+        '`M` resolves to `--form-field-text-medium-height` (2.25rem / 36px) — the default for most form contexts.',
+        '`S` resolves to `--form-field-text-small-height` (2rem / 32px) — use in dense toolbars or compact table filters.',
+        'Note: the HTML `size` attribute is intentionally omitted from this component.',
+        'Width is always 100% of the parent container regardless of this prop.',
+      ].join(' '),
+      table: {
+        type: { summary: "'M' | 'S'" },
+        defaultValue: { summary: "'M'" },
+      },
+    },
+    'hasError': {
+      control: 'boolean',
+      description: [
+        'Applies the `ds-input--error` class, which sets a red border.',
+        'When using TextInput inside `FormField`, this prop is set automatically when `errorText` is present',
+        '— do NOT pass it manually in `inputProps`.',
+        'When using bare TextInput, also pass `aria-invalid="true"` — `hasError` is purely visual',
+        'and carries no ARIA semantics on its own.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
     },
-    disabled: {
+    'disabled': {
       control: 'boolean',
-      description: 'Disable the input',
+      description: [
+        'Native HTML disabled attribute. Removes the field from tab order entirely.',
+        'Prevents all interaction and excludes the value from form submission.',
+        'Use `readOnly` instead when the value must remain accessible, copyable, or submitted.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'placeholder': {
+      control: 'text',
+      description: [
+        'Hint text displayed when the field is empty.',
+        'Never use placeholder as the only visible label — it disappears on input',
+        'and has poor colour contrast by default. Always pair with a visible `<label>` or `aria-label`.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
-    placeholder: {
+    'type': {
       control: 'text',
-      description: 'Input placeholder text',
+      description: [
+        'HTML input type attribute, passed through to the native `<input>` element.',
+        'Valid values for single-line text scenarios: `"text"` (default), `"email"`, `"password"`,',
+        '`"tel"`, `"url"`, `"search"`.',
+        'Avoid `"number"` and `"time"` — use `NumberInput` and `TimeInput` instead for better UX.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "'text'" },
+      },
+    },
+    'readOnly': {
+      control: 'boolean',
+      description: [
+        'Makes the field focusable and selectable but not editable.',
+        'The value IS included in form submission (unlike `disabled`).',
+        'The field remains in tab order — use this instead of `disabled` when the value',
+        'must be accessible, readable, or copyable by the user.',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+      },
+    },
+    'value': {
+      control: 'text',
+      description: [
+        'Controlled value — pair with `onChange` to manage state externally.',
+        'When using controlled mode, you must handle `onChange` otherwise the input will appear frozen.',
+        'For uncontrolled usage, use `defaultValue` instead.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'onChange': {
+      description: [
+        'Change event handler. Fires on every keystroke.',
+        'Required when using controlled `value` — otherwise the input will not update.',
+      ].join(' '),
+      table: {
+        type: { summary: 'ChangeEventHandler<HTMLInputElement>' },
+      },
+    },
+    'onBlur': {
+      description: [
+        'Blur event handler. Fires when the field loses focus.',
+        'The canonical trigger for field-level validation — check the value here and set error state if invalid.',
+      ].join(' '),
+      table: {
+        type: { summary: 'FocusEventHandler<HTMLInputElement>' },
+      },
+    },
+    'maxLength': {
+      control: 'number',
+      description: [
+        'Maximum number of characters allowed, enforced natively by the browser.',
+        'Useful for fields with a hard character limit — student reference numbers, short codes.',
+        'Consider pairing with a visible character count for longer limits.',
+      ].join(' '),
+      table: {
+        type: { summary: 'number' },
+      },
+    },
+    'id': {
+      control: 'text',
+      description: [
+        'HTML `id` attribute — required for label association via `htmlFor` when used outside `FormField`.',
+        '`FormField` passes `id` through automatically. On a bare TextInput, always set this',
+        'when a visible label is present so screen readers can associate the label with the field.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'aria-label': {
+      control: 'text',
+      description: [
+        'Accessible label for contexts where a visible label is not possible',
+        '(e.g. an inline filter input in a data grid header).',
+        'If a visible label exists, prefer `id` + `htmlFor` association instead.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
     },
   },
 } satisfies Meta<typeof TextInput>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof TextInput>;
 
-// Default input
-export const Default: Story = {
-  args: {
-    placeholder: 'Enter text...',
-    size: 'M',
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
   },
+});
+
+// ---------------------------------------------------------------------------
+// Stateful template components
+// Named components avoid hooks-in-callbacks lint issues (react-hooks plugin
+// is NOT configured in this project — do not add eslint-disable comments).
+// ---------------------------------------------------------------------------
+
+const ControlledWithValidationTemplate = () => {
+  const [value, setValue] = useState('');
+  const [hasError, setHasError] = useState(false);
+
+  const handleBlur = () => {
+    setHasError(value.length > 0 && !value.includes('@'));
+  };
+
+  return (
+    <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <label htmlFor="parent-email-controlled" className="ds-text">
+        Parent email address
+      </label>
+      <TextInput
+        id="parent-email-controlled"
+        type="email"
+        placeholder="jane.doe@example.com"
+        value={value}
+        hasError={hasError}
+        aria-invalid={hasError}
+        aria-describedby={hasError ? 'parent-email-error' : undefined}
+        onChange={(e) => {
+          setValue(e.target.value);
+          if (hasError && e.target.value.includes('@')) {
+            setHasError(false);
+          }
+        }}
+        onBlur={handleBlur}
+      />
+      {hasError && (
+        <span id="parent-email-error" className="ds-text" style={{ color: 'var(--color-semantic-destructive-600)' }}>
+          Enter a valid email address
+        </span>
+      )}
+      {!hasError && value.includes('@') && (
+        <span className="ds-text" style={{ color: 'var(--color-semantic-success-600)' }}>
+          Email looks valid
+        </span>
+      )}
+    </div>
+  );
 };
+
+const WithForwardRefTemplate = () => {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p className="ds-text" style={{ margin: 0, color: 'var(--color-grey-600)' }}>
+        Click the button below to programmatically focus the text input.
+      </p>
+      <TextInput
+        ref={inputRef}
+        id="student-name-ref"
+        placeholder="Enter student full name"
+        aria-label="Student full name"
+      />
+      <button
+        type="button"
+        className="ds-button ds-button--secondary ds-button--M"
+        onClick={() => inputRef.current?.focus()}
+      >
+        Focus input
+      </button>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      size: 'M',
+      placeholder: 'Enter student full name',
+      disabled: false,
+      hasError: false,
+    },
+    render: args => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <TextInput {...args} />
+      </div>
+    ),
+  },
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore sizes, error state, disabled, placeholder, and other HTML input attributes.',
+);
+
+export const Sizes: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { TextInput } from '@arbor-education/design-system.components';
+
+function SizesExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="size-m">Medium (M) — 2.25rem</label>
+        <TextInput id="size-m" size="M" placeholder="Year group label or student name" />
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="size-s">Small (S) — 2rem</label>
+        <TextInput id="size-s" size="S" placeholder="Year group label or student name" />
+      </div>
+    </div>
+  );
+}
+export default SizesExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="size-m" className="ds-text">
+            Medium (M) — 2.25rem via --form-field-text-medium-height
+          </label>
+          <TextInput
+            id="size-m"
+            size="M"
+            placeholder="Year group label or student name"
+          />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="size-s" className="ds-text">
+            Small (S) — 2rem via --form-field-text-small-height
+          </label>
+          <TextInput
+            id="size-s"
+            size="S"
+            placeholder="Year group label or student name"
+          />
+        </div>
+      </div>
+    ),
+  },
+  'Both sizes stacked for comparison. `M` is the default for standard form layouts. `S` is for dense toolbars or compact table filters where the medium height would feel too tall. Heights are entirely token-driven — never hardcode a height on a TextInput wrapper.',
+);
+
+export const States: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { TextInput } from '@arbor-education/design-system.components';
+
+function StatesExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      {/* Default — empty */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="state-default">Default — empty</label>
+        <TextInput id="state-default" placeholder="Enter student full name" />
+      </div>
+      {/* Error — always pair hasError with aria-invalid + aria-describedby on bare TextInput */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="state-error">Error — invalid input</label>
+        <TextInput
+          id="state-error"
+          hasError
+          aria-invalid="true"
+          aria-describedby="state-error-msg"
+          defaultValue="not-an-email"
+          type="email"
+        />
+        <span id="state-error-msg" style={{ color: 'var(--color-semantic-destructive-600)' }}>
+          Enter a valid email address
+        </span>
+      </div>
+      {/* Disabled */}
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="state-disabled">Disabled — not interactive</label>
+        <TextInput id="state-disabled" disabled placeholder="Field is disabled" />
+      </div>
+    </div>
+  );
+}
+export default StatesExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="state-default" className="ds-text">Default — empty</label>
+          <TextInput id="state-default" placeholder="Enter student full name" />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="state-filled" className="ds-text">Filled — value present</label>
+          <TextInput id="state-filled" defaultValue="Amara Osei-Bonsu" />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="state-error" className="ds-text">Error — invalid input</label>
+          <TextInput
+            id="state-error"
+            hasError
+            aria-invalid="true"
+            aria-describedby="state-error-msg"
+            defaultValue="not-an-email"
+            type="email"
+          />
+          <span id="state-error-msg" className="ds-text" style={{ color: 'var(--color-semantic-destructive-600)' }}>
+            Enter a valid email address
+          </span>
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="state-disabled" className="ds-text" style={{ color: 'var(--color-grey-400)' }}>
+            Disabled — not interactive
+          </label>
+          <TextInput
+            id="state-disabled"
+            disabled
+            placeholder="Field is disabled"
+          />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="state-readonly" className="ds-text">Read only — value visible, not editable</label>
+          <TextInput
+            id="state-readonly"
+            readOnly
+            defaultValue="Year 9 — Elm House"
+          />
+        </div>
+      </div>
+    ),
+  },
+  'All five states in a single view: default (empty), filled (value present), error (with `hasError` + `aria-invalid` + an error message), disabled (removed from tab order; value not submitted), and readOnly (focusable, selectable, submittable — but not editable). Note: the error state on a bare TextInput always requires `aria-invalid="true"` set manually — `FormField` handles this automatically.',
+);
+
+export const WithFormField: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithFormFieldExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        inputType="text"
+        label="Student name"
+        id="student-name"
+        inputProps={{ placeholder: 'Enter student full name' }}
+      />
+      <FormField
+        inputType="text"
+        label="Parent email"
+        id="parent-email"
+        errorText="Enter a valid email address"
+        inputProps={{ placeholder: 'jane.doe@example.com', type: 'email' }}
+      />
+    </div>
+  );
+}
+export default WithFormFieldExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          inputType="text"
+          label="Student name"
+          id="student-name"
+          inputProps={{ placeholder: 'Enter student full name' }}
+        />
+        <FormField
+          inputType="text"
+          label="Parent email"
+          id="parent-email"
+          errorText="Enter a valid email address"
+          inputProps={{ placeholder: 'jane.doe@example.com', type: 'email' }}
+        />
+      </div>
+    ),
+  },
+  [
+    '**Always use `FormField` in real forms.** `FormField` with `inputType="text"` wraps TextInput and',
+    'automatically wires `hasError`, `aria-invalid`, `aria-describedby`, and the label `htmlFor` association.',
+    'The second example shows how `errorText` automatically sets the error state — do NOT pass',
+    '`hasError` or `aria-invalid` manually in `inputProps` when using FormField.',
+  ].join(' '),
+);
+
+export const InputTypes: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { TextInput } from '@arbor-education/design-system.components';
+
+function InputTypesExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="type-text">type="text" — Student name</label>
+        <TextInput id="type-text" type="text" placeholder="Amara Osei-Bonsu" />
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="type-email">type="email" — Parent email</label>
+        <TextInput id="type-email" type="email" placeholder="jane.doe@example.com" />
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="type-password">type="password" — Set password</label>
+        <TextInput id="type-password" type="password" placeholder="Min. 8 characters" />
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="type-tel">type="tel" — Parent phone number</label>
+        <TextInput id="type-tel" type="tel" placeholder="07700 900 123" />
+      </div>
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <label htmlFor="type-url">type="url" — School website</label>
+        <TextInput id="type-url" type="url" placeholder="https://example-school.ac.uk" />
+      </div>
+    </div>
+  );
+}
+export default InputTypesExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="type-text" className="ds-text">type="text" — Student name</label>
+          <TextInput id="type-text" type="text" placeholder="Amara Osei-Bonsu" />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="type-email" className="ds-text">type="email" — Parent email</label>
+          <TextInput id="type-email" type="email" placeholder="jane.doe@example.com" />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="type-password" className="ds-text">type="password" — Set password</label>
+          <TextInput id="type-password" type="password" placeholder="Min. 8 characters" />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="type-tel" className="ds-text">type="tel" — Parent phone number</label>
+          <TextInput id="type-tel" type="tel" placeholder="07700 900 123" />
+        </div>
+        <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+          <label htmlFor="type-url" className="ds-text">type="url" — School website</label>
+          <TextInput id="type-url" type="url" placeholder="https://example-school.ac.uk" />
+        </div>
+      </div>
+    ),
+  },
+  'TextInput passes `type` directly to the native `<input>`. The visual appearance is identical across all types — the difference is in browser behaviour: `email` validates address format, `password` masks characters, `tel` opens a numeric keyboard on mobile, `url` validates URL format. Avoid `type="number"` and `type="time"` — use `NumberInput` and `TimeInput` for those.',
+);
+
+export const ControlledWithValidation: Story = withDescription(
+  {
+    render: () => <ControlledWithValidationTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { TextInput } from '@arbor-education/design-system.components';
+
+function EmailValidationExample() {
+  const [value, setValue] = useState('');
+  const [hasError, setHasError] = useState(false);
+
+  const handleBlur = () => {
+    setHasError(value.length > 0 && !value.includes('@'));
+  };
+
+  return (
+    <div>
+      <label htmlFor="parent-email">Parent email address</label>
+      <TextInput
+        id="parent-email"
+        type="email"
+        placeholder="jane.doe@example.com"
+        value={value}
+        hasError={hasError}
+        aria-invalid={hasError}
+        aria-describedby={hasError ? 'parent-email-error' : undefined}
+        onChange={(e) => {
+          setValue(e.target.value);
+          if (hasError && e.target.value.includes('@')) setHasError(false);
+        }}
+        onBlur={handleBlur}
+      />
+      {hasError && (
+        <span id="parent-email-error">Enter a valid email address</span>
+      )}
+    </div>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+  },
+  [
+    'A fully controlled email field with validation-on-blur. State is managed externally:',
+    '`value` and `onChange` track the input; `onBlur` checks for `"@"` and sets `hasError`.',
+    'When `hasError` is true, the story also sets `aria-invalid="true"` and',
+    '`aria-describedby` pointing to the error message span — this is the correct bare-TextInput',
+    'pattern (FormField handles this wiring automatically).',
+    'The error clears as soon as the user types an `"@"` character, giving immediate positive feedback.',
+  ].join(' '),
+);
+
+export const WithForwardRef: Story = withDescription(
+  {
+    render: () => <WithForwardRefTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useRef } from 'react';
+import { TextInput } from '@arbor-education/design-system.components';
+
+function FocusExample() {
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  return (
+    <div>
+      <TextInput
+        ref={inputRef}
+        id="student-name"
+        placeholder="Enter student full name"
+        aria-label="Student full name"
+      />
+      <button type="button" onClick={() => inputRef.current?.focus()}>
+        Focus input
+      </button>
+    </div>
+  );
+}
+`.trim(),
+        },
+      },
+    },
+  },
+  '`TextInput` uses `forwardRef` — it exposes the underlying `<input>` DOM node via `ref`. This story demonstrates programmatic focus: clicking the button calls `inputRef.current?.focus()`. Common real-world uses: restoring focus after an inline edit is saved, advancing focus in a multi-step form, or auto-focusing a search field when a panel opens.',
+);