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

package/dist/components/table/Table.stories.js

@@ -1,4 +1,5 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { Controls, Heading as DocHeading, Markdown, Primary as DocPrimary, Stories, Subtitle, Title, } from '@storybook/addon-docs/blocks';
 import {} from 'ag-grid-enterprise';
 import { Table } from './Table';
 import { Button } from '../button/Button';
@@ -12,14 +13,317 @@ import { Modal } from '../modal/Modal';
 import { ModalUtils } from '../../utils/ModalUtils';
 import { BooleanFilter, doesBooleanFilterPass, } from './columnFilters/BooleanFilter/BooleanFilter';
 import { doesTimeFilterPass, TimeFilter, } from './columnFilters/TimeFilter/TimeFilter';
+// ---------------------------------------------------------------------------
+// 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 (_jsxs(_Fragment, { children: [_jsx(Title, {}), _jsx(Subtitle, {}), _jsx(Markdown, { children: DESCRIPTION_INTRO }), _jsx(DocHeading, { children: "Interactive example" }), _jsx(Markdown, { children: PROPS_INTRO }), _jsx(DocPrimary, {}), _jsx(Controls, {}), _jsx(DocHeading, { children: "Usage guidance" }), _jsx(Markdown, { children: USAGE_GUIDANCE }), _jsx(DocHeading, { children: "Developer notes" }), _jsx(Markdown, { children: DEVELOPER_NOTES }), _jsx(DocHeading, { children: "Examples" }), _jsx(Stories, { title: "" }), _jsx(Markdown, { children: RELATED_COMPONENTS })] }));
+}
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
 const meta = {
     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' },
             },
         },
     },
@@ -31,6 +335,7 @@ const sampleData = [
         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),
@@ -41,6 +346,7 @@ const sampleData = [
         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),
@@ -51,6 +357,7 @@ const sampleData = [
         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),
@@ -61,6 +368,7 @@ const sampleData = [
         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),
@@ -71,6 +379,7 @@ const sampleData = [
         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),
@@ -118,6 +427,17 @@ const sampleColumnDefs = [
         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 },
@@ -131,6 +451,58 @@ const sampleColumnDefs = [
         editable: false,
     },
 ];
+const verticalHeaderTextColumnDefs = [
+    {
+        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 = [
     _jsx(Button, { variant: "primary", children: "Button 1" }, 0),
     _jsx(RowCountInfo, {}, 3),
@@ -150,6 +522,26 @@ export const Default = {
         cellSelection: true,
     },
 };
+export const WithVerticalHeaderText = {
+    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 = {
     args: {
         rowData: sampleData,
@@ -1376,6 +1768,56 @@ const checkboxColumnDefs = [
         editable: false,
     },
 ];
+export const WithTableSettingsDropdownItems = {
+    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: (_jsx(Table.TableSettingsDropdown, { items: ['tableSpacing'] })),
+    },
+};
+export const WithTableSettingsDropdownCustomItems = {
+    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) => row.active);
+        return (_jsx(Table, { ...args, rowData: filteredData, onTableSettingsReset: () => setShowInactive(false), headerContent: (_jsx(Table.TableSettingsDropdown, { items: [
+                    'tableSpacing',
+                    'separator',
+                    'style',
+                    'separator',
+                    {
+                        type: 'checkboxGroup',
+                        legend: 'View options',
+                        options: [
+                            { label: 'Show inactive users', checked: showInactive, onChange: setShowInactive },
+                        ],
+                    },
+                ] })) }));
+    },
+};
 export const WithCheckboxCellRenderer = {
     parameters: {
         docs: {