@arbor-education/design-system.components 0.25.6 → 0.25.8

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

@@ -0,0 +1,346 @@
+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 { NumberInputCellRenderer } from './NumberInputCellRenderer.js';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`NumberInputCellRenderer` is an AG Grid cell renderer that renders an editable Arbor `NumberInput`',
+  'permanently inside a table cell. On change, it calls `node.setDataValue` to update the row data in-place.',
+  '',
+  'Register it via the string key `dsNumberInputCellRenderer` (pre-registered by Arbor\'s `Table`) or by importing the component directly.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On numeric columns where the user edits a value directly in the table without opening a form',
+  '- Quantities, counts, scores, or any bounded numeric field that should be editable inline',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Display-only number (no editing) | Plain AG Grid value formatting or `DefaultCellRenderer` |',
+  '| The edit requires confirmation or a side effect | Handle in a modal; do not edit inline |',
+  '| Free-form decimal entry without step constraints | A form in a slideover |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`colDef.field` must be set for changes to persist.**',
+  'On change, the renderer calls `node.setDataValue(colDef.field, parsedValue)`. If `field` is not set',
+  'on the column definition, the change is silently ignored.',
+  '',
+  '**Non-finite input (empty or non-numeric) is coerced to `0`.**',
+  'If the user clears the input, `setDataValue` is called with `0` rather than `NaN`.',
+  '',
+  '**Pass `min`, `max`, and `disabled` via `cellRendererParams`.**',
+  'These are forwarded directly to `NumberInput`.',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'quantity',",
+  "    headerName: 'Quantity',",
+  "    cellRenderer: 'dsNumberInputCellRenderer',",
+  '    cellRendererParams: { min: 0, max: 100 },',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { NumberInputCellRenderer } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '`NumberInputCellRenderer` accepts `CustomCellRendererProps` from AG Grid plus `value: number | null`,',
+  '`min?: number`, `max?: number`, and `disabled?: boolean` (passed via `cellRendererParams`).',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [NumberInput](?path=/docs/components-numberinput--docs) · [CheckboxCellRenderer](?path=/docs/components-table-cellrenderers-checkboxcellrenderer--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below uses a mock AG Grid row node. Type a value or use the +/− spinners — `node.setDataValue` is wired to local state in this preview; in a real table it updates the row data in-place.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function NumberInputCellRendererDocsPage() {
+  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/NumberInputCellRenderer',
+  component: NumberInputCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: NumberInputCellRendererDocsPage },
+  },
+  argTypes: {
+    value: {
+      control: false,
+      description: 'Current numeric value. `null` is rendered as `0`. On change, the parsed float is written back via `node.setDataValue`.',
+      table: {
+        type: { summary: 'number | null' },
+        defaultValue: { summary: 'null' },
+      },
+    },
+    min: {
+      control: false,
+      description: 'Minimum allowed value. The minus spinner is disabled when the value reaches this bound.',
+      table: { type: { summary: 'number' } },
+    },
+    max: {
+      control: false,
+      description: 'Maximum allowed value. The plus spinner is disabled when the value reaches this bound.',
+      table: { type: { summary: 'number' } },
+    },
+    disabled: {
+      control: false,
+      description: 'When `true`, the input and spinners are non-interactive.',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
+    node: {
+      control: false,
+      description: 'AG Grid row node. The renderer calls `node.setDataValue` on each value change.',
+      table: { type: { summary: 'IRowNode' } },
+    },
+    colDef: {
+      control: false,
+      description: '`colDef.field` is used as the key passed to `node.setDataValue`. Changes are silently ignored when `field` is absent.',
+      table: { type: { summary: 'ColDef' } },
+    },
+  },
+} satisfies Meta<typeof NumberInputCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof NumberInputCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// Helper
+// ---------------------------------------------------------------------------
+
+const withDescription = (story: Story, description: string): Story => ({
+  ...story,
+  parameters: {
+    ...story.parameters,
+    docs: { ...story.parameters?.docs, description: { story: description } },
+  },
+});
+
+// ---------------------------------------------------------------------------
+// Template components
+// ---------------------------------------------------------------------------
+
+const InteractiveTemplate = () => {
+  const [count, setCount] = useState<number>(5);
+  const mockNode = { setDataValue: (_: unknown, val: number) => setCount(val) } as CustomCellRendererProps['node'];
+
+  return (
+    <NumberInputCellRenderer
+      {...({} as unknown as CustomCellRendererProps)}
+      value={count}
+      node={mockNode}
+      colDef={{ field: 'count' }}
+    />
+  );
+};
+
+// ---------------------------------------------------------------------------
+// Stories
+// ---------------------------------------------------------------------------
+
+export const Default: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: InteractiveTemplate,
+  },
+  'Interactive `NumberInput` backed by a mock row node. Use the +/− spinners or type directly — `node.setDataValue` updates local state in this preview; in a real table it updates AG Grid row data in-place.',
+);
+
+export const WithMinMax: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => {
+      const [val, setVal] = useState<number>(5);
+      const mockNode = { setDataValue: (_: unknown, v: number) => setVal(v) } as CustomCellRendererProps['node'];
+
+      return (
+        <NumberInputCellRenderer
+          {...({} as unknown as CustomCellRendererProps)}
+          value={val}
+          min={0}
+          max={10}
+          node={mockNode}
+          colDef={{ field: 'count' }}
+        />
+      );
+    },
+  },
+  'Bounded range via `min={0}` and `max={10}`. The minus spinner disables at `0`; the plus spinner disables at `10`. Values typed outside the range are clamped on blur.',
+);
+
+export const NullValue: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <NumberInputCellRenderer
+        {...({} as unknown as CustomCellRendererProps)}
+        value={null}
+        node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+        colDef={{ field: 'count' }}
+      />
+    ),
+  },
+  '`value={null}` is coerced to `0` before being passed to `NumberInput`. This keeps the input always controlled with a valid numeric display.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <NumberInputCellRenderer
+        {...({} as unknown as CustomCellRendererProps)}
+        value={7}
+        disabled
+        node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+        colDef={{ field: 'count' }}
+      />
+    ),
+  },
+  'Disabled state — pass `disabled: true` via `cellRendererParams` to prevent editing. Useful for read-only rows or conditional editing logic.',
+);
+
+const NUMBER_INPUT_TABLE_DATA = [
+  { name: 'Alice Johnson', sessions: 12, score: 95 },
+  { name: 'Bob Smith', sessions: 8, score: 72 },
+  { name: 'Charlie Brown', sessions: 15, score: 88 },
+  { name: 'Diana Prince', sessions: 3, score: 60 },
+];
+
+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', sessions: 12, score: 95 },
+  { name: 'Bob Smith', sessions: 8, score: 72 },
+  { name: 'Charlie Brown', sessions: 15, score: 88 },
+  { name: 'Diana Prince', sessions: 3, score: 60 },
+];
+
+function NumberInputCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2 },
+        {
+          field: 'sessions',
+          headerName: 'Sessions',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsNumberInputCellRenderer',
+          cellRendererParams: { min: 0, suppressCellFocusAndFocusFirstElement: true },
+        },
+        {
+          field: 'score',
+          headerName: 'Score (/100)',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsNumberInputCellRenderer',
+          cellRendererParams: { min: 0, max: 100, suppressCellFocusAndFocusFirstElement: true },
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={NUMBER_INPUT_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'sessions',
+            headerName: 'Sessions',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsNumberInputCellRenderer',
+            cellRendererParams: { min: 0, suppressCellFocusAndFocusFirstElement: true },
+          },
+          {
+            field: 'score',
+            headerName: 'Score (/100)',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsNumberInputCellRenderer',
+            cellRendererParams: { min: 0, max: 100, suppressCellFocusAndFocusFirstElement: true },
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsNumberInputCellRenderer` wired up inside a full `Table`. Sessions has `min={0}`; Score has `min={0}` and `max={100}`. Edit any cell — AG Grid calls `node.setDataValue` which updates the row data in-place.',
+);

package/src/components/table/cellRenderers/NumberInputCellRenderer.test.tsx

@@ -0,0 +1,99 @@
+import { describe, expect, test, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import '@testing-library/jest-dom/vitest';
+import userEvent from '@testing-library/user-event';
+import type { CustomCellRendererProps } from 'ag-grid-react';
+import { NumberInputCellRenderer } from './NumberInputCellRenderer.js';
+
+const createMockProps = (overrides: Partial<CustomCellRendererProps & { value: number | null; min?: number; max?: number; disabled?: boolean }> = {}): CustomCellRendererProps => ({
+  value: 0,
+  node: { setDataValue: vi.fn() },
+  colDef: { field: 'count' },
+  ...overrides,
+} as unknown as CustomCellRendererProps);
+
+describe('NumberInputCellRenderer', () => {
+  test('renders a number input', () => {
+    render(<NumberInputCellRenderer {...createMockProps()} />);
+    expect(screen.getByRole('textbox')).toBeInTheDocument();
+  });
+
+  test('renders the supplied value in the input', () => {
+    render(<NumberInputCellRenderer {...createMockProps({ value: 42 })} />);
+    expect(screen.getByRole('textbox')).toHaveValue('42');
+  });
+
+  test('renders null value as 0', () => {
+    render(<NumberInputCellRenderer {...createMockProps({ value: null })} />);
+    expect(screen.getByRole('textbox')).toHaveValue('0');
+  });
+
+  test('disables the input when disabled prop is true', () => {
+    render(<NumberInputCellRenderer {...createMockProps({ disabled: true })} />);
+    expect(screen.getByRole('textbox')).toBeDisabled();
+  });
+
+  test('minus button is disabled when value equals min', () => {
+    render(<NumberInputCellRenderer {...createMockProps({ value: 5, min: 5 })} />);
+    expect(screen.getByRole('button', { name: 'Minus button' })).toBeDisabled();
+  });
+
+  test('plus button is disabled when value equals max', () => {
+    render(<NumberInputCellRenderer {...createMockProps({ value: 10, max: 10 })} />);
+    expect(screen.getByRole('button', { name: 'Plus button' })).toBeDisabled();
+  });
+
+  test('calls node.setDataValue with the updated value when the input changes', async () => {
+    const setDataValue = vi.fn();
+    render(
+      <NumberInputCellRenderer
+        {...createMockProps({
+          value: 5,
+          node: { setDataValue } as unknown as CustomCellRendererProps['node'],
+          colDef: { field: 'count' },
+        })}
+      />,
+    );
+    setDataValue.mockClear();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Plus button' }));
+
+    expect(setDataValue).toHaveBeenCalledWith('count', 6);
+  });
+
+  test('calls node.setDataValue with 0 when the input is cleared', async () => {
+    const setDataValue = vi.fn();
+    render(
+      <NumberInputCellRenderer
+        {...createMockProps({
+          value: 5,
+          node: { setDataValue } as unknown as CustomCellRendererProps['node'],
+          colDef: { field: 'count' },
+        })}
+      />,
+    );
+    setDataValue.mockClear();
+
+    await userEvent.clear(screen.getByRole('textbox'));
+
+    expect(setDataValue).toHaveBeenCalledWith('count', 0);
+  });
+
+  test('does not call node.setDataValue when colDef.field is undefined', async () => {
+    const setDataValue = vi.fn();
+    render(
+      <NumberInputCellRenderer
+        {...createMockProps({
+          value: 5,
+          node: { setDataValue } as unknown as CustomCellRendererProps['node'],
+          colDef: {},
+        })}
+      />,
+    );
+    setDataValue.mockClear();
+
+    await userEvent.click(screen.getByRole('button', { name: 'Plus button' }));
+
+    expect(setDataValue).not.toHaveBeenCalled();
+  });
+});

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

@@ -0,0 +1,36 @@
+import type { CustomCellRendererProps } from 'ag-grid-react';
+import { NumberInput } from 'Components/formField/inputs/number/NumberInput';
+
+type NumberInputCellRendererProps = {
+  value: number | null;
+  min?: number;
+  max?: number;
+  disabled?: boolean;
+} & CustomCellRendererProps;
+
+export const NumberInputCellRenderer = (
+  props: NumberInputCellRendererProps,
+) => {
+  const { value, min, max, disabled, node, colDef = {} } = props;
+
+  return (
+    <div className="cell-input-wrapper">
+      <NumberInput
+        min={min}
+        max={max}
+        disabled={disabled}
+        value={value ?? 0}
+        onChange={(e) => {
+          if (!colDef.field) {
+            return;
+          }
+          const next = parseFloat(e.currentTarget.value);
+          node.setDataValue(
+            colDef.field,
+            Number.isFinite(next) ? next : 0,
+          );
+        }}
+      />
+    </div>
+  );
+};

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

@@ -211,6 +211,14 @@ const meta = {
         defaultValue: { summary: 'false' },
       },
     },
+    onCloseAutoFocus: {
+      control: false,
+      description: 'Called when focus is about to return to the ag-grid cell after the dropdown closes (e.g. after selecting an option). Call `event.preventDefault()` to stop radix\'s default restore-to-cell behaviour and move focus elsewhere yourself.',
+      table: {
+        type: { summary: '(event: Event) => void' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
   },
 } satisfies Meta<typeof SelectDropdownCellRenderer>;
 
@@ -718,3 +726,62 @@ const columnDefs = [
   },
   '(fillCell + colored) Marksheet with grade-driven cell colours. Each cell uses `backgroundColor` (derived per-row from the current grade) and `fillCell: true` so the colour spans the cell edge-to-edge, plus `cellStyle: { padding: 0 }` to strip ag-grid\'s default cell padding. `iconClickOnly: true` is set so cell selection works — click anywhere in a cell to select it (or shift/drag for a range), and only the chevron icon opens the grade picker. Text colour auto-switches between dark and white for legibility against each background.',
 );
+
+export const CustomCloseFocus: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const columnDefs = [
+  { field: 'name', headerName: 'Name', flex: 2 },
+  {
+    field: 'status',
+    headerName: 'Status',
+    cellRenderer: 'dsSelectDropdownCellRenderer',
+    cellRendererParams: {
+      options: statusOptions,
+      onCloseAutoFocus: (event) => {
+        event.preventDefault();
+        window.alert('Dropdown closed — running custom focus handler');
+      },
+    },
+  },
+];
+
+<Table rowData={rowData} columnDefs={columnDefs} domLayout="autoHeight" />
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={SELECT_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'status',
+            headerName: 'Status',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsSelectDropdownCellRenderer',
+            cellRendererParams: {
+              options: STATUS_OPTIONS,
+              onCloseAutoFocus: (event: Event) => {
+                event.preventDefault();
+                window.alert('Dropdown closed — running custom focus handler');
+              },
+            },
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  'Passes `onCloseAutoFocus` via `cellRendererParams` to override what happens to focus when the dropdown closes. Open a Status dropdown and pick an option (or press Escape) — instead of radix restoring focus to the cell, the handler calls `event.preventDefault()` and fires a `window.alert`. In a real app you would move focus to a specific element here rather than alert.',
+);

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

@@ -52,6 +52,7 @@ export const SelectDropdownCellRenderer = (
     backgroundColor,
     fillCell = false,
     iconClickOnly = false,
+    onCloseAutoFocus,
   } = props;
 
   const textContrast = backgroundColor ? getTextContrast(backgroundColor) : null;
@@ -113,6 +114,7 @@ export const SelectDropdownCellRenderer = (
         onOpenChange={setIsOpen}
         multiple={false}
         iconClickOnly={iconClickOnly}
+        onCloseAutoFocus={onCloseAutoFocus}
         onSelectionChange={(newValue) => {
           if (column && newValue[0] != null) {
             const selectedOption = rawOptions.find(

package/src/index.ts

@@ -69,6 +69,7 @@ export { DSDefaultColDef } from 'Components/table/DSDefaultColDef';
 export { GridApiContext } from 'Components/table/GridApiContext';
 export { NumberCellEditor } from 'Components/table/cellEditors/NumberCellEditor';
 export { CheckboxCellRenderer } from 'Components/table/cellRenderers/CheckboxCellRenderer';
+export { NumberInputCellRenderer } from 'Components/table/cellRenderers/NumberInputCellRenderer';
 export { Table } from 'Components/table/Table';
 export { Tabs } from 'Components/tabs/Tabs';
 export { Tag } from 'Components/tag/Tag';