@arbor-education/design-system.components 0.25.6 → 0.25.8

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/Table.stories.tsx

@@ -87,6 +87,7 @@ const DEVELOPER_NOTES = [
   '| `dsSelectDropdownCellRenderer` | `Table.SelectDropdownCellRenderer` | Renders a `SelectDropdown` in a cell |',
   '| `dsBooleanCellRenderer` | `Table.BooleanCellRenderer` | Read-only boolean display |',
   '| `dsCheckboxCellRenderer` | `Table.CheckboxCellRenderer` | Editable boolean checkbox |',
+  '| `dsNumberInputCellRenderer` | `Table.NumberInputCellRenderer` | Editable numeric input |',
   '| `dsDateCellEditor` | `Table.DateCellEditor` | Date picker cell editor |',
   '',
   '---',
@@ -2408,4 +2409,48 @@ export const WithComboboxCellRenderer: Story = {
   },
 };
 
+const numberInputSampleData = [
+  { name: 'Alice Johnson', sessions: 12, score: 95 },
+  { name: 'Bob Smith', sessions: 8, score: 72 },
+  { name: 'Charlie Brown', sessions: 15, score: 88 },
+  { name: 'Diana Prince', sessions: 3, score: 60 },
+];
+
+const numberInputColDefs: (ColDef | ColGroupDef)[] = [
+  { field: 'name', headerName: 'Name', flex: 2 },
+  {
+    field: 'sessions',
+    headerName: 'Sessions',
+    flex: 1,
+    editable: false,
+    cellRenderer: 'dsNumberInputCellRenderer',
+    cellRendererParams: { min: 0, suppressCellFocusAndFocusFirstElement: true },
+  },
+  {
+    field: 'score',
+    headerName: 'Score (/100)',
+    flex: 1,
+    editable: false,
+    cellRenderer: 'dsNumberInputCellRenderer',
+    cellRendererParams: { min: 0, max: 100, suppressCellFocusAndFocusFirstElement: true },
+  },
+];
+
+export const WithNumberInputCellRenderer: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Columns can use the `dsNumberInputCellRenderer` cell renderer to display an editable numeric input inside the cell. Pass `min` and `max` via `cellRendererParams` to constrain the allowed range — the spinners disable at the bounds.',
+      },
+    },
+  },
+  args: {
+    rowData: numberInputSampleData,
+    columnDefs: numberInputColDefs,
+    defaultColDef,
+    domLayout: 'autoHeight',
+  },
+};
+
 export default meta;

package/src/components/table/Table.tsx

@@ -35,6 +35,7 @@ import { BooleanCellRenderer } from './cellRenderers/BooleanCellRenderer.js';
 import { CheckboxCellRenderer } from './cellRenderers/CheckboxCellRenderer.js';
 import { ComboboxCellRenderer } from './cellRenderers/ComboboxCellRenderer.js';
 import { DefaultCellRenderer } from './cellRenderers/DefaultCellRenderer.js';
+import { NumberInputCellRenderer } from './cellRenderers/NumberInputCellRenderer.js';
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 type TableProps<TData = any> = {
@@ -210,6 +211,7 @@ export const Table = (props: TableProps) => {
               dsCheckboxCellRenderer: CheckboxCellRenderer,
               dsBooleanCellRenderer: BooleanCellRenderer,
               dsComboboxCellRenderer: ComboboxCellRenderer,
+              dsNumberInputCellRenderer: NumberInputCellRenderer,
               ...components,
             }}
             {...rest}
@@ -245,6 +247,7 @@ Table.ComboboxCellRenderer = ComboboxCellRenderer;
 Table.DefaultValueFormatter = defaultValueFormatter;
 Table.TableSettingsDropdown = TableSettingsDropdown;
 Table.TableControls = TableControls;
+Table.NumberInputCellRenderer = NumberInputCellRenderer;
 
 Table.Spacing = TABLE_SPACING;
 Table.SettingsItems = TABLE_SETTINGS_ITEMS;