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

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

@@ -11,6 +11,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { type Column, type ColDef, type ColGroupDef } from 'ag-grid-enterprise';
 import { Table } from './Table.js';
+import { TABLE_SPACING } from './tableConsts.js';
 import { Button } from 'Components/button/Button';
 import { Icon } from 'Components/icon/Icon';
 
@@ -348,6 +349,14 @@ const meta: Meta<TableProps> = {
         defaultValue: { summary: 'false' },
       },
     },
+    initialSettings: {
+      description: 'Seeds the table settings (column borders, spacing, cell colours) on mount, e.g. to restore a user\'s previously persisted preferences. Only affects the initial render — `resetSettings` still falls back to the DS defaults, not these values.',
+      control: false,
+      table: {
+        type: { summary: 'Partial<TableSettings>' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
     onTableSettingsChanged: {
       description: 'Fired when the user changes table settings (column borders, spacing, cell colours) via the settings dropdown.',
       control: false,
@@ -614,6 +623,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 +1539,6 @@ export const WithValidation: Story = {
     columnDefs: colDefsWithValidation,
     defaultColDef: defaultColDef,
     domLayout: 'autoHeight',
-    rowSelection: { mode: 'multiRow', checkboxes: true },
-    cellSelection: true,
   },
 };
 
@@ -1552,8 +1584,6 @@ export const WithValidationClassesAdded: Story = {
     columnDefs: colDefsWithValidationClasses,
     defaultColDef: defaultColDef,
     domLayout: 'autoHeight',
-    rowSelection: { mode: 'multiRow', checkboxes: true },
-    cellSelection: true,
   },
 };
 
@@ -1719,10 +1749,6 @@ export const TidyTable: Story = {
       groupExpanded: '',
       groupContracted: '',
     },
-    rowSelection: {
-      mode: 'multiRow',
-      groupSelects: 'filteredDescendants',
-    },
     autoGroupColumnDef: {
       field: 'name',
       headerName: 'Marksheet Columns',
@@ -1841,7 +1867,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 +1926,6 @@ export const TableWithSemanticColors: Story = {
     ],
     columnDefs: sampleColumnDefs,
     defaultColDef,
-    headerContent,
     domLayout: 'autoHeight',
     onCellValueChanged: (e) => {
       const { node, column, oldValue, newValue } = e;
@@ -2197,6 +2221,54 @@ export const WithTableSettingsDropdownCustomItems: Story = {
   },
 };
 
+type WithInitialSettingsArgs = TableProps & {
+  hasColumnBorders?: boolean;
+  tableSpacing?: TABLE_SPACING;
+  areCellColorsEnabled?: boolean;
+};
+
+export const WithInitialSettings: StoryObj<WithInitialSettingsArgs> = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`initialSettings` seeds column borders, spacing and cell colours on mount — useful for restoring a user\'s previously persisted preferences without a flash of the DS defaults. Resetting via the settings dropdown still falls back to the DS defaults, not these values. Use the Controls panel below to try different combinations.',
+      },
+    },
+  },
+  argTypes: {
+    hasColumnBorders: {
+      description: 'Seeds `initialSettings.hasColumnBorders`.',
+      control: 'boolean',
+    },
+    tableSpacing: {
+      description: 'Seeds `initialSettings.tableSpacing`.',
+      control: 'select',
+      options: Object.values(TABLE_SPACING),
+    },
+    areCellColorsEnabled: {
+      description: 'Seeds `initialSettings.areCellColorsEnabled`.',
+      control: 'boolean',
+    },
+  },
+  args: {
+    rowData: sampleData,
+    columnDefs: sampleColumnDefs,
+    defaultColDef,
+    domLayout: 'autoHeight',
+    headerContent: <Table.TableSettingsDropdown />,
+    hasColumnBorders: true,
+    tableSpacing: Table.Spacing.L,
+    areCellColorsEnabled: false,
+  },
+  render: ({ hasColumnBorders, tableSpacing, areCellColorsEnabled, ...rest }) => (
+    <Table
+      {...rest}
+      initialSettings={{ hasColumnBorders, tableSpacing, areCellColorsEnabled }}
+    />
+  ),
+};
+
 export const WithCheckboxCellRenderer: Story = {
   parameters: {
     docs: {

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

@@ -894,6 +894,48 @@ describe('Table', () => {
       expect(onTableSettingsChanged).toHaveBeenNthCalledWith(2, expect.objectContaining({ hasColumnBorders: true }));
     });
 
+    test('renders with initialSettings applied instead of the hardcoded defaults', async () => {
+      render(
+        <Table
+          headerContent={<TableSettingsDropdown />}
+          initialSettings={{
+            hasColumnBorders: true,
+            tableSpacing: Table.Spacing.L,
+            areCellColorsEnabled: false,
+          }}
+        />,
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: /Table settings/i }));
+
+      expect((screen.getByLabelText('Large') as HTMLInputElement).checked).toBe(true);
+      expect((screen.getByLabelText('Column borders') as HTMLInputElement).checked).toBe(true);
+      expect((screen.getByLabelText('Cell colours') as HTMLInputElement).checked).toBe(false);
+    });
+
+    test('resetSettings falls back to the DS defaults, not initialSettings', async () => {
+      const onTableSettingsReset = vi.fn();
+
+      render(
+        <Table
+          headerContent={<TableSettingsDropdown />}
+          initialSettings={{ hasColumnBorders: true, tableSpacing: Table.Spacing.L }}
+          onTableSettingsReset={onTableSettingsReset}
+        />,
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: /Table settings/i }));
+
+      const resetButton = screen.getByRole('button', { name: /Reset Table Settings/i });
+      await userEvent.click(resetButton);
+
+      expect(onTableSettingsReset).toHaveBeenCalledOnce();
+      await waitFor(() => {
+        expect((screen.getByLabelText('Medium') as HTMLInputElement).checked).toBe(true);
+        expect((screen.getByLabelText('Column borders') as HTMLInputElement).checked).toBe(false);
+      });
+    });
+
     test('resetSettings is called appropriately', async () => {
       const onTableSettingsReset = vi.fn();
 

package/src/components/table/Table.tsx

@@ -69,6 +69,7 @@ export const Table = (props: TableProps) => {
     footerContent,
     footerTestId,
     onGridReady,
+    initialSettings,
     onTableSettingsChanged,
     onTableSettingsReset,
     onColumnBordersChanged,
@@ -100,6 +101,7 @@ export const Table = (props: TableProps) => {
     setTableSpacing,
     setAreCellColorsEnabled,
   } = useTableSettings({
+    initialSettings,
     onTableSettingsChanged,
     onTableSettingsReset,
     onColumnBordersChanged,

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(