@sincpro/web-ui 0.0.0-stage → 0.2.0

package/dist/views/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./list/index.js";
+export * from "./record/index.js";

package/dist/views/index.js

@@ -0,0 +1,3 @@
+/* VIEWS — the two macros, and nothing else: one record, or N records. */
+export * from "./list/index.js";
+export * from "./record/index.js";

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

@@ -0,0 +1,119 @@
+import type { ListIdentity } from "../../components/listing/ListingBar.js";
+import type { SortField } from "../../components/listing/SortMenu.js";
+import type { Surface } from "../../foundations/types.js";
+import type { DataColumn, DataTableCreate } from "../../primitives/table/DataTable.js";
+import type { RowAction } from "../../primitives/table/RowActions.js";
+import type { SortState } from "../../primitives/table/Table.js";
+import { type ListCrumb, type ListEmpty, type ListGroup, type ListPivot, type ListPresent, type ListReport, type ListSheet, type RowOf } from "./types.js";
+import type { ReactNode } from "react";
+type BarProps = {
+    children?: ReactNode;
+};
+type CrumbsProps = {
+    crumbs: readonly ListCrumb[];
+};
+type NodeProps = {
+    children?: ReactNode;
+};
+type RowsProps<T> = {
+    row: (item: T) => RowOf;
+    /**
+     * Los rótulos de las zonas de una fila, arriba de todas. Sin esto no hay
+     * encabezado: 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.
+     */
+    header?: {
+        name: string;
+        meta?: string;
+        tags?: string;
+    };
+};
+type TableProps<T extends object> = {
+    columns: readonly DataColumn<T>[];
+    /** Cuáles están en pantalla. Las obligatorias se quedan aunque se omitan. */
+    visibleColumnIds?: readonly string[];
+    onVisibleColumnIdsChange?: (ids: readonly string[]) => void;
+    /** El pie con los agregados de las columnas que declararon uno. */
+    totals?: boolean;
+    /** Lo que se le hace a UNA fila sin entrar. Se dibujan escondidas y aparecen
+     *  sobre la fila que se está apuntando. */
+    rowActions?: (item: T) => readonly RowAction[];
+    /** Escribir un registro nuevo como una fila más de la tabla (la lista editable de
+     *  Odoo). Ver la cabecera de `DataTable`. */
+    create?: DataTableCreate<T>;
+};
+/** El tablero. Sin `card`, la tarjeta sale de lo que ya dice `List.Rows`: el
+ *  nombre, el `meta` y las fichas. Escribirla igual es declarar que ESTA lista
+ *  se puede ver como tablero. */
+type BoardProps<T> = {
+    card?: (item: T) => ReactNode;
+};
+/** La planilla. Sin columnas propias, sale de las que declaró `List.Table` — la
+ *  de datos CRUDOS sí las trae, porque ahí salen del archivo y el código no sabe
+ *  cuáles son. */
+type SheetProps<T> = Partial<ListSheet<T>>;
+export type ListProps<T extends object> = {
+    items: readonly T[];
+    keyOf: (item: T) => string;
+    /** The list is a FIELD of a record — a one2many / many2many — and not a screen: a
+     *  one-line bar that does not stick. See «A list INSIDE a record» above. */
+    embedded?: boolean;
+    /** En qué superficie se apoya la BARRA. `canvas` (el default) es una barra
+     *  de control clara; `chrome` la convierte en una banda oscura, una opción
+     *  explícita: la barra de la aplicación es la única banda oscura de la
+     *  pantalla, igual que el riel de un registro. */
+    surface?: Surface;
+    /** Cómo se parte el conjunto. Es del CONJUNTO y no de una cara: cambiar de
+     *  presentación no puede perderlo. */
+    group?: ListGroup<T>;
+    selection?: {
+        has: (id: string) => boolean;
+        toggle: (id: string) => void;
+        count: number;
+        clear: () => void;
+        actions?: ReactNode;
+    };
+    /** El orden, que también es del conjunto. */
+    sort?: SortState | null;
+    onSortChange?: (next: SortState | null) => void;
+    /** Por qué campos se puede ordenar en las caras que NO tienen encabezados
+     *  donde hacer clic. */
+    sortable?: readonly SortField<T>[];
+    /** Cuál cara se está mirando. Sin esto, la primera que esté escrita. */
+    present?: ListPresent;
+    onPresentChange?: (next: ListPresent) => void;
+    onOpen?: (item: T) => void;
+    onPeek?: (item: T) => void;
+    isPeeked?: (item: T) => boolean;
+    /** Los tres estados, en un solo lugar. */
+    state?: {
+        loading?: boolean;
+        error?: string | null;
+    };
+    /** Vacía POR UN FILTRO es otra situación: no falta contenido, sobra un
+     *  recorte. */
+    filtered?: boolean;
+    empty?: ListEmpty;
+    children?: ReactNode;
+};
+export declare function List<T extends object>({ items, keyOf, embedded, surface, group, selection, sort, onSortChange, sortable, present, onPresentChange, onOpen, onPeek, isPeeked, state, filtered, empty, children, }: ListProps<T>): import("react").JSX.Element;
+export declare namespace List {
+    var Bar: ((props: BarProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"bar">;
+    var Crumbs: ((props: CrumbsProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"crumbs">;
+    var Identity: ((props: ListIdentity) => ReactNode) & import("../../foundations/slots.js").Slotted<"identity">;
+    var Search: ((props: NodeProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"search">;
+    var Actions: ((props: NodeProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"actions">;
+    var Pagination: ((props: NodeProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"pagination">;
+    var Views: ((props: NodeProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"views">;
+    var Metrics: ((props: NodeProps) => ReactNode) & import("../../foundations/slots.js").Slotted<"metrics">;
+    var Rows: <T>(props: RowsProps<T>) => ReactNode;
+    var Table: <T extends object>(props: TableProps<T>) => ReactNode;
+    var Board: <T>(props: BoardProps<T>) => ReactNode;
+    var Sheet: <T>(props: SheetProps<T>) => ReactNode;
+    var Report: ((props: ListReport) => ReactNode) & import("../../foundations/slots.js").Slotted<"report">;
+    var Pivot: <T>(props: ListPivot<T>) => ReactNode;
+}
+export {};

package/dist/views/list/List.js

@@ -0,0 +1,101 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { flatten, loose, pick, propsOf, slot, slotOf, } from "../../foundations/slots.js";
+import { ListView } from "./ListView.js";
+import {} from "./types.js";
+/** La barra: todo lo que es del CONJUNTO y no de una fila. Sin ella no hay
+ *  banda — que es lo que quiere una lista metida adentro de un diálogo. */
+const Bar = slot("bar", (_props) => null);
+/** De dónde vengo. Va arriba de la barra, y sólo cuando la barra es cromo. */
+const Crumbs = slot("crumbs", (_props) => null);
+/** Cómo se llama esta lista y cuánto tiene. */
+const Identity = slot("identity", (_props) => null);
+/** El campo de búsqueda, ya armado: lo arma quien tiene las declaraciones del
+ *  dominio — el sistema no sabe qué es un NIT. */
+const Search = slot("search", (_props) => null);
+/** Lo que EMPIEZA algo nuevo. Sigue visible cuando hay una selección. */
+const Actions = slot("actions", (_props) => null);
+const Pagination = slot("pagination", (_props) => null);
+/** La escotilla del conmutador: un selector propio. Casi nunca hace falta —
+ *  las caras escritas ya lo dibujan. */
+const Views = slot("views", (_props) => null);
+/** Las medidas que además RECORTAN: «2 por confirmar». Van debajo de la barra y
+ *  arriba de las filas, porque son del conjunto y no del marco. */
+const Metrics = slot("metrics", (_props) => null);
+const Rows = slot("rows", (_props) => null);
+/* Through `unknown`: `create` both receives and hands back a `T` (`onChange`, `draft`),
+   so `TableProps` is invariant in `T` and `TableProps<never>` no longer narrows to it. The
+   slot only carries the props; `List` reads them back typed against the list's `T`. */
+const TableSlot = slot("table", (_props) => null);
+const Board = slot("board", (_props) => null);
+const SheetSlot = slot("sheet", (_props) => null);
+const Report = slot("report", (_props) => null);
+const Pivot = slot("pivot", (_props) => null);
+/* El orden en que se OFRECEN cuando están escritas de otra manera. El conmutador
+   respeta el orden del árbol; esto sólo nombra a qué presentación corresponde
+   cada ranura. */
+const PRESENT_OF = {
+    rows: "rows",
+    table: "table",
+    board: "board",
+    sheet: "sheet",
+    report: "report",
+    pivot: "pivot",
+};
+const FACES = ["rows", "table", "board", "sheet", "report", "pivot"];
+export function List({ items, keyOf, embedded, surface, group, selection, sort, onSortChange, sortable, present, onPresentChange, onOpen, onPeek, isPeeked, state, filtered, empty, children, }) {
+    const top = flatten(children);
+    const bar = flatten(propsOf(pick(top, "bar"))?.children);
+    const crumbs = propsOf(pick(bar, "crumbs"))?.crumbs;
+    const identity = propsOf(pick(bar, "identity"));
+    const search = propsOf(pick(bar, "search"))?.children;
+    const actions = propsOf(pick(bar, "actions"))?.children;
+    const pagination = propsOf(pick(bar, "pagination"))?.children;
+    const views = propsOf(pick(bar, "views"))?.children;
+    const metrics = propsOf(pick(top, "metrics"))?.children;
+    const rows = propsOf(pick(top, "rows"));
+    const table = propsOf(pick(top, "table"));
+    const board = propsOf(pick(top, "board"));
+    const sheet = propsOf(pick(top, "sheet"));
+    const report = propsOf(pick(top, "report"));
+    const pivot = propsOf(pick(top, "pivot"));
+    /* Las caras que hay son las que están escritas, EN ESE ORDEN. El conmutador
+       no puede ofrecer una que no se pueda dibujar, porque la que se dibuja y la
+       que se ofrece son el mismo nodo. */
+    const presents = top
+        .map((node) => FACES.find((face) => slotOf(node) === face))
+        .filter((face) => face !== undefined)
+        .map((face) => PRESENT_OF[face]);
+    /* La escotilla: lo que el arquetipo no previó se dibuja igual, debajo. Que
+       aparezca algo acá es la señal de que al arquetipo le falta una pieza. */
+    const rest = loose(top, ["bar", "metrics", ...FACES]);
+    return (_jsx(ListView, { items: items, keyOf: keyOf, row: rows?.row ?? (() => ({ name: "" })), ...(rows?.header === undefined ? {} : { rowHeader: rows.header }), ...(identity === undefined ? {} : { identity }), ...(crumbs === undefined ? {} : { crumbs }), ...(embedded === undefined ? {} : { embedded }), ...(surface === undefined ? {} : { surface }), ...(search === undefined ? {} : { search }), ...(actions === undefined ? {} : { actions }), ...(pagination === undefined ? {} : { pagination }), ...(views === undefined ? {} : { views }), ...(metrics === undefined ? {} : { metrics }), ...(table === undefined
+            ? {}
+            : {
+                columns: table.columns,
+                ...(table.totals === undefined ? {} : { totals: table.totals }),
+                ...(table.rowActions === undefined ? {} : { rowActions: table.rowActions }),
+                ...(table.create === undefined ? {} : { create: table.create }),
+                ...(table.visibleColumnIds === undefined
+                    ? {}
+                    : { visibleColumnIds: table.visibleColumnIds }),
+                ...(table.onVisibleColumnIdsChange === undefined
+                    ? {}
+                    : { onVisibleColumnIdsChange: table.onVisibleColumnIdsChange }),
+            }), ...(board?.card === undefined ? {} : { card: board.card }), ...(sheet?.columns === undefined || sheet.cell === undefined
+            ? {}
+            : { sheet: sheet }), ...(report === undefined ? {} : { report }), ...(pivot === undefined ? {} : { pivot }), ...(presents.length === 0 ? {} : { presents }), ...(present === undefined ? {} : { present }), ...(onPresentChange === undefined ? {} : { onPresentChange }), ...(group === undefined ? {} : { group }), ...(selection === undefined ? {} : { selection }), ...(sort === undefined ? {} : { sort }), ...(onSortChange === undefined ? {} : { onSortChange }), ...(sortable === undefined ? {} : { sortable }), ...(onOpen === undefined ? {} : { onOpen }), ...(onPeek === undefined ? {} : { onPeek }), ...(isPeeked === undefined ? {} : { isPeeked }), ...(state === undefined ? {} : { state }), ...(filtered === undefined ? {} : { filtered }), ...(empty === undefined ? {} : { empty }), children: rest.length === 0 ? undefined : rest }));
+}
+List.Bar = Bar;
+List.Crumbs = Crumbs;
+List.Identity = Identity;
+List.Search = Search;
+List.Actions = Actions;
+List.Pagination = Pagination;
+List.Views = Views;
+List.Metrics = Metrics;
+List.Rows = Rows;
+List.Table = TableSlot;
+List.Board = Board;
+List.Sheet = SheetSlot;
+List.Report = Report;
+List.Pivot = Pivot;

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

@@ -0,0 +1,6 @@
+import type { ListViewProps } from "./types.js";
+export declare function ListView<T extends object>({ items, keyOf, identity, crumbs, embedded, surface: requestedSurface, metrics, search, pagination, views, actions, row, rowHeader, columns, visibleColumnIds, onVisibleColumnIdsChange, card, sheet, report, pivot, present: requested, presents, onPresentChange, sort, onSortChange, sortable, totals, rowActions, create, group, selection, onOpen, onPeek, state, filtered, empty, children, }: ListViewProps<T>): import("react").JSX.Element;
+/** What a list offers when it fails and can be retried. */
+export declare function RetryAction({ onRetry }: {
+    onRetry: () => void;
+}): import("react").JSX.Element;

package/dist/views/list/ListView.js

@@ -0,0 +1,295 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useColumnControl, visibleColumns } from "../../components/listing/columns.js";
+import { ColumnsMenu, specsFromColumns, } from "../../components/listing/ColumnsMenu.js";
+import { Listing } from "../../components/listing/Listing.js";
+import { ListingBar } from "../../components/listing/ListingBar.js";
+import { RecordCard } from "../../components/listing/RecordCard.js";
+import { GroupHeader, Row, RowHeader } from "../../components/listing/Row.js";
+import { sortItems, SortMenu, } from "../../components/listing/SortMenu.js";
+import { ViewSwitcher } from "../../components/listing/ViewSwitcher.js";
+import { Breadcrumb } from "../../components/record/Breadcrumb.js";
+import { useUiCopy } from "../../foundations/copy.js";
+import { useDensity } from "../../foundations/density.js";
+import { pathKey, pileIsOpen, pilesOf, } from "../../foundations/grouping.js";
+import { pivotFrom, pivotIsEmpty } from "../../foundations/pivot.js";
+import { Button } from "../../primitives/button/Button.js";
+import { Empty, Failed, Skeleton } from "../../primitives/notice/Notice.js";
+import { PivotTable } from "../../primitives/table/PivotTable.js";
+import { ReportTable } from "../../primitives/table/ReportTable.js";
+import { groupedColumnIds } from "./columns.js";
+import { groupLevelsOf, reportColumnsOf, reportRowsOf, sheetFromColumns, sheetRowsOf, } from "./derive.js";
+import { SheetPresentation, TablePresentation, } from "./presentations.js";
+import { useNarrowList } from "./useNarrowList.js";
+import { Grid3x3, LayoutGrid, List, Sheet, Sigma, Table2 } from "lucide-react";
+import { Fragment, useCallback, useMemo } from "react";
+/**
+ * EL DIBUJO de una lista. **La puerta es `List`**, que se escribe como árbol y
+ * traduce las ranuras a esto — acá todo entra como props porque acá ya se
+ * decidió todo: quién compone no elige entre dos maneras de escribir lo mismo,
+ * porque esto no se publica.
+ *
+ * Context: `invoices.view.tsx` has 349 lines and about 120 of them are
+ * re-assembling this: the bar, the search field, the grouping and the three
+ * states. Ten views with their own copy are 1,200 lines that drift apart one at
+ * a time, one per week — and it already happened: Facturas had a text
+ * `<input>` while the modal explorer had facets, filters and grouping. The same
+ * list, in two places, with two sets of capabilities.
+ *
+ * **Grouping, sorting and which columns are on screen belong to the SET;
+ * rows, table and board are three PRESENTATIONS of the same set.** Until now
+ * grouping only existed inside `DataTable`, so switching presentation lost
+ * the grouping; the columns submenu existed only on FrameView, and every
+ * column could hide. Odoo splits required vs optional — that split lives in
+ * `useColumnControl`. Collapse lives in `useTreeControl`.
+ *
+ * The escape hatch is `children`: whatever the archetype did not foresee gets
+ * drawn anyway, and its appearing there is the signal that the archetype is
+ * missing something.
+ */
+const PRESENT_ICONS = [
+    { id: "rows", icon: List },
+    { id: "table", icon: Table2 },
+    { id: "board", icon: LayoutGrid },
+    { id: "sheet", icon: Sheet },
+    /* La sigma y no un ícono de tabla: lo que distingue a un informe de las otras
+       cuatro es que SUMA. */
+    { id: "report", icon: Sigma },
+    /* La cuadrícula: dos ejes, y lo que importa está adentro. */
+    { id: "pivot", icon: Grid3x3 },
+];
+export function ListView({ items, keyOf, identity, crumbs, embedded = false, surface: requestedSurface, metrics, search, pagination, views, actions, row, rowHeader, columns, visibleColumnIds, onVisibleColumnIdsChange, card, sheet, report, pivot, present: requested = "rows", presents, onPresentChange, sort, onSortChange, sortable, totals = false, rowActions, create, group, selection, onOpen, onPeek, state, filtered = false, empty, children, }) {
+    const { frame, offered, present } = useNarrowList(presents, requested);
+    /* Embedded, the list sits on the record's paper: there is no dark band to inherit, and a
+       navy switcher inside a white sheet would be a second chrome on the screen. */
+    const surface = embedded ? undefined : requestedSurface;
+    const density = useDensity();
+    const copy = useUiCopy();
+    const loading = state?.loading === true;
+    const error = state?.error ?? null;
+    const columnSpecs = useMemo(() => specsFromColumns(columns ?? [], false), [columns]);
+    const columnControl = useColumnControl(columnSpecs, {
+        ...(visibleColumnIds === undefined ? {} : { visibleIds: visibleColumnIds }),
+        /* El nombre tiene que ser el que `useColumnControl` lee. Decía
+           `onVisibleColumnIdsChange` —el nombre de la prop de ACÁ— y el hook busca
+           `onVisibleIdsChange`, así que nunca entraba en modo controlado: la lista
+           ignoraba en silencio las columnas que le pasaran. */
+        ...(onVisibleColumnIdsChange === undefined
+            ? {}
+            : { onVisibleIdsChange: onVisibleColumnIdsChange }),
+    });
+    /* Agrupar por una columna escondida dejaría montones cuyo criterio no se ve.
+       Con N niveles son N columnas, y se reponen todas. Es lo ÚNICO para lo que
+       hace falta saber qué columna contesta por un campo: la tabla ya no agrupa
+       por columnas, agrupa por niveles. */
+    const groupedIds = group === undefined ? [] : groupedColumnIds(group, columns);
+    const tableIds = groupedIds.every((id) => columnControl.visibleIds.includes(id))
+        ? columnControl.visibleIds
+        : [
+            ...columnControl.visibleIds,
+            ...groupedIds.filter((id) => !columnControl.visibleIds.includes(id)),
+        ];
+    const shownColumns = columns === undefined ? undefined : visibleColumns(columns, tableIds);
+    const groupLevels = useMemo(() => groupLevelsOf(group, columns), [group, columns]);
+    const switcher = views ??
+        (offered.length > 1 ? (_jsx(ViewSwitcher, { options: PRESENT_ICONS.filter((option) => offered.includes(option.id)).map((option) => ({
+                id: option.id,
+                label: copy.present[option.id],
+                icon: option.icon,
+            })), current: present, ...(onPresentChange === undefined
+                ? {}
+                : { onSelect: (id) => onPresentChange(id) }), ...(surface === undefined ? {} : { surface }) })) : undefined);
+    const sheetFromDeclared = useMemo(() => sheetFromColumns(shownColumns), [shownColumns]);
+    const sheetSpec = sheet ?? sheetFromDeclared;
+    /* El menú de columnas vale en `table` y en la planilla DERIVADA —las dos
+       dibujan las columnas que declaró el código—, y no en la planilla de datos
+       crudos ni en el informe: ahí las columnas salen del archivo o son los
+       períodos, y no hay ninguna que el código pueda ofrecer esconder. */
+    const columnsMenu = (present === "table" || (present === "sheet" && sheet === undefined)) &&
+        columnControl.hasOptional ? (_jsx(ColumnsMenu, { control: columnControl, ...(surface === undefined ? {} : { surface }) })) : null;
+    /* ORDENAR. El control va en la barra y no adentro de la tabla porque el orden
+       es del CONJUNTO, igual que los niveles y que lo plegado: cambiar de
+       presentación no puede perderlo, y en filas, tablero y planilla no hay
+       encabezados donde hacer clic.
+  
+       Lo único que NO se ordena es un informe cuyas filas DECLARÓ el dominio: ahí
+       el orden es el informe —«Total activos» tiene que quedar después de los
+       activos— y reordenarlo por importe lo destruye.
+  
+       Un informe armado a partir de los montones sí se ordena, porque no es una
+       jerarquía que alguien escribió: es este mismo conjunto, contado. La regla
+       mira `report.rows` y no la presentación, que era la versión gruesa de esto y
+       le sacaba el orden a un informe que sí podía tenerlo. */
+    const declaredReport = present === "report" && report?.rows !== undefined;
+    /* El pivote tampoco se ordena desde la barra, y por una razón propia: sus
+       filas no son las filas del conjunto. Cada eje está en el orden de sus
+       claves, y ordenar los registros de abajo no ordena los montones de arriba —
+       ofrecerlo sería un control que se mueve y no cambia nada. */
+    const sortMenu = sortable === undefined ||
+        sortable.length === 0 ||
+        declaredReport ||
+        present === "pivot" ? null : (_jsx(SortMenu, { fields: sortable, sort: sort ?? null, onSortChange: (next) => onSortChange?.(next), ...(surface === undefined ? {} : { surface }) }));
+    const rightViews = views ?? switcher;
+    const viewsSlot = columnsMenu === null && sortMenu === null && rightViews === undefined ? undefined : (_jsxs(_Fragment, { children: [sortMenu, columnsMenu, rightViews] }));
+    /* Embedded, the line is drawn only if it has something to OFFER: a count alone repeats
+       what the rows (and the footer) already say. */
+    const barHasControls = !embedded ||
+        search !== undefined ||
+        viewsSlot !== undefined ||
+        actions !== undefined ||
+        pagination !== undefined ||
+        (selection?.count ?? 0) > 0;
+    const bar = !barHasControls ? undefined : (_jsx(ListingBar, { surface: surface, ...(embedded ? { inline: true, count: items.length } : {}), ...(embedded || crumbs === undefined || crumbs.length === 0 || density === "compact"
+            ? {}
+            : {
+                crumbs: (_jsx(Breadcrumb, { crumbs: crumbs, ...(surface === undefined ? {} : { surface }) })),
+            }), ...(actions === undefined ? {} : { actions }), ...(identity?.title === undefined ? {} : { title: identity.title }), ...(identity?.description === undefined ? {} : { description: identity.description }), ...(identity?.counters === undefined ? {} : { counters: identity.counters }), ...(selection === undefined
+            ? {}
+            : {
+                selection: {
+                    count: selection.count,
+                    onClear: selection.clear,
+                    ...(selection.actions === undefined ? {} : { actions: selection.actions }),
+                },
+            }), ...(search === undefined ? {} : { search }), ...(pagination === undefined ? {} : { pagination }), ...(viewsSlot === undefined ? {} : { views: viewsSlot }) }));
+    const renderRow = (item) => {
+        const d = row(item);
+        const id = keyOf(item);
+        return (_jsx(Row, { ...(d.icon === undefined ? {} : { icon: d.icon }), name: d.name, ...(d.tags === undefined ? {} : { tags: d.tags }), ...(d.meta === undefined ? {} : { meta: d.meta }), ...(d.actions === undefined ? {} : { actions: d.actions }), ...(onOpen === undefined ? {} : { onOpen: () => onOpen(item) }), ...(onPeek === undefined ? {} : { onPeek: () => onPeek(item) }), ...(selection === undefined
+                ? {}
+                : { selected: selection.has(id), onSelectedChange: () => selection.toggle(id) }), children: d.children }, id));
+    };
+    /* El orden va ANTES de agrupar y no después, y no es indistinto: agrupar
+       preserva el orden de aparición dentro de cada montón, así que ordenar
+       primero ordena las filas de cada montón. Al revés habría que reordenar N
+       montones y el orden entre ellos quedaría al azar.
+  
+       La tabla ordena adentro —es TanStack— así que ahí se deja pasar: ordenar dos
+       veces no rompe nada, pero es trabajo al pedo sobre cada render. */
+    const ordered = useMemo(() => present === "table" || sortable === undefined
+        ? items
+        : sortItems(items, sortable, sort ?? null), [items, present, sortable, sort]);
+    /**
+     * La grilla que hay que dibujar: la que le pasaron plegada, o la que se arma
+     * con las filas en la mano.
+     *
+     * Es la misma decisión que `pilesOf` toma para los montones, y por el mismo
+     * motivo: quién plegó no es asunto de esta capa.
+     */
+    const pivotShown = useMemo(() => {
+        if (pivot?.folded !== undefined)
+            return pivot.folded;
+        if (pivot?.spec === undefined)
+            return undefined;
+        return pivotFrom(ordered, pivot.spec);
+    }, [pivot, ordered]);
+    /**
+     * Vacío es no tener NADA que dibujar, y en el pivote eso no se pregunta
+     * contando `items`: cuando la grilla la plegó quien guarda los datos, las
+     * filas de la pantalla son montones y el conjunto puede no haber bajado
+     * nunca. Contar los registros ahí es tapar una grilla entera con «todavía no
+     * hay datos».
+     */
+    const isEmpty = !loading &&
+        error === null &&
+        (present === "pivot" && pivotShown !== undefined
+            ? pivotIsEmpty(pivotShown)
+            : items.length === 0) &&
+        /* The first record of an empty list is written in the table, not under a sentence
+           saying there is nothing. */
+        !(present === "table" && create?.draft != null);
+    /* La única línea que hace agrupable a una vista: el árbol que le pasaron, o el
+       que se arma con las filas en la mano. */
+    const piles = useMemo(() => pilesOf(ordered, group), [group, ordered]);
+    const isOpen = useCallback((pile) => pileIsOpen(pile, group), [group]);
+    const sheetRows = useMemo(() => sheetRowsOf(piles, isOpen, columns), [piles, isOpen, columns]);
+    /* La forma de una fila de ESTA lista, para que el encabezado reserve los
+       mismos espaciadores. Se mira la primera y no todas: el ícono y las acciones
+       los decide la vista para la lista entera. */
+    const first = items[0];
+    const firstRow = first === undefined ? undefined : row(first);
+    /** Los montones, con sus filas adentro. Se llama a sí misma porque el árbol
+     *  tiene N niveles: un montón dibuja su encabezado y, adentro, o bien los
+     *  montones de abajo o bien las filas — nunca las dos cosas. */
+    function renderPiles(list, nodes) {
+        return list.map((pile) => {
+            const key = pathKey(pile.path);
+            const open = isOpen(pile);
+            return (_jsxs(Fragment, { children: [_jsx(GroupHeader, { field: pile.field, label: pile.label, count: pile.count, depth: pile.depth, open: open, ...(group?.onToggle === undefined
+                            ? {}
+                            : { onToggle: () => group.onToggle?.(key) }) }), !open
+                        ? null
+                        : pile.piles.length > 0
+                            ? renderPiles(pile.piles, nodes)
+                            : nodes(pile.items)] }, key));
+        });
+    }
+    const reportRows = useMemo(() => reportRowsOf(piles, columns, row), [piles, columns, row]);
+    function wrapGroups(nodes) {
+        if (piles === null)
+            return nodes(ordered);
+        return renderPiles(piles, nodes);
+    }
+    const renderCard = (item) => {
+        if (card !== undefined) {
+            return _jsx(Fragment, { children: card(item) }, keyOf(item));
+        }
+        const d = row(item);
+        return (_jsx(RecordCard, { title: d.name, ...(d.tags === undefined ? {} : { tags: d.tags }), ...(d.meta === undefined ? {} : { meta: d.meta }), ...(onOpen === undefined ? {} : { onOpen: () => onOpen(item) }) }, keyOf(item)));
+    };
+    const body = present === "table" && shownColumns !== undefined ? (
+    /* The table receives EVERYTHING that belongs to the set: see `TablePresentation`. */
+    _jsx(TablePresentation, { items: items, columns: shownColumns, keyOf: keyOf, levels: groupLevels, ...(sort === undefined ? {} : { sort }), ...(onSortChange === undefined ? {} : { onSortChange }), ...(group === undefined ? {} : { group }), ...(selection === undefined ? {} : { selection }), totals: totals, ...(rowActions === undefined ? {} : { rowActions }), ...(create === undefined ? {} : { create }), ...(onPeek === undefined ? {} : { onPeek }), ...(onOpen === undefined ? {} : { onOpen }) })) : present === "sheet" && sheetSpec !== undefined ? (
+    /* La planilla recibe el conjunto por ÍNDICE y no una matriz ya armada: ver `SheetPresentation`. */
+    _jsx(SheetPresentation, { spec: sheetSpec, entries: sheetRows, ordered: ordered, ...(group === undefined ? {} : { group }) })) : present === "report" && report !== undefined ? (
+    /* El informe declarado por el dominio no se ORDENA desde la barra: el
+       orden ES el informe, y ordenar un balance por importe deja «Total
+       Activos» en el medio. Pero sí se AGRUPA cuando las líneas no vienen
+       declaradas: ahí el informe es este conjunto contado por los niveles que
+       estén puestos. */
+    _jsx(ReportTable
+    /* Built from the piles, the numbers are the list's columns' — and so is how they
+       are written. Declared by the domain, the columns are the domain's. */
+    , { 
+        /* Built from the piles, the numbers are the list's columns' — and so is how they
+           are written. Declared by the domain, the columns are the domain's. */
+        columns: report.rows === undefined
+            ? reportColumnsOf(report.columns, columns)
+            : report.columns, rows: report.rows ?? reportRows, ...(report.defaultOpen === undefined ? {} : { defaultOpen: report.defaultOpen }), ...(report.height === undefined ? {} : { height: report.height }) })) : present === "pivot" && pivotShown !== undefined ? (
+    /* El pivote recibe la grilla y nada más: no hay selección que pasarle
+       —una casilla por montón elegiría cosas que no son registros—, no hay
+       orden —cada eje viene en el orden de sus claves— y no hay menú de
+       columnas, porque las columnas son un eje y no una lista de campos que
+       se puedan esconder de a uno. */
+    _jsx(PivotTable, { pivot: pivotShown, ...(pivot?.onCell === undefined ? {} : { onCell: pivot.onCell }), ...(pivot?.height === undefined ? {} : { height: pivot.height }) })) : present === "board" ? (_jsx("div", { className: "flex flex-col", children: wrapGroups((inside) => (_jsx("div", { className: "grid gap-3 p-3 @2xl:grid-cols-2 @5xl:grid-cols-3", children: inside.map(renderCard) }))) })) : (
+    /* El encabezado va ANTES de los montones y no adentro de cada uno:
+       rotula la fila, y la fila es la misma en los cinco montones. */
+    _jsxs(_Fragment, { children: [rowHeader === undefined || items.length === 0 ? null : (_jsx(RowHeader, { name: rowHeader.name, ...(rowHeader.meta === undefined ? {} : { meta: rowHeader.meta }), ...(rowHeader.tags === undefined ? {} : { tags: rowHeader.tags }), withSelection: selection !== undefined, 
+                /* Los espaciadores se preguntan por la PRIMERA fila: el ícono y las
+                   acciones son de la lista entera, no de una fila — si la primera no
+                   tiene ícono, ninguna lo tiene. */
+                withIcon: firstRow?.icon !== undefined, withActions: onOpen !== undefined || firstRow?.actions !== undefined })), wrapGroups((inside) => inside.map(renderRow))] }));
+    return (
+    /* The list is its own container (`@container`: the presentations adapt to the width
+       the LIST has, not the window) and fills the space it is given. Before, every page
+       wrapped it in a `div` to get both. */
+    _jsxs("div", { ref: frame, className: "@container flex min-w-0 flex-1 flex-col bg-surface", children: [_jsxs(Listing, { bar: bar, 
+                /* La barra se queda arriba: con 187 filas, scrollear para ver la última
+                   dejaba sin buscador, sin paginador y sin el conmutador.
+                   Embedded it does NOT: the record has its own sticky parts (its rail, its tabs),
+                   and a second band stuck under them — or carried up into the frame's header slot,
+                   which is what a sticky list bar does under a sidebar — would cover the record
+                   for a collection of a dozen rows. */
+                sticky: !embedded, ...(surface === undefined ? {} : { surface }), ...(metrics === undefined
+                    ? {}
+                    : {
+                        metrics: _jsx("div", { className: "px-3.5", children: metrics }),
+                    }), children: [loading ? _jsx(Skeleton, { label: copy.failed.loading }) : null, isEmpty ? (filtered ? (_jsx(Empty, { sentence: empty?.whenFiltered?.sentence ?? copy.list.emptyFiltered, ...(empty?.whenFiltered?.action === undefined
+                            ? {}
+                            : { action: empty.whenFiltered.action }) })) : (_jsx(Empty, { sentence: empty?.sentence ?? copy.list.empty, ...(empty?.action === undefined ? {} : { action: empty.action }) }))) : null, loading || isEmpty ? null : body] }), error === null ? null : (_jsx("div", { className: "px-3 pt-(--spacing-block)", children: _jsx(Failed, { heading: copy.failed.list, sentence: error }) })), children] }));
+}
+/** What a list offers when it fails and can be retried. */
+export function RetryAction({ onRetry }) {
+    const copy = useUiCopy();
+    return (_jsx(Button, { role: "secondary", size: "sm", onClick: onRetry, children: copy.failed.retry }));
+}

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

@@ -0,0 +1,18 @@
+import type { ListPresent } from "../../components/listing/set.js";
+import type { DataColumn } from "../../primitives/table/DataTable.js";
+import type { ListGroup } from "./types.js";
+/** Las columnas que una tabla agrupada tiene que MOSTRAR, en orden.
+ *
+ *  No son por las que agrupa —eso lo hacen los niveles, con la clave del motor—
+ *  sino las que no pueden quedar escondidas: un montón «Septiembre» con la
+ *  columna «registrado» apagada es un corte cuyo criterio no está en la
+ *  pantalla.
+ *
+ *  **El nombre de una columna y el de un campo no son el mismo, y suponerlo fue
+ *  lo que rompió la tabla.** Una columna puede llamarse `registered` y contestar
+ *  por el `registered_at` del modelo — que es justo lo que declara
+ *  `DataColumn.field`. Lee las columnas en orden —la que SE LLAMA como el campo,
+ *  después la que lo declara— y `columnOf` gana si la vista sabe más. */
+export declare function groupedColumnIds<T extends object>(group: ListGroup<T>, columns: readonly DataColumn<T>[] | undefined): string[];
+/** The presentations that need width: a grid of columns. */
+export declare const WIDE_PRESENTS: readonly ListPresent[];

package/dist/views/list/columns.js

@@ -0,0 +1,27 @@
+/** Las columnas que una tabla agrupada tiene que MOSTRAR, en orden.
+ *
+ *  No son por las que agrupa —eso lo hacen los niveles, con la clave del motor—
+ *  sino las que no pueden quedar escondidas: un montón «Septiembre» con la
+ *  columna «registrado» apagada es un corte cuyo criterio no está en la
+ *  pantalla.
+ *
+ *  **El nombre de una columna y el de un campo no son el mismo, y suponerlo fue
+ *  lo que rompió la tabla.** Una columna puede llamarse `registered` y contestar
+ *  por el `registered_at` del modelo — que es justo lo que declara
+ *  `DataColumn.field`. Lee las columnas en orden —la que SE LLAMA como el campo,
+ *  después la que lo declara— y `columnOf` gana si la vista sabe más. */
+export function groupedColumnIds(group, columns) {
+    return group.levels
+        .map((level) => group.columnOf?.(level) ?? columnAnswering(level.field, columns))
+        .filter((id) => id !== undefined);
+}
+/** The presentations that need width: a grid of columns. */
+export const WIDE_PRESENTS = ["table", "sheet", "report", "pivot"];
+/** The id of the column that answers for a model field, when there is one. */
+function columnAnswering(field, columns) {
+    if (columns === undefined)
+        return field;
+    return (columns.find((one) => one.id === field)?.id ??
+        columns.find((one) => one.field === field)?.id ??
+        field);
+}