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

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

@@ -0,0 +1,196 @@
+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 { TableFooter } from './TableFooter';
+import { PaginationPanel } from './pagination/PaginationPanel';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`TableFooter` is the pre-composed footer slot for the Arbor data table.',
+  'It renders a `<footer>` element and accepts any `children` (typically a `<PaginationPanel />` element).',
+  '',
+  'Pass the entire `<TableFooter />` element as the `footerContent` prop of `<Table />`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- As the `footerContent` of a `<Table />` when you need a standard footer region',
+  '- When you want to wrap `<PaginationPanel />` in the footer slot',
+  '- When you need custom footer content beyond pagination controls',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Alternative |',
+  '|---|---|',
+  '| You only need pagination | Pass `<PaginationPanel />` directly as `footerContent` |',
+  '| The table has no footer | Omit `footerContent` entirely |',
+  '',
+  '---',
+  '',
+  '### Props summary',
+  '',
+  '| Prop | Description |',
+  '|---|---|',
+  '| `children` | Content rendered inside the footer — typically `<PaginationPanel />` |',
+  '| `className` | Additional CSS class name(s) on the root `<footer>` element |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Wiring into `<Table />`',
+  '',
+  '```tsx',
+  "import { Table, TableFooter, PaginationPanel } from '@arbor-education/design-system.components';",
+  '',
+  'function MyTable() {',
+  '  return (',
+  '    <Table',
+  '      rowData={rows}',
+  '      columnDefs={colDefs}',
+  '      footerContent={(',
+  '        <TableFooter>',
+  '          <PaginationPanel',
+  '            availableSizes={[10, 25, 50, 100]}',
+  '            initialPageSize={25}',
+  '            onPageSizeChange={setPageSize}',
+  '          />',
+  '        </TableFooter>',
+  '      )}',
+  '    />',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### `TableFooter` vs passing `<PaginationPanel />` directly',
+  '',
+  '`<TableFooter />` adds the `ds-table__footer` class and `<footer>` semantic element around its',
+  'children. If you only need pagination, passing `<PaginationPanel />` directly as `footerContent`',
+  'is also valid — `<Table />` renders `footerContent` inside its own footer region.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [PaginationPanel](?path=/docs/components-table-paginationpanel--docs) · [TableHeader](?path=/docs/components-table-tableheader--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel. `TableFooter` is a thin layout wrapper — its main value is the semantic `<footer>` element and `ds-table__footer` class it applies around its children.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function TableFooterDocsPage() {
+  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/TableFooter',
+  component: TableFooter,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: TableFooterDocsPage },
+  },
+  argTypes: {
+    children: {
+      description: 'Content rendered inside the footer. Typically a `<PaginationPanel />` element.',
+      control: false,
+      table: { type: { summary: 'ReactNode' }, defaultValue: { summary: 'undefined' } },
+    },
+    className: {
+      description: 'Additional CSS class name(s) to apply to the root `<footer>` element.',
+      control: 'text',
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'undefined' } },
+    },
+  },
+} satisfies Meta<typeof TableFooter>;
+
+export default meta;
+type Story = StoryObj<typeof TableFooter>;
+
+// ---------------------------------------------------------------------------
+// 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: {
+      children: (
+        <PaginationPanel
+          totalPages={10}
+          onPageChange={fn()}
+          availableSizes={[10, 25, 50, 100]}
+          initialPageSize={25}
+          onPageSizeChange={fn()}
+        />
+      ),
+    },
+  },
+  'The canonical usage — `TableFooter` wrapping a `<PaginationPanel />`. '
+  + '`RowCountInfo` (the row count text) is not visible in this standalone preview because it '
+  + 'requires `GridApiContext` provided by a wrapping `<Table />`.',
+);
+
+export const WithCustomContent: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      children: (
+        <span style={{ padding: '8px 16px', fontSize: '14px', color: 'var(--color-neutral-500)' }}>
+          Custom footer content — e.g. totals, status messages, or secondary actions
+        </span>
+      ),
+    },
+  },
+  '`TableFooter` accepts any `ReactNode` as `children` — not just `PaginationPanel`. '
+  + 'Use it to add totals rows, status messages, or any other custom footer content.',
+);

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

@@ -0,0 +1,251 @@
+import React from 'react';
+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 { TableHeader } from './TableHeader';
+import { TableControls } from './tableControls/TableControls';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`TableHeader` is the pre-composed header slot for the Arbor data table.',
+  'It renders a `<header>` element and accepts any `children` (typically a `<TableControls />` element)',
+  'plus an optional built-in `<SearchBar />` via the `hasSearch` prop.',
+  '',
+  'Pass the entire `<TableHeader />` element as the `headerContent` prop of `<Table />`.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- As the `headerContent` of a `<Table />` when you need a standard header region',
+  '- When you want to combine a toolbar (`<TableControls />`) with a search bar in one slot',
+  '- When you need custom header content that is not covered by `<TableControls />`',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Alternative |',
+  '|---|---|',
+  '| You only need a toolbar | Pass `<TableControls />` directly as `headerContent` |',
+  '| You only need a search bar | Pass `<SearchBar />` directly as `headerContent` |',
+  '| The table has no header | Omit `headerContent` entirely |',
+  '',
+  '---',
+  '',
+  '### Props summary',
+  '',
+  '| Prop | Description |',
+  '|---|---|',
+  '| `children` | Content rendered before the `SearchBar` — typically `<TableControls />` |',
+  '| `hasSearch` | When `true`, renders a `<SearchBar />` at the end of the header |',
+  '| `searchValue` | Controlled value for the `SearchBar` |',
+  '| `setSearchValue` | Called with the new search string when the user types |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Wiring into `<Table />`',
+  '',
+  '```tsx',
+  "import { useState } from 'react';",
+  "import { Table, TableHeader, TableControls } from '@arbor-education/design-system.components';",
+  '',
+  'function MyTable() {',
+  "  const [search, setSearch] = useState('');",
+  '',
+  '  return (',
+  '    <Table',
+  '      rowData={rows}',
+  '      columnDefs={colDefs}',
+  '      quickFilterText={search}',
+  '      headerContent={(',
+  '        <TableHeader hasSearch searchValue={search} setSearchValue={setSearch}>',
+  '          <TableControls',
+  '            onUndo={handleUndo}',
+  '            onDownload={handleDownload}',
+  '            showSettings',
+  '          />',
+  '        </TableHeader>',
+  '      )}',
+  '    />',
+  '  );',
+  '}',
+  '```',
+  '',
+  '---',
+  '',
+  '### `hasSearch` vs passing `<SearchBar />` directly',
+  '',
+  'Both approaches are equivalent. `TableHeader` with `hasSearch` is more concise when you already',
+  'have `TableHeader` for the `children` slot. If you only need a search bar and no other header',
+  'content, pass `<SearchBar />` directly as `headerContent` without wrapping it in `TableHeader`.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [TableControls](?path=/docs/components-table-tablecontrols--docs) · [TableFooter](?path=/docs/components-table-tablefooter--docs) · [SearchBar](?path=/docs/components-searchbar--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — toggle `hasSearch` to add or remove the search bar.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function TableHeaderDocsPage() {
+  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/TableHeader',
+  component: TableHeader,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: TableHeaderDocsPage },
+  },
+  argTypes: {
+    children: {
+      description: 'Content rendered inside the header before the `SearchBar`. Typically a `<TableControls />` element.',
+      control: false,
+      table: { type: { summary: 'ReactNode' }, defaultValue: { summary: 'undefined' } },
+    },
+    hasSearch: {
+      description: 'When `true`, renders a `<SearchBar />` at the end of the header.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    searchValue: {
+      description: 'Controlled value for the `SearchBar`. Only used when `hasSearch` is `true`.',
+      control: 'text',
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'undefined' } },
+    },
+    setSearchValue: {
+      description: 'Called with the new search string when the user types. Only used when `hasSearch` is `true`.',
+      control: false,
+      table: { type: { summary: '(searchValue: string) => void' }, defaultValue: { summary: 'undefined' } },
+    },
+    className: {
+      description: 'Additional CSS class name(s) to apply to the root `<header>` element.',
+      control: 'text',
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'undefined' } },
+    },
+  },
+  args: {
+    setSearchValue: fn(),
+  },
+} satisfies Meta<typeof TableHeader>;
+
+export default meta;
+type Story = StoryObj<typeof TableHeader>;
+
+// ---------------------------------------------------------------------------
+// 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: {
+      hasSearch: false,
+      children: (
+        <TableControls
+          onUndo={fn()}
+          onRedo={fn()}
+          onDownload={fn()}
+          showSettings
+          onHelp={fn()}
+          onExpandToggle={fn()}
+        />
+      ),
+    },
+  },
+  'The interactive canvas — `TableHeader` wrapping a `<TableControls />` element, which is the canonical usage. '
+  + 'Toggle `hasSearch` in the Controls panel to add the built-in `SearchBar`.',
+);
+
+export const WithSearch: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => {
+      const [search, setSearch] = React.useState('');
+      return (
+        <TableHeader hasSearch searchValue={search} setSearchValue={setSearch}>
+          <TableControls
+            onUndo={fn()}
+            onRedo={fn()}
+            onDownload={fn()}
+            showSettings
+          />
+        </TableHeader>
+      );
+    },
+  },
+  '`hasSearch={true}` adds a `SearchBar` at the end of the header. '
+  + '`searchValue` and `setSearchValue` give you controlled access to the search string — '
+  + "pass it as `quickFilterText` to `<Table />` to drive AG Grid's built-in text filtering.",
+);
+
+export const ChildrenOnly: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    args: {
+      children: (
+        <TableControls
+          bulkActions={[
+            { displayName: 'Export selected', callback: fn() },
+            { displayName: 'Delete selected', callback: fn(), disabled: true },
+          ]}
+          onUndo={fn()}
+          onRedo={fn()}
+        />
+      ),
+    },
+  },
+  'The header slot with only `children` — no built-in search bar. '
+  + 'Any `ReactNode` is accepted as `children`; `<TableControls />` is the most common choice.',
+);

package/src/components/table/cellEditors/DateCellEditor.stories.tsx

@@ -0,0 +1,245 @@
+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 type { CustomCellEditorProps } from 'ag-grid-react';
+import { DateCellEditor } from './DateCellEditor';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`DateCellEditor` is an AG Grid cell editor component that renders an Arbor `DatePicker` inside a table cell.',
+  'It is invoked when a user begins editing a date column (e.g. by pressing Enter or double-clicking the cell).',
+  '',
+  'Register it via the AG Grid `cellEditor` column definition property.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On date columns that need an inline date-picker editor',
+  '- When users should be able to edit a date value directly in the table without leaving the row',
+  '',
+  '---',
+  '',
+  '### Registration',
+  '',
+  '```tsx',
+  "import { DateCellEditor } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'dob',",
+  "    headerName: 'Date of birth',",
+  '    cellEditor: DateCellEditor,',
+  '    // or via string key:',
+  "    cellEditor: 'dsDateCellEditor',",
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### `cellEditorParams`',
+  '',
+  'Any additional props to pass to the underlying `DatePicker` can be provided via `cellEditorParams`:',
+  '',
+  '```tsx',
+  'cellEditorParams: {',
+  "  placeholder: 'dd/mm/yyyy',",
+  '  disabled: false,',
+  '},',
+  '```',
+  '',
+  '---',
+  '',
+  '### Value format',
+  '',
+  'The `value` and `onValueChange` use the same date format as the Arbor `DatePicker`.',
+  'Refer to the [DatePicker docs](?path=/docs/components-datepicker--docs) for format details.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [DatePicker](?path=/docs/components-datepicker--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below shows `DateCellEditor` rendering the Arbor `DatePicker` with a pre-set date value. In a real table this component is mounted by AG Grid when the user begins editing a date cell.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function DateCellEditorDocsPage() {
+  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>Examples</DocHeading>
+      <Stories title="" />
+      <Markdown>{RELATED_COMPONENTS}</Markdown>
+    </>
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const makeEditorProps = (value: Date | undefined): CustomCellEditorProps => ({
+  value,
+  onValueChange: fn(),
+  colDef: { cellEditorParams: {} },
+} as unknown as CustomCellEditorProps);
+
+// ---------------------------------------------------------------------------
+// Meta
+// ---------------------------------------------------------------------------
+
+const meta = {
+  title: 'Components/Table/CellEditors/DateCellEditor',
+  component: DateCellEditor,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: DateCellEditorDocsPage },
+  },
+  argTypes: {
+    value: {
+      description: 'The current date value of the cell being edited. Format matches the Arbor `DatePicker` value format.',
+      control: false,
+      table: { type: { summary: 'string' }, defaultValue: { summary: 'undefined' } },
+    },
+    onValueChange: {
+      description: 'Called by AG Grid when the editor value changes. Receives the new date value.',
+      control: false,
+      table: { type: { summary: '(value: string) => void' } },
+    },
+  },
+} satisfies Meta<typeof DateCellEditor>;
+
+export default meta;
+type Story = StoryObj<typeof DateCellEditor>;
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    render: () => <DateCellEditor {...makeEditorProps(undefined)} />,
+  },
+  'The `DateCellEditor` with no initial value — renders an empty `DatePicker` ready for input.',
+);
+
+export const WithExistingDate: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => <DateCellEditor {...makeEditorProps(new Date('2024-09-01'))} />,
+  },
+  'Pre-populated with an existing date value. In a table, AG Grid passes the cell\'s current value as `value` when the editor opens.',
+);
+
+const DATE_EDITOR_IN_TABLE_DATA = [
+  { name: 'Alice Johnson', dateOfBirth: new Date(1990, 0, 15) },
+  { name: 'Bob Smith', dateOfBirth: new Date(1985, 5, 20) },
+  { name: 'Charlie Brown', dateOfBirth: new Date(1992, 10, 3) },
+  { name: 'Diana Prince', dateOfBirth: new Date(1988, 3, 12) },
+];
+
+export const InATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const rowData = [
+  { name: 'Alice Johnson', dateOfBirth: new Date(1990, 0, 15) },
+  { name: 'Bob Smith', dateOfBirth: new Date(1985, 5, 20) },
+  { name: 'Charlie Brown', dateOfBirth: new Date(1992, 10, 3) },
+  { name: 'Diana Prince', dateOfBirth: new Date(1988, 3, 12) },
+];
+
+function DateCellEditorExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2, editable: false },
+        {
+          field: 'dateOfBirth',
+          headerName: 'Date of birth',
+          flex: 1,
+          editable: true,
+          cellEditor: 'dsDateCellEditor',
+          valueFormatter: (params) =>
+            params.value instanceof Date
+              ? params.value.toLocaleDateString('en-GB')
+              : params.value,
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default DateCellEditorExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={DATE_EDITOR_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2, editable: false },
+          {
+            field: 'dateOfBirth',
+            headerName: 'Date of birth',
+            flex: 1,
+            editable: true,
+            cellEditor: 'dsDateCellEditor',
+            valueFormatter: params =>
+              params.value instanceof Date
+                ? params.value.toLocaleDateString('en-GB')
+                : params.value,
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsDateCellEditor` wired up inside a full `Table`. Double-click (or press F2/Enter) on a Date of birth cell to open the `DatePicker` editor — AG Grid mounts the editor component and passes the current cell value as `value`. The `valueFormatter` formats the stored `Date` object as a localised string for display.',
+);