@arbor-education/design-system.components 4.9.1 → 5.0.0

package/src/components/kvpList/KVPList.stories.tsx

@@ -33,6 +33,7 @@ const TERM_PROPS = [
   '| Prop | Type | Default | Description |',
   '|---|---|---|---|',
   '| `children` | `ReactNode` | — | The key/label text |',
+  '| `prominence` | `\'neutral\' \\| \'strong\'` | `\'neutral\'` | `neutral` = body text; `strong` = bold body weight, e.g. a totals row label |',
   '| `className` | `string` | — | Additional CSS classes on the `<dt>` element |',
   '| `...HTMLAttributes<dt>` | | | All standard element attributes forwarded |',
 ].join('\n');
@@ -372,6 +373,59 @@ export default StrongProminenceExample;
   '`prominence="strong"` applies h2-scale typography to the definition — rendered as `<dd>` semantically but visually dominant. Use for the primary metric value in a list; `"neutral"` for supporting context.',
 );
 
+export const TotalsRow: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { KVPList } from '@arbor-education/design-system.components';
+
+function TotalsRowExample() {
+  return (
+    <KVPList aria-label="Basket totals">
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Subtotal</KVPList.Term>
+        <KVPList.Definition>£40.00</KVPList.Definition>
+      </KVPList.Row>
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term>Delivery</KVPList.Term>
+        <KVPList.Definition>£2.00</KVPList.Definition>
+      </KVPList.Row>
+      <KVPList.Row orientation="horizontal">
+        <KVPList.Term prominence="strong">Total</KVPList.Term>
+        <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+      </KVPList.Row>
+    </KVPList>
+  );
+}
+export default TotalsRowExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <KVPList aria-label="Basket totals">
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Subtotal</KVPList.Term>
+          <KVPList.Definition>£40.00</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term>Delivery</KVPList.Term>
+          <KVPList.Definition>£2.00</KVPList.Definition>
+        </KVPList.Row>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>
+    ),
+  },
+  '`prominence="strong"` on `KVPList.Term` applies the bold body weight token (`--type-body-bold-weight`) so the label of a totals row balances a strong definition. Unemphasised terms are unchanged.',
+);
+
 export const IsRow: Story = withDescription(
   {
     parameters: {

package/src/components/kvpList/KVPList.test.tsx

@@ -51,6 +51,58 @@ describe('KVPList', () => {
     expect(container.querySelector('.ds-kvp-list__description--row')).toBeInTheDocument();
   });
 
+  test('applies the strong modifier to a term with strong prominence', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Total')).toHaveClass('ds-kvp-list__term', 'ds-kvp-list__term--strong');
+  });
+
+  test('does not forward prominence to the term element', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="strong">Total</KVPList.Term>
+          <KVPList.Definition prominence="strong">£42.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Total')).not.toHaveAttribute('prominence');
+  });
+
+  test('leaves a term without prominence unchanged', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term className="custom-term">Subtotal</KVPList.Term>
+          <KVPList.Definition>£40.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Subtotal')).toHaveAttribute('class', 'ds-kvp-list__term custom-term');
+  });
+
+  test('leaves a term with neutral prominence unchanged', () => {
+    render(
+      <KVPList>
+        <KVPList.Row orientation="horizontal">
+          <KVPList.Term prominence="neutral">Delivery</KVPList.Term>
+          <KVPList.Definition>£2.00</KVPList.Definition>
+        </KVPList.Row>
+      </KVPList>,
+    );
+
+    expect(screen.getByText('Delivery')).toHaveAttribute('class', 'ds-kvp-list__term');
+  });
+
   test('does not add group semantics when no accessible label is provided', () => {
     render(
       <KVPList>

package/src/components/kvpList/KVPList.tsx

@@ -11,6 +11,7 @@ export type KVPListRowProps = React.HTMLAttributes<HTMLDListElement> & {
 
 export type KVPListTermProps = React.HTMLAttributes<HTMLElement> & {
   children?: React.ReactNode;
+  prominence?: 'neutral' | 'strong';
 };
 
 export type KVPListDefinitionProps = React.HTMLAttributes<HTMLElement> & {
@@ -60,9 +61,17 @@ const KVPListRow = ({
 const KVPListTerm = ({
   children,
   className,
+  prominence = 'neutral',
   ...rest
 }: KVPListTermProps): React.JSX.Element => (
-  <dt className={classNames('ds-kvp-list__term', className)} {...rest}>
+  <dt
+    className={classNames(
+      'ds-kvp-list__term',
+      { 'ds-kvp-list__term--strong': prominence === 'strong' },
+      className,
+    )}
+    {...rest}
+  >
     {children}
   </dt>
 );

package/src/components/kvpList/kvpList.scss

@@ -21,6 +21,10 @@
   line-height: var(--type-body-line-height);
 }
 
+.ds-kvp-list__term--strong {
+  font-weight: var(--type-body-bold-weight);
+}
+
 .ds-kvp-list__description--strong {
   color: var(--kvp-list-color-text-strong);
   font-family: var(--type-headings-h2-family);

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

@@ -25,6 +25,7 @@ const DESCRIPTION_INTRO = [
   'Pass an `onClick` handler to make the row fully interactive — it enters the tab order, gains hover and focus styles, and renders a pair of animated directional icons.',
   'Pass `href` to turn the value into a native anchor link, supporting any protocol including `mailto:` and `tel:`.',
   'Pass `tooltipText` to show an explanatory tooltip when a user hovers the row — useful for read-only fields or values that need additional context.',
+  'Pass `isActive` to highlight the row as the one currently being worked on, for example the row a slideover was opened from.',
 ].join(' ');
 
 const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
@@ -60,6 +61,9 @@ const DEVELOPER_NOTES = [
   '| Static | `-1` (not in tab order) | — | None |',
   '| Clickable | `0` (in tab order) | `ds-row--clickable` | `chevron-right` + `arrow-right` |',
   '',
+  '`isActive` is independent of `onClick`: it adds the `ds-row--active` modifier and `aria-current="true"`, and can be combined with either state.',
+  'The active background is kept on hover so an active clickable row stays distinguishable from its siblings.',
+  '',
   '**Dual-icon swap:** Both icons are always in the DOM when `onClick` is provided. CSS controls visibility —',
   'at rest `chevron-right` shows; on hover/focus `arrow-right` shows. No JavaScript state is involved.',
   '',
@@ -109,6 +113,7 @@ const DEVELOPER_NOTES = [
   '|---|---|',
   '| `--section-list-row-default-color-background` | Resting background colour |',
   '| `--section-list-row-hover-hover-bg` | Hover background (clickable rows only) |',
+  '| `--section-list-row-active-active-bg` | Background of an active row (`isActive`), including on hover |',
   '| `--section-list-row-spacing-vertical` | Top/bottom padding |',
   '| `--section-list-row-spacing-horizontal` | Left/right padding |',
   '| `--section-list-row-radius` | Border radius |',
@@ -133,6 +138,7 @@ const DEVELOPER_NOTES = [
   '  note?: ReactNode;',
   '  placeholder?: string;',
   '  tooltipText?: string;',
+  '  isActive?: boolean;',
   '  onClick?: MouseEventHandler<HTMLDivElement>;',
   '};',
   '```',
@@ -256,6 +262,18 @@ const meta = {
         defaultValue: { summary: 'undefined' },
       },
     },
+    isActive: {
+      description: [
+        'Marks the row as the currently active or selected row, such as the row a slideover was opened from.',
+        'Adds the `ds-row--active` modifier and `aria-current="true"`, and applies the `--section-list-row-active-active-bg` background, which is kept on hover.',
+        'Combine with `onClick` for an active row that is also clickable.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
     onClick: {
       description: [
         'When provided, activates all clickable behaviour: the row enters the tab order (`tabIndex={0}`),',
@@ -757,6 +775,51 @@ export default GuardianRow;
   'Clickable row with all three right-side elements active: value, note, and the chevron/arrow icon pair. The note takes 20% flex-basis; the value narrows to 50%; the icon is flex-shrunk. The secondary context ("Primary contact") persists alongside the navigation affordance.',
 );
 
+export const Active: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row, Section } from '@arbor-education/design-system.components';
+
+function GuardianSection({ activeGuardianId, openGuardian }) {
+  return (
+    <Section title="Guardians">
+      <Row
+        label="Mother"
+        value="Sarah Okafor"
+        isActive={activeGuardianId === 'guardian-42'}
+        onClick={() => openGuardian('guardian-42')}
+      />
+      <Row
+        label="Father"
+        value="David Okafor"
+        isActive={activeGuardianId === 'guardian-43'}
+        onClick={() => openGuardian('guardian-43')}
+      />
+      <Row label="Emergency contact" value="Grace Mensah" isActive={false} />
+    </Section>
+  );
+}
+export default GuardianSection;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Section title="Guardians">
+        <Row label="Mother" value="Sarah Okafor" isActive onClick={fn()} />
+        <Row label="Father" value="David Okafor" onClick={fn()} />
+        <Row label="Emergency contact" value="Grace Mensah" />
+      </Section>
+    ),
+  },
+  'Set `isActive` to highlight the row currently being worked on — for example the row a slideover was opened from. The first row is active **and** clickable: it keeps the active background on hover, retains its focus ring and keyboard activation, and exposes `aria-current="true"`. The other rows render exactly as they do without the prop.',
+);
+
 export const MixedClickableAndStatic: Story = withDescription(
   {
     parameters: {

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

@@ -106,6 +106,65 @@ describe('Row component', () => {
     });
   });
 
+  describe('active behaviour', () => {
+    test('applies the active modifier when isActive is true', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveClass('ds-row--active');
+    });
+
+    test('marks an active row as the current item for assistive technology', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveAttribute('aria-current', 'true');
+    });
+
+    test('does not apply the active modifier when isActive is omitted', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" />);
+
+      const row = container.querySelector('.ds-row');
+      expect(row).not.toHaveClass('ds-row--active');
+      expect(row).not.toHaveAttribute('aria-current');
+    });
+
+    test('does not apply the active modifier when isActive is false', () => {
+      const { container } = render(<Row label="Guardian" value="Sarah Okafor" isActive={false} />);
+
+      expect(container.querySelector('.ds-row')).not.toHaveClass('ds-row--active');
+    });
+
+    test('keeps clickable behaviour on an active clickable row', async () => {
+      const handleClick = vi.fn();
+      const { container } = render(
+        <Row label="Guardian" value="Sarah Okafor" isActive onClick={handleClick} />,
+      );
+
+      const row = container.querySelector('.ds-row')!;
+      expect(row).toHaveClass('ds-row--active', 'ds-row--clickable');
+      expect(row).toHaveAttribute('tabindex', '0');
+
+      await userEvent.click(screen.getByText('Sarah Okafor'));
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('activates an active clickable row with the keyboard', async () => {
+      const handleClick = vi.fn();
+      render(<Row label="Guardian" value="Sarah Okafor" isActive onClick={handleClick} />);
+
+      await userEvent.tab();
+      await userEvent.keyboard('{Enter}');
+
+      expect(handleClick).toHaveBeenCalledTimes(1);
+    });
+
+    test('combines the active modifier with a custom className', () => {
+      const { container } = render(<Row label="Guardian" className="custom-row" isActive />);
+
+      expect(container.querySelector('.ds-row')).toHaveClass('ds-row', 'ds-row--active', 'custom-row');
+    });
+  });
+
   describe('placeholder behaviour', () => {
     test('renders placeholder text when no value is provided', () => {
       render(<Row label="Medical condition" placeholder="Not recorded" />);

package/src/components/row/Row.tsx

@@ -13,6 +13,7 @@ export type RowProps = {
   note?: ReactNode;
   placeholder?: string;
   tooltipText?: string;
+  isActive?: boolean;
   onClick?: MouseEventHandler<HTMLDivElement>;
 };
 
@@ -26,6 +27,7 @@ export const Row = (props: RowProps) => {
     note,
     placeholder,
     tooltipText,
+    isActive = false,
     onClick,
   } = props;
 
@@ -47,10 +49,12 @@ export const Row = (props: RowProps) => {
         'ds-row',
         {
           'ds-row--clickable': isClickable,
+          'ds-row--active': isActive,
         },
         className,
       )}
       style={style}
+      aria-current={isActive ? 'true' : undefined}
       onClick={onClick}
       onKeyDown={(e) => {
         if (isClickable && [ENTER_KEY, SPACE_KEY].includes(e.key)) {

package/src/components/row/row.scss

@@ -11,7 +11,6 @@
   .ds-row__icon-click {
     flex-shrink: 0;
     stroke: var(--section-list-row-default-color-icon-arrow);
-    
 
     &.ds-icon-arrow-right {
       display: none;
@@ -26,6 +25,11 @@
     }
   }
 
+  &--active,
+  &--active:hover {
+    background-color: var(--section-list-row-active-active-bg);
+  }
+
   &:focus {
     box-shadow: 0 0 0 3px var(--color-brand-300);
     outline: none;
@@ -34,7 +38,6 @@
   &:hover {
     .ds-row__icon-click {
         stroke: var(--section-list-row-hover-color-icon-arrow);
-      
 
       &.ds-icon-chevron-right {
         display: none;

package/src/components/table/cellEditors/NumberCellEditor.test.tsx

@@ -0,0 +1,74 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom/vitest';
+import { NumberCellEditor, type NumberCellEditorProps } from './NumberCellEditor.js';
+
+const createProps = (overrides: Partial<NumberCellEditorProps> = {}): NumberCellEditorProps => ({
+  value: undefined,
+  onValueChange: vi.fn(),
+  step: 1,
+  disableSpinners: true,
+  ...overrides,
+});
+
+const lastCommittedValue = (onValueChange: ReturnType<typeof vi.fn>) => (
+  onValueChange.mock.calls.at(-1)?.[0]
+);
+
+describe('NumberCellEditor', () => {
+  test('commits typed numbers unchanged when no min or max is supplied', async () => {
+    const onValueChange = vi.fn();
+    render(<NumberCellEditor {...createProps({ onValueChange })} />);
+
+    await userEvent.type(screen.getByRole('textbox'), '42');
+
+    expect(onValueChange).toHaveBeenCalledWith(4);
+    expect(onValueChange).toHaveBeenLastCalledWith(42);
+  });
+
+  test('commits the typed number on Enter when no min or max is supplied', async () => {
+    const onValueChange = vi.fn();
+    render(<NumberCellEditor {...createProps({ onValueChange })} />);
+
+    await userEvent.type(screen.getByRole('textbox'), '-1234.5{Enter}');
+
+    expect(lastCommittedValue(onValueChange)).toBe(-1234.5);
+  });
+
+  test('clamps to min and leaves values above min unchanged when only min is supplied', async () => {
+    const onValueChange = vi.fn();
+    render(<NumberCellEditor {...createProps({ onValueChange, min: 10 })} />);
+
+    await userEvent.type(screen.getByRole('textbox'), '5');
+    expect(lastCommittedValue(onValueChange)).toBe(10);
+
+    await userEvent.clear(screen.getByRole('textbox'));
+    await userEvent.type(screen.getByRole('textbox'), '500');
+    expect(lastCommittedValue(onValueChange)).toBe(500);
+  });
+
+  test('clamps to max and leaves values below max unchanged when only max is supplied', async () => {
+    const onValueChange = vi.fn();
+    render(<NumberCellEditor {...createProps({ onValueChange, max: 100 })} />);
+
+    await userEvent.type(screen.getByRole('textbox'), '500');
+    expect(lastCommittedValue(onValueChange)).toBe(100);
+
+    await userEvent.clear(screen.getByRole('textbox'));
+    await userEvent.type(screen.getByRole('textbox'), '-500');
+    expect(lastCommittedValue(onValueChange)).toBe(-500);
+  });
+
+  test('clamps out-of-range values when both min and max are supplied', async () => {
+    const onValueChange = vi.fn();
+    render(<NumberCellEditor {...createProps({ onValueChange, min: 0, max: 100 })} />);
+
+    await userEvent.type(screen.getByRole('textbox'), '-5');
+    expect(lastCommittedValue(onValueChange)).toBe(0);
+
+    await userEvent.clear(screen.getByRole('textbox'));
+    await userEvent.type(screen.getByRole('textbox'), '250{Enter}');
+    expect(lastCommittedValue(onValueChange)).toBe(100);
+  });
+});

package/src/components/table/cellEditors/NumberCellEditor.tsx

@@ -7,8 +7,8 @@ import {
 export type NumberCellEditorProps = {
   value: number | null | undefined;
   onValueChange: (value: number | null) => void;
-  min: number;
-  max: number;
+  min?: number;
+  max?: number;
   step: number;
   disableSpinners: boolean;
 };
@@ -21,8 +21,8 @@ export const NumberCellEditor = (props: NumberCellEditorProps) => {
   const {
     value,
     onValueChange,
-    min,
-    max,
+    min = -Infinity,
+    max = Infinity,
     step,
     disableSpinners,
   } = props;

package/src/utils/hooks/useIsControlledOnceSet.test.ts

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'vitest';
+import { renderHook } from '@testing-library/react';
+import { useIsControlledOnceSet } from './useIsControlledOnceSet.js';
+
+describe('useIsControlledOnceSet', () => {
+  test('is uncontrolled while no value has been received', () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useIsControlledOnceSet(value),
+      { initialProps: { value: undefined as Date | undefined } },
+    );
+
+    rerender({ value: undefined });
+
+    expect(result.current).toBe(false);
+  });
+
+  test('is controlled from the first render with a value', () => {
+    const { result } = renderHook(() => useIsControlledOnceSet(new Date(2026, 3, 14)));
+
+    expect(result.current).toBe(true);
+  });
+
+  test('becomes controlled when a value arrives after an empty mount', () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useIsControlledOnceSet(value),
+      { initialProps: { value: undefined as Date | undefined } },
+    );
+
+    rerender({ value: new Date(2026, 3, 14) });
+
+    expect(result.current).toBe(true);
+  });
+
+  test('stays controlled when the value is cleared', () => {
+    const { result, rerender } = renderHook(
+      ({ value }) => useIsControlledOnceSet(value),
+      { initialProps: { value: new Date(2026, 3, 14) as Date | undefined } },
+    );
+
+    rerender({ value: undefined });
+
+    expect(result.current).toBe(true);
+  });
+});

package/src/utils/hooks/useIsControlledOnceSet.ts

@@ -0,0 +1,13 @@
+import { useRef } from 'react';
+
+/**
+ * Treats a component as controlled from the first render that receives a `value`, so a later
+ * `undefined` means "controlled and empty" rather than reverting to uncontrolled.
+ */
+export const useIsControlledOnceSet = <T>(value: T | undefined) => {
+  const hasReceivedValueRef = useRef(value !== undefined);
+  if (value !== undefined) {
+    hasReceivedValueRef.current = true;
+  }
+  return hasReceivedValueRef.current;
+};