@arbor-education/design-system.components 0.15.0 → 0.16.0

package/src/components/table/DSDefaultColDef.ts

@@ -1,4 +1,10 @@
-import type { CellClassParams, CellFocusedParams, ColDef, SuppressMouseEventHandlingParams, ValueFormatterFunc } from 'ag-grid-community';
+import type {
+  CellClassParams,
+  CellFocusedParams,
+  ColDef,
+  SuppressMouseEventHandlingParams,
+  ValueFormatterFunc,
+} from 'ag-grid-community';
 import { cellColorStyles } from './cellColorStyles';
 
 // checks if the value is wrapped in a object with a value property
@@ -15,17 +21,28 @@ export const defaultValueFormatter: ValueFormatterFunc = (params) => {
   return value;
 };
 
-export const shouldSuppressFocus = (params: SuppressMouseEventHandlingParams | CellClassParams | CellFocusedParams) => {
+export const shouldSuppressFocus = (
+  params:
+    | SuppressMouseEventHandlingParams
+    | CellClassParams
+    | CellFocusedParams,
+) => {
   if (typeof params.column !== 'object') {
     return false;
   }
-  return params.column?.getColDef().cellRendererParams.suppressCellFocusAndFocusFirstElement ?? false;
+  return (
+    params.column?.getColDef()?.cellRendererParams
+      ?.suppressCellFocusAndFocusFirstElement ?? false
+  );
 };
 
 export const DSDefaultColDef: ColDef = {
   cellStyle: cellColorStyles,
   valueGetter: (params) => {
-    const { data, colDef: { field } } = params;
+    const {
+      data,
+      colDef: { field },
+    } = params;
     if (data == null || field == null) {
       return undefined;
     }
@@ -33,7 +50,10 @@ export const DSDefaultColDef: ColDef = {
   },
   valueFormatter: defaultValueFormatter,
   filterValueGetter: (params) => {
-    const { data, colDef: { field } } = params;
+    const {
+      data,
+      colDef: { field },
+    } = params;
     if (data == null || field == null) {
       return undefined;
     }

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

@@ -1,4 +1,13 @@
 import type { Meta, StoryObj } from '@storybook/react-vite';
+import {
+  Controls,
+  Heading as DocHeading,
+  Markdown,
+  Primary as DocPrimary,
+  Stories,
+  Subtitle,
+  Title,
+} from '@storybook/addon-docs/blocks';
 import { type Column, type ColDef, type ColGroupDef } from 'ag-grid-enterprise';
 import { Table } from './Table';
 import { Button } from 'Components/button/Button';
@@ -24,15 +33,344 @@ import type { CustomCellRendererProps } from 'ag-grid-react';
 
 type TableProps = ComponentProps<typeof Table>;
 
+// ---------------------------------------------------------------------------
+// Content strings for the custom DocsPage
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`Table` is an enterprise-grade data table built on top of [AG Grid React](https://www.ag-grid.com/react-data-grid/).',
+  'It wraps `AgGridReact` with Arbor design tokens, a custom theme, built-in search, pagination, bulk actions,',
+  'hide-columns, and a suite of custom cell renderers and column filters.',
+  'All AG Grid props pass through via `...rest`, so the full AG Grid API is available.',
+].join(' ');
+
+const PROPS_INTRO
+  = 'The preview below is wired to the **Controls** panel — tweak any DS-specific prop to see the story update in real time.';
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- Displaying large, structured datasets where users need to sort, filter, search, or paginate.',
+  '- Any screen in Arbor that renders rows of records (pupil lists, staff registers, attendance grids, marksheets).',
+  '- When cells need interactive controls — buttons, dropdowns, checkboxes, date pickers.',
+  '- When column visibility, row selection, and bulk actions are required.',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| A small read-only list of key–value pairs | [`Section`](?path=/docs/components-section--docs) with [`Row`](?path=/docs/components-row--docs) components |',
+  '| A two-column data summary (label + value) | [`Row`](?path=/docs/components-row--docs) inside a `Section` |',
+  '| Simple static HTML tables | Native `<table>` with semantic markup |',
+  '| A handful of rows that never change | Native `<table>` — AG Grid has overhead |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### AG Grid license',
+  '',
+  '`setAgGridLicenseKey()` is called automatically inside the `Table` component.',
+  'You do **not** need to call it yourself.',
+  '',
+  '---',
+  '',
+  '### Registered cell renderers',
+  '',
+  'These string keys are pre-registered and available in any `cellRenderer` or `cellRendererParams`:',
+  '',
+  '| Key | Component | Purpose |',
+  '|---|---|---|',
+  '| `dsButtonCellRenderer` | `Table.ButtonCellRenderer` | Renders a `Button` inside a cell |',
+  '| `dsInlineTextCellRenderer` | `Table.InlineTextCellRenderer` | Inline text editing with expand/collapse support |',
+  '| `dsSelectDropdownCellRenderer` | `Table.SelectDropdownCellRenderer` | Renders a `SelectDropdown` in a cell |',
+  '| `dsBooleanCellRenderer` | `Table.BooleanCellRenderer` | Read-only boolean display |',
+  '| `dsCheckboxCellRenderer` | `Table.CheckboxCellRenderer` | Editable boolean checkbox |',
+  '| `dsDateCellEditor` | `Table.DateCellEditor` | Date picker cell editor |',
+  '',
+  '---',
+  '',
+  '### Registered column filters',
+  '',
+  '| Import | `doesFilterPass` helper | Use case |',
+  '|---|---|---|',
+  '| `BooleanFilter` | `doesBooleanFilterPass` | Filtering boolean / active columns |',
+  '| `TimeFilter` | `doesTimeFilterPass` | Filtering time string columns |',
+  '',
+  '---',
+  '',
+  '### Header and footer slots',
+  '',
+  '- `headerContent` — pass any `ReactNode` here; the `<TableHeader>` wraps it with a built-in search bar.',
+  '  Use `Table.TableControls` for the standard toolbar (bulk actions, hide columns, settings, download, help, expand).',
+  '- `hasSearch` (default `true`) — controls whether the search bar is rendered inside the header.',
+  '  Set to `false` when the header has no search functionality.',
+  '- `footerContent` — pass any `ReactNode` here; the `<TableFooter>` wraps it.',
+  '  Use `Table.PaginationPanel` for standard pagination.',
+  '',
+  '---',
+  '',
+  '### TableSettingsDropdown customisation',
+  '',
+  '`Table.TableSettingsDropdown` accepts an optional `items` prop to control which controls are shown and in what order.',
+  'Omit `items` (or omit any key) to hide that control entirely.',
+  '',
+  '```tsx',
+  '// Built-in keys — use any subset in any order:',
+  '<Table.TableSettingsDropdown items={[\'tableSpacing\', \'separator\', \'style\']} />',
+  '',
+  '// Custom checkbox group:',
+  '<Table.TableSettingsDropdown items={[',
+  '  \'tableSpacing\',',
+  '  { type: \'checkboxGroup\', legend: \'View options\', options: [',
+  '    { label: \'Show inactive\', checked: showInactive, onChange: setShowInactive },',
+  '  ] },',
+  ']} />',
+  '',
+  '// Custom radio group:',
+  '<Table.TableSettingsDropdown items={[',
+  '  { type: \'radioGroup\', legend: \'Display\', name: \'display\', checkedValue: view, onChange: setView,',
+  '    options: [{ label: \'Compact\', value: \'compact\' }, { label: \'Default\', value: \'default\' }] },',
+  ']} />',
+  '```',
+  '',
+  'Use `Table.SettingsItems` to access the default items array and extend it:',
+  '',
+  '```tsx',
+  'const myItems = [...Table.SettingsItems, { type: \'checkboxGroup\', options: [...] }];',
+  '<Table.TableSettingsDropdown items={myItems} />',
+  '```',
+  '',
+  'Use `onTableSettingsReset` on `Table` to reset your custom state when the reset button is clicked.',
+  '',
+  '---',
+  '',
+  '### Themes',
+  '',
+  '| Value | Description |',
+  '|---|---|',
+  '| _(omit)_ | Default Arbor table theme with full spacing and borders |',
+  '| `"tidy"` | Compact theme for dense layouts like marksheets. Suppresses expand/collapse icons. |',
+  '',
+  '---',
+  '',
+  '### Table spacing',
+  '',
+  'Use `Table.Spacing` (enum `TABLE_SPACING`) when handling `onTableSpacingChanged`:',
+  '',
+  '```ts',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  '// Table.Spacing values:',
+  '// Table.Spacing.XS  → 0',
+  '// Table.Spacing.S   → var(--spacing-xsmall)',
+  '// Table.Spacing.M   → var(--spacing-small)  ← default',
+  '// Table.Spacing.L   → var(--spacing-medium)',
+  '```',
+  '',
+  '---',
+  '',
+  '### GridApiContext',
+  '',
+  'Child components that need the AG Grid `GridApi` can consume `Table.GridApiContext`:',
+  '',
+  '```tsx',
+  "import { useContext } from 'react';",
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'function MyTableChild() {',
+  '  const gridApi = useContext(Table.GridApiContext);',
+  '  return <button onClick={() => gridApi?.exportDataAsCsv()}>Export</button>;',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### DefaultColDef and DefaultValueFormatter',
+  '',
+  '`Table.DefaultColDef` contains Arbor defaults (editable, sortable, resizable, min-width, flex).',
+  'Spread it into your `defaultColDef` and add overrides:',
+  '',
+  '```ts',
+  'const defaultColDef = {',
+  '  ...Table.DefaultColDef,',
+  '  editable: false, // override',
+  '};',
+  '```',
+  '',
+  '`Table.DefaultValueFormatter` handles the `{ value: string }` cell data shape.',
+  'Any column using the object cell shape (`{ value, backgroundColor, foregroundColor, semanticColor }`) **must** use this formatter.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { Table } from '@arbor-education/design-system.components';",
+  "import type { TableProps, TableControlsProps, BulkAction, HideColumnsProps } from '@arbor-education/design-system.components';",
+  '',
+  '// or via namespace:',
+  'type MyTableProps = Table.Props;',
+  'type MyControlsProps = Table.ControlsProps;',
+  'type MyBulkAction = Table.BulkAction;',
+  'type MySpacing = Table.Spacing;',
+  '',
+  '// Table.SettingsItems — the default settings items array (spread to extend):',
+  'const myItems = [...Table.SettingsItems, { type: \'checkboxGroup\' as const, options: [] }];',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Section](?path=/docs/components-section--docs) · [Row](?path=/docs/components-row--docs) · [Button](?path=/docs/components-button--docs) · [SelectDropdown](?path=/docs/components-selectdropdown--docs)',
+].join('\n');
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function TableDocsPage() {
+  return (
+    <>
+      <Title />
+      <Subtitle />
+      <Markdown>{DESCRIPTION_INTRO}</Markdown>
+      <DocHeading>Interactive example</DocHeading>
+      <Markdown>{PROPS_INTRO}</Markdown>
+      <DocPrimary />
+      <Controls />
+      <DocHeading>Usage guidance</DocHeading>
+      <Markdown>{USAGE_GUIDANCE}</Markdown>
+      <DocHeading>Developer notes</DocHeading>
+      <Markdown>{DEVELOPER_NOTES}</Markdown>
+      <DocHeading>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
 const meta: Meta<TableProps> = {
   title: 'Components/Table',
   component: Table,
   tags: ['autodocs'],
   parameters: {
+    layout: 'padded',
     docs: {
-      description: {
-        component:
-          'The Table component is a wrapper around the ag-grid-react component. It provides a set of props that can be used to configure the table.',
+      page: TableDocsPage,
+    },
+  },
+  argTypes: {
+    wrapperClassName: {
+      description: 'Additional CSS class names applied to the root `<section>` wrapper.',
+      control: 'text',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    hasSearch: {
+      description: [
+        'When `true` (the default) a quick-filter search bar is rendered inside the header area.',
+        'Set to `false` when using `headerContent` without a search requirement,',
+        'or when you want to suppress the search bar entirely.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'true' },
+      },
+    },
+    headerContent: {
+      description: [
+        'ReactNode rendered inside the `<TableHeader>` above the grid.',
+        'Use `Table.TableControls` for the standard composed toolbar.',
+        'The built-in search bar appears here when `hasSearch` is `true`.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    footerContent: {
+      description: [
+        'ReactNode rendered inside the `<TableFooter>` below the grid.',
+        'Use `Table.PaginationPanel` for standard client-side or server-side pagination.',
+      ].join(' '),
+      control: false,
+      table: {
+        type: { summary: 'ReactNode' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    tableTheme: {
+      description: [
+        'Visual theme for the grid.',
+        'Pass `"tidy"` for the compact marksheet-style theme.',
+        'Omit (or pass `undefined`) for the default Arbor table theme.',
+      ].join(' '),
+      control: 'select',
+      options: [undefined, 'tidy'],
+      table: {
+        type: { summary: "'tidy' | undefined" },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    enableSimultaneousRangeAndRowSelection: {
+      description: [
+        'When `true`, allows both cell-range selection and row selection to be active at the same time.',
+        'Default `false` — drag selection clears row selection.',
+      ].join(' '),
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    disableDragSelect: {
+      description: 'When `true`, disables drag-to-select behaviour on cell range selection.',
+      control: 'boolean',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    onTableSettingsChanged: {
+      description: 'Fired when the user changes table settings (column borders, spacing, cell colours) via the settings dropdown.',
+      control: false,
+      table: {
+        type: { summary: '(settings: TableSettings) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    onTableSpacingChanged: {
+      description: 'Fired when the user changes row spacing. Receives a `Table.Spacing` (TABLE_SPACING) enum value.',
+      control: false,
+      table: {
+        type: { summary: '(val: TABLE_SPACING) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    onColumnBordersChanged: {
+      description: 'Fired when the user toggles column borders on or off via the settings dropdown.',
+      control: false,
+      table: {
+        type: { summary: '(hasBorders: boolean) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    onTableSettingsReset: {
+      description: 'Fired when the user resets all table settings to their defaults.',
+      control: false,
+      table: {
+        type: { summary: '() => void' },
+        defaultValue: { summary: 'undefined' },
       },
     },
   },
@@ -1754,6 +2092,76 @@ const checkboxColumnDefs: ColDef[] = [
   },
 ];
 
+export const WithTableSettingsDropdownItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass an `items` array to control exactly which controls appear. Only the items you include will be shown. Available keys: `tableSpacing`, `separator`, `style`.',
+      },
+    },
+  },
+  args: {
+    rowData: sampleData,
+    columnDefs: sampleColumnDefs,
+    defaultColDef,
+    domLayout: 'autoHeight',
+    headerContent: (
+      <Table.TableSettingsDropdown
+        items={['tableSpacing']}
+      />
+    ),
+  },
+};
+
+export const WithTableSettingsDropdownCustomItems: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Pass an `items` array with any mix of built-in keys and custom item objects in any order. Built-in keys: `tableSpacing`, `separator`, `style`. For custom items, use `{ type: "checkboxGroup", legend?, options }` for a group of toggles or `{ type: "radioGroup", legend?, name, checkedValue, onChange, options }` for mutually exclusive options. Custom item state is managed externally. Use `onTableSettingsReset` on the Table to reset custom state when the reset button is clicked.',
+      },
+    },
+  },
+  args: {
+    rowData: sampleData,
+    columnDefs: sampleColumnDefs,
+    defaultColDef,
+    domLayout: 'autoHeight',
+  },
+  render: (args) => {
+    const [showInactive, setShowInactive] = useState(false);
+    const filteredData = showInactive
+      ? args.rowData
+      : args.rowData?.filter((row: RowData) => row.active);
+
+    return (
+      <Table
+        {...args}
+        rowData={filteredData}
+        onTableSettingsReset={() => setShowInactive(false)}
+        headerContent={(
+          <Table.TableSettingsDropdown
+            items={[
+              'tableSpacing',
+              'separator',
+              'style',
+              'separator',
+              {
+                type: 'checkboxGroup',
+                legend: 'View options',
+                options: [
+                  { label: 'Show inactive users', checked: showInactive, onChange: setShowInactive },
+                ],
+              },
+            ]}
+          />
+        )}
+      />
+    );
+  },
+};
+
 export const WithCheckboxCellRenderer: Story = {
   parameters: {
     docs: {

package/src/components/table/Table.tsx

@@ -2,7 +2,7 @@ import { AllEnterpriseModule, ModuleRegistry, type GridApi } from 'ag-grid-enter
 import { AgGridReact, type AgGridReactProps } from 'ag-grid-react';
 import { defaultTheme } from './theme/defaultTheme';
 import classNames from 'classnames';
-import { useRef, useState, type ReactNode } from 'react';
+import { useContext, useRef, useState, type ReactNode } from 'react';
 import { TableFooter } from './TableFooter';
 import { TableHeader } from './TableHeader';
 import { GridApiContext } from './GridApiContext';
@@ -14,6 +14,7 @@ import { BulkActionsDropdown } from './tableControls/BulkActionsDropdown';
 import { HideColumnsDropdown } from './tableControls/HideColumnsDropdown';
 import { useTableSettings, type UseTableSettingsParams } from './useTableSettings';
 import { setAgGridLicenseKey } from 'Utils/setAgGridLicenseKey';
+import { PopupParentContext } from 'Utils/PopupParentContext';
 import { toggleRowSelectionInCurrentRange } from './toggleRowSelectionInCurrentRange';
 import { defaultValueFormatter, DSDefaultColDef, shouldSuppressFocus } from './DSDefaultColDef';
 import { NumberCellEditor } from './cellEditors/NumberCellEditor';
@@ -25,7 +26,7 @@ import { focusFirstFocusableElement } from 'Utils/focusFirstFocusableElement';
 import { BooleanFilter } from './columnFilters/BooleanFilter/BooleanFilter';
 import { TimeFilter } from './columnFilters/TimeFilter/TimeFilter';
 import { DateCellEditor } from './cellEditors/DateCellEditor';
-import { TableSettingsDropdown } from './tableControls/TableSettingsDropdown';
+import { TableSettingsDropdown, TABLE_SETTINGS_ITEMS } from './tableControls/TableSettingsDropdown';
 import { TableControls, type TableControlsProps, type BulkAction as BulkActionType } from './tableControls/TableControls';
 import type { HideColumnsDropdownProps } from './tableControls/HideColumnsDropdown';
 import { TABLE_SPACING } from './tableConsts';
@@ -87,6 +88,8 @@ export const Table = (props: TableProps) => {
 
   const [searchValue, setSearchValue] = useState('');
 
+  const popupParentRef = useContext(PopupParentContext);
+
   const {
     settings,
     resetSettings,
@@ -150,6 +153,7 @@ export const Table = (props: TableProps) => {
           )}
           <AgGridReact
             theme={getTheme()}
+            popupParent={popupParentRef.current}
             onGridReady={(event) => {
               const { api } = event;
               setGridApi(api);
@@ -217,6 +221,8 @@ Table.RowCountInfo = RowCountInfo;
 Table.BulkActionsDropdown = BulkActionsDropdown;
 Table.HideColumnsDropdown = HideColumnsDropdown;
 Table.ButtonCellRenderer = ButtonCellRenderer;
+Table.InlineTextCellRenderer = InlineTextCellRenderer;
+Table.SelectDropdownCellRenderer = SelectDropdownCellRenderer;
 Table.BooleanCellRenderer = BooleanCellRenderer;
 Table.DefaultCellRenderer = DefaultCellRenderer;
 Table.DateCellEditor = DateCellEditor;
@@ -228,6 +234,7 @@ Table.TableSettingsDropdown = TableSettingsDropdown;
 Table.TableControls = TableControls;
 
 Table.Spacing = TABLE_SPACING;
+Table.SettingsItems = TABLE_SETTINGS_ITEMS;
 
 export namespace Table {
   // eslint-disable-next-line @typescript-eslint/no-explicit-any