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

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

@@ -0,0 +1,292 @@
+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 { InlineTextCellRenderer } from './InlineTextCellRenderer';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`InlineTextCellRenderer` is an AG Grid cell renderer that renders a `TextInput` permanently',
+  'inside a table cell for inline text editing. Pressing Enter commits the current value via',
+  '`node.setDataValue`. The input is pre-populated from `valueFormatted ?? value`.',
+  '',
+  'Register it via the string key `dsInlineTextCellRenderer` (pre-registered by Arbor\'s `Table`) or by importing the component directly.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- When users need to edit text values directly in the table row without opening a modal or form',
+  '- Short, single-field edits (names, codes, quantities) where the editing context is clear',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Editing a date value | `DateCellEditor` (`dsDateCellEditor`) |',
+  '| Selecting from a list of options | `SelectDropdownCellRenderer` (`dsSelectDropdownCellRenderer`) |',
+  '| The edit requires validation before saving | A form in a modal — inline editing skips the validation step |',
+  '| The field is long-form text | A full text area in a slideover or modal |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**This is a renderer, not an editor — the `TextInput` is always visible.**',
+  'Unlike AG Grid\'s native cell editors (which mount only during edit mode), `InlineTextCellRenderer`',
+  'renders the `TextInput` permanently in the cell.',
+  '',
+  '**Pressing Enter commits the value via `node.setDataValue`.**',
+  'The renderer attaches a `keydown` listener to the cell wrapper on mount. Pressing Enter calls',
+  '`node.setDataValue(column, currentInputValue)`. If `column` is not in props, Enter is a no-op.',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'forename',",
+  "    headerName: 'First name',",
+  "    cellRenderer: 'dsInlineTextCellRenderer',",
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'The `TextInput` inside the cell has no explicit label — the column header provides visual context.',
+  'For screen readers, add an `aria-label` via `cellRendererParams: { "aria-label": "..." }`.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { InlineTextCellRenderer } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '`InlineTextCellRenderer` extends `CustomCellRendererProps` with `value: string`.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [SelectDropdownCellRenderer](?path=/docs/components-table-cellrenderers-selectdropdowncellrenderer--docs) · [TextInput](?path=/docs/components-textinput--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below shows `InlineTextCellRenderer` with a pre-populated value. Type in the input to see it update. Pressing Enter would call `node.setDataValue` — in this preview that call is a no-op since there is no AG Grid row node.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function InlineTextCellRendererDocsPage() {
+  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/InlineTextCellRenderer',
+  component: InlineTextCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: InlineTextCellRendererDocsPage },
+  },
+  argTypes: {
+    value: {
+      control: false,
+      description: 'The initial text value displayed in the `TextInput`. The component manages its own internal state from this initial value.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: "''" },
+      },
+    },
+    valueFormatted: {
+      control: false,
+      description: 'If provided, used as the initial text value instead of `value`. Set by AG Grid\'s `valueFormatter`.',
+      table: {
+        type: { summary: 'string | undefined' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+    node: {
+      control: false,
+      description: 'AG Grid row node. The renderer calls `node.setDataValue` when the user presses Enter.',
+      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' } },
+    },
+  },
+} satisfies Meta<typeof InlineTextCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof InlineTextCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// 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: () => (
+      <InlineTextCellRenderer
+        {...MOCK_CELL_PROPS}
+        value="Alice Smith"
+      />
+    ),
+  },
+  'Pre-populated with an existing value. The `TextInput` is always visible — type to update the internal value, then press Enter to commit (in a real table, Enter calls `node.setDataValue`).',
+);
+
+export const Empty: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const colDefs = [
+  {
+    field: 'forename',
+    headerName: 'First name',
+    cellRenderer: 'dsInlineTextCellRenderer',
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <InlineTextCellRenderer
+        {...MOCK_CELL_PROPS}
+        value=""
+      />
+    ),
+  },
+  'Empty initial state — the `TextInput` is blank and ready for input. This is the state for a new row with no existing data.',
+);
+
+const INLINE_TEXT_IN_TABLE_DATA = [
+  { fullName: 'Alice Johnson', forename: 'Alice' },
+  { fullName: 'Bob Smith', forename: 'Bob' },
+  { fullName: 'Charlie Brown', forename: 'Charlie' },
+];
+
+export const InATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const rowData = [
+  { fullName: 'Alice Johnson', forename: 'Alice' },
+  { fullName: 'Bob Smith', forename: 'Bob' },
+  { fullName: 'Charlie Brown', forename: 'Charlie' },
+];
+
+function InlineTextCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'fullName', headerName: 'Full Name', flex: 2, editable: false },
+        {
+          field: 'forename',
+          headerName: 'First Name',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsInlineTextCellRenderer',
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default InlineTextCellRendererExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={INLINE_TEXT_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'fullName', headerName: 'Full Name', flex: 2, editable: false },
+          {
+            field: 'forename',
+            headerName: 'First Name',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsInlineTextCellRenderer',
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsInlineTextCellRenderer` wired up inside a full `Table`. Click into any First Name cell to start editing — the `TextInput` is always visible. Press Enter to commit the value via `node.setDataValue`, updating the row data in-place.',
+);

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

@@ -0,0 +1,369 @@
+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 { GridApi } from 'ag-grid-community';
+import type { CustomCellRendererProps } from 'ag-grid-react';
+import { SelectDropdownCellRenderer } from './SelectDropdownCellRenderer';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`SelectDropdownCellRenderer` is an AG Grid cell renderer that renders an Arbor `SelectDropdown`',
+  'permanently inside a table cell. It listens for `cellKeyDown` events on the Grid API to open the',
+  'dropdown when the user presses Enter in the focused cell. On selection, it calls `node.setDataValue`',
+  'to update the row data in-place.',
+  '',
+  'Register it via the string key `dsSelectDropdownCellRenderer` (pre-registered by Arbor\'s `Table`) or by importing the component directly.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On columns where the user must choose from a fixed list of options (status, category, type)',
+  '- When the options are the same for every row',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| Options vary per row | A custom cell renderer with a `SelectDropdown` and per-row option logic |',
+  '| The user can select multiple options in one cell | Not currently supported — use a form in a modal |',
+  '| The list is very long (100+ options) | A searchable select or a modal with filtering |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`api` is required.**',
+  'The renderer attaches a `cellKeyDown` listener to the Grid API on mount so that pressing Enter',
+  'in the focused cell opens the dropdown. Without `api`, the keyboard shortcut is silently skipped',
+  'but the dropdown still renders and is clickable.',
+  '',
+  '**`options` must be passed via `cellRendererParams`.**',
+  'Options are not part of the cell `value` — configure them in `cellRendererParams`.',
+  'Option `value` fields are normalised to strings internally for comparison, but the original value',
+  '(string or number) is restored when calling `node.setDataValue`.',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'status',",
+  "    headerName: 'Status',",
+  "    cellRenderer: 'dsSelectDropdownCellRenderer',",
+  '    cellRendererParams: {',
+  '      options: [',
+  "        { label: 'Active', value: 'active' },",
+  "        { label: 'Inactive', value: 'inactive' },",
+  "        { label: 'Pending', value: 'pending' },",
+  '      ],',
+  "      placeholder: 'Select status',",
+  '    },',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'Pressing Enter in a focused cell opens the dropdown — no mouse click required.',
+  'The `SelectDropdown` handles full keyboard navigation internally (arrow keys, Enter/Escape).',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { SelectDropdownCellRenderer } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '`SelectDropdownCellRenderer` extends `CustomCellRendererProps` with `SelectDropdownInputProps`.',
+  '`options` and `placeholder` are the most commonly used extra props.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [SelectDropdown](?path=/docs/components-selectdropdown--docs) · [InlineTextCellRenderer](?path=/docs/components-table-cellrenderers-inlinetextcellrenderer--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below shows `SelectDropdownCellRenderer` with a set of status options. The dropdown can be opened by clicking it — the Enter-key shortcut requires a live AG Grid API and is a no-op in this preview.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function SelectDropdownCellRendererDocsPage() {
+  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_API = {
+  addEventListener: () => {},
+  removeEventListener: () => {},
+} as unknown as GridApi;
+
+const MOCK_CELL_PROPS = {} as unknown as CustomCellRendererProps;
+
+const STATUS_OPTIONS = [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' },
+  { label: 'Pending', value: 'pending' },
+];
+
+const meta = {
+  title: 'Components/Table/CellRenderers/SelectDropdownCellRenderer',
+  component: SelectDropdownCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: SelectDropdownCellRendererDocsPage },
+  },
+  argTypes: {
+    value: {
+      control: false,
+      description: 'The currently selected option value. Used to set the initial selection in the `SelectDropdown`.',
+      table: {
+        type: { summary: 'string | number | null | undefined' },
+      },
+    },
+    options: {
+      control: false,
+      description: 'The list of options to display in the dropdown. Passed via `cellRendererParams` in the column definition.',
+      table: {
+        type: { summary: 'Array<{ label: string; value: string | number }>' },
+        defaultValue: { summary: '[]' },
+      },
+    },
+    placeholder: {
+      control: false,
+      description: 'Placeholder text shown when no option is selected.',
+      table: {
+        type: { summary: 'string' },
+        defaultValue: { summary: '"Select"' },
+      },
+    },
+    api: {
+      control: false,
+      description: 'AG Grid API. Required for the Enter-key shortcut that opens the dropdown. Provided automatically by AG Grid.',
+      table: { type: { summary: 'GridApi' } },
+    },
+    node: {
+      control: false,
+      description: 'AG Grid row node. The renderer calls `node.setDataValue` on option selection.',
+      table: { type: { summary: 'IRowNode' } },
+    },
+  },
+} satisfies Meta<typeof SelectDropdownCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof SelectDropdownCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// 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: () => (
+      <SelectDropdownCellRenderer
+        {...MOCK_CELL_PROPS}
+        api={MOCK_API}
+        value=""
+        options={STATUS_OPTIONS}
+        placeholder="Select status"
+        node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+        column={{} as CustomCellRendererProps['column']}
+      />
+    ),
+  },
+  'No selection — the `SelectDropdown` shows the placeholder text. Click to open the dropdown and select an option.',
+);
+
+export const WithSelection: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const colDefs = [
+  {
+    field: 'status',
+    headerName: 'Status',
+    cellRenderer: 'dsSelectDropdownCellRenderer',
+    cellRendererParams: {
+      options: [
+        { label: 'Active', value: 'active' },
+        { label: 'Inactive', value: 'inactive' },
+        { label: 'Pending', value: 'pending' },
+      ],
+      placeholder: 'Select status',
+    },
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <SelectDropdownCellRenderer
+        {...MOCK_CELL_PROPS}
+        api={MOCK_API}
+        value="active"
+        options={STATUS_OPTIONS}
+        placeholder="Select status"
+        node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+        column={{} as CustomCellRendererProps['column']}
+      />
+    ),
+  },
+  'Pre-selected with `value="active"`. The `SelectDropdown` initialises with the matching option selected.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <SelectDropdownCellRenderer
+        {...MOCK_CELL_PROPS}
+        api={MOCK_API}
+        value="active"
+        options={STATUS_OPTIONS}
+        placeholder="Select status"
+        disabled={true}
+        node={{ setDataValue: () => {} } as unknown as CustomCellRendererProps['node']}
+        column={{} as CustomCellRendererProps['column']}
+      />
+    ),
+  },
+  'Pass `disabled: true` via `cellRendererParams` to prevent the user from changing the selection for specific rows.',
+);
+
+const SELECT_IN_TABLE_DATA = [
+  { name: 'Alice Johnson', status: 'active' },
+  { name: 'Bob Smith', status: 'inactive' },
+  { name: 'Charlie Brown', status: 'pending' },
+  { name: 'Diana Prince', status: 'active' },
+];
+
+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', status: 'active' },
+  { name: 'Bob Smith', status: 'inactive' },
+  { name: 'Charlie Brown', status: 'pending' },
+  { name: 'Diana Prince', status: 'active' },
+];
+
+const statusOptions = [
+  { label: 'Active', value: 'active' },
+  { label: 'Inactive', value: 'inactive' },
+  { label: 'Pending', value: 'pending' },
+];
+
+function SelectDropdownCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2 },
+        {
+          field: 'status',
+          headerName: 'Status',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsSelectDropdownCellRenderer',
+          cellRendererParams: { options: statusOptions },
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default SelectDropdownCellRendererExample;
+`.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 },
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsSelectDropdownCellRenderer` wired up inside a full `Table`. Click a Status dropdown to select a new value — the selection is committed to the row via `node.setDataValue`. Press Enter in a focused Status cell to open the dropdown via keyboard.',
+);