@arbor-education/design-system.components 3.2.0 → 3.2.1

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

@@ -320,13 +320,11 @@ const MixedClickableAndStaticTemplate = () => (
     <Row
       label="SEN status"
       value="SEN Support"
-      note="Review due May 2026"
       onClick={() => {}}
     />
     <Row
       label="Attendance (YTD)"
       value="88.3%"
-      note="Below 90% threshold"
       onClick={() => {}}
     />
   </Section>
@@ -778,13 +776,11 @@ function PupilDetailSection() {
       <Row
         label="SEN status"
         value="SEN Support"
-        note="Review due May 2026"
         onClick={() => navigateToSENRecord()}
       />
       <Row
         label="Attendance (YTD)"
         value="88.3%"
-        note="Below 90% threshold"
         onClick={() => navigateToAttendance()}
       />
     </Section>
@@ -832,7 +828,7 @@ export default PersonalDetailsSection;
     },
     render: InSectionTemplate,
   },
-  'The canonical real-world usage: `Row` components as children of a `Section`. The `Section` provides the container heading and background; each `Row` handles the label/value layout. Most product uses of `Row` are inside a `Section`.',
+  'The canonical real-world usage: `Row` components as children of a `Section`. The `Section` provides the container heading and background; each `Row` handles the label/value layout. Most product uses of `Row` are inside a `Section` — one row demonstrates a linked value via `href` to show that pattern working inside a realistic panel too.',
 );
 
 export const LongContent: Story = withDescription(
@@ -857,7 +853,6 @@ function LongContentExample() {
         label="Pupil premium eligibility reason"
         value="Free school meals — ever 6"
         note="Verified by LA"
-        onClick={() => navigateToEligibilityDetail()}
       />
     </div>
   );
@@ -878,7 +873,6 @@ export default LongContentExample;
           label="Pupil premium eligibility reason"
           value="Free school meals — ever 6"
           note="Verified by LA"
-          onClick={fn()}
         />
       </div>
     ),
@@ -1102,16 +1096,28 @@ export const WithTooltip: Story = withDescription(
           code: `
 import { Row } from '@arbor-education/design-system.components';
 
-function ReadOnlyRow() {
+function ReadOnlyRows() {
   return (
-    <Row
-      label="UPN"
-      value="A823456789012"
-      tooltipText="Unique Pupil Number — assigned by the DfE and cannot be changed here"
-    />
+    <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"
+      />
+      {/* No tooltipText — hovering this row shows nothing */}
+      <Row
+        label="Year group"
+        value="Year 9"
+      />
+    </div>
   );
 }
-export default ReadOnlyRow;
+export default ReadOnlyRows;
 `.trim(),
         },
       },

package/src/components/sidebar/Sidebar.stories.tsx

@@ -330,98 +330,53 @@ const DefaultTemplate = () => {
   );
 };
 
-const WithSeparatorsTemplate = () => {
-  const [active, setActive] = useState<string>('favourites');
-
-  return (
-    <div style={storyWrapperStyle}>
-      <Sidebar ariaLabel="App navigation">
-        <SidebarItem
-          aria-label="Favourites"
-          selected={active === 'favourites'}
-          onClick={() => setActive('favourites')}
-        >
-          <Icon name="favourite-outline" size={24} />
-        </SidebarItem>
-        <SidebarItem
-          aria-label="Notifications"
-          selected={active === 'notifications'}
-          onClick={() => setActive('notifications')}
-        >
-          <Icon name="message-square-more" size={24} />
-        </SidebarItem>
-        <SidebarItem
-          aria-label="My Calendar"
-          selected={active === 'calendar'}
-          onClick={() => setActive('calendar')}
-        >
-          <Icon name="date" size={24} />
-        </SidebarItem>
-        <Separator orientation="horizontal" decorative />
-        <SidebarItem
-          aria-label="Emergency Alerts"
-          selected={active === 'emergency'}
-          onClick={() => setActive('emergency')}
-        >
-          <Icon name="triangle-alert" size={24} />
-        </SidebarItem>
-        <Separator orientation="horizontal" decorative />
-        <SidebarItem
-          aria-label="Help & Learn with Arbor"
-          selected={active === 'help'}
-          onClick={() => setActive('help')}
-        >
-          <Icon name="circle-help" size={24} />
-        </SidebarItem>
-      </Sidebar>
-    </div>
-  );
-};
-
-const WithBadgeTemplate = () => {
-  const [active, setActive] = useState<string>('favourites');
+const WithSeparatorsTemplate = () => (
+  <div style={storyWrapperStyle}>
+    <Sidebar ariaLabel="App navigation">
+      <SidebarItem aria-label="Favourites">
+        <Icon name="favourite-outline" size={24} />
+      </SidebarItem>
+      <SidebarItem aria-label="Notifications">
+        <Icon name="message-square-more" size={24} />
+      </SidebarItem>
+      <SidebarItem aria-label="My Calendar">
+        <Icon name="date" size={24} />
+      </SidebarItem>
+      <Separator orientation="horizontal" decorative />
+      <SidebarItem aria-label="Emergency Alerts">
+        <Icon name="triangle-alert" size={24} />
+      </SidebarItem>
+      <Separator orientation="horizontal" decorative />
+      <SidebarItem aria-label="Help & Learn with Arbor">
+        <Icon name="circle-help" size={24} />
+      </SidebarItem>
+    </Sidebar>
+  </div>
+);
 
-  return (
-    <div style={storyWrapperStyle}>
-      <Sidebar ariaLabel="App navigation">
-        <SidebarItem
-          aria-label="Favourites"
-          selected={active === 'favourites'}
-          onClick={() => setActive('favourites')}
-        >
-          <Icon name="favourite-outline" size={24} />
-        </SidebarItem>
-        <SidebarItem
-          aria-label="Notifications — 6 unread"
-          selected={active === 'notifications'}
-          onClick={() => setActive('notifications')}
-        >
-          <Icon name="message-square-more" size={24} />
-          <Badge size="sm" colour="salmon">6</Badge>
-        </SidebarItem>
-        <SidebarItem
-          aria-label="Emergency Alerts — 2 active"
-          selected={active === 'emergency'}
-          onClick={() => setActive('emergency')}
-        >
-          <Icon name="triangle-alert" size={24} />
-          <Badge size="sm" colour="yellow">2</Badge>
-        </SidebarItem>
-        <SidebarItem
-          aria-label="My Calendar"
-          selected={active === 'calendar'}
-          onClick={() => setActive('calendar')}
-        >
-          <Icon name="date" size={24} />
-        </SidebarItem>
-      </Sidebar>
-    </div>
-  );
-};
+const WithBadgeTemplate = () => (
+  <div style={storyWrapperStyle}>
+    <Sidebar ariaLabel="App navigation">
+      <SidebarItem aria-label="Favourites">
+        <Icon name="favourite-outline" size={24} />
+      </SidebarItem>
+      <SidebarItem aria-label="Notifications — 6 unread">
+        <Icon name="message-square-more" size={24} />
+        <Badge size="sm" colour="salmon">6</Badge>
+      </SidebarItem>
+      <SidebarItem aria-label="Emergency Alerts — 2 active">
+        <Icon name="triangle-alert" size={24} />
+        <Badge size="sm" colour="yellow">2</Badge>
+      </SidebarItem>
+      <SidebarItem aria-label="My Calendar">
+        <Icon name="date" size={24} />
+      </SidebarItem>
+    </Sidebar>
+  </div>
+);
 
 const WithPanelTemplate = () => {
   const [open, setOpen] = useState(true);
-  const [active, setActive] = useState<string>('favourites');
 
   return (
     <div style={storyWrapperStyle}>
@@ -436,18 +391,10 @@ const WithPanelTemplate = () => {
           <Icon name="menu" size={24} />
         </SidebarItem>
         <Separator orientation="horizontal" decorative />
-        <SidebarItem
-          aria-label="Favourites"
-          selected={active === 'favourites'}
-          onClick={() => setActive('favourites')}
-        >
+        <SidebarItem aria-label="Favourites">
           <Icon name="favourite-outline" size={24} />
         </SidebarItem>
-        <SidebarItem
-          aria-label="My Calendar"
-          selected={active === 'calendar'}
-          onClick={() => setActive('calendar')}
-        >
+        <SidebarItem aria-label="My Calendar">
           <Icon name="date" size={24} />
         </SidebarItem>
       </Sidebar>
@@ -497,30 +444,28 @@ export const WithSeparators: Story = withDescription(
           language: 'tsx',
           code: `
 import { Sidebar, SidebarItem, Separator, Icon } from '@arbor-education/design-system.components';
-import { useState } from 'react';
 
 function WithSeparatorsExample() {
-  const [active, setActive] = useState('favourites');
   return (
     <Sidebar ariaLabel="App navigation">
       {/* Primary nav group */}
-      <SidebarItem aria-label="Favourites" selected={active === 'favourites'} onClick={() => setActive('favourites')}>
+      <SidebarItem aria-label="Favourites">
         <Icon name="favourite-outline" size={24} />
       </SidebarItem>
-      <SidebarItem aria-label="Notifications" selected={active === 'notifications'} onClick={() => setActive('notifications')}>
+      <SidebarItem aria-label="Notifications">
         <Icon name="message-square-more" size={24} />
       </SidebarItem>
-      <SidebarItem aria-label="My Calendar" selected={active === 'calendar'} onClick={() => setActive('calendar')}>
+      <SidebarItem aria-label="My Calendar">
         <Icon name="date" size={24} />
       </SidebarItem>
       <Separator orientation="horizontal" decorative />
       {/* Alert group */}
-      <SidebarItem aria-label="Emergency Alerts" selected={active === 'emergency'} onClick={() => setActive('emergency')}>
+      <SidebarItem aria-label="Emergency Alerts">
         <Icon name="triangle-alert" size={24} />
       </SidebarItem>
       <Separator orientation="horizontal" decorative />
       {/* Utility group */}
-      <SidebarItem aria-label="Help & Learn with Arbor" selected={active === 'help'} onClick={() => setActive('help')}>
+      <SidebarItem aria-label="Help & Learn with Arbor">
         <Icon name="circle-help" size={24} />
       </SidebarItem>
     </Sidebar>
@@ -532,7 +477,7 @@ export default WithSeparatorsExample;
       },
     },
   },
-  'Three groups divided by `<Separator orientation="horizontal" decorative />`. A common layout: primary nav / alerts / utility items. Click any item to see the active state.',
+  'Three groups divided by `<Separator orientation="horizontal" decorative />`: primary nav (Favourites, Notifications, My Calendar), alerts (Emergency Alerts), and utility (Help & Learn with Arbor).',
 );
 
 export const WithBadge: Story = withDescription(
@@ -545,27 +490,28 @@ export const WithBadge: Story = withDescription(
           language: 'tsx',
           code: `
 import { Sidebar, SidebarItem, Badge, Icon } from '@arbor-education/design-system.components';
-import { useState } from 'react';
 
 function WithBadgeExample() {
-  const [active, setActive] = useState('favourites');
   return (
     <Sidebar ariaLabel="App navigation">
-      <SidebarItem aria-label="Favourites" selected={active === 'favourites'} onClick={() => setActive('favourites')}>
+      <SidebarItem aria-label="Favourites">
         <Icon name="favourite-outline" size={24} />
       </SidebarItem>
       {/*
         Badge is automatically positioned top-right by sidebar.scss — no extra styling needed.
         Include the count in aria-label so screen reader users also receive the total.
       */}
-      <SidebarItem aria-label="Notifications — 6 unread" selected={active === 'notifications'} onClick={() => setActive('notifications')}>
+      <SidebarItem aria-label="Notifications — 6 unread">
         <Icon name="message-square-more" size={24} />
         <Badge size="sm" colour="salmon">6</Badge>
       </SidebarItem>
-      <SidebarItem aria-label="Emergency Alerts — 2 active" selected={active === 'emergency'} onClick={() => setActive('emergency')}>
+      <SidebarItem aria-label="Emergency Alerts — 2 active">
         <Icon name="triangle-alert" size={24} />
         <Badge size="sm" colour="yellow">2</Badge>
       </SidebarItem>
+      <SidebarItem aria-label="My Calendar">
+        <Icon name="date" size={24} />
+      </SidebarItem>
     </Sidebar>
   );
 }
@@ -607,9 +553,12 @@ function WithPanelExample() {
           <Icon name="menu" size={24} />
         </SidebarItem>
         <Separator orientation="horizontal" decorative />
-        <SidebarItem aria-label="Favourites" selected={false}>
+        <SidebarItem aria-label="Favourites">
           <Icon name="favourite-outline" size={24} />
         </SidebarItem>
+        <SidebarItem aria-label="My Calendar">
+          <Icon name="date" size={24} />
+        </SidebarItem>
       </Sidebar>
 
       {/* SideNavigation is a separate companion component — not a sub-component of Sidebar. */}

package/src/components/table/Table.stories.tsx

@@ -614,6 +614,31 @@ export const Default: Story = {
       rowSelection: ['2', '3'],
     },
     cellSelection: true,
+    headerContent: (
+      <TableControls
+        bulkActions={[
+          {
+            displayName: 'foo',
+            callback: (gridApi) => {
+              console.log('clicked on the foo action', gridApi);
+            },
+          },
+          {
+            displayName: 'bar',
+            callback: (gridApi) => {
+              console.log('clicked on the bar action', gridApi);
+            },
+            disabled: true,
+          },
+        ]}
+        showHideColumns
+        onDownload={() => console.log('download')}
+        showSettings
+        onHelp={() => console.log('help')}
+        onExpandToggle={expanded => console.log('expand', expanded)}
+      />
+    ),
+    footerContent,
   },
 };
 
@@ -1505,8 +1530,6 @@ export const WithValidation: Story = {
     columnDefs: colDefsWithValidation,
     defaultColDef: defaultColDef,
     domLayout: 'autoHeight',
-    rowSelection: { mode: 'multiRow', checkboxes: true },
-    cellSelection: true,
   },
 };
 
@@ -1552,8 +1575,6 @@ export const WithValidationClassesAdded: Story = {
     columnDefs: colDefsWithValidationClasses,
     defaultColDef: defaultColDef,
     domLayout: 'autoHeight',
-    rowSelection: { mode: 'multiRow', checkboxes: true },
-    cellSelection: true,
   },
 };
 
@@ -1719,10 +1740,6 @@ export const TidyTable: Story = {
       groupExpanded: '',
       groupContracted: '',
     },
-    rowSelection: {
-      mode: 'multiRow',
-      groupSelects: 'filteredDescendants',
-    },
     autoGroupColumnDef: {
       field: 'name',
       headerName: 'Marksheet Columns',
@@ -1841,7 +1858,6 @@ export const TableWithExplicitColours: Story = {
     ],
     columnDefs: sampleColumnDefs,
     defaultColDef,
-    headerContent,
     onCellValueChanged: (e) => {
       const { node, column, oldValue, newValue } = e;
       if (typeof oldValue === 'object' && 'value' in oldValue) {
@@ -1901,7 +1917,6 @@ export const TableWithSemanticColors: Story = {
     ],
     columnDefs: sampleColumnDefs,
     defaultColDef,
-    headerContent,
     domLayout: 'autoHeight',
     onCellValueChanged: (e) => {
       const { node, column, oldValue, newValue } = e;

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

@@ -24,7 +24,7 @@ const DESCRIPTION_INTRO = [
   'to update the row data in-place.',
   '',
   'Register it via `type: \'dsSelectDropdownColumn\'` on the column definition (pre-registered by Arbor\'s `Table`),',
-  'via the string key `dsSelectDropdownCellRenderer`, or by importing the component directly.',
+  'via the string key `dsSelectDropdownCellRenderer`, or via `Table.SelectDropdownCellRenderer`.',
 ].join('\n');
 
 const USAGE_GUIDANCE = [
@@ -49,8 +49,9 @@ const DEVELOPER_NOTES = [
   '',
   '**`api` is required.**',
   'The renderer attaches a `cellKeyDown` listener to the Grid API on mount so that pressing Enter',
-  'in the focused cell opens the dropdown. Without `api`, the keyboard shortcut is silently skipped',
-  'but the dropdown still renders and is clickable.',
+  'in the focused cell opens the dropdown. `api` is used unconditionally with no fallback — rendering',
+  'this component without a live `api` throws on mount. AG Grid always supplies `api` to cell renderers,',
+  'so this only matters if you render `SelectDropdownCellRenderer` outside of `AgGridReact` yourself.',
   '',
   '**`options` must be passed via `cellRendererParams`.**',
   'Options are not part of the cell `value` — configure them in `cellRendererParams`.',
@@ -89,7 +90,9 @@ const DEVELOPER_NOTES = [
   '### TypeScript types',
   '',
   '```ts',
-  "import { SelectDropdownCellRenderer } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'type SelectDropdownCellRendererProps = React.ComponentProps<typeof Table.SelectDropdownCellRenderer>;',
   '```',
   '',
   '`SelectDropdownCellRenderer` extends `CustomCellRendererProps` with `SelectDropdownInputProps`.',
@@ -715,7 +718,7 @@ 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.',
+  '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(

package/src/components/table/tableControls/TableControls.stories.tsx

@@ -65,7 +65,7 @@ const DEVELOPER_NOTES = [
   '### Wiring into `<Table />`',
   '',
   '```tsx',
-  "import { Table, TableControls } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
   '',
   'function MyTable() {',
   '  return (',
@@ -73,7 +73,7 @@ const DEVELOPER_NOTES = [
   '      rowData={rows}',
   '      columnDefs={colDefs}',
   '      headerContent={(',
-  '        <TableControls',
+  '        <Table.TableControls',
   '          bulkActions={[',
   '            { displayName: "Export selected", callback: api => exportCsv(api) },',
   '            { displayName: "Delete selected", callback: api => deleteRows(api) },',
@@ -93,16 +93,19 @@ const DEVELOPER_NOTES = [
   '',
   '---',
   '',
-  '### `BulkAction` type',
+  '### `Table.BulkAction` type',
   '',
   '```ts',
-  "import type { BulkAction } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
   '',
-  'type BulkAction = {',
-  '  displayName: string;',
-  '  callback: (gridApi: GridApi) => void;',
-  '  disabled?: boolean;',
-  '};',
+  'type MyAction = Table.BulkAction;',
+  '',
+  '// shape:',
+  '// {',
+  '//   displayName: string;',
+  '//   callback: (gridApi: GridApi) => void;',
+  '//   disabled?: boolean;',
+  '// }',
   '```',
   '',
   '---',
@@ -115,7 +118,7 @@ const DEVELOPER_NOTES = [
   'prop to supply columns manually:',
   '',
   '```tsx',
-  '<TableControls',
+  '<Table.TableControls',
   '  showHideColumns',
   '  hideColumnsProps={{',
   '    columns: myColumns,',
@@ -129,8 +132,10 @@ const DEVELOPER_NOTES = [
   '### TypeScript types',
   '',
   '```ts',
-  "import { TableControls } from '@arbor-education/design-system.components';",
-  "import type { TableControlsProps, BulkAction } from '@arbor-education/design-system.components';",
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'type MyControlsProps = Table.ControlsProps;',
+  'type MyAction = Table.BulkAction;',
   '```',
 ].join('\n');
 
@@ -317,7 +322,7 @@ export const BulkActionsOnly: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Table, TableControls } from '@arbor-education/design-system.components';
+import { Table } from '@arbor-education/design-system.components';
 
 function MyTable() {
   return (
@@ -326,7 +331,7 @@ function MyTable() {
       columnDefs={colDefs}
       rowSelection={{ mode: 'multiRow', checkboxes: true }}
       headerContent={(
-        <TableControls
+        <Table.TableControls
           bulkActions={[
             { displayName: 'Export selected', callback: api => api.exportDataAsCsv() },
             { displayName: 'Delete selected', callback: handleDelete, disabled: !canDelete },
@@ -355,7 +360,7 @@ export default MyTable;
   + 'Pass `disabled: true` to a specific action to grey it out (e.g. "Delete selected" when nothing is selected).',
 );
 
-export const FullToolbar: Story = withDescription(
+export const MaximumStandaloneToolbar: Story = withDescription(
   {
     parameters: {
       controls: { disable: true },
@@ -363,7 +368,7 @@ export const FullToolbar: Story = withDescription(
         source: {
           language: 'tsx',
           code: `
-import { Table, TableControls } from '@arbor-education/design-system.components';
+import { Table } from '@arbor-education/design-system.components';
 
 function FullTableExample() {
   return (
@@ -372,7 +377,7 @@ function FullTableExample() {
       columnDefs={colDefs}
       rowSelection={{ mode: 'multiRow', checkboxes: true }}
       headerContent={(
-        <TableControls
+        <Table.TableControls
           bulkActions={[
             { displayName: 'Export selected', callback: api => api.exportDataAsCsv() },
             { displayName: 'Delete selected', callback: handleDelete },
@@ -408,8 +413,8 @@ export default FullTableExample;
       onExpandToggle: fn(),
     },
   },
-  'The full toolbar with both groups populated: bulk actions, undo, redo, hide columns, download, settings, help, and expand. '
-  + 'This is the maximum control density — only include the slots your users actually need. '
-  + '`showHideColumns` renders a `HideColumnsDropdown` that reads columns from `GridApiContext`; '
-  + 'in this standalone preview it is disabled since there is no enclosing `<Table />` providing that context.',
+  'Every standalone control except `showHideColumns`: bulk actions, undo, redo, download, settings, help, and expand. '
+  + '`showHideColumns` is left `false` here because `HideColumnsDropdown` needs a `GridApiContext` to read column data, '
+  + 'and that context is only provided by a real `<Table />` — it cannot be faked in this standalone preview. '
+  + 'See [Table](?path=/docs/components-table--docs) for a fully-wired example with `showHideColumns: true` inside an actual `<Table />`.',
 );