@sincpro/web-ui 0.0.0-stage → 0.1.0

package/dist/views/list/derive.js

@@ -0,0 +1,181 @@
+import { levelKey, pathKey, pileItems, pileLabel, } from "../../foundations/grouping.js";
+import { aggregateOf } from "../../primitives/table/DataTable.js";
+/**
+ * Context: what a list DERIVES from its set, as pure functions — the table's group levels,
+ * the sheet drawn from the declared columns, the sheet's flattened band/row sequence and
+ * the report built from the piles. `ListView` calls them inside `useMemo` with the same
+ * dependencies they always had; nothing here knows React.
+ */
+/**
+ * Los niveles, como los necesita la tabla: uno por NIVEL y no uno por campo.
+ *
+ * La clave sale de `group.of` —la misma que arman las otras cinco
+ * presentaciones— así que los montones de la tabla son los mismos y lo plegado
+ * vale para todas. El rótulo sale de la misma regla que el árbol: un nivel no
+ * repite lo que el de arriba, del mismo campo, ya dijo.
+ */
+export function groupLevelsOf(group, columns) {
+    if (group === undefined || group.levels.length === 0)
+        return [];
+    const above = [];
+    const label = group.label ?? pileLabel;
+    return group.levels.map((level) => {
+        const within = above.flatMap((one) => one.field === level.field && one.grain !== undefined ? [one.grain] : []);
+        above.push(level);
+        /* Cómo se llama el corte: como lo llama la columna que contesta por ese
+           campo, que es el único rótulo humano que esta capa tiene. */
+        const column = columns?.find((one) => one.id === level.field || one.field === level.field);
+        return {
+            id: levelKey(level),
+            label: column?.header ?? level.field,
+            keyOf: (item) => group.of(item, level),
+            labelOf: (key) => label(key, level, within),
+        };
+    });
+}
+/**
+ * La planilla de un conjunto de REGISTROS sale de las columnas que la lista
+ * ya declaró. Sin esto, ofrecer `sheet` obligaba a escribir las columnas dos
+ * veces —una como `DataColumn` y otra como `SheetColumn`— y entonces nadie la
+ * ofrecía: la presentación existía en el arquetipo y no estaba en ninguna
+ * pantalla.
+ *
+ * `sheet` explícita sigue siendo para los DATOS CRUDOS, donde las columnas
+ * salen del archivo y el código no sabe cuáles son.
+ */
+export function sheetFromColumns(shownColumns) {
+    if (shownColumns === undefined || shownColumns.length === 0)
+        return undefined;
+    const byId = new Map(shownColumns.map((column) => [column.id, column]));
+    return {
+        columns: shownColumns.map((column) => ({
+            id: column.id,
+            header: column.header,
+            ...(column.numeric === true ? { numeric: true } : {}),
+            ...(column.width === undefined ? {} : { width: column.width }),
+        })),
+        cell: (item, column) => {
+            const declared = byId.get(column.id);
+            /* `text` primero: `value` es la clave de ORDEN, no lo que se lee. Sin
+               esto la planilla mostraba `computed` donde la tabla muestra
+               «calculado». */
+            if (declared?.text !== undefined)
+                return declared.text(item);
+            const raw = declared?.value(item);
+            /* Un booleano no es una celda: la cuadrícula dibuja texto o número, y
+               `false` se vería como una celda vacía, que significa otra cosa. */
+            return typeof raw === "boolean" ? String(raw) : (raw ?? null);
+        },
+        tone: (item, column) => byId.get(column.id)?.tone?.(item),
+        note: (item, column) => byId.get(column.id)?.note?.(item),
+        /* Crece con la página en vez de abrir una caja con scroll adentro de otra
+           que ya scrollea. La lista ya vino paginada, así que son ochenta filas y
+           no ciento ochenta y siete — el caso de un millón es el de los datos
+           crudos, y ése declara su propio alto. */
+        height: "auto",
+    };
+}
+/**
+ * La planilla, cuando hay montones: una SECUENCIA donde cada índice es una
+ * fila o la cabecera del montón que empieza ahí.
+ *
+ * **Acá decía que la planilla no agrupa y estaba mal razonado.** El argumento
+ * —una banda corre la cuadrícula y mirar datos crudos es seguir una fila a lo
+ * ancho— vale para los datos crudos, donde las columnas salen del archivo y
+ * no hay ningún eje del dominio por el que agrupar. Pero la planilla DERIVADA
+ * es el mismo conjunto de registros que la tabla, con los mismos ejes: que
+ * agrupe la tabla y no ella es exactamente el drift que este arquetipo existe
+ * para impedir — cambiar de presentación perdía la agrupación.
+ *
+ * La regla queda en manos de la vista, como corresponde: si declara `group`,
+ * agrupa; si no, no hay montones que dibujar.
+ */
+export function sheetRowsOf(piles, isOpen, columns) {
+    if (piles === null)
+        return null;
+    const out = [];
+    let n = 0;
+    /* Aplanar es recursivo porque el árbol lo es. La planilla no puede recibir
+       el árbol: está virtualizada por índice, y un índice es una posición en una
+       secuencia — así que la jerarquía se expresa en la sangría de cada banda. */
+    const walk = (list) => {
+        for (const pile of list) {
+            const open = isOpen(pile);
+            const inside = pile.piles.length === 0 ? pile.items : pileItems(pile.piles);
+            out.push({
+                band: {
+                    field: pile.field,
+                    label: pile.label,
+                    count: pile.count,
+                    open,
+                    key: pathKey(pile.path),
+                    depth: pile.depth,
+                    /* El total de cada columna, en la posición de esa columna. Sale de
+                       las `columns` de la lista —las mismas que suma el pie de la
+                       tabla— para que la planilla y la tabla no digan números distintos
+                       del mismo montón. La planilla declara SUS columnas aparte, así que
+                       se busca por id. */
+                    total: (column) => {
+                        const declared = columns?.find((one) => one.id === column.id);
+                        return declared === undefined ? null : aggregateOf(declared, inside);
+                    },
+                },
+            });
+            if (!open)
+                continue;
+            if (pile.piles.length > 0) {
+                walk(pile.piles);
+                continue;
+            }
+            for (const one of pile.items) {
+                n += 1;
+                out.push({ item: one, n });
+            }
+        }
+    };
+    walk(piles);
+    return out;
+}
+/**
+ * El informe armado a partir de los montones, cuando el dominio no declaró
+ * líneas.
+ *
+ * Cada montón es una línea con los agregados de las columnas que declararon
+ * uno, y el nivel más profundo cuelga sus filas. Las columnas del informe las
+ * pone `report.columns`; los números salen de las `columns` de la lista, que
+ * son las mismas que suma el pie de la tabla — para que el informe y la tabla
+ * no digan totales distintos del mismo conjunto.
+ */
+export function reportRowsOf(piles, columns, row) {
+    if (piles === null || columns === undefined)
+        return [];
+    const numeric = columns.filter((column) => column.aggregate !== undefined);
+    /* A pile is named by the HEADER of the column that answers for its field — the word the
+       person reads in the table — not by the field's id: «stage · pedido» showed the
+       model's name for it. */
+    const fieldName = (field) => columns.find((column) => column.id === field || column.field === field)?.header ?? field;
+    const line = (pile) => {
+        const inside = pile.piles.length === 0 ? pile.items : pileItems(pile.piles);
+        const children = pile.piles.length > 0
+            ? pile.piles.map(line)
+            : pile.items.map((item, index) => ({
+                id: `${pathKey(pile.path)}\u0000${index}`,
+                label: row(item).name,
+                kind: "line",
+                level: pile.depth + 1,
+                values: numeric.map((column) => {
+                    const value = column.value(item);
+                    return typeof value === "number" ? value : null;
+                }),
+            }));
+        return {
+            id: pathKey(pile.path),
+            label: `${fieldName(pile.field)} · ${pile.label}`,
+            kind: pile.depth === 0 ? "section" : "group",
+            level: pile.depth,
+            values: numeric.map((column) => aggregateOf(column, inside)),
+            children,
+        };
+    };
+    return piles.map(line);
+}

package/dist/views/list/index.d.ts

@@ -0,0 +1,2 @@
+export { List, type ListProps } from "./List.js";
+export { type ListCrumb, type ListEmpty, type ListGroup, type ListPivot, type ListPresent, type ListReport, type ListSheet, type RowOf, } from "./types.js";

package/dist/views/list/index.js

@@ -0,0 +1,4 @@
+/* LISTA — N registros. `List` se escribe como ÁRBOL: las caras que ofrece son las que
+   están escritas adentro. `ListView` es el DIBUJO que hay detrás y no se publica. */
+export { List } from "./List.js";
+export {} from "./types.js";

package/dist/views/list/presentations.d.ts

@@ -0,0 +1,39 @@
+import { type DataColumn, DataTable } from "../../primitives/table/DataTable.js";
+import type { SheetEntry } from "./derive.js";
+import type { ListGroup, ListSheet, ListViewProps } from "./types.js";
+/**
+ * Context: the two presentations whose body is an adapter between the list's vocabulary
+ * (one selection that speaks one id at a time, a grouping tree, an index-addressed sequence)
+ * and a primitive's (a Set, levels, indexes). They draw nothing of their own — they are
+ * `ListView`'s `table` and `sheet` branches, moved out so that file reads as the decision of
+ * WHICH presentation, and these as HOW the two grids are fed.
+ */
+type TableProps<T extends object> = {
+    items: readonly T[];
+    columns: readonly DataColumn<T>[];
+    keyOf: (item: T) => string;
+    levels: NonNullable<Parameters<typeof DataTable<T>>[0]["levels"]>;
+    group?: ListGroup<T>;
+    totals: boolean;
+} & Pick<ListViewProps<T>, "sort" | "onSortChange" | "selection" | "rowActions" | "onPeek" | "onOpen">;
+/** The table receives EVERYTHING that belongs to the set —sorting, selection, grouping,
+ *  which columns are on screen— and not a trimmed down version: that was exactly the trap
+ *  this archetype exists to avoid, that switching presentation loses capabilities. */
+export declare function TablePresentation<T extends object>({ items, columns, keyOf, levels, group, totals, sort, onSortChange, selection, rowActions, onPeek, onOpen, }: TableProps<T>): import("react").JSX.Element;
+type SheetProps<T extends object> = {
+    spec: ListSheet<T>;
+    /** The flattened bands and rows when the set is grouped; `null` when it is not. */
+    entries: readonly SheetEntry<T>[] | null;
+    ordered: readonly T[];
+    group?: ListGroup<T>;
+};
+/** The sheet receives the set by INDEX and not a ready-made matrix: `SheetTable` is
+ *  virtualized precisely so as not to materialize a million rows, and handing it copies
+ *  would throw that away.
+ *
+ *  It groups like the other three —grouping belongs to the SET, not to the presentation—
+ *  and the piles enter as rows of another kind, so virtualization is not lost. What it still
+ *  lacks is selection: a checkbox per row in a forty-column grid competes with the frozen
+ *  row-number column, the one that lets you know which row you are on. */
+export declare function SheetPresentation<T extends object>({ spec, entries, ordered, group, }: SheetProps<T>): import("react").JSX.Element;
+export {};

package/dist/views/list/presentations.js

@@ -0,0 +1,103 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUiCopy } from "../../foundations/copy.js";
+import { DataTable } from "../../primitives/table/DataTable.js";
+import { SheetTable } from "../../primitives/table/SheetTable.js";
+/** The table receives EVERYTHING that belongs to the set —sorting, selection, grouping,
+ *  which columns are on screen— and not a trimmed down version: that was exactly the trap
+ *  this archetype exists to avoid, that switching presentation loses capabilities. */
+export function TablePresentation({ items, columns, keyOf, levels, group, totals, sort, onSortChange, selection, rowActions, onPeek, onOpen, }) {
+    return (_jsx(DataTable, { data: items, columns: columns, getRowId: keyOf, ...(sort === undefined ? {} : { sort }), ...(onSortChange === undefined ? {} : { onSortChange }), ...(levels.length === 0 ? {} : { levels: levels }), ...(group?.collapsed === undefined ? {} : { collapsed: group.collapsed }), ...(group?.onToggle === undefined ? {} : { onGroupToggle: group.onToggle }), ...(selection === undefined
+            ? {}
+            : {
+                selected: new Set(items.filter((i) => selection.has(keyOf(i))).map(keyOf)),
+                onSelectedChange: (next) => {
+                    /* `DataTable` sends the whole set; the view's selection speaks
+                       one at a time. It is translated here and not there because the
+                       one who knows what changed is the one holding the before and
+                       the after. */
+                    for (const item of items) {
+                        const id = keyOf(item);
+                        if (next.has(id) !== selection.has(id))
+                            selection.toggle(id);
+                    }
+                },
+            }), ...(totals ? { totals: true } : {}), ...(rowActions === undefined ? {} : { rowActions }), ...((onPeek ?? onOpen) === undefined ? {} : { onRowClick: onPeek ?? onOpen }) }));
+}
+/** The sheet receives the set by INDEX and not a ready-made matrix: `SheetTable` is
+ *  virtualized precisely so as not to materialize a million rows, and handing it copies
+ *  would throw that away.
+ *
+ *  It groups like the other three —grouping belongs to the SET, not to the presentation—
+ *  and the piles enter as rows of another kind, so virtualization is not lost. What it still
+ *  lacks is selection: a checkbox per row in a forty-column grid competes with the frozen
+ *  row-number column, the one that lets you know which row you are on. */
+export function SheetPresentation({ spec, entries, ordered, group, }) {
+    const copy = useUiCopy();
+    /** Qué ítem hay en este índice de la planilla. Con montones, un índice puede
+     *  ser una banda y no una fila — y entonces no hay ítem. Una sola vez, porque
+     *  las seis funciones que la planilla recibe hacen la misma pregunta. */
+    const sheetItemAt = (index) => entries === null ? ordered[index] : entries[index]?.item;
+    return (_jsx(SheetTable, { columns: spec.columns, rows: entries === null ? ordered.length : entries.length, value: (index, column, columnIndex) => {
+            const item = sheetItemAt(index);
+            return item === undefined ? null : spec.cell(item, column, columnIndex);
+        }, ...(entries === null
+            ? {}
+            : {
+                band: (index) => entries[index]?.band,
+                ...(group?.onToggle === undefined
+                    ? {}
+                    : {
+                        onBandToggle: (index) => {
+                            const key = entries[index]?.band?.key;
+                            if (key !== undefined)
+                                group.onToggle?.(key);
+                        },
+                    }),
+            }), ...(spec.tone === undefined
+            ? {}
+            : {
+                tone: (index, column, columnIndex) => {
+                    const item = sheetItemAt(index);
+                    return item === undefined ? undefined : spec.tone?.(item, column, columnIndex);
+                },
+            }), ...(spec.note === undefined
+            ? {}
+            : {
+                note: (index, column, columnIndex) => {
+                    const item = sheetItemAt(index);
+                    return item === undefined ? undefined : spec.note?.(item, column, columnIndex);
+                },
+            }), ...(spec.height === undefined ? {} : { height: spec.height }), ...(spec.rowLabel !== undefined
+            ? {
+                rowLabel: (index) => {
+                    const item = sheetItemAt(index);
+                    return item === undefined ? "" : (spec.rowLabel?.(item, index) ?? "");
+                },
+            }
+            : entries === null
+                ? {}
+                : {
+                    rowLabel: (index) => {
+                        const n = entries[index]?.n;
+                        return n === undefined ? "" : n.toLocaleString(copy.locale);
+                    },
+                }), ...(spec.onCommit === undefined
+            ? {}
+            : {
+                onCommit: (index, column, columnIndex, next) => {
+                    const item = sheetItemAt(index);
+                    if (item !== undefined)
+                        spec.onCommit?.(item, column, columnIndex, next);
+                },
+            }), ...(spec.editable === undefined
+            ? {}
+            : {
+                editable: (index, column, columnIndex) => {
+                    const item = sheetItemAt(index);
+                    return item === undefined
+                        ? false
+                        : (spec.editable?.(item, column, columnIndex) ?? false);
+                },
+            }) }));
+}

package/dist/views/list/types.d.ts

@@ -0,0 +1,272 @@
+import type { ListIdentity } from "../../components/listing/ListingBar.js";
+import type { ListPresent } from "../../components/listing/set.js";
+import type { SortField } from "../../components/listing/SortMenu.js";
+import type { Grouping, GroupLevel } from "../../foundations/grouping.js";
+import type { Pivot, PivotKey, PivotSpec } from "../../foundations/pivot.js";
+import type { Surface, Tone } from "../../foundations/types.js";
+import type { DataColumn } from "../../primitives/table/DataTable.js";
+import type { ReportColumn, ReportRow } from "../../primitives/table/ReportTable.js";
+import type { RowAction } from "../../primitives/table/RowActions.js";
+import type { SheetColumn } from "../../primitives/table/SheetTable.js";
+import type { SortState } from "../../primitives/table/Table.js";
+import type { LucideIcon } from "lucide-react";
+import type { ReactNode } from "react";
+/**
+ * Las seis maneras de mirar un conjunto. La unión vive en `list/set.ts`, que
+ * es donde ya vivía su copia.
+ *
+ * Las seis son el MISMO conjunto mirado distinto, y por eso comparten barra.
+ * Lo que cambia entre ellas es qué sabe el código de las columnas — y, en el
+ * pivote, que las filas de la pantalla ya no son las filas del conjunto.
+ */
+export type { ListPresent };
+/** What an item looks like when the presentation is rows. */
+export type RowOf = {
+    icon?: LucideIcon;
+    name: string;
+    tags?: ReactNode;
+    meta?: string;
+    /** What this resource produced, hanging underneath. */
+    children?: ReactNode;
+    actions?: ReactNode;
+};
+/** A crumb of the list: where I came from. */
+export type ListCrumb = {
+    label: string;
+    onClick?: () => void;
+};
+export type ListEmpty = {
+    sentence: string;
+    action?: ReactNode;
+    /** Empty because of a filter is ANOTHER situation: content is not missing,
+     *  there is an extra narrowing. Telling «importá tus facturas» to someone who has 180
+     *  and mistyped a name is answering a different question. */
+    whenFiltered?: {
+        sentence: string;
+        action?: ReactNode;
+    };
+};
+/**
+ * El agrupado de una lista: el CONTRATO de `system/grouping.ts` más lo único que
+ * una tabla necesita de más.
+ *
+ * Las seis presentaciones parten el conjunto con el MISMO árbol y las mismas
+ * claves — la tabla incluida. Lo único que una tabla agrega es una pregunta de
+ * VISIBILIDAD: agrupar por un campo cuya columna está escondida dejaría montones
+ * cuyo criterio no se ve en ninguna parte, así que esa columna se repone, y para
+ * reponerla hay que saber cuál es. Eso es `columnOf`, y nada más: la clave del
+ * montón no sale de una columna.
+ *
+ * Va acá y no en el contrato para que una vista que no tenga columnas no tenga
+ * que fingir que las tiene.
+ */
+export type ListGroup<T extends object> = Grouping<T> & {
+    /** Qué COLUMNA contesta por cada nivel, para reponerla cuando está escondida.
+     *  Sin esto, la que se llame como el campo o la que lo declare en `field`. */
+    columnOf?: (level: GroupLevel) => string | undefined;
+};
+/**
+ * La PLANILLA de una lista: las columnas y cómo se lee cada celda.
+ *
+ * Se declara cuando las columnas salen del ARCHIVO y el código no sabe cuáles
+ * son. Para un conjunto de registros no hace falta: sale de las `columns` que
+ * la lista ya declaró.
+ */
+export type ListSheet<T> = {
+    columns: readonly SheetColumn[];
+    /** El valor de una celda. `null` es un faltante y `""` una celda vacía: son
+     *  cosas distintas y el motor las distingue, así que la interfaz también. */
+    cell: (item: T, column: SheetColumn, columnIndex: number) => string | number | null;
+    /** Qué celdas se pintan y con qué: un valor imputado, uno fuera de rango. */
+    tone?: (item: T, column: SheetColumn, columnIndex: number) => Tone | undefined;
+    note?: (item: T, column: SheetColumn, columnIndex: number) => string | undefined;
+    height?: number | "auto";
+    /** Qué dice la columna fija de la izquierda. Sin esto, el número de fila. */
+    rowLabel?: (item: T, index: number) => string;
+    /** Presente = la planilla se edita como planilla. Recibe el texto crudo;
+     *  convertirlo al tipo de la columna es del dominio, no de acá. */
+    onCommit?: (item: T, column: SheetColumn, columnIndex: number, next: string) => void;
+    editable?: (item: T, column: SheetColumn, columnIndex: number) => boolean;
+};
+/**
+ * El INFORME de una lista: los períodos y la jerarquía que termina en totales.
+ *
+ * Las filas van aparte de `items` y es deliberado: un balance no es la lista
+ * plana agrupada —«Total Activos» es una suma de sumas— y el arquetipo no puede
+ * inventar esa jerarquía. La arma quien conoce el dominio, como ya arma
+ * `columns`.
+ */
+export type ListReport = {
+    columns: readonly ReportColumn[];
+    /**
+     * Las líneas del informe, cuando el DOMINIO las arma.
+     *
+     * Un balance no es la lista plana agrupada —«Total Activos» es una suma de
+     * sumas— y el arquetipo no puede inventar esa jerarquía.
+     *
+     * **Sin esto, el informe se arma con los montones**: cada nivel es una línea
+     * con sus agregados, y el más profundo son las filas. Es el mismo conjunto que
+     * ven las otras cuatro presentaciones, contado — que es lo que alguien espera
+     * al pasar de «tabla» a «informe» con dos niveles puestos.
+     */
+    rows?: readonly ReportRow[];
+    /** Qué grupos arrancan abiertos. Por omisión ninguno: un balance con todo
+     *  desplegado son cuatrocientas líneas y lo que se mira primero son los
+     *  totales. */
+    defaultOpen?: readonly string[];
+    height?: number;
+};
+/**
+ * El PIVOTE de una lista: los dos ejes y las medidas que se pliegan en el cruce.
+ *
+ * Es la presentación en la que **las filas de la pantalla dejan de ser los
+ * registros**: una fila es un montón y una columna también, así que no hay nada
+ * que elegir ni que abrir, y lo que se lee está en el cruce.
+ *
+ * De ahí que venga plegado de dos lugares posibles, igual que los montones de
+ * una lista agrupada:
+ *
+ *     folded   lo plegó quien guarda los datos. Es el caso normal en cuanto el
+ *              conjunto no entra en el navegador: contar 187 vencidas no lo
+ *              pueden contestar las doce filas que se bajaron.
+ *     spec     lo pliega esta máquina, con las filas en la mano.
+ *
+ * Los dos dibujan igual porque dibujan el mismo tipo.
+ */
+export type ListPivot<T> = {
+    /** El pivote ya plegado. Gana sobre `spec` cuando están los dos: si alguien
+     *  con el conjunto entero ya contestó, no hay nada que recalcular. */
+    folded?: Pivot;
+    /**
+     * Cómo armarlo acá adentro. Las medidas traen su pliegue, y los márgenes salen
+     * de la BASE y no de sumar celdas — ver `system/pivot.ts`.
+     *
+     * Quien además necesite la grilla EN LA MANO —para bajarla como planilla con
+     * `downloadPivot`, por ejemplo— la pliega él con `pivotFrom` y la pasa por
+     * `folded`: así la que se dibuja y la que se baja son el mismo objeto, y no
+     * dos que podrían no coincidir.
+     */
+    spec?: PivotSpec<T>;
+    /** Qué pasa al tocar un cruce: abrir las filas que cayeron ahí. */
+    onCell?: (row: PivotKey, column: PivotKey) => void;
+    height?: number | string;
+};
+export type ListViewProps<T extends object> = {
+    items: readonly T[];
+    keyOf: (item: T) => string;
+    identity?: ListIdentity;
+    /** Where I came from. It goes above the bar, and only when the bar is chrome. */
+    crumbs?: readonly ListCrumb[];
+    /** The metrics that also NARROW: «2 por confirmar», «41 por entregar». They go
+     *  below the bar and above the rows — they belong to the set, not to the frame. */
+    metrics?: ReactNode;
+    /** Which surface the BAR sits on. `canvas` (the default) is a light control bar;
+     *  `chrome` turns it into a dark band — an explicit choice, since the application bar
+     *  is the screen's one dark band (same as the rail of a record). */
+    surface?: Surface;
+    /** The search field, already assembled. It is assembled by whoever holds the
+     *  domain declarations — the system does not know what a provenance is. */
+    search?: ReactNode;
+    pagination?: ReactNode;
+    /** Escape hatch: a custom switcher. Prefer `presents` so the archetype draws it. */
+    views?: ReactNode;
+    actions?: ReactNode;
+    row: (item: T) => RowOf;
+    /**
+     * Los rótulos de las zonas de una fila, arriba de todas. Sin esto no hay
+     * encabezado: `rows` no es una tabla y no toda lista tiene algo que rotular
+     * —una lista de cinco archivos con el nombre y nada más no lo necesita.
+     *
+     * No son columnas. Una fila tiene un nombre, UNA cadena de `meta` ya
+     * formateada y una columna de fichas: eso es lo que se rotula, y por eso los
+     * rótulos los escribe la vista y no salen de `columns`.
+     */
+    rowHeader?: {
+        name: string;
+        meta?: string;
+        tags?: string;
+    };
+    /** The table presentation. With this, `present="table"` draws a `DataTable`. */
+    columns?: readonly DataColumn<T>[];
+    /** Which table columns are on screen. Required columns stay even if omitted.
+     *  Owned by the view when omitted — catalog filters must not reset them. */
+    visibleColumnIds?: readonly string[];
+    onVisibleColumnIdsChange?: (ids: readonly string[]) => void;
+    /** The sorting of the table. It lives outside because it belongs to the SET
+     *  and not to the presentation: switching from table to rows has no reason to
+     *  lose it. */
+    sort?: SortState | null;
+    onSortChange?: (next: SortState | null) => void;
+    /**
+     * Por qué campos se puede ordenar, para las presentaciones que NO tienen
+     * encabezados donde hacer clic.
+     *
+     * Sin esto, ordenar existe sólo en la tabla — y entonces pasar a filas o a
+     * tablero no pierde el orden puesto, pierde la posibilidad de ordenar. La
+     * tabla sigue teniendo además sus encabezados: son dos puertas a lo mismo, y
+     * la de los encabezados es más rápida donde existe.
+     */
+    sortable?: readonly SortField<T>[];
+    /** The footer with the aggregates of the columns that declared one. */
+    totals?: boolean;
+    /** What gets done to ONE row without entering it, in the table presentation.
+     *  They are drawn hidden and appear on the row being pointed at. */
+    rowActions?: (item: T) => readonly RowAction[];
+    /** The board presentation. */
+    card?: (item: T) => ReactNode;
+    /**
+     * La PLANILLA. Con esto, `present="sheet"` dibuja un `SheetTable`.
+     *
+     * Es la presentación de los datos crudos, y por eso no recibe `DataColumn`:
+     * las columnas salen del archivo y el código no sabe cuáles son ni cuántas.
+     * El valor se pide por índice —igual que `SheetTable`, que está virtualizado—
+     * así que un millón de filas no se copia a ninguna otra estructura.
+     */
+    sheet?: ListSheet<T>;
+    /**
+     * El INFORME: una jerarquía que termina en totales. Con esto,
+     * `present="report"` dibuja un `ReportTable`.
+     *
+     * Las filas van aparte de `items` y es deliberado: un balance NO es la lista
+     * plana agrupada —«Total Activos» no es un montón de cuentas, es una suma de
+     * sumas— y el arquetipo no puede inventar esa jerarquía a partir del
+     * conjunto. La arma quien conoce el dominio, como ya arma `columns`.
+     */
+    report?: ListReport;
+    /**
+     * El PIVOTE: dos ejes a la vez. Con esto, `present="pivot"` dibuja un
+     * `PivotTable`.
+     *
+     * Va aparte de `group` y no derivado de él aunque los dos partan el conjunto,
+     * porque un pivote parte por DOS ejes y una lista agrupada por uno: los
+     * niveles de `group` no dicen cuál de ellos sería el eje horizontal, y
+     * elegirlo acá sería adivinar la pregunta.
+     */
+    pivot?: ListPivot<T>;
+    present?: ListPresent;
+    /** Which presentations this list offers. Two or more draw the switcher. */
+    presents?: readonly ListPresent[];
+    onPresentChange?: (next: ListPresent) => void;
+    group?: ListGroup<T>;
+    selection?: {
+        has: (id: string) => boolean;
+        toggle: (id: string) => void;
+        count: number;
+        clear: () => void;
+        actions?: ReactNode;
+    };
+    onOpen?: (item: T) => void;
+    onPeek?: (item: T) => void;
+    isPeeked?: (item: T) => boolean;
+    /** The three states, in a single place. Every view used to re-assemble them
+     *  with three nested ternaries, and that is why «empty because of a filter»
+     *  and «really empty» got mixed up in half the screens. */
+    state?: {
+        loading?: boolean;
+        error?: string | null;
+    };
+    filtered?: boolean;
+    empty?: ListEmpty;
+    /** The escape hatch. */
+    children?: ReactNode;
+};

package/dist/views/list/types.js

@@ -0,0 +1 @@
+export {};

package/dist/views/list/useNarrowList.d.ts

@@ -0,0 +1,17 @@
+import type { ListPresent } from "../../components/listing/set.js";
+import { type RefObject } from "react";
+/**
+ * A narrow LIST — a phone, a drawer, a panel among four — does not offer the presentations
+ * that need width: a seven-column table at 360 px is a horizontal scroll nobody reads.
+ * There the list shows rows (a stacked card per record: the name, its state, its facts)
+ * and the board, and the switcher offers only those. It is the width of the list's own
+ * container that decides, not the window's: a narrow panel on a wide screen is narrow.
+ *
+ * Attach `frame` to the list's root element; `offered` is what the switcher may show and
+ * `present` what to draw (a wide one that was asked for falls back to rows).
+ */
+export declare function useNarrowList(presents: readonly ListPresent[] | undefined, requested: ListPresent): {
+    frame: RefObject<HTMLDivElement | null>;
+    offered: readonly ListPresent[];
+    present: ListPresent;
+};

package/dist/views/list/useNarrowList.js

@@ -0,0 +1,32 @@
+"use client";
+import { HANDHELD_WIDTH } from "../../foundations/layout.js";
+import { WIDE_PRESENTS } from "./columns.js";
+import { useEffect, useRef, useState } from "react";
+/**
+ * A narrow LIST — a phone, a drawer, a panel among four — does not offer the presentations
+ * that need width: a seven-column table at 360 px is a horizontal scroll nobody reads.
+ * There the list shows rows (a stacked card per record: the name, its state, its facts)
+ * and the board, and the switcher offers only those. It is the width of the list's own
+ * container that decides, not the window's: a narrow panel on a wide screen is narrow.
+ *
+ * Attach `frame` to the list's root element; `offered` is what the switcher may show and
+ * `present` what to draw (a wide one that was asked for falls back to rows).
+ */
+export function useNarrowList(presents, requested) {
+    const frame = useRef(null);
+    const [narrow, setNarrow] = useState(false);
+    useEffect(() => {
+        const el = frame.current;
+        if (el === null || typeof ResizeObserver === "undefined")
+            return;
+        const watch = new ResizeObserver(([entry]) => {
+            if (entry !== undefined)
+                setNarrow(entry.contentRect.width < HANDHELD_WIDTH);
+        });
+        watch.observe(el);
+        return () => watch.disconnect();
+    }, []);
+    const offered = (presents ?? []).filter((p) => !narrow || !WIDE_PRESENTS.includes(p));
+    const present = narrow && WIDE_PRESENTS.includes(requested) ? "rows" : requested;
+    return { frame, offered, present };
+}