@12-apps/ui 6.57.0 → 6.59.0

package/src/components/data-display/DataViews/base-list-card-layout.tsx

@@ -0,0 +1,104 @@
+"use client";
+
+import { type ReactNode } from "react";
+
+import { Box } from "../../../mui/Box";
+import type { BaseListCardProps } from "./base-list-card";
+import { rowGutters, type StackPlacement, type useRowShell } from "./base-list-card-geometry";
+import { cellRailsTemplate } from "./list-card-rails";
+import { cellTracks, useCellConfig, type ListCardCellConfig } from "./list-card-cells";
+
+/**
+ * WHAT SHAPE A ROW TAKES, resolved once: its cells and their template, whether
+ * it ends in the "this opens" chevron, and what its two-line form keeps.
+ *
+ * Split from the card at the file-size gate. Everything here decides; nothing
+ * here renders but the standalone container.
+ */
+
+/**
+ * Which cell config applies, and whether this row resolves its own tracks.
+ *
+ * The list's config wins over the card's: one declaration of the list's shape is
+ * the point, so a row inside a group cannot introduce a column of its own. And
+ * the template is standalone-only — inside a group the GROUP owns it and the row
+ * is subgrid over it, because a row resolving its own tracks is exactly what
+ * stops a list from lining up.
+ */
+function useResolvedCells(
+  props: BaseListCardProps,
+  inGroup: boolean,
+  gutters: { disclose: boolean; drag: boolean; select: boolean },
+): {
+  cells: readonly ListCardCellConfig<never>[] | null;
+  configured: boolean;
+  cellTemplate: string | null;
+} {
+  const groupCells = useCellConfig();
+  const cells = groupCells ?? props.cells ?? null;
+  const configured = cells != null && cells.length > 0 && props.row != null;
+  const cellTemplate = configured && !inGroup ? cellRailsTemplate(cellTracks(cells), gutters) : null;
+  return { cells, configured, cellTemplate };
+}
+
+/**
+ * Whether the row ends in the "this opens" chevron: it is live and leads
+ * somewhere it can actually go — a click handler, or a link the row renders.
+ * Only a named-slot row with a title renders an anchor for `href` (the caption
+ * wraps the title), so an `href` alone does not count elsewhere: a chevron on
+ * a row that cannot open is the promise the disclosure chevron's docblock
+ * warns about. Not when the row expands either:
+ * the disclosure chevron already speaks, and a second arrow meaning something
+ * else beside it would contradict it.
+ */
+function rowOpens(
+  props: BaseListCardProps,
+  shell: ReturnType<typeof useRowShell>,
+  configured: boolean,
+  expandable: boolean,
+): boolean {
+  if (expandable) return false;
+  // The named-slot caption renders its anchor only around a title.
+  return shell.acts || (shell.actionable && props.href != null && props.title != null && !configured);
+}
+
+/**
+ * The cell that takes the VALUE's place when the row stacks: the one the config
+ * marks `strong` ("the figure the row is really about"), else the last — as
+ * long as it is not the first cell, which already holds the title's place.
+ */
+function valueCellId(cells: readonly ListCardCellConfig<never>[]): string | null {
+  const first = cells[0];
+  const candidate = cells.find((cell) => cell.strong === true && cell !== first) ?? cells[cells.length - 1];
+  return candidate != null && candidate !== first ? candidate.id : null;
+}
+
+/** Everything the row's shape depends on, resolved once. */
+export function useRowLayout(
+  props: BaseListCardProps,
+  shell: ReturnType<typeof useRowShell>,
+  expandable: boolean,
+): ReturnType<typeof useResolvedCells> & { opens: boolean; stack: StackPlacement } {
+  const resolved = useResolvedCells(props, shell.group != null, rowGutters(props, shell));
+  const cells = resolved.configured ? resolved.cells : null;
+  return {
+    ...resolved,
+    opens: rowOpens(props, shell, resolved.configured, expandable),
+    stack: {
+      firstCell: cells?.[0]?.id ?? null,
+      valueCell: cells == null ? null : valueCellId(cells),
+      expandable,
+    },
+  };
+}
+
+/**
+ * A standalone row's QUERY CONTAINER. A container query matches an ancestor,
+ * never the element itself, so the row cannot be the container its own
+ * two-line template asks about. In a group the group is the container, and the
+ * row must stay its direct child for subgrid, so no wrapper there.
+ */
+export function StandaloneContainer({ inGroup, children }: { inGroup: boolean; children: ReactNode }): React.JSX.Element {
+  if (inGroup) return <>{children}</>;
+  return <Box sx={{ containerType: "inline-size", width: "100%", minWidth: 0 }}>{children}</Box>;
+}

package/src/components/data-display/DataViews/base-list-card-slots.tsx

@@ -1,5 +1,6 @@
 "use client";
 
+import KeyboardArrowRightIcon from "@mui/icons-material/KeyboardArrowRight";
 import { Fragment, type ReactNode } from "react";
 
 import { DescriptionItem, type DescriptionItemProps } from "../DescriptionItem";
@@ -242,19 +243,34 @@ export function ListCardActions({
   actions,
   alwaysVisible,
   menu,
+  opens = false,
   testId,
 }: {
   actions?: ReactNode;
   alwaysVisible?: boolean;
   menu?: ReactNode;
+  /** End the row with the "this opens" chevron. */
+  opens?: boolean;
   testId: (slot: string) => string | undefined;
 }): React.JSX.Element | null {
-  if (actions == null && menu == null) return null;
+  if (actions == null && menu == null && !opens) return null;
   return (
-    // z-index 1: above the stretched link, so these stay clickable.
+    // z-index 1: above the stretched link, so these stay clickable. The box
+    // itself lets clicks through (`pointer-events: none`, re-enabled on its
+    // children): only the controls inside it are meant to catch one, and the
+    // chevron, which re-disables it, must hand its click to the row or link
+    // underneath rather than swallow it.
     <Box
       data-slot="actions"
-      sx={{ display: "flex", alignItems: "center", gap: 0.5, position: "relative", zIndex: 1 }}
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 0.5,
+        position: "relative",
+        zIndex: 1,
+        pointerEvents: "none",
+        "& > *": { pointerEvents: "auto" },
+      }}
     >
       {actions && (
         <Box
@@ -282,6 +298,31 @@ export function ListCardActions({
           {menu}
         </Box>
       )}
+      {opens && <OpenChevron testId={testId("open")} />}
+    </Box>
+  );
+}
+
+/**
+ * THE "THIS OPENS" CHEVRON, at the end of a row that leads somewhere.
+ *
+ * A row that navigates or opens a record looked exactly like a row that does
+ * nothing until a pointer hovered it, and a phone has no hover. Always visible —
+ * unlike `actions`, it is a statement about the row, not a control to reveal.
+ *
+ * Decorative to assistive tech (`aria-hidden`): the row itself is the button or
+ * the link, and already says so. It takes no click of its own for the same
+ * reason; the click falls through to the row.
+ */
+function OpenChevron({ testId }: { testId?: string }): React.JSX.Element {
+  return (
+    <Box
+      component="span"
+      aria-hidden
+      data-testid={testId}
+      sx={{ display: "flex", alignItems: "center", color: "text.secondary", pointerEvents: "none !important" }}
+    >
+      <KeyboardArrowRightIcon fontSize="small" />
     </Box>
   );
 }
@@ -293,6 +334,7 @@ export function ListCardTail({
   actions,
   actionsAlwaysVisible,
   menu,
+  opens,
   testId,
 }: {
   value?: ReactNode;
@@ -301,6 +343,7 @@ export function ListCardTail({
   actions?: ReactNode;
   actionsAlwaysVisible?: boolean;
   menu?: ReactNode;
+  opens?: boolean;
   testId: (slot: string) => string | undefined;
 }): React.JSX.Element {
   return (
@@ -319,6 +362,7 @@ export function ListCardTail({
         actions={actions}
         alwaysVisible={actionsAlwaysVisible}
         menu={menu}
+        opens={opens}
         testId={testId}
       />
     </>

package/src/components/data-display/DataViews/base-list-card.tsx

@@ -11,10 +11,10 @@ import { type CardSurfaceProps } from "./card-surface";
 import { DropIndicator } from "./data-views-drag";
 import { useDisclosure } from "./base-list-card-disclosure";
 import { actionProps, metaShape, rowStyles, useRowShell } from "./base-list-card-geometry";
+import { StandaloneContainer, useRowLayout } from "./base-list-card-layout";
 import { DiscloseSlot, DragSlot, SelectSlot } from "./base-list-card-gutters";
 import { type DataViewsDensity } from "./data-views-layout-context";
-import { cellRailsTemplate } from "./list-card-rails";
-import { ListCardCells, cellTracks, useCellConfig, type ListCardCellConfig } from "./list-card-cells";
+import { ListCardCells, type ListCardCellConfig } from "./list-card-cells";
 import {
   ListCardActions,
   ListCardCaption,
@@ -41,7 +41,16 @@ import {
  * same row renders full-bleed on a phone, in a 300px board column, and beside a
  * filter panel that opens and closes. Below `STACK_BREAK` it leaves the shared
  * rails entirely and goes two-line, which is the standard mobile transaction
- * row and beats truncating everything: title + value, then subtitle + status.
+ * row and beats truncating everything: the title (with its subtitle) on line
+ * 1, the value under it at the right edge.
+ * A CONFIGURED row keeps the same two facts — its first cell in the title's
+ * place, its `strong` (else last) cell in the value's — and drops the rest
+ * into the expandable body's job. Standalone, the card renders inside a
+ * wrapper that is the query container, since a row cannot query itself.
+ *
+ * A row that OPENS something (a click handler, or a link it renders) ends in a
+ * chevron saying so, at every width — unless it expands, where the disclosure
+ * chevron is the only arrow it carries.
  */
 
 export interface BaseListCardProps extends CardSurfaceProps {
@@ -145,33 +154,6 @@ export interface BaseListCardProps extends CardSurfaceProps {
 }
 
 
-
-
-/**
- * Which cell config applies, and whether this row resolves its own tracks.
- *
- * The list's config wins over the card's: one declaration of the list's shape is
- * the point, so a row inside a group cannot introduce a column of its own. And
- * the template is standalone-only — inside a group the GROUP owns it and the row
- * is subgrid over it, because a row resolving its own tracks is exactly what
- * stops a list from lining up.
- */
-function useResolvedCells(
-  props: BaseListCardProps,
-  inGroup: boolean,
-): {
-  cells: readonly ListCardCellConfig<never>[] | null;
-  configured: boolean;
-  cellTemplate: string | null;
-} {
-  const groupCells = useCellConfig();
-  const cells = groupCells ?? props.cells ?? null;
-  const configured = cells != null && cells.length > 0 && props.row != null;
-  const cellTemplate = configured && !inGroup ? cellRailsTemplate(cellTracks(cells)) : null;
-  return { cells, configured, cellTemplate };
-}
-
-
 /**
  * The row's middle: either the list's configured cells, or the named slots.
  *
@@ -185,6 +167,7 @@ function RowContent({
   slot,
   actionable,
   meta,
+  opens,
 }: {
   card: BaseListCardProps;
   cells: readonly ListCardCellConfig<never>[] | null;
@@ -192,6 +175,8 @@ function RowContent({
   slot: (name: string) => string | undefined;
   actionable: boolean;
   meta: { columns: number; present: boolean };
+  /** Whether the row ends in the "this opens" chevron. */
+  opens: boolean;
 }): React.JSX.Element {
   if (configured && cells != null) {
     return (
@@ -206,6 +191,7 @@ function RowContent({
           actions={actionable ? card.actions : undefined}
           alwaysVisible={card.actionsAlwaysVisible}
           menu={card.menu}
+          opens={opens}
           testId={slot}
         />
       </>
@@ -227,6 +213,7 @@ function RowContent({
         actions={actionable ? card.actions : undefined}
         actionsAlwaysVisible={card.actionsAlwaysVisible}
         menu={card.menu}
+        opens={opens}
         testId={slot}
       />
     </>
@@ -294,46 +281,56 @@ export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
   const { actionable, selectable, slot, drag, reserve, pad, padY, acts } = shell;
   const meta = metaShape(props);
   const disclosure = useDisclosure(props);
-  const { cells, configured, cellTemplate } = useResolvedCells(props, shell.group != null);
+  const { cells, configured, cellTemplate, opens, stack } = useRowLayout(props, shell, disclosure.expandable);
 
   return (
-    <Card
-      variant="outlined"
-      className={props.className}
-      dataTestId={props.testId}
-      aria-label={props["aria-label"]}
-      aria-disabled={actionable ? undefined : true}
-      onContextMenu={props.onContextMenu}
-      {...(acts ? actionProps(onClick) : {})}
-      {...drag.itemProps}
-      // A PLAIN OBJECT: `Card` merges by spreading, so a function sx vanishes.
-      sx={rowStyles(props, shell, cellTemplate)}
-    >
-      {drag.dropEdge != null && <DropIndicator edge={drag.dropEdge} />}
-      <DiscloseSlot
-        expandable={disclosure.expandable}
-        expanded={disclosure.expanded}
-        reserve={reserve}
-        onToggle={disclosure.toggle}
-        controls={disclosure.regionId}
-        testId={slot("disclose")}
-      />
-      <DragSlot drag={drag} reserve={reserve} testId={slot("drag")} />
-      <SelectSlot
-        selectable={selectable}
-        selected={selected}
-        reserve={reserve}
-        onToggleSelect={props.onToggleSelect}
-        testId={slot("checkbox")}
-      />
-      <Box data-slot="leading" sx={{ display: "flex", alignItems: "center" }}>
-        {props.leading}
-      </Box>
-      <RowContent card={props} cells={cells} configured={configured} slot={slot} actionable={actionable} meta={meta} />
-      <ExpandableBody disclosure={disclosure} padY={padY} pad={pad}>
-        {props.children}
-      </ExpandableBody>
-    </Card>
+    <StandaloneContainer inGroup={shell.group != null}>
+      <Card
+        variant="outlined"
+        className={props.className}
+        dataTestId={props.testId}
+        aria-label={props["aria-label"]}
+        aria-disabled={actionable ? undefined : true}
+        onContextMenu={props.onContextMenu}
+        {...(acts ? actionProps(onClick) : {})}
+        {...drag.itemProps}
+        // A PLAIN OBJECT: `Card` merges by spreading, so a function sx vanishes.
+        sx={rowStyles(props, shell, cellTemplate, stack)}
+      >
+        {drag.dropEdge != null && <DropIndicator edge={drag.dropEdge} />}
+        <DiscloseSlot
+          expandable={disclosure.expandable}
+          expanded={disclosure.expanded}
+          reserve={reserve}
+          onToggle={disclosure.toggle}
+          controls={disclosure.regionId}
+          testId={slot("disclose")}
+        />
+        <DragSlot drag={drag} reserve={reserve} testId={slot("drag")} />
+        <SelectSlot
+          selectable={selectable}
+          selected={selected}
+          reserve={reserve}
+          onToggleSelect={props.onToggleSelect}
+          testId={slot("checkbox")}
+        />
+        <Box data-slot="leading" sx={{ display: "flex", alignItems: "center" }}>
+          {props.leading}
+        </Box>
+        <RowContent
+          card={props}
+          cells={cells}
+          configured={configured}
+          slot={slot}
+          actionable={actionable}
+          meta={meta}
+          opens={opens}
+        />
+        <ExpandableBody disclosure={disclosure} padY={padY} pad={pad}>
+          {props.children}
+        </ExpandableBody>
+      </Card>
+    </StandaloneContainer>
   );
 }
 

package/src/components/data-display/DataViews/data-views-copy.ts

@@ -225,6 +225,13 @@ export interface DataViewsSelectionCopy {
   clearSelection: string;
   selectAll: string;
   onThisPage(count: number): string;
+  /**
+   * The toolbar's count while rows are ticked: "1 selecionado". A plural, so a
+   * function. Keep it SHORT: at 320 it shares line 1 with the clear button and
+   * has about 118px — "20 itens selecionados" (135px) wrapped and stranded the
+   * divider before it; "20 selecionados" fits.
+   */
+  selectedCount(count: number): string;
   /** One row's checkbox, which carries no visible label of its own. */
   selectRow: string;
   /**

package/src/components/data-display/DataViews/data-views-grid-parts.tsx

@@ -16,7 +16,7 @@ import type { ListGroupConfig } from "./list-card-rails";
 import { InlineFilterControls } from "./data-views-inline-bar";
 import { toOverflowFields, useFilterOverflow, type OverflowSplit } from "./data-views-overflow";
 import { GridHeaderRow } from "./data-views-header-row";
-import { resolveSelectionExtra, type SelectionExtraRender } from "./data-views-selection-extra";
+import { allOnPageSelected, resolveSelectionExtra, type SelectionExtraRender } from "./data-views-selection-extra";
 import { ShellToolbar } from "./data-views-shell-toolbar";
 import type { DisplayPanelView } from "./data-views-display-panel";
 import type { DataViewExport } from "./data-views-export";
@@ -284,6 +284,7 @@ function ShellStack<T extends Record<string, unknown>>({
           rowActions={props.rowActions}
           bulkActions={props.bulkActions}
           selectionExtra={resolveSelectionExtra(props)}
+          allOnPageSelected={allOnPageSelected(c, props.getRowId)}
           toolbarRightSlot={props.toolbarRightSlot}
           compactControls={showInline && split.compactControls}
           counterHidden={showInline && split.counterHidden}

package/src/components/data-display/DataViews/data-views-selection-extra.ts

@@ -47,6 +47,15 @@ export type SelectionExtraRender<T extends Record<string, unknown>> = (
  * Returns `undefined` with nothing selected, so the toolbar renders no empty
  * slot: a widening with nothing to widen is not a control.
  */
+/** Every row the page is rendering is selected — and the page is not empty. */
+export function allOnPageSelected<T extends Record<string, unknown>>(
+  c: DataViewsController<T>,
+  getRowId: (row: T) => string | number,
+): boolean {
+  const page = c.matched;
+  return page.length > 0 && page.every((row) => c.selectedIds.has(getRowId(row)));
+}
+
 export function resolveSelectionExtra<T extends Record<string, unknown>>({
   c,
   getRowId,
@@ -61,7 +70,7 @@ export function resolveSelectionExtra<T extends Record<string, unknown>>({
   return selectionExtra({
     selectedRows: c.selectedRows,
     clearSelection: c.clearSelection,
-    allOnPageSelected: page.length > 0 && page.every((row) => c.selectedIds.has(getRowId(row))),
+    allOnPageSelected: allOnPageSelected(c, getRowId),
     pageRowCount: page.length,
   });
 }

package/src/components/data-display/DataViews/data-views-shell-toolbar.tsx

@@ -23,6 +23,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   rowActions,
   bulkActions,
   selectionExtra,
+  allOnPageSelected,
   toolbarRightSlot,
   showInline,
   compactControls,
@@ -43,6 +44,8 @@ export function ShellToolbar<T extends Record<string, unknown>>({
   bulkActions?: (selectedRows: T[], clearSelection: () => void) => React.ReactNode;
   /** Already resolved by the shell, which is the party that knows the page. */
   selectionExtra?: React.ReactNode;
+  /** Every row on the page is ticked: the select-all box reads checked, else partial. */
+  allOnPageSelected?: boolean;
   toolbarRightSlot?: React.ReactNode;
   /** Search + filters, rendered on the toolbar line (see `GridToolbar`). */
   filterControls?: React.ReactNode;
@@ -75,6 +78,7 @@ export function ShellToolbar<T extends Record<string, unknown>>({
       rowActions={rowActions}
       bulkActions={bulkActions}
       selectionExtra={selectionExtra}
+      allOnPageSelected={allOnPageSelected}
       sortFields={c.resolvedSortFields}
       activeSortField={c.activeSortField}
       activeSortOrder={c.activeSortOrder}

package/src/components/data-display/DataViews/data-views-toolbar.tsx

@@ -28,6 +28,8 @@ export interface GridToolbarProps<T extends Record<string, unknown>> {
   bulkActions?: (selectedRows: T[], clearSelection: () => void) => React.ReactNode;
   /** A control between the count and the actions menu — see `selectionExtra`. */
   selectionExtra?: React.ReactNode;
+  /** Every row on the page is ticked: the select-all box reads checked, else partial. */
+  allOnPageSelected?: boolean;
   sortFields: SortFieldDefinition[];
   activeSortField: string;
   activeSortOrder: "asc" | "desc";
@@ -160,11 +162,13 @@ export function GridToolbar<T extends Record<string, unknown>>(props: GridToolba
         clearAllText={copy.filters.clearAll}
         hasSelection={selectedRows.length > 0}
         selectedCount={selectedRows.length}
+        selectedCountLabel={copy.selection.selectedCount}
         selectAll={props.selectAll}
         clearSelection={props.clearSelection}
         selectAllTestId={`${testIdPrefix}-select-all`}
         clearAllTestId={`${testIdPrefix}-clear-all`}
         selectionExtra={props.selectionExtra}
+        allSelected={props.allOnPageSelected}
         actions={renderBulkActions({
           rowActions: props.rowActions,
           bulkActions: props.bulkActions,

package/src/components/data-display/DataViews/data-views-url-echo.ts

@@ -0,0 +1,134 @@
+"use client";
+
+import { useEffect, useRef, useState } from "react";
+
+import type { RangeValue } from "./data-views-range-types";
+import type { DataViewServer, DataViewState, DataViewSyncState } from "./data-views-types";
+
+/**
+ * A server-mode grid's URL round trip, and the echo it must not re-apply.
+ *
+ * A server-mode host mirrors the grid's query into its URL and hands it back as
+ * `initialState`, which the base turns into `syncState` and MERGES over the live
+ * state, so browser back/forward moves the controls. But the browser shows the
+ * new URL before React renders it. An edit made in that window, such as
+ * clearing a date bound right after typing it, is overwritten when the render
+ * carrying the PREVIOUS query lands. The grid then re-emits that stale query,
+ * and the cleared filter comes back and sticks in the URL (FUT-3182, the
+ * audit trail's "De" bound).
+ *
+ * So the base records every query it emits. An `initialState` matching one
+ * still pending is the host echoing it back, not a navigation, and it is not
+ * merged. Anything else (back/forward, a deep link, a host-side reset) still is.
+ * A host whose round trip changes the slice's shape never matches, and keeps
+ * the old behaviour rather than losing a navigation.
+ */
+
+/** The URL-carried part of a grid state or query. */
+type UrlSlice = Pick<DataViewState, "search" | "pills" | "ranges" | "sortBy" | "scope">;
+
+/** Hosts drop unset bounds on the way through the URL, so the key drops them too. */
+function bounds(range: RangeValue): RangeValue | null {
+  const set = (value: number | string | undefined): boolean => value !== undefined && value !== "";
+  const kept: RangeValue = {
+    ...(set(range.min) ? { min: range.min } : {}),
+    ...(set(range.max) ? { max: range.max } : {}),
+  };
+  return Object.keys(kept).length > 0 ? kept : null;
+}
+
+const byKey = ([a]: [string, unknown], [b]: [string, unknown]): number => a.localeCompare(b);
+
+/** One comparable string for a URL slice: empty pills and unbounded ranges left out. */
+export function urlSliceKey(slice: UrlSlice): string {
+  const pills = Object.entries(slice.pills ?? {})
+    .filter(([, values]) => values.length > 0)
+    .sort(byKey);
+  const ranges = Object.entries(slice.ranges ?? {})
+    .map(([id, range]): [string, RangeValue | null] => [id, bounds(range)])
+    .filter(([, range]) => range !== null)
+    .sort(byKey);
+  return JSON.stringify({
+    q: slice.search ?? "",
+    pills,
+    ranges,
+    sort: slice.sortBy ?? [],
+    scope: slice.scope ?? null,
+  });
+}
+
+/** Enough to cover a burst of edits; older entries can no longer echo. */
+const MAX_PENDING = 20;
+
+/**
+ * Record what the grid emits, and recognise it coming back.
+ *
+ * `consumeEcho` answers whether a URL slice is one of the queries still in
+ * flight. A match drops it and every older one, since the host has caught up to
+ * at least that far; a miss is a navigation and clears the list.
+ */
+export function useUrlEchoGuard(server: DataViewServer | undefined): {
+  server: DataViewServer | undefined;
+  consumeEcho: (slice: UrlSlice) => boolean;
+} {
+  const pending = useRef<string[]>([]);
+  const recorded: DataViewServer | undefined = server && {
+    ...server,
+    onQueryChange: (query) => {
+      pending.current = [...pending.current, urlSliceKey(query)].slice(-MAX_PENDING);
+      server.onQueryChange(query);
+    },
+  };
+  const consumeEcho = (slice: UrlSlice): boolean => {
+    const at = pending.current.lastIndexOf(urlSliceKey(slice));
+    pending.current = at === -1 ? [] : pending.current.slice(at + 1);
+    return at !== -1;
+  };
+  return { server: recorded, consumeEcho };
+}
+
+function syncFrom(serverMode: boolean, initialState: DataViewState | undefined): DataViewSyncState | undefined {
+  if (!serverMode || !initialState) return undefined;
+  return {
+    search: initialState.search,
+    pills: initialState.pills,
+    ranges: initialState.ranges,
+    sortBy: initialState.sortBy,
+    // The scope belongs in the URL-driven slice alongside them: a
+    // `?view=recusados`-style deep link and browser back/forward must move the
+    // tab strip, and they must do it WITHOUT resetting the user's hidden
+    // columns — which is the whole reason this is a merging `syncState` and
+    // not a replacing `appliedState`.
+    scope: initialState.scope,
+  };
+}
+
+/**
+ * Derive the grid's reactive `syncState` from the URL-seeded `initialState` in
+ * server mode, so browser back/forward RE-APPLIES the search/pills/sort controls
+ * (merging over live state, preserving hidden columns — see
+ * {@link DataViewSyncState}). Client-mode tables (no `server`) get `undefined`.
+ *
+ * Seeded on the first render, so a deep link shows on mount. After that a new
+ * `initialState` reference is re-applied unless it is the grid's own query
+ * coming back (`consumeEcho`), which would overwrite an edit made since.
+ */
+export function useUrlSyncState(
+  server: DataViewServer | undefined,
+  initialState: DataViewState | undefined,
+  consumeEcho: (slice: UrlSlice) => boolean,
+): DataViewSyncState | undefined {
+  const serverMode = server !== undefined;
+  const [syncState, setSyncState] = useState(() => syncFrom(serverMode, initialState));
+  const seen = useRef({ serverMode, initialState });
+  useEffect(() => {
+    const last = seen.current;
+    if (last.serverMode === serverMode && last.initialState === initialState) return;
+    seen.current = { serverMode, initialState };
+    const next = syncFrom(serverMode, initialState);
+    if (next && consumeEcho(next)) return;
+    setSyncState(next);
+    // `consumeEcho` reads a ref; only a new URL seed or a mode change re-runs this.
+  }, [serverMode, initialState]);
+  return syncState;
+}