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

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

@@ -0,0 +1,278 @@
+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 { BooleanCellRenderer } from './BooleanCellRenderer';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`BooleanCellRenderer` is an AG Grid cell renderer that displays boolean values as icons.',
+  'A `true` value renders a green check icon; a `false` value renders a red ✕ icon;',
+  'any other value (including `null` and `undefined`) renders nothing.',
+  '',
+  'Register it via the string key `dsBooleanCellRenderer` (pre-registered by Arbor\'s `Table`) or by importing the component directly.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On boolean columns where a visual icon is clearer than plain `true`/`false` text',
+  '- Active/inactive flags, yes/no columns, on/off states that are read-only',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| User needs to toggle the value in the cell | `CheckboxCellRenderer` (`dsCheckboxCellRenderer`) |',
+  '| You want text labels like "Yes" / "No" | A `valueFormatter` returning strings, with the default renderer |',
+  '| The value is truthy/falsy but not strictly boolean | Coerce to `true`/`false` first — see Developer notes |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**Value comparison is strict — only `true` and `false` produce icons.**',
+  'The renderer checks `value === true` and `value === false`. Truthy values like `1`, `"yes"`, or objects render nothing.',
+  'Coerce your data to a strict boolean before passing to this column.',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    field: 'isActive',",
+  "    headerName: 'Active',",
+  "    cellRenderer: 'dsBooleanCellRenderer',  // string key — no import needed",
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'Icons include `screenReaderText` props (`"true"` and `"false"`) so screen readers announce',
+  "the cell's boolean meaning rather than describing the icon shape.",
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { BooleanCellRenderer } from '@arbor-education/design-system.components';",
+  '```',
+  '',
+  '`BooleanCellRenderer` accepts `CustomCellRendererProps` from AG Grid — only `value` is used by this renderer.',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [CheckboxCellRenderer](?path=/docs/components-table-cellrenderers-checkboxcellrenderer--docs) · [Icon](?path=/docs/components-icon--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below is wired to the **Controls** panel — use the `value` selector to see how `true`, `false`, and `null` each render.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function BooleanCellRendererDocsPage() {
+  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/BooleanCellRenderer',
+  component: BooleanCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: BooleanCellRendererDocsPage },
+  },
+  argTypes: {
+    value: {
+      control: { type: 'select' },
+      options: [true, false, null],
+      description: 'The cell value. `true` renders a green check icon; `false` renders a red ✕ icon; any other value renders nothing.',
+      table: {
+        type: { summary: 'true | false | null | undefined' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
+} satisfies Meta<typeof BooleanCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof BooleanCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// 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(
+  {
+    args: { value: true },
+    render: args => <BooleanCellRenderer {...MOCK_CELL_PROPS} value={args.value} />,
+  },
+  'Interactive example — select `true`, `false`, or `null` from the **Controls** panel to see how each value renders.',
+);
+
+export const True: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const colDefs = [
+  {
+    field: 'isActive',
+    headerName: 'Active',
+    cellRenderer: 'dsBooleanCellRenderer',
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => <BooleanCellRenderer {...MOCK_CELL_PROPS} value={true} />,
+  },
+  'A `true` value renders a green check icon. The icon carries `screenReaderText="true"` for assistive technology.',
+);
+
+export const False: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => <BooleanCellRenderer {...MOCK_CELL_PROPS} value={false} />,
+  },
+  'A `false` value renders a red ✕ icon. The icon carries `screenReaderText="false"` for assistive technology.',
+);
+
+export const Empty: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => <BooleanCellRenderer {...MOCK_CELL_PROPS} value={null} />,
+  },
+  '`null`, `undefined`, or any non-boolean value renders nothing — the cell is intentionally left empty. This is by design: the renderer uses strict `=== true` / `=== false` comparisons, not truthiness.',
+);
+
+const BOOLEAN_IN_TABLE_DATA = [
+  { name: 'Alice Johnson', active: true },
+  { name: 'Bob Smith', active: false },
+  { name: 'Charlie Brown', active: true },
+  { name: 'Diana Prince', active: null },
+];
+
+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', active: true },
+  { name: 'Bob Smith', active: false },
+  { name: 'Charlie Brown', active: true },
+  { name: 'Diana Prince', active: null },
+];
+
+function BooleanCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2 },
+        {
+          field: 'active',
+          headerName: 'Active',
+          flex: 1,
+          editable: false,
+          cellRenderer: 'dsBooleanCellRenderer',
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default BooleanCellRendererExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={BOOLEAN_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          {
+            field: 'active',
+            headerName: 'Active',
+            flex: 1,
+            editable: false,
+            cellRenderer: 'dsBooleanCellRenderer',
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsBooleanCellRenderer` wired up inside a full `Table`. `true` renders a check, `false` renders a ✕, and `null` leaves the cell empty. The Active column is set to `editable: false` — this renderer is display-only.',
+);

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

@@ -0,0 +1,333 @@
+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 { ButtonCellRenderer } from './ButtonCellRenderer';
+import { Table } from 'Components/table/Table';
+
+// ---------------------------------------------------------------------------
+// Docs page content
+// ---------------------------------------------------------------------------
+
+const DESCRIPTION_INTRO = [
+  '`ButtonCellRenderer` is an AG Grid cell renderer that renders an Arbor `Button` inside a table cell.',
+  'The cell `value` (or `valueFormatted`) must be a `ButtonProps` object — the renderer spreads it',
+  'directly onto `Button`, so all button variants, sizes, and handlers are supported.',
+  '',
+  'Register it via the string key `dsButtonCellRenderer` (pre-registered by Arbor\'s `Table`) or by importing the component directly.',
+].join('\n');
+
+const USAGE_GUIDANCE = [
+  '### When to use',
+  '',
+  '- On action columns where each row needs a button (e.g. "View", "Edit", "Delete")',
+  '- When the action is contextual to the row — the `onClick` handler receives the event and can close over row data',
+  '',
+  '---',
+  '',
+  '### When NOT to use',
+  '',
+  '| Situation | Use instead |',
+  '|---|---|',
+  '| The action navigates to another page | A link (`<a>`) cell renderer or AG Grid\'s built-in link support |',
+  '| Every row shares the exact same static label with no per-row variation | A column header action button outside the grid |',
+].join('\n');
+
+const DEVELOPER_NOTES = [
+  '### Critical usage patterns',
+  '',
+  '**`value` must be a `ButtonProps` object with a `children` key.**',
+  'The renderer reads `value.children` as the button label. If `children` is absent it falls back to `value.value`.',
+  'All other `ButtonProps` (`variant`, `size`, `onClick`, `disabled`) are spread onto `Button`.',
+  '',
+  '**Provide the ButtonProps via `valueGetter` — the cell field value must BE the ButtonProps object.**',
+  '',
+  '```tsx',
+  "import { Table } from '@arbor-education/design-system.components';",
+  '',
+  'const colDefs = [',
+  '  {',
+  "    colId: 'viewAction',",
+  "    headerName: '',",
+  "    cellRenderer: 'dsButtonCellRenderer',",
+  '    valueGetter: (params) => ({',
+  "      children: 'View',",
+  "      variant: 'secondary',",
+  "      size: 'S',",
+  '      onClick: () => handleView(params.data),',
+  '    }),',
+  '  },',
+  '];',
+  '```',
+  '',
+  '---',
+  '',
+  '### Accessibility',
+  '',
+  'Each cell\'s button inherits its accessible name from `children`. If `children` is an icon with no',
+  'visible text, add `aria-label` to the ButtonProps object.',
+  '',
+  '---',
+  '',
+  '### TypeScript types',
+  '',
+  '```ts',
+  "import { ButtonCellRenderer } from '@arbor-education/design-system.components';",
+  "import type { ButtonProps } from '@arbor-education/design-system.components';",
+  '',
+  '// In your valueGetter:',
+  '// (params): ButtonProps => ({ children: "View", variant: "secondary", onClick: ... })',
+  '```',
+].join('\n');
+
+const RELATED_COMPONENTS = [
+  '## Related components',
+  '',
+  '[Table](?path=/docs/components-table--docs) · [Button](?path=/docs/components-button--docs)',
+].join('\n');
+
+const PROPS_INTRO = 'The preview below shows `ButtonCellRenderer` with representative button configurations. The `value` prop is a `ButtonProps` object — most individual props are not separately controllable via the Controls panel.';
+
+// ---------------------------------------------------------------------------
+// Custom DocsPage
+// ---------------------------------------------------------------------------
+
+function ButtonCellRendererDocsPage() {
+  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/ButtonCellRenderer',
+  component: ButtonCellRenderer,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: { page: ButtonCellRendererDocsPage },
+  },
+  argTypes: {
+    value: {
+      control: false,
+      description: 'A `ButtonProps` object. The `children` key becomes the button label; all other `ButtonProps` (`variant`, `size`, `onClick`, `disabled`) are spread onto the `Button` component.',
+      table: {
+        type: { summary: 'ButtonProps' },
+      },
+    },
+    valueFormatted: {
+      control: false,
+      description: 'If provided, overrides `value` as the source for button props. Set by AG Grid\'s `valueFormatter`.',
+      table: {
+        type: { summary: 'ButtonProps | undefined' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
+  },
+} satisfies Meta<typeof ButtonCellRenderer>;
+
+export default meta;
+type Story = StoryObj<typeof ButtonCellRenderer>;
+
+// ---------------------------------------------------------------------------
+// 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: () => (
+      <ButtonCellRenderer
+        {...MOCK_CELL_PROPS}
+        value={{ children: 'View details', variant: 'secondary', size: 'S' }}
+      />
+    ),
+  },
+  'A secondary `Button` rendered inside a cell. `variant: "secondary"` and `size: "S"` are typical for action columns.',
+);
+
+export const PrimaryVariant: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const colDefs = [
+  {
+    colId: 'action',
+    headerName: '',
+    cellRenderer: 'dsButtonCellRenderer',
+    valueGetter: (params) => ({
+      children: 'Enrol',
+      variant: 'primary',
+      size: 'S',
+      onClick: () => handleEnrol(params.data),
+    }),
+  },
+];
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <ButtonCellRenderer
+        {...MOCK_CELL_PROPS}
+        value={{ children: 'Enrol', variant: 'primary', size: 'S' }}
+      />
+    ),
+  },
+  '`variant: "primary"` — use sparingly and only when the action is the primary call-to-action for the row.',
+);
+
+export const DestructiveVariant: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <ButtonCellRenderer
+        {...MOCK_CELL_PROPS}
+        value={{ children: 'Remove', variant: 'primary-destructive', size: 'S' }}
+      />
+    ),
+  },
+  '`variant: "primary-destructive"` — for destructive actions like delete or remove.',
+);
+
+export const Disabled: Story = withDescription(
+  {
+    parameters: { controls: { disable: true } },
+    render: () => (
+      <ButtonCellRenderer
+        {...MOCK_CELL_PROPS}
+        value={{ children: 'View details', variant: 'secondary', size: 'S', disabled: true }}
+      />
+    ),
+  },
+  'Pass `disabled: true` in the `ButtonProps` value to conditionally disable the button for specific rows.',
+);
+
+const BUTTON_IN_TABLE_DATA = [
+  { id: 1, name: 'Alice Johnson', role: 'Developer' },
+  { id: 2, name: 'Bob Smith', role: 'Designer' },
+  { id: 3, name: 'Charlie Brown', role: 'Manager' },
+];
+
+export const InATable: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { Table } from '@arbor-education/design-system.components';
+
+const rowData = [
+  { id: 1, name: 'Alice Johnson', role: 'Developer' },
+  { id: 2, name: 'Bob Smith', role: 'Designer' },
+  { id: 3, name: 'Charlie Brown', role: 'Manager' },
+];
+
+function ButtonCellRendererExample() {
+  return (
+    <Table
+      rowData={rowData}
+      columnDefs={[
+        { field: 'name', headerName: 'Name', flex: 2 },
+        { field: 'role', headerName: 'Role', flex: 1 },
+        {
+          colId: 'viewAction',
+          headerName: '',
+          flex: 1,
+          maxWidth: 180,
+          editable: false,
+          cellRenderer: 'dsButtonCellRenderer',
+          valueGetter: (params) => ({
+            children: 'View details',
+            variant: 'secondary',
+            size: 'S',
+            onClick: () => console.log('View', params.data.name),
+          }),
+        },
+      ]}
+      defaultColDef={{ flex: 1, minWidth: 120 }}
+      domLayout="autoHeight"
+    />
+  );
+}
+
+export default ButtonCellRendererExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <Table
+        rowData={BUTTON_IN_TABLE_DATA}
+        columnDefs={[
+          { field: 'name', headerName: 'Name', flex: 2 },
+          { field: 'role', headerName: 'Role', flex: 1 },
+          {
+            colId: 'viewAction',
+            headerName: '',
+            flex: 1,
+            maxWidth: 180,
+            editable: false,
+            cellRenderer: 'dsButtonCellRenderer',
+            valueGetter: params => ({
+              children: 'View details',
+              variant: 'secondary',
+              size: 'S',
+              onClick: () => console.log('View', params.data.name),
+            }),
+          },
+        ]}
+        defaultColDef={{ flex: 1, minWidth: 120 }}
+        domLayout="autoHeight"
+      />
+    ),
+  },
+  '`dsButtonCellRenderer` wired up inside a full `Table`. The action column uses `valueGetter` to return a `ButtonProps` object per row — `onClick` closes over `params.data` so each button knows its row. Click a button and check the browser console.',
+);