@astryxdesign/core 0.1.4 → 0.1.5-canary.76e6697

package/src/Table/plugins/groupedRows/useTableGroupedRows.test.tsx

@@ -0,0 +1,231 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {describe, it, expect} from 'vitest';
+import {render, screen, fireEvent, within} from '@testing-library/react';
+import {useState, useCallback} from 'react';
+import {Table} from '../../Table';
+import type {TableColumn} from '../../types';
+import {useTableGroupedRows} from './useTableGroupedRows';
+
+interface Person extends Record<string, unknown> {
+  id: string;
+  name: string;
+  team: string;
+}
+
+const people: Person[] = [
+  {id: 'a', name: 'Alice', team: 'Core'},
+  {id: 'b', name: 'Bob', team: 'Core'},
+  {id: 'c', name: 'Carol', team: 'Infra'},
+];
+
+const columns: TableColumn<Person>[] = [{key: 'name', header: 'Name'}];
+
+const EMPTY = new Set<string>();
+
+function Harness({
+  rows = people,
+  initialCollapsed = EMPTY,
+  renderGroupHeader,
+}: {
+  rows?: Person[];
+  initialCollapsed?: Set<string>;
+  renderGroupHeader?: (
+    groupKey: string,
+    count: number,
+    collapsed: boolean,
+  ) => React.ReactNode;
+}) {
+  const [collapsedGroups, setCollapsed] = useState(initialCollapsed);
+  const onToggleGroup = useCallback((key: string) => {
+    setCollapsed(prev => {
+      const next = new Set(prev);
+      if (next.has(key)) {
+        next.delete(key);
+      } else {
+        next.add(key);
+      }
+      return next;
+    });
+  }, []);
+  const grouped = useTableGroupedRows<Person>({
+    data: rows,
+    groupBy: p => p.team,
+    collapsedGroups,
+    onToggleGroup,
+    getRowKey: p => p.id,
+    renderGroupHeader,
+  });
+  return (
+    <Table
+      data={grouped.data}
+      columns={columns}
+      idKey={grouped.idKey}
+      plugins={{grouped: grouped.plugin}}
+    />
+  );
+}
+
+describe('useTableGroupedRows', () => {
+  it('renders a header row per group with label and count', () => {
+    render(<Harness />);
+    // Two groups: Core (2), Infra (1).
+    expect(screen.getByText('Core')).toBeInTheDocument();
+    expect(screen.getByText('(2)')).toBeInTheDocument();
+    expect(screen.getByText('Infra')).toBeInTheDocument();
+    expect(screen.getByText('(1)')).toBeInTheDocument();
+  });
+
+  it('shows group members when expanded', () => {
+    render(<Harness />);
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+    expect(screen.getByText('Carol')).toBeInTheDocument();
+  });
+
+  it('hides members of a collapsed group but keeps the header', () => {
+    render(<Harness initialCollapsed={new Set(['Core'])} />);
+    expect(screen.getByText('Core')).toBeInTheDocument();
+    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
+    expect(screen.queryByText('Bob')).not.toBeInTheDocument();
+    // Other group unaffected.
+    expect(screen.getByText('Carol')).toBeInTheDocument();
+  });
+
+  it('toggles a group via its chevron and back again', () => {
+    render(<Harness />);
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+    // The standalone chevron button toggles the group; its accessible name is
+    // qualified with the group key.
+    fireEvent.click(screen.getByRole('button', {name: 'Collapse group Core'}));
+    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
+    expect(screen.queryByText('Bob')).not.toBeInTheDocument();
+    expect(screen.getByText('Core')).toBeInTheDocument();
+    expect(screen.getByText('Carol')).toBeInTheDocument();
+    // Toggle back: the Core chevron now says "Expand group Core".
+    fireEvent.click(screen.getByRole('button', {name: 'Expand group Core'}));
+    expect(screen.getByText('Alice')).toBeInTheDocument();
+    expect(screen.getByText('Bob')).toBeInTheDocument();
+  });
+
+  it('exposes each group toggle as a named, keyboard-operable button', () => {
+    render(<Harness />);
+    // Native <button>: focusable and operable without a custom key handler.
+    const coreToggle = screen.getByRole('button', {
+      name: 'Collapse group Core',
+    });
+    expect(coreToggle.tagName).toBe('BUTTON');
+    expect(coreToggle).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('sets aria-expanded on the header row reflecting collapse state', () => {
+    render(<Harness initialCollapsed={new Set(['Core'])} />);
+    const rows = screen.getAllByRole('row');
+    // rows[1] = Core header (collapsed), rows[2] = Infra header (expanded).
+    expect(rows[1]).toHaveAttribute('aria-expanded', 'false');
+    expect(rows[2]).toHaveAttribute('aria-expanded', 'true');
+  });
+
+  it('respects groupOrder in the flattened data', () => {
+    function OrderedHarness() {
+      const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+      const grouped = useTableGroupedRows<Person>({
+        data: people,
+        groupBy: p => p.team,
+        collapsedGroups: collapsed,
+        onToggleGroup: k => setCollapsed(new Set([k])),
+        getRowKey: p => p.id,
+        groupOrder: ['Infra', 'Core'],
+      });
+      expect(grouped.data.length).toBeGreaterThan(0);
+      return (
+        <Table
+          data={grouped.data}
+          columns={columns}
+          idKey={grouped.idKey}
+          plugins={{grouped: grouped.plugin}}
+        />
+      );
+    }
+    render(<OrderedHarness />);
+    const rows = screen.getAllByRole('row');
+    // rows[0] = column header; rows[1] = first group header (Infra).
+    expect(within(rows[1]).getByText('Infra')).toBeInTheDocument();
+  });
+
+  it('renders custom group header content via renderGroupHeader', () => {
+    render(
+      <Harness
+        renderGroupHeader={(key, count, collapsed) => (
+          <span>{`${key}::${count}::${collapsed ? 'closed' : 'open'}`}</span>
+        )}
+      />,
+    );
+    expect(screen.getByText('Core::2::open')).toBeInTheDocument();
+    expect(screen.getByText('Infra::1::open')).toBeInTheDocument();
+  });
+
+  it('renders nothing (no group headers) for empty data', () => {
+    render(<Harness rows={[]} />);
+    // Column header row still renders; no group header rows.
+    expect(screen.queryByText('Core')).not.toBeInTheDocument();
+    expect(screen.queryByText('Infra')).not.toBeInTheDocument();
+    expect(
+      screen.queryByRole('button', {name: /group/i}),
+    ).not.toBeInTheDocument();
+  });
+
+  it('keeps a group collapsed across a data change (state keyed by group)', () => {
+    function ChangingHarness() {
+      const [collapsed, setCollapsed] = useState<Set<string>>(
+        new Set(['Core']),
+      );
+      const [rows, setRows] = useState(people);
+      const onToggleGroup = useCallback((key: string) => {
+        setCollapsed(prev => {
+          const next = new Set(prev);
+          if (next.has(key)) {
+            next.delete(key);
+          } else {
+            next.add(key);
+          }
+          return next;
+        });
+      }, []);
+      const grouped = useTableGroupedRows<Person>({
+        data: rows,
+        groupBy: p => p.team,
+        collapsedGroups: collapsed,
+        onToggleGroup,
+        getRowKey: p => p.id,
+      });
+      return (
+        <>
+          <button
+            type="button"
+            onClick={() =>
+              setRows([...people, {id: 'd', name: 'Dave', team: 'Core'}])
+            }>
+            add
+          </button>
+          <Table
+            data={grouped.data}
+            columns={columns}
+            idKey={grouped.idKey}
+            plugins={{grouped: grouped.plugin}}
+          />
+        </>
+      );
+    }
+    render(<ChangingHarness />);
+    // Core collapsed initially: Alice hidden.
+    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
+    // Add a new Core member; Core must stay collapsed (keyed by group value).
+    fireEvent.click(screen.getByText('add'));
+    expect(screen.queryByText('Alice')).not.toBeInTheDocument();
+    expect(screen.queryByText('Dave')).not.toBeInTheDocument();
+    // Count reflects the new member (3), header still present.
+    expect(screen.getByText('Core')).toBeInTheDocument();
+    expect(screen.getByText('(3)')).toBeInTheDocument();
+  });
+});

package/src/Table/plugins/groupedRows/useTableGroupedRows.tsx

@@ -0,0 +1,349 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file useTableGroupedRows.tsx
+ * @input React, StyleX, Icon, Table types + the flat data array
+ * @output Exports useTableGroupedRows hook + config/result types
+ * @position Grouped-rows plugin; consumed by Table via plugins prop
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Table/index.ts (exports)
+ */
+
+import {useCallback, useMemo, type ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import {
+  spacingVars,
+  colorVars,
+  fontWeightVars,
+} from '../../../theme/tokens.stylex';
+import {Icon} from '../../../Icon';
+import type {TablePlugin} from '../../types';
+
+// A synthetic group-header row injected into the flattened data. Real rows
+// never carry this marker.
+const GROUP_HEADER = Symbol('tableGroupHeader');
+
+interface GroupHeader {
+  [GROUP_HEADER]: true;
+  groupKey: string;
+  count: number;
+}
+
+function isGroupHeader(item: unknown): item is GroupHeader {
+  return (
+    typeof item === 'object' &&
+    item !== null &&
+    (item as Record<symbol, unknown>)[GROUP_HEADER] === true
+  );
+}
+
+// Proxy handler: any field access beyond the marker fields resolves to `''`
+// so user cell renderers (`item.name.toUpperCase()`) never throw on a header.
+const HEADER_PROXY_HANDLER: ProxyHandler<Record<string | symbol, unknown>> = {
+  // eslint-disable-next-line @typescript-eslint/promise-function-async -- Proxy get trap, not a promise-returning fn
+  get(t: Record<string | symbol, unknown>, prop: string | symbol): unknown {
+    if (prop === GROUP_HEADER || prop === 'groupKey' || prop === 'count') {
+      return t[prop];
+    }
+    return prop in t ? t[prop] : '';
+  },
+};
+
+/**
+ * Build a synthetic header row wrapped in a Proxy so arbitrary field access
+ * from user cell renderers (e.g. `item.name.toUpperCase()`) resolves to `''`
+ * instead of throwing — BaseTable evaluates `col.renderCell(item)` on every
+ * row (including synthetic headers) before `transformBodyRow` can replace the
+ * row's cells. `transformBodyRow` then discards those cells and renders a
+ * single full-width header cell.
+ */
+function makeHeader<T extends Record<string, unknown>>(
+  groupKey: string,
+  count: number,
+): T {
+  const target: Record<string | symbol, unknown> = {
+    [GROUP_HEADER]: true,
+    groupKey,
+    count,
+  };
+  return new Proxy(target, HEADER_PROXY_HANDLER) as unknown as T;
+}
+
+/** Configuration for {@link useTableGroupedRows}. */
+export interface UseTableGroupedRowsConfig<T extends Record<string, unknown>> {
+  /** The flat data to group. */
+  data: T[];
+  /** Derive the group key for a row. Rows with the same key share a section. */
+  groupBy: (item: T) => string;
+  /** Set of currently-collapsed group keys. */
+  collapsedGroups: Set<string>;
+  /** Called with a group key when its header is toggled. */
+  onToggleGroup: (groupKey: string) => void;
+  /**
+   * Custom renderer for a group header's content (right of the chevron).
+   * Defaults to `<groupKey> (<count>)`.
+   */
+  renderGroupHeader?: (
+    groupKey: string,
+    count: number,
+    collapsed: boolean,
+  ) => ReactNode;
+  /** Stable key for a real row. Falls back to a positional key when omitted. */
+  getRowKey?: (item: T) => string;
+  /** Explicit group ordering; groups not listed keep first-seen order after these. */
+  groupOrder?: string[];
+}
+
+export interface UseTableGroupedRowsResult<T extends Record<string, unknown>> {
+  /** Ready-to-use plugin for `<Table plugins>`. */
+  plugin: TablePlugin<T>;
+  /** Flattened rows: `[header, ...visibleRows, header, ...visibleRows]`. */
+  data: T[];
+  /**
+   * Row-key resolver (also keys synthetic headers as `__group_<key>`). Pass to
+   * `<Table idKey>` — named for parallelism with the Table prop:
+   * `<Table idKey={grouped.idKey} />`.
+   */
+  idKey: (item: T) => string;
+}
+
+const styles = stylex.create({
+  headerRow: {
+    cursor: 'pointer',
+    userSelect: 'none',
+    backgroundColor: colorVars['--color-background-muted'],
+    // Divider beneath each group header row (Ernest review #2).
+    borderBottomWidth: '1px',
+    borderBottomStyle: 'solid',
+    borderBottomColor: colorVars['--color-border'],
+  },
+  headerCell: {
+    paddingBlock: spacingVars['--spacing-2'],
+    // No inline start padding so the chevron aligns with the table's leading
+    // edge (Ernest review #1).
+    paddingInlineStart: spacingVars['--spacing-1'],
+    paddingInlineEnd: spacingVars['--spacing-3'],
+  },
+  headerInner: {
+    display: 'flex',
+    alignItems: 'center',
+    gap: spacingVars['--spacing-1'],
+  },
+  // Standalone chevron button with no heavy chrome (transparent, borderless,
+  // zero padding) so the icon sits flush with the start of the table
+  // (Ernest review #1) while staying keyboard-operable.
+  chevron: {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    flexShrink: '0',
+    padding: 0,
+    margin: 0,
+    background: 'transparent',
+    border: 'none',
+    cursor: 'pointer',
+    color: {
+      default: colorVars['--color-icon-secondary'],
+      ':hover': colorVars['--color-icon-primary'],
+    },
+  },
+  chevronIcon: {
+    display: 'inline-flex',
+    transitionProperty: 'transform',
+    transitionDuration: '150ms',
+  },
+  chevronExpanded: {
+    transform: 'rotate(90deg)',
+  },
+  // Emphasized body text — same size as body, heavier weight (Ernest #3).
+  label: {
+    fontWeight: fontWeightVars['--font-weight-semibold'],
+    color: colorVars['--color-text-primary'],
+  },
+  count: {
+    fontWeight: fontWeightVars['--font-weight-normal'],
+    color: colorVars['--color-text-secondary'],
+  },
+});
+
+/**
+ * Groups a flat data array into collapsible section rows. Each distinct
+ * `groupBy` value becomes a full-width section-header row with a chevron
+ * toggle, the group label, and a member count; collapsing hides that group's
+ * data rows while keeping the header visible.
+ *
+ * Mirrors {@link useTableRowExpansionState}: the consumer owns the
+ * `collapsedGroups` set and this hook returns `{data, plugin, idKey}` —
+ * pass all three to `<Table>`.
+ *
+ * @example
+ * ```tsx
+ * const [collapsed, setCollapsed] = useState<Set<string>>(new Set());
+ * const grouped = useTableGroupedRows({
+ *   data: rows,
+ *   groupBy: r => r.team,
+ *   collapsedGroups: collapsed,
+ *   onToggleGroup: key =>
+ *     setCollapsed(prev => {
+ *       const next = new Set(prev);
+ *       next.has(key) ? next.delete(key) : next.add(key);
+ *       return next;
+ *     }),
+ *   getRowKey: r => r.id,
+ * });
+ * <Table
+ *   data={grouped.data}
+ *   columns={columns}
+ *   idKey={grouped.idKey}
+ *   plugins={{grouped: grouped.plugin}}
+ * />;
+ * ```
+ */
+export function useTableGroupedRows<T extends Record<string, unknown>>(
+  config: UseTableGroupedRowsConfig<T>,
+): UseTableGroupedRowsResult<T> {
+  const {
+    data,
+    groupBy,
+    collapsedGroups,
+    onToggleGroup,
+    renderGroupHeader,
+    getRowKey: getRowKeyProp,
+    groupOrder,
+  } = config;
+
+  const flattened = useMemo((): T[] => {
+    if (data.length === 0) {
+      return [];
+    }
+
+    // Group preserving first-seen order.
+    const groups = new Map<string, T[]>();
+    for (const item of data) {
+      const key = groupBy(item);
+      const bucket = groups.get(key);
+      if (bucket) {
+        bucket.push(item);
+      } else {
+        groups.set(key, [item]);
+      }
+    }
+
+    // Determine iteration order.
+    let keys = [...groups.keys()];
+    if (groupOrder && groupOrder.length > 0) {
+      const ordered = groupOrder.filter(k => groups.has(k));
+      const rest = keys.filter(k => !groupOrder.includes(k));
+      keys = [...ordered, ...rest];
+    }
+
+    const out: T[] = [];
+    for (const key of keys) {
+      const rows = groups.get(key) ?? [];
+      out.push(makeHeader<T>(key, rows.length));
+      if (!collapsedGroups.has(key)) {
+        out.push(...rows);
+      }
+    }
+    return out;
+  }, [data, groupBy, collapsedGroups, groupOrder]);
+
+  // Positional fallback index, built once per flattened array so key lookup
+  // stays O(1) instead of O(n) per row (which would make table keying O(n²)).
+  const positionByItem = useMemo(() => {
+    if (getRowKeyProp) {
+      return null;
+    }
+    const map = new Map<T, number>();
+    for (let i = 0; i < flattened.length; i++) {
+      map.set(flattened[i], i);
+    }
+    return map;
+  }, [flattened, getRowKeyProp]);
+
+  const idKey = useCallback(
+    (item: T): string => {
+      if (isGroupHeader(item)) {
+        return `__group_${item.groupKey}`;
+      }
+      if (getRowKeyProp) {
+        return getRowKeyProp(item);
+      }
+      return String(positionByItem?.get(item) ?? -1);
+    },
+    [getRowKeyProp, positionByItem],
+  );
+
+  const plugin = useMemo(
+    (): TablePlugin<T> => ({
+      // Replace a header row's pre-rendered cells with one full-width cell.
+      transformBodyRow(props, item) {
+        if (!isGroupHeader(item)) {
+          return props;
+        }
+        const header = item as unknown as GroupHeader;
+        const collapsed = collapsedGroups.has(header.groupKey);
+        const toggle = () => onToggleGroup(header.groupKey);
+        const content: ReactNode = renderGroupHeader ? (
+          renderGroupHeader(header.groupKey, header.count, collapsed)
+        ) : (
+          <span {...stylex.props(styles.label)}>
+            {header.groupKey}{' '}
+            <span {...stylex.props(styles.count)}>({header.count})</span>
+          </span>
+        );
+        return {
+          ...props,
+          htmlProps: {
+            ...props.htmlProps,
+            // Convenience: clicking anywhere on the row toggles it. The chevron
+            // button below is the accessible, keyboard-operable control, so the
+            // row keeps its implicit `row` role (no role override here).
+            onClick: toggle,
+            'aria-expanded': !collapsed,
+          },
+          styles: [...props.styles, styles.headerRow],
+          children: (
+            // colSpan larger than the column count is clamped by the browser
+            // to the actual number of columns, so the header always spans the
+            // full width without the plugin knowing the column count.
+            <td colSpan={999} {...stylex.props(styles.headerCell)}>
+              <span {...stylex.props(styles.headerInner)}>
+                {/* Standalone chevron button, flush with the table's start
+                    edge (no heavy button chrome) — the keyboard control. */}
+                <button
+                  type="button"
+                  {...stylex.props(styles.chevron)}
+                  onClick={e => {
+                    e.stopPropagation();
+                    toggle();
+                  }}
+                  aria-label={
+                    collapsed
+                      ? `Expand group ${header.groupKey}`
+                      : `Collapse group ${header.groupKey}`
+                  }
+                  aria-expanded={!collapsed}>
+                  <span
+                    {...stylex.props(
+                      styles.chevronIcon,
+                      !collapsed && styles.chevronExpanded,
+                    )}>
+                    <Icon icon="chevronRight" size="xsm" />
+                  </span>
+                </button>
+                {content}
+              </span>
+            </td>
+          ),
+        };
+      },
+    }),
+    [collapsedGroups, onToggleGroup, renderGroupHeader],
+  );
+
+  return {plugin, data: flattened, idKey};
+}

package/src/Table/plugins/pagination/paginateData.ts

@@ -38,6 +38,10 @@ export function paginateData<T>(
   const size = Number.isFinite(pageSize)
     ? Math.max(1, Math.floor(pageSize))
     : 10;
-  const start = (page - 1) * size;
+  // page needs the same coercion: a negative start index makes Array.slice
+  // count from the END of the data (page -1 returns the tail dressed up as a
+  // page), and a fractional page returns a slice straddling two pages.
+  const p = Number.isFinite(page) ? Math.max(1, Math.floor(page)) : 1;
+  const start = (p - 1) * size;
   return data.slice(start, start + size);
 }

package/src/Table/plugins/pagination/useTablePagination.test.tsx

@@ -132,6 +132,19 @@ describe('paginateData', () => {
     expect(paginateData([], 1, 10)).toEqual([]);
   });
 
+  it('clamps invalid page numbers to the first page (#3593)', () => {
+    const data = generateItems(30);
+    // Negative pages previously fed a negative index to Array.slice, which
+    // counts from the END of the data — the tail dressed up as a page.
+    expect(paginateData(data, -1, 10)[0].id).toBe('1');
+    expect(paginateData(data, 0, 10)[0].id).toBe('1');
+    expect(paginateData(data, NaN, 10)[0].id).toBe('1');
+    // Fractional pages floor to the containing page instead of straddling two.
+    expect(paginateData(data, 1.5, 10).map(i => i.id)).toEqual(
+      paginateData(data, 1, 10).map(i => i.id),
+    );
+  });
+
   it('returns empty array when page exceeds data', () => {
     const data = generateItems(10);
     expect(paginateData(data, 5, 10)).toEqual([]);

package/src/Table/plugins/rowExpansion/useTableRowExpansion.tsx

@@ -109,7 +109,7 @@ export interface UseTableRowExpansionStateResult<
  * computing the expand-all state.
  *
  * @example
- * ```tsx
+ * ```
  * const [expandedKeys, setExpandedKeys] = useState<Set<string>>(new Set());
  * const {data, expansionConfig} = useTableRowExpansionState({
  *   baseData: tree,

package/src/Table/plugins/selection/useTableSelectionState.test.tsx

@@ -302,6 +302,29 @@ describe('useTableSelectionState with filtered data', () => {
     expect(screen.getByTestId('selected-keys')).toHaveTextContent('1,3');
   });
 
+  it('select-all is unchecked when the filter matches nothing (#3591)', async () => {
+    const user = userEvent.setup();
+    render(<FilteredSelectionTable />);
+
+    // Select Bob, then filter to an empty result set.
+    const checkboxes = screen.getAllByLabelText('Select row');
+    await user.click(checkboxes[1]);
+    expect(screen.getByTestId('selected-keys')).toHaveTextContent('2');
+
+    const input = screen.getByTestId('filter-input');
+    await user.clear(input);
+    await user.type(input, 'zzz');
+
+    // Zero visible rows must not read as "all selected" — previously the
+    // header checkbox rendered checked here and deselect-all was a no-op.
+    const selectAll = screen.getByLabelText('Select all rows');
+    expect(selectAll).not.toBeChecked();
+
+    // The hidden selection itself is preserved (frozen), as designed.
+    await user.clear(input);
+    expect(screen.getByTestId('selected-keys')).toHaveTextContent('2');
+  });
+
   it('selections persist when filter changes', async () => {
     const user = userEvent.setup();
     render(<FilteredSelectionTable />);

package/src/Table/plugins/selection/useTableSelectionState.tsx

@@ -125,12 +125,17 @@ export function useTableSelectionState<T extends Record<string, unknown>>(
     [selectedKeys, selectableIDs],
   );
 
-  const getAllSelected = useCallback(
-    () =>
-      allSelectableIDs.size === selectedKeys.size &&
-      allSelectableIDs.size !== 0,
-    [allSelectableIDs, selectedKeys],
-  );
+  const getAllSelected = useCallback(() => {
+    // Require at least one actionable row: with zero visible selectable
+    // rows (e.g. a filter with no matches while a selection exists), the
+    // union-based size comparison would read any non-empty selection as
+    // "all selected" — a checked header checkbox over an empty table that
+    // deselect-all can't clear, since the invisible keys count as frozen.
+    if (selectableIDs.size === 0) {
+      return false;
+    }
+    return allSelectableIDs.size === selectedKeys.size;
+  }, [allSelectableIDs, selectableIDs, selectedKeys]);
 
   // Use refs to keep onSelectAll stable
   const frozenSelectedIDsRef = useRef(frozenSelectedIDs);