@sincpro/web-ui 0.0.0-stage → 0.1.0

package/dist/components/listing/SortMenu.js

@@ -0,0 +1,105 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { Menu } from "../../primitives/menu/Menu.js";
+import { ArrowDownUp, ArrowDownWideNarrow, ArrowUpNarrowWide } from "lucide-react";
+/**
+ * Las filas, ordenadas acá.
+ *
+ * Sólo cuando el campo activo declara `value`; si no, se devuelven tal cual —
+ * ordenar una página de un conjunto que se pagina afuera produce un orden que es
+ * mentira, porque ordena las doce que llegaron y no las ciento ochenta y siete.
+ *
+ * Los faltantes van SIEMPRE al final, suba o baje el orden. Es lo que hace
+ * cualquier planilla, y la razón es que un vacío no es «el más chico»: es la
+ * ausencia de respuesta, y ponerlo primero al invertir el orden llena la primera
+ * pantalla con las filas que menos dicen.
+ */
+export function sortItems(items, fields, sort) {
+    if (sort === null || sort === undefined)
+        return items;
+    const field = fields.find((one) => one.field === sort.key);
+    if (field?.value === undefined)
+        return items;
+    const read = field.value;
+    const sign = sort.direction === "asc" ? 1 : -1;
+    return [...items].sort((a, b) => {
+        const left = read(a);
+        const right = read(b);
+        const leftMissing = left === null || left === undefined || left === "";
+        const rightMissing = right === null || right === undefined || right === "";
+        if (leftMissing && rightMissing)
+            return 0;
+        if (leftMissing)
+            return 1;
+        if (rightMissing)
+            return -1;
+        if (typeof left === "number" && typeof right === "number")
+            return (left - right) * sign;
+        return String(left).localeCompare(String(right)) * sign;
+    });
+}
+export function SortMenu({ fields, sort, onSortChange, surface }) {
+    const copy = useUiCopy();
+    if (fields.length === 0)
+        return null;
+    const current = fields.find((one) => one.field === sort?.key);
+    const groups = [
+        {
+            label: copy.sorting.by,
+            options: fields.map((one) => ({
+                id: one.field,
+                label: one.label,
+                checked: one.field === sort?.key,
+            })),
+        },
+        /* La dirección sólo cuando hay algo ordenado: «descendente» sin campo no
+           ordena nada, y una opción que no hace nada es una opción que se prueba. */
+        ...(current === undefined
+            ? []
+            : [
+                {
+                    options: [
+                        {
+                            id: "__asc__",
+                            label: current.ascLabel ?? copy.sorting.asc,
+                            icon: ArrowUpNarrowWide,
+                            checked: sort?.direction === "asc",
+                        },
+                        {
+                            id: "__desc__",
+                            label: current.descLabel ?? copy.sorting.desc,
+                            icon: ArrowDownWideNarrow,
+                            checked: sort?.direction === "desc",
+                        },
+                    ],
+                },
+                { options: [{ id: "__none__", label: copy.sorting.clear }] },
+            ]),
+    ];
+    return (_jsx(Menu, { label: current === undefined ? copy.sorting.label : current.label, icon: sort === null || sort === undefined
+            ? ArrowDownUp
+            : sort.direction === "asc"
+                ? ArrowUpNarrowWide
+                : ArrowDownWideNarrow, groups: groups, active: sort !== null && sort !== undefined, size: "sm", width: "sm", closeOnSelect: false, ...(surface === undefined ? {} : { surface }), onSelect: (id) => {
+            if (id === "__none__")
+                return onSortChange(null);
+            if (id === "__asc__") {
+                return onSortChange(sort === null ? null : { ...sort, direction: "asc" });
+            }
+            if (id === "__desc__") {
+                return onSortChange(sort === null ? null : { ...sort, direction: "desc" });
+            }
+            /* Volver a elegir el campo que ya está puesto DA VUELTA la dirección, que
+               es lo que hace el clic en un encabezado. Sin eso, invertir el orden son
+               dos gestos en un menú y uno en la tabla — la misma capacidad costando
+               distinto según la presentación. */
+            if (sort?.key === id) {
+                return onSortChange({
+                    key: id,
+                    direction: sort.direction === "asc" ? "desc" : "asc",
+                });
+            }
+            onSortChange({ key: id, direction: "asc" });
+        } }));
+}

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

@@ -0,0 +1,24 @@
+import type { Surface } from "../../foundations/types.js";
+import type { LucideIcon } from "lucide-react";
+/** How the same list is shown: table, board, timeline.
+ *
+ *  The icons go together and touching —a segmented group and not three loose
+ *  buttons— because they are MUTUALLY EXCLUSIVE options of a single question.
+ *  Three separate buttons read as three different actions, and then it is not
+ *  understood that choosing one turns the other off.
+ *
+ *  The label goes in the `title` and in the `aria-label`, never drawn: they are
+ *  three silhouettes that are learned once and recognized afterwards without
+ *  reading, and writing them out would burn the width the search box needs. */
+export interface ViewOption {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+}
+export declare function ViewSwitcher({ options, current, onSelect, surface, }: {
+    options: readonly ViewOption[];
+    current: string;
+    onSelect?: (id: string) => void;
+    /** By default it inherits it from the surface that wraps it. */
+    surface?: Surface;
+}): import("react").JSX.Element;

package/dist/components/listing/ViewSwitcher.js

@@ -0,0 +1,16 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { bySurface, useSurface } from "../../foundations/surface.js";
+export function ViewSwitcher({ options, current, onSelect, surface, }) {
+    const activeSurface = useSurface(surface);
+    const copy = useUiCopy();
+    const rule = bySurface(activeSurface, "border-line-strong", "border-chrome-ink/45");
+    return (_jsx("div", { role: "group", "aria-label": copy.present.group, className: `flex shrink-0 items-center overflow-hidden rounded-control border ${rule}`, children: options.map((o, i) => {
+            const here = o.id === current;
+            const Icon = o.icon;
+            return (_jsx("button", { type: "button", onClick: () => onSelect?.(o.id), "aria-pressed": here, title: o.label, "aria-label": o.label, className: `inline-flex size-(--size-control-sm) items-center justify-center transition-colors duration-(--duration-instant) focus-visible:outline-2 focus-visible:-outline-offset-1 focus-visible:outline-primary ${i === 0 ? "" : `border-l ${rule}`} ${here
+                    ? bySurface(activeSurface, "bg-ink/8 text-ink", "bg-chrome-link/20 text-chrome-link")
+                    : bySurface(activeSurface, "bg-surface text-muted hover:bg-ink/5 hover:text-ink", "bg-chrome-ink/6 text-chrome-muted hover:bg-chrome-ink/14 hover:text-chrome-ink")}`, children: _jsx(Icon, { className: "size-(--size-icon-md)", strokeWidth: 1.75 }) }, o.id));
+        }) }));
+}

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;
+};