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

package/src/components/table/tableControls/TableControls.stories.tsx

@@ -0,0 +1,415 @@
+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 { fn } from 'storybook/test';
+import { TableControls } from './TableControls';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`TableControls` is the pre-composed toolbar slot for the Arbor data table.',
+  'It renders a two-group flex row: a **start group** (bulk actions, undo, redo, hide columns)',
+  'and an **end group** (search, download, settings, help, expand).',
+  '',
+  'Every slot is opt-in — only pass the props for the controls you need.',
+  'If neither group has any props, the component returns `null` and renders nothing.',
+  '',
+  'Pass the entire `<TableControls />` element as the `headerContent` prop of `<Table />`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- As the `headerContent` of a `<Table />` to give it a standard toolbar',
+  '- When you need a consistent mix of bulk actions, column visibility, search, and settings',
+  '- When consumers need access to the full set of standard table controls in one composable component',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Alternative |',
+  '|---|---|',
+  '| You only need a search bar | Pass `<SearchBar />` directly as `headerContent` |',
+  '| You need a custom toolbar layout | Compose your own header with individual components |',
+  '| The table has no toolbar at all | Omit `headerContent` entirely |',
+  '',
+  '---',
+  '',
+  '### Start group vs end group',
+  '',
+  '| Prop | Group | Description |',
+  '|---|---|---|',
+  '| `bulkActions` | Start | Array of `{ displayName, callback, disabled? }` — shown as a dropdown when rows are selected |',
+  '| `onUndo` | Start | Renders an undo icon button |',
+  '| `onRedo` | Start | Renders a redo icon button |',
+  '| `showHideColumns` | Start | Renders the `HideColumnsDropdown` |',
+  '| `hasSearch` | End | Renders the `SearchBar` |',
+  '| `onDownload` | End | Renders a download icon button |',
+  '| `onTooltipsToggle` | End | Renders a tooltip-toggle icon button (aria-pressed) |',
+  '| `showSettings` | End | Renders the `TableSettingsDropdown` |',
+  '| `onHelp` | End | Renders a help icon button |',
+  '| `onExpandToggle` | End | Renders an expand/shrink icon button |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Wiring into `<Table />`',
+  '',
+  '```tsx',
+  "import { Table, TableControls } from '@arbor-education/design-system.components';",
+  '',
+  'function MyTable() {',
+  '  return (',
+  '    <Table',
+  '      rowData={rows}',
+  '      columnDefs={colDefs}',
+  '      headerContent={(',
+  '        <TableControls',
+  '          bulkActions={[',
+  '            { displayName: "Export selected", callback: api => exportCsv(api) },',
+  '            { displayName: "Delete selected", callback: api => deleteRows(api) },',
+  '          ]}',
+  '          onUndo={handleUndo}',
+  '          showHideColumns',
+  '          onDownload={handleDownload}',
+  '          showSettings',
+  '          onHelp={openHelpPanel}',
+  '          onExpandToggle={setExpanded}',
+  '        />',
+  '      )}',
+  '    />',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### `BulkAction` type',
+  '',
+  '```ts',
+  "import type { BulkAction } from '@arbor-education/design-system.components';",
+  '',
+  'type BulkAction = {',
+  '  displayName: string;',
+  '  callback: (gridApi: GridApi) => void;',
+  '  disabled?: boolean;',
+  '};',
+  '```',
+  '',
+  '---',
+  '',
+  '### `HideColumnsDropdown` and `GridApiContext`',
+  '',
+  'When `showHideColumns` is `true`, `TableControls` renders `HideColumnsDropdown`.',
+  '`HideColumnsDropdown` reads the column list from `GridApiContext` — this context is provided',
+  'automatically by `<Table />`. When used outside a `<Table />`, pass the `hideColumnsProps`',
+  'prop to supply columns manually:',
+  '',
+  '```tsx',
+  '<TableControls',
+  '  showHideColumns',
+  '  hideColumnsProps={{',
+  '    columns: myColumns,',
+  '    onSelectionChanged: handleVisibilityChange,',
+  '  }}',
+  '/>',
+  '```',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { TableControls } from '@arbor-education/design-system.components';",
+  "import type { TableControlsProps, BulkAction } from '@arbor-education/design-system.components';",
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [PaginationPanel](?path=/docs/components-table-paginationpanel--docs) · [SearchBar](?path=/docs/components-searchbar--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — toggle props to see the toolbar update in real time.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function TableControlsDocsPage() {
+  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 = {
+  title: 'Components/Table/TableControls',
+  component: TableControls,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: TableControlsDocsPage },
+  },
+  argTypes: {
+    bulkActions: {
+      description: 'Array of bulk action definitions. Each action has a `displayName`, a `callback(gridApi)`, and an optional `disabled` flag. Renders as a `BulkActionsDropdown` in the start group.',
+      control: false,
+      table: { type: { summary: 'BulkAction[]' }, defaultValue: { summary: 'undefined' } },
+    },
+    onUndo: {
+      description: 'Renders an undo icon button in the start group. Called with no arguments on click.',
+      control: false,
+      table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    onRedo: {
+      description: 'Renders a redo icon button in the start group. Called with no arguments on click.',
+      control: false,
+      table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    showHideColumns: {
+      description: 'When `true`, renders the `HideColumnsDropdown` in the start group. Reads column visibility from `GridApiContext` (provided by `<Table />`). Pass `hideColumnsProps` for manual column control.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    hasSearch: {
+      description: 'When `true`, renders a `SearchBar` in the end group.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    onDownload: {
+      description: 'Renders a download icon button in the end group. Called with no arguments on click.',
+      control: false,
+      table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    showSettings: {
+      description: 'When `true`, renders the `TableSettingsDropdown` in the end group.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    onHelp: {
+      description: 'Renders a help icon button in the end group. Called with no arguments on click.',
+      control: false,
+      table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    isExpanded: {
+      description: 'Controls the expand/shrink icon state when `onExpandToggle` is provided. `true` = shrink icon; `false` = expand icon.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    onExpandToggle: {
+      description: 'Renders an expand/shrink icon button in the end group. Called with the new expanded state (`boolean`) on click.',
+      control: false,
+      table: { type: { summary: '(expanded: boolean) => void' }, defaultValue: { summary: 'undefined' } },
+    },
+  },
+  args: {
+    onUndo: fn(),
+    onRedo: fn(),
+    onDownload: fn(),
+    onHelp: fn(),
+    onExpandToggle: fn(),
+  },
+} satisfies Meta<typeof TableControls>;
+
+export default meta;
+type Story = StoryObj<typeof TableControls>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    args: {
+      onUndo: fn(),
+      onRedo: fn(),
+      onDownload: fn(),
+      showSettings: true,
+      onHelp: fn(),
+      onExpandToggle: fn(),
+    },
+  },
+  'The interactive canvas — toggle Controls to add or remove toolbar slots. '
+  + 'Every prop is opt-in: only slots with a prop provided will render. '
+  + 'If no props are passed at all, `TableControls` returns `null`.',
+);
+
+export const StartGroupOnly: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      bulkActions: [
+        { displayName: 'Export selected', callback: fn() },
+        { displayName: 'Delete selected', callback: fn(), disabled: true },
+      ],
+      onUndo: fn(),
+      onRedo: fn(),
+      showHideColumns: false,
+    },
+  },
+  'Only the start group: bulk actions dropdown, undo, and redo. '
+  + 'No end-group props are passed so that side is omitted entirely. '
+  + '`showHideColumns` is `false` here because `HideColumnsDropdown` needs a `GridApiContext` (provided by `<Table />`) to read column data — '
+  + 'see the **Within a Table** story for a fully wired example.',
+);
+
+export const EndGroupOnly: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      hasSearch: true,
+      onDownload: fn(),
+      showSettings: true,
+      onHelp: fn(),
+      onExpandToggle: fn(),
+    },
+  },
+  'Only the end group: search bar, download, settings dropdown, help, and expand. '
+  + 'No start-group props are passed so that side is omitted entirely.',
+);
+
+export const BulkActionsOnly: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table, TableControls } from '@arbor-education/design-system.components';
+
+function MyTable() {
+  return (
+    <Table
+      rowData={rows}
+      columnDefs={colDefs}
+      rowSelection={{ mode: 'multiRow', checkboxes: true }}
+      headerContent={(
+        <TableControls
+          bulkActions={[
+            { displayName: 'Export selected', callback: api => api.exportDataAsCsv() },
+            { displayName: 'Delete selected', callback: handleDelete, disabled: !canDelete },
+          ]}
+        />
+      )}
+    />
+  );
+}
+export default MyTable;
+`.trim(),
+        },
+      },
+    },
+    args: {
+      bulkActions: [
+        { displayName: 'Export selected', callback: fn() },
+        { displayName: 'Archive selected', callback: fn() },
+        { displayName: 'Delete selected', callback: fn(), disabled: true },
+      ],
+    },
+  },
+  'Only the `bulkActions` slot in the start group — no other controls. '
+  + 'Bulk actions render as a `BulkActionsDropdown`. The `callback` receives the AG Grid `GridApi` instance '
+  + 'so you can directly call `api.exportDataAsCsv()`, `api.getSelectedRows()`, etc. '
+  + 'Pass `disabled: true` to a specific action to grey it out (e.g. "Delete selected" when nothing is selected).',
+);
+
+export const FullToolbar: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table, TableControls } from '@arbor-education/design-system.components';
+
+function FullTableExample() {
+  return (
+    <Table
+      rowData={rows}
+      columnDefs={colDefs}
+      rowSelection={{ mode: 'multiRow', checkboxes: true }}
+      headerContent={(
+        <TableControls
+          bulkActions={[
+            { displayName: 'Export selected', callback: api => api.exportDataAsCsv() },
+            { displayName: 'Delete selected', callback: handleDelete },
+          ]}
+          onUndo={handleUndo}
+          onRedo={handleRedo}
+          showHideColumns
+          onDownload={handleDownload}
+          showSettings
+          onHelp={openHelpPanel}
+          onExpandToggle={setExpanded}
+        />
+      )}
+    />
+  );
+}
+export default FullTableExample;
+`.trim(),
+        },
+      },
+    },
+    args: {
+      bulkActions: [
+        { displayName: 'Export selected', callback: fn() },
+        { displayName: 'Delete selected', callback: fn() },
+      ],
+      onUndo: fn(),
+      onRedo: fn(),
+      showHideColumns: false,
+      onDownload: fn(),
+      showSettings: true,
+      onHelp: fn(),
+      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.',
+);

package/src/components/table/tableControls/TableSettingsDropdown.test.tsx

@@ -0,0 +1,207 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+import '@testing-library/jest-dom/vitest';
+import { TableSettingsDropdown } from './TableSettingsDropdown';
+import { TableSettingsContext } from '../TableSettingsContext';
+import { TABLE_SPACING } from '../tableConsts';
+import { useTableSettings } from '../useTableSettings';
+
+const buildContextValue = (overrides: Partial<ReturnType<typeof useTableSettings>> = {}) => ({
+  settings: {
+    hasColumnBorders: false,
+    tableSpacing: TABLE_SPACING.S,
+    areCellColorsEnabled: true,
+  },
+  setTableSpacing: vi.fn(),
+  setHasColumnBorders: vi.fn(),
+  resetSettings: vi.fn(),
+  setAreCellColorsEnabled: vi.fn(),
+  ...overrides,
+});
+
+const renderDropdown = (
+  ui: React.ReactElement,
+  contextValue = buildContextValue(),
+) => {
+  return render(
+    <TableSettingsContext.Provider value={contextValue}>
+      {ui}
+    </TableSettingsContext.Provider>,
+  );
+};
+
+const openDropdown = async () => {
+  const trigger = screen.getByRole('button', { name: /table settings/i });
+  await userEvent.click(trigger);
+};
+
+describe('TableSettingsDropdown', () => {
+  describe('default items (no items prop)', () => {
+    test('renders the settings trigger button', () => {
+      renderDropdown(<TableSettingsDropdown />);
+      expect(screen.getByRole('button', { name: /table settings/i })).toBeInTheDocument();
+    });
+
+    test('shows table spacing radio group when opened', async () => {
+      renderDropdown(<TableSettingsDropdown />);
+      await openDropdown();
+      expect(await screen.findByRole('group', { name: /table spacing/i })).toBeInTheDocument();
+    });
+
+    test('shows column borders checkbox when opened', async () => {
+      renderDropdown(<TableSettingsDropdown />);
+      await openDropdown();
+      expect(await screen.findByRole('checkbox', { name: /column borders/i })).toBeInTheDocument();
+    });
+
+    test('shows cell colours checkbox when opened', async () => {
+      renderDropdown(<TableSettingsDropdown />);
+      await openDropdown();
+      expect(await screen.findByRole('checkbox', { name: /cell colours/i })).toBeInTheDocument();
+    });
+
+    test('shows reset button when opened', async () => {
+      renderDropdown(<TableSettingsDropdown />);
+      await openDropdown();
+      expect(await screen.findByRole('button', { name: /reset table settings/i })).toBeInTheDocument();
+    });
+  });
+
+  describe('items prop - opt-in to specific built-in items', () => {
+    test('shows only table spacing when items contains only tableSpacing', async () => {
+      renderDropdown(<TableSettingsDropdown items={['tableSpacing']} />);
+      await openDropdown();
+      expect(await screen.findByRole('group', { name: /table spacing/i })).toBeInTheDocument();
+      expect(screen.queryByRole('checkbox', { name: /column borders/i })).not.toBeInTheDocument();
+      expect(screen.queryByRole('checkbox', { name: /cell colours/i })).not.toBeInTheDocument();
+    });
+
+    test('shows both style checkboxes when style is included in items', async () => {
+      renderDropdown(<TableSettingsDropdown items={['style']} />);
+      await openDropdown();
+      expect(await screen.findByRole('checkbox', { name: /column borders/i })).toBeInTheDocument();
+      expect(screen.getByRole('checkbox', { name: /cell colours/i })).toBeInTheDocument();
+    });
+
+    test('does not render table spacing when not included in items', async () => {
+      renderDropdown(<TableSettingsDropdown items={['style']} />);
+      await openDropdown();
+      await screen.findByRole('checkbox', { name: /column borders/i });
+      expect(screen.queryByRole('group', { name: /table spacing/i })).not.toBeInTheDocument();
+    });
+
+    test('does not render style checkboxes when style is not included in items', async () => {
+      renderDropdown(<TableSettingsDropdown items={['tableSpacing']} />);
+      await openDropdown();
+      await screen.findByRole('group', { name: /table spacing/i });
+      expect(screen.queryByRole('checkbox', { name: /column borders/i })).not.toBeInTheDocument();
+      expect(screen.queryByRole('checkbox', { name: /cell colours/i })).not.toBeInTheDocument();
+    });
+  });
+
+  describe('separator item', () => {
+    test('renders a separator when separator is included in items', async () => {
+      renderDropdown(<TableSettingsDropdown items={['tableSpacing', 'separator', 'style']} />);
+      await openDropdown();
+      await screen.findByRole('group', { name: /table spacing/i });
+      // 2 separators: 1 from the items array, 1 always-present above the reset button
+      expect(screen.getAllByRole('separator')).toHaveLength(2);
+    });
+  });
+
+  describe('custom items - checkboxGroup', () => {
+    test('renders a checkbox group with the provided legend', async () => {
+      const customItem = { type: 'checkboxGroup' as const, legend: 'View options', options: [{ label: 'Show archived rows', checked: false, onChange: vi.fn() }] };
+      renderDropdown(<TableSettingsDropdown items={[customItem]} />);
+      await openDropdown();
+      expect(await screen.findByRole('group', { name: /view options/i })).toBeInTheDocument();
+    });
+
+    test('renders custom checkbox options with provided labels', async () => {
+      const customItem = { type: 'checkboxGroup' as const, options: [{ label: 'Show archived rows', checked: false, onChange: vi.fn() }] };
+      renderDropdown(<TableSettingsDropdown items={[customItem]} />);
+      await openDropdown();
+      expect(await screen.findByRole('checkbox', { name: /show archived rows/i })).toBeInTheDocument();
+    });
+
+    test('reflects the checked state of a custom checkbox option', async () => {
+      const customItem = { type: 'checkboxGroup' as const, options: [{ label: 'Show archived rows', checked: true, onChange: vi.fn() }] };
+      renderDropdown(<TableSettingsDropdown items={[customItem]} />);
+      await openDropdown();
+      const checkbox = await screen.findByRole('checkbox', { name: /show archived rows/i });
+      expect(checkbox).toBeChecked();
+    });
+
+    test('calls onChange with the new checked value when a custom checkbox option is clicked', async () => {
+      const onChange = vi.fn();
+      const customItem = { type: 'checkboxGroup' as const, options: [{ label: 'Show archived rows', checked: false, onChange }] };
+      renderDropdown(<TableSettingsDropdown items={[customItem]} />);
+      await openDropdown();
+      const checkbox = await screen.findByRole('checkbox', { name: /show archived rows/i });
+      await userEvent.click(checkbox);
+      expect(onChange).toHaveBeenCalledWith(true);
+    });
+  });
+
+  describe('custom items - radioGroup', () => {
+    const buildRadioItem = (overrides = {}) => ({
+      type: 'radioGroup' as const,
+      legend: 'Grouping',
+      name: 'ds-grouping',
+      checkedValue: 'week',
+      onChange: vi.fn(),
+      options: [
+        { label: 'Day', value: 'day' },
+        { label: 'Week', value: 'week' },
+      ],
+      ...overrides,
+    });
+
+    test('renders a radio group with the provided legend', async () => {
+      renderDropdown(<TableSettingsDropdown items={[buildRadioItem()]} />);
+      await openDropdown();
+      expect(await screen.findByRole('group', { name: /grouping/i })).toBeInTheDocument();
+    });
+
+    test('renders custom radio options with provided labels', async () => {
+      renderDropdown(<TableSettingsDropdown items={[buildRadioItem()]} />);
+      await openDropdown();
+      expect(await screen.findByRole('radio', { name: /day/i })).toBeInTheDocument();
+      expect(screen.getByRole('radio', { name: /week/i })).toBeInTheDocument();
+    });
+
+    test('reflects the checkedValue by checking the matching radio', async () => {
+      renderDropdown(<TableSettingsDropdown items={[buildRadioItem({ checkedValue: 'day' })]} />);
+      await openDropdown();
+      expect(await screen.findByRole('radio', { name: /day/i })).toBeChecked();
+      expect(screen.getByRole('radio', { name: /week/i })).not.toBeChecked();
+    });
+
+    test('calls onChange with the selected value when a radio option is clicked', async () => {
+      const onChange = vi.fn();
+      renderDropdown(<TableSettingsDropdown items={[buildRadioItem({ onChange })]} />);
+      await openDropdown();
+      const dayRadio = await screen.findByRole('radio', { name: /day/i });
+      await userEvent.click(dayRadio);
+      expect(onChange).toHaveBeenCalledWith('day');
+    });
+  });
+
+  describe('reset button', () => {
+    test('reset button is always present regardless of items prop', async () => {
+      renderDropdown(<TableSettingsDropdown items={['tableSpacing']} />);
+      await openDropdown();
+      expect(await screen.findByRole('button', { name: /reset table settings/i })).toBeInTheDocument();
+    });
+
+    test('calls resetSettings from context when reset button is clicked', async () => {
+      const resetSettings = vi.fn();
+      renderDropdown(<TableSettingsDropdown />, buildContextValue({ resetSettings }));
+      await openDropdown();
+      const resetButton = await screen.findByRole('button', { name: /reset table settings/i });
+      await userEvent.click(resetButton);
+      expect(resetSettings).toHaveBeenCalledTimes(1);
+    });
+  });
+});