@arbor-education/design-system.components 0.15.0 → 0.16.1

package/src/components/formField/inputs/checkbox/CheckboxGroup.tsx

@@ -2,7 +2,7 @@ import { Fieldset, type FieldsetProps } from 'Components/formField/fieldset/Fiel
 import { CheckboxInput, type CheckboxInputProps } from './CheckboxInput';
 
 export type CheckboxGroupProps = {
-  options: CheckboxInputProps[];
+  options: (CheckboxInputProps & { id: string })[];
 } & FieldsetProps;
 
 export const CheckboxGroup = (props: CheckboxGroupProps) => {

package/src/components/formField/inputs/checkbox/CheckboxInput.tsx

@@ -1,6 +1,6 @@
 import classNames from 'classnames';
 import { useRef, useEffect, type InputHTMLAttributes } from 'react';
-import { Icon } from '../../../..';
+import { Icon } from 'Components/icon/Icon';
 
 export type CheckboxInputProps = {
   indeterminate?: boolean;

package/src/components/formField/inputs/colourPickerDropdown/ColourPickerDropdown.stories.tsx

@@ -1,29 +1,522 @@
+import { useState } from 'react';
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import type { ColorResult } from '@uiw/color-convert';
+import { FormField } from 'Components/formField/FormField';
 import { ColourPickerDropdown } from './ColourPickerDropdown';
-import type { ColorResult } from '@uiw/react-color';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'ColourPickerDropdown is a dropdown-triggered colour picker that lets users select any colour from a',
+  'full-spectrum palette, with Hex and RGB input fields for precise entry.',
+  'Built on the [`@uiw/react-color` Sketch picker](https://uiwjs.github.io/react-color/), which provides',
+  'the colour plane, hue slider, Hex/RGB inputs, and preset swatches.',
+  'The dropdown panel renders via a Radix UI portal —',
+  '**do not place inside a container with `overflow: hidden`**.',
+  '',
+  'The trigger renders as a small circular colour swatch inside a dropdown-variant button.',
+  'Selection applies immediately — the swatch updates live as the user picks.',
+  'The panel closes on click outside or `Escape`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Data-driven formatting where users assign a colour to a record — for example, background colours for conditional formatting bands in a marksheet.',
+  '- When users need to match a specific colour exactly by Hex or RGB value.',
+  '- When freedom of colour choice is appropriate and available colours are not predefined.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Status choices ("On track / At risk / Off track") | `SelectDropdown` with named labels — colour alone is not sufficient to communicate status |',
+  '| Small fixed set of meaningful colours | `SelectDropdown` with colour swatches as option labels |',
+  '| Colour could reduce readability (e.g. text colour without contrast checks) | Constrain choices via `SelectDropdown` with an approved palette |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`onChange` receives a `ColorResult` object, not a plain hex string.** Read the format you need:',
+  '',
+  '```tsx',
+  "import type { ColorResult } from '@uiw/color-convert';",
+  '',
+  '<ColourPickerDropdown',
+  '  value={colour}',
+  '  onChange={(result: ColorResult) => {',
+  "    const hex = result.hex;           // '#3cad51'",
+  '    const { r, g, b } = result.rgb;  // { r: 60, g: 173, b: 81 }',
+  '    setColour(hex);',
+  '  }}',
+  '/>',
+  '```',
+  '',
+  '**`id` is dual-purpose** — it sets the `name` on the hidden `<input>` (for native form submission) AND',
+  'the `id` on the trigger button (for label association via `htmlFor`).',
+  '',
+  '**`hasError` is visual-only.** It changes the trigger button\'s border colour but tells screen readers',
+  'nothing. Always pair it with `aria-invalid={true}`.',
+  '',
+  '**No alpha / transparency support** — `disableAlpha` is hardcoded. The picker never shows an opacity slider.',
+  '',
+  '**Semi-controlled pattern** — the component holds internal state via `useState`, but syncs from the',
+  '`value` prop via `useEffect`. Changing `value` externally (e.g. a form reset) will update the picker.',
+  '',
+  '**`onChange` fires on every picker interaction**, including while sliders are dragged.',
+  'If you update server state in `onChange`, consider debouncing.',
+  '',
+  '**Portal rendering** — the dropdown panel renders via a Radix UI portal outside the trigger\'s DOM subtree.',
+  'Do not place inside `overflow: hidden` or `position: relative` containers.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- The trigger button includes a visually-hidden "Toggle colour picker." label for screen readers.',
+  '- The swatch inside the trigger includes a visually-hidden "current colour: #hex" label that updates live.',
+  '- Always pair `hasError` with `aria-invalid={true}` — one is visual, one is for assistive technology.',
+  '- Use `aria-describedBy` pointing to the `id` of a `FormField.Error` element to provide the error message.',
+  '- The recommended pattern is `<FormField inputType="colourPicker" inputProps={{...}} />` — this wires `hasError`, `aria-invalid`, and `aria-describedby` automatically.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```tsx',
+  "import type { ColorResult } from '@uiw/color-convert';",
+  "import { ColourPickerDropdown } from '@arbor-education/design-system.components';",
+  '',
+  '// Access colour values in onChange:',
+  'onChange={(result: ColorResult) => {',
+  "  const hex = result.hex;         // '#3cad51'",
+  '  const { r, g, b } = result.rgb; // { r: 60, g: 173, b: 81 }',
+  '}}',
+  '',
+  '// Type your own props using the exported namespace:',
+  'function MyField(props: ColourPickerDropdown.Props) { ... }',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[FormField](?path=/docs/components-formfield--docs) · [SelectDropdown](?path=/docs/components-formfield-inputs-selectdropdown--docs) · [Combobox](?path=/docs/components-combobox--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 ColourPickerDropdownDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 
 const meta = {
   title: 'Components/FormField/Inputs/ColourPickerDropdown',
   component: ColourPickerDropdown,
   tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      page: ColourPickerDropdownDocsPage,
+    },
+  },
+  argTypes: {
+    'value': {
+      description: [
+        'The current colour value as a hex string (e.g. `\'#3cad51\'`).',
+        'The component holds internal state but syncs from this prop via `useEffect` —',
+        'changing it externally (e.g. a form reset) will update the picker.',
+      ].join(' '),
+      control: { type: 'color' },
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "'#3cad51'" },
+      },
+    },
+    'onChange': {
+      description: [
+        'Callback fired on every colour change (including while sliders are dragged).',
+        'Receives a `ColorResult` object — read `.hex`, `.rgb`, or `.hsl` off it.',
+      ].join(' '),
+      action: 'onChange',
+      control: false,
+      table: {
+        type: { summary: '(value: ColorResult) => void' },
+      },
+    },
+    'hasError': {
+      description: [
+        'Applies error styling (red border) to the trigger button.',
+        'Visual only — always pair with `aria-invalid` for screen-reader coverage.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'disabled': {
+      description: 'When true, the trigger is non-interactive and visually muted.',
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    'id': {
+      description: [
+        'Dual-purpose: sets the `name` on the hidden `<input>` for native form submission AND',
+        'the `id` on the trigger button for label association via `htmlFor`.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'aria-describedBy': {
+      description: [
+        'ID of the element describing this field (e.g. a `FormField.Error`).',
+        'Note the capital B — the component maps this to the lowercase `aria-describedby` DOM attribute.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+      },
+    },
+    'aria-invalid': {
+      description: 'Marks the trigger as invalid for screen readers. Use alongside `hasError` and `aria-describedBy`.',
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+  },
 } satisfies Meta<typeof ColourPickerDropdown>;
 
 export default meta;
-type Story = StoryObj<typeof meta>;
+type Story = StoryObj<typeof ColourPickerDropdown>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: {
+      ...story.parameters?.docs,
+      description: {
+        story: description,
+      },
+    },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components for stateful and composite stories
+// ---------------------------------------------------------------------------
+
+const ControlledTemplate = () => {
+  const [colour, setColour] = useState('#3cad51');
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '20rem' }}>
+      <ColourPickerDropdown
+        value={colour}
+        onChange={(result: ColorResult) => setColour(result.hex)}
+        id="controlled-colour"
+      />
+      <p style={{ margin: 0, fontSize: '0.875rem', color: 'var(--color-grey-600)' }}>
+        Selected colour:
+        {' '}
+        <code>{colour}</code>
+      </p>
+    </div>
+  );
+};
+
+const InFormFieldTemplate = () => (
+  <div style={{ maxWidth: '20rem' }}>
+    <FormField
+      label="Category colour"
+      id="category-colour"
+      inputType="colourPicker"
+      inputProps={{ value: '#3cad51' }}
+    />
+  </div>
+);
+
+const WithFormFieldAndErrorTemplate = () => (
+  <div style={{ maxWidth: '20rem' }}>
+    <FormField
+      label="Background colour"
+      id="background-colour"
+      inputType="colourPicker"
+      errorText="Please choose a background colour."
+      inputProps={{ value: '#3cad51' }}
+    />
+  </div>
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
 
 export const Default: Story = {
   args: {
     value: '#3cad51',
-    onChange: (value: ColorResult) => { console.log(value); },
   },
-  argTypes: {
-    value: {
-      control: 'color',
-      description: 'The colour to display in the preview',
+  render: args => (
+    <div style={{ maxWidth: '20rem' }}>
+      <ColourPickerDropdown {...args} />
+    </div>
+  ),
+};
+
+export const WithCustomValue: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ColourPickerDropdown } from '@arbor-education/design-system.components';
+
+function WithCustomValueExample() {
+  return (
+    <div style={{ maxWidth: '20rem' }}>
+      <ColourPickerDropdown value="#e84393" id="highlight-colour" />
+    </div>
+  );
+}
+
+export default WithCustomValueExample;
+          `.trim(),
+        },
+      },
     },
-    onChange: {
-      action: 'changed',
-      description: 'The function to call when the colour is changed',
+    render: () => (
+      <div style={{ maxWidth: '20rem' }}>
+        <ColourPickerDropdown value="#e84393" id="highlight-colour" />
+      </div>
+    ),
+  },
+  'Pass any valid hex string to `value` to pre-seed the picker with a specific colour. The swatch in the trigger updates immediately.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ColourPickerDropdown } from '@arbor-education/design-system.components';
+
+function DisabledExample() {
+  return (
+    <div style={{ maxWidth: '20rem' }}>
+      <ColourPickerDropdown value="#3cad51" disabled id="disabled-colour" />
+    </div>
+  );
+}
+
+export default DisabledExample;
+          `.trim(),
+        },
+      },
     },
+    render: () => (
+      <div style={{ maxWidth: '20rem' }}>
+        <ColourPickerDropdown value="#3cad51" disabled id="disabled-colour" />
+      </div>
+    ),
   },
-};
+  'When `disabled` is true the trigger is non-interactive and visually muted. The colour swatch is still visible so the current value remains clear.',
+);
+
+export const WithError: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ColourPickerDropdown } from '@arbor-education/design-system.components';
+
+function WithErrorExample() {
+  return (
+    <div style={{ maxWidth: '20rem' }}>
+      <ColourPickerDropdown
+        value="#3cad51"
+        hasError
+        aria-invalid
+        id="colour-with-error"
+      />
+    </div>
+  );
+}
+
+export default WithErrorExample;
+          `.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ maxWidth: '20rem' }}>
+        <ColourPickerDropdown
+          value="#3cad51"
+          hasError
+          aria-invalid
+          id="colour-with-error"
+        />
+      </div>
+    ),
+  },
+  'Both `hasError` (red border on the trigger) and `aria-invalid` (screen-reader announcement) must be set together for a complete error treatment. Neither alone is sufficient.',
+);
+
+export const Controlled: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import type { ColorResult } from '@uiw/color-convert';
+import { ColourPickerDropdown } from '@arbor-education/design-system.components';
+
+function ControlledExample() {
+  const [colour, setColour] = useState('#3cad51');
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', maxWidth: '20rem' }}>
+      <ColourPickerDropdown
+        value={colour}
+        onChange={(result: ColorResult) => setColour(result.hex)}
+        id="controlled-colour"
+      />
+      <p style={{ margin: 0, fontSize: '0.875rem' }}>
+        Selected colour: <code>{colour}</code>
+      </p>
+    </div>
+  );
+}
+
+export default ControlledExample;
+          `.trim(),
+        },
+      },
+    },
+    render: () => <ControlledTemplate />,
+  },
+  '`onChange` receives a `ColorResult` object — read `.hex` off it to keep your own state in sync. The selected hex value is reflected live beneath the picker.',
+);
+
+export const InFormField: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function InFormFieldExample() {
+  return (
+    <div style={{ maxWidth: '20rem' }}>
+      <FormField
+        label="Category colour"
+        id="category-colour"
+        inputType="colourPicker"
+        inputProps={{ value: '#3cad51' }}
+      />
+    </div>
+  );
+}
+
+export default InFormFieldExample;
+          `.trim(),
+        },
+      },
+    },
+    render: () => <InFormFieldTemplate />,
+  },
+  'The recommended usage pattern — `FormField` with `inputType="colourPicker"` auto-wires the label, `hasError`, `aria-invalid`, and `aria-describedby`. No manual prop threading required.',
+);
+
+export const WithFormFieldAndError: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FormField } from '@arbor-education/design-system.components';
+
+function WithFormFieldAndErrorExample() {
+  return (
+    <div style={{ maxWidth: '20rem' }}>
+      <FormField
+        label="Background colour"
+        id="background-colour"
+        inputType="colourPicker"
+        errorText="Please choose a background colour."
+        inputProps={{ value: '#3cad51' }}
+      />
+    </div>
+  );
+}
+
+export default WithFormFieldAndErrorExample;
+          `.trim(),
+        },
+      },
+    },
+    render: () => <WithFormFieldAndErrorTemplate />,
+  },
+  'The full error treatment via `FormField` — setting `errorText` automatically passes `hasError`, `aria-invalid`, and `aria-describedby` to the picker. No manual prop threading required.',
+);

package/src/components/formField/inputs/radio/RadioButtonGroup.tsx

@@ -1,10 +1,16 @@
 import type { ChangeEvent } from 'react';
-import { RadioButtonInput, type RadioButtonInputProps } from './RadioButtonInput';
+import { RadioButtonInput } from './RadioButtonInput';
 import { Fieldset, type FieldsetProps } from '../../fieldset/Fieldset';
 
+export type RadioGroupOption = {
+  id: string;
+  value?: string | number | readonly string[];
+  label?: string;
+};
+
 export type RadioButtonGroupProps = {
   name: string;
-  options: RadioButtonInputProps[];
+  options: RadioGroupOption[];
   checkedValue: string;
   onChange: (event: ChangeEvent<HTMLInputElement>) => void;
 } & Omit<FieldsetProps, 'onChange'>;
@@ -14,8 +20,15 @@ export const RadioButtonGroup = (props: RadioButtonGroupProps) => {
 
   return (
     <Fieldset legend={legend} {...rest}>
-      {options.map((option: RadioButtonInputProps) => (
-        <RadioButtonInput key={option.id} name={name} value={option.value} label={option.label} checked={checkedValue === option.value} onChange={onChange} />
+      {options.map((option: RadioGroupOption) => (
+        <RadioButtonInput
+          key={option.id}
+          name={name}
+          value={option.value}
+          label={option.label}
+          checked={checkedValue === option.value}
+          onChange={onChange}
+        />
       ))}
     </Fieldset>
   );