@arbor-education/design-system.components 3.2.1 → 3.4.0

package/src/components/dataViewCard/DataViewCard.tsx

@@ -5,6 +5,7 @@ import { Card, getCardInteractionProps } from 'Components/card/Card';
 import { Heading } from 'Components/heading/Heading';
 import { Row } from 'Components/row/Row';
 import { Separator } from 'Components/separator/Separator';
+import { Tag } from 'Components/tag/Tag';
 
 export type DataViewCardRow = Row.Props;
 
@@ -14,12 +15,20 @@ type DataViewCardBaseProps = {
   avatar?: Avatar.Props;
   rows: DataViewCardRow[];
   disabled?: boolean;
+  tags?: { color: Tag.Color; label: string }[];
 };
 
 export type DataViewCardProps = DataViewCardBaseProps & Card.InteractionProps;
 
 export const DataViewCard = (props: DataViewCardProps): React.JSX.Element => {
-  const { className, header, avatar, rows, disabled = false } = props;
+  const {
+    className,
+    header,
+    avatar,
+    rows,
+    disabled = false,
+    tags,
+  } = props;
 
   return (
     <Card
@@ -50,6 +59,24 @@ export const DataViewCard = (props: DataViewCardProps): React.JSX.Element => {
               {index < rows.length - 1 && <Separator />}
             </Fragment>
           ))}
+          {tags && tags.length > 0 && (
+            <>
+              <Separator />
+              <span className="ds-data-view-card__tag-list">
+                {tags.map((tag) => {
+                  const { label, color } = tag;
+                  return (
+                    <Tag
+                      key={`dvc-${label}-${color}`}
+                      color={color}
+                    >
+                      {label}
+                    </Tag>
+                  );
+                })}
+              </span>
+            </>
+          )}
         </div>
       </article>
     </Card>

package/src/components/dataViewCard/dataViewCard.scss

@@ -23,3 +23,10 @@
   text-overflow: ellipsis;
   white-space: nowrap;
 }
+
+.ds-data-view-card__tag-list {
+  display: flex;
+  flex-direction: row;
+  justify-content: start;
+  gap: var(--spacing-xsmall);
+}

package/src/components/filterBar/FilterBar.stories.tsx

@@ -75,6 +75,12 @@ const DEVELOPER_NOTES = [
   'compose custom `FilterBar.Tag` children when you need bespoke markup. Avoid mixing both patterns in',
   'the same production instance.',
   '',
+  '**`label` is optional.** Omit it when the value alone is self-explanatory, such as a free-text',
+  'search term or a single unambiguous criterion. Without a `label`, the tag renders just the value',
+  '(no `Label:` prefix) and the generated `actionLabel` drops the label segment too, e.g. `Open filter',
+  'Interventions` instead of `Open filter Event Type: Interventions`. Most applied tags in a filter,',
+  'sort, or group list benefit from a label, so reach for this only when it would be redundant.',
+  '',
   '---',
   '',
   '### Accessibility',
@@ -106,7 +112,7 @@ const DEVELOPER_NOTES = [
   '| `FilterBar.ActiveListProps` | Applied-item summary props |',
   '| `FilterBar.TagProps` | Manually composed tag props |',
   '| `FilterBar.TagItem` | Data shape for `ActiveList.items` |',
-  '| `FilterBarType` | Union of `filter`, `sort`, and `group` |',
+  '| `FilterBarType` | Union of `filter`, `sort`, `group`, and `add` |',
 ].join('\n');
 
 const RELATED_COMPONENTS = [
@@ -134,7 +140,7 @@ const TOOLBAR_PROPS = [
 const BUTTON_PROPS = [
   '| Prop | Type | Default | Description |',
   '|---|---|---|---|',
-  '| `type` | `` `filter` \\| `sort` \\| `group` `` | — | **Required.** Chooses the default label, icon, and count announcement text |',
+  '| `type` | `` `filter` \\| `sort` \\| `group` \\| `add` `` | — | **Required.** Chooses the default label, icon, and count announcement text |',
   '| `label` | `string` | inferred from `type` | Override the visible button label |',
   '| `count` | `number \\| null` | — | Shows a badge when `> 0`. The badge caps visually at `99+`, but the accessible label keeps the full number |',
   '| `icon` | `IconName` | inferred from `type` | Override the default icon for that trigger type |',
@@ -163,8 +169,8 @@ const ACTIVE_LIST_PROPS = [
 const TAG_PROPS = [
   '| Prop | Type | Default | Description |',
   '|---|---|---|---|',
-  '| `type` | `` `filter` \\| `sort` \\| `group` `` | — | **Required.** Sets the default icon and action language |',
-  '| `label` | `string` | — | **Required.** Criterion label, e.g. `Year group` |',
+  '| `type` | `` `filter` \\| `sort` \\| `group` \\| `add` `` | — | **Required.** Sets the default icon and action language |',
+  '| `label` | `string` | — | Criterion label, e.g. `Year group`. Optional — omit it when the value alone is self-explanatory; the tag then renders just the value with no `Label:` prefix, and the generated `actionLabel` drops the label segment too |',
   '| `value` | `ReactNode` | — | **Required.** Current applied value, e.g. `Year 10` |',
   '| `id` | `string` | derived from `fieldId` or label | Stable identifier for list rendering and event payloads |',
   '| `fieldId` | `string` | — | Optional DOM id for the field that should receive focus after opening an editor |',
@@ -188,6 +194,7 @@ type FilterBarStoryArgs = FilterBar.Props & {
   filterCount: number;
   sortCount: number;
   groupCount: number;
+  addCount: number;
   wrap: boolean;
   collapseOverflow: boolean;
   overflowActionLabel: string;
@@ -229,6 +236,7 @@ const StoryShell = ({
 const onOpenFilter = fn();
 const onOpenSort = fn();
 const onOpenGroup = fn();
+const onOpenAdd = fn();
 const onOpenAppliedItem = fn();
 const onRemoveAppliedItem = fn();
 const onShowOverflow = fn();
@@ -337,12 +345,14 @@ const PANEL_FIELD_IDS: Record<FilterBar.Type, string> = {
   filter: 'attendance-filter-year-group',
   sort: 'attendance-sort-order',
   group: 'attendance-group-by',
+  add: 'attendance-add-criteria',
 };
 
 const PANEL_TITLES: Record<FilterBar.Type, string> = {
   filter: 'Filters',
   sort: 'Sorting',
   group: 'Grouping',
+  add: 'Add criteria',
 };
 
 // ---------------------------------------------------------------------------
@@ -455,6 +465,14 @@ const meta = {
         type: { summary: 'number' },
       },
     },
+    'addCount': {
+      control: { type: 'number', min: 0, max: 250 },
+      description: 'Applied add count shown on the Add trigger badge.',
+      table: {
+        category: 'FilterBar.Button',
+        type: { summary: 'number' },
+      },
+    },
     'wrap': {
       control: 'boolean',
       description: 'Allows the applied-item summary to wrap onto multiple lines.',
@@ -514,6 +532,7 @@ const DefaultTemplate = ({
   filterCount,
   sortCount,
   groupCount,
+  addCount,
   wrap,
   collapseOverflow,
   overflowActionLabel,
@@ -525,6 +544,7 @@ const DefaultTemplate = ({
         <FilterBar.Button type="filter" count={filterCount} onClick={onOpenFilter} />
         <FilterBar.Button type="sort" count={sortCount} onClick={onOpenSort} />
         <FilterBar.Button type="group" count={groupCount} onClick={onOpenGroup} />
+        <FilterBar.Button type="add" count={addCount} onClick={onOpenAdd} />
       </FilterBar.Toolbar>
       <FilterBar.ActiveList
         items={DEFAULT_ITEMS}
@@ -580,6 +600,7 @@ const ModalWiringTemplate = () => {
     filter: 0,
     sort: 0,
     group: 0,
+    add: 0,
   });
 
   const items: FilterBar.TagItem[] = APPLIED_ITEM_SEEDS.flatMap((item) => {
@@ -639,6 +660,14 @@ const ModalWiringTemplate = () => {
               aria-haspopup="dialog"
               onClick={() => openModal('group')}
             />
+            <FilterBar.Button
+              type="add"
+              count={counts.add}
+              aria-controls={modalId}
+              aria-expanded={open && activeType === 'add'}
+              aria-haspopup="dialog"
+              onClick={() => openModal('add')}
+            />
           </FilterBar.Toolbar>
           <FilterBar.ActiveList
             ariaLabel="Applied attendance filters, sorting, and grouping"
@@ -744,6 +773,7 @@ export const Default: Story = withDescription(
       'filterCount': 3,
       'sortCount': 1,
       'groupCount': 1,
+      'addCount': 0,
       'wrap': false,
       'collapseOverflow': true,
       'overflowActionLabel': 'Show more applied items',
@@ -783,6 +813,7 @@ function HighCountsExample() {
           <FilterBar.Button type="filter" count={142} onClick={() => {}} />
           <FilterBar.Button type="sort" count={103} onClick={() => {}} />
           <FilterBar.Button type="group" count={12} onClick={() => {}} />
+          <FilterBar.Button type="add" onClick={() => {}} />
         </FilterBar.Toolbar>
         <FilterBar.ActiveList items={items} ariaLabel="Applied attendance filters, sorting, and grouping" />
       </FilterBar>
@@ -801,6 +832,7 @@ export default HighCountsExample;
             <FilterBar.Button type="filter" count={142} onClick={onOpenFilter} />
             <FilterBar.Button type="sort" count={103} onClick={onOpenSort} />
             <FilterBar.Button type="group" count={12} onClick={onOpenGroup} />
+            <FilterBar.Button type="add" onClick={onOpenAdd} />
           </FilterBar.Toolbar>
           <FilterBar.ActiveList
             items={DEFAULT_ITEMS}
@@ -841,12 +873,14 @@ const panelFieldIds: Record<FilterBarType, string> = {
   filter: 'attendance-filter-year-group',
   sort: 'attendance-sort-order',
   group: 'attendance-group-by',
+  add: 'attendance-add-criteria',
 };
 
 const PANEL_TITLES: Record<FilterBarType, string> = {
   filter: 'Filters',
   sort: 'Sorting',
   group: 'Grouping',
+  add: 'Add criteria',
 };
 
 const seedItems: FilterBarTagItem[] = [
@@ -931,6 +965,7 @@ function FilterBarModalWiringExample() {
     filter: 0,
     sort: 0,
     group: 0,
+    add: 0,
   });
 
   const items = seedItems.flatMap((item) => {
@@ -985,6 +1020,14 @@ function FilterBarModalWiringExample() {
             aria-haspopup="dialog"
             onClick={() => openModal('group')}
           />
+          <FilterBar.Button
+            type="add"
+            count={counts.add}
+            aria-controls={modalId}
+            aria-expanded={open && activeType === 'add'}
+            aria-haspopup="dialog"
+            onClick={() => openModal('add')}
+          />
         </FilterBar.Toolbar>
 
         <FilterBar.ActiveList
@@ -1156,6 +1199,85 @@ export default OverflowExample;
   ].join(' '),
 );
 
+export const WithoutLabels: Story = withDescription(
+  {
+    parameters: {
+      controls: { disable: true },
+      docs: {
+        source: {
+          language: 'tsx',
+          code: `
+import { FilterBar, type FilterBarTagItem } from '@arbor-education/design-system.components';
+
+const items: FilterBarTagItem[] = [
+  { id: 'search-term', type: 'filter', value: 'Jordan Casey' },
+  { id: 'year-group', type: 'filter', label: 'Year group', value: 'Year 10' },
+  { id: 'attendance-band', type: 'filter', label: 'Attendance band', value: 'Below 90%' },
+];
+
+function WithoutLabelsExample() {
+  return (
+    <div style={{ width: '100%', maxWidth: 'min(100%, 72rem)', padding: 'var(--spacing-large)', boxSizing: 'border-box' }}>
+      <FilterBar aria-label="Attendance view controls">
+        <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+          <FilterBar.Button type="filter" count={3} onClick={() => {}} />
+        </FilterBar.Toolbar>
+        <FilterBar.ActiveList items={items} ariaLabel="Applied attendance filters" />
+      </FilterBar>
+    </div>
+  );
+}
+export default WithoutLabelsExample;
+`.trim(),
+        },
+      },
+    },
+    render: () => (
+      <StoryShell>
+        <FilterBar aria-label="Attendance view controls">
+          <FilterBar.Toolbar aria-label="Filter, sort, and group controls">
+            <FilterBar.Button type="filter" count={3} onClick={onOpenFilter} />
+          </FilterBar.Toolbar>
+          <FilterBar.ActiveList
+            items={[
+              {
+                id: 'search-term',
+                type: 'filter',
+                value: 'Jordan Casey',
+                onClick: onOpenAppliedItem,
+                onRemove: onRemoveAppliedItem,
+              },
+              {
+                id: 'year-group',
+                type: 'filter',
+                label: 'Year group',
+                value: 'Year 10',
+                onClick: onOpenAppliedItem,
+                onRemove: onRemoveAppliedItem,
+              },
+              {
+                id: 'attendance-band',
+                type: 'filter',
+                label: 'Attendance band',
+                value: 'Below 90%',
+                onClick: onOpenAppliedItem,
+                onRemove: onRemoveAppliedItem,
+              },
+            ]}
+            ariaLabel="Applied attendance filters"
+          />
+        </FilterBar>
+      </StoryShell>
+    ),
+  },
+  [
+    'Omit `label` when the value alone is self-explanatory, such as the free-text search term shown',
+    'first here. That tag renders as just `Jordan Casey` with a shorter generated action label',
+    '(`Open filter Jordan Casey` instead of `Open filter Search: Jordan Casey`), while the labelled',
+    'tags alongside it keep their `Label: Value` layout for comparison.',
+  ].join(' '),
+);
+
 export const Empty: Story = withDescription(
   {
     parameters: {

package/src/components/filterBar/FilterBar.test.tsx

@@ -171,6 +171,57 @@ describe('FilterBar', () => {
     }
   });
 
+  test('renders active list tags without a label and omits the label segment from the content and action label', async () => {
+    const user = userEvent.setup();
+    const onItemClick = vi.fn();
+
+    render(
+      <FilterBar>
+        <FilterBar.ActiveList
+          items={[
+            {
+              id: 'search',
+              type: 'filter',
+              value: 'Interventions',
+              onClick: onItemClick,
+            },
+          ]}
+        />
+      </FilterBar>,
+    );
+
+    const tagButton = screen.getByRole('button', { name: 'Open filter Interventions' });
+    expect(tagButton).toBeInTheDocument();
+    expect(screen.queryByText(':')).not.toBeInTheDocument();
+
+    await user.click(tagButton);
+
+    expect(onItemClick).toHaveBeenCalledOnce();
+    const [clickedItem] = onItemClick.mock.calls[0] ?? [];
+    expect(clickedItem).toMatchObject({ id: 'search', type: 'filter', value: 'Interventions' });
+    expect(clickedItem?.label).toBeUndefined();
+  });
+
+  test('renders a manually composed FilterBar.Tag without a label', async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+
+    render(
+      <FilterBar>
+        <FilterBar.ActiveList>
+          <FilterBar.Tag type="sort" value="Priority first" onClick={onClick} />
+        </FilterBar.ActiveList>
+      </FilterBar>,
+    );
+
+    const tagButton = screen.getByRole('button', { name: 'Open sort Priority first' });
+    expect(screen.getByText('Priority first')).toBeInTheDocument();
+    expect(screen.queryByText(':')).not.toBeInTheDocument();
+
+    await user.click(tagButton);
+    expect(onClick).toHaveBeenCalledOnce();
+  });
+
   test('returns focus to the first toolbar button after sequentially removing all tags from their remove buttons', async () => {
     const user = userEvent.setup();
 

package/src/components/filterBar/FilterBar.tsx

@@ -7,12 +7,12 @@ import { TagList } from 'Components/tagList/TagList';
 import classNames from 'classnames';
 import { Children, forwardRef, type ButtonHTMLAttributes, type HTMLAttributes, type MouseEventHandler, type RefObject } from 'react';
 
-export type FilterBarType = 'filter' | 'sort' | 'group';
+export type FilterBarType = 'filter' | 'sort' | 'group' | 'add';
 
 export type FilterBarTagItem = {
   id: string;
   type: FilterBarType;
-  label: string;
+  label?: string;
   value: React.ReactNode;
   fieldId?: string;
   icon?: IconName;
@@ -64,12 +64,14 @@ const FILTER_BAR_TYPE_LABELS: Record<FilterBarType, string> = {
   filter: 'Filter',
   sort: 'Sort',
   group: 'Group',
+  add: 'Add',
 };
 
 const FILTER_BAR_TYPE_ICONS: Record<FilterBarType, IconName> = {
   filter: 'sliders-horizontal',
   sort: 'sorting',
   group: 'list-tree',
+  add: 'circle-plus',
 };
 
 const getVisibleCount = (count?: number | null): string | null => {
@@ -87,17 +89,21 @@ const getButtonA11yLabel = (type: FilterBarType, label: string, count?: number |
   return `Open ${label.toLowerCase()}. ${count} ${type} item${count === 1 ? '' : 's'} applied`;
 };
 
-const getTagActionLabel = (item: FilterBarTagItem): string => `Open ${item.type} ${item.label}: ${item.value}`;
+const getTagActionLabel = (item: FilterBarTagItem): string => item.label ? `Open ${item.type} ${item.label}: ${item.value}` : `Open ${item.type} ${item.value}`;
 
-const FilterBarTagContent = ({ label, value }: Pick<FilterBarTagProps, 'label' | 'value'>) => (
-  <span className="ds-filter-bar__tag-content">
-    <span className="ds-filter-bar__tag-label">
-      {label}
-      :
+const FilterBarTagContent = ({ label, value }: Pick<FilterBarTagProps, 'label' | 'value'>) => {
+  return (
+    <span className="ds-filter-bar__tag-content">
+      {label && (
+        <span className="ds-filter-bar__tag-label">
+          {label}
+          :
+        </span>
+      )}
+      <span className="ds-filter-bar__tag-value">{value}</span>
     </span>
-    <span className="ds-filter-bar__tag-value">{value}</span>
-  </span>
-);
+  );
+};
 
 export const FilterBar = ({
   children,
@@ -193,7 +199,7 @@ const FilterBarTag = ({
   onRemove,
 }: FilterBarTagProps): React.JSX.Element => {
   const item: FilterBarTagItem = {
-    id: id ?? fieldId ?? `${type}-${label}`,
+    id: id ?? fieldId ?? `${type}-${label}-${value}`,
     type,
     label,
     value,

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

@@ -11,6 +11,7 @@ import {
 } from '@storybook/addon-docs/blocks';
 import { type Column, type ColDef, type ColGroupDef } from 'ag-grid-enterprise';
 import { Table } from './Table.js';
+import { TABLE_SPACING } from './tableConsts.js';
 import { Button } from 'Components/button/Button';
 import { Icon } from 'Components/icon/Icon';
 
@@ -348,6 +349,14 @@ const meta: Meta<TableProps> = {
         defaultValue: { summary: 'false' },
       },
     },
+    initialSettings: {
+      description: 'Seeds the table settings (column borders, spacing, cell colours) on mount, e.g. to restore a user\'s previously persisted preferences. Only affects the initial render — `resetSettings` still falls back to the DS defaults, not these values.',
+      control: false,
+      table: {
+        type: { summary: 'Partial<TableSettings>' },
+        defaultValue: { summary: 'undefined' },
+      },
+    },
     onTableSettingsChanged: {
       description: 'Fired when the user changes table settings (column borders, spacing, cell colours) via the settings dropdown.',
       control: false,
@@ -2212,6 +2221,54 @@ export const WithTableSettingsDropdownCustomItems: Story = {
   },
 };
 
+type WithInitialSettingsArgs = TableProps & {
+  hasColumnBorders?: boolean;
+  tableSpacing?: TABLE_SPACING;
+  areCellColorsEnabled?: boolean;
+};
+
+export const WithInitialSettings: StoryObj<WithInitialSettingsArgs> = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          '`initialSettings` seeds column borders, spacing and cell colours on mount — useful for restoring a user\'s previously persisted preferences without a flash of the DS defaults. Resetting via the settings dropdown still falls back to the DS defaults, not these values. Use the Controls panel below to try different combinations.',
+      },
+    },
+  },
+  argTypes: {
+    hasColumnBorders: {
+      description: 'Seeds `initialSettings.hasColumnBorders`.',
+      control: 'boolean',
+    },
+    tableSpacing: {
+      description: 'Seeds `initialSettings.tableSpacing`.',
+      control: 'select',
+      options: Object.values(TABLE_SPACING),
+    },
+    areCellColorsEnabled: {
+      description: 'Seeds `initialSettings.areCellColorsEnabled`.',
+      control: 'boolean',
+    },
+  },
+  args: {
+    rowData: sampleData,
+    columnDefs: sampleColumnDefs,
+    defaultColDef,
+    domLayout: 'autoHeight',
+    headerContent: <Table.TableSettingsDropdown />,
+    hasColumnBorders: true,
+    tableSpacing: Table.Spacing.L,
+    areCellColorsEnabled: false,
+  },
+  render: ({ hasColumnBorders, tableSpacing, areCellColorsEnabled, ...rest }) => (
+    <Table
+      {...rest}
+      initialSettings={{ hasColumnBorders, tableSpacing, areCellColorsEnabled }}
+    />
+  ),
+};
+
 export const WithCheckboxCellRenderer: Story = {
   parameters: {
     docs: {

package/src/components/table/Table.test.tsx

@@ -894,6 +894,48 @@ describe('Table', () => {
       expect(onTableSettingsChanged).toHaveBeenNthCalledWith(2, expect.objectContaining({ hasColumnBorders: true }));
     });
 
+    test('renders with initialSettings applied instead of the hardcoded defaults', async () => {
+      render(
+        <Table
+          headerContent={<TableSettingsDropdown />}
+          initialSettings={{
+            hasColumnBorders: true,
+            tableSpacing: Table.Spacing.L,
+            areCellColorsEnabled: false,
+          }}
+        />,
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: /Table settings/i }));
+
+      expect((screen.getByLabelText('Large') as HTMLInputElement).checked).toBe(true);
+      expect((screen.getByLabelText('Column borders') as HTMLInputElement).checked).toBe(true);
+      expect((screen.getByLabelText('Cell colours') as HTMLInputElement).checked).toBe(false);
+    });
+
+    test('resetSettings falls back to the DS defaults, not initialSettings', async () => {
+      const onTableSettingsReset = vi.fn();
+
+      render(
+        <Table
+          headerContent={<TableSettingsDropdown />}
+          initialSettings={{ hasColumnBorders: true, tableSpacing: Table.Spacing.L }}
+          onTableSettingsReset={onTableSettingsReset}
+        />,
+      );
+
+      await userEvent.click(screen.getByRole('button', { name: /Table settings/i }));
+
+      const resetButton = screen.getByRole('button', { name: /Reset Table Settings/i });
+      await userEvent.click(resetButton);
+
+      expect(onTableSettingsReset).toHaveBeenCalledOnce();
+      await waitFor(() => {
+        expect((screen.getByLabelText('Medium') as HTMLInputElement).checked).toBe(true);
+        expect((screen.getByLabelText('Column borders') as HTMLInputElement).checked).toBe(false);
+      });
+    });
+
     test('resetSettings is called appropriately', async () => {
       const onTableSettingsReset = vi.fn();
 

package/src/components/table/Table.tsx

@@ -69,6 +69,7 @@ export const Table = (props: TableProps) => {
     footerContent,
     footerTestId,
     onGridReady,
+    initialSettings,
     onTableSettingsChanged,
     onTableSettingsReset,
     onColumnBordersChanged,
@@ -100,6 +101,7 @@ export const Table = (props: TableProps) => {
     setTableSpacing,
     setAreCellColorsEnabled,
   } = useTableSettings({
+    initialSettings,
     onTableSettingsChanged,
     onTableSettingsReset,
     onColumnBordersChanged,

package/src/components/table/tableControls/TableControls.stories.tsx

@@ -51,7 +51,9 @@ const USAGE_GUIDANCE = [
   '|---|---|---|',
   '| `bulkActions` | Start | Array of `{ displayName, callback, disabled? }` — shown as a dropdown when rows are selected |',
   '| `onUndo` | Start | Renders an undo icon button |',
+  '| `isUndoDisabled` | Start | Disables the undo button (e.g. when there is nothing to undo) |',
   '| `onRedo` | Start | Renders a redo icon button |',
+  '| `isRedoDisabled` | Start | Disables the redo button (e.g. when there is nothing to redo) |',
   '| `showHideColumns` | Start | Renders the `HideColumnsDropdown` |',
   '| `hasSearch` | End | Renders the `SearchBar` |',
   '| `onDownload` | End | Renders a download icon button |',
@@ -79,6 +81,7 @@ const DEVELOPER_NOTES = [
   '            { displayName: "Delete selected", callback: api => deleteRows(api) },',
   '          ]}',
   '          onUndo={handleUndo}',
+  '          isUndoDisabled={!canUndo}',
   '          showHideColumns',
   '          onDownload={handleDownload}',
   '          showSettings',
@@ -195,11 +198,21 @@ const meta = {
       control: false,
       table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
     },
+    isUndoDisabled: {
+      description: 'When `true`, disables the undo button (e.g. when there is nothing to undo). Has no effect if `onUndo` is not provided.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
     onRedo: {
       description: 'Renders a redo icon button in the start group. Called with no arguments on click.',
       control: false,
       table: { type: { summary: '() => void' }, defaultValue: { summary: 'undefined' } },
     },
+    isRedoDisabled: {
+      description: 'When `true`, disables the redo button (e.g. when there is nothing to redo). Has no effect if `onRedo` is not provided.',
+      control: 'boolean',
+      table: { type: { summary: 'boolean' }, defaultValue: { summary: 'false' } },
+    },
     showHideColumns: {
       description: 'When `true`, renders the `HideColumnsDropdown` in the start group. Reads column visibility from `GridApiContext` (provided by `<Table />`). Pass `hideColumnsProps` for manual column control.',
       control: 'boolean',
@@ -299,6 +312,21 @@ export const StartGroupOnly: Story = withDescription(
   + 'see the **Within a Table** story for a fully wired example.',
 );
 
+export const UndoRedoDisabled: Story = withDescription(
+  {
+    args: {
+      onUndo: fn(),
+      isUndoDisabled: true,
+      onRedo: fn(),
+      isRedoDisabled: true,
+    },
+  },
+  'Undo and redo rendered with `isUndoDisabled` / `isRedoDisabled` set — use these when there is '
+  + 'nothing left to undo or redo, so the buttons stay visible but communicate they are unavailable '
+  + 'instead of silently no-opping when clicked. Toggle `isUndoDisabled` / `isRedoDisabled` off in the '
+  + 'Controls panel to compare against the enabled state.',
+);
+
 export const EndGroupOnly: Story = withDescription(
   {
     parameters: { controls: { disable: true } },