@sincpro/web-ui 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,87 @@
+import { type Pile } from "../../foundations/grouping.js";
+import { type DataColumn } from "../../primitives/table/DataTable.js";
+import type { ReportColumn, ReportRow } from "../../primitives/table/ReportTable.js";
+import type { SheetColumn } from "../../primitives/table/SheetTable.js";
+import type { ListGroup, ListSheet, RowOf } from "./types.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 declare function groupLevelsOf<T extends object>(group: ListGroup<T> | undefined, columns: readonly DataColumn<T>[] | undefined): {
+    id: string;
+    label: string;
+    keyOf: (item: T) => string;
+    labelOf: (key: string) => string;
+}[];
+/**
+ * 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 declare function sheetFromColumns<T extends object>(shownColumns: readonly DataColumn<T>[] | undefined): ListSheet<T> | undefined;
+export type SheetEntry<T> = {
+    band?: {
+        field: string;
+        label: string;
+        count: number;
+        open: boolean;
+        key: string;
+        depth: number;
+        total?: (column: SheetColumn, columnIndex: number) => string | number | null;
+    };
+    item?: T;
+    n?: number;
+};
+/**
+ * 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 declare function sheetRowsOf<T extends object>(piles: readonly Pile<T>[] | null, isOpen: (pile: Pile<T>) => boolean, columns: readonly DataColumn<T>[] | undefined): SheetEntry<T>[] | null;
+/**
+ * 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 declare function reportRowsOf<T extends object>(piles: readonly Pile<T>[] | null, columns: readonly DataColumn<T>[] | undefined, row: (item: T) => RowOf): readonly ReportRow[];
+/**
+ * The columns of a report built from the piles, written like the list's own columns.
+ *
+ * `reportRowsOf` puts in position `i` the aggregate of the `i`-th column that declared one,
+ * so `report.columns[i]` is THAT column's: a report column without its own `format` takes
+ * the one the list column declared — otherwise the report wrote «Bs. 78.752,90» in the
+ * table's footer and «78.752,90» in its own total line. A format declared on the report
+ * column wins: it is the more specific declaration. A `count` column keeps the report's own
+ * number format — a count of rows is not an amount.
+ */
+export declare function reportColumnsOf<T extends object>(reportColumns: readonly ReportColumn[], columns: readonly DataColumn<T>[] | undefined): readonly ReportColumn[];

package/dist/views/list/derive.js

@@ -0,0 +1,207 @@
+import { levelKey, pathKey, pileItems, pileLabel, } from "../../foundations/grouping.js";
+import { aggregateFormat, aggregateOf, aggregateText, } 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. Y se ESCRIBE como el pie: con el `format` de la
+                       columna, para que el montón no diga «78752,9» debajo de «Bs.». */
+                    total: (column) => {
+                        const declared = columns?.find((one) => one.id === column.id);
+                        const value = declared === undefined ? null : aggregateOf(declared, inside);
+                        return declared === undefined || value === null
+                            ? null
+                            : aggregateText(declared, value);
+                    },
+                },
+            });
+            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);
+}
+/**
+ * The columns of a report built from the piles, written like the list's own columns.
+ *
+ * `reportRowsOf` puts in position `i` the aggregate of the `i`-th column that declared one,
+ * so `report.columns[i]` is THAT column's: a report column without its own `format` takes
+ * the one the list column declared — otherwise the report wrote «Bs. 78.752,90» in the
+ * table's footer and «78.752,90» in its own total line. A format declared on the report
+ * column wins: it is the more specific declaration. A `count` column keeps the report's own
+ * number format — a count of rows is not an amount.
+ */
+export function reportColumnsOf(reportColumns, columns) {
+    if (columns === undefined)
+        return reportColumns;
+    const numeric = columns.filter((column) => column.aggregate !== undefined);
+    return reportColumns.map((column, index) => {
+        const declared = numeric[index];
+        const format = declared === undefined ? undefined : aggregateFormat(declared);
+        return column.format !== undefined || format === undefined
+            ? column
+            : { ...column, format };
+    });
+}

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" | "create" | "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, create, 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,105 @@
+"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, create, 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 }), ...(create === undefined ? {} : { create }), ...((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);
+                },
+            }), ...(spec.onAddRow === undefined || entries !== null
+            ? {}
+            : { onAddRow: spec.onAddRow }) }));
+}