@eifi1/ui-kit 0.51.6 → 0.52.0

package/src/components/data-table.tsx

@@ -8,6 +8,7 @@ import { useRangeSelection } from "./data-table-selection";
 import { columnLabel, logicalAlign, resolveDataTableLabels } from "./data-table-shared";
 import {
   MobileFilters,
+  MobileLeadingRow,
   MobileSelectBar,
   MobileSort,
   StackedFields,
@@ -41,8 +42,9 @@ import { ColumnSettingsPanel } from "./data-table-column-settings";
 import { useLargeText } from "../hooks/use-large-text";
 import { cn } from "../lib/cn";
 import { isFilterActive, resolveFilter, rowMatches } from "./data-table-filters";
+import { matchesSearch, searchWords } from "../lib/text-match";
 import type { ColumnFilter, FilterValue } from "./data-table-filters";
-import { nextSorts } from "./data-table-sort";
+import { compareSortValues, nextSorts } from "./data-table-sort";
 import type { SortCycle, SortDir, SortState } from "./data-table-sort";
 import { Pagination } from "./data-table-pagination";
 import type { SwipeAction } from "./swipeable-row";
@@ -60,6 +62,7 @@ import {
 } from "../i18n/kit-labels";
 import { useEdgeFade } from "../lib/strip-fade";
 import { dirOf, type Direction } from "../lib/direction";
+import { focusContainer, focusFirst, focusIsLost, tabStops, whenFocusLeftForNothing } from "../lib/focus-left";
 
 // ---------- Types ----------
 
@@ -67,6 +70,11 @@ export interface DataTableColumn<T> {
   key: string;
   header: ReactNode;
   cell: (row: T) => ReactNode;
+  /** What a client sort orders the column by. Strings collate in the table's `locale`
+   *  (digits as numbers, case and accents left out; 0.51.7, audit 2026-10-30 DSP-3),
+   *  numbers compare as numbers and sort before strings, `null` and `undefined` sort
+   *  last in either direction. The order is `compareSortValues`, exported for an app's
+   *  own list beside the table (0.52). */
   sortBy?: (row: T) => string | number | null | undefined;
   filter?: ColumnFilter<T>;
   filterBy?: (row: T) => string;
@@ -261,8 +269,11 @@ export interface ServerPagination {
 }
 
 export interface DataTableProps<T> {
-  rows: T[];
-  columns: DataTableColumn<T>[];
+  /** `readonly` since 0.52 (refactor audit 2026-10-30, API-7): the table never changes the
+   *  arrays it is handed, so a caller's `as const` list or a query's frozen result needs no
+   *  copy. Only widens: a mutable array is still one. The same for `columns` and `sorts`. */
+  rows: readonly T[];
+  columns: readonly DataTableColumn<T>[];
   rowKey: (row: T) => string | number;
   defaultPageSize?: number;
   onRowClick?: (row: T) => void;
@@ -284,6 +295,11 @@ export interface DataTableProps<T> {
    * not wrap table cells, and the absolutely-positioned row overlay that is the
    * usual workaround would sit on top of the per-cell controls these rows carry
    * (status toggles, the selection checkbox, nested links) and swallow them.
+   *
+   * With `onRowClick` a plain click opens the row through it, in place. Without one
+   * (0.52, refactor audit 2026-10-30, DSP-23 b) the click follows the link — through the
+   * provider's `linkComponent` for an in-app path, as every kit link — and the phone
+   * card is that link too; before, the click was cancelled and opened nothing.
    */
   rowHref?: (row: T) => string | undefined;
   expandedRow?: (row: T) => ReactNode | null;
@@ -437,7 +453,7 @@ export interface DataTableProps<T> {
    */
   filters?: FilterState;
   onFiltersChange?: (next: FilterState) => void;
-  sorts?: SortState[];
+  sorts?: readonly SortState[];
   onSortsChange?: (next: SortState[]) => void;
   /**
    * Controlled page size, as `sorts` above: the table pages by it and hands its pager's
@@ -618,8 +634,10 @@ export interface DataTableProps<T> {
    */
   desktopSwipeActions?: boolean | DataTableDesktopSwipeActions<T>;
   /**
-   * Renders as a full-width row above the data rows in the desktop table
-   * (mobile has no equivalent list-row slot, so it's desktop-only). For a
+   * Renders as a full-width row above the data rows in the desktop table, and since
+   * 0.51.7 as the first item of the phone's card list (audit 2026-10-30 DSP-2: the card
+   * list dropped it, and kastlan's inline "Add meter" editor never appeared on a phone).
+   * On the phone it is no card: no row link, swipe or selection toggle. For a
    * toggle that shows/hides a slice of rows, style it as an expand/collapse
    * disclosure (chevron + label) so it reads as part of the table rather
    * than a floating control above it. See feedback #10/#11 (transactions'
@@ -629,9 +647,11 @@ export interface DataTableProps<T> {
   /**
    * 0.48 (keksdose dev #603: "it should rather be sticky, so the user can show hide them
    * everywhere on click"): pin the {@link leadingRow} under the sticky header while the
-   * rows scroll beneath both — its `top` is the header's measured height. Desktop only,
-   * as `leadingRow` is; it sticks within the table's own scroller (a bounded body:
-   * `fillHeight` or `maxBodyHeight`). Default: it scrolls with the rows.
+   * rows scroll beneath both — its `top` is the header's measured height. It sticks
+   * within the table's own scroller (a bounded body: `fillHeight` or `maxBodyHeight`).
+   * On a phone (0.51.7) it is pinned at the top of the card list's scroller (the list
+   * under a bounded `fillHeight`, else the page), with `mobileGroupBy`'s section headers
+   * under it. Default: it scrolls with the rows.
    */
   leadingRowSticky?: boolean;
   /**
@@ -922,6 +942,28 @@ export interface DataTableDesktopSwipeActions<T> {
  */
 const FOOTER_CELL = "sticky bottom-0 z-10 bg-surface-2 shadow-[inset_0_2px_0_var(--border-strong)]";
 
+/** Where focus that leaves a row is still the row's (DSP-4): an overlay — a confirm, a
+ *  menu, a sheet — hands it back or closes with the row it was about. The kit marks its
+ *  own (`data-kit-layer`); an app's dialog says what it is. */
+const OVERLAY_SELECTOR = '[data-kit-layer],[role="dialog"],[role="alertdialog"],[aria-modal="true"],[role="menu"]';
+
+/** `rows`' places by `rowKey`, the first row of a key winning as a `findIndex`'s did; the
+ *  map built at the first lookup (0.52 code review, data-table.tsx). */
+function keyIndex<T>(rows: readonly T[], rowKey: (row: T) => string | number): (key: string | number) => number {
+  let at: Map<string | number, number> | null = null;
+  return (key) => {
+    if (!at) {
+      at = new Map();
+      for (let i = rows.length - 1; i >= 0; i--) at.set(rowKey(rows[i]), i);
+    }
+    return at.get(key) ?? -1;
+  };
+}
+
+/** How long a filter's "n of m rows" waits for the typing to pause (DSP-23 d): longer than
+ *  the gap between two keystrokes, short enough to answer the word just typed. */
+const FILTER_ANNOUNCE_DELAY_MS = 500;
+
 // ---------- Phone sort control (keksdose K10) ----------
 
 /**
@@ -968,6 +1010,21 @@ import { DEFAULT_PERSIST_PREFIX, useTableState, type TableUrlSync } from "./use-
 import { useMobileReveal } from "./use-mobile-reveal";
 import { GROW_CELL_CLASS, GROW_PEER_CELL_CLASS, useColumnFit } from "./data-table-fit";
 
+/**
+ * rowMatches for one column's filter state, the text filter's query folded once (0.52
+ * code review, data-table-filters.ts): folded again for every row it tested, a 5000-row
+ * table folded the same query 5000 times per keystroke. Module-private: data-table-filters
+ * is re-exported whole by @eifi1/ui-kit/data-table, and this is no public API.
+ */
+function rowMatcher<T>(col: DataTableColumn<T>, state: FilterValue, locale?: string): (row: T) => boolean {
+  const filter = resolveFilter(col);
+  if (filter?.type === "text" && state.type === "text" && state.q.trim()) {
+    const words = searchWords(state.q, locale);
+    return (row) => matchesSearch(words, [filter.getValue(row)], locale);
+  }
+  return (row) => rowMatches(col, row, state, locale);
+}
+
 export function DataTable<T>({
   rows,
   columns: columnsProp,
@@ -1108,13 +1165,15 @@ export function DataTable<T>({
   // (a drag or "Auto-size columns" before it grew, KS N2) is ignored, and it has no
   // handle, so it can never pin it again. Ignored rather than deleted from storage, as
   // the widths above; the next resize or auto-size writes a blob without it.
+  // Keyed on the `grow` column's key, not the columns array: an inline `columns={…}`
+  // gave every render new widths, and the fit measured the table for it (DSP-19).
+  const growKey = columns.find((c) => c.grow)?.key;
   const widths = useMemo(() => {
     if (!resizable) return {};
-    const grow = columns.find((c) => c.grow)?.key;
-    if (!grow || !(grow in storedWidths)) return storedWidths;
-    const { [grow]: _ignored, ...rest } = storedWidths;
+    if (!growKey || !(growKey in storedWidths)) return storedWidths;
+    const { [growKey]: _ignored, ...rest } = storedWidths;
     return rest;
-  }, [resizable, storedWidths, columns]);
+  }, [resizable, storedWidths, growKey]);
   const hiddenCols = useMemo(
     () => (columnSettings ? storedHiddenCols : new Set<string>()),
     [columnSettings, storedHiddenCols],
@@ -1159,13 +1218,13 @@ export function DataTable<T>({
         if (v && !seen.has(v)) seen.add(v);
       }
       map[col.key] = Array.from(seen)
-        .sort()
+        .sort((a, b) => compareSortValues(a, b, locale))
         .map((v) => ({ value: v, label: v }));
     }
     return map;
     // `columns` by signature — see the note above the signatures.
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [columnSig, selectOptionsSig, rows]);
+  }, [columnSig, selectOptionsSig, rows, locale]);
 
   const filtered = useMemo(() => {
     if (serverRows) return rows;
@@ -1173,7 +1232,8 @@ export function DataTable<T>({
     for (const col of columns) {
       const state = filters[col.key];
       if (!state || !isFilterActive(state)) continue;
-      result = result.filter((row) => rowMatches(col, row, state, locale));
+      // One matcher per filter, its query folded once (0.52 code review, data-table-filters.ts).
+      result = result.filter(rowMatcher(col, state, locale));
     }
     return result;
     // eslint-disable-next-line react-hooks/exhaustive-deps
@@ -1198,14 +1258,16 @@ export function DataTable<T>({
         if (av == null && bv == null) continue;
         if (av == null) return 1;
         if (bv == null) return -1;
-        if (av < bv) return dir === "asc" ? -1 : 1;
-        if (av > bv) return dir === "asc" ? 1 : -1;
+        // The order `compareSortValues` exports (0.52): one rule, here and in an app's
+        // own list beside the table. Nulls are last above, in either direction.
+        const order = compareSortValues(av, bv, locale);
+        if (order !== 0) return dir === "asc" ? order : -order;
       }
       return 0;
     });
     return copy;
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [filtered, sorts, columnSig, serverRows]);
+  }, [filtered, sorts, columnSig, serverRows, locale]);
 
   // `paginated={false}` is expressed as "page size = everything" rather than as a
   // second code path, so slicing, the page clamp and the range summary all keep
@@ -1224,10 +1286,16 @@ export function DataTable<T>({
   const safePage = isServer
     ? Math.min(Math.max(0, serverPagination!.page), totalPages - 1)
     : Math.min(page, totalPages - 1);
-  const slice =
-    isServer || unpaged || pageSize === Infinity
-      ? sorted
-      : sorted.slice(safePage * effectivePageSize, safePage * effectivePageSize + effectivePageSize);
+  // Memoised (refactor audit 2026-10-30, DSP-19): the fit, the rows' window and the
+  // range selection compare the page's rows by identity, and a fresh `slice(…)` on every
+  // render of a paginated table — the default — had the fit lay the whole table out on a
+  // ticked box, a keystroke, any parent render.
+  const wholeList = isServer || unpaged || pageSize === Infinity;
+  const slice = useMemo(
+    () =>
+      wholeList ? sorted : sorted.slice(safePage * effectivePageSize, safePage * effectivePageSize + effectivePageSize),
+    [wholeList, sorted, safePage, effectivePageSize],
+  );
 
   const toggleSort = (key: string, shiftKey: boolean) => {
     const col = columns.find((c) => c.key === key);
@@ -1320,6 +1388,16 @@ export function DataTable<T>({
   // Seeded with the mount value: a live region that speaks on first paint talks over
   // the page the user has just opened, and every table on that page does it at once.
   const announcedFilterKey = useRef(filterKey);
+  // Spoken once the typing pauses (refactor audit 2026-10-30, DSP-23 d): every keystroke
+  // in a text filter is a new filter, and "12 of 137 rows" on each one — through the live
+  // region's 50 ms reset — talked over the very letters being typed. The count is read
+  // when the sentence goes out, so it is the rows the pause left on screen.
+  const filterSpeech = useRef({ shown: filtered.length, total: rows.length, labels });
+  useLayoutEffect(() => {
+    filterSpeech.current = { shown: filtered.length, total: rows.length, labels };
+  });
+  const filterTimer = useRef<ReturnType<typeof setTimeout> | undefined>(undefined);
+  useEffect(() => () => clearTimeout(filterTimer.current), []);
   useEffect(() => {
     if (announcedFilterKey.current === filterKey) return;
     announcedFilterKey.current = filterKey;
@@ -1328,8 +1406,12 @@ export function DataTable<T>({
     // filtered total — so the "n of m" sentence has no second number to give here.
     // Saying nothing is better than announcing the page size as a result count.
     if (serverRows) return;
-    announce(labels.filterResults(filtered.length, rows.length));
-  }, [filterKey, filtered.length, rows.length, serverRows, announce, labels]);
+    clearTimeout(filterTimer.current);
+    filterTimer.current = setTimeout(() => {
+      const { shown, total, labels: words } = filterSpeech.current;
+      announce(words.filterResults(shown, total));
+    }, FILTER_ANNOUNCE_DELAY_MS);
+  }, [filterKey, serverRows, announce]);
 
   // 1-based, because that is what the page strip shows and what a person says.
   const goToPage = (p: number) => {
@@ -1348,8 +1430,11 @@ export function DataTable<T>({
     headRefs,
     scroller: () => desktopScroller.current,
     enabled: !usePhoneLayout(),
-    // Measured only when one of these changed (0.48.2): not on a ticked box.
-    content: [slice, columns, hiddenCols, widths, density, large],
+    // Measured only when one of these changed (0.48.2): not on a ticked box. The columns
+    // by their keys (DSP-19): an inline `columns={…}` is a new array every render. The
+    // locale (0.52 code review, data-table.tsx): the cells' dates, numbers and the kit's
+    // words follow it under the same rows and keys; the fit adds the headers' drawn text.
+    content: [slice, columnSig, hiddenCols, widths, density, large, locale],
   });
   const visibleColumns = useMemo(
     () => columns.filter((c) => !hiddenCols.has(c.key) && !autoHidden.has(c.key)),
@@ -1404,7 +1489,10 @@ export function DataTable<T>({
   const footerLabelCol = showFooter
     ? (visibleColumns.find((c) => !c.footer && !isTableOwnColumn(c.key)) ?? visibleColumns[0])
     : undefined;
-  const footerValue = (col: DataTableColumn<T>) => col.footer?.(sorted, slice);
+  // `footer` keeps its `T[]` parameters: narrowed to `readonly`, a caller's footer typed
+  // `(rows: Row[]) => …` would no longer fit (API-7 only widens). The table hands over the
+  // arrays it holds, as before, and changes neither.
+  const footerValue = (col: DataTableColumn<T>) => col.footer?.(sorted as T[], slice as T[]);
   const footerHeadingId = useId();
   // Each open row's detail row, for its disclosure button's `aria-controls`.
   const detailIdBase = useId();
@@ -1541,10 +1629,14 @@ export function DataTable<T>({
     if (el.parentElement) ro.observe(el.parentElement);
     return () => ro.disconnect();
   }, [phoneFill]);
+  // A sticky `leadingRow`'s height on a phone (audit 2026-10-30 DSP-2): the section
+  // headers stick under it, as the desktop's group bands stick under the desktop row.
+  const [phoneLeadHeight, setPhoneLeadHeight] = useState(0);
 
   const { mobileSlice, canRevealMoreMobile, loadMoreRef } = useMobileReveal({
-    rows: sorted,
-    slice,
+    // Read only there; its `T[]` widens to `readonly T[]` with its owner (API-7).
+    rows: sorted as T[],
+    slice: slice as T[],
     isServer,
     isMdUp,
     unpaged,
@@ -1594,12 +1686,18 @@ export function DataTable<T>({
   // the pager.
   const rowsFocusable = !!onRowClick;
   const [focusRowKey, setFocusRowKey] = useState<string | number | null>(null);
+  // The rows' places by key (0.52 code review, data-table.tsx): the tab stop's check
+  // below, the focus note and its recovery each walked the rows calling `rowKey` — on
+  // every render, at each focus, in every commit while a row was noted: under
+  // `virtualize`, 3000 rows, ~15000 calls per arrow step at the table's end. Built at the
+  // first lookup, once per array, so a table nobody focuses builds none. Keyed on the
+  // rows alone: `rowKey` is a pure function of its row, and a call site writes it inline.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const sliceIndex = useMemo(() => keyIndex(slice, rowKey), [slice]);
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const mobileIndex = useMemo(() => keyIndex(mobileSlice, rowKey), [mobileSlice]);
   const tabRowKey =
-    focusRowKey !== null && slice.some((r) => rowKey(r) === focusRowKey)
-      ? focusRowKey
-      : slice.length
-        ? rowKey(slice[0])
-        : null;
+    focusRowKey !== null && sliceIndex(focusRowKey) !== -1 ? focusRowKey : slice.length ? rowKey(slice[0]) : null;
 
   // What the memoised rows' handlers read at event time (0.48.2, K-052-2): the latest
   // props, refreshed every commit, so a row that bailed out of a render still toggles
@@ -1608,7 +1706,38 @@ export function DataTable<T>({
   // move over every row, rendered or not: the target is rendered, then focused.
   const virtualOn = !!virtualize && isMdUp && slice.length > 0;
   const focusRowRef = useRef<((index: number) => void) | undefined>(undefined);
+  // ---- When the focused row leaves (refactor audit 2026-10-30, DSP-4) ----
+  // The row holding the focus — its key, and where it stood — noted as the focus comes
+  // into it (the rows report it, through React, so a menu or a dialog a row opened in a
+  // portal is the row's too). A delete, a status change that filters the row out, an
+  // approval: the row's DOM goes, the focus with it to <body>, and the commit that took it
+  // puts the focus on the row now in its place (below).
+  const heldRow = useRef<{ key: string | number; index: number } | null>(null);
+  const noteRowFocus = (key: string | number) => {
+    heldRow.current = { key, index: (isMdUp ? sliceIndex : mobileIndex)(key) };
+  };
+  // A gone row's note waiting for the overlay that holds the focus (below): watched as
+  // a node until it leaves the page, since its close need not render the table.
+  const overlayWatch = useRef<{ layer: Element; stop: () => void } | null>(null);
+  const settleRef = useRef<() => void>(() => {});
+  const watchOverlay = (layer: Element) => {
+    if (overlayWatch.current?.layer === layer) return;
+    overlayWatch.current?.stop();
+    const observer = new MutationObserver(() => {
+      if (layer.isConnected) return;
+      stop();
+      settleRef.current();
+    });
+    const stop = () => {
+      observer.disconnect();
+      if (overlayWatch.current?.layer === layer) overlayWatch.current = null;
+    };
+    observer.observe(layer.ownerDocument.body, { childList: true, subtree: true });
+    overlayWatch.current = { layer, stop };
+  };
+  useEffect(() => () => overlayWatch.current?.stop(), []);
   const latestRowCtx: DataTableRowCtx<T> = {
+    noteFocus: noteRowFocus,
     moveFocus: virtualOn
       ? (from, key) => {
           const target = rowNavTarget(from, key, slice.length);
@@ -1653,7 +1782,7 @@ export function DataTable<T>({
 
   // One mobile card (`MobileRow`, data-table-mobile.tsx). A function so the flat list
   // and the grouped list (below) share identical row markup.
-  const renderMobileRow = (row: T) => {
+  const renderMobileRow = (row: T, index: number) => {
     const key = rowKey(row);
     const expanded = isExpanded?.(row) ?? false;
     return (
@@ -1661,6 +1790,7 @@ export function DataTable<T>({
         key={key}
         ctx={rowCtx}
         rowKey={key}
+        rowIndex={index}
         row={row}
         expanded={expanded}
         expansion={expanded ? openedRowContent(row) : null}
@@ -1756,15 +1886,72 @@ export function DataTable<T>({
     focusRowRef.current = focusRowAt;
   }, [focusRowAt]);
 
+  // The commit that took the focused row (DSP-4): if the focus fell with it — to <body>,
+  // not into a dialog or a field the app chose — it goes to the row now at that index,
+  // else the last row, else the table itself (`tabIndex=-1` while empty, named by
+  // `labels.table`); the card on a phone. A focusable row (`onRowClick`) takes it itself,
+  // any other its first control. The remaining count is said, as a filter's is: the
+  // focus moved without the user moving it. translation-review's `keepFocusAt` is the
+  // kit's earlier copy of the rule, for its groups.
+  //
+  // Every commit while a row is noted, a lookup by its key. A focus the user took
+  // elsewhere drops the note (`onBlur` on the root, below), and since the 0.52 code review
+  // so does one that went to nothing — a click on the page's background: kept, it was the
+  // one case where a later removal (a refetch, a sync) pulled the focus back in.
+  const settleFocus = () => {
+    const held = heldRow.current;
+    if (!held) return;
+    const now = (isMdUp ? sliceIndex : mobileIndex)(held.key);
+    if (now !== -1) {
+      held.index = now;
+      return;
+    }
+    const list = isMdUp ? tableRef.current : phoneListRef.current;
+    // In an overlay — a confirm, an edit drawer — the focus is not lost yet: the overlay
+    // hands it back to its opener as it closes, and the opener was in the row (0.52 code
+    // review, data-table.tsx: an optimistic delete with its confirm still open dropped the
+    // note, and the confirm's close dropped the focus to <body>). The note waits for the
+    // overlay to leave the page, watched as a node: the table need not render when it does
+    // (`useConfirm`'s provider, a Modal's exit). Not an overlay the table itself is in.
+    const layer = focusIsLost() ? null : document.activeElement?.closest(OVERLAY_SELECTOR);
+    if (layer && !(list && layer.contains(list))) {
+      watchOverlay(layer);
+      return;
+    }
+    heldRow.current = null;
+    overlayWatch.current?.stop();
+    if (!list || !focusIsLost()) return;
+    const shown = isMdUp ? slice : mobileSlice;
+    const at = shown.length === 0 ? -1 : Math.min(Math.max(held.index, 0), shown.length - 1);
+    if (at === -1) list.focus();
+    else if (isMdUp && virtualOn && rowsFocusable) focusRowRef.current?.(at);
+    else {
+      const row = list.querySelector<HTMLElement>(
+        isMdUp ? `:scope > tbody > tr[data-row-index="${at}"]` : `:scope > li[data-row-index="${at}"]`,
+      );
+      // Each of the row's stops in turn, then the table (0.52 code review): `focus()` on
+      // one that cannot hold it — `display: none`, in a closed <details>, a hidden input —
+      // does nothing, and the focus stayed on <body>.
+      const stops = !row ? [] : isMdUp && rowsFocusable ? [row] : tabStops(row, { includeSelf: false });
+      if (!focusFirst(stops)) focusContainer(list);
+    }
+    announce(labels.filterResults(paginationTotal, isServer ? paginationTotal : rows.length));
+  };
+  useLayoutEffect(() => {
+    settleRef.current = settleFocus;
+    settleFocus();
+  });
+
   // `mobileGroupBy` may be a desktop `groupBy` level (0.48), its label and end slot too.
   const mobileLevel = typeof mobileGroupBy === "function" ? null : (mobileGroupBy ?? null);
   const mobileKey = typeof mobileGroupBy === "function" ? mobileGroupBy : mobileGroupBy?.key;
-  const mobileGroups: { key: string; rows: T[] }[] | null = mobileKey
-    ? mobileSlice.reduce<{ key: string; rows: T[] }[]>((acc, row) => {
+  // `start`: the section's first card's place in the list (its `data-row-index`, DSP-4).
+  const mobileGroups: { key: string; rows: T[]; start: number }[] | null = mobileKey
+    ? mobileSlice.reduce<{ key: string; rows: T[]; start: number }[]>((acc, row, i) => {
         const key = mobileKey(row);
         const last = acc[acc.length - 1];
         if (last && last.key === key) last.rows.push(row);
-        else acc.push({ key, rows: [row] });
+        else acc.push({ key, rows: [row], start: i });
         return acc;
       }, [])
     : null;
@@ -1788,6 +1975,24 @@ export function DataTable<T>({
       // `<main>` and every `FillHeight` between it and this table key off it with
       // `has-[[data-fill-height]]`, so a page asks for the fill by passing the prop.
       data-fill-height={fillHeight ? "" : undefined}
+      // The focused row's note (DSP-4): cleared on the way down to whatever takes the
+      // focus, and set again on the way up by the row that holds it. Focus leaving for
+      // something real outside the table drops it — unless that is an overlay (a confirm,
+      // a menu), which hands the focus back, or closes with the row it asked about.
+      onFocusCapture={() => {
+        heldRow.current = null;
+        overlayWatch.current?.stop();
+      }}
+      onBlur={(e) => {
+        const to = e.relatedTarget;
+        if (to instanceof Element && !to.closest(OVERLAY_SELECTOR)) heldRow.current = null;
+        // Focus that left for nothing — a click on the page (0.52 code review): no
+        // element to say where, and a later removal of the row is no longer the user's.
+        const held = heldRow.current;
+        whenFocusLeftForNothing(e, () => {
+          if (heldRow.current === held) heldRow.current = null;
+        });
+      }}
       className={cn(
         "group/table",
         frame ? "overflow-clip" : "min-w-0",
@@ -1879,6 +2084,10 @@ export function DataTable<T>({
           )}
           <ul
             ref={phoneListRef}
+            // Named as the table is, and focusable while empty: where the focus goes when
+            // the last card leaves (DSP-4).
+            aria-label={labels.table}
+            tabIndex={mobileSlice.length === 0 ? -1 : undefined}
             className={cn(
               "divide-y divide-subtle",
               // Under `fillHeight` the list takes the room its parent gives it, and in a
@@ -1894,10 +2103,20 @@ export function DataTable<T>({
             )}
             aria-busy={isLoading || undefined}
           >
+            {/* The desktop's leading row, as the list's first item (0.51.7, audit
+              2026-10-30 DSP-2; MobileLeadingRow says what it is and is not). */}
+            {leadingRow ? (
+              <MobileLeadingRow sticky={leadingRowSticky} onHeight={setPhoneLeadHeight}>
+                {leadingRow}
+              </MobileLeadingRow>
+            ) : null}
             {mobileGroups
               ? mobileGroups.map((g) => (
                   <Fragment key={`hb-group:${g.key}`}>
-                    <li className="sticky top-0 z-10 flex flex-wrap items-baseline justify-between gap-x-3 bg-surface-2 px-4 py-1.5 text-xs font-semibold uppercase tracking-wide text-muted backdrop-blur">
+                    <li
+                      className="sticky top-0 z-10 flex flex-wrap items-baseline justify-between gap-x-3 bg-surface-2 px-4 py-1.5 text-xs font-semibold uppercase tracking-wide text-muted backdrop-blur"
+                      style={leadingRow && leadingRowSticky ? { top: phoneLeadHeight } : undefined}
+                    >
                       <span className="min-w-0">
                         {mobileGroupLabel
                           ? mobileGroupLabel(g.key)
@@ -1909,7 +2128,7 @@ export function DataTable<T>({
                         <span className="ms-auto tabular-nums">{mobileLevel.end(g.key, g.rows)}</span>
                       )}
                     </li>
-                    {g.rows.map(renderMobileRow)}
+                    {g.rows.map((r, i) => renderMobileRow(r, g.start + i))}
                   </Fragment>
                 ))
               : mobileSlice.map(renderMobileRow)}
@@ -1992,6 +2211,11 @@ export function DataTable<T>({
             behind it shows, so the panel names the row it opened from. */}
           <FullBleedDialog
             open={dialogOpen}
+            // The open row's editor is the row's focus too: a Delete in it takes the row,
+            // and the dialog with it (DSP-4).
+            onFocus={() => {
+              if (mobileDialogRow) noteRowFocus(rowKey(mobileDialogRow));
+            }}
             onClose={closeDialog}
             closeLabel={labels.close}
             header={mobileDialogRow ? mobilePrimaryCol?.cell(mobileDialogRow) : null}
@@ -2036,6 +2260,8 @@ export function DataTable<T>({
                 className={cn("w-full", compact ? "text-xs" : "text-sm")}
                 data-fit-grow={growDrawn ? "" : undefined}
                 aria-label={labels.table}
+                // Focusable while empty: where the focus goes when the last row leaves (DSP-4).
+                tabIndex={slice.length === 0 ? -1 : undefined}
                 aria-busy={isLoading || undefined}
                 // `virtualize` (0.48.2): every row counted, rendered or not.
                 aria-rowcount={rowWindow?.rowCount}