@arbor-education/design-system.components 3.0.2 → 3.2.0

package/src/components/formField/FormField.stories.tsx

@@ -18,7 +18,7 @@ import { FormField } from './FormField.js';
 
 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',
+  'description, any of thirteen 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',
@@ -45,7 +45,7 @@ const USAGE_GUIDANCE = [
   '',
   '---',
   '',
-  '### The eight input types',
+  '### The thirteen input types',
   '',
   '| `inputType` | Renders | Typical use |',
   '|---|---|---|',
@@ -56,7 +56,12 @@ const USAGE_GUIDANCE = [
   '| `"colourPicker"` | `ColourPickerDropdown` | Form group or subject colour |',
   '| `"selectDropdown"` | `SelectDropdown` | Year group, term, single or multi select |',
   '| `"datePicker"` | `DatePicker` | Date of birth, enrolment date |',
+  '| `"dateTimePicker"` | `DateTimePicker` | Event date and time together |',
   '| `"combobox"` | `Combobox` | Searchable people picker, tutor assignment |',
+  '| `"checkbox"` | `CheckboxInput` | Single opt-in, consent, acknowledgement |',
+  '| `"checkboxGroup"` | `CheckboxGroup` | Several independent selections (support needs, alert recipients) |',
+  '| `"toggle"` | `Toggle` | Instant on/off settings embedded in a form |',
+  '| `"radio"` | `RadioButtonGroup` | One choice from a short, mutually-exclusive list |',
 ].join('\n');
 
 const DEVELOPER_NOTES = [
@@ -103,6 +108,25 @@ const DEVELOPER_NOTES = [
   '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.',
   '',
+  '**12. `"checkbox"`, `"checkboxGroup"`, `"toggle"`, and `"radio"` all require `inputProps`.** Every',
+  'other `inputType` has optional `inputProps`; these four do not — the union marks them as required',
+  'because each underlying component needs at least `checked`/`checkedValue` and an `onChange`',
+  '(or `onCheckedChange`) to be usable at all.',
+  '',
+  '**13. `"checkbox"` and `"checkboxGroup"` name themselves via `inputProps`, not the top-level',
+  '`label`.** `CheckboxInput` renders its own inline `label` beside the box; `CheckboxGroup` renders',
+  'a `<legend>` via `inputProps.legend`. Providing FormField\'s top-level `label` as well produces a',
+  'second, redundant heading — pick one.',
+  '',
+  '**14. `"toggle"` is the one case where the top-level `label` prop is doing real work.** Standalone',
+  '`Toggle` has no visible label and needs one hand-rolled; inside FormField, the top-level `label`',
+  'renders the `<Label htmlFor={id}>` for you, so `Toggle` gets a proper accessible label for free.',
+  '',
+  '**15. `"radio"` matches `checkedValue` against `option.value`, not `option.id`.** `id` only',
+  'supplies the React key. Also note `RadioButtonGroup` is controlled from one `checkedValue` +',
+  '`onChange` at the group level, unlike `CheckboxGroup` where every option carries its own',
+  '`checked` + `onChange`.',
+  '',
   '---',
   '',
   '### Accessibility',
@@ -141,7 +165,10 @@ const RELATED_COMPONENTS = [
   '[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)',
+  '[Label](?path=/docs/components-formfield-inputs-label--docs) · ',
+  '[CheckboxInput](?path=/docs/components-formfield-inputs-checkbox--docs) · ',
+  '[RadioButtonInput](?path=/docs/components-formfield-inputs-radiobutton--docs) · ',
+  '[Toggle](?path=/docs/components-toggle--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.';
@@ -206,7 +233,7 @@ const meta = {
     },
     inputType: {
       control: 'select',
-      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox'],
+      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox', 'checkbox', 'checkboxGroup', 'toggle', 'radio'],
       description: [
         'Determines which input component is rendered.',
         'Defaults to `"text"` (renders `TextInput`).',
@@ -215,10 +242,15 @@ const meta = {
         '`"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).',
+        '`"combobox"` → `Combobox` (searchable, type-ahead);',
+        '`"checkbox"` → `CheckboxInput` (single opt-in/consent);',
+        '`"checkboxGroup"` → `CheckboxGroup` (several independent selections);',
+        '`"toggle"` → `Toggle` (instant on/off switch);',
+        '`"radio"` → `RadioButtonGroup` (one choice from a short list).',
+        'The last four require `inputProps` — see the developer notes.',
       ].join(' '),
       table: {
-        type: { summary: "'text' | 'textarea' | 'number' | 'time' | 'colourPicker' | 'selectDropdown' | 'datePicker' | 'combobox'" },
+        type: { summary: "'text' | 'textarea' | 'number' | 'time' | 'colourPicker' | 'selectDropdown' | 'datePicker' | 'combobox' | 'checkbox' | 'checkboxGroup' | 'toggle' | 'radio'" },
         defaultValue: { summary: "'text'" },
       },
     },
@@ -290,9 +322,10 @@ const meta = {
         '**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.',
+        '**Required, not optional, for `"checkbox"`, `"checkboxGroup"`, `"toggle"`, and `"radio"`.**',
       ].join(' '),
       table: {
-        type: { summary: 'TextInputProps | TextAreaProps | NumberInputProps | TimeInputProps | ColourPickerDropdownProps | SelectDropdownInputProps | DatePickerProps | ComboboxProps' },
+        type: { summary: 'TextInputProps | TextAreaProps | NumberInputProps | TimeInputProps | ColourPickerDropdownProps | SelectDropdownInputProps | DatePickerProps | DateTimePickerProps | ComboboxProps | CheckboxInputProps | CheckboxGroupProps | Toggle.Props | RadioButtonGroupProps' },
       },
     },
   },
@@ -1596,3 +1629,361 @@ export default CompleteStudentFormExample;
     'This replaces the old `FormExample` story which used `"1rem"` gaps and non-school copy.',
   ].join('\n'),
 );
+
+export const WithCheckbox: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithCheckboxExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="sms-alerts-opt-in"
+        inputType="checkbox"
+        fieldDescription="Sent for unexplained absences and behaviour incidents"
+        inputProps={{
+          label: 'Notify parents by SMS',
+          checked: true,
+          onChange: (event) => console.log(event.target.checked),
+        }}
+      />
+      <FormField
+        id="data-accuracy-ack"
+        inputType="checkbox"
+        inputProps={{
+          label: 'I confirm this record is accurate and up to date',
+          checked: false,
+          onChange: (event) => console.log(event.target.checked),
+        }}
+      />
+      <FormField
+        id="parental-consent"
+        inputType="checkbox"
+        errorText="You must confirm parental consent before submitting"
+        inputProps={{
+          label: 'I have obtained parental consent',
+          checked: false,
+          onChange: (event) => console.log(event.target.checked),
+        }}
+      />
+    </div>
+  );
+}
+export default WithCheckboxExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="sms-alerts-opt-in"
+          inputType="checkbox"
+          fieldDescription="Sent for unexplained absences and behaviour incidents"
+          inputProps={{
+            label: 'Notify parents by SMS',
+            checked: true,
+            onChange: fn(),
+          }}
+        />
+        <FormField
+          id="data-accuracy-ack"
+          inputType="checkbox"
+          inputProps={{
+            label: 'I confirm this record is accurate and up to date',
+            checked: false,
+            onChange: fn(),
+          }}
+        />
+        <FormField
+          id="parental-consent"
+          inputType="checkbox"
+          errorText="You must confirm parental consent before submitting"
+          inputProps={{
+            label: 'I have obtained parental consent',
+            checked: false,
+            onChange: fn(),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="checkbox"` renders a `CheckboxInput` and, unlike most other `inputType`s, its',
+    '`inputProps` are **required** — `CheckboxInput.Props` has no optional variant in the union.',
+    '',
+    '**Skip the top-level `label` prop for checkboxes.** `CheckboxInput` renders its own inline',
+    '`label` next to the box, inside the same `<label>` element as the input. Setting FormField\'s',
+    'top-level `label` as well produces two separate label texts stacked above and beside the box.',
+    'Use `fieldDescription` for supporting copy instead — it still renders above the input.',
+    '',
+    '**`checked` has no default and must be controlled.** There is no `defaultChecked` escape hatch',
+    'the way there is on `Toggle` — pair `checked` with `onChange` or the box will never update.',
+  ].join('\n'),
+);
+
+export const WithCheckboxGroup: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithCheckboxGroupExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="support-needs"
+        inputType="checkboxGroup"
+        fieldDescription="Select all that currently apply — this can be updated at any time"
+        inputProps={{
+          legend: 'Support needs',
+          options: [
+            { id: 'autism', label: 'Autism spectrum', checked: true, onChange: (event) => console.log(event.target.checked) },
+            { id: 'dyslexia', label: 'Dyslexia', checked: false, onChange: (event) => console.log(event.target.checked) },
+            { id: 'eal', label: 'EAL support', checked: false, onChange: (event) => console.log(event.target.checked) },
+          ],
+        }}
+      />
+      <FormField
+        id="consent-forms"
+        inputType="checkboxGroup"
+        errorText="Select at least one consent option before continuing"
+        inputProps={{
+          legend: 'Consent forms received',
+          options: [
+            { id: 'medical', label: 'Medical consent', checked: false, onChange: (event) => console.log(event.target.checked) },
+            { id: 'photo', label: 'Photo consent', checked: false, onChange: (event) => console.log(event.target.checked) },
+          ],
+        }}
+      />
+    </div>
+  );
+}
+export default WithCheckboxGroupExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="support-needs"
+          inputType="checkboxGroup"
+          fieldDescription="Select all that currently apply — this can be updated at any time"
+          inputProps={{
+            legend: 'Support needs',
+            options: [
+              { id: 'autism', label: 'Autism spectrum', checked: true, onChange: fn() },
+              { id: 'dyslexia', label: 'Dyslexia', checked: false, onChange: fn() },
+              { id: 'eal', label: 'EAL support', checked: false, onChange: fn() },
+            ],
+          }}
+        />
+        <FormField
+          id="consent-forms"
+          inputType="checkboxGroup"
+          errorText="Select at least one consent option before continuing"
+          inputProps={{
+            legend: 'Consent forms received',
+            options: [
+              { id: 'medical', label: 'Medical consent', checked: false, onChange: fn() },
+              { id: 'photo', label: 'Photo consent', checked: false, onChange: fn() },
+            ],
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="checkboxGroup"` renders a `CheckboxGroup` — a `Fieldset` wrapping one `CheckboxInput`',
+    'per entry in `inputProps.options`. Like `"checkbox"`, `inputProps` is **required**.',
+    '',
+    '**Use `inputProps.legend`, not FormField\'s top-level `label`, to name the group.** `Fieldset`',
+    'renders its own `<legend>` — set it via `legend` inside `inputProps`. FormField\'s top-level',
+    '`label` still renders (as a standalone `<Label>` above the fieldset) if you provide one, so pick',
+    'one or the other to avoid two headings for the same group.',
+    '',
+    '**Each option manages its own `checked` and `onChange`.** Unlike `RadioButtonGroup`, there is no',
+    'single group-level value — every entry in `options` needs its own `checked` boolean and `onChange`',
+    'handler. `option.id` doubles as the React key.',
+  ].join('\n'),
+);
+
+export const WithToggle: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithToggleExample() {
+  return (
+    <div style={{ maxWidth: '28rem', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+      <FormField
+        id="weekly-summary-emails"
+        label="Weekly summary emails"
+        inputType="toggle"
+        fieldDescription="Sent every Friday afternoon with attendance and behaviour highlights"
+        inputProps={{
+          defaultChecked: true,
+          onCheckedChange: (checked) => console.log(checked),
+        }}
+      />
+      <FormField
+        id="two-factor-auth"
+        label="Require two-factor authentication"
+        inputType="toggle"
+        inputProps={{
+          defaultChecked: false,
+          onCheckedChange: (checked) => console.log(checked),
+        }}
+      />
+      <FormField
+        id="marketing-emails"
+        label="Marketing emails"
+        inputType="toggle"
+        errorText="You must accept the updated marketing preferences to continue"
+        inputProps={{
+          defaultChecked: false,
+          onCheckedChange: (checked) => console.log(checked),
+        }}
+      />
+    </div>
+  );
+}
+export default WithToggleExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)', display: 'flex', flexDirection: 'column', gap: 'var(--spacing-large)' }}>
+        <FormField
+          id="weekly-summary-emails"
+          label="Weekly summary emails"
+          inputType="toggle"
+          fieldDescription="Sent every Friday afternoon with attendance and behaviour highlights"
+          inputProps={{
+            defaultChecked: true,
+            onCheckedChange: fn(),
+          }}
+        />
+        <FormField
+          id="two-factor-auth"
+          label="Require two-factor authentication"
+          inputType="toggle"
+          inputProps={{
+            defaultChecked: false,
+            onCheckedChange: fn(),
+          }}
+        />
+        <FormField
+          id="marketing-emails"
+          label="Marketing emails"
+          inputType="toggle"
+          errorText="You must accept the updated marketing preferences to continue"
+          inputProps={{
+            defaultChecked: false,
+            onCheckedChange: fn(),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="toggle"` renders a `Toggle` (`inputProps` is `Toggle.Props` — Radix UI\'s `Switch.SwitchProps` plus `hasError` — and',
+    '— like the other three new types — it is **required**).',
+    '',
+    '**FormField solves Toggle\'s biggest standalone gotcha for you.** Used on its own, `Toggle` has',
+    'no visible label and needs a hand-rolled `<label htmlFor={id}>` (see the `Toggle` stories\' `WithLabel`',
+    'example). Inside FormField, the top-level `label` prop renders that `<Label htmlFor={id}>` for you',
+    'automatically — just provide `label` and `id` as normal, no manual pairing required.',
+    '',
+    '**`onCheckedChange` receives a boolean, not an event.** `(checked: boolean) => void` — there is',
+    'no `event.target.checked` to unwrap, unlike the native-input-backed `checkbox` and `radio` types.',
+  ].join('\n'),
+);
+
+export const WithRadio: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithRadioExample() {
+  return (
+    <FormField
+      id="contact-method"
+      inputType="radio"
+      fieldDescription="Used for attendance and behaviour notifications only"
+      errorText="Please select a contact method"
+      inputProps={{
+        legend: 'Preferred contact method',
+        name: 'contact-method',
+        checkedValue: 'sms',
+        options: [
+          { id: 'phone', value: 'phone', label: 'Phone call' },
+          { id: 'email', value: 'email', label: 'Email' },
+          { id: 'sms', value: 'sms', label: 'SMS' },
+        ],
+        onChange: (event) => console.log(event.target.value),
+      }}
+    />
+  );
+}
+export default WithRadioExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <FormField
+          id="contact-method"
+          inputType="radio"
+          fieldDescription="Used for attendance and behaviour notifications only"
+          errorText="Please select a contact method"
+          inputProps={{
+            legend: 'Preferred contact method',
+            name: 'contact-method',
+            checkedValue: 'sms',
+            options: [
+              { id: 'phone', value: 'phone', label: 'Phone call' },
+              { id: 'email', value: 'email', label: 'Email' },
+              { id: 'sms', value: 'sms', label: 'SMS' },
+            ],
+            onChange: fn(),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="radio"` renders a `RadioButtonGroup` — a `Fieldset` wrapping one radio per entry in',
+    '`inputProps.options`. `inputProps` is **required** and, unlike `CheckboxGroup`, the group is',
+    'controlled from a single place: `checkedValue` + one `onChange`, not per-option state.',
+    '',
+    '**`checkedValue` is compared against each `option.value`, not `option.id`.** `id` only supplies',
+    'the React key — set `value` on every option and match it against `checkedValue` to control which',
+    'radio is selected.',
+    '',
+    '**`name` is required by the type, and functionally mandatory** — without a shared `name`, the',
+    'native radios do not group and multiple can appear selected at once.',
+    '',
+    '**Use `inputProps.legend`, not FormField\'s top-level `label`,** to name the group — the same',
+    'convention as `checkboxGroup`.',
+  ].join('\n'),
+);

package/src/components/formField/FormField.test.tsx

@@ -75,6 +75,106 @@ describe('FormField component', () => {
     expect(screen.getByRole('button', { name: 'Open date and time picker' })).toBeInTheDocument();
   });
 
+  test('renders a checkbox when inputType is checkbox', () => {
+    render(<FormField id="niceid" inputType="checkbox" inputProps={{ label: 'Subscribe to newsletter', checked: false, onChange: () => {} }} />);
+    expect(screen.getByRole('checkbox', { name: 'Subscribe to newsletter' })).toBeInTheDocument();
+  });
+
+  test('marks a checkbox as invalid when errorText is provided', () => {
+    render(<FormField id="niceid" errorText="Required" inputType="checkbox" inputProps={{ label: 'Subscribe to newsletter', checked: false, onChange: () => {} }} />);
+    expect(screen.getByRole('checkbox', { name: 'Subscribe to newsletter' })).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  test('renders a checkbox group when inputType is checkboxGroup', () => {
+    render(
+      <FormField
+        id="niceid"
+        inputType="checkboxGroup"
+        inputProps={{
+          legend: 'Preferences',
+          options: [
+            { id: 'optionA', label: 'Option A', checked: false, onChange: () => {} },
+            { id: 'optionB', label: 'Option B', checked: true, onChange: () => {} },
+          ],
+        }}
+      />,
+    );
+    expect(screen.getByRole('group', { name: 'Preferences' })).toBeInTheDocument();
+    expect(screen.getByRole('checkbox', { name: 'Option A' })).not.toBeChecked();
+    expect(screen.getByRole('checkbox', { name: 'Option B' })).toBeChecked();
+  });
+
+  test('marks checkboxes in a checkbox group as invalid when errorText is provided', () => {
+    render(
+      <FormField
+        id="niceid"
+        errorText="Please select at least one option"
+        inputType="checkboxGroup"
+        inputProps={{
+          legend: 'Preferences',
+          options: [
+            { id: 'optionA', label: 'Option A', checked: false, onChange: () => {} },
+          ],
+        }}
+      />,
+    );
+    expect(screen.getByRole('checkbox', { name: 'Option A' })).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  test('renders a toggle when inputType is toggle', () => {
+    render(<FormField id="niceid" label="Enable notifications" inputType="toggle" inputProps={{ onCheckedChange: () => {} }} />);
+    expect(screen.getByRole('switch', { name: 'Enable notifications' })).toBeInTheDocument();
+  });
+
+  test('marks a toggle as invalid when errorText is provided', () => {
+    render(<FormField id="niceid" label="Enable notifications" errorText="Required" inputType="toggle" inputProps={{ onCheckedChange: () => {} }} />);
+    expect(screen.getByRole('switch', { name: 'Enable notifications' })).toHaveAttribute('aria-invalid', 'true');
+  });
+
+  test('renders a radio button group when inputType is radio', () => {
+    render(
+      <FormField
+        id="niceid"
+        inputType="radio"
+        inputProps={{
+          legend: 'Contact method',
+          name: 'contact-method',
+          checkedValue: 'sms',
+          options: [
+            { id: 'sms', value: 'sms', label: 'SMS' },
+            { id: 'email', value: 'email', label: 'Email' },
+          ],
+          onChange: () => {},
+        }}
+      />,
+    );
+    expect(screen.getByRole('group', { name: 'Contact method' })).toBeInTheDocument();
+    expect(screen.getByRole('radio', { name: 'SMS' })).toBeChecked();
+    expect(screen.getByRole('radio', { name: 'Email' })).not.toBeChecked();
+  });
+
+  test('marks radio buttons in a radio group as invalid when errorText is provided', () => {
+    render(
+      <FormField
+        id="niceid"
+        errorText="Please choose a contact method"
+        inputType="radio"
+        inputProps={{
+          legend: 'Contact method',
+          name: 'contact-method',
+          checkedValue: 'sms',
+          options: [
+            { id: 'sms', value: 'sms', label: 'SMS' },
+            { id: 'email', value: 'email', label: 'Email' },
+          ],
+          onChange: () => {},
+        }}
+      />,
+    );
+    expect(screen.getByRole('radio', { name: 'SMS' })).toHaveAttribute('aria-invalid', 'true');
+    expect(screen.getByRole('radio', { name: 'Email' })).toHaveAttribute('aria-invalid', 'true');
+  });
+
   test('passes error state through to Combobox when errorText is provided', () => {
     render(
       <FormField