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

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 />`.',
 );

package/src/components/tabs/Tabs.stories.tsx

@@ -107,7 +107,7 @@ const DEVELOPER_NOTES = [
   '| `active` | `boolean` | `false` | Marks this tab as selected — sets `aria-selected` and active styles |',
   '| `tabElement` | `"button" \\| "link"` | `"button"` | Inner element type. `"button"` for JS-controlled tabs; `"link"` for anchor/router navigation |',
   '| `tabElementProps` | `ButtonHTMLAttributes` or `AnchorHTMLAttributes` | — | Props forwarded to the inner `<button>` or `<a>`. Use `onClick` for state control; `href` for links |',
-  '| `iconName` | `keyof allowedIcons` | — | Optional icon rendered before the label text (16 px) |',
+  '| `iconName` | `IconName` | — | Optional icon rendered before the label text (16 px) |',
   '| `children` | `ReactNode` | — | Tab label text |',
   '| `className` | `string` | — | Extra CSS class on the `<li>` wrapper |',
   '',

package/src/components/tabs/TabsItem.stories.tsx

@@ -9,7 +9,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { TabsItem } from './TabsItem.js';
 import { Tabs } from './Tabs.js';
-import { allowedIcons } from 'Components/icon/allowedIcons';
+import type { IconName } from 'Components/icon/allowedIcons';
 
 // ---------------------------------------------------------------------------
 // Docs page
@@ -93,10 +93,14 @@ const meta = {
     },
     iconName: {
       control: 'select',
-      options: Object.keys(allowedIcons),
-      description: 'Optional icon rendered before the label text at 16 px.',
+      // Any Icon name works; these are the ones that read well in a tab.
+      options: [
+        'house', 'user', 'guardians', 'staff', 'date', 'sheet', 'table', 'settings',
+        'chart-column-increasing', 'clipboard-list', 'mail', 'archive',
+      ] satisfies IconName[],
+      description: 'Optional icon rendered before the label text at 16 px. Accepts any `IconName`.',
       table: {
-        type: { summary: 'keyof allowedIcons' },
+        type: { summary: 'IconName' },
         defaultValue: { summary: 'undefined' },
       },
     },

package/src/components/tabs/TabsItem.tsx

@@ -1,11 +1,11 @@
 import classNames from 'classnames';
-import type { allowedIcons } from 'Components/icon/allowedIcons';
+import type { IconName } from 'Components/icon/allowedIcons';
 import { Icon } from 'Components/icon/Icon';
 import type { AnchorHTMLAttributes, ButtonHTMLAttributes, HTMLAttributes } from 'react';
 
 type TabsItemProps = {
   active?: boolean;
-  iconName?: keyof typeof allowedIcons;
+  iconName?: IconName;
 } & (
   | { tabElement?: 'button'; tabElementProps?: ButtonHTMLAttributes<HTMLButtonElement> }
   | { tabElement?: 'link'; tabElementProps?: AnchorHTMLAttributes<HTMLAnchorElement> }