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

package/src/components/row/Row.test.tsx

@@ -43,6 +43,31 @@ describe('Row component', () => {
     expect(row).toHaveClass('ds-row', 'custom-row');
   });
 
+  describe('href behaviour', () => {
+    test('wraps value in an anchor when href is provided', () => {
+      render(<Row label="Profile" value="View profile" href="/students/123" />);
+
+      const link = screen.getByRole('link', { name: 'View profile' });
+      expect(link).toBeInTheDocument();
+      expect(link).toHaveAttribute('href', '/students/123');
+    });
+
+    test('uses href as link text when no value is provided', () => {
+      render(<Row label="Document" href="/documents/report.pdf" />);
+
+      const link = screen.getByRole('link', { name: '/documents/report.pdf' });
+      expect(link).toBeInTheDocument();
+      expect(link).toHaveAttribute('href', '/documents/report.pdf');
+    });
+
+    test('renders value as plain text when href is not provided', () => {
+      render(<Row label="Profile" value="View profile" />);
+
+      expect(screen.getByText('View profile')).toBeInTheDocument();
+      expect(screen.queryByRole('link')).not.toBeInTheDocument();
+    });
+  });
+
   describe('click behaviour', () => {
     test('calls onClick handler when clicked', () => {
       const handleClick = vi.fn();
@@ -79,4 +104,27 @@ describe('Row component', () => {
       expect(handleClick.mock.calls[0]?.[0]).toBeDefined();
     });
   });
+
+  describe('ReactNode content', () => {
+    test('accepts ReactNode label', () => {
+      render(<Row label={<span className="foo">bar</span>} />);
+      const label = screen.getByText('bar');
+      expect(label).toBeInTheDocument();
+      expect(label).toHaveClass('foo');
+    });
+
+    test('accepts ReactNode value', () => {
+      render(<Row value={<span className="foo">bar</span>} />);
+      const value = screen.getByText('bar');
+      expect(value).toBeInTheDocument();
+      expect(value).toHaveClass('foo');
+    });
+
+    test('accepts ReactNode note', () => {
+      render(<Row note={<span className="foo">bar</span>} />);
+      const note = screen.getByText('bar');
+      expect(note).toBeInTheDocument();
+      expect(note).toHaveClass('foo');
+    });
+  });
 });

package/src/components/row/Row.tsx

@@ -1,14 +1,15 @@
 import classNames from 'classnames';
 import { Icon } from 'Components/icon/Icon';
-import type { CSSProperties, MouseEvent, MouseEventHandler } from 'react';
+import type { CSSProperties, MouseEvent, MouseEventHandler, ReactNode } from 'react';
 import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
 
 export type RowProps = {
   className?: string;
   style?: CSSProperties;
-  label?: string;
-  value?: string;
-  note?: string;
+  label?: ReactNode;
+  value?: ReactNode;
+  href?: string;
+  note?: ReactNode;
   onClick?: MouseEventHandler<HTMLDivElement>;
 };
 
@@ -18,6 +19,7 @@ export const Row = (props: RowProps) => {
     style,
     label,
     value,
+    href,
     note,
     onClick,
   } = props;
@@ -44,7 +46,15 @@ export const Row = (props: RowProps) => {
       tabIndex={isClickable ? 0 : -1}
     >
       <span className="ds-row__label">{label}</span>
-      <span className="ds-row__value">{value}</span>
+      <span className="ds-row__value">
+        {href
+          ? (
+              <a href={href}>
+                {value || href}
+              </a>
+            )
+          : value}
+      </span>
       <span className="ds-row__note">{note}</span>
       {isClickable && (
         <>

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' }));
+    });
+  });
+});