@arbor-education/design-system.components 4.1.0 → 4.3.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 thirteen input controls, an optional helper link, and an error message — all',
+  'description, any of fourteen input controls (or your own via `custom`), 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',
@@ -63,6 +63,7 @@ const USAGE_GUIDANCE = [
   '| `"toggle"` | `Toggle` | Instant on/off settings embedded in a form |',
   '| `"radio"` | `RadioButtonGroup` | One choice from a short, mutually-exclusive list |',
   '| `"singleFile"` | `SingleFileInput` | One attachment submitted with a native form POST |',
+  '| `"custom"` | Your own element, via `inputProps.renderCustomInput` | A control the DS does not ship, such as a rich-text editor |',
 ].join('\n');
 
 const DEVELOPER_NOTES = [
@@ -235,7 +236,7 @@ const meta = {
     },
     inputType: {
       control: 'select',
-      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox', 'checkbox', 'checkboxGroup', 'toggle', 'radio', 'singleFile'],
+      options: ['text', 'textarea', 'number', 'time', 'colourPicker', 'selectDropdown', 'datePicker', 'combobox', 'checkbox', 'checkboxGroup', 'toggle', 'radio', 'singleFile', 'custom'],
       description: [
         'Determines which input component is rendered.',
         'Defaults to `"text"` (renders `TextInput`).',
@@ -249,11 +250,12 @@ const meta = {
         '`"checkboxGroup"` → `CheckboxGroup` (several independent selections);',
         '`"toggle"` → `Toggle` (instant on/off switch);',
         '`"radio"` → `RadioButtonGroup` (one choice from a short list);',
-        '`"singleFile"` → `SingleFileInput` (one file for a native form POST).',
+        '`"singleFile"` → `SingleFileInput` (one file for a native form POST);',
+        '`"custom"` → the element returned by `inputProps.renderCustomInput` (a control the DS does not ship).',
         '`"checkbox"`, `"checkboxGroup"`, `"toggle"` and `"radio"` require `inputProps` — see the developer notes.',
       ].join(' '),
       table: {
-        type: { summary: "'text' | 'textarea' | 'number' | 'time' | 'colourPicker' | 'selectDropdown' | 'datePicker' | 'combobox' | 'checkbox' | 'checkboxGroup' | 'toggle' | 'radio' | 'singleFile'" },
+        type: { summary: "'text' | 'textarea' | 'number' | 'time' | 'colourPicker' | 'selectDropdown' | 'datePicker' | 'combobox' | 'checkbox' | 'checkboxGroup' | 'toggle' | 'radio' | 'singleFile' | 'custom'" },
         defaultValue: { summary: "'text'" },
       },
     },
@@ -328,7 +330,7 @@ const meta = {
         '**Required, not optional, for `"checkbox"`, `"checkboxGroup"`, `"toggle"`, and `"radio"`.**',
       ].join(' '),
       table: {
-        type: { summary: 'TextInputProps | TextAreaProps | NumberInputProps | TimeInputProps | ColourPickerDropdownProps | SelectDropdownInputProps | DatePickerProps | DateTimePickerProps | ComboboxProps | CheckboxInputProps | CheckboxGroupProps | Toggle.Props | RadioButtonGroupProps | SingleFileInputProps' },
+        type: { summary: 'TextInputProps | TextAreaProps | NumberInputProps | TimeInputProps | ColourPickerDropdownProps | SelectDropdownInputProps | DatePickerProps | DateTimePickerProps | ComboboxProps | CheckboxInputProps | CheckboxGroupProps | Toggle.Props | RadioButtonGroupProps | SingleFileInputProps | CustomInputProps' },
       },
     },
   },
@@ -1990,3 +1992,96 @@ export default WithRadioExample;
     'convention as `checkboxGroup`.',
   ].join('\n'),
 );
+
+export const WithCustomInput: Story = withDescription(
+  {
+    parameters: {
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithCustomInputExample() {
+  return (
+    <FormField
+      id="report-notes"
+      label="Report notes"
+      inputType="custom"
+      fieldDescription="Shown to parents on the termly report"
+      helperLinkText="Formatting help"
+      helperLinkUrl="https://example.com/formatting"
+      errorText="Report notes are required"
+      inputProps={{
+        renderCustomInput: ({ id, labelId, hasError, 'aria-describedby': describedBy, 'aria-invalid': invalid }) => (
+          <div
+            id={id}
+            role="textbox"
+            aria-multiline="true"
+            aria-labelledby={labelId}
+            aria-describedby={describedBy}
+            aria-invalid={invalid}
+            contentEditable
+            suppressContentEditableWarning
+            className={hasError ? 'my-editor my-editor--error' : 'my-editor'}
+          />
+        ),
+      }}
+    />
+  );
+}
+export default WithCustomInputExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '28rem', padding: 'var(--spacing-xlarge)' }}>
+        <FormField
+          id="report-notes"
+          label="Report notes"
+          inputType="custom"
+          fieldDescription="Shown to parents on the termly report"
+          helperLinkText="Formatting help"
+          helperLinkUrl="https://example.com/formatting"
+          errorText="Report notes are required"
+          inputProps={{
+            renderCustomInput: ({ id, labelId, hasError, 'aria-describedby': describedBy, 'aria-invalid': invalid }) => (
+              <div
+                id={id}
+                role="textbox"
+                aria-multiline="true"
+                aria-labelledby={labelId}
+                aria-describedby={describedBy}
+                aria-invalid={invalid}
+                contentEditable
+                suppressContentEditableWarning
+                style={{
+                  minHeight: '6rem',
+                  padding: 'var(--spacing-small)',
+                  border: `1px solid ${hasError ? 'var(--color-border-error, red)' : 'var(--color-border-default, grey)'}`,
+                  borderRadius: 'var(--border-radius-small, 4px)',
+                }}
+              />
+            ),
+          }}
+        />
+      </div>
+    ),
+  },
+  [
+    '`inputType="custom"` hosts an input the DS does not ship, such as a rich-text editor. `FormField`',
+    'still renders the label, `fieldDescription`, helper link and `errorText`; your',
+    '`inputProps.renderCustomInput` function returns the control. `inputProps` is **required**.',
+    '',
+    '**`renderCustomInput` receives the same wiring the built-in inputs get:** `id`, `aria-describedby`,',
+    '`aria-invalid` and `hasError`. Apply them to the element that takes focus, otherwise the',
+    'description and error are not announced.',
+    '',
+    '**Use `labelId` with `aria-labelledby` when the control is not a native input.** The label\'s',
+    '`htmlFor` only names `input`, `textarea` and `select`. A `contentEditable` element or an iframe',
+    'needs `aria-labelledby={labelId}` to get its accessible name.',
+    '',
+    '**The DS styles none of the custom control.** Use `hasError` to apply your own error treatment.',
+  ].join('\n'),
+);

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

@@ -1,6 +1,6 @@
 import '@testing-library/jest-dom/vitest';
 import { render, screen } from '@testing-library/react';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { FormField } from './FormField.js';
 
 describe('FormField component', () => {
@@ -229,4 +229,39 @@ describe('FormField component', () => {
     expect(field).toHaveClass('ds-input--error');
     expect(field).toHaveAccessibleDescription('File is too large');
   });
+
+  test('renders the consumer element inside the field chrome when inputType is custom', () => {
+    render(
+      <FormField
+        id="notes"
+        label="Notes"
+        inputType="custom"
+        fieldDescription="Shown on the report"
+        helperLinkText="Formatting help"
+        helperLinkUrl="https://example.com/help"
+        errorText="Notes are required"
+        inputProps={{
+          renderCustomInput: ({ id, labelId, 'aria-describedby': describedBy, 'aria-invalid': invalid }) => (
+            <div role="textbox" id={id} aria-multiline="true" aria-labelledby={labelId} aria-describedby={describedBy} aria-invalid={invalid} />
+          ),
+        }}
+      />,
+    );
+
+    const editor = screen.getByRole('textbox', { name: 'Notes' });
+    expect(editor).toHaveAccessibleDescription('Shown on the report Notes are required');
+    expect(editor).toBeInvalid();
+    expect(screen.getByText('Notes are required')).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'Notes helper link' })).toBeInTheDocument();
+    expect(editor.closest('.ds-form-field')).not.toBeNull();
+  });
+
+  test('tells a custom input whether the field has an error', () => {
+    const renderCustomInput = vi.fn(() => <div />);
+    const { rerender } = render(<FormField id="notes" inputType="custom" inputProps={{ renderCustomInput }} />);
+    expect(renderCustomInput).toHaveBeenLastCalledWith(expect.objectContaining({ 'hasError': false, 'aria-invalid': false }));
+
+    rerender(<FormField id="notes" inputType="custom" errorText="Required" inputProps={{ renderCustomInput }} />);
+    expect(renderCustomInput).toHaveBeenLastCalledWith(expect.objectContaining({ 'hasError': true, 'aria-invalid': true }));
+  });
 });

package/src/components/formField/FormField.tsx

@@ -16,6 +16,21 @@ import { CheckboxGroup } from './inputs/checkbox/CheckboxGroup.js';
 import { RadioButtonGroup } from './inputs/radio/RadioButtonGroup.js';
 import { Toggle } from 'Components/toggle/Toggle.js';
 
+export type FormFieldSharedProps = {
+  'id'?: string;
+  'aria-describedby': string;
+  'aria-invalid': boolean;
+  'hasError': boolean;
+};
+
+export type CustomInputRenderProps = FormFieldSharedProps & {
+  labelId?: string;
+};
+
+export type CustomInputProps = {
+  renderCustomInput: (renderProps: CustomInputRenderProps) => React.ReactNode;
+};
+
 export type FormFieldProps = {
   className?: string;
   label?: string;
@@ -39,6 +54,7 @@ export type FormFieldProps = {
   | { inputType?: 'toggle'; inputProps: Toggle.Props }
   | { inputType?: 'radio'; inputProps: RadioButtonGroup.Props }
   | { inputType?: 'singleFile'; inputProps?: SingleFileInput.Props }
+  | { inputType?: 'custom'; inputProps: CustomInputProps }
 );
 
 export const FormField = (props: FormFieldProps) => {
@@ -52,7 +68,9 @@ export const FormField = (props: FormFieldProps) => {
     describedByIds.push(`${id}-error`);
   }
 
-  const sharedProps = {
+  const labelId = inputType === 'custom' && id ? `${id}-label` : undefined;
+
+  const sharedProps: FormFieldSharedProps = {
     id,
     'aria-describedby': describedByIds.join(' '),
     'hasError': !!errorText,
@@ -62,7 +80,7 @@ export const FormField = (props: FormFieldProps) => {
   return (
     <div className={classes}>
       {label && (
-        <Label htmlFor={id}>
+        <Label htmlFor={id} id={labelId}>
           {label}
         </Label>
       )}
@@ -111,6 +129,7 @@ export const FormField = (props: FormFieldProps) => {
       {inputType === 'singleFile' && (
         <SingleFileInput {...sharedProps} {...(inputProps as SingleFileInput.Props)} />
       )}
+      {inputType === 'custom' && (inputProps as CustomInputProps).renderCustomInput({ ...sharedProps, labelId })}
       {((helperLinkText && helperLinkUrl) || errorText) && (
         <div className="ds-form-field__message">
           {errorText && (

package/src/components/formField/label/Label.tsx

@@ -2,7 +2,7 @@ import classNames from 'classnames';
 import type { HTMLProps } from 'react';
 
 export const Label = (props: HTMLProps<HTMLLabelElement>) => {
-  const { className, htmlFor, children } = props;
+  const { className, htmlFor, id, children } = props;
   const classes = classNames('ds-label', className);
-  return <label className={classes} htmlFor={htmlFor}>{children}</label>;
+  return <label className={classes} htmlFor={htmlFor} id={id}>{children}</label>;
 };

package/src/components/widgetCalendar/WidgetCalendar.stories.tsx

@@ -166,7 +166,7 @@ const groupedItems: WidgetCalendar.ItemData[] = [
 
 const DESCRIPTION_INTRO = [
   '`WidgetCalendar` is a pre-composed dashboard widget for date/time-anchored calendar events.',
-  'It wraps [`Widget`](?path=/docs/components-widget--docs) with an event list, primary/secondary type indicators, and',
+  'It wraps [`Widget`](?path=/docs/components-widget--docs) with an event list, an eight-value event type indicator, and',
   'optional heading navigation. Each item renders a semantic `<time>` element from an ISO `eventDateTime` and a',
   'human-readable `eventTimeLabel`.',
 ].join('\n');
@@ -214,9 +214,12 @@ const DEVELOPER_NOTES = [
   'fall into the ungrouped bucket, which renders above all groups to prevent ambiguity about which group',
   'an item belongs to. Groups appear in the order their labels are first declared.',
   '',
-  '**The type-bar colour is semantic, not decorative.** `eventType="primary"` renders the brand-green bar',
-  '(`--widget-calendar-type-primary-color`), `"secondary"` renders neutral grey',
-  '(`--widget-calendar-type-secondary-color`). Choose deliberately — don\'t treat it as a purely visual toggle.',
+  '**`eventType` selects one of eight type-bar colours.** The accepted values are `primary` (the default),',
+  '`secondary`, `destructive`, `caution`, `info`, `warning`, `green`, and `purple`, matching the eight index',
+  'colours in the design. The colour is chosen by the school per event and carries no meaning of its own —',
+  '`WidgetCalendar` attaches no semantics to the value, so the same colour can represent different event',
+  'categories in different schools. Pass the value the data source supplies rather than inferring one from',
+  'the event content.',
   '',
   '**No loading, disabled, or error state exists on this component.** Handle those states in the consumer',
   '(e.g. render a Skeleton in place of `WidgetCalendar` while data loads). `isLoading` and `loadingLabel` are',
@@ -688,6 +691,80 @@ export const SecondaryEventType: Story = withDescription(
   'Isolates `eventType="secondary"` — the neutral grey type bar, used for lower-priority or generic events.',
 );
 
+export const AllEventTypes: Story = withDescription(
+  {
+    args: {
+      heading: 'Calendar',
+      items: [
+        {
+          id: 'type-primary',
+          eventType: 'primary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 10: 10G',
+          ...classEventTime,
+        },
+        {
+          id: 'type-secondary',
+          eventType: 'secondary',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 8: 8B',
+          ...classEventTime,
+        },
+        {
+          id: 'type-destructive',
+          eventType: 'destructive',
+          eventPrimaryTerm: 'Exam',
+          eventPrimaryDefinition: 'GCSE Maths: Paper 1',
+          ...classEventTime,
+        },
+        {
+          id: 'type-caution',
+          eventType: 'caution',
+          eventPrimaryTerm: 'Trip',
+          eventPrimaryDefinition: 'Geography field trip',
+          ...classEventTime,
+        },
+        {
+          id: 'type-info',
+          eventType: 'info',
+          eventPrimaryTerm: 'Meeting',
+          eventPrimaryDefinition: 'Parents\' evening',
+          ...classEventTime,
+        },
+        {
+          id: 'type-warning',
+          eventType: 'warning',
+          eventPrimaryTerm: 'Deadline',
+          eventPrimaryDefinition: 'Reports due to head of year',
+          ...classEventTime,
+        },
+        {
+          id: 'type-green',
+          eventType: 'green',
+          eventPrimaryTerm: 'Club',
+          eventPrimaryDefinition: 'Football: Year 9',
+          ...classEventTime,
+        },
+        {
+          id: 'type-purple',
+          eventType: 'purple',
+          eventPrimaryTerm: 'Assembly',
+          eventPrimaryDefinition: 'Whole-school assembly',
+          ...classEventTime,
+        },
+      ],
+      onItemClick: fn(),
+    },
+    render: args => <WidgetCalendar {...args} />,
+    parameters: { controls: { disable: true } },
+  },
+  [
+    'All eight `eventType` values side by side, so the full set of type-bar colours can be compared in one view.',
+    'The colour is chosen by the school per event — `WidgetCalendar` attaches no semantics to any of the eight',
+    'values. See the Developer notes above for the full list.',
+  ].join(' '),
+);
+
 export const NonInteractiveItems: Story = withDescription(
   {
     args: {

package/src/components/widgetCalendar/WidgetCalendar.test.tsx

@@ -60,6 +60,54 @@ describe('WidgetCalendar', () => {
     expect(container.querySelector('.ds-widget-calendar__item--secondary')).toBeInTheDocument();
   });
 
+  const eventTypes: WidgetCalendar.EventType[] = [
+    'primary',
+    'secondary',
+    'destructive',
+    'caution',
+    'info',
+    'warning',
+    'green',
+    'purple',
+  ];
+
+  test.each(eventTypes)('applies the %s modifier class and no other event type class', (eventType) => {
+    const { container } = render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={[{ ...mockItems[0]!, eventType }]}
+      />,
+    );
+
+    const item = container.querySelector('.ds-widget-calendar__item');
+
+    expect(item).toHaveClass(`ds-widget-calendar__item--${eventType}`);
+
+    eventTypes
+      .filter(otherType => otherType !== eventType)
+      .forEach((otherType) => {
+        expect(item).not.toHaveClass(`ds-widget-calendar__item--${otherType}`);
+      });
+  });
+
+  test('defaults to the primary modifier class when eventType is omitted', () => {
+    const { container } = render(
+      <WidgetCalendar
+        heading="Calendar"
+        items={[{
+          id: 'no-type',
+          eventPrimaryTerm: 'Class',
+          eventPrimaryDefinition: 'Year 10: 10G',
+          eventSecondaryTerm: 'Time and location',
+          eventDateTime: '2026-06-08T08:45/2026-06-08T09:00',
+          eventTimeLabel: '08:45 – 09:00',
+        }]}
+      />,
+    );
+
+    expect(container.querySelector('.ds-widget-calendar__item')).toHaveClass('ds-widget-calendar__item--primary');
+  });
+
   test('calls onItemClick with item id', async () => {
     const user = userEvent.setup();
     const onItemClick = vi.fn();

package/src/components/widgetCalendar/WidgetCalendarItem.tsx

@@ -3,7 +3,15 @@ import { Icon } from 'Components/icon/Icon';
 import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
 import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
 
-export type WidgetCalendarEventType = 'primary' | 'secondary';
+export type WidgetCalendarEventType
+  = 'primary'
+    | 'secondary'
+    | 'destructive'
+    | 'caution'
+    | 'info'
+    | 'warning'
+    | 'green'
+    | 'purple';
 
 export type WidgetCalendarItemProps = {
   id: string;
@@ -68,9 +76,7 @@ export const WidgetCalendarItem = (props: WidgetCalendarItemProps): React.JSX.El
     <li
       className={classNames(
         'ds-widget-calendar__item',
-        eventType === 'secondary'
-          ? 'ds-widget-calendar__item--secondary'
-          : 'ds-widget-calendar__item--primary',
+        `ds-widget-calendar__item--${eventType}`,
         isInteractive && 'ds-widget-calendar__item--interactive',
         className,
       )}

package/src/components/widgetCalendar/widgetCalendar.scss

@@ -75,6 +75,30 @@
   background-color: var(--widget-calendar-type-secondary-color);
 }
 
+.ds-widget-calendar__item--destructive .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-destructive-color);
+}
+
+.ds-widget-calendar__item--caution .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-caution-color);
+}
+
+.ds-widget-calendar__item--info .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-info-color);
+}
+
+.ds-widget-calendar__item--warning .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-warning-color);
+}
+
+.ds-widget-calendar__item--green .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-green-color);
+}
+
+.ds-widget-calendar__item--purple .ds-widget-calendar__content::before {
+  background-color: var(--widget-calendar-type-purple-color);
+}
+
 .ds-widget-calendar__details {
   margin: 0;
 }

package/src/index.ts

@@ -28,6 +28,7 @@ export {
 } from 'Components/filterBar/FilterBar';
 export { Fieldset } from 'Components/formField/fieldset/Fieldset';
 export { FormField } from 'Components/formField/FormField';
+export type { CustomInputProps, CustomInputRenderProps, FormFieldSharedProps } from 'Components/formField/FormField';
 export { CheckboxGroup } from 'Components/formField/inputs/checkbox/CheckboxGroup';
 export { CheckboxInput } from 'Components/formField/inputs/checkbox/CheckboxInput';
 export { ColourPickerDropdown } from 'Components/formField/inputs/colourPickerDropdown/ColourPickerDropdown';

package/src/tokens.scss

@@ -841,6 +841,12 @@
   --widget-calendar-type-bar-radius: var(--border-radius-xsmall);
   --widget-calendar-type-primary-color: var(--color-brand-500);
   --widget-calendar-type-secondary-color: var(--color-grey-300);
+  --widget-calendar-type-destructive-color: var(--color-semantic-destructive-500);
+  --widget-calendar-type-caution-color: var(--color-semantic-caution-500);
+  --widget-calendar-type-info-color: var(--color-semantic-info-500);
+  --widget-calendar-type-warning-color: var(--color-semantic-warning-500);
+  --widget-calendar-type-green-color: var(--color-ramp-gradient-sequential-500);
+  --widget-calendar-type-purple-color: var(--color-extended-colours-purple-500);
   --widget-calendar-color-title: var(--color-grey-900);
   --widget-list-row-hover-hover-bg: var(--color-grey-050);
   --widget-list-row-hover-color-icon-arrow: var(--color-grey-900);