@arbor-education/design-system.components 0.25.1 → 0.25.2

package/src/components/toggleGroup/ToggleGroup.stories.tsx

@@ -0,0 +1,429 @@
+import { useState } from 'react';
+import type { Meta, StoryObj } from '@storybook/react-vite';
+import { fn } from 'storybook/test';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
+import { Icon } from 'Components/icon/Icon.js';
+import { ToggleGroup } from './ToggleGroup.js';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  'ToggleGroup renders a set of mutually exclusive toggle options built on',
+  '[Radix UI Toggle Group](https://www.radix-ui.com/primitives/docs/components/toggle-group).',
+  'Each option can carry a semantic `color` (`"red"`, `"yellow"`, or `"green"`) that applies',
+  'a background and text colour from the design token palette when the item is active.',
+  'It behaves as a radio group — only one option can be selected at a time.',
+  'Typical use cases include attendance status pickers (Present / Late / Absent) and any',
+  'single-select choice set where each option has a semantic colour meaning.',
+].join(' ');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- **Categorised single-select** — when each option has a distinct semantic colour (attendance, priority, status)',
+  '- **Compact radio replacement** — when a traditional radio group would take too much vertical space',
+  '- **Immediate selection** — when choosing an option takes effect right away without a form submission',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Multiple options can be selected | `CheckboxGroup` |',
+  '| Options are part of a larger form submission | `RadioButtonGroup` — communicates deferred action |',
+  '| More than ~6 options | `SelectDropdown` — toggle groups become unwieldy at scale |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Controlled vs uncontrolled',
+  '',
+  'Use `defaultValue` for uncontrolled mode — the component manages its own selection state.',
+  'Use `value` + `onValueChange` for controlled mode when you need to read or sync the value externally.',
+  '',
+  '**`onValueChange` receives the new value string directly**, not a React event.',
+  '',
+  '---',
+  '',
+  '### Option colour',
+  '',
+  'The `color` prop accepts `"red"`, `"yellow"`, or `"green"` and is optional.',
+  'When set, the colour is applied as background and text colour using semantic design tokens on the active item.',
+  'When omitted, the primary button style is used for the selected state.',
+  'Options within the same group can mix coloured and uncoloured items.',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  '- Rendered as `role="group"` containing `role="radio"` items',
+  '- Keyboard navigation: `Tab` focuses the group, arrow keys move between items, `Space`/`Enter` select',
+  '- Each item uses its `text` value as the accessible label',
+  '- The `disabled` prop on the root or individual options correctly sets the `disabled` attribute',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Docs page
+// ---------------------------------------------------------------------------
+
+function ToggleGroupDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const attendanceOptions = [
+  { value: 'present', text: 'Present' },
+  { value: 'late', text: 'Late' },
+  { value: 'absent', text: 'Absent' },
+];
+
+const meta = {
+  title: 'Components/ToggleGroup',
+  component: ToggleGroup,
+  parameters: {
+    layout: 'centered',
+    docs: {
+      page: ToggleGroupDocsPage,
+    },
+  },
+  tags: ['autodocs'],
+  args: {
+    options: attendanceOptions,
+    onValueChange: fn(),
+  },
+  argTypes: {
+    value: {
+      control: 'text',
+      description: 'The controlled selected value. Pair with `onValueChange`.',
+      table: { type: { summary: 'string' } },
+    },
+    defaultValue: {
+      control: 'text',
+      description: 'The initial selected value for uncontrolled usage.',
+      table: { type: { summary: 'string' } },
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables all options in the group.',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    onValueChange: {
+      action: 'valueChange',
+      control: false,
+      description: 'Callback fired when the selection changes. Receives the new value string.',
+      table: { type: { summary: '(value: string) => void' } },
+    },
+    options: {
+      control: false,
+      description:
+        'Array of option configs. Each accepts `value`, `text`, `color` (`"red" | "yellow" | "green"`), `icon`, and `disabled`.',
+      table: { type: { summary: 'ToggleGroupOption[]' } },
+    },
+  },
+} satisfies Meta<typeof ToggleGroup>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      options: attendanceOptions,
+      value: undefined,
+      onValueChange: fn(),
+    },
+  },
+  'No option selected. Click an option to see the selected state.',
+);
+
+export const WithDefaultValue: Story = withDescription(
+  {
+    args: {
+      options: attendanceOptions,
+      defaultValue: 'present',
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ToggleGroup } from '@arbor-education/design-system.components';
+
+const options = [
+  { value: 'present', text: 'Present' },
+  { value: 'late',    text: 'Late' },
+  { value: 'absent',  text: 'Absent' },
+];
+
+<ToggleGroup options={options} defaultValue="present" />
+`.trim(),
+        },
+      },
+    },
+  },
+  'Uncontrolled mode — `defaultValue` sets the initial selection and the component manages state internally.',
+);
+
+export const Controlled: Story = withDescription(
+  {
+    render: (args) => {
+      const [value, setValue] = useState('present');
+      return (
+        <div style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 'var(--spacing-small)' }}>
+          <ToggleGroup
+            options={args.options}
+            disabled={args.disabled}
+            className={args.className}
+            value={value}
+            onValueChange={(v) => {
+              setValue(v);
+              args.onValueChange?.(v);
+            }}
+          />
+          <p style={{ margin: 0, fontSize: 'var(--font-size-2-13)', color: 'var(--color-grey-600)' }}>
+            Selected:
+            {' '}
+            <strong>{value || '—'}</strong>
+          </p>
+        </div>
+      );
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { useState } from 'react';
+import { ToggleGroup } from '@arbor-education/design-system.components';
+
+const options = [
+  { value: 'present', text: 'Present' },
+  { value: 'late',    text: 'Late' },
+  { value: 'absent',  text: 'Absent' },
+];
+
+function AttendancePicker() {
+  const [status, setStatus] = useState('present');
+  return <ToggleGroup options={options} value={status} onValueChange={setStatus} />;
+}
+`.trim(),
+        },
+      },
+    },
+  },
+  'Controlled mode — `value` and `onValueChange` manage selection externally. The label below reflects the current value.',
+);
+
+export const WithColours: Story = withDescription(
+  {
+    args: {
+      options: [
+        { value: 'present', text: 'Present', color: 'green' as const },
+        { value: 'late', text: 'Late', color: 'yellow' as const },
+        { value: 'absent', text: 'Absent', color: 'red' as const },
+      ],
+      defaultValue: 'present',
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ToggleGroup } from '@arbor-education/design-system.components';
+
+const options = [
+  { value: 'present', text: 'Present', color: 'green' },
+  { value: 'late',    text: 'Late',    color: 'yellow' },
+  { value: 'absent',  text: 'Absent',  color: 'red' },
+];
+
+<ToggleGroup options={options} defaultValue="present" />
+`.trim(),
+        },
+      },
+    },
+  },
+  'Each option accepts an optional `color` prop (`"green"`, `"yellow"`, or `"red"`). The colour is applied using semantic design tokens when the item is selected.',
+);
+
+export const WithMixedColours: Story = withDescription(
+  {
+    args: {
+      options: [
+        { value: 'present', text: 'Present', color: 'green' as const },
+        { value: 'late', text: 'Late', color: 'yellow' as const },
+        { value: 'absent', text: 'Absent', color: 'red' as const },
+        { value: 'not-required', text: 'Not required' },
+      ],
+      defaultValue: 'not-required',
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { ToggleGroup } from '@arbor-education/design-system.components';
+
+const options = [
+  { value: 'present',      text: 'Present',      color: 'green' },
+  { value: 'late',         text: 'Late',          color: 'yellow' },
+  { value: 'absent',       text: 'Absent',        color: 'red' },
+  { value: 'not-required', text: 'Not required' },
+];
+
+<ToggleGroup options={options} defaultValue="not-required" />
+`.trim(),
+        },
+      },
+    },
+  },
+  'Options within the same group can mix coloured and uncoloured items. Uncoloured items use the primary button style when selected.',
+);
+
+export const WithColoursAndIcons: Story = withDescription(
+  {
+    args: {
+      options: [
+        { value: 'present', text: 'Present', color: 'green' as const, icon: <Icon name="check" size={16} /> },
+        { value: 'late', text: 'Late', color: 'yellow' as const, icon: <Icon name="clock-3" size={16} /> },
+        { value: 'absent', text: 'Absent', color: 'red' as const, icon: <Icon name="x" size={16} /> },
+      ],
+      defaultValue: 'present',
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon, ToggleGroup } from '@arbor-education/design-system.components';
+
+const options = [
+  { value: 'present', text: 'Present', color: 'green',  icon: <Icon name="check"   size={16} /> },
+  { value: 'late',    text: 'Late',    color: 'yellow', icon: <Icon name="clock-3" size={16} /> },
+  { value: 'absent',  text: 'Absent',  color: 'red',    icon: <Icon name="x"       size={16} /> },
+];
+
+<ToggleGroup options={options} defaultValue="present" />
+`.trim(),
+        },
+      },
+    },
+  },
+  'Options can combine a semantic colour with an icon.',
+);
+
+export const WithIcons: Story = withDescription(
+  {
+    args: {
+      options: [
+        { value: 'present', text: 'Present', icon: <Icon name="check" size={16} /> },
+        { value: 'late', text: 'Late', icon: <Icon name="clock-3" size={16} /> },
+        { value: 'absent', text: 'Absent', icon: <Icon name="x" size={16} /> },
+      ],
+      defaultValue: 'present',
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Icon, ToggleGroup } from '@arbor-education/design-system.components';
+
+const options = [
+  { value: 'present', text: 'Present', icon: <Icon name="check"   size={16} /> },
+  { value: 'late',    text: 'Late',    icon: <Icon name="clock-3" size={16} /> },
+  { value: 'absent',  text: 'Absent',  icon: <Icon name="x"       size={16} /> },
+];
+
+<ToggleGroup options={options} defaultValue="present" />
+`.trim(),
+        },
+      },
+    },
+  },
+  'Each option can include an `icon`. The icon renders to the left of the label text.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    args: {
+      options: attendanceOptions,
+      defaultValue: 'late',
+      disabled: true,
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+    },
+  },
+  'The entire group can be disabled with the `disabled` prop. Use when the field exists but cannot currently be changed.',
+);
+
+export const PartiallyDisabled: Story = withDescription(
+  {
+    args: {
+      options: [
+        { value: 'present', text: 'Present' },
+        { value: 'late', text: 'Late', disabled: true },
+        { value: 'absent', text: 'Absent' },
+      ],
+      defaultValue: 'present',
+      onValueChange: undefined,
+    },
+    parameters: {
+      controls: { disable: true },
+    },
+  },
+  'Individual options can be disabled by setting `disabled: true` on the option config.',
+);

package/src/components/toggleGroup/ToggleGroup.test.tsx

@@ -0,0 +1,155 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen, fireEvent } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom/vitest';
+import { ToggleGroup } from './ToggleGroup.js';
+
+const options = [
+  { value: 'present', text: 'Present', color: 'green' as const },
+  { value: 'late', text: 'Late', color: 'yellow' as const },
+  { value: 'absent', text: 'Absent', color: 'red' as const },
+];
+
+describe('ToggleGroup component', () => {
+  test('renders all options', () => {
+    render(<ToggleGroup options={options} />);
+    expect(screen.getByRole('group')).toBeInTheDocument();
+    expect(screen.getAllByRole('radio')).toHaveLength(3);
+  });
+
+  test('renders option text', () => {
+    render(<ToggleGroup options={options} />);
+    expect(screen.getByText('Present')).toBeInTheDocument();
+    expect(screen.getByText('Late')).toBeInTheDocument();
+    expect(screen.getByText('Absent')).toBeInTheDocument();
+  });
+
+  test('applies ds-toggle-group base class', () => {
+    render(<ToggleGroup options={options} />);
+    expect(screen.getByRole('group')).toHaveClass('ds-toggle-group');
+  });
+
+  test('applies additional className alongside base class', () => {
+    render(<ToggleGroup options={options} className="custom-class" />);
+    const group = screen.getByRole('group');
+    expect(group).toHaveClass('ds-toggle-group');
+    expect(group).toHaveClass('custom-class');
+  });
+
+  test('no option is selected by default', () => {
+    render(<ToggleGroup options={options} />);
+    screen.getAllByRole('radio').forEach((radio) => {
+      expect(radio).toHaveAttribute('data-state', 'off');
+    });
+  });
+
+  test('selects the option matching defaultValue in uncontrolled mode', () => {
+    render(<ToggleGroup options={options} defaultValue="late" />);
+    expect(screen.getByRole('radio', { name: 'Late' })).toHaveAttribute('data-state', 'on');
+    expect(screen.getByRole('radio', { name: 'Present' })).toHaveAttribute('data-state', 'off');
+  });
+
+  test('selects the option matching value in controlled mode', () => {
+    render(<ToggleGroup options={options} value="absent" onValueChange={vi.fn()} />);
+    expect(screen.getByRole('radio', { name: 'Absent' })).toHaveAttribute('data-state', 'on');
+  });
+
+  test('calls onValueChange with the clicked option value', () => {
+    const handleChange = vi.fn();
+    render(<ToggleGroup options={options} value="" onValueChange={handleChange} />);
+    fireEvent.click(screen.getByRole('radio', { name: 'Present' }));
+    expect(handleChange).toHaveBeenCalledTimes(1);
+    expect(handleChange).toHaveBeenCalledWith('present');
+  });
+
+  test('applies color class for green option when selected', () => {
+    render(<ToggleGroup options={options} value="present" onValueChange={vi.fn()} />);
+    expect(screen.getByRole('radio', { name: 'Present' })).toHaveClass(
+      'ds-toggle-group__item--green',
+    );
+  });
+
+  test('applies color class for yellow option when selected', () => {
+    render(<ToggleGroup options={options} value="late" onValueChange={vi.fn()} />);
+    expect(screen.getByRole('radio', { name: 'Late' })).toHaveClass(
+      'ds-toggle-group__item--yellow',
+    );
+  });
+
+  test('applies color class for red option when selected', () => {
+    render(<ToggleGroup options={options} value="absent" onValueChange={vi.fn()} />);
+    expect(screen.getByRole('radio', { name: 'Absent' })).toHaveClass(
+      'ds-toggle-group__item--red',
+    );
+  });
+
+  test('does not apply a color class when the option is not selected', () => {
+    render(<ToggleGroup options={options} value="absent" onValueChange={vi.fn()} />);
+    const present = screen.getByRole('radio', { name: 'Present' });
+    expect(present).not.toHaveClass('ds-toggle-group__item--green');
+  });
+
+  test('does not apply a color class when no color is provided', () => {
+    const noColorOptions = [{ value: 'yes', text: 'Yes' }, { value: 'no', text: 'No' }];
+    render(<ToggleGroup options={noColorOptions} value="yes" onValueChange={vi.fn()} />);
+    const yes = screen.getByRole('radio', { name: 'Yes' });
+    expect(yes).not.toHaveClass('ds-toggle-group__item--green');
+    expect(yes).not.toHaveClass('ds-toggle-group__item--yellow');
+    expect(yes).not.toHaveClass('ds-toggle-group__item--red');
+  });
+
+  test('disables the whole group when disabled prop is set', () => {
+    render(<ToggleGroup options={options} disabled />);
+    screen.getAllByRole('radio').forEach((radio) => {
+      expect(radio).toBeDisabled();
+    });
+  });
+
+  test('disables a single option when its disabled prop is set', () => {
+    const mixedOptions = [
+      { value: 'a', text: 'A', color: 'green' as const },
+      { value: 'b', text: 'B', color: 'red' as const, disabled: true },
+    ];
+    render(<ToggleGroup options={mixedOptions} />);
+    expect(screen.getByRole('radio', { name: 'B' })).toBeDisabled();
+    expect(screen.getByRole('radio', { name: 'A' })).not.toBeDisabled();
+  });
+
+  test('does not deselect an active option when clicked again', () => {
+    const handleChange = vi.fn();
+    render(<ToggleGroup options={options} value="present" onValueChange={handleChange} />);
+    fireEvent.click(screen.getByRole('radio', { name: 'Present' }));
+    expect(handleChange).not.toHaveBeenCalled();
+    expect(screen.getByRole('radio', { name: 'Present' })).toHaveAttribute('data-state', 'on');
+  });
+
+  test('renders an icon when provided', () => {
+    const withIcon = [{ value: 'x', text: 'X', icon: <svg data-testid="test-icon" /> }];
+    render(<ToggleGroup options={withIcon} />);
+    expect(screen.getByTestId('test-icon')).toBeInTheDocument();
+  });
+
+  describe('keyboard navigation', () => {
+    test('all items are individually reachable via Tab', async () => {
+      const user = userEvent.setup();
+      render(
+        <div>
+          <button>Before</button>
+          <ToggleGroup options={options} value="late" onValueChange={vi.fn()} />
+        </div>,
+      );
+
+      await user.tab();
+      expect(document.activeElement).toHaveTextContent('Before');
+
+      await user.tab();
+      expect(document.activeElement).toBe(screen.getByRole('radio', { name: 'Present' }));
+
+      await user.tab();
+      expect(document.activeElement).toBe(screen.getByRole('radio', { name: 'Late' }));
+
+      await user.tab();
+      expect(document.activeElement).toBe(screen.getByRole('radio', { name: 'Absent' }));
+    });
+  });
+});

package/src/components/toggleGroup/ToggleGroup.tsx

@@ -0,0 +1,74 @@
+import { useState, type KeyboardEventHandler } from 'react';
+import classNames from 'classnames';
+import { ToggleGroup as RadixToggleGroup, type ToggleGroupSingleProps } from '@radix-ui/react-toggle-group';
+import { ToggleGroupItem, type ToggleGroupItemProps, type ToggleGroupItemColor } from './ToggleGroupItem.js';
+
+type ControlledProps = {
+  value: string;
+  onValueChange: (value: string) => void;
+  defaultValue?: never;
+};
+
+type UncontrolledProps = {
+  defaultValue?: string;
+  value?: never;
+  onValueChange?: never;
+};
+
+type BaseProps = Omit<ToggleGroupSingleProps, 'type' | 'value' | 'onValueChange' | 'defaultValue'> & {
+  options: ToggleGroupItemProps[];
+  onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+};
+
+export type ToggleGroupProps = BaseProps & (ControlledProps | UncontrolledProps);
+
+const isControlled = (props: ToggleGroupProps): props is ControlledProps & ToggleGroupProps =>
+  props.value !== undefined;
+
+export const ToggleGroup = (props: ToggleGroupProps) => {
+  const { options, className, value, defaultValue, onValueChange, onKeyDown, ...radixToggleGroupProps } = props;
+  const [internalValue, setInternalValue] = useState<string | undefined>(
+    isControlled(props) ? undefined : defaultValue,
+  );
+  const selectedValue = isControlled(props) ? value : internalValue;
+
+  const handleValueChange = (newValue: string) => {
+    if (!newValue) {
+      return;
+    }
+    if (isControlled(props)) {
+      onValueChange?.(newValue);
+    }
+    else {
+      setInternalValue(newValue);
+    }
+  };
+
+  return (
+    <RadixToggleGroup
+      {...radixToggleGroupProps}
+      type="single"
+      rovingFocus={false}
+      className={classNames('ds-toggle-group', className)}
+      value={selectedValue}
+      onValueChange={handleValueChange}
+      onKeyDown={onKeyDown}
+    >
+      {options.map(({ ...itemProps }) => (
+        <ToggleGroupItem
+          {...itemProps}
+          key={itemProps.value}
+          isActive={itemProps.value === selectedValue}
+        />
+      ))}
+    </RadixToggleGroup>
+  );
+};
+
+ToggleGroup.Item = ToggleGroupItem;
+
+export namespace ToggleGroup {
+  export type Props = ToggleGroupProps;
+  export type ItemProps = ToggleGroupItemProps;
+  export type ItemColor = ToggleGroupItemColor;
+}

package/src/components/toggleGroup/ToggleGroupItem.tsx

@@ -0,0 +1,24 @@
+import { Item, type ToggleGroupItemProps as RadixToggleGroupItemProps } from '@radix-ui/react-toggle-group';
+import { Button } from 'Components/button/Button';
+
+export type ToggleGroupItemColor = 'red' | 'yellow' | 'green';
+
+export type ToggleGroupItemProps = {
+  text: string;
+  color?: ToggleGroupItemColor;
+  icon?: React.ReactNode;
+  isActive?: boolean;
+} & RadixToggleGroupItemProps;
+
+export const ToggleGroupItem = ({ text, color, icon, isActive = false, ...radixProps }: ToggleGroupItemProps) => (
+  <Item {...radixProps} asChild>
+    <Button
+      className={isActive && color ? `ds-toggle-group__item--${color}` : undefined}
+      borderless
+      variant={isActive ? 'primary' : 'secondary'}
+    >
+      {icon}
+      {text}
+    </Button>
+  </Item>
+);