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

package/src/components/table/cellRenderers/CheckboxCellRenderer.stories.tsx

@@ -0,0 +1,337 @@
+import { useState } 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 type { CustomCellRendererProps } from 'ag-grid-react';
+import { CheckboxCellRenderer } from './CheckboxCellRenderer';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`CheckboxCellRenderer` is an AG Grid cell renderer that renders an editable Arbor `CheckboxInput`',
+  'inside a table cell. On toggle, it calls `node.setDataValue` to update the row data in-place.',
+  '',
+  'Register it via the string key `dsCheckboxCellRenderer` (pre-registered by Arbor\'s `Table`) or by importing the component directly.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On boolean columns that the user needs to toggle directly in the table without opening a form',
+  '- "Active", "Enrolled", "Consent given" columns where inline editing is expected',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Display-only boolean (no editing) | `BooleanCellRenderer` (`dsBooleanCellRenderer`) |',
+  '| Toggling the value requires confirmation or a side effect | Handle in a modal; do not edit inline |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`column` must be provided for changes to persist.**',
+  'On toggle, the renderer calls `node.setDataValue(column, !value)`. If `column` is not available in',
+  'props (which should not happen inside a real AG Grid), the change is silently ignored.',
+  '',
+  '**`aria-label` is derived from `colDef.headerName`.**',
+  'Always set `headerName` on the column definition — without it, the checkbox has no accessible label.',
+  'Override with `cellRendererParams: { "aria-label": "..." }` if needed.',
+  '',
+  '**Pass extra `CheckboxInput` props via `cellRendererParams`.**',
+  'The renderer spreads `cellRendererParams` onto `CheckboxInput`, so you can pass `disabled`, `className`, etc.',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'isEnrolled',",
+  "    headerName: 'Enrolled',",
+  "    cellRenderer: 'dsCheckboxCellRenderer',",
+  '    // optional extra CheckboxInput props:',
+  '    cellRendererParams: { disabled: isReadOnly },',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'The `aria-label` is set to `"Checkbox: {headerName}"` when `headerName` is defined. Without it,',
+  'the checkbox has no accessible label — WCAG 2.1 failure (1.3.1 Info and Relationships).',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { CheckboxCellRenderer } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '`CheckboxCellRenderer` accepts `CustomCellRendererProps` from AG Grid.',
+  '`value` should be a `boolean`. Additional `CheckboxInput` props can be passed via `colDef.cellRendererParams`.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [BooleanCellRenderer](?path=/docs/components-table-cellrenderers-booleancellrenderer--docs) · [CheckboxInput](?path=/docs/components-checkboxinput--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below uses a mock AG Grid row node — click the checkbox to see it toggle. `node.setDataValue` is wired to local state in this preview; in a real table it updates the row data directly.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function CheckboxCellRendererDocsPage() {
+  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/CellRenderers/CheckboxCellRenderer',
+  component: CheckboxCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: CheckboxCellRendererDocsPage },
+  },
+  argTypes: {
+    value: {
+      control: false,
+      description: 'The current boolean state of the checkbox. On toggle, the renderer calls `node.setDataValue(column, !value)`.',
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+      },
+    },
+    node: {
+      control: false,
+      description: 'AG Grid row node. The renderer calls `node.setDataValue` on toggle.',
+      table: { type: { summary: 'IRowNode' } },
+    },
+    column: {
+      control: false,
+      description: 'AG Grid column instance. Passed as the first argument to `node.setDataValue`.',
+      table: { type: { summary: 'Column | null' } },
+    },
+    colDef: {
+      control: false,
+      description: '`headerName` is used as the basis of the checkbox `aria-label`. Extra `CheckboxInput` props can be passed via `cellRendererParams`.',
+      table: { type: { summary: 'ColDef' } },
+    },
+  },
+} satisfies Meta<typeof CheckboxCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof CheckboxCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const InteractiveTemplate = () => {
+  const [checked, setChecked] = useState(false);
+  const mockNode = { setDataValue: (_: unknown, val: boolean) => setChecked(val) } as CustomCellRendererProps['node'];
+  const mockColumn = {} as CustomCellRendererProps['column'];
+
+  return (
+    <CheckboxCellRenderer
+      {...({} as unknown as CustomCellRendererProps)}
+      value={checked}
+      node={mockNode}
+      column={mockColumn}
+      colDef={{ headerName: 'Enrolled' }}
+    />
+  );
+};
+
+const DisabledTemplate = ({ checked }: { checked: boolean }) => (
+  <CheckboxCellRenderer
+    {...({} as unknown as CustomCellRendererProps)}
+    value={checked}
+    node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+    column={{} as CustomCellRendererProps['column']}
+    colDef={{ headerName: 'Enrolled', cellRendererParams: { disabled: true } }}
+  />
+);
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: InteractiveTemplate,
+  },
+  'An interactive `CheckboxInput` backed by a mock row node. Click to toggle — `node.setDataValue` updates local state in this preview; in a real table it updates the AG Grid row data in-place.',
+);
+
+export const Checked: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const colDefs = [
+  {
+    field: 'isEnrolled',
+    headerName: 'Enrolled',
+    cellRenderer: 'dsCheckboxCellRenderer',
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => <DisabledTemplate checked={true} />,
+  },
+  'Checked state — `value={true}`. The `aria-label` is derived from `colDef.headerName` ("Checkbox: Enrolled").',
+);
+
+export const Unchecked: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => <DisabledTemplate checked={false} />,
+  },
+  'Unchecked state — `value={false}`.',
+);
+
+export const DisabledChecked: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <CheckboxCellRenderer
+        {...({} as unknown as CustomCellRendererProps)}
+        value={true}
+        node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+        column={{} as CustomCellRendererProps['column']}
+        colDef={{ headerName: 'Enrolled', cellRendererParams: { disabled: true } }}
+      />
+    ),
+  },
+  'Disabled state — pass `disabled: true` via `cellRendererParams` to prevent the user from toggling the value. Useful for read-only rows or conditional editing logic.',
+);
+
+const CHECKBOX_IN_TABLE_DATA = [
+  { name: 'Alice Johnson', enrolled: true },
+  { name: 'Bob Smith', enrolled: false },
+  { name: 'Charlie Brown', enrolled: true },
+  { name: 'Diana Prince', enrolled: false },
+];
+
+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', enrolled: true },
+  { name: 'Bob Smith', enrolled: false },
+  { name: 'Charlie Brown', enrolled: true },
+  { name: 'Diana Prince', enrolled: false },
+];
+
+function CheckboxCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2 },
+        {
+          field: 'enrolled',
+          headerName: 'Enrolled',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsCheckboxCellRenderer',
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default CheckboxCellRendererExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={CHECKBOX_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'enrolled',
+            headerName: 'Enrolled',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsCheckboxCellRenderer',
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsCheckboxCellRenderer` wired up inside a full `Table`. Click a checkbox to toggle the value — AG Grid calls `node.setDataValue` which updates the row data in-place. The `headerName` ("Enrolled") becomes the checkbox `aria-label`.',
+);

package/src/components/table/cellRenderers/CheckboxCellRenderer.tsx

@@ -11,6 +11,10 @@ export const CheckboxCellRenderer = (props: CustomCellRendererProps) => {
 
   const { cellRendererParams, headerName } = colDef;
 
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  const { suppressCellFocusAndFocusFirstElement, suppressMouseEventHandling, ...checkboxParams }
+    = (cellRendererParams ?? {}) as Record<string, unknown>;
+
   return (
     <div className="ds-checkbox-cell-renderer">
       <CheckboxInput
@@ -21,7 +25,7 @@ export const CheckboxCellRenderer = (props: CustomCellRendererProps) => {
             node.setDataValue(column, !value);
           }
         }}
-        {...cellRendererParams}
+        {...checkboxParams}
       />
     </div>
   );

package/src/components/table/cellRenderers/DefaultCellRenderer.stories.tsx

@@ -0,0 +1,342 @@
+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 { CustomCellRendererProps } from 'ag-grid-react';
+import { DefaultCellRenderer } from './DefaultCellRenderer';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`DefaultCellRenderer` is the internal default cell renderer used by Arbor\'s `Table`. It renders',
+  '`valueFormatted` when available, falls back to `value.value`, and renders an empty `div` for',
+  '`null` or `undefined`. It also supports an optional `dataTestId` via `colDef.cellRendererParams`.',
+  '',
+  '**You rarely need to register this renderer explicitly.** AG Grid uses it automatically for all',
+  'columns in an Arbor Table.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- When you need to add a `dataTestId` to a cell for automated testing',
+  '- When you want to be explicit about using the default renderer in a column definition',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| The column needs interactive controls | `CheckboxCellRenderer`, `ButtonCellRenderer`, or `SelectDropdownCellRenderer` |',
+  '| The column renders a boolean flag | `BooleanCellRenderer` |',
+  '| You want formatted text output | A `valueFormatter` on the column — `DefaultCellRenderer` renders `valueFormatted` automatically |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Value resolution order:**',
+  '1. Uses `valueFormatted` if it exists and is NOT the string `"[object Object]"`',
+  '2. Falls back to `value.value`',
+  '3. Renders an empty `<div>` for `null` or `undefined`',
+  '',
+  'This means a `valueFormatter` on the column will always take precedence over the raw value.',
+  '',
+  '**`dataTestId` must be passed via `colDef.cellRendererParams`** — it is not a direct prop.',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'name',",
+  "    headerName: 'Name',",
+  '    // Explicit registration — only needed when you want a dataTestId:',
+  '    cellRenderer: DefaultCellRenderer,',
+  '    cellRendererParams: {',
+  "      dataTestId: 'student-name-cell',",
+  '    },',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'No specific accessibility requirements — this renderer renders plain text. Ensure your `valueFormatter`',
+  'returns a human-readable string, not a raw object (which would produce `"[object Object]"`).',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { DefaultCellRenderer } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '`DefaultCellRenderer` accepts `CustomCellRendererProps` from AG Grid.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [BooleanCellRenderer](?path=/docs/components-table-cellrenderers-booleancellrenderer--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below shows `DefaultCellRenderer` in its various value states. This renderer is used internally by Arbor\'s Table — its Controls are not individually wired to the grid runtime.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function DefaultCellRendererDocsPage() {
+  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 MOCK_CELL_PROPS = {} as unknown as CustomCellRendererProps;
+
+const meta = {
+  title: 'Components/Table/CellRenderers/DefaultCellRenderer',
+  component: DefaultCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: DefaultCellRendererDocsPage },
+  },
+  argTypes: {
+    valueFormatted: {
+      control: false,
+      description: 'String produced by AG Grid\'s `valueFormatter`. Takes precedence over `value.value` unless it equals `"[object Object]"`.',
+      table: {
+        type: { summary: 'string | undefined' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    value: {
+      control: false,
+      description: 'The raw cell value from AG Grid. The renderer reads `value.value` as a fallback when `valueFormatted` is not set.',
+      table: {
+        type: { summary: '{ value: string | number | null | undefined } | any' },
+      },
+    },
+    colDef: {
+      control: false,
+      description: 'Pass `cellRendererParams: { dataTestId: "..." }` to add a test ID to the cell `div`.',
+      table: {
+        type: { summary: 'ColDef' },
+      },
+    },
+  },
+} satisfies Meta<typeof DefaultCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof DefaultCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// Helper: attach a per-story description to docs
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <DefaultCellRenderer
+        {...MOCK_CELL_PROPS}
+        valueFormatted="Smith, Alice"
+        value={{ value: 'smith-alice' }}
+        colDef={{}}
+      />
+    ),
+  },
+  '`valueFormatted` takes precedence — the renderer displays "Smith, Alice" (the formatted value) rather than "smith-alice" (the raw value).',
+);
+
+export const RawValueFallback: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <DefaultCellRenderer
+        {...MOCK_CELL_PROPS}
+        valueFormatted={undefined}
+        value={{ value: 'Unformatted cell value' }}
+        colDef={{}}
+      />
+    ),
+  },
+  'When `valueFormatted` is not set, the renderer falls back to `value.value`.',
+);
+
+export const Empty: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <DefaultCellRenderer
+        {...MOCK_CELL_PROPS}
+        valueFormatted={undefined}
+        value={{ value: null }}
+        colDef={{}}
+      />
+    ),
+  },
+  '`null` or `undefined` resolved values render an empty `<div>`. The cell is blank but the DOM element is present (useful for `dataTestId` targeting).',
+);
+
+export const WithDataTestId: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { DefaultCellRenderer } from '@arbor-education/design-system.components';
+
+const colDefs = [
+  {
+    field: 'name',
+    headerName: 'Name',
+    cellRenderer: DefaultCellRenderer,
+    cellRendererParams: {
+      dataTestId: 'student-name-cell',
+    },
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <DefaultCellRenderer
+        {...MOCK_CELL_PROPS}
+        valueFormatted="Smith, Alice"
+        value={{ value: 'smith-alice' }}
+        colDef={{ cellRendererParams: { dataTestId: 'student-name-cell' } }}
+      />
+    ),
+  },
+  'Pass `dataTestId` via `colDef.cellRendererParams` to add a `data-testid` attribute to the cell `div`. Inspect the rendered element to see `data-testid="student-name-cell"`.',
+);
+
+const DEFAULT_IN_TABLE_DATA = [
+  { name: { value: 'Alice Johnson' }, role: { value: 'Developer' } },
+  { name: { value: 'Bob Smith' }, role: { value: 'Designer' } },
+  { name: { value: 'Charlie Brown' }, role: { value: 'Manager' } },
+];
+
+export const InATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table, DefaultCellRenderer } from '@arbor-education/design-system.components';
+
+const rowData = [
+  { name: { value: 'Alice Johnson' }, role: { value: 'Developer' } },
+  { name: { value: 'Bob Smith' }, role: { value: 'Designer' } },
+  { name: { value: 'Charlie Brown' }, role: { value: 'Manager' } },
+];
+
+function DefaultCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        {
+          field: 'name',
+          headerName: 'Name',
+          flex: 2,
+          cellRenderer: DefaultCellRenderer,
+          cellRendererParams: { dataTestId: 'name-cell' },
+          valueFormatter: Table.DefaultValueFormatter,
+        },
+        {
+          field: 'role',
+          headerName: 'Role',
+          flex: 1,
+          valueFormatter: Table.DefaultValueFormatter,
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default DefaultCellRendererExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={DEFAULT_IN_TABLE_DATA}
+        columnDefs={[
+          {
+            field: 'name',
+            headerName: 'Name',
+            flex: 2,
+            cellRenderer: DefaultCellRenderer,
+            cellRendererParams: { dataTestId: 'name-cell' },
+            valueFormatter: Table.DefaultValueFormatter,
+          },
+          {
+            field: 'role',
+            headerName: 'Role',
+            flex: 1,
+            valueFormatter: Table.DefaultValueFormatter,
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`DefaultCellRenderer` registered explicitly on the Name column to attach a `dataTestId`. Row data uses the `{ value: string }` object shape — `Table.DefaultValueFormatter` formats it for display, and `DefaultCellRenderer` reads `value.value` as its fallback. Inspect the Name cells in DevTools to see `data-testid="name-cell"`.',
+);