@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/components/listing/columns.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Which FIELDS of a set are on screen.
+ *
+ * Odoo lists split columns in two: fields without `optional` cannot leave the
+ * view; fields with `optional="show"|"hide"` appear in the columns submenu
+ * and can be added or removed. ListView and FrameView were inventing that
+ * menu each on their own — FrameView let every column hide, ListView had no
+ * menu at all — so the same question («may I hide this?») had two answers.
+ *
+ * This hook is the third knob of a SET, next to `useSetControl` (how I look)
+ * and `useSelection` (which rows). Presentation can change; the visible
+ * field set stays.
+ */
+export type ColumnSpec = {
+    id: string;
+    label: string;
+    /** When true, the column may leave the view. Required columns stay, and
+     *  the submenu shows them checked and disabled so the split is visible. */
+    optional?: boolean;
+    /** Odoo `optional="hide"`: start off. Only for optional columns. */
+    defaultHidden?: boolean;
+};
+export type ColumnControl = {
+    visibleIds: readonly string[];
+    isVisible: (id: string) => boolean;
+    isRequired: (id: string) => boolean;
+    toggle: (id: string) => void;
+    optional: readonly ColumnSpec[];
+    required: readonly ColumnSpec[];
+    hasOptional: boolean;
+};
+export declare function isRequiredColumn(column: ColumnSpec): boolean;
+export declare function defaultVisibleIds(columns: readonly ColumnSpec[]): string[];
+/**
+ * Required columns always stay. Unknown ids drop out. If everything optional
+ * was unchecked, the first column remains — a table with zero columns is not
+ * a table.
+ */
+export declare function reconcileVisible(columns: readonly ColumnSpec[], visibleIds: readonly string[]): string[];
+export declare function toggleColumn(columns: readonly ColumnSpec[], visibleIds: readonly string[], id: string): string[];
+export declare function visibleColumns<T extends {
+    id: string;
+}>(columns: readonly T[], visibleIds: readonly string[]): T[];
+export declare function useColumnControl(columns: readonly ColumnSpec[], options?: {
+    visibleIds?: readonly string[];
+    onVisibleIdsChange?: (ids: readonly string[]) => void;
+}): ColumnControl;

package/dist/components/listing/columns.js

@@ -0,0 +1,72 @@
+"use client";
+import { useCallback, useState } from "react";
+export function isRequiredColumn(column) {
+    return column.optional !== true;
+}
+export function defaultVisibleIds(columns) {
+    return columns
+        .filter((column) => isRequiredColumn(column) || column.defaultHidden !== true)
+        .map((column) => column.id);
+}
+/**
+ * Required columns always stay. Unknown ids drop out. If everything optional
+ * was unchecked, the first column remains — a table with zero columns is not
+ * a table.
+ */
+export function reconcileVisible(columns, visibleIds) {
+    if (columns.length === 0)
+        return [];
+    const known = new Set(columns.map((column) => column.id));
+    const visible = new Set(visibleIds.filter((id) => known.has(id)));
+    for (const column of columns) {
+        if (isRequiredColumn(column))
+            visible.add(column.id);
+    }
+    if (visible.size === 0)
+        visible.add(columns[0].id);
+    return columns.filter((column) => visible.has(column.id)).map((column) => column.id);
+}
+export function toggleColumn(columns, visibleIds, id) {
+    const column = columns.find((one) => one.id === id);
+    if (column === undefined || isRequiredColumn(column)) {
+        return reconcileVisible(columns, visibleIds);
+    }
+    const current = reconcileVisible(columns, visibleIds);
+    const next = current.includes(id) ? current.filter((one) => one !== id) : [...current, id];
+    return reconcileVisible(columns, next);
+}
+export function visibleColumns(columns, visibleIds) {
+    const wanted = new Set(visibleIds);
+    return columns.filter((column) => wanted.has(column.id));
+}
+export function useColumnControl(columns, options = {}) {
+    const signature = columns.map((column) => column.id).join("\0");
+    const [owned, setOwned] = useState(() => defaultVisibleIds(columns));
+    const [seen, setSeen] = useState(signature);
+    const controlled = options.onVisibleIdsChange !== undefined;
+    if (signature !== seen) {
+        setSeen(signature);
+        if (!controlled)
+            setOwned(defaultVisibleIds(columns));
+    }
+    const raw = controlled ? (options.visibleIds ?? defaultVisibleIds(columns)) : owned;
+    const visibleIds = reconcileVisible(columns, raw);
+    const setVisible = controlled ? options.onVisibleIdsChange : setOwned;
+    const toggle = useCallback((id) => {
+        setVisible(toggleColumn(columns, visibleIds, id));
+    }, [columns, visibleIds, setVisible]);
+    const optional = columns.filter((column) => column.optional === true);
+    const required = columns.filter((column) => isRequiredColumn(column));
+    return {
+        visibleIds,
+        isVisible: (id) => visibleIds.includes(id),
+        isRequired: (id) => {
+            const column = columns.find((one) => one.id === id);
+            return column === undefined ? true : isRequiredColumn(column);
+        },
+        toggle,
+        optional,
+        required,
+        hasOptional: optional.length > 0,
+    };
+}

package/dist/components/listing/grouping.d.ts

@@ -0,0 +1,35 @@
+import { type GroupGrain, type GroupLevel } from "../../foundations/grouping.js";
+/**
+ * LOS NIVELES, como estado que alguien edita.
+ *
+ * El vocabulario —qué es un nivel, qué es un montón, cómo se identifica— vive en
+ * `system/grouping.ts`, porque lo hablan las DOS capas: la lista arma el árbol y
+ * la tabla lo dibuja, y una primitiva no puede importar de un contexto. Acá
+ * queda sólo el CONTROL, que es de la lista como lo son el de columnas y el de
+ * plegado.
+ */
+/** Los niveles puestos, y las cuatro cosas que se les hacen. El orden ES la
+ *  jerarquía: mover un nivel de lugar cambia por qué se parte primero. */
+export type GroupingControl = {
+    levels: readonly GroupLevel[];
+    /**
+     * Pone un nivel. Un campo de fecha puede estar puesto con VARIOS granos —«por
+     * mes y adentro por día»— así que lo que no se duplica es el par campo+grano,
+     * no el campo. Agrupar dos veces por exactamente lo mismo parte en montones de
+     * uno, y eso siempre es un error de tipeo.
+     */
+    add: (field: string, grain?: GroupGrain) => void;
+    remove: (field: string, grain?: GroupGrain) => void;
+    /** Tildar y destildar en un gesto, que es lo que hace una casilla. */
+    toggle: (field: string, grain?: GroupGrain) => void;
+    has: (field: string, grain?: GroupGrain) => boolean;
+    /** Mueve un nivel `delta` lugares. Se queda en los bordes en vez de dar la
+     *  vuelta: llegar al primero y volver al último no es lo que nadie espera de
+     *  una flecha «subir». */
+    move: (field: string, delta: number) => void;
+    clear: () => void;
+};
+export declare function useGroupingControl(options?: {
+    levels?: readonly GroupLevel[];
+    onLevelsChange?: (levels: readonly GroupLevel[]) => void;
+}): GroupingControl;

package/dist/components/listing/grouping.js

@@ -0,0 +1,47 @@
+"use client";
+import { levelKey, moveLevel, normalizeLevels, } from "../../foundations/grouping.js";
+import { useCallback, useState } from "react";
+// One empty array for every render: a fresh `[]` would change the callbacks below each time.
+const NO_LEVELS = [];
+export function useGroupingControl(options = {}) {
+    const [owned, setOwned] = useState(options.levels ?? NO_LEVELS);
+    const controlled = options.onLevelsChange !== undefined;
+    const levels = controlled ? (options.levels ?? NO_LEVELS) : owned;
+    const setLevels = controlled ? options.onLevelsChange : setOwned;
+    const keyOf = (field, grain) => levelKey(grain === undefined ? { field } : { field, grain });
+    const has = useCallback((field, grain) => levels.some((one) => levelKey(one) === keyOf(field, grain)), [levels]);
+    const add = useCallback((field, grain) => {
+        if (levels.some((one) => levelKey(one) === keyOf(field, grain)))
+            return;
+        /* Se normaliza SIEMPRE y no sólo al agregar fechas: es la única forma de
+           que tildar «día» y después «mes» dé «mes › día» sin que quien tilda
+           tenga que saber en qué orden hacerlo. */
+        setLevels(normalizeLevels([...levels, grain === undefined ? { field } : { field, grain }]));
+    }, [levels, setLevels]);
+    const remove = useCallback((field, grain) => {
+        setLevels(grain === undefined && !levels.some((one) => levelKey(one) === field)
+            ? /* Sin grano y sin coincidencia exacta: se saca el campo ENTERO, con
+                 todos sus granos. Es lo que quiere decir la × de un campo de
+                 fecha que está puesto por mes y por día. */
+                levels.filter((one) => one.field !== field)
+            : levels.filter((one) => levelKey(one) !== keyOf(field, grain)));
+    }, [levels, setLevels]);
+    return {
+        levels,
+        has,
+        add,
+        remove,
+        toggle: useCallback((field, grain) => {
+            if (levels.some((one) => levelKey(one) === keyOf(field, grain)))
+                remove(field, grain);
+            else
+                add(field, grain);
+        }, [levels, add, remove]),
+        move: useCallback((field, delta) => {
+            setLevels(moveLevel(levels, field, delta));
+        }, [levels, setLevels]),
+        clear: useCallback(() => {
+            setLevels([]);
+        }, [setLevels]),
+    };
+}

package/dist/components/listing/index.d.ts

@@ -0,0 +1,17 @@
+export { type ColumnControl, type ColumnSpec, defaultVisibleIds, reconcileVisible, toggleColumn, useColumnControl, visibleColumns, } from "./columns.js";
+export { ColumnsMenu, specsFromColumns, } from "./ColumnsMenu.js";
+export { Listing } from "./Listing.js";
+export { type ListIdentity, ListingBar } from "./ListingBar.js";
+export { type ClaimedField, claimedFields, columnsFromModel, readModelValue, } from "./modelColumns.js";
+export { type CursorSource, DEFAULT_PAGE_SIZE, PAGE_SIZES, type Pages, type PaginationBridge, type ServerPage, useCursorPagination, usePagination, } from "./pages.js";
+export { Pagination } from "./Pagination.js";
+export { RecordLink } from "./RecordLink.js";
+export { GroupHeader, Row } from "./Row.js";
+export { type Selection, useSelection } from "./selection.js";
+export { type SetControl, useSetControl } from "./set.js";
+export { toggleCollapsed, type TreeControl, useTreeControl, } from "./tree.js";
+export { type ViewOption, ViewSwitcher, } from "./ViewSwitcher.js";
+export { type GroupingControl, useGroupingControl, } from "./grouping.js";
+export { GroupingLevels, type GroupingLevelsProps, } from "./GroupingLevels.js";
+export { RecordCard } from "./RecordCard.js";
+export { type SortField, SortMenu, type SortMenuProps, } from "./SortMenu.js";

package/dist/components/listing/index.js

@@ -0,0 +1,20 @@
+/* LISTING — the pieces a collection of N records is drawn with: rows, columns, paging,
+   sorting, grouping. The `List` view composes them; any other component may reuse them. */
+export { defaultVisibleIds, reconcileVisible, toggleColumn, useColumnControl, visibleColumns, } from "./columns.js";
+export { ColumnsMenu, specsFromColumns, } from "./ColumnsMenu.js";
+export { Listing } from "./Listing.js";
+export { ListingBar } from "./ListingBar.js";
+export { claimedFields, columnsFromModel, readModelValue, } from "./modelColumns.js";
+export { DEFAULT_PAGE_SIZE, PAGE_SIZES, useCursorPagination, usePagination, } from "./pages.js";
+export { Pagination } from "./Pagination.js";
+export { RecordLink } from "./RecordLink.js";
+export { GroupHeader, Row } from "./Row.js";
+export { useSelection } from "./selection.js";
+export { useSetControl } from "./set.js";
+export { toggleCollapsed, useTreeControl, } from "./tree.js";
+export { ViewSwitcher, } from "./ViewSwitcher.js";
+/* El control de los niveles. El vocabulario está en `system/grouping.ts`. */
+export { useGroupingControl, } from "./grouping.js";
+export { GroupingLevels, } from "./GroupingLevels.js";
+export { RecordCard } from "./RecordCard.js";
+export { SortMenu, } from "./SortMenu.js";

package/dist/components/listing/modelColumns.d.ts

@@ -0,0 +1,50 @@
+import { type ModelDefinition } from "../search/model.js";
+import type { DataColumn } from "../../primitives/table/DataTable.js";
+/** Qué campo del modelo muestra una columna declarada a mano.
+ *
+ *  Sin esto, «filas» y `row_count` son dos cosas distintas y el campo
+ *  aparecería dos veces: una con el rótulo bueno y otra cruda. */
+export type ClaimedField = {
+    id: string;
+    field?: string;
+};
+/** Los campos que las columnas declaradas ya contestan.
+ *
+ *      in            [{id:"rows", field:"row_count"}, {id:"name"}]
+ *      out           Set {"row_count", "name"}
+ *
+ *  El `id` cuenta como reclamo cuando coincide con el nombre del campo: la
+ *  mayoría de las columnas se llaman como lo que muestran. */
+export declare function claimedFields(columns: readonly ClaimedField[]): Set<string>;
+/** Un valor del registro, en algo que una celda pueda ordenar y dibujar.
+ *
+ *      in            ["edad","sexo"]     un `text[]`
+ *      out           "edad, sexo"
+ *      in            []                  una lista vacía no es un texto vacío
+ *      out           null                la tabla dibuja «—»
+ *      in            "2026-09-13T04:17:00"
+ *      out           "2026-09-13T04:17:00"
+ *
+ *  Las fechas se dejan como vienen —ISO— porque en ISO el orden alfabético ES
+ *  el cronológico, y así la columna ordena bien sin parsear nada. */
+export declare function readModelValue(raw: unknown): string | number | boolean | null;
+/**
+ * Las columnas declaradas, más una por cada campo del modelo que ninguna
+ * contestaba.
+ *
+ *     in    model     el `model_meta_data` de `account.move` — 12 campos
+ *     in    declared  6 columnas escritas a mano en la vista
+ *     out             las 6, y detrás `journal_id`, `currency_id`, `invoice_origin`,
+ *                     `payment_reference`, `fiscal_position_id`, `company_id`,
+ *                     `move_type`, todas apagadas
+ *
+ * El rótulo de las agregadas sale de `model.translations` en el idioma pedido —el mismo
+ * `translations()` que el modelo publica para todo lo demás—, con el `default` que ese mismo
+ * modelo declaró si el idioma no está, y el nombre del campo tal cual sólo si el modelo no
+ * dijo ninguna palabra sobre él. Nunca puede desincronizarse con el motor porque sale de la
+ * MISMA respuesta que nombra el campo — a diferencia de un diccionario mantenido acá.
+ *
+ * `model === null` —todavía no llegó la definición— devuelve las declaradas sin
+ * tocar, que es exactamente lo que había antes.
+ */
+export declare function columnsFromModel<T extends object>(declared: readonly DataColumn<T>[], model: ModelDefinition | null | undefined, locale?: string): DataColumn<T>[];

package/dist/components/listing/modelColumns.js

@@ -0,0 +1,103 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { fieldLabel } from "../search/model.js";
+/** Los campos que las columnas declaradas ya contestan.
+ *
+ *      in            [{id:"rows", field:"row_count"}, {id:"name"}]
+ *      out           Set {"row_count", "name"}
+ *
+ *  El `id` cuenta como reclamo cuando coincide con el nombre del campo: la
+ *  mayoría de las columnas se llaman como lo que muestran. */
+export function claimedFields(columns) {
+    const claimed = new Set();
+    for (const column of columns) {
+        claimed.add(column.field ?? column.id);
+        if (column.field !== undefined)
+            claimed.add(column.id);
+    }
+    return claimed;
+}
+/** Un valor del registro, en algo que una celda pueda ordenar y dibujar.
+ *
+ *      in            ["edad","sexo"]     un `text[]`
+ *      out           "edad, sexo"
+ *      in            []                  una lista vacía no es un texto vacío
+ *      out           null                la tabla dibuja «—»
+ *      in            "2026-09-13T04:17:00"
+ *      out           "2026-09-13T04:17:00"
+ *
+ *  Las fechas se dejan como vienen —ISO— porque en ISO el orden alfabético ES
+ *  el cronológico, y así la columna ordena bien sin parsear nada. */
+export function readModelValue(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (Array.isArray(raw))
+        return raw.length === 0 ? null : raw.join(", ");
+    if (typeof raw === "number" || typeof raw === "boolean")
+        return raw;
+    if (typeof raw === "string")
+        return raw === "" ? null : raw;
+    return JSON.stringify(raw);
+}
+/** Cuánto ancho merece un campo, por su tipo. Una huella son 64 caracteres y
+ *  una cuenta son seis: darles el mismo ancho arruina las dos. */
+function widthFor(type) {
+    if (type === "integer" || type === "number")
+        return 120;
+    if (type === "datetime" || type === "date")
+        return 190;
+    if (type === "boolean")
+        return 90;
+    return 260;
+}
+/**
+ * Las columnas declaradas, más una por cada campo del modelo que ninguna
+ * contestaba.
+ *
+ *     in    model     el `model_meta_data` de `account.move` — 12 campos
+ *     in    declared  6 columnas escritas a mano en la vista
+ *     out             las 6, y detrás `journal_id`, `currency_id`, `invoice_origin`,
+ *                     `payment_reference`, `fiscal_position_id`, `company_id`,
+ *                     `move_type`, todas apagadas
+ *
+ * El rótulo de las agregadas sale de `model.translations` en el idioma pedido —el mismo
+ * `translations()` que el modelo publica para todo lo demás—, con el `default` que ese mismo
+ * modelo declaró si el idioma no está, y el nombre del campo tal cual sólo si el modelo no
+ * dijo ninguna palabra sobre él. Nunca puede desincronizarse con el motor porque sale de la
+ * MISMA respuesta que nombra el campo — a diferencia de un diccionario mantenido acá.
+ *
+ * `model === null` —todavía no llegó la definición— devuelve las declaradas sin
+ * tocar, que es exactamente lo que había antes.
+ */
+export function columnsFromModel(declared, model, locale = "default") {
+    if (model === null || model === undefined)
+        return [...declared];
+    const claimed = claimedFields(declared);
+    const extra = [];
+    for (const [field, definition] of Object.entries(model.fields)) {
+        if (claimed.has(field))
+            continue;
+        const numeric = definition.type === "integer" || definition.type === "number";
+        extra.push({
+            id: field,
+            field,
+            header: fieldLabel(model, field, locale),
+            value: (row) => readModelValue(row[field]),
+            /* El valor entero en el `title`: una huella de 64 caracteres no entra en
+               ninguna celda, y cortada no sirve para nada — salvo para pasar el mouse
+               por encima y leerla. */
+            cell: (row) => {
+                const value = readModelValue(row[field]);
+                if (value === null)
+                    return _jsx("span", { className: "text-subtle", children: "\u2014" });
+                const text = String(value);
+                return (_jsx("span", { className: "block truncate text-muted", title: text, children: text }));
+            },
+            ...(numeric ? { numeric: true } : {}),
+            sortable: definition.sortable,
+            optional: true,
+            defaultHidden: true,
+            width: widthFor(definition.type),
+        });
+    }
+    return [...declared, ...extra];
+}

package/dist/components/listing/pages.d.ts

@@ -0,0 +1,78 @@
+/**
+ * How many records a list shows until someone asks for another size.
+ *
+ * 80 is the product default: enough to scan a catalog without paging every
+ * twenty-five rows, still small enough that a table stays a table. 25 / 80 / 100
+ * are the presets; any other positive integer is valid and is kept.
+ */
+export declare const DEFAULT_PAGE_SIZE = 80;
+export declare const PAGE_SIZES: readonly [25, 80, 100];
+/** What `Pagination` needs, already computed from a set in memory. */
+export interface PaginationBridge {
+    from: number;
+    to: number;
+    total: number;
+    pageSize: number;
+    onPageSizeChange: (next: number) => void;
+    onPrev?: () => void;
+    onNext?: () => void;
+}
+export interface Pages<Row> {
+    pageItems: Row[];
+    bridge: PaginationBridge;
+}
+/**
+ * Cut an in-memory set into pages.
+ *
+ * `pageSize` is controlled when `onPageSizeChange` is passed — that is how a
+ * view context keeps the size across filters. Without it the hook owns the
+ * size, defaulting to 80.
+ *
+ * The current page is clamped in the calculation, not in an effect: if a
+ * filter leaves fewer pages than the current one, the next read already
+ * lands on the last page that exists.
+ */
+export declare function usePagination<Row>(items: readonly Row[], options?: {
+    pageSize?: number;
+    onPageSizeChange?: (next: number) => void;
+}): Pages<Row>;
+/** What a server answered about a page: the records, where the next one starts, how many
+ *  match in total. `exact: false` on the count means *at least* that many — a server that
+ *  stops counting at a ceiling so its cost does not grow with the table. */
+export interface ServerPage<Row> {
+    items: readonly Row[];
+    cursor: string | null;
+    count: {
+        value: number;
+        exact: boolean;
+    } | null;
+}
+/** What a cursor-paged list needs from whoever fetches it. */
+export interface CursorSource<Row> {
+    /** The page at this cursor. `undefined` asks for the first one. */
+    fetch: (cursor: string | undefined, pageSize: number) => Promise<ServerPage<Row>>;
+    /** Anything that changes WHICH records are being paged — a filter, an ordering. Pagination
+     *  starts over when this changes, because page 3 of another reading is not page 3. */
+    resetKey?: unknown;
+}
+/**
+ * Cut a *server-side* set into pages, by cursor.
+ *
+ * `usePagination` slices an array that is already in hand; this one never holds the whole set.
+ * Same `bridge`, so `Pagination` draws it identically — the difference is invisible to a view.
+ *
+ * **Going back is a walk, not a jump.** A keyset cursor names the last row seen, so it points
+ * forward and nothing points back. Rather than fake it with an offset — which would reintroduce
+ * exactly the incoherence the cursor exists to avoid — the cursors already walked are kept, and
+ * `onPrev` re-fetches with the one before. That is one request, not a re-walk from the start.
+ *
+ * **Changing the size starts over**, and that is not a limitation: a cursor belongs to the page
+ * size it was minted under, so keeping it would land somewhere nobody asked for.
+ */
+export declare function useCursorPagination<Row>(source: CursorSource<Row>, options?: {
+    pageSize?: number;
+    onPageSizeChange?: (next: number) => void;
+}): Pages<Row> & {
+    loading: boolean;
+    error: unknown;
+};

package/dist/components/listing/pages.js

@@ -0,0 +1,135 @@
+"use client";
+import { useEffect, useState } from "react";
+/**
+ * How many records a list shows until someone asks for another size.
+ *
+ * 80 is the product default: enough to scan a catalog without paging every
+ * twenty-five rows, still small enough that a table stays a table. 25 / 80 / 100
+ * are the presets; any other positive integer is valid and is kept.
+ */
+export const DEFAULT_PAGE_SIZE = 80;
+export const PAGE_SIZES = [25, 80, 100];
+function clampSize(next) {
+    if (!Number.isFinite(next))
+        return DEFAULT_PAGE_SIZE;
+    return Math.max(1, Math.floor(next));
+}
+/**
+ * Cut an in-memory set into pages.
+ *
+ * `pageSize` is controlled when `onPageSizeChange` is passed — that is how a
+ * view context keeps the size across filters. Without it the hook owns the
+ * size, defaulting to 80.
+ *
+ * The current page is clamped in the calculation, not in an effect: if a
+ * filter leaves fewer pages than the current one, the next read already
+ * lands on the last page that exists.
+ */
+export function usePagination(items, options = {}) {
+    const controlled = options.pageSize !== undefined && options.onPageSizeChange !== undefined;
+    const [ownedSize, setOwnedSize] = useState(options.pageSize ?? DEFAULT_PAGE_SIZE);
+    const [page, setPage] = useState(1);
+    const pageSize = clampSize(controlled ? (options.pageSize ?? DEFAULT_PAGE_SIZE) : ownedSize);
+    const setPageSize = controlled ? options.onPageSizeChange : setOwnedSize;
+    const total = items.length;
+    const pages = Math.max(1, Math.ceil(total / pageSize));
+    const current = Math.min(page, pages);
+    const from = total === 0 ? 0 : (current - 1) * pageSize + 1;
+    const to = Math.min(current * pageSize, total);
+    return {
+        pageItems: items.slice(from > 0 ? from - 1 : 0, to),
+        bridge: {
+            from,
+            to,
+            total,
+            pageSize,
+            onPageSizeChange: (next) => {
+                setPageSize(clampSize(next));
+                setPage(1);
+            },
+            /* Se mueve desde `current` y no desde `page`, que es el que puede haber
+               quedado alto: si estabas en la 3 y un filtro dejó dos páginas, `page`
+               sigue en 3 mientras se muestra la 2, y `p - 1` volvía a 2 — o sea que
+               «anterior» no hacía nada hasta el segundo clic. */
+            ...(current > 1 ? { onPrev: () => setPage(current - 1) } : {}),
+            ...(current < pages ? { onNext: () => setPage(current + 1) } : {}),
+        },
+    };
+}
+/**
+ * Cut a *server-side* set into pages, by cursor.
+ *
+ * `usePagination` slices an array that is already in hand; this one never holds the whole set.
+ * Same `bridge`, so `Pagination` draws it identically — the difference is invisible to a view.
+ *
+ * **Going back is a walk, not a jump.** A keyset cursor names the last row seen, so it points
+ * forward and nothing points back. Rather than fake it with an offset — which would reintroduce
+ * exactly the incoherence the cursor exists to avoid — the cursors already walked are kept, and
+ * `onPrev` re-fetches with the one before. That is one request, not a re-walk from the start.
+ *
+ * **Changing the size starts over**, and that is not a limitation: a cursor belongs to the page
+ * size it was minted under, so keeping it would land somewhere nobody asked for.
+ */
+export function useCursorPagination(source, options = {}) {
+    const controlled = options.pageSize !== undefined && options.onPageSizeChange !== undefined;
+    const [ownedSize, setOwnedSize] = useState(options.pageSize ?? DEFAULT_PAGE_SIZE);
+    const pageSize = clampSize(controlled ? options.pageSize : ownedSize);
+    /* The cursor that opened each page walked so far. `[undefined]` is the first page, which
+       opens with no cursor — so `walked.length` is the page number. */
+    const [walked, setWalked] = useState([undefined]);
+    const [page, setPage] = useState(null);
+    const [loading, setLoading] = useState(true);
+    const [error, setError] = useState(null);
+    const at = walked[walked.length - 1];
+    /* Starting over is keyed on what changes the reading — the filter, the ordering, the size.
+       Without this an `onPrev` after a filter change would re-fetch a cursor minted for the
+       previous reading, and the server would refuse it. */
+    useEffect(() => {
+        setWalked([undefined]);
+    }, [source.resetKey, pageSize]);
+    useEffect(() => {
+        let current = true;
+        setLoading(true);
+        source
+            .fetch(at, pageSize)
+            .then((answer) => {
+            if (!current)
+                return;
+            setPage(answer);
+            setError(null);
+        })
+            .catch((failure) => current && setError(failure))
+            .finally(() => current && setLoading(false));
+        return () => {
+            current = false;
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [at, pageSize, source.resetKey]);
+    const items = page?.items ?? [];
+    const total = page?.count?.value ?? items.length;
+    const from = items.length === 0 ? 0 : (walked.length - 1) * pageSize + 1;
+    const to = from === 0 ? 0 : from + items.length - 1;
+    return {
+        pageItems: [...items],
+        loading,
+        error,
+        bridge: {
+            from,
+            to,
+            total,
+            pageSize,
+            onPageSizeChange: (next) => {
+                const size = clampSize(next);
+                if (controlled)
+                    options.onPageSizeChange(size);
+                else
+                    setOwnedSize(size);
+                setWalked([undefined]);
+            },
+            ...(walked.length > 1 ? { onPrev: () => setWalked((so) => so.slice(0, -1)) } : {}),
+            ...(page?.cursor != null
+                ? { onNext: () => setWalked((so) => [...so, page.cursor ?? undefined]) }
+                : {}),
+        },
+    };
+}

package/dist/components/listing/selection.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Choosing rows of a SET. Lives next to pagination because both are how N
+ * records are controlled, not how they are drawn.
+ *
+ * «All» means the ones ON SCREEN: with a filter on, select-all cannot take
+ * what the filter hid. Chosen ids survive filtering — the Set stores ids,
+ * not positions — so you can choose, filter again, choose more, and act on
+ * both batches.
+ */
+export interface Selection {
+    chosen: ReadonlySet<string>;
+    count: number;
+    has: (id: string) => boolean;
+    toggle: (id: string) => void;
+    toggleAll: () => void;
+    /** `true` all, `false` none, `"some"` part — the third state is the half
+     *  checkbox, and without it the header lies when three of ten are chosen. */
+    allState: boolean | "some";
+    clear: () => void;
+}
+export declare function useSelection(visible: readonly string[]): Selection;