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

package/src/components/formField/inputs/textArea/TextArea.stories.tsx

@@ -1,18 +1,766 @@
-import type { Meta } from '@storybook/react-vite';
+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 { useState } from 'react';
 import { fn } from 'storybook/test';
-
+import { FormField } from 'Components/formField/FormField';
 import { TextArea } from './TextArea';
 
-const meta: Meta<typeof TextArea> = {
+// ---------------------------------------------------------------------------
+// Component description — built as joined arrays to avoid no-useless-escape
+// on backtick code spans inside template literals.
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'The **TextArea** is the multi-line text entry control in the Arbor design system.',
+  'It wraps a native `<textarea>` element with an optional auto-grow behaviour,',
+  'an error state, and full pass-through of HTML textarea attributes.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Multi-line free text: pupil notes, incident reports, medical conditions, absence reasons, exclusion summaries',
+  '- Any field where the user needs room to write more than one sentence',
+  '- As the underlying input inside a `FormField` with `inputType="textarea"` (the recommended pattern in real forms)',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Instead of TextArea... | Use... | Why |',
+  '|---|---|---|',
+  '| Single-line short text | [`TextInput`](?path=/docs/components-formfield-inputs-textinput--docs) | Smaller footprint; correct affordance for short values |',
+  '| Numeric values | [`NumberInput`](?path=/docs/components-formfield-inputs-numberinput--docs) | Precision handling, stepper UI |',
+  '| Date selection | `DatePicker` | Calendar UI; avoids inconsistent native date picker chrome |',
+  '| Selecting from a list | `SelectDropdown` or `Combobox` | Constrained selection; better keyboard and screen reader UX |',
+  '',
+  '---',
+  '',
+  '### Design guidance',
+  '',
+  '- **Width is always 100%** — the textarea fills its container. Control width by sizing the wrapper.',
+  '- **Use `rows` to set the initial height** — a value of 3–5 suits most school management forms.',
+  '- **`autoSize` (default `true`) grows the textarea as the user types** — prefer this over a fixed height so users can see their full input without scrolling inside the box.',
+  '- **Use `FormField` in real forms** — `FormField` automatically wires `hasError`, `aria-invalid`, and `aria-describedby`.',
+  '  On a bare `TextArea`, you are responsible for those attributes yourself.',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical gotchas',
+  '',
+  '#### 1. `autoSize` mechanics',
+  'When `autoSize={true}` (the default), the component reads `scrollHeight` on every `onChange` event',
+  'and sets `height = scrollHeight + 4px` (vertical padding compensation).',
+  'The textarea still starts at the height implied by the `rows` prop — growth begins after the first keystroke.',
+  'Importantly, `autoSize` is triggered by `onChange`, which means it only fires when the user types.',
+  'Setting a large `defaultValue` at mount will NOT auto-grow; call layout imperatively if needed.',
+  '',
+  '#### 2. CSS `resize` is NOT controlled by this component',
+  'The browser default (`resize: both` or `resize: vertical` depending on browser) applies.',
+  'Consumers override it directly on the element:',
+  '',
+  '```tsx',
+  '// Prevent user resizing entirely',
+  '<TextArea style={{ resize: "none" }} />',
+  '',
+  '// Or via a CSS class you own',
+  '<TextArea className="my-fixed-textarea" />',
+  '```',
+  '',
+  '#### 3. No `forwardRef` — consumers cannot attach a ref',
+  'TextArea uses an internal `ref` for `autoSize` calculations.',
+  'It is NOT a `forwardRef` component — you cannot attach a `ref` to it from the outside.',
+  'If you need imperative focus control, wrap the TextArea and use a separate DOM query,',
+  'or request `forwardRef` support as a library enhancement.',
+  '',
+  '#### 4. `size` prop is intentionally omitted',
+  'The HTML `size` attribute is omitted from the props (the TypeScript type uses `Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "size">`).',
+  'Use `rows` to control the initial height; control width by sizing the parent wrapper.',
+  '',
+  '#### 5. `aria-invalid` is NOT automatic on bare TextArea',
+  '`hasError={true}` only adds the visual red border class (`ds-input--error`).',
+  'It carries no ARIA semantics. When using TextArea 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',
+  '<TextArea hasError />',
+  '',
+  '// GOOD — both the visual class and the ARIA attribute are set',
+  '<TextArea hasError aria-invalid="true" aria-describedby="my-field-error" />',
+  '<span id="my-field-error">Enter a valid absence reason</span>',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- **Label association** — always wire `id` on the textarea and `htmlFor` on the label.',
+  '  `FormField` does this automatically; bare TextArea 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.',
+  '- **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.',
+  '- **Character limits** — when using `maxLength`, always pair with a visible character counter.',
+  '  Screen reader users cannot see the browser-native character limit indicator.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '`TextArea` exports a namespace with the `Props` type:',
+  '',
+  '```tsx',
+  "import { TextArea } from '@arbor-education/design-system.components';",
+  '',
+  'type Props = TextArea.Props;',
+  '```',
+  '',
+  '| Type | Description |',
+  '|---|---|',
+  '| `TextArea.Props` | Full props interface — `hasError`, `autoSize`, plus all `TextareaHTMLAttributes<HTMLTextAreaElement>` (except `size`) |',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[FormField](?path=/docs/components-formfield--docs)',
+  '· [TextInput](?path=/docs/components-formfield-inputs-textinput--docs)',
+  '· [NumberInput](?path=/docs/components-formfield-inputs-numberinput--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.';
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function TextAreaDocsPage() {
+  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/TextArea',
   component: TextArea,
-};
-
-export const Default = {
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'centered',
+    docs: { page: TextAreaDocsPage },
+  },
+  argTypes: {
+    hasError: {
+      control: 'boolean',
+      description: [
+        'Applies the `ds-input--error` class, which sets a red border and error text colour.',
+        'When using TextArea inside `FormField`, this prop is set automatically when `errorText` is present',
+        '— do NOT pass it manually in `inputProps`.',
+        'When using bare TextArea, 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' },
+      },
+    },
+    autoSize: {
+      control: 'boolean',
+      description: [
+        'When `true` (the default), the textarea automatically grows vertically as the user types.',
+        'Height is recalculated on each `onChange` event: `scrollHeight + 4px` (vertical padding compensation).',
+        'Initial height is still determined by the `rows` prop.',
+        'When `false`, the textarea has a fixed height and the browser resize handle is available.',
+        'Use `false` for forms where a consistent field height is important (e.g. data tables).',
+      ].join(' '),
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+      },
+    },
+    disabled: {
+      control: 'boolean',
+      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' },
+      },
+    },
+    rows: {
+      control: 'number',
+      description: [
+        'Sets the initial visible height of the textarea as a number of text rows.',
+        'Recommended default: 3 for short notes, 5 for incident reports or medical summaries.',
+        'When `autoSize` is true, the textarea grows beyond this initial height as the user types.',
+        'When `autoSize` is false, this is the fixed height (unless the user drags the resize handle).',
+      ].join(' '),
+      table: {
+        type: { summary: 'number' },
+      },
+    },
+    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' },
+      },
+    },
+    maxLength: {
+      control: 'number',
+      description: [
+        'Maximum number of characters allowed, enforced natively by the browser.',
+        'Useful for fields with a hard character limit — short notes, reference fields.',
+        'Always pair with a visible character counter so users know how much space remains.',
+        'Screen reader users cannot see the browser-native character limit indicator.',
+      ].join(' '),
+      table: {
+        type: { summary: 'number' },
+      },
+    },
+    value: {
+      control: 'text',
+      description: [
+        'Controlled value — pair with `onChange` to manage state externally.',
+        'When using controlled mode, you must handle `onChange` otherwise the textarea will appear frozen.',
+        'For uncontrolled usage, use `defaultValue` instead.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    defaultValue: {
+      control: 'text',
+      description: [
+        'Uncontrolled initial value. The textarea manages its own state after mount.',
+        'Do not combine with `value` — use one or the other.',
+        'Note: setting a large `defaultValue` at mount will NOT trigger `autoSize`.',
+        'The textarea starts at the height set by `rows` regardless of the initial value length.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    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' },
+      },
+    },
+    onChange: {
+      description: [
+        'Change event handler. Fires on every keystroke.',
+        'Required when using controlled `value` — otherwise the textarea will not update.',
+        'Unlike `NumberInput`, this is a real native `ChangeEvent<HTMLTextAreaElement>` —',
+        'both `e.target.value` and `e.currentTarget.value` are populated.',
+      ].join(' '),
+      table: {
+        type: { summary: '(e: ChangeEvent<HTMLTextAreaElement>) => void' },
+      },
+    },
+    className: {
+      control: 'text',
+      description: [
+        'CSS class applied to the `<textarea>` element.',
+        'Use to override resize behaviour — e.g. a class with `resize: none` —',
+        'or to apply custom styles. The `ds-textarea` and `ds-input` base classes are always applied.',
+        'You can also pass `style={{ resize: "none" }}` directly as an HTML attribute.',
+      ].join(' '),
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+  },
   args: {
-    title: 'titleValue',
     onChange: fn(),
   },
-};
+} satisfies Meta<typeof TextArea>;
 
 export default meta;
+type Story = StoryObj<typeof TextArea>;
+
+// ---------------------------------------------------------------------------
+// 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 ControlledWithCharacterCountTemplate = () => {
+  const maxLength = 500;
+  const [value, setValue] = useState('');
+
+  const remaining = maxLength - value.length;
+  const isApproaching = remaining <= 100 && remaining > 0;
+  const isAtLimit = remaining <= 0;
+
+  const countColour = isAtLimit
+    ? 'var(--color-semantic-destructive-600)'
+    : isApproaching
+      ? 'var(--color-semantic-caution-600)'
+      : 'var(--color-grey-600)';
+
+  return (
+    <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+      <label htmlFor="incident-notes" style={{ color: 'var(--color-grey-600)' }}>
+        Incident report notes
+      </label>
+      <TextArea
+        id="incident-notes"
+        rows={5}
+        maxLength={maxLength}
+        placeholder="Describe the incident, including time, location, and witnesses..."
+        value={value}
+        onChange={e => setValue(e.currentTarget.value)}
+        aria-describedby="incident-notes-count"
+      />
+      <span
+        id="incident-notes-count"
+        style={{
+          fontSize: 'var(--font-size-1-11)',
+          color: countColour,
+          textAlign: 'right',
+        }}
+      >
+        {remaining}
+        {' '}
+        character
+        {remaining !== 1 ? 's' : ''}
+        {' '}
+        remaining
+      </span>
+    </div>
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      placeholder: 'Enter pupil notes here...',
+      rows: 3,
+      autoSize: true,
+      disabled: false,
+      hasError: false,
+    },
+    render: args => <TextArea {...args} />,
+  },
+  'The interactive canvas story — every prop is wired to the **Controls** panel. Use the controls to explore error state, disabled, autoSize, placeholder, rows, and other HTML textarea attributes.',
+);
+
+export const WithError: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <label htmlFor="absence-reason-error" style={{ color: 'var(--color-grey-600)' }}>
+          Absence reason
+        </label>
+        <TextArea
+          id="absence-reason-error"
+          rows={3}
+          hasError
+          aria-invalid="true"
+          aria-describedby="absence-reason-error-msg"
+          defaultValue=""
+          placeholder="Enter the reason for absence..."
+        />
+        <span
+          id="absence-reason-error-msg"
+          style={{ color: 'var(--color-semantic-destructive-600)' }}
+        >
+          An absence reason is required before this record can be saved.
+        </span>
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: [
+            "import { TextArea } from '@arbor-education/design-system.components';",
+            '',
+            'function WithErrorExample() {',
+            '  return (',
+            '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-xsmall)" }}>',
+            '      <label htmlFor="absence-reason-error" style={{ color: "var(--color-grey-600)" }}>',
+            '        Absence reason',
+            '      </label>',
+            '      <TextArea',
+            '        id="absence-reason-error"',
+            '        rows={3}',
+            '        hasError',
+            '        aria-invalid="true"',
+            '        aria-describedby="absence-reason-error-msg"',
+            '        defaultValue=""',
+            '        placeholder="Enter the reason for absence..."',
+            '      />',
+            '      <span',
+            '        id="absence-reason-error-msg"',
+            '        style={{ color: "var(--color-semantic-destructive-600)" }}',
+            '      >',
+            '        An absence reason is required before this record can be saved.',
+            '      </span>',
+            '    </div>',
+            '  );',
+            '}',
+            'export default WithErrorExample;',
+          ].join('\n'),
+        },
+      },
+    },
+  },
+  [
+    'Shows `hasError={true}` — the red border (`ds-input--error` class) combined with `aria-invalid="true"`',
+    'and `aria-describedby` pointing to the error message. On a bare TextArea,',
+    '**you must provide all three**. `hasError` alone is purely visual and has no ARIA semantics.',
+    '`FormField` handles this wiring automatically when `errorText` is present.',
+  ].join(' '),
+);
+
+export const Disabled: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <label
+          htmlFor="medical-notes-disabled"
+          style={{ color: 'var(--color-grey-400)' }}
+        >
+          Medical information (locked)
+        </label>
+        <TextArea
+          id="medical-notes-disabled"
+          rows={4}
+          disabled
+          defaultValue="Pupil has a documented nut allergy (anaphylaxis risk). EpiPen is held in the school office. All catering staff have been briefed."
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: [
+            "import { TextArea } from '@arbor-education/design-system.components';",
+            '',
+            'function DisabledExample() {',
+            '  return (',
+            '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-xsmall)" }}>',
+            '      <label',
+            '        htmlFor="medical-notes-disabled"',
+            '        style={{ color: "var(--color-grey-400)" }}',
+            '      >',
+            '        Medical information (locked)',
+            '      </label>',
+            '      <TextArea',
+            '        id="medical-notes-disabled"',
+            '        rows={4}',
+            '        disabled',
+            '        defaultValue="Pupil has a documented nut allergy (anaphylaxis risk). EpiPen is held in the school office. All catering staff have been briefed."',
+            '      />',
+            '    </div>',
+            '  );',
+            '}',
+            'export default DisabledExample;',
+          ].join('\n'),
+        },
+      },
+    },
+  },
+  [
+    '`disabled={true}` — the field is greyed out, removed from the tab order, and its value is excluded from form submission.',
+    'The label colour is shifted to `--color-grey-400` to reflect the inactive state.',
+    'Use `readOnly` instead when the value must remain accessible, copyable, or submitted with the form.',
+  ].join(' '),
+);
+
+export const FixedHeight: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <label htmlFor="exclusion-summary-fixed" style={{ color: 'var(--color-grey-600)' }}>
+          Exclusion summary
+        </label>
+        <TextArea
+          id="exclusion-summary-fixed"
+          rows={5}
+          autoSize={false}
+          style={{ resize: 'none' }}
+          placeholder="Summarise the exclusion circumstances, duration, and any meetings held with parents..."
+        />
+        <span style={{ fontSize: 'var(--font-size-1-11)', color: 'var(--color-grey-600)' }}>
+          Fixed height — scroll inside the box to read long entries.
+        </span>
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: [
+            "import { TextArea } from '@arbor-education/design-system.components';",
+            '',
+            'function FixedHeightExample() {',
+            '  return (',
+            '    <TextArea',
+            '      id="exclusion-summary"',
+            '      rows={5}',
+            '      autoSize={false}',
+            '      style={{ resize: "none" }}',
+            '      placeholder="Summarise the exclusion circumstances..."',
+            '    />',
+            '  );',
+            '}',
+            'export default FixedHeightExample;',
+          ].join('\n'),
+        },
+      },
+    },
+  },
+  [
+    '`autoSize={false}` — the textarea has a fixed height set by `rows`. The browser resize handle is hidden',
+    'via `style={{ resize: "none" }}` (CSS `resize` is not controlled by the component itself — consumers',
+    'override it directly). Use a fixed height in data table cells, compact admin forms, or anywhere',
+    'a consistent field height matters more than full content visibility.',
+  ].join(' '),
+);
+
+export const ReadOnly: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-xsmall)' }}>
+        <label htmlFor="sen-notes-readonly" style={{ color: 'var(--color-grey-600)' }}>
+          SEN support plan notes (read only)
+        </label>
+        <TextArea
+          id="sen-notes-readonly"
+          rows={4}
+          readOnly
+          defaultValue="Pupil receives 1:1 literacy support three times per week. Extra time (25%) applies in all timed assessments. Seating near the front of class is recommended. Review due: end of Spring term."
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: [
+            "import { TextArea } from '@arbor-education/design-system.components';",
+            '',
+            'function ReadOnlyExample() {',
+            '  return (',
+            '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-xsmall)" }}>',
+            '      <label htmlFor="sen-notes-readonly" style={{ color: "var(--color-grey-600)" }}>',
+            '        SEN support plan notes (read only)',
+            '      </label>',
+            '      <TextArea',
+            '        id="sen-notes-readonly"',
+            '        rows={4}',
+            '        readOnly',
+            '        defaultValue="Pupil receives 1:1 literacy support three times per week. Extra time (25%) applies in all timed assessments. Seating near the front of class is recommended. Review due: end of Spring term."',
+            '      />',
+            '    </div>',
+            '  );',
+            '}',
+            'export default ReadOnlyExample;',
+          ].join('\n'),
+        },
+      },
+    },
+  },
+  [
+    '`readOnly={true}` — the field is focusable and selectable (the user can copy the content)',
+    'but not editable. The value IS included in form submission, unlike `disabled`.',
+    'The field remains in the tab order. Use `readOnly` when displaying a value that should be',
+    'visible and copyable — SEN plans, locked incident summaries, pre-filled template text.',
+  ].join(' '),
+);
+
+export const WithFormField: Story = withDescription(
+  {
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          inputType="textarea"
+          label="Pupil notes"
+          id="pupil-notes"
+          fieldDescription="Add any pastoral or academic notes visible to form tutors."
+          inputProps={{ rows: 3, placeholder: 'Enter notes about this pupil...' }}
+        />
+        <FormField
+          inputType="textarea"
+          label="Absence reason"
+          id="absence-reason"
+          errorText="An absence reason is required before this record can be saved."
+          inputProps={{ rows: 3, placeholder: 'Enter the reason for absence...' }}
+        />
+      </div>
+    ),
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: [
+            "import { FormField } from '@arbor-education/design-system.components';",
+            '',
+            'function WithFormFieldExample() {',
+            '  return (',
+            '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-large)" }}>',
+            '      <FormField',
+            '        inputType="textarea"',
+            '        label="Pupil notes"',
+            '        id="pupil-notes"',
+            '        fieldDescription="Add any pastoral or academic notes visible to form tutors."',
+            '        inputProps={{ rows: 3, placeholder: "Enter notes about this pupil..." }}',
+            '      />',
+            '      <FormField',
+            '        inputType="textarea"',
+            '        label="Absence reason"',
+            '        id="absence-reason"',
+            '        errorText="An absence reason is required before this record can be saved."',
+            '        inputProps={{ rows: 3, placeholder: "Enter the reason for absence..." }}',
+            '      />',
+            '    </div>',
+            '  );',
+            '}',
+            'export default WithFormFieldExample;',
+          ].join('\n'),
+        },
+      },
+    },
+  },
+  [
+    '**Always use `FormField` in real forms.** `FormField` with `inputType="textarea"` wraps TextArea 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.',
+    'The first example shows `fieldDescription`, which renders helper text below the label.',
+  ].join(' '),
+);
+
+export const ControlledWithCharacterCount: Story = withDescription(
+  {
+    render: () => <ControlledWithCharacterCountTemplate />,
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: [
+            "import { useState } from 'react';",
+            "import { TextArea } from '@arbor-education/design-system.components';",
+            '',
+            'function IncidentNotesField() {',
+            '  const maxLength = 500;',
+            '  const [value, setValue] = useState("");',
+            '',
+            '  const remaining = maxLength - value.length;',
+            '  const isApproaching = remaining <= 100 && remaining > 0;',
+            '  const isAtLimit = remaining <= 0;',
+            '',
+            '  const countColour = isAtLimit',
+            '    ? "var(--color-semantic-destructive-600)"',
+            '    : isApproaching',
+            '      ? "var(--color-semantic-caution-600)"',
+            '      : "var(--color-grey-600)";',
+            '',
+            '  return (',
+            '    <div style={{ display: "flex", flexDirection: "column", gap: "var(--spacing-xsmall)" }}>',
+            '      <label htmlFor="incident-notes">Incident report notes</label>',
+            '      <TextArea',
+            '        id="incident-notes"',
+            '        rows={5}',
+            '        maxLength={maxLength}',
+            '        placeholder="Describe the incident..."',
+            '        value={value}',
+            '        onChange={(e) => setValue(e.currentTarget.value)}',
+            '        aria-describedby="incident-notes-count"',
+            '      />',
+            '      <span',
+            '        id="incident-notes-count"',
+            '        style={{',
+            '          fontSize: "var(--font-size-1-11)",',
+            '          color: countColour,',
+            '          textAlign: "right",',
+            '        }}',
+            '      >',
+            '        {remaining} character{remaining !== 1 ? "s" : ""} remaining',
+            '      </span>',
+            '    </div>',
+            '  );',
+            '}',
+            'export default IncidentNotesField;',
+          ].join('\n'),
+        },
+      },
+    },
+  },
+  [
+    'A fully controlled textarea with a live character counter.',
+    '`value` and `onChange` manage state externally (note: use `e.currentTarget.value` — it is always populated).',
+    'The counter colour progresses through three states using design tokens:',
+    '`--color-grey-600` (neutral) → `--color-semantic-caution-600` (amber, within 100 of limit) → `--color-semantic-destructive-600` (red, at limit).',
+    '`aria-describedby` wires the counter to the textarea so screen readers announce the remaining count.',
+    'The browser-enforced `maxLength` silently truncates beyond the limit — always pair it with a visible counter.',
+  ].join(' '),
+);