@arbor-education/design-system.components 0.14.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' },
       },
     },
   },
@@ -52,6 +390,7 @@ interface RowData {
   email: { value: string } & CellColors;
   role: { value: string } & CellColors;
   status: { value: string } & CellColors;
+  marks: number;
   active: boolean;
   time: string;
   dateOfBirth: Date;
@@ -64,6 +403,7 @@ const sampleData: RowData[] = [
     email: { value: 'alice.johnson@example.com' },
     role: { value: 'Developer' },
     status: { value: 'Active' },
+    marks: 84,
     active: true,
     time: '2026-01-28 12:00:00',
     dateOfBirth: new Date(1990, 0, 1),
@@ -74,6 +414,7 @@ const sampleData: RowData[] = [
     email: { value: 'bob.smith@example.com' },
     role: { value: 'Designer' },
     status: { value: 'Active' },
+    marks: 76,
     active: false,
     time: '2026-01-28 13:00:00',
     dateOfBirth: new Date(1991, 1, 2),
@@ -84,6 +425,7 @@ const sampleData: RowData[] = [
     email: { value: 'charlie.brown@example.com' },
     role: { value: 'Manager' },
     status: { value: 'Inactive' },
+    marks: 92,
     active: true,
     time: '2026-01-28 14:00:00',
     dateOfBirth: new Date(1992, 2, 3),
@@ -94,6 +436,7 @@ const sampleData: RowData[] = [
     email: { value: 'diana.prince@example.com' },
     role: { value: 'Developer' },
     status: { value: 'Active' },
+    marks: 88,
     active: false,
     time: '2026-01-28 15:00:00',
     dateOfBirth: new Date(1993, 3, 4),
@@ -104,6 +447,7 @@ const sampleData: RowData[] = [
     email: { value: 'ethan.hunt@example.com' },
     role: { value: 'Analyst' },
     status: { value: 'Active' },
+    marks: 69,
     active: false,
     time: '2026-01-28 16:00:00',
     dateOfBirth: new Date(1994, 4, 5),
@@ -154,6 +498,17 @@ const sampleColumnDefs: (ColDef | ColGroupDef)[] = [
     valueFormatter: Table.DefaultValueFormatter,
   },
   { field: 'status', valueFormatter: Table.DefaultValueFormatter },
+  {
+    field: 'marks',
+    cellDataType: 'number',
+    cellEditor: 'dsNumberCellEditor',
+    cellEditorParams: {
+      min: 0,
+      max: 100,
+      step: 1,
+      disableSpinners: false,
+    },
+  },
   {
     field: 'active',
     filter: { component: BooleanFilter, doesFilterPass: doesBooleanFilterPass },
@@ -168,6 +523,60 @@ const sampleColumnDefs: (ColDef | ColGroupDef)[] = [
   },
 ];
 
+const verticalHeaderTextColumnDefs: (ColDef | ColGroupDef)[] = [
+  {
+    headerName: 'Details',
+    children: [
+      {
+        field: 'name',
+        headerName: 'Preferred Learner Name',
+        filter: 'agSetColumnFilter',
+      },
+      {
+        field: 'email',
+        headerName: 'Primary Contact Email Address',
+        filter: 'agSetColumnFilter',
+      },
+      {
+        field: 'role',
+        headerName: 'Role',
+        filter: 'agSetColumnFilter',
+      },
+      {
+        field: 'dateOfBirth',
+        headerName: 'Date of Birth',
+        filter: 'agDateColumnFilter',
+        filterParams: { buttons: ['clear', 'apply'] },
+        valueFormatter: params =>
+          params.value instanceof Date
+            ? params.value.toLocaleDateString()
+            : params.value,
+      },
+    ],
+    valueFormatter: Table.DefaultValueFormatter,
+  },
+  {
+    field: 'status',
+    headerName: 'Current Enrollment Status',
+  },
+  {
+    field: 'marks',
+    headerName: 'Overall Score (%)',
+    cellDataType: 'number',
+  },
+  {
+    field: 'active',
+    headerName: 'Active?',
+    cellDataType: 'boolean',
+    editable: false,
+  },
+  {
+    field: 'time',
+    headerName: 'Most Recent Activity Timestamp',
+    editable: false,
+  },
+];
+
 const footerContent = [
   <Button key={0} variant="primary">
     Button 1
@@ -201,6 +610,28 @@ export const Default: Story = {
   },
 };
 
+export const WithVerticalHeaderText: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use the `verticalHeaderText` prop when columns are narrow and header labels need to remain readable.',
+      },
+    },
+  },
+  args: {
+    rowData: sampleData,
+    columnDefs: verticalHeaderTextColumnDefs,
+    defaultColDef: {
+      ...defaultColDef,
+      wrapHeaderText: true,
+      autoHeaderHeight: true,
+    },
+    domLayout: 'autoHeight',
+    verticalHeaderText: true,
+  },
+};
+
 export const WithFooter: Story = {
   args: {
     rowData: sampleData,
@@ -1661,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: {