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

package/dist/components/formField/FormField.stories.js

@@ -1,97 +1,1202 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
 import { fn } from 'storybook/test';
 import { comboboxPeopleOptions } from '../../mocks/comboboxStoryOptions';
 import { FormField } from './FormField';
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+const DESCRIPTION_INTRO = [
+    'FormField is the **complete form field assembly**: it wires together a label, an optional',
+    'description, any of eight input controls, an optional helper link, and an error message — all',
+    'with the correct accessibility connections built in automatically.',
+    '',
+    'Think of it as a filing cabinet drawer with everything pre-labelled: you tell it what kind of',
+    'input you need (`inputType`), give it a label and an `id`, and it handles the `htmlFor`,',
+    '`aria-describedby`, `aria-invalid`, and `hasError` wiring for you.',
+].join('\n');
+const USAGE_GUIDANCE = [
+    '### When to use',
+    '',
+    '- Any labelled input in an Arbor form — enrolment, student records, timetabling, attendance',
+    '- When you need built-in error state management without writing the aria connections yourself',
+    '- When a field needs a helper link to external documentation or a field description below the label',
+    '',
+    '---',
+    '',
+    '### When NOT to use',
+    '',
+    '| Scenario | Use instead |',
+    '|---|---|',
+    '| Raw input without a label | Use the individual input component (`TextInput`, etc.) directly |',
+    '| Grouping several related fields (address, name) | Wrap multiple `FormField`s in a `Fieldset` |',
+    '| Non-standard input control | Compose the label + input yourself using `Label` + the input component |',
+    '',
+    '---',
+    '',
+    '### The eight input types',
+    '',
+    '| `inputType` | Renders | Typical use |',
+    '|---|---|---|',
+    '| `"text"` (default) | `TextInput` | Names, codes, short free text |',
+    '| `"textarea"` | `TextArea` | Notes, medical conditions, long free text |',
+    '| `"number"` | `NumberInput` | Class sizes, ages, counts |',
+    '| `"time"` | `TimeInput` | Registration time, period start/end |',
+    '| `"colourPicker"` | `ColourPickerDropdown` | Form group or subject colour |',
+    '| `"selectDropdown"` | `SelectDropdown` | Year group, term, single or multi select |',
+    '| `"datePicker"` | `DatePicker` | Date of birth, enrolment date |',
+    '| `"combobox"` | `Combobox` | Searchable people picker, tutor assignment |',
+].join('\n');
+const DEVELOPER_NOTES = [
+    '### Critical gotchas — read before using',
+    '',
+    '**1. Always provide `id`.** The `id` prop drives `label[htmlFor]`, and the `aria-describedby`',
+    'IDs for the description and error spans. Omit it and the a11y wiring silently breaks — no TS',
+    'error, just inaccessible markup. Treat it as required.',
+    '',
+    '**2. Never set `hasError`, `aria-invalid`, or `aria-describedby` in `inputProps`.** FormField',
+    'builds these automatically from `errorText` and `fieldDescription`. If you set them in',
+    '`inputProps`, they will be overridden — but the intent becomes confusing and may produce',
+    'conflicting values depending on spread order.',
+    '',
+    '**3. `helperLinkText` and `helperLinkUrl` must both be provided.** Providing only one renders',
+    'nothing — the component renders neither the link text nor the URL if the pair is incomplete.',
+    '',
+    '**4. `helperLink` and `fieldDescription` are mutually exclusive by design.** The component',
+    'will render both if you supply both, but the Confluence design spec prohibits this combination.',
+    'Use one or the other, never both.',
+    '',
+    '**5. `errorText` and `helperLink` CAN coexist.** Both appear inside the same `ds-form-field__message`',
+    'container: error rendered first, helper link second (stacked vertically).',
+    '',
+    '**6. `fieldDescription` persists during errors.** The description span stays visible even when',
+    '`errorText` is set. It is not hidden or replaced by the error.',
+    '',
+    '**7. Always provide `label` when using `helperLinkText`.** The helper link `aria-label` is',
+    'constructed as `"${label} helper link"`. Omit `label` and the aria-label becomes `"undefined helper link"`.',
+    '',
+    '**8. Optional fields: use the label suffix convention.** There is no `required` prop and no',
+    'asterisk pattern. Mark optional fields by appending `"(optional)"` to the label text, e.g.',
+    '`label="Middle name (optional)"`. All fields without this suffix are implicitly required.',
+    '',
+    '**9. `NumberInput` renders `type="text"` internally.** Do not pass `type` in `inputProps` when',
+    '`inputType="number"` — it is ignored and may produce confusing behaviour. The component uses',
+    '`inputMode="numeric"` for mobile keyboards.',
+    '',
+    '**10. `TimeInput` switches to Combobox mode when `options` is provided.** Pass an array of',
+    '`"HH:MM"` strings to `inputProps.options` to replace the native time picker with a searchable',
+    'dropdown of preset times.',
+    '',
+    '**11. The helper link does NOT open in a new tab.** There is no `target="_blank"` on the anchor.',
+    'This is a known limitation — Confluence guidance says it should open a new tab, but the current',
+    'implementation does not do this. Bear it in mind when linking to external documentation.',
+    '',
+    '---',
+    '',
+    '### Accessibility',
+    '',
+    '- `id` drives all ARIA wiring — treat it as required even though TypeScript allows it to be omitted',
+    '- `fieldDescription` is connected via `aria-describedby` automatically — never wire this yourself',
+    '- `errorText` sets both `hasError` and `aria-invalid` on the inner input, and a description via `aria-describedby`',
+    '- The error span contains a `triangle-alert` icon; the icon is decorative (the text carries the meaning)',
+    '- Visible labels are always required — never rely on placeholder text as a substitute for a label',
+    '- For grouped fields (address blocks, name fields) wrap in `Fieldset` with a `legend`',
+    '',
+    '---',
+    '',
+    '### TypeScript types',
+    '',
+    '```ts',
+    "import { FormField } from '@arbor-education/design-system.components';",
+    '',
+    'function MyField(props: FormField.Props) { ... }',
+    '```',
+    '',
+    '| Type | Description |',
+    '|---|---|',
+    '| `FormField.Props` | Full props interface |',
+].join('\n');
+const RELATED_COMPONENTS = [
+    '## Related components',
+    '',
+    '[TextInput](?path=/docs/components-formfield-inputs-textinput--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) · ',
+    '[SelectDropdown](?path=/docs/components-formfield-inputs-selectdropdown--docs) · ',
+    '[ColourPickerDropdown](?path=/docs/components-formfield-inputs-colourpickerdropdown--docs) · ',
+    '[DatePicker](?path=/docs/components-datepicker--docs) · ',
+    '[Combobox](?path=/docs/components-combobox--docs) · ',
+    '[Fieldset](?path=/docs/components-formfield-fieldset--docs) · ',
+    '[Label](?path=/docs/components-formfield-inputs-label--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 FormFieldDocsPage() {
+    return (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     title: 'Components/FormField',
     component: FormField,
-};
-export const Default = {
-    args: {
-        id: 'text-input',
-        label: 'Text Input',
-        inputProps: {
-            placeholder: 'Enter your text',
-            onChange: fn(),
+    tags: ['autodocs'],
+    parameters: {
+        docs: {
+            page: FormFieldDocsPage,
         },
-        helperLinkText: 'More information',
-        helperLinkUrl: 'https://www.google.com',
-        errorText: 'This is some error text',
-        fieldDescription: 'This is some descriptive text for the field',
-        inputType: 'text',
     },
     argTypes: {
-        'helperLinkText': {
+        id: {
             control: 'text',
-            description: 'Helper link text',
+            description: [
+                '**Practically required.** Drives `label[htmlFor]` and the `aria-describedby` IDs for the',
+                'field description (`{id}-description`) and error message (`{id}-error`).',
+                'Omit it and all accessibility wiring silently breaks — no TypeScript error, just broken a11y.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        'helperLinkUrl': {
+        label: {
             control: 'text',
-            description: 'Helper link URL',
+            description: [
+                'Visible label rendered above the input via the `Label` component (`ds-label`).',
+                'Short, sentence case. Use `"Field name (optional)"` suffix for optional fields — there is',
+                'no `required` prop and no asterisk convention.',
+                '**Also required when using `helperLinkText`** — the link\'s `aria-label` uses this value verbatim.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        'errorText': {
-            control: 'text',
-            description: 'Error text',
+        inputType: {
+            control: 'select',
+            options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
+            description: [
+                'Determines which input component is rendered.',
+                'Defaults to `"text"` (renders `TextInput`).',
+                '`"textarea"` → `TextArea` (auto-grows); `"number"` → `NumberInput` (spinner buttons + decimal);',
+                '`"time"` → `TimeInput` (native picker or combobox preset mode);',
+                '`"colourPicker"` → `ColourPickerDropdown` (hex colour sketch picker in a dropdown);',
+                '`"selectDropdown"` → `SelectDropdown` (single or multi select with grouping);',
+                '`"datePicker"` → `DatePicker` (calendar popover);',
+                '`"combobox"` → `Combobox` (searchable, type-ahead).',
+            ].join(' '),
+            table: {
+                type: { summary: "'text' | 'textarea' | 'number' | 'time' | 'colourPicker' | 'selectDropdown' | 'datePicker' | 'combobox'" },
+                defaultValue: { summary: "'text'" },
+            },
         },
-        'fieldDescription': {
+        fieldDescription: {
             control: 'text',
-            description: 'Field description',
+            description: [
+                'Static guidance rendered below the label, above the input.',
+                'Automatically connected to the input via `aria-describedby`.',
+                'Target 20–60 characters. Good examples: `"Shown on the parent-facing report"`,',
+                '`"Up to 30 characters"`, `"Format: DD/MM/YYYY"`.',
+                '**Stays visible when `errorText` is set** — it is not replaced by the error.',
+                '**Mutually exclusive with `helperLinkText` / `helperLinkUrl`** per Confluence design spec.',
+            ].join(' '),
+            table: {
+                type: { summary: 'ReactNode' },
+            },
         },
-        'inputType': {
-            control: 'select',
-            options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
-            description: 'Input type',
+        helperLinkText: {
+            control: 'text',
+            description: [
+                'Text for an external documentation link rendered below the input.',
+                '**Both `helperLinkText` AND `helperLinkUrl` must be provided** — supplying only one renders nothing.',
+                'Use action-led copy: `"Learn more"`, `"View guidance"`, `"See SEN framework"`.',
+                '**Mutually exclusive with `fieldDescription`** per Confluence design spec.',
+                '**Known limitation:** the link has no `target="_blank"` and does not open in a new tab.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        'inputProps.size': {
-            control: 'select',
-            options: ['M', 'S'],
-            description: 'Input size',
+        helperLinkUrl: {
+            control: 'text',
+            description: [
+                'URL for the helper link. **Must be paired with `helperLinkText`** — supplying only one renders nothing.',
+                'Typically points to Confluence guidance or external documentation.',
+                '**Known limitation:** no `target="_blank"` — does not open in a new tab.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        'inputProps.disabled': {
-            control: 'boolean',
-            description: 'Disable the input',
+        errorText: {
+            control: 'text',
+            description: [
+                'Error message rendered below the input with a `triangle-alert` icon.',
+                'Setting this automatically applies `hasError` and `aria-invalid` to the inner input,',
+                'and adds an `aria-describedby` reference to the error span.',
+                'Write errors as: what went wrong + how to fix it.',
+                'Example: `"Enter a date in DD/MM/YYYY format"`. One error per field.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
         },
-        'inputProps.placeholder': {
+        className: {
             control: 'text',
-            description: 'Input placeholder text',
+            description: [
+                'Additional CSS class(es) applied to the **root `div`** (`ds-form-field`), not the inner input.',
+                'Use for layout overrides only — do not use to style the input itself.',
+            ].join(' '),
+            table: {
+                type: { summary: 'string' },
+            },
+        },
+        inputProps: {
+            control: false,
+            description: [
+                'Props spread onto the inner input component. The shape narrows based on `inputType`.',
+                '**Do NOT set `hasError`, `aria-invalid`, or `aria-describedby` here** — FormField builds',
+                'these automatically. They are spread BEFORE `inputProps` and will be overridden.',
+                'The Controls panel cannot represent this discriminated union — configure it in the story code.',
+            ].join(' '),
+            table: {
+                type: { summary: 'TextInputProps | TextAreaProps | NumberInputProps | TimeInputProps | ColourPickerDropdownProps | SelectDropdownInputProps | DatePickerProps | ComboboxProps' },
+            },
         },
     },
 };
-// Form example with multiple inputs
-export const FormExample = {
-    render: () => (_jsxs("div", { style: { width: '400px', display: 'flex', flexDirection: 'column', gap: '1rem' }, children: [_jsx(FormField, { id: "first-name", label: "First Name", inputProps: {
-                    placeholder: 'Enter your first name',
-                } }), _jsx(FormField, { id: "last-name", label: "Last Name", inputProps: {
-                    placeholder: 'Enter your first name',
-                } }), _jsx(FormField, { id: "email", label: "Email", inputProps: {
-                    placeholder: 'Enter your email',
-                }, helperLinkText: "More information", helperLinkUrl: "https://www.google.com" }), _jsx(FormField, { id: "password", label: "Password", inputProps: {
-                    placeholder: 'Enter your first name',
-                    type: 'password',
-                } }), _jsx(FormField, { id: "message", label: "Message", inputType: "textarea", inputProps: {
-                    placeholder: 'Enter a lovely message',
-                } }), _jsx(FormField, { id: "age", label: "Age", inputType: "number", inputProps: {
-                    placeholder: 'Enter your age',
-                } }), _jsx(FormField, { id: "start-time", label: "Start time", inputType: "time", inputProps: {
-                    'aria-label': 'Start time',
-                    'defaultValue': '14:30',
-                } }), _jsx(FormField, { id: "colour-dropdown", label: "Colour", inputType: "colourPicker", inputProps: {
-                    onChange: fn(),
-                } }), _jsx(FormField, { id: "select-dropdown", label: "Select", inputType: "selectDropdown", inputProps: {
-                    options: [{ label: 'Option 1', value: 'option1' }, { label: 'Option 2', value: 'option2' }, { label: 'Option 3', value: 'option3' }],
+export default meta;
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+const withDescription = (story, description) => ({
+    ...story,
+    parameters: {
+        ...story.parameters,
+        docs: {
+            ...story.parameters?.docs,
+            description: {
+                story: description,
+            },
+        },
+    },
+});
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+export const Default = withDescription({
+    args: {
+        id: 'student-surname',
+        label: 'Surname',
+        inputType: 'text',
+        inputProps: {
+            placeholder: 'e.g. Nylund',
+        },
+    },
+    render: args => _jsx(FormField, { ...args }),
+}, 'The interactive canvas. Every top-level prop is wired to the Controls panel below. Use the controls to toggle `errorText`, add a `fieldDescription`, switch `inputType`, or add a `helperLinkUrl`. **Note:** `inputProps` cannot be controlled from the panel — it represents a discriminated union that changes shape with `inputType`. Edit the story code to configure it.');
+export const WithFieldDescription = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithFieldDescriptionExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="preferred-name"
+        label="Preferred name (optional)"
+        fieldDescription="Shown on the parent-facing report card"
+        inputProps={{ placeholder: 'e.g. Rose' }}
+      />
+      <FormField
+        id="medical-notes"
+        label="Medical conditions"
+        fieldDescription="Up to 30 characters. Visible to form tutors only."
+        inputType="textarea"
+        inputProps={{ placeholder: 'e.g. Asthma — uses inhaler before PE' }}
+      />
+    </div>
+  );
+}
+export default WithFieldDescriptionExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "preferred-name", label: "Preferred name (optional)", fieldDescription: "Shown on the parent-facing report card", inputProps: { placeholder: 'e.g. Rose' } }), _jsx(FormField, { id: "medical-notes", label: "Medical conditions", fieldDescription: "Up to 30 characters. Visible to form tutors only.", inputType: "textarea", inputProps: { placeholder: 'e.g. Asthma — uses inhaler before PE' } })] })),
+}, [
+    'A field description provides static contextual guidance below the label — it tells the user what',
+    'the field is for or what format to use. It appears above the input and stays visible even when',
+    'an error is shown.',
+    '',
+    '**Content guidance:** target 20–60 characters. Use it for format hints (`"DD/MM/YYYY"`) or',
+    'visibility notes (`"Shown on the parent-facing report"`). Do not use it for validation messages',
+    '— that is what `errorText` is for.',
+    '',
+    '**Never combine with `helperLinkText` / `helperLinkUrl`.** Per Confluence design spec these are',
+    'mutually exclusive — `fieldDescription` is for static guidance, the helper link is for external',
+    'documentation. Using both creates visual noise and breaks the design intent.',
+].join('\n'));
+export const WithHelperLink = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithHelperLinkExample() {
+  return (
+    <FormField
+      id="sen-category"
+      label="SEN category"
+      inputType="selectDropdown"
+      inputProps={{
+        options: [
+          { label: 'Cognition and learning', value: 'cognition-learning' },
+          { label: 'Communication and interaction', value: 'communication-interaction' },
+          { label: 'Social, emotional and mental health', value: 'semh' },
+          { label: 'Sensory and physical needs', value: 'sensory-physical' },
+        ],
+        placeholder: 'Select a category',
+        onSelectionChange: (values) => console.log(values),
+      }}
+      helperLinkText="View SEN framework"
+      helperLinkUrl="https://www.gov.uk/government/publications/send-code-of-practice-0-to-25"
+    />
+  );
+}
+export default WithHelperLinkExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(FormField, { id: "sen-category", label: "SEN category", inputType: "selectDropdown", inputProps: {
+                options: [
+                    { label: 'Cognition and learning', value: 'cognition-learning' },
+                    { label: 'Communication and interaction', value: 'communication-interaction' },
+                    { label: 'Social, emotional and mental health', value: 'semh' },
+                    { label: 'Sensory and physical needs', value: 'sensory-physical' },
+                ],
+                placeholder: 'Select a category',
+                onSelectionChange: fn(),
+            }, helperLinkText: "View SEN framework", helperLinkUrl: "https://www.gov.uk/government/publications/send-code-of-practice-0-to-25" }) })),
+}, [
+    'The helper link renders below the input as an action-led anchor with a `arrow-up-right` icon.',
+    'It connects to external documentation — DfE guidance, Confluence pages, or statutory frameworks.',
+    '',
+    '**Both props required:** `helperLinkText` and `helperLinkUrl` must both be set. Providing only',
+    'one renders nothing at all.',
+    '',
+    '**Known limitation:** the anchor has no `target="_blank"` — it does not open in a new tab.',
+    'Confluence design guidance says it should, but the current implementation navigates in the same',
+    'tab. Bear this in mind for links to external documentation.',
+    '',
+    '**Never combine with `fieldDescription`.** Per Confluence design spec these are mutually exclusive.',
+    'The helper link is for external documentation; `fieldDescription` is for inline static guidance.',
+    '',
+    '**Always provide `label` when using `helperLinkText`.** The link\'s `aria-label` is built as',
+    '`"${label} helper link"`. Omit `label` and screen readers announce `"undefined helper link"`.',
+].join('\n'));
+export const WithError = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithErrorExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="date-of-birth"
+        label="Date of birth"
+        inputType="datePicker"
+        inputProps={{ onChange: (date) => console.log(date) }}
+        errorText="Enter a date in DD/MM/YYYY format"
+      />
+      <FormField
+        id="class-size"
+        label="Class size"
+        inputType="number"
+        inputProps={{ min: 1, max: 35, placeholder: '30' }}
+        errorText="Class size must be between 1 and 35"
+      />
+    </div>
+  );
+}
+export default WithErrorExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "date-of-birth", label: "Date of birth", inputType: "datePicker", inputProps: { onChange: fn() }, errorText: "Enter a date in DD/MM/YYYY format" }), _jsx(FormField, { id: "class-size", label: "Class size", inputType: "number", inputProps: { min: 1, max: 35, placeholder: '30' }, errorText: "Class size must be between 1 and 35" })] })),
+}, [
+    'The error state. Setting `errorText` automatically:',
+    '',
+    '- Renders a `triangle-alert` icon followed by the error message below the input',
+    '- Applies `hasError={true}` to the inner input (which adds `ds-input--error` classes)',
+    '- Sets `aria-invalid={true}` on the inner input',
+    '- Adds the error span to the input\'s `aria-describedby`',
+    '',
+    '**Write errors as:** what went wrong + how to fix it. `"Enter a date in DD/MM/YYYY format"` is',
+    'better than `"Invalid date"`. `"Class size must be between 1 and 35"` beats `"Invalid number"`.',
+    '',
+    '**One error per field.** FormField only accepts a single `errorText` string — render one clear,',
+    'actionable message rather than a list.',
+    '',
+    '**Do NOT set `hasError` or `aria-invalid` in `inputProps`** — FormField sets these for you.',
+].join('\n'));
+export const WithErrorAndFieldDescription = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithErrorAndFieldDescriptionExample() {
+  return (
+    <FormField
+      id="student-upn"
+      label="Unique Pupil Number (UPN)"
+      fieldDescription="13-character code on previous school letter"
+      inputProps={{ placeholder: 'e.g. A123456789012' }}
+      errorText="Enter a valid 13-character UPN — check the letter from the previous school"
+    />
+  );
+}
+export default WithErrorAndFieldDescriptionExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(FormField, { id: "student-upn", label: "Unique Pupil Number (UPN)", fieldDescription: "13-character code on previous school letter", inputProps: { placeholder: 'e.g. A123456789012' }, errorText: "Enter a valid 13-character UPN \u2014 check the letter from the previous school" }) })),
+}, [
+    'Both `fieldDescription` and `errorText` can coexist. The description stays visible above the',
+    'input as usual; the error appears below. Both are connected to the input via `aria-describedby`',
+    'so screen readers announce both the description context and the error.',
+    '',
+    'This is confirmed behaviour from the source: `fieldDescription` is never hidden when an error',
+    'is active. The design rationale is that the description provides context the user still needs',
+    'to fix the error correctly.',
+    '',
+    'The `aria-describedby` value will be `"{id}-description {id}-error"` — both IDs concatenated.',
+].join('\n'));
+export const WithErrorAndHelperLink = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithErrorAndHelperLinkExample() {
+  return (
+    <FormField
+      id="attendance-code"
+      label="Attendance code"
+      inputProps={{ placeholder: 'e.g. B' }}
+      errorText="Enter a valid DfE attendance code (single letter A–Z)"
+      helperLinkText="View attendance code reference"
+      helperLinkUrl="https://www.gov.uk/government/publications/school-attendance"
+    />
+  );
+}
+export default WithErrorAndHelperLinkExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(FormField, { id: "attendance-code", label: "Attendance code", inputProps: { placeholder: 'e.g. B' }, errorText: "Enter a valid DfE attendance code (single letter A\u2013Z)", helperLinkText: "View attendance code reference", helperLinkUrl: "https://www.gov.uk/government/publications/school-attendance" }) })),
+}, [
+    '`errorText` and the helper link CAN appear together — this is the one exception where the',
+    'message container renders both elements simultaneously: the error appears first, the helper link',
+    'below it.',
+    '',
+    'This is useful when the validation failure is likely to require the user to look up a reference',
+    '— for example, an attendance code or a statutory identifier.',
+].join('\n'));
+export const Disabled = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="admissions-number"
+        label="Admissions number"
+        fieldDescription="Assigned by your local authority — cannot be edited"
+        inputProps={{ disabled: true, value: 'ADM-2024-00412', readOnly: true }}
+      />
+      <FormField
+        id="school-urn"
+        label="School URN"
+        fieldDescription="Unique Reference Number — set by Ofsted"
+        inputProps={{ disabled: true, value: '123456' }}
+      />
+    </div>
+  );
+}
+export default DisabledExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "admissions-number", label: "Admissions number", fieldDescription: "Assigned by your local authority \u2014 cannot be edited", inputProps: { disabled: true, value: 'ADM-2024-00412', readOnly: true } }), _jsx(FormField, { id: "school-urn", label: "School URN", fieldDescription: "Unique Reference Number \u2014 set by Ofsted", inputProps: { disabled: true, value: '123456' } })] })),
+}, [
+    'Pass `disabled: true` inside `inputProps` to disable the inner input. The label and description',
+    'remain visible for context; the input becomes non-interactive and muted.',
+    '',
+    '**Disabled vs read-only:** disabled fields are not focusable and are not submitted with form data.',
+    'Read-only fields (`readOnly: true`) ARE focusable and their value IS submitted. Use read-only',
+    'when the user should be able to select and copy the value (e.g. a generated code or reference).',
+    '',
+    '**Do not show errors on disabled fields** — a user cannot fix a field they cannot edit.',
+].join('\n'));
+export const TextArea = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function TextAreaExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="pastoral-notes"
+        label="Pastoral notes"
+        inputType="textarea"
+        fieldDescription="Visible to form tutor and head of year only"
+        inputProps={{
+          placeholder: 'e.g. Supporting bereavement — meeting with school counsellor Tuesdays',
+          rows: 3,
+        }}
+      />
+      <FormField
+        id="medical-conditions"
+        label="Medical conditions (optional)"
+        inputType="textarea"
+        inputProps={{
+          placeholder: 'e.g. Type 1 diabetes — checks blood sugar before lunch',
+          rows: 3,
+        }}
+      />
+    </div>
+  );
+}
+export default TextAreaExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "pastoral-notes", label: "Pastoral notes", inputType: "textarea", fieldDescription: "Visible to form tutor and head of year only", inputProps: {
+                    placeholder: 'e.g. Supporting bereavement — meeting with school counsellor Tuesdays',
+                    rows: 3,
+                } }), _jsx(FormField, { id: "medical-conditions", label: "Medical conditions (optional)", inputType: "textarea", inputProps: {
+                    placeholder: 'e.g. Type 1 diabetes — checks blood sugar before lunch',
+                    rows: 3,
+                } })] })),
+}, [
+    '`inputType="textarea"` renders a `TextArea` — a multi-line input that grows automatically as',
+    'the user types (`autoSize={true}` is the default). The initial height is controlled by the',
+    '`rows` prop in `inputProps`.',
+    '',
+    '**Use for:** pastoral notes, medical conditions, free-text feedback, long descriptions.',
+    '',
+    '**Auto-sizing:** the textarea expands vertically as the user types — it does not scroll.',
+    'To opt out, pass `autoSize: false` in `inputProps`.',
+    '',
+    '**All shared wiring still applies:** `errorText`, `fieldDescription`, and `id` work identically.',
+].join('\n'));
+export const NumberInput = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function NumberInputExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="class-capacity"
+        label="Class capacity"
+        inputType="number"
+        fieldDescription="Maximum number of students in this class"
+        inputProps={{
+          min: 1,
+          max: 35,
+          step: 1,
+          defaultValue: 30,
+        }}
+      />
+      <FormField
+        id="fsm-percentage"
+        label="FSM threshold (%)"
+        inputType="number"
+        fieldDescription="Free school meals eligibility threshold"
+        inputProps={{
+          min: 0,
+          max: 100,
+          step: 5,
+          defaultValue: 20,
+        }}
+      />
+      <FormField
+        id="absence-sessions"
+        label="Absence sessions"
+        inputType="number"
+        fieldDescription="Number of half-day sessions (no spinner)"
+        inputProps={{
+          min: 0,
+          max: 200,
+          disableSpinners: true,
+          placeholder: '0',
+        }}
+      />
+    </div>
+  );
+}
+export default NumberInputExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "class-capacity", label: "Class capacity", inputType: "number", fieldDescription: "Maximum number of students in this class", inputProps: {
+                    min: 1,
+                    max: 35,
+                    step: 1,
+                    defaultValue: 30,
+                } }), _jsx(FormField, { id: "fsm-percentage", label: "FSM threshold (%)", inputType: "number", fieldDescription: "Free school meals eligibility threshold", inputProps: {
+                    min: 0,
+                    max: 100,
+                    step: 5,
+                    defaultValue: 20,
+                } }), _jsx(FormField, { id: "absence-sessions", label: "Absence sessions", inputType: "number", fieldDescription: "Number of half-day sessions (no spinner)", inputProps: {
+                    min: 0,
+                    max: 200,
+                    disableSpinners: true,
+                    placeholder: '0',
+                } })] })),
+}, [
+    '`inputType="number"` renders a `NumberInput` — a text input (`type="text"`, `inputMode="numeric"`)',
+    'with optional ± spinner buttons and decimal-safe arithmetic via `decimal.js`.',
+    '',
+    '**Do NOT pass `type` in `inputProps`.** `NumberInput` renders as `type="text"` internally to',
+    'avoid browser number input quirks. The component handles formatting and validation itself.',
+    '',
+    '**`min` / `max` / `step`:** on blur and on spinner click, the value is clamped to the range.',
+    'Pass `step={5}` for coarse increments (e.g. FSM thresholds at 5% steps).',
+    '',
+    '**`disableSpinners={true}`:** removes the ± buttons for fields where the user should type',
+    'directly rather than increment — large session counts, reference numbers.',
+].join('\n'));
+export const TimeInput = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function TimeInputExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="registration-time"
+        label="Registration time"
+        inputType="time"
+        fieldDescription="Morning registration start time"
+        inputProps={{ defaultValue: '08:45' }}
+      />
+      <FormField
+        id="period-start"
+        label="Period start"
+        inputType="time"
+        fieldDescription="Choose from preset timetable slots"
+        inputProps={{
+          options: ['08:00', '08:45', '09:30', '10:15', '11:00', '11:45', '12:30', '13:15', '14:00', '14:45', '15:30'],
+          placeholder: 'Select a period',
+        }}
+      />
+    </div>
+  );
+}
+export default TimeInputExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "registration-time", label: "Registration time", inputType: "time", fieldDescription: "Morning registration start time", inputProps: { defaultValue: '08:45' } }), _jsx(FormField, { id: "period-start", label: "Period start", inputType: "time", fieldDescription: "Choose from preset timetable slots", inputProps: {
+                    options: ['08:00', '08:45', '09:30', '10:15', '11:00', '11:45', '12:30', '13:15', '14:00', '14:45', '15:30'],
+                    placeholder: 'Select a period',
+                } })] })),
+}, [
+    '`inputType="time"` renders a `TimeInput`, which has two modes:',
+    '',
+    '**Native mode** (no `options` prop): renders the browser\'s native `<input type="time">` with a',
+    'clock icon button. The value format is `"HH:MM"` or `"HH:MM:SS"`. Use `granularity="second"`',
+    'in `inputProps` to add seconds precision.',
+    '',
+    '**Combobox mode** (`options` array provided): replaces the native picker with a searchable',
+    'Combobox preset list — ideal for timetabling screens where slots are fixed.',
+    'Pass `options={["08:00", "08:45", ...]}` as an array of `"HH:MM"` strings.',
+    '',
+    'Use `onValueChange` in `inputProps` to receive value changes (accepts a string).',
+    'Use `onChange` if you need the native `ChangeEvent<HTMLInputElement>` interface.',
+].join('\n'));
+export const WithSelectDropdown = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithSelectDropdownExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="year-group"
+        label="Year group"
+        inputType="selectDropdown"
+        inputProps={{
+          options: [
+            { label: 'Year 7', value: 'y7' },
+            { label: 'Year 8', value: 'y8' },
+            { label: 'Year 9', value: 'y9' },
+            { label: 'Year 10', value: 'y10' },
+            { label: 'Year 11', value: 'y11' },
+          ],
+          placeholder: 'Select year group',
+          onSelectionChange: (values) => console.log(values),
+        }}
+      />
+      <FormField
+        id="subject-filter"
+        label="Subjects taught (optional)"
+        inputType="selectDropdown"
+        fieldDescription="Select all that apply"
+        inputProps={{
+          multiple: true,
+          options: [
+            { label: 'Maths', value: 'maths' },
+            { label: 'English', value: 'english' },
+            { label: 'Science', value: 'science' },
+            { label: 'History', value: 'history' },
+            { label: 'Geography', value: 'geography' },
+            { label: 'Art', value: 'art' },
+            { label: 'Music', value: 'music' },
+            { label: 'Physical Education', value: 'pe' },
+          ],
+          placeholder: 'Select subjects',
+          onSelectionChange: (values) => console.log(values),
+        }}
+      />
+    </div>
+  );
+}
+export default WithSelectDropdownExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "year-group", label: "Year group", inputType: "selectDropdown", inputProps: {
+                    options: [
+                        { label: 'Year 7', value: 'y7' },
+                        { label: 'Year 8', value: 'y8' },
+                        { label: 'Year 9', value: 'y9' },
+                        { label: 'Year 10', value: 'y10' },
+                        { label: 'Year 11', value: 'y11' },
+                    ],
+                    placeholder: 'Select year group',
                     onSelectionChange: fn(),
-                } }), _jsx(FormField, { id: "assignee", label: "Assignee", inputType: "combobox", inputProps: {
-                    options: comboboxPeopleOptions,
-                    placeholder: 'Search people...',
-                    onValueChange: fn(),
-                } }), _jsx(FormField, { id: "date-of-birth", label: "Date of Birth", inputType: "datePicker", inputProps: { onChange: fn() } })] })),
-};
-export const Combobox = {
-    render: () => (_jsx("div", { "data-surface": "base", "data-colour-mode": "light", className: "bg-surface text-on-surface-default", style: { padding: 32, maxWidth: 420 }, children: _jsx(FormField, { id: "form-field-combobox", label: "Assignee", fieldDescription: "Search and select a person.", inputType: "combobox", inputProps: {
+                } }), _jsx(FormField, { id: "subject-filter", label: "Subjects taught (optional)", inputType: "selectDropdown", fieldDescription: "Select all that apply", inputProps: {
+                    multiple: true,
+                    options: [
+                        { label: 'Maths', value: 'maths' },
+                        { label: 'English', value: 'english' },
+                        { label: 'Science', value: 'science' },
+                        { label: 'History', value: 'history' },
+                        { label: 'Geography', value: 'geography' },
+                        { label: 'Art', value: 'art' },
+                        { label: 'Music', value: 'music' },
+                        { label: 'Physical Education', value: 'pe' },
+                    ],
+                    placeholder: 'Select subjects',
+                    onSelectionChange: fn(),
+                } })] })),
+}, [
+    '`inputType="selectDropdown"` renders a `SelectDropdown` — a Dropdown-based button trigger with',
+    'a list of selectable options. Supports single select (default) and multi-select (`multiple={true}`).',
+    '',
+    '**Options shape:** each option is `{ label: string; value: string; group?: string }`. Grouped',
+    'options render a bold header row above each group.',
+    '',
+    '**Multi-select:** pass `multiple={true}` in `inputProps`. The trigger shows the count of',
+    'selected values when more than one is chosen.',
+    '',
+    '**Controlled vs uncontrolled:** pass `selectedValues` to control the selection externally;',
+    'omit it for uncontrolled (internal state). Use `initialSelectedValues` to set a default.',
+].join('\n'));
+export const WithCombobox = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithComboboxExample() {
+  const tutorOptions = [
+    { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
+    { value: 'bob', label: 'Bob Smith', iconName: 'user' },
+    { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
+    { value: 'diana', label: 'Diana Prince', iconName: 'user' },
+  ];
+
+  return (
+    <FormField
+      id="form-tutor"
+      label="Form tutor"
+      inputType="combobox"
+      fieldDescription="Assigned tutor for this form group"
+      inputProps={{
+        options: tutorOptions,
+        placeholder: 'Search by name...',
+        onValueChange: (values) => console.log(values),
+      }}
+    />
+  );
+}
+export default WithComboboxExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsx("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }, children: _jsx(FormField, { id: "form-tutor", label: "Form tutor", inputType: "combobox", fieldDescription: "Assigned tutor for this form group", inputProps: {
                 options: comboboxPeopleOptions,
-                placeholder: 'Search people...',
+                placeholder: 'Search by name...',
                 onValueChange: fn(),
             } }) })),
-};
-export default meta;
+}, [
+    '`inputType="combobox"` renders a `Combobox` — a searchable, type-ahead selector.',
+    'The user types to filter the options list; results highlight matching characters.',
+    '',
+    '**Use for:** any "select a person" scenario — form tutor assignment, cover teacher lookup,',
+    'parent/guardian search. Works with the `comboboxPeopleOptions` mock for stories.',
+    '',
+    '**`onValueChange`** in `inputProps` receives the selected value as `string[]` (Combobox is',
+    'inherently multi-value even in single-select mode — expect an array of one).',
+    '',
+    '**Options shape:** `{ value: string; label: string; iconName?: IconName; group?: string }`.',
+    'Provide `iconName="user"` for people pickers to render the person icon.',
+    '',
+    '**Note:** `fieldDescription` is shown here alongside the combobox — this is intentional.',
+    'Do not add `helperLinkText` when `fieldDescription` is already present.',
+].join('\n'));
+export const WithDatePicker = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithDatePickerExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="date-of-birth"
+        label="Date of birth"
+        inputType="datePicker"
+        fieldDescription="Format: DD/MM/YYYY"
+        inputProps={{ onChange: (date) => console.log(date) }}
+      />
+      <FormField
+        id="enrolment-date"
+        label="Enrolment date"
+        inputType="datePicker"
+        inputProps={{
+          onChange: (date) => console.log(date),
+          displayFormat: 'default',
+        }}
+      />
+    </div>
+  );
+}
+export default WithDatePickerExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "date-of-birth", label: "Date of birth", inputType: "datePicker", fieldDescription: "Format: DD/MM/YYYY", inputProps: { onChange: fn() } }), _jsx(FormField, { id: "enrolment-date", label: "Enrolment date", inputType: "datePicker", inputProps: {
+                    onChange: fn(),
+                    displayFormat: 'default',
+                } })] })),
+}, [
+    '`inputType="datePicker"` renders a `DatePicker` — a text input that opens a calendar popover',
+    'when clicked. The user can type the date directly or pick from the calendar.',
+    '',
+    '**`onChange`** in `inputProps` receives a `Date | undefined` — not a string. Format it for',
+    'display or API submission in your application layer.',
+    '',
+    '**`displayFormat`** controls how the date is shown in the text input. Defaults to `"default"`',
+    '(locale-appropriate). Check the DatePicker stories for the full format reference.',
+    '',
+    '**Portalled component:** the calendar popover is rendered via a portal. Do not wrap this story',
+    'or any component using FormField with `overflow: hidden` or `position: relative` on a tight',
+    'container — it will clip the calendar.',
+].join('\n'));
+export const OptionalAndRequiredFields = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function OptionalAndRequiredFieldsExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="student-forename"
+        label="First name"
+        inputProps={{ placeholder: 'e.g. Rose' }}
+      />
+      <FormField
+        id="student-middle-name"
+        label="Middle name (optional)"
+        inputProps={{ placeholder: 'e.g. Marie' }}
+      />
+      <FormField
+        id="student-surname"
+        label="Surname"
+        inputProps={{ placeholder: 'e.g. Nylund' }}
+      />
+      <FormField
+        id="student-preferred-name"
+        label="Preferred name (optional)"
+        fieldDescription="Used in class registers and parent communications"
+        inputProps={{ placeholder: 'e.g. Rosie' }}
+      />
+      <FormField
+        id="student-legal-name"
+        label="Legal name"
+        fieldDescription="As it appears on official documents"
+        inputProps={{ placeholder: 'e.g. Rose Marie Nylund' }}
+      />
+    </div>
+  );
+}
+export default OptionalAndRequiredFieldsExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "student-forename", label: "First name", inputProps: { placeholder: 'e.g. Rose' } }), _jsx(FormField, { id: "student-middle-name", label: "Middle name (optional)", inputProps: { placeholder: 'e.g. Marie' } }), _jsx(FormField, { id: "student-surname", label: "Surname", inputProps: { placeholder: 'e.g. Nylund' } }), _jsx(FormField, { id: "student-preferred-name", label: "Preferred name (optional)", fieldDescription: "Used in class registers and parent communications", inputProps: { placeholder: 'e.g. Rosie' } }), _jsx(FormField, { id: "student-legal-name", label: "Legal name", fieldDescription: "As it appears on official documents", inputProps: { placeholder: 'e.g. Rose Marie Nylund' } })] })),
+}, [
+    'Arbor uses the **label suffix convention** for optional fields — no asterisk, no `required` prop.',
+    'Append `"(optional)"` directly to the label text: `label="Middle name (optional)"`.',
+    '',
+    'Fields without this suffix are implicitly required. This is a deliberate Confluence design',
+    'decision: marking optional fields (the minority) is less visually noisy than marking required',
+    'fields (the majority) with an asterisk that users learn to ignore anyway.',
+    '',
+    '**Never** use a red asterisk (`*`) required indicator — this is not in the Arbor design system.',
+    '**Never** use placeholder text as a substitute for a label, even for optional fields.',
+].join('\n'));
+export const WithColourPicker = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithColourPickerExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="form-group-colour"
+        label="Form group colour"
+        inputType="colourPicker"
+        fieldDescription="Shown on the timetable and group list"
+        inputProps={{ onChange: (result) => console.log(result.hex) }}
+      />
+      <FormField
+        id="subject-colour"
+        label="Subject colour (optional)"
+        inputType="colourPicker"
+        inputProps={{
+          value: '#e63946',
+          onChange: (result) => console.log(result.hex),
+        }}
+      />
+    </div>
+  );
+}
+export default WithColourPickerExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx(FormField, { id: "form-group-colour", label: "Form group colour", inputType: "colourPicker", fieldDescription: "Shown on the timetable and group list", inputProps: { onChange: fn() } }), _jsx(FormField, { id: "subject-colour", label: "Subject colour (optional)", inputType: "colourPicker", inputProps: {
+                    value: '#e63946',
+                    onChange: fn(),
+                } })] })),
+}, [
+    '`inputType="colourPicker"` renders a `ColourPickerDropdown` — a button trigger that opens a',
+    'Sketch colour picker in a Dropdown. The selected colour is previewed in the trigger button.',
+    '',
+    '**`onChange`** in `inputProps` receives a `ColorResult` object from `@uiw/color-convert` —',
+    'use `.hex` to get the hex string: `onChange={(result) => setColour(result.hex)}`.',
+    '',
+    '**`value`** in `inputProps` accepts a hex string (e.g. `"#3cad51"`). Defaults to Arbor green',
+    '(`"#3cad51"`) if not provided.',
+    '',
+    '**Portalled component:** the colour picker popover is rendered via a portal. Do not wrap',
+    'with `overflow: hidden` — it will clip the picker.',
+].join('\n'));
+export const CompleteStudentForm = withDescription({
+    parameters: {
+        docs: {
+            source: {
+                language: 'tsx',
+                code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function CompleteStudentFormExample() {
+  const tutorOptions = [
+    { value: 'alice', label: 'Alice Johnson', iconName: 'user' },
+    { value: 'bob', label: 'Bob Smith', iconName: 'user' },
+    { value: 'charlie', label: 'Charlie Brown', iconName: 'user' },
+  ];
+
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <p style={{ margin: 0, fontWeight: 'var(--font-weight-semi-bold)', color: 'var(--color-grey-900)' }}>
+        New student record
+      </p>
+      <FormField id="student-first-name" label="First name" inputProps={{ placeholder: 'e.g. Dorothy' }} />
+      <FormField id="student-surname" label="Surname" inputProps={{ placeholder: 'e.g. Zbornak' }} />
+      <FormField
+        id="student-preferred-name"
+        label="Preferred name (optional)"
+        fieldDescription="Used in registers and parent communications"
+        inputProps={{ placeholder: 'e.g. Dot' }}
+      />
+      <FormField
+        id="student-dob"
+        label="Date of birth"
+        inputType="datePicker"
+        fieldDescription="Format: DD/MM/YYYY"
+        inputProps={{ onChange: (date) => console.log(date) }}
+      />
+      <FormField
+        id="student-year-group"
+        label="Year group"
+        inputType="selectDropdown"
+        inputProps={{
+          options: [
+            { label: 'Year 7', value: 'y7' },
+            { label: 'Year 8', value: 'y8' },
+            { label: 'Year 9', value: 'y9' },
+            { label: 'Year 10', value: 'y10' },
+            { label: 'Year 11', value: 'y11' },
+          ],
+          placeholder: 'Select year group',
+          onSelectionChange: (values) => console.log(values),
+        }}
+      />
+      <FormField
+        id="student-form-tutor"
+        label="Form tutor"
+        inputType="combobox"
+        inputProps={{
+          options: tutorOptions,
+          placeholder: 'Search by name...',
+          onValueChange: (values) => console.log(values),
+        }}
+      />
+      <FormField
+        id="student-registration-time"
+        label="Registration time"
+        inputType="time"
+        inputProps={{ defaultValue: '08:45' }}
+      />
+      <FormField
+        id="student-class-size"
+        label="Class size"
+        inputType="number"
+        inputProps={{ min: 1, max: 35, defaultValue: 30 }}
+      />
+      <FormField
+        id="student-group-colour"
+        label="Form group colour"
+        inputType="colourPicker"
+        inputProps={{ onChange: (result) => console.log(result.hex) }}
+      />
+      <FormField
+        id="student-pastoral-notes"
+        label="Pastoral notes (optional)"
+        inputType="textarea"
+        fieldDescription="Visible to form tutor and SENCO only"
+        inputProps={{
+          placeholder: 'e.g. Transitioning from primary — mild anxiety in crowded spaces',
+          rows: 3,
+        }}
+      />
+    </div>
+  );
+}
+export default CompleteStudentFormExample;
+`.trim(),
+            },
+        },
+    },
+    render: () => (_jsxs("div", { style: { maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }, children: [_jsx("p", { className: "ds-text", style: { margin: 0, fontWeight: 'var(--font-weight-semi-bold)', color: 'var(--color-grey-900)' }, children: "New student record" }), _jsx(FormField, { id: "student-first-name", label: "First name", inputProps: { placeholder: 'e.g. Dorothy' } }), _jsx(FormField, { id: "student-surname", label: "Surname", inputProps: { placeholder: 'e.g. Zbornak' } }), _jsx(FormField, { id: "student-preferred-name", label: "Preferred name (optional)", fieldDescription: "Used in registers and parent communications", inputProps: { placeholder: 'e.g. Dot' } }), _jsx(FormField, { id: "student-dob", label: "Date of birth", inputType: "datePicker", fieldDescription: "Format: DD/MM/YYYY", inputProps: { onChange: fn() } }), _jsx(FormField, { id: "student-year-group", label: "Year group", inputType: "selectDropdown", inputProps: {
+                    options: [
+                        { label: 'Year 7', value: 'y7' },
+                        { label: 'Year 8', value: 'y8' },
+                        { label: 'Year 9', value: 'y9' },
+                        { label: 'Year 10', value: 'y10' },
+                        { label: 'Year 11', value: 'y11' },
+                    ],
+                    placeholder: 'Select year group',
+                    onSelectionChange: fn(),
+                } }), _jsx(FormField, { id: "student-form-tutor", label: "Form tutor", inputType: "combobox", inputProps: {
+                    options: comboboxPeopleOptions,
+                    placeholder: 'Search by name...',
+                    onValueChange: fn(),
+                } }), _jsx(FormField, { id: "student-registration-time", label: "Registration time", inputType: "time", inputProps: { defaultValue: '08:45' } }), _jsx(FormField, { id: "student-class-size", label: "Class size", inputType: "number", inputProps: { min: 1, max: 35, defaultValue: 30 } }), _jsx(FormField, { id: "student-group-colour", label: "Form group colour", inputType: "colourPicker", inputProps: { onChange: fn() } }), _jsx(FormField, { id: "student-pastoral-notes", label: "Pastoral notes (optional)", inputType: "textarea", fieldDescription: "Visible to form tutor and SENCO only", inputProps: {
+                    placeholder: 'e.g. Transitioning from primary — mild anxiety in crowded spaces',
+                    rows: 3,
+                } })] })),
+}, [
+    'A realistic school record form using all eight `inputType` values together. This shows how',
+    'FormField composes into a real data-entry screen — consistent spacing (`var(--spacing-large)`',
+    'between fields), a shared `maxWidth` container, and school management domain content throughout.',
+    '',
+    'Notice the conventions in action:',
+    '- Implicitly required fields: no suffix (First name, Surname, Date of birth)',
+    '- Explicitly optional fields: `"(optional)"` suffix (Preferred name, Pastoral notes)',
+    '- `fieldDescription` on fields where format or visibility context helps the user',
+    '- `min` / `max` on the number input to constrain class size',
+    '- `comboboxPeopleOptions` mock for the form tutor Combobox',
+    '',
+    'This replaces the old `FormExample` story which used `"1rem"` gaps and non-school copy.',
+].join('\n'));
 //# sourceMappingURL=FormField.stories.js.map