@arbor-education/design-system.components 0.25.5 → 0.25.7

package/src/components/grid/Grid.test.tsx

@@ -0,0 +1,67 @@
+import { expect, test, describe } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import { Grid } from './Grid.js';
+
+describe('Grid', () => {
+  test('renders govuk-main-wrapper class', () => {
+    const { container } = render(<Grid />);
+    expect(container.firstChild).toHaveClass('govuk-main-wrapper');
+  });
+
+  test('renders children', () => {
+    render(<Grid><span>School report</span></Grid>);
+    expect(screen.getByText('School report')).toBeInTheDocument();
+  });
+
+  test('merges custom className with govuk-main-wrapper', () => {
+    const { container } = render(<Grid className="my-layout" />);
+    expect(container.firstChild).toHaveClass('govuk-main-wrapper', 'my-layout');
+  });
+});
+
+describe('Grid.Row', () => {
+  test('renders govuk-grid-row class', () => {
+    const { container } = render(<Grid.Row />);
+    expect(container.firstChild).toHaveClass('govuk-grid-row');
+  });
+
+  test('renders children', () => {
+    render(<Grid.Row><span>Attendance data</span></Grid.Row>);
+    expect(screen.getByText('Attendance data')).toBeInTheDocument();
+  });
+
+  test('merges custom className with govuk-grid-row', () => {
+    const { container } = render(<Grid.Row className="my-row" />);
+    expect(container.firstChild).toHaveClass('govuk-grid-row', 'my-row');
+  });
+});
+
+describe('Grid.Column', () => {
+  test('defaults to govuk-grid-column-full when columnWidth is omitted', () => {
+    const { container } = render(<Grid.Column />);
+    expect(container.firstChild).toHaveClass('govuk-grid-column-full');
+  });
+
+  test('renders children', () => {
+    render(<Grid.Column columnWidth="full"><span>Student profile</span></Grid.Column>);
+    expect(screen.getByText('Student profile')).toBeInTheDocument();
+  });
+
+  test('merges custom className', () => {
+    const { container } = render(<Grid.Column columnWidth="full" className="my-col" />);
+    expect(container.firstChild).toHaveClass('govuk-grid-column-full', 'my-col');
+  });
+
+  test.each([
+    ['full', 'govuk-grid-column-full'],
+    ['one-half', 'govuk-grid-column-one-half'],
+    ['one-third', 'govuk-grid-column-one-third'],
+    ['two-thirds', 'govuk-grid-column-two-thirds'],
+    ['one-quarter', 'govuk-grid-column-one-quarter'],
+    ['three-quarters', 'govuk-grid-column-three-quarters'],
+  ] as const)('applies %s class for columnWidth="%s"', (width, expectedClass) => {
+    const { container } = render(<Grid.Column columnWidth={width} />);
+    expect(container.firstChild).toHaveClass(expectedClass);
+  });
+});

package/src/components/grid/Grid.tsx

@@ -0,0 +1,34 @@
+import classNames from 'classnames';
+import type { ReactNode } from 'react';
+import { GridRow } from './GridRow.js';
+import { GridColumn } from './GridColumn.js';
+
+export type GridProps = {
+  className?: string;
+  children?: ReactNode;
+};
+
+export const Grid = (props: GridProps) => {
+  const {
+    className,
+    children,
+  } = props;
+
+  return (
+    <div
+      className={classNames(
+        'govuk-main-wrapper',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+Grid.Row = GridRow;
+Grid.Column = GridColumn;
+
+export namespace Grid {
+  export type Props = GridProps;
+}

package/src/components/grid/GridColumn.tsx

@@ -0,0 +1,31 @@
+import classNames from 'classnames';
+import type { ReactNode } from 'react';
+
+export type GridColumnProps = {
+  className?: string;
+  children?: ReactNode;
+  columnWidth?: 'one-quarter' | 'three-quarters' | 'one-third' | 'two-thirds' | 'one-half' | 'full';
+};
+
+export const GridColumn = (props: GridColumnProps) => {
+  const {
+    className,
+    children,
+    columnWidth = 'full',
+  } = props;
+
+  return (
+    <div
+      className={classNames(
+        `govuk-grid-column-${columnWidth}`,
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+export namespace GridColumn {
+  export type Props = GridColumnProps;
+}

package/src/components/grid/GridRow.tsx

@@ -0,0 +1,29 @@
+import classNames from 'classnames';
+import type { ReactNode } from 'react';
+
+export type GridRowProps = {
+  className?: string;
+  children?: ReactNode;
+};
+
+export const GridRow = (props: GridRowProps) => {
+  const {
+    className,
+    children,
+  } = props;
+
+  return (
+    <div
+      className={classNames(
+        'govuk-grid-row',
+        className,
+      )}
+    >
+      {children}
+    </div>
+  );
+};
+
+export namespace GridRow {
+  export type Props = GridRowProps;
+}

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

@@ -24,6 +24,7 @@ const DESCRIPTION_INTRO = [
   '`Row` is a single-line display component for presenting a labelled piece of data inside summary panels, detail cards, or section-style layouts.',
   '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.',
 ].join(' ');
 
 const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — tweak any prop to see the story update in real time.';
@@ -130,6 +131,8 @@ const DEVELOPER_NOTES = [
   '  value?: ReactNode;',
   '  href?: string;',
   '  note?: ReactNode;',
+  '  placeholder?: string;',
+  '  tooltipText?: string;',
   '  onClick?: MouseEventHandler<HTMLDivElement>;',
   '};',
   '```',
@@ -229,6 +232,30 @@ const meta = {
         defaultValue: { summary: 'undefined' },
       },
     },
+    tooltipText: {
+      description: [
+        'When provided, wraps the row in a `Tooltip` and shows this string as the tooltip content on hover.',
+        'Use it to surface contextual help for read-only fields, abbreviations, or values that benefit from further explanation.',
+        'Omit the prop (or pass `undefined`) when no tooltip is needed — the Tooltip wrapper is still rendered but remains invisible.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    placeholder: {
+      description: [
+        'Fallback text shown in the value slot when no `value` prop is provided.',
+        'Rendered in italics to signal that no real data is set.',
+        'Ignored when `value` is present — `value` always takes precedence.',
+      ].join(' '),
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
     onClick: {
       description: [
         'When provided, activates all clickable behaviour: the row enters the tab order (`tabIndex={0}`),',
@@ -426,6 +453,74 @@ export default ActiveStatusRow;
   'A value with no label — the label column renders empty. Valid but uncommon; most real-world rows pair a label with every value.',
 );
 
+export const WithPlaceholder: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function MedicalConditionRow() {
+  return (
+    <Row
+      label="Medical condition"
+      placeholder="Not recorded"
+    />
+  );
+}
+export default MedicalConditionRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Row
+        label="Medical condition"
+        placeholder="Not recorded"
+      />
+    ),
+  },
+  'When `placeholder` is provided and no `value` is set, the placeholder renders in the value slot with italic styling — visually distinct from real data. Use it for optional fields where an empty state is meaningful (e.g. "Not recorded", "Not applicable").',
+);
+
+export const PlaceholderIgnoredWhenValuePresent: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function MedicalConditionRow() {
+  return (
+    <Row
+      label="Medical condition"
+      value="Asthma"
+      placeholder="Not recorded"
+    />
+  );
+}
+export default MedicalConditionRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Row
+        label="Medical condition"
+        value="Asthma"
+        placeholder="Not recorded"
+      />
+    ),
+  },
+  'When both `value` and `placeholder` are provided, `value` always wins — the placeholder is never shown. Consumers can safely pass a `placeholder` as a permanent fallback without needing to conditionally omit it when data is present.',
+);
+
 export const WithNote: Story = withDescription(
   {
     parameters: {
@@ -997,6 +1092,52 @@ import { Row } from '@arbor-education/design-system.components';
   ].join(' '),
 );
 
+export const WithTooltip: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Row } from '@arbor-education/design-system.components';
+
+function ReadOnlyRow() {
+  return (
+    <Row
+      label="UPN"
+      value="A823456789012"
+      tooltipText="Unique Pupil Number — assigned by the DfE and cannot be changed here"
+    />
+  );
+}
+export default ReadOnlyRow;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <div style={{ display: 'flex', flexDirection: 'column', gap: 'var(--spacing-small)' }}>
+        <Row
+          label="UPN"
+          value="A823456789012"
+          tooltipText="Unique Pupil Number — assigned by the DfE and cannot be changed here"
+        />
+        <Row
+          label="Admission number"
+          value="001847"
+          tooltipText="Set at admission — contact the office to request a change"
+        />
+        <Row
+          label="Year group"
+          value="Year 9"
+        />
+      </div>
+    ),
+  },
+  'Hover either of the first two rows to see the tooltip. The third row has no `tooltipText` — hovering it shows nothing. Use `tooltipText` to clarify read-only fields, abbreviations, or values that benefit from a short explanation without cluttering the label column.',
+);
+
 export const CustomClassAndStyle: Story = withDescription(
   {
     parameters: {

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

@@ -1,5 +1,6 @@
 import { expect, test, describe, vi } from 'vitest';
-import { render, screen, fireEvent } from '@testing-library/react';
+import { render, screen, fireEvent, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
 import { Row } from './Row.js';
 import '@testing-library/jest-dom/vitest';
 
@@ -105,6 +106,58 @@ describe('Row component', () => {
     });
   });
 
+  describe('placeholder behaviour', () => {
+    test('renders placeholder text when no value is provided', () => {
+      render(<Row label="Medical condition" placeholder="Not recorded" />);
+
+      expect(screen.getByText('Not recorded')).toBeInTheDocument();
+    });
+
+    test('renders placeholder element when no value is provided', () => {
+      const { container } = render(<Row placeholder="Not recorded" />);
+
+      expect(container.querySelector('.ds-row__placeholder')).toBeInTheDocument();
+    });
+
+    test('renders value instead of placeholder when both are provided', () => {
+      render(<Row value="Asthma" placeholder="Not recorded" />);
+
+      expect(screen.getByText('Asthma')).toBeInTheDocument();
+      expect(screen.queryByText('Not recorded')).not.toBeInTheDocument();
+    });
+
+    test('renders value element (not placeholder element) when both are provided', () => {
+      const { container } = render(<Row value="Asthma" placeholder="Not recorded" />);
+
+      expect(container.querySelector('.ds-row__value')).toBeInTheDocument();
+      expect(container.querySelector('.ds-row__placeholder')).not.toBeInTheDocument();
+    });
+
+    test('does not render placeholder element when placeholder is not provided', () => {
+      const { container } = render(<Row label="Medical condition" />);
+
+      expect(container.querySelector('.ds-row__placeholder')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('tooltip behaviour', () => {
+    test('shows tooltip text when hovering the row', async () => {
+      render(<Row label="Year group" value="Year 9" tooltipText="This field is read-only" />);
+
+      await userEvent.hover(screen.getByText('Year group'));
+
+      await waitFor(() => {
+        expect(screen.getAllByText('This field is read-only')[0]).toBeInTheDocument();
+      });
+    });
+
+    test('does not render tooltip text when tooltipText is not provided', () => {
+      render(<Row label="Year group" value="Year 9" />);
+
+      expect(screen.queryByText('This field is read-only')).not.toBeInTheDocument();
+    });
+  });
+
   describe('ReactNode content', () => {
     test('accepts ReactNode label', () => {
       render(<Row label={<span className="foo">bar</span>} />);

package/src/components/row/Row.tsx

@@ -1,5 +1,6 @@
 import classNames from 'classnames';
 import { Icon } from 'Components/icon/Icon';
+import { TooltipWrapper } from 'Components/tooltip/TooltipWrapper';
 import type { CSSProperties, MouseEvent, MouseEventHandler, ReactNode } from 'react';
 import { ENTER_KEY, SPACE_KEY } from 'Utils/keyboardConstants';
 
@@ -10,6 +11,8 @@ export type RowProps = {
   value?: ReactNode;
   href?: string;
   note?: ReactNode;
+  placeholder?: string;
+  tooltipText?: string;
   onClick?: MouseEventHandler<HTMLDivElement>;
 };
 
@@ -21,12 +24,24 @@ export const Row = (props: RowProps) => {
     value,
     href,
     note,
+    placeholder,
+    tooltipText,
     onClick,
   } = props;
 
   const isClickable = !!onClick;
 
-  return (
+  const shouldShowPlaceholder = !value && !href && !!placeholder;
+
+  const rowContent = href
+    ? (
+        <a href={href}>
+          {value || href}
+        </a>
+      )
+    : value;
+
+  const row = (
     <div
       className={classNames(
         'ds-row',
@@ -46,15 +61,9 @@ export const Row = (props: RowProps) => {
       tabIndex={isClickable ? 0 : -1}
     >
       <span className="ds-row__label">{label}</span>
-      <span className="ds-row__value">
-        {href
-          ? (
-              <a href={href}>
-                {value || href}
-              </a>
-            )
-          : value}
-      </span>
+      {shouldShowPlaceholder
+        ? <span className="ds-row__placeholder">{placeholder}</span>
+        : <span className="ds-row__value">{rowContent}</span>}
       <span className="ds-row__note">{note}</span>
       {isClickable && (
         <>
@@ -64,6 +73,16 @@ export const Row = (props: RowProps) => {
       )}
     </div>
   );
+
+  if (tooltipText) {
+    return (
+      <TooltipWrapper tooltipContent={tooltipText}>
+        {row}
+      </TooltipWrapper>
+    );
+  }
+
+  return row;
 };
 
 export namespace Row {

package/src/components/row/row.scss

@@ -61,6 +61,16 @@
     }
   }
 
+  &__placeholder {
+    flex-grow: 1;
+    flex-basis: 70%;
+    font-style: italic;
+
+    &:has(+ .ds-row__note) {
+      flex-basis: 50%;
+    }
+  }
+
   &__note {
     font-style: italic;
     flex-basis: 20%;

package/src/components/table/cellRenderers/SelectDropdownCellRenderer.stories.tsx

@@ -211,6 +211,14 @@ const meta = {
         defaultValue: { summary: 'false' },
       },
     },
+    onCloseAutoFocus: {
+      control: false,
+      description: 'Called when focus is about to return to the ag-grid cell after the dropdown closes (e.g. after selecting an option). Call `event.preventDefault()` to stop radix\'s default restore-to-cell behaviour and move focus elsewhere yourself.',
+      table: {
+        type: { summary: '(event: Event) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
   },
 } satisfies Meta<typeof SelectDropdownCellRenderer>;
 
@@ -718,3 +726,62 @@ const columnDefs = [
   },
   '(fillCell + colored) Marksheet with grade-driven cell colours. Each cell uses `backgroundColor` (derived per-row from the current grade) and `fillCell: true` so the colour spans the cell edge-to-edge, plus `cellStyle: { padding: 0 }` to strip ag-grid\'s default cell padding. `iconClickOnly: true` is set so cell selection works — click anywhere in a cell to select it (or shift/drag for a range), and only the chevron icon opens the grade picker. Text colour auto-switches between dark and white for legibility against each background.',
 );
+
+export const CustomCloseFocus: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const columnDefs = [
+  { field: 'name', headerName: 'Name', flex: 2 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    cellRenderer: 'dsSelectDropdownCellRenderer',
+    cellRendererParams: {
+      options: statusOptions,
+      onCloseAutoFocus: (event) => {
+        event.preventDefault();
+        window.alert('Dropdown closed — running custom focus handler');
+      },
+    },
+  },
+];
+
+<Table rowData={rowData} columnDefs={columnDefs} domLayout="autoHeight" />
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={SELECT_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'status',
+            headerName: 'Status',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsSelectDropdownCellRenderer',
+            cellRendererParams: {
+              options: STATUS_OPTIONS,
+              onCloseAutoFocus: (event: Event) => {
+                event.preventDefault();
+                window.alert('Dropdown closed — running custom focus handler');
+              },
+            },
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  'Passes `onCloseAutoFocus` via `cellRendererParams` to override what happens to focus when the dropdown closes. Open a Status dropdown and pick an option (or press Escape) — instead of radix restoring focus to the cell, the handler calls `event.preventDefault()` and fires a `window.alert`. In a real app you would move focus to a specific element here rather than alert.',
+);

package/src/components/table/cellRenderers/SelectDropdownCellRenderer.tsx

@@ -52,6 +52,7 @@ export const SelectDropdownCellRenderer = (
     backgroundColor,
     fillCell = false,
     iconClickOnly = false,
+    onCloseAutoFocus,
   } = props;
 
   const textContrast = backgroundColor ? getTextContrast(backgroundColor) : null;
@@ -113,6 +114,7 @@ export const SelectDropdownCellRenderer = (
         onOpenChange={setIsOpen}
         multiple={false}
         iconClickOnly={iconClickOnly}
+        onCloseAutoFocus={onCloseAutoFocus}
         onSelectionChange={(newValue) => {
           if (column && newValue[0] != null) {
             const selectedOption = rawOptions.find(

package/src/docs/Contributing.mdx

@@ -52,6 +52,8 @@ It also automatically adds the component's exports to `src/index.ts` and `src/in
 
 ## Key conventions
 
+Most of these are enforced automatically by ESLint — run `yarn eslint --fix` and let it guide you. A few the linter can't catch are worth knowing.
+
 ### File and directory naming
 
 <table>
@@ -97,6 +99,20 @@ import { Button } from '../../components/button/Button';  // ✗
   </tbody>
 </table>
 
+### Prefer team hooks
+
+Before writing your own hook, check `Utils/hooks` — reuse one that already exists, and reach for one that encapsulates a common pattern rather than hand-rolling it. For example, use `useComponentDidMount` for run-once-on-mount effects rather than `useEffect(fn, [])`. Always give `useEffect` a dependency array, even an empty one.
+
+### One component per file
+
+Keep one component per file. This applies to compound components too: define each part in its own file and assemble the public API in the root component's file by importing the parts. `Table` is a good example — it pulls in `TableHeader`, `TableFooter`, and its cell renderers from their own files. See the **Compound components** design principle below for the API pattern itself.
+
+### Keep comments rare and meaningful
+
+Good code is self-documenting, so comments should be the exception rather than the rule. Before writing one, make the code explain itself instead: choose descriptive names, and lift complex expressions or conditions into well-named constants. A clear name is worth more than a sentence describing it.
+
+Reserve comments for the _why_ behind something unusual — a constraint, a workaround, a non-obvious decision — never the _what_ the code already says plainly. If you feel the need to explain a piece of code, that's often a sign the code itself should be clearer. This matters especially for agent-assisted changes, which tend to over-narrate — strip the running commentary before opening a PR.
+
 ---
 
 ## Design principles

package/src/index.scss

@@ -1,4 +1,5 @@
 @use "../node_modules/react-day-picker/src/style.css";
+@use "../node_modules/govuk-frontend/dist/govuk/objects/grid.import.scss";
 @use "./tokens.scss";
 @use "./global.scss";
 @use "components/breadcrumbs/breadcrumbs.scss";

package/src/index.ts

@@ -89,3 +89,4 @@ export { SlideoverUtils } from 'Utils/SlideoverUtils';
 export { ArborLogo, type ArborLogoProps } from 'Components/arborLogo/ArborLogo';
 export { DataViewCard, type DataViewCardProps } from 'Components/dataViewCard/DataViewCard';
 export { FileUpload, type FileUploadProps } from 'Components/fileUpload/FileUpload';
+export { Grid, type GridProps } from 'Components/grid/Grid';