@declarion/react 0.48.2 → 0.50.0

package/dist-lib/components/{shared → actions}/ObjectActionBar.d.ts

@@ -1,7 +1,7 @@
 import { type ReactNode } from "react";
 import { type ResolvedActionLayoutNode } from "../../lib/actions";
 import { type Action } from "../../types/schema";
-import { type WidgetContext } from "../../components/shared/ResponsiveActionBar";
+import { type WidgetContext } from "../../components/actions/ResponsiveActionBar";
 export type ObjectActionBarSlot = "detail" | "detail_toolbar" | "list_row" | "quick_peek";
 export type ObjectActionSelection = {
     include: string[];

package/dist-lib/components/{shared → actions}/ResponsiveActionBar.d.ts

@@ -232,7 +232,7 @@ interface LayoutDecision {
      */
     iconOnly: ReadonlySet<string>;
 }
-export declare function computeLayout(nodes: ResolvedActionLayoutNode[], containerWidth: number, reservedRightWidth: number, measuredWidths: Map<string, number>, entityActions: Record<string, Action> | undefined, globalActions: Record<string, Action> | undefined, measurementOverride?: (node: ResolvedActionLayoutNode) => boolean, prevInline?: ReadonlySet<string>, maxInline?: number): LayoutDecision;
+export declare function computeLayout(nodes: ResolvedActionLayoutNode[], containerWidth: number, reservedRightWidth: number, measuredWidths: Map<string, number>, entityActions: Record<string, Action> | undefined, globalActions: Record<string, Action> | undefined, measurementOverride?: (node: ResolvedActionLayoutNode) => boolean, prevInline?: ReadonlySet<string>, prevIconOnly?: ReadonlySet<string>): LayoutDecision;
 /**
  * slotIsContentSized answers the only question the contract check may act on:
  * is the box holding this bar sized BY the bar?

package/dist-lib/components/fields/cells/factories/date.d.ts

@@ -0,0 +1,2 @@
+import type { CellFactory } from "../registry";
+export declare const dateFactory: CellFactory;

package/dist-lib/components/file-widgets/upload.d.ts

@@ -8,9 +8,14 @@ export interface UploadOptions {
     signal?: AbortSignal;
 }
 export declare class UploadError extends Error {
+    /** The declared type's identifier, e.g. `file.too_large`. */
     code: string;
     status: number;
-    constructor(status: number, code: string, message: string);
+    /** The untouched body, so a declared member reaches a caller through ext(). */
+    raw?: unknown;
+    constructor(status: number, code: string, message: string, raw?: unknown);
+    /** A declared member of this error's type, read the one way. */
+    ext<T = unknown>(member: string): T | undefined;
 }
 export interface UploadEnvelope {
     status: string;

package/dist-lib/components/layout/Layout.d.ts

@@ -1,5 +1,5 @@
 import { useTabStore } from "../../stores/tabs";
 import { type NavNode, type Screen } from "../../types/schema";
-import type { Crumb } from "../../components/shared/Breadcrumbs";
+import type { Crumb } from "../../components/chrome/Breadcrumbs";
 export declare function Layout(): import("react").JSX.Element | null;
 export declare function buildCrumbs(nodes: NavNode[], screens: Record<string, Screen>, pathname: string, tabs: ReturnType<typeof useTabStore.getState>["tabs"], activeTabId: string | null, topLevelNavigate: (to: string) => void): Crumb[];

package/dist-lib/components/layout/TopBar.d.ts

@@ -1,5 +1,5 @@
 import { type RefObject } from "react";
-import { type Crumb } from "../../components/shared/Breadcrumbs";
+import { type Crumb } from "../../components/chrome/Breadcrumbs";
 export interface TopBarProps {
     breadcrumbs?: Crumb[];
     onCrumbClick?: (c: Crumb) => void;

package/dist-lib/components/pages/SmartListPage.d.ts

@@ -1,12 +1,2 @@
-import { type RowData } from "../../types/api";
-import type { Entity, PkValues } from "../../types/schema";
-interface SmartListPageProps {
-    screenCode: string;
-}
-export declare const PER_PAGE_MAX = 1000;
-export declare const PER_PAGE_DEFAULT = 200;
-export declare const PER_PAGE_OPTIONS: readonly [25, 50, 100, 200, 500, 1000];
-export declare function rowSelectionKey(entity: Entity, row: RowData): string;
-export declare function selectedRowPkValues(entity: Entity | undefined, rows: RowData[], selectedKeys: string[]): PkValues[];
-export declare function SmartListPage({ screenCode }: SmartListPageProps): import("react").JSX.Element;
-export {};
+import type { SmartListPageProps } from "./SmartListPage.impl";
+export declare function SmartListPage(props: SmartListPageProps): import("react").JSX.Element;

package/dist-lib/components/pages/SmartListPage.impl.d.ts

@@ -0,0 +1,4 @@
+export interface SmartListPageProps {
+    screenCode: string;
+}
+export declare function SmartListPage({ screenCode }: SmartListPageProps): import("react").JSX.Element;

package/dist-lib/components/pages/list/ListCardRow.d.ts

@@ -0,0 +1,40 @@
+import type { Row } from "@tanstack/react-table";
+import type { ListResponse, RowData } from "../../../types/api";
+import { type Action, type Entity, type Screen } from "../../../types/schema";
+import type { resolveCellRenderer } from "../../../components/fields/cells/registry";
+import type { RowInteraction } from "./useListRowInteraction";
+type CellRenderer = ReturnType<typeof resolveCellRenderer>;
+interface ListCardRowProps {
+    row: Row<RowData>;
+    /** The ABSOLUTE index, which is what decides striping - the list is
+     *  virtualized, so `nth-child` would count the render window. */
+    rowIndex: number;
+    entity: Entity;
+    screen: Screen;
+    entityCode: string | undefined;
+    entities: Record<string, Entity> | undefined;
+    /** The active saved view's columns, which the card projection may follow. */
+    savedViewColumns: string[] | undefined;
+    refs: ListResponse<RowData>["$refs"];
+    locale: string;
+    renderers: Map<string, CellRenderer>;
+    rowActions: {
+        code: string;
+        action: Action;
+    }[];
+    tabNavigate: (href: string, meta?: {
+        title?: string;
+        icon?: string;
+    }) => void;
+    interaction: RowInteraction;
+    hasSoftDelete: boolean;
+    zebra: boolean;
+    hasBatchActions: boolean;
+    hasDetailTarget: boolean;
+    /** The row's stable id, which is also TanStack's. */
+    rowKey: (row: Record<string, unknown>) => string;
+    /** TanStack Virtual's measure ref, so a card sizes itself. */
+    measureElement: (node: Element | null) => void;
+}
+export declare function ListCardRow({ row, rowIndex, entity, screen, entityCode, entities, savedViewColumns, refs, locale, renderers, rowActions, tabNavigate, interaction, hasSoftDelete, zebra, hasBatchActions, hasDetailTarget, rowKey, measureElement, }: ListCardRowProps): import("react").JSX.Element;
+export {};

package/dist-lib/components/pages/list/ListCardsBody.d.ts

@@ -0,0 +1,34 @@
+import type { Row } from "@tanstack/react-table";
+import type { Virtualizer } from "@tanstack/react-virtual";
+import type { ListResponse, RowData } from "../../../types/api";
+import type { resolveCellRenderer } from "../../../components/fields/cells/registry";
+import type { Action, Entity, Screen } from "../../../types/schema";
+import type { RowInteraction } from "./useListRowInteraction";
+interface ListCardsBodyProps {
+    rows: Row<RowData>[];
+    virtualizer: Virtualizer<HTMLDivElement, Element>;
+    entity: Entity;
+    screen: Screen;
+    entityCode: string | undefined;
+    entities: Record<string, Entity> | undefined;
+    savedViewColumns: string[] | undefined;
+    refs: ListResponse<RowData>["$refs"];
+    locale: string;
+    renderers: Map<string, ReturnType<typeof resolveCellRenderer>>;
+    rowActions: {
+        code: string;
+        action: Action;
+    }[];
+    tabNavigate: (href: string, meta?: {
+        title?: string;
+        icon?: string;
+    }) => void;
+    interaction: RowInteraction;
+    hasSoftDelete: boolean;
+    zebra: boolean;
+    hasBatchActions: boolean;
+    hasDetailTarget: boolean;
+    rowKey: (row: Record<string, unknown>) => string;
+}
+export declare function ListCardsBody({ rows, virtualizer, ...card }: ListCardsBodyProps): import("react").JSX.Element;
+export {};

package/dist-lib/components/pages/list/ListFloatbar.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedActionLayoutNode } from "../../../lib/actions";
-import { type WidgetContext } from "../../../components/shared/ResponsiveActionBar";
+import { type WidgetContext } from "../../../components/actions/ResponsiveActionBar";
 import type { Action, Entity, Screen } from "../../../types/schema";
 export interface ListFloatbarProps {
     selectedIds: string[];

package/dist-lib/components/pages/list/ListFooter.d.ts

@@ -0,0 +1,26 @@
+interface ListFooterProps {
+    /** An offset list's window shape. Absent on a cursor list. */
+    meta: {
+        has_more?: boolean;
+    } | undefined;
+    isCursor: boolean;
+    isPhone: boolean;
+    rowsLoaded: number;
+    selectedCount: number;
+    /** The total, and how it was produced. Undefined while the count is in
+     *  flight or after it failed - the footer degrades to the loaded count. */
+    countTotal: number | undefined;
+    countStrategy: "exact" | "estimated" | undefined;
+    countLoading: boolean;
+    countError: boolean;
+    page: number;
+    totalPages: number | undefined;
+    goToPage: (page: number) => void;
+    perPage: number;
+    setPerPage: (n: number) => void;
+    hasMorePages: boolean;
+    fetchNextPage: () => void;
+    isFetchingNextPage: boolean;
+}
+export declare function ListFooter({ meta, isCursor, isPhone, rowsLoaded, selectedCount, countTotal, countStrategy, countLoading, countError, page, totalPages, goToPage, perPage, setPerPage, hasMorePages, fetchNextPage, isFetchingNextPage, }: ListFooterProps): import("react").JSX.Element | null;
+export {};

package/dist-lib/components/pages/list/ListHeader.d.ts

@@ -1,5 +1,5 @@
 import { type ResolvedActionLayoutNode } from "../../../lib/actions";
-import { type WidgetContext } from "../../../components/shared/ResponsiveActionBar";
+import { type WidgetContext } from "../../../components/actions/ResponsiveActionBar";
 import type { Action } from "../../../types/schema";
 export interface ListHeaderProps {
     title: string;

package/dist-lib/components/pages/list/ListNoRows.d.ts

@@ -0,0 +1,32 @@
+import type { ReactNode } from "react";
+import { type Action, type Entity, type Screen } from "../../../types/schema";
+/** The sentence a failed load shows: the server's own, then the two members
+ *  saying WHICH value it is about - without them the reader is told something
+ *  went wrong and not what to change. Never the machine code, which is already
+ *  in the console and the audit. */
+export declare function listLoadErrorDescription(error: unknown): string;
+interface ListNoRowsProps {
+    isLoading: boolean;
+    /** The load has been running long enough to be worth saying so. */
+    tableLoadingStale: boolean;
+    isError: boolean;
+    error: unknown;
+    rowCount: number;
+    entity: Entity;
+    screen: Screen;
+    screenName: string;
+    screenIcon: string;
+    /** A search or a filter is active, so "no results" is the honest title
+     *  rather than "none yet". */
+    isFiltered: boolean;
+    /** The empty state invites a create only where the toolbar actually serves
+     *  one, so `disable_defaults: [__new]` is honoured. */
+    canCreate: boolean;
+    toolbarActions: {
+        code: string;
+        action: Action;
+    }[];
+    onRetry: () => void;
+}
+export declare function ListNoRows({ isLoading, tableLoadingStale, isError, error, rowCount, entity, screen, screenName, screenIcon, isFiltered, canCreate, toolbarActions, onRetry, }: ListNoRowsProps): ReactNode;
+export {};

package/dist-lib/components/pages/list/ListTable.d.ts

@@ -0,0 +1,34 @@
+import { type ReactNode } from "react";
+import { type ColumnDef, type Row, type Table } from "@tanstack/react-table";
+import type { Virtualizer } from "@tanstack/react-virtual";
+import { type SortCol, type SortNulls } from "../../../lib/sort";
+import type { RowData } from "../../../types/api";
+import type { Entity } from "../../../types/schema";
+import type { useHeaderReorder } from "./useHeaderReorder";
+interface ListTableProps {
+    table: Table<RowData>;
+    columns: ColumnDef<RowData>[];
+    rows: Row<RowData>[];
+    entity: Entity;
+    /** Published as CSS variables on the <table> so a resize drag reflows without
+     *  re-rendering the memoized body. */
+    columnSizeVars: Record<string, number>;
+    /** The real columns' summed width, which forces the horizontal scroll. */
+    totalColumnsWidth: number;
+    theadRef: React.RefObject<HTMLTableSectionElement | null>;
+    virtualizer: Virtualizer<HTMLDivElement, Element>;
+    /** The ordered visible set, which decides a header's drop slot. */
+    visibleCols: string[];
+    headerReorder: ReturnType<typeof useHeaderReorder>;
+    sortCols: SortCol[];
+    sortNullsMap: Map<string, SortNulls>;
+    shiftClickColumn: (field: string) => void;
+    applyColumnSort: (field: string, dir: "asc" | "desc", nulls: SortNulls | undefined) => void;
+    appendColumnSort: (field: string, dir: "asc" | "desc", nulls: SortNulls | undefined) => void;
+    clearColumnSort: (field: string) => void;
+    clearAllSorts: () => void;
+    renderRow: (row: Row<RowData>, index: number) => ReactNode;
+    isResizingColumn: string | false;
+}
+export declare function ListTable({ table, columns, rows, entity, columnSizeVars, totalColumnsWidth, theadRef, virtualizer: rowVirtualizer, visibleCols, headerReorder, sortCols, sortNullsMap, shiftClickColumn, applyColumnSort, appendColumnSort, clearColumnSort, clearAllSorts, renderRow, isResizingColumn, }: ListTableProps): import("react").JSX.Element;
+export {};

package/dist-lib/components/pages/list/ListTableRow.d.ts

@@ -0,0 +1,18 @@
+import type { Row } from "@tanstack/react-table";
+import type { RowData } from "../../../types/api";
+import type { Entity } from "../../../types/schema";
+import type { RowInteraction } from "./useListRowInteraction";
+interface ListTableRowProps {
+    row: Row<RowData>;
+    rowIndex: number;
+    entity: Entity;
+    hasSoftDelete: boolean;
+    zebra: boolean;
+    /** The entity has a detail route. A composite-PK entity has none, so without
+     *  the peek branch its rows looked dead. */
+    hasDetailTarget: boolean;
+    interaction: RowInteraction;
+    measureElement: (node: Element | null) => void;
+}
+export declare function ListTableRow({ row, rowIndex, entity, hasSoftDelete, zebra, hasDetailTarget, interaction, measureElement, }: ListTableRowProps): import("react").JSX.Element;
+export {};

package/dist-lib/components/pages/list/ListToolbar.d.ts

@@ -0,0 +1,43 @@
+import type { FilterNode } from "../../../lib/filters";
+import { type Entity, type Schema, type Screen } from "../../../types/schema";
+import type { ListColumnLayout } from "./useListColumnLayout";
+import type { ListQueryResult } from "./useListQuery";
+import type { ListSelection } from "./useListSelection";
+import type { ListSortState } from "./useListSort";
+import type { ListViews } from "./useListViews";
+interface ListToolbarProps {
+    screen: Screen;
+    entity: Entity;
+    entityCode: string | undefined;
+    schema: Schema | undefined;
+    screenCode: string;
+    screenName: string;
+    locale: string;
+    isPhone: boolean;
+    /** Cards mode has no column headers, so sorting moves into a menu here. */
+    isCardsPresentation: boolean;
+    sort: ListSortState;
+    columns: ListColumnLayout;
+    views: ListViews;
+    query: ListQueryResult;
+    selection: ListSelection;
+    filters: {
+        json: FilterNode[];
+        debouncedSearch: string;
+        count: number;
+        onOpen: () => void;
+    };
+    searchValue: string;
+    onSearchChange: (value: string) => void;
+    onSaveView: () => void;
+    page: number;
+    perPage: number;
+    includeDeleted: boolean;
+    canViewDeleted: boolean;
+    onToggleDeleted: () => void;
+    /** The entity auto-updates from the CDC relay, so the refresh control shows
+     *  the Live indicator instead of the button alone. */
+    isLive: boolean;
+}
+export declare function ListToolbar({ screen, entity, entityCode, schema, screenCode, screenName, locale, isPhone, isCardsPresentation, sort, columns, views, query, selection, filters, searchValue, onSearchChange, onSaveView, page, perPage, includeDeleted, canViewDeleted, onToggleDeleted, isLive, }: ListToolbarProps): import("react").JSX.Element;
+export {};

package/dist-lib/components/pages/list/SortHeaderMenu.d.ts

@@ -0,0 +1,14 @@
+import type { SortNulls } from "../../../lib/sort";
+export declare function SortHeaderMenu({ field, activeDir, activeNulls, inMultiSort, canAppend, onApply, onAppend, onClearColumn, onClearAll, }: {
+    field: string;
+    activeDir: "asc" | "desc" | false;
+    activeNulls: SortNulls | undefined;
+    /** True if this column is already part of the current sort list. */
+    inMultiSort: boolean;
+    /** True if the sort has room to add another column (length < cap). */
+    canAppend: boolean;
+    onApply: (dir: "asc" | "desc", nulls: SortNulls | undefined) => void;
+    onAppend: (dir: "asc" | "desc", nulls: SortNulls | undefined) => void;
+    onClearColumn: () => void;
+    onClearAll: () => void;
+}): import("react").JSX.Element;

package/dist-lib/components/pages/list/page-size.d.ts

@@ -0,0 +1,3 @@
+export declare const PER_PAGE_MAX = 1000;
+export declare const PER_PAGE_DEFAULT = 200;
+export declare const PER_PAGE_OPTIONS: readonly [25, 50, 100, 200, 500, 1000];

package/dist-lib/components/pages/list/sortable-header.d.ts

@@ -0,0 +1,2 @@
+import type { Entity } from "../../../types/schema";
+export declare function isHeaderSortable(headerId: string, entity: Entity | undefined): boolean;

package/dist-lib/components/pages/list/useListColumnLayout.d.ts

@@ -0,0 +1,37 @@
+import type { ColumnSizingState } from "@tanstack/react-table";
+import type { Screen } from "../../../types/schema";
+interface ListColumnLayoutInput {
+    screenCode: string;
+    screen: Screen | undefined;
+    searchParams: URLSearchParams;
+    setSearchParams: (next: URLSearchParams) => void;
+}
+/** Which columns a list shows, in what order, and how wide. */
+export interface ListColumnLayout {
+    /** The ordered visible set, from `?columns` or the screen/view default. */
+    visible: string[];
+    /** Live widths during a drag; the device store is the durable backing. */
+    sizing: ColumnSizingState;
+    setSizing: (updater: ColumnSizingState | ((prev: ColumnSizingState) => ColumnSizingState)) => void;
+    /** Apply a new ordered visible set - the one path for toggle, reorder and
+     *  show-all. */
+    apply: (next: string[]) => void;
+    /** Back to the screen or view default: drop `?columns`. Widths untouched. */
+    clear: () => void;
+    /** Drag-free reorder: swap one column a slot up or down. */
+    move: (col: string, dir: "up" | "down") => void;
+    /** Commit a finished resize to the device store, and say once that widths are
+     *  personal. */
+    commitResize: (sizing: ColumnSizingState) => void;
+    resetWidths: () => void;
+}
+/**
+ * Which columns a list shows, in what order, and how wide.
+ *
+ * Order, visibility, sort and filters ride the URL, so they are shareable and
+ * can be saved into a view. Widths are per DEVICE (localStorage), never sent to
+ * the server and never part of a saved view - which is why the two live in
+ * different places and why a resize says so the first time.
+ */
+export declare function useListColumnLayout({ screenCode, screen, searchParams, setSearchParams, }: ListColumnLayoutInput): ListColumnLayout;
+export {};

package/dist-lib/components/pages/list/useListQuery.d.ts

@@ -0,0 +1,66 @@
+import type { FilterNode } from "../../../lib/filters";
+import type { RowData, ListResponse } from "../../../types/api";
+import type { Entity, Screen } from "../../../types/schema";
+interface ListQueryInput {
+    entity: Entity | undefined;
+    entityCode: string | undefined;
+    screen: Screen | undefined;
+    screenCode: string;
+    page: number;
+    perPage: number;
+    /** The sort grammar the request carries, already stripped of the segments
+     *  the backend's strict parser would reject. Undefined when the URL carries
+     *  no sort and the screen declares no default. */
+    sortForRequest: string | undefined;
+    debouncedSearch: string;
+    filters: FilterNode[];
+    /** A malformed `?filters=` bookmark: the list loads unfiltered and the screen
+     *  shows the error rather than sending something the backend refuses. */
+    filterError: boolean;
+    includeDeleted: boolean;
+    expand: string[] | undefined;
+    select: string[] | undefined;
+    /** Whether to run the separate count query. A paginated list needs the total
+     *  to size its pager; a screen that loads one window and shows what it loaded
+     *  would pay a request per load for a number nothing renders. */
+    runCountQuery: boolean;
+    /** The canonical form of the URL, so a change resets the stale-loading clock. */
+    urlKey: string;
+}
+/** One view over the rows a list screen shows, whichever source produced them. */
+export interface ListQueryResult {
+    rows: RowData[];
+    meta: ListResponse<RowData>["meta"] | undefined;
+    /** Join-expansion data for the loaded window, keyed by entity then id. */
+    refs: ListResponse<RowData>["$refs"];
+    isLoading: boolean;
+    isFetching: boolean;
+    isError: boolean;
+    error: unknown;
+    /** True while a load has been running long enough to be worth saying so. */
+    isLoadingStale: boolean;
+    retry: () => void;
+    /** The total, and how it was produced. Undefined while the count is in flight
+     *  or after it failed - a caller degrades to the loaded row count. */
+    countTotal: number | undefined;
+    countStrategy: "exact" | "estimated" | undefined;
+    countLoading: boolean;
+    countError: boolean;
+    totalPages: number | undefined;
+    hasMorePages: boolean;
+    /** Cursor mode: an archive entity on a ClickHouse deployment, whose
+     *  cross-store hot+cold read cannot offset-paginate. */
+    isCursor: boolean;
+    fetchNextPage: () => void;
+    isFetchingNextPage: boolean;
+}
+/**
+ * The rows a list screen shows: the window query, the separate count query, and
+ * one view over whichever of the two sources is live.
+ *
+ * The window and the count are SEPARATE requests on purpose - the table renders
+ * the moment the window resolves and never blocks on a count that may take
+ * seconds on a firehose table.
+ */
+export declare function useListQuery(input: ListQueryInput): ListQueryResult;
+export {};

package/dist-lib/components/pages/list/useListRowInteraction.d.ts

@@ -0,0 +1,61 @@
+import type { MouseEvent as ReactMouseEvent } from "react";
+import type { QuickPeekFieldSpec } from "../../../components/list/QuickPeek";
+import { useLongPress } from "../../../hooks/useLongPress";
+import type { RowData } from "../../../types/api";
+import { type Action, type Entity, type Screen } from "../../../types/schema";
+interface RowInteractionInput {
+    entity: Entity | undefined;
+    screen: Screen | undefined;
+    screens: Record<string, Screen> | undefined;
+    entities: Record<string, Entity> | undefined;
+    searchParams: URLSearchParams;
+    tabNavigate: (href: string, meta: {
+        title?: string;
+        icon?: string;
+    }) => void;
+    /** Commits interaction-owned URL state before navigation, so a click that
+     *  lands before the passive tab effect runs does not lose it. */
+    commitScreenTabSearch: (search: string) => void;
+    /** A phone never peeks: the drawer would cover the list it came from. */
+    isPhone: boolean;
+    canUpdate: boolean;
+}
+/** What a click, a long press or a right-click on a row does. */
+export interface RowInteraction {
+    /** Open in the right drawer instead of navigating, when the screen asks for
+     *  it and the viewport has room. */
+    peekAllowed: boolean;
+    peekRow: RowData | null;
+    setPeekRow: (row: RowData | null) => void;
+    peekFields: QuickPeekFieldSpec[];
+    peekActions: Record<string, Action>;
+    peekExecute: (code: string, action: Action, params: Record<string, unknown>) => Promise<unknown>;
+    /** Where the kebab, the right-click and the long press all land. */
+    contextMenu: {
+        x: number;
+        y: number;
+        row: RowData;
+    } | null;
+    setContextMenu: (menu: {
+        x: number;
+        y: number;
+        row: RowData;
+    } | null) => void;
+    /** The row a press started on. A ref, not state: it changes on every touch
+     *  and must not re-render a virtualized list mid-gesture. */
+    pressedRow: React.MutableRefObject<RowData | null>;
+    longPress: ReturnType<typeof useLongPress>;
+    onRowClick: (e: ReactMouseEvent, row: RowData) => void;
+    navigateToDetail: (row: RowData, options?: {
+        draft?: RowData | null;
+    }) => void;
+}
+/**
+ * Everything a row responds to.
+ *
+ * Peek and drill share one gesture, so the peek is DEFERRED by the double-click
+ * window: a second click on the same row cancels it and drills into detail
+ * instead. An immediately-opened drawer eats that second click.
+ */
+export declare function useListRowInteraction({ entity, screen, screens, entities, searchParams, tabNavigate, commitScreenTabSearch, isPhone, canUpdate, }: RowInteractionInput): RowInteraction;
+export {};

package/dist-lib/components/pages/list/useListSelection.d.ts

@@ -0,0 +1,31 @@
+import type { RowSelectionState } from "@tanstack/react-table";
+import type { RowData } from "../../../types/api";
+import { type Entity, type PkValues } from "../../../types/schema";
+/** The id a selection is keyed by: the entity's primary key values in the
+ *  platform's own detail-id encoding, so a composite key selects as stably as a
+ *  single one and the key round-trips to a detail route. */
+export declare function rowSelectionKey(entity: Entity, row: RowData): string;
+export declare function selectedRowPkValues(entity: Entity | undefined, rows: RowData[], selectedKeys: string[]): PkValues[];
+/** Which rows are selected, and the shapes an action needs them in. */
+export interface ListSelection {
+    state: RowSelectionState;
+    setState: (updater: RowSelectionState | ((prev: RowSelectionState) => RowSelectionState)) => void;
+    /** The selection's row ids, which are also TanStack's row ids. */
+    ids: string[];
+    /** The same rows as primary key values. */
+    pkValues: PkValues[];
+    /** The full row objects, resolved from the loaded window. */
+    rows: Record<string, unknown>[];
+    /** TanStack's `getRowId`, and the key everything else here agrees on. */
+    keyOf: (row: Record<string, unknown>) => string;
+}
+/**
+ * Which rows are selected.
+ *
+ * The state is DEEP retained-page state rather than URL state, and SCREEN-scoped
+ * (`scope: "path"`): it survives a tab switch, Back, and an in-screen filter
+ * change. Rows that a change filtered away are PRUNED rather than the selection
+ * being blanket-cleared, so a filter that still contains the selected rows keeps
+ * them.
+ */
+export declare function useListSelection(entity: Entity | undefined, rows: RowData[], isFetching: boolean): ListSelection;

package/dist-lib/components/pages/list/useListSort.d.ts

@@ -0,0 +1,45 @@
+import type { SortingState } from "@tanstack/react-table";
+import { type SortCol, type SortNulls } from "../../../lib/sort";
+interface ListSortInput {
+    searchParams: URLSearchParams;
+    setSearchParams: (next: URLSearchParams) => void;
+    /** The screen's declared `sort_default`, used when the URL carries none. */
+    screenSortDefault: string | undefined;
+    /** Commits the URL to the tab store in the same interaction, before React
+     *  Router schedules the navigation. */
+    commitScreenTabSearch: (search: string) => void;
+}
+/** How a list is ordered, and every gesture that changes it. */
+export interface ListSortState {
+    /** The parser-filtered columns, which the header and the saved-view path read. */
+    cols: SortCol[];
+    /** Per-column NULLs placement, which TanStack's `{id, desc}` cannot model. */
+    nullsByField: Map<string, SortNulls>;
+    /** The raw URL grammar minus the documented `$property.*` deferral, so
+     *  malformed input still reaches the backend's strict-parse 400 rather than
+     *  being silently rewritten. */
+    forRequest: string | undefined;
+    /** The same order in TanStack's own shape. */
+    tableSorting: SortingState;
+    /** The one writer of the URL `sort` param. */
+    write: (cols: SortCol[]) => void;
+    /** Replace the whole sort with one column, as a plain header click does. */
+    applyColumn: (field: string, dir: "asc" | "desc", nulls: SortNulls | undefined) => void;
+    /** Shift-click: toggle this column in or out of the multi-sort tail. */
+    shiftClickColumn: (field: string) => void;
+    /** Append a column to the tail with a chosen direction and NULLs placement. */
+    appendColumn: (field: string, dir: "asc" | "desc", nulls: SortNulls | undefined) => void;
+    /** Splice one column out, preserving the rest of the multi-sort. */
+    clearColumn: (field: string) => void;
+    clearAll: () => void;
+}
+/**
+ * The list's ordering: parsed from the URL, written back to it through one
+ * writer, and offered to the header in the shapes it needs.
+ *
+ * Every gesture goes through `write`, which commits the tab store before React
+ * Router schedules the navigation - that is what closes the mount-effect race
+ * for the header, the menu and the mobile sort sheet alike.
+ */
+export declare function useListSort({ searchParams, setSearchParams, screenSortDefault, commitScreenTabSearch, }: ListSortInput): ListSortState;
+export {};