@sincpro/web-framework 0.0.0-stage → 0.2.0

package/dist/web/list/EntityList.js

@@ -0,0 +1,229 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { nameOf } from "@sincpro/criteria";
+import { RecordLink, useCrumbs } from "@sincpro/web-composer";
+import { frameworkCopy } from "../../core/copy.js";
+import { PICK_PARAM, QUERY_PARAM, TRAIL_PARAM } from "../../core/entity.js";
+import { textOf, viewOf } from "../../core/present.js";
+import { explain } from "../../core/transport.js";
+import { useFramework } from "../../react/context.js";
+import { useGroups } from "../../react/useGroups.js";
+import { columnsOf } from "./columns.js";
+import { EntitySearchBar } from "./EntitySearchBar.js";
+import { pilesOf } from "./groups.js";
+import { useRowCommands } from "./rowCommands.js";
+import { Button, Callout, List, Pagination, SearchField, Tag, } from "@sincpro/web-ui";
+import { useEffect, useId, useMemo, useState } from "react";
+/** What `useCrumbs` reads when the list is not in a workspace: no trail, and nothing to follow. */
+const NO_TRAIL = [];
+const NO_WORKSPACE = {
+    crumbs: () => NO_TRAIL,
+    context: { subscribe: () => () => undefined },
+};
+/** How many lists' trails are kept: the records opened from the last fifty lists page on. */
+const TRAILS = 50;
+/** No commands: one constant, so the hook is not handed a new array on every render. */
+const NO_COMMANDS = [];
+export function EntityList({ listing, api, columns: askedColumns, cells, views: askedViews, title: askedTitle, description: askedDescription, crumbs, actions, onOpen, onPeek, empty, search = "bar", sums, filters: askedFilters, selectable = false, selectionActions, embedded = false, create = true, commands = NO_COMMANDS, rowActions: askedRowActions, }) {
+    // A named list (`defineList`) brings its own columns, filters, faces and words; what the
+    // screen passes wins.
+    const definition = listing.definition;
+    const columns = askedColumns ?? definition?.columns;
+    const views = askedViews ?? definition?.views ?? ["table"];
+    const filters = askedFilters ?? definition?.filters ?? [];
+    const title = askedTitle ?? definition?.title;
+    const description = askedDescription ?? definition?.description;
+    const copy = frameworkCopy().list;
+    const { meta, locale, count, page } = listing;
+    const identity = meta?.identity ?? "id";
+    const idOf = (row) => String(row[identity]);
+    const failed = listing.status === "failed" ? explain(listing.error) : null;
+    const dropped = listing.dropped.map((d) => viewOf(meta, d.field, locale).label);
+    const [present, setPresent] = useState(views[0] ?? "table");
+    // Opened to choose on what was typed in a picker (`chooserRef(query)`): it starts searched.
+    const asked = api?.self.params?.[QUERY_PARAM] ?? "";
+    // The box's text is a draft until Enter: typing asks the server nothing.
+    const [draft, setDraft] = useState(asked === "" ? listing.text : asked);
+    useEffect(() => {
+        if (asked !== "" && search === "box")
+            listing.search(asked, { now: true });
+        // Once, as it opens: what the person types next is theirs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    // Opened by `api.pick` (`entity.chooserRef()`): a row ANSWERS whoever asked, it does not open.
+    const choosing = api?.self.params?.[PICK_PARAM] !== undefined;
+    // The record opened from a row knows the page it came from: «3 / 64» and its neighbours.
+    const { trails } = useFramework();
+    const trailKey = `trail:${useId()}`;
+    // Kept current with the page on screen: the row and its name (`RecordLink`) open the same
+    // reference, and whichever opens it, the record finds where it came from.
+    useEffect(() => {
+        if (api === undefined)
+            return;
+        const pages = listing.paging === "pages";
+        trails.set(trailKey, {
+            route: listing.route,
+            question: listing.question,
+            key: identity,
+            ids: listing.rows.map(idOf),
+            offset: pages ? Math.max(0, listing.page.from - 1) : 0,
+            size: listing.page.size,
+            cursors: pages ? listing.page.cursors : [null],
+            after: pages ? listing.page.after : null,
+            total: pages ? (listing.count?.value ?? null) : listing.rows.length,
+        });
+        // Never forgotten when the list unmounts — the record it opened replaced it and still walks
+        // on it — so the oldest go past a ceiling instead: one per list ever shown, fifty at most.
+        for (const old of trails.keys()) {
+            if (trails.size <= TRAILS)
+                break;
+            if (old !== trailKey)
+                trails.delete(old);
+        }
+        // The page on screen is what the trail is: its rows, its cursors, its count.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [
+        api,
+        trails,
+        trailKey,
+        listing.rows,
+        listing.count,
+        listing.page.from,
+        listing.page.after,
+    ]);
+    const refOf = (row) => {
+        const ref = listing.entity.ref(idOf(row));
+        return { ...ref, params: { ...ref.params, [TRAIL_PARAM]: trailKey } };
+    };
+    const openWithTrail = (row) => api?.open(refOf(row));
+    const opening = onOpen ??
+        (api === undefined
+            ? undefined
+            : choosing
+                ? (row) => api.answer(listing.entity.ref(idOf(row)))
+                : openWithTrail);
+    const creating = create &&
+        api !== undefined &&
+        !choosing &&
+        !embedded &&
+        listing.entity.create !== undefined
+        ? () => api.open(listing.entity.newRef())
+        : undefined;
+    // A row click opens the page — the composer's one predictable gesture. web-ui's table turns a
+    // row click into a PEEK whenever `onPeek` is given, so the list never passes one by itself:
+    // the peek, the side panel and the window are the composer's `RecordLink` on the identity.
+    const linked = api === undefined || choosing || cells?.[identity] !== undefined
+        ? cells
+        : {
+            ...cells,
+            [identity]: (row) => (_jsx(RecordLink, { api: api, resource: refOf(row), children: idOf(row) })),
+        };
+    // `useCrumbs`, not `api.crumbs()`: the crumb must follow a name given later (`setTitle`).
+    // Without a workspace it reads a trail that never changes — a hook cannot be skipped.
+    const following = useCrumbs(api ?? NO_WORKSPACE);
+    const trail = crumbs ?? (embedded || api === undefined ? undefined : following);
+    const [ticked, setTicked] = useState(() => new Set());
+    const tick = (next) => {
+        setTicked(next);
+        api?.select([...next].map((id) => listing.entity.ref(id)));
+    };
+    const selection = selectable
+        ? {
+            has: (id) => ticked.has(id),
+            toggle: (id) => {
+                const next = new Set(ticked);
+                if (next.has(id))
+                    next.delete(id);
+                else
+                    next.add(id);
+                tick(next);
+            },
+            count: ticked.size,
+            clear: () => tick(new Set()),
+            ...(selectionActions === undefined ? {} : { actions: selectionActions }),
+        }
+        : undefined;
+    // Rebuilt only when what it reads changes: a new set of columns on every render redraws
+    // every cell of the table. `columns` is compared by content (it is usually a literal);
+    // `cells` by identity, since its functions may close over state — memoise it to keep this.
+    const names = columns?.join("\u0000");
+    const shown = useMemo(() => columnsOf(meta, columns, { locale, ...(linked ? { cells: linked } : {}) }), 
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [meta, locale, names, cells, api]);
+    // A row and a card read the record by its display and the first fields shown beside it.
+    const display = meta?.display || identity;
+    const facts = shown
+        .filter((c) => c.id !== display && c.id !== identity && !c.defaultHidden)
+        .slice(0, 3);
+    const rowOf = (row) => ({
+        name: textOf(meta, display, row[display], locale) ?? idOf(row),
+        meta: [
+            ...(display === identity ? [] : [idOf(row)]),
+            ...facts.map((c) => textOf(meta, c.id, row[c.id], locale)).filter(Boolean),
+        ].join(" · "),
+    });
+    // Grouped: the SERVER counts the groups; a group's rows are read when it is opened, so every
+    // group starts closed. web-ui's table groups the rows it holds — the page — so a grouped list
+    // shows rows, the face that draws the piles it is given.
+    const groups = useGroups(listing, sums === undefined ? {} : { sums: sums || [] });
+    const grouped = groups.levels.length > 0;
+    const { piles, bucketAt } = pilesOf(groups.buckets, groups.levels, meta, locale, groups.rowsOf);
+    const [opened, setOpened] = useState(() => new Set());
+    useEffect(() => setOpened(new Set()), [groups.buckets]);
+    const collapsed = [...bucketAt.keys()].filter((key) => !opened.has(key));
+    const toggle = (key) => {
+        const next = new Set(opened);
+        if (next.has(key))
+            next.delete(key);
+        else {
+            next.add(key);
+            const bucket = bucketAt.get(key);
+            const deepest = bucket !== undefined && (bucket.groups ?? []).length === 0;
+            if (deepest && groups.rowsOf(bucket) === undefined)
+                groups.open(bucket);
+        }
+        setOpened(next);
+    };
+    const failure = grouped && groups.status === "failed" ? explain(groups.error) : grouped ? null : failed;
+    const grouping = grouped
+        ? {
+            group: {
+                levels: groups.levels,
+                of: (row, level) => String(row[level.field] ?? ""),
+                piles,
+                collapsed,
+                onToggle: toggle,
+            },
+        }
+        : {};
+    const records = groups.buckets.reduce((sum, bucket) => sum + bucket.count, 0);
+    // A row's actions: the entity's Commands, then whatever else the screen offers.
+    const rowCommands = useRowCommands(listing, commands);
+    const rowActions = commands.length === 0 && askedRowActions === undefined
+        ? undefined
+        : (row) => [...rowCommands.rowActions(row), ...(askedRowActions?.(row) ?? [])];
+    const refused = rowCommands.error === null ? null : explain(rowCommands.error);
+    return (_jsxs(List, { items: listing.rows, keyOf: idOf, embedded: embedded, present: grouped ? "rows" : present, onPresentChange: (next) => setPresent(next), ...grouping, sort: listing.order === null
+            ? null
+            : { key: listing.order.field, direction: listing.order.descending ? "desc" : "asc" }, onSortChange: (next) => listing.orderBy(next === null ? null : { field: next.key, descending: next.direction === "desc" }), state: {
+            // Only the FIRST reading shows the skeleton. Refining (typing, a filter, the next
+            // page) keeps the rows on screen until the server answers: web-ui swaps the body for
+            // a skeleton while `loading`, and a row that vanished under the pointer lost a click.
+            loading: grouped
+                ? groups.status === "loading"
+                : listing.status === "loading" && listing.rows.length === 0,
+            error: failure === null
+                ? null
+                : [failure.heading, failure.sentence].filter(Boolean).join(". "),
+        }, filtered: listing.where !== undefined || listing.text !== "", empty: {
+            sentence: empty ?? copy.empty,
+            whenFiltered: { sentence: copy.emptyFiltered },
+        }, ...(selection === undefined ? {} : { selection }), ...(opening === undefined ? {} : { onOpen: opening }), ...(onPeek === undefined ? {} : { onPeek }), children: [_jsxs(List.Bar, { children: [trail === undefined || trail.length === 0 ? null : _jsx(List.Crumbs, { crumbs: trail }), embedded ? null : (_jsx(List.Identity, { title: title ?? nameOf(meta, locale), ...(description === undefined ? {} : { description }) })), search === "bar" ? (_jsx(List.Search, { children: _jsx(EntitySearchBar, { listing: listing, filters: filters, groups: groups, ...(asked === "" ? {} : { seed: asked }) }) })) : null, search === "box" && meta?.search != null ? (_jsx(List.Search, { children: _jsx(SearchField, { value: draft, onChange: (next) => {
+                                setDraft(next);
+                                // Emptied (or cleared with ×): the whole set again, at once.
+                                if (next === "" && listing.text !== "")
+                                    listing.search("", { now: true });
+                            }, onSubmit: (text) => listing.search(text, { now: true }), placeholder: copy.search, "aria-label": copy.search }) })) : null, actions === undefined && creating === undefined ? null : (_jsxs(List.Actions, { children: [actions, creating === undefined ? null : (_jsx(Button, { role: "primary", size: "sm", onClick: creating, children: frameworkCopy().record.create }))] })), _jsxs(List.Pagination, { children: [dropped.length === 0 ? null : (_jsx(Tag, { tone: "warn", title: copy.dropped(dropped), children: copy.dropped(dropped) })), grouped ? (groups.status !== "ready" ? null : (_jsx("span", { className: "text-meta text-muted", children: groups.capped
+                                    ? copy.groupsCapped(groups.buckets.length)
+                                    : copy.groups(groups.buckets.length, records) }))) : listing.paging === "pages" ? (page.from === 0 ? null : (_jsx(Pagination, { from: page.from, to: page.to, total: count?.value ?? page.to, ...(page.hasPrev ? { onPrev: listing.prev } : {}), ...(page.hasNext ? { onNext: listing.next } : {}) }))) : (_jsxs(_Fragment, { children: [count === null ? null : (_jsx("span", { className: "text-meta text-muted", children: copy.shown(listing.rows.length, count.value, count.exact) })), listing.capped ? (_jsx("span", { className: "text-meta text-muted", children: copy.capped(listing.rows.length) })) : listing.hasMore ? (_jsx(Button, { size: "sm", role: "secondary", disabled: listing.status === "loadingMore", onClick: listing.more, children: listing.status === "loadingMore" ? copy.loading : copy.loadMore })) : null] }))] })] }), views.includes("table") ? (_jsx(List.Table, { columns: shown, ...(rowActions === undefined ? {} : { rowActions }) })) : null, _jsx(List.Rows, { row: rowOf }), views.includes("board") ? _jsx(List.Board, {}) : null, refused === null ? null : (_jsx(Callout, { tone: "bad", title: refused.heading, children: refused.sentence }))] }));
+}

package/dist/web/list/EntitySearchBar.d.ts

@@ -0,0 +1,34 @@
+import { type AnyRecord } from "@sincpro/criteria";
+import type { NamedFilter } from "../../core/list.js";
+import type { Groups } from "../../react/useGroups.js";
+import type { Listing } from "../../react/useListing.js";
+/**
+ * web-ui's search bar and criteria builder, bound to a `Listing`.
+ *
+ * Context: this is the «search over a set» every collection screen needs — a list, the lines
+ * of a record, a chooser — so it is a piece of its own, not something only `EntityList` can do.
+ * A screen that writes its own `List` drops it in `List.Search` and gets the same behaviour:
+ *
+ *   - a free text is the entity's LITERAL search — its whole template, every field at once
+ *     (sincpro_framework's `LiteralSearch`, the same question a many2one and ⌘K ask): it is
+ *     what Enter puts, unless the model reads the text as a question of its own;
+ *   - «search by name»: facets are the fields the entity's search template names first;
+ *   - a typed question («total > 5000») is checked against each field's operators;
+ *   - a named filter is one click; the builder writes what nobody foresaw (all/any/not);
+ *   - everything put becomes ONE `where` the SERVER answers (`listing.filter`);
+ *   - with `groups`, «Group by» offers the fields the model says may split the set, and the
+ *     SERVER counts the groups (`useGroups`).
+ *
+ *     <List.Search><EntitySearchBar listing={listing} filters={…} /></List.Search>
+ */
+export type { NamedFilter };
+export declare function EntitySearchBar<T extends AnyRecord>({ listing, filters, groups, seed, }: {
+    listing: Listing<T>;
+    /** The cuts this set offers by name: «sólo pagadas», «vencidas». */
+    filters?: readonly NamedFilter<T>[];
+    /** The grouping of the same set (`useGroups(listing)`): offers «Group by». */
+    groups?: Groups<T>;
+    /** A text to start on, put as the literal search chip — what was typed in a picker whose
+     *  «Buscar más…» opened this list. */
+    seed?: string;
+}): import("react").JSX.Element | null;

package/dist/web/list/EntitySearchBar.js

@@ -0,0 +1,73 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { matching } from "@sincpro/criteria";
+import { frameworkCopy } from "../../core/copy.js";
+import { groupableOf } from "./groups.js";
+import { facetsOf, modelOf } from "./search.js";
+import { CriteriaBuilder, describeFilter, Dialog, fillCopy, filterCriteria, GroupingLevels, hasNamed, SearchBar, toggleNamed, useGroupingControl, useUiCopy, whereOf, } from "@sincpro/web-ui";
+import { useEffect, useMemo, useRef, useState } from "react";
+/** No grouping: one constant, so the control is not handed a new array on every render. */
+const NO_LEVELS = [];
+export function EntitySearchBar({ listing, filters = [], groups, seed, }) {
+    const copy = frameworkCopy().list;
+    const { meta, locale } = listing;
+    const [put, setPut] = useState([]);
+    const [building, setBuilding] = useState(false);
+    const model = useMemo(() => (meta ? modelOf(meta, locale) : undefined), [meta, locale]);
+    const facets = useMemo(() => (meta ? facetsOf(meta, locale) : []), [meta, locale]);
+    const groupable = useMemo(() => groupableOf(meta, locale), [meta, locale]);
+    const ui = useUiCopy();
+    const seeded = useRef(false);
+    useEffect(() => {
+        if (seeded.current || seed === undefined || seed === "" || meta?.search == null)
+            return;
+        seeded.current = true;
+        const where = matching(meta, seed).where;
+        if (where === undefined)
+            return;
+        const chip = filterCriteria(where, fillCopy(ui.search.literalChip, { text: seed }));
+        setPut([chip]);
+        listing.filter(whereOf([chip]));
+        // Once the definition is known; what the person changes afterwards is theirs.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [meta, seed]);
+    const control = useGroupingControl({
+        levels: groups?.levels ?? NO_LEVELS,
+        onLevelsChange: (next) => groups?.group(next),
+    });
+    if (model === undefined)
+        return null;
+    const place = (next) => {
+        setPut(next);
+        listing.filter(whereOf(next));
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(SearchBar, { facets: facets, model: model, criteria: put, onCriteriaChange: place, placeholder: copy.searchBar, ...(filters.length === 0
+                    ? {}
+                    : {
+                        filters: [
+                            {
+                                options: filters.map((one) => ({
+                                    id: one.id,
+                                    label: one.label,
+                                    checked: hasNamed(put, one.id),
+                                })),
+                            },
+                        ],
+                        onFilterSelect: (id) => {
+                            const named = filters.find((one) => one.id === id);
+                            if (named !== undefined)
+                                place(toggleNamed(put, { ...named, where: named.where }));
+                        },
+                    }), ...(groups === undefined || groupable.length === 0
+                    ? {}
+                    : { grouping: _jsx(GroupingLevels, { fields: groupable, control: control }) }), onOpenBuilder: () => setBuilding(true), ...(meta?.search == null
+                    ? {}
+                    : {
+                        literal: (text) => matching(meta, text).where ?? null,
+                    }) }), building ? (_jsx(Dialog, { open: true, width: "lg", title: copy.builder, onClose: () => setBuilding(false), children: _jsx(CriteriaBuilder, { model: model, ...(whereOf(put) === undefined ? {} : { initial: { where: whereOf(put) } }), onApply: (built) => {
+                        place(built?.where === undefined
+                            ? []
+                            : [filterCriteria(built.where, describeFilter(built.where, model))]);
+                        setBuilding(false);
+                    }, onCancel: () => setBuilding(false) }) })) : null] }));
+}

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

@@ -0,0 +1,22 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+import type { DataColumn } from "@sincpro/web-ui";
+import type { ReactNode } from "react";
+/**
+ * The columns of a table, from the model: name the fields, the rest follows.
+ *
+ * Context: forge's lists wrote every column by hand — `header: "nombre"`, `value: (p) =>
+ * p.display_name`, a date formatter per screen — while the server already said what each field
+ * is called and what type it holds. Here a column is a NAME: its header is the model's label,
+ * its cell the text the value reads as (`textOf`), its sort key the raw value, and whether it
+ * can be ordered is what the server said (`sortable`). A cell that needs more than text — a
+ * link, a tag — is the one thing a screen writes (`cells`).
+ *
+ * The fields NOT named still exist: they come after, `optional` and hidden, so the columns
+ * menu offers them and nobody edits the screen to see a field the server already sends.
+ */
+export type ColumnOptions<T> = {
+    locale?: string | undefined;
+    /** The cells that are not plain text, by field name. */
+    cells?: Readonly<Partial<Record<string, (row: T) => ReactNode>>>;
+};
+export declare function columnsOf<T extends AnyRecord>(meta: Meta | null | undefined, names?: readonly string[], options?: ColumnOptions<T>): DataColumn<T>[];

package/dist/web/list/columns.js

@@ -0,0 +1,27 @@
+import { BOOKKEEPING, defaultFields, sortKeyOf, textOf, viewOf, } from "../../core/present.js";
+function columnOf(meta, name, options, hidden) {
+    const view = viewOf(meta, name, options.locale);
+    const text = (row) => textOf(meta, name, row[name], options.locale) ?? "";
+    const own = options.cells?.[name];
+    return {
+        id: name,
+        header: view.label,
+        field: name,
+        value: (row) => sortKeyOf(meta, name, row[name]),
+        cell: own ?? text,
+        text,
+        numeric: view.numeric,
+        sortable: view.sortable,
+        ...(view.name === meta?.identity ? { mono: true } : {}),
+        ...(hidden ? { optional: true, defaultHidden: true } : {}),
+    };
+}
+export function columnsOf(meta, names, options = {}) {
+    const all = defaultFields(meta);
+    const shown = names ?? all.filter((name) => !BOOKKEEPING.has(name));
+    const rest = all.filter((name) => !shown.includes(name));
+    return [
+        ...shown.map((name) => columnOf(meta, name, options, false)),
+        ...rest.map((name) => columnOf(meta, name, options, true)),
+    ];
+}

package/dist/web/list/groups.d.ts

@@ -0,0 +1,15 @@
+import { type AnyRecord, type Bucket, type Meta } from "@sincpro/criteria";
+import type { GroupLevel } from "../../react/useGroups.js";
+import { type GroupableField, type Pile } from "@sincpro/web-ui";
+/** The fields the model says may split a set (`groupable`), in its words. The identity splits
+ *  into groups of one, and the version means nothing to a person: neither is offered. */
+export declare function groupableOf(meta: Meta | null, locale?: string): GroupableField[];
+/**
+ * The server's groups as piles, with the words a person reads, and each pile's group so that
+ * opening one reads its rows. Rows sit only on the deepest level, once read.
+ */
+export declare function pilesOf<T extends AnyRecord>(buckets: readonly Bucket<T>[], levels: readonly GroupLevel[], meta: Meta | null, locale: string | undefined, rowsOf: (bucket: Bucket<T>) => readonly T[] | undefined): {
+    piles: Pile<T>[];
+    bucketAt: ReadonlyMap<string, Bucket<T>>;
+    deepest: number;
+};

package/dist/web/list/groups.js

@@ -0,0 +1,73 @@
+import { labelOf } from "@sincpro/criteria";
+import { frameworkCopy } from "../../core/copy.js";
+import { detailOf } from "../../core/measure.js";
+import { textOf } from "../../core/present.js";
+import { dateLabel, pathKey, } from "@sincpro/web-ui";
+/**
+ * Grouping, as web-ui draws it: which fields may split a set, and the server's groups as the
+ * piles a `List` shows.
+ *
+ * Context: web-ui keeps «what was asked» (`GroupLevel`) apart from «what is drawn» (`Pile`)
+ * precisely so that piles can come counted from whoever keeps the data. These are the two
+ * translations from the model and from criteria's `Bucket`.
+ */
+/** The cuts a date offers, coarse to fine — web-ui orders the levels by them. */
+const DATE_GRAINS = ["year", "quarter", "month", "week", "day"];
+/** The fields the model says may split a set (`groupable`), in its words. The identity splits
+ *  into groups of one, and the version means nothing to a person: neither is offered. */
+export function groupableOf(meta, locale) {
+    if (meta === null)
+        return [];
+    return Object.entries(meta.fields)
+        .filter(([name, field]) => field.groupable === true &&
+        field.kind === "scalar" &&
+        name !== meta.identity &&
+        name !== "version")
+        .map(([name, field]) => ({
+        field: name,
+        label: labelOf(meta, name, locale),
+        ...(field.type === "date" || field.type === "datetime" ? { grains: DATE_GRAINS } : {}),
+    }));
+}
+/**
+ * The server's groups as piles, with the words a person reads, and each pile's group so that
+ * opening one reads its rows. Rows sit only on the deepest level, once read.
+ */
+export function pilesOf(buckets, levels, meta, locale, rowsOf) {
+    const bucketAt = new Map();
+    const none = frameworkCopy().list.noValue;
+    const labelFor = (bucket, depth, key) => {
+        const level = levels[depth];
+        if (bucket.value === null || bucket.value === undefined || bucket.value === "")
+            return none;
+        if (level?.grain) {
+            const within = levels
+                .slice(0, depth)
+                .flatMap((one) => (one.field === level.field && one.grain ? [one.grain] : []));
+            return dateLabel(key, level.grain, within);
+        }
+        return textOf(meta, bucket.field, bucket.value, locale) || key;
+    };
+    const detailed = (bucket) => {
+        const detail = detailOf(meta, bucket.measures, locale);
+        return detail === undefined ? {} : { detail };
+    };
+    const walk = (level, above, depth) => level.map((bucket) => {
+        const key = bucket.value === null || bucket.value === undefined ? "" : String(bucket.value);
+        const path = [...above, key];
+        bucketAt.set(pathKey(path), bucket);
+        const below = bucket.groups ?? [];
+        return {
+            path,
+            depth,
+            field: bucket.field,
+            key,
+            label: labelFor(bucket, depth, key),
+            count: bucket.count,
+            ...detailed(bucket),
+            items: below.length === 0 ? [...(rowsOf(bucket) ?? [])] : [],
+            piles: walk(below, path, depth + 1),
+        };
+    });
+    return { piles: walk(buckets, [], 0), bucketAt, deepest: levels.length - 1 };
+}

package/dist/web/list/rowCommands.d.ts

@@ -0,0 +1,41 @@
+import { type AnyRecord, type Expression } from "@sincpro/criteria";
+import type { Listing } from "../../react/useListing.js";
+import type { RowAction } from "@sincpro/web-ui";
+import type { LucideIcon } from "lucide-react";
+/**
+ * An entity's Commands as the actions of a row: «Confirmar» on each invoice, without opening it.
+ *
+ * Context: web-ui draws a row's actions (`rowActions`) and knows nothing of what they do; the
+ * entity knows its Commands and their routes. This joins them, with the rules a Command keeps
+ * everywhere: sent once per gesture with its `Idempotency-Key` (a retry is the same Command),
+ * the row's action disabled while it runs, and the list read again when it is done — the server
+ * says what the row became. `when` is a condition over the row, evaluated the way the server's
+ * hints are (`matches`): «Confirmar» only on drafts.
+ *
+ * Only Commands that can be undone belong on a row. One that destroys is confirmed by its dry
+ * run, and that is the record's `CommandButton`, where the consequence has room to be read.
+ *
+ *     const commands = useRowCommands(listing, [
+ *       { command: "confirmar", label: "Confirmar", icon: Check,
+ *         when: { field: "state", operator: "=", value: "draft" } },
+ *     ]);
+ *     <EntityList listing={listing} rowActions={commands.rowActions} />
+ */
+export type RowCommand<T> = {
+    /** A Command the entity declares (`entity({ commands })`). */
+    command: string;
+    label: string;
+    icon: LucideIcon;
+    tone?: RowAction["tone"];
+    /** Offered only on rows that hold it — a hint, not protection: the server decides. */
+    when?: Expression<T>;
+    /** What the Command is sent with. Without it, an empty body: the route names the row. */
+    body?: (row: T) => AnyRecord;
+};
+export type RowCommands<T> = {
+    rowActions: (row: T) => readonly RowAction[];
+    /** The last refusal, until `dismiss`. */
+    error: unknown;
+    dismiss: () => void;
+};
+export declare function useRowCommands<T extends AnyRecord>(listing: Listing<T>, commands: readonly RowCommand<T>[]): RowCommands<T>;

package/dist/web/list/rowCommands.js

@@ -0,0 +1,56 @@
+"use client";
+import { matches } from "@sincpro/criteria";
+import { pathFor } from "../../core/entity.js";
+import { retryKeys } from "../../core/retry.js";
+import { useFramework } from "../../react/context.js";
+import { useCallback, useState } from "react";
+export function useRowCommands(listing, commands) {
+    const { transport } = useFramework();
+    const [running, setRunning] = useState(new Set());
+    const [error, setError] = useState(null);
+    // One key per row and Command, kept while it goes unanswered: retrying is the same gesture.
+    const [keys] = useState(() => new Map());
+    const { entity, meta } = listing;
+    const key = meta?.get_id || meta?.identity || "id";
+    const run = useCallback(async (one, row) => {
+        const route = entity.commands[one.command];
+        if (route === undefined)
+            throw new Error(`${entity.key} declares no command "${one.command}"`);
+        const id = String(row[key]);
+        const gesture = `${one.command}\u0000${id}`;
+        const retry = keys.get(gesture) ?? retryKeys();
+        keys.set(gesture, retry);
+        const body = one.body?.(row) ?? {};
+        setRunning((now) => new Set(now).add(gesture));
+        setError(null);
+        try {
+            await transport.send(route.method, pathFor(route, id), body, undefined, {
+                idempotencyKey: retry.keyFor(body),
+            });
+            retry.settle(null);
+            listing.reload();
+        }
+        catch (failure) {
+            retry.settle(failure);
+            setError(failure);
+        }
+        finally {
+            setRunning((now) => {
+                const next = new Set(now);
+                next.delete(gesture);
+                return next;
+            });
+        }
+    }, [transport, entity, key, keys, listing]);
+    const rowActions = (row) => commands
+        .filter((one) => meta === null || one.when === undefined || matches(row, one.when, meta))
+        .map((one) => ({
+        id: one.command,
+        label: one.label,
+        icon: one.icon,
+        ...(one.tone === undefined ? {} : { tone: one.tone }),
+        disabled: running.has(`${one.command}\u0000${String(row[key])}`),
+        onSelect: () => void run(one, row),
+    }));
+    return { rowActions, error, dismiss: () => setError(null) };
+}

package/dist/web/list/search.d.ts

@@ -0,0 +1,21 @@
+import { type Meta } from "@sincpro/criteria";
+import type { ModelDefinition, SearchFacet } from "@sincpro/web-ui";
+/**
+ * The model, as web-ui's search bar and criteria builder read it.
+ *
+ * Context: web-ui keeps its OWN vocabulary of a model (`ModelDefinition`), written before the
+ * framework settled its wire, and the two drifted: `identifiedBy` against `identified_by`, one
+ * `translations` object against a `label` on each field. web-ui is right to own it — it is a
+ * design system and must not depend on one backend — so the translation lives here, the one
+ * place that knows both.
+ *
+ * Known gap: web-ui's field has `choices` but no word for each choice, so the bar offers an
+ * enum's raw values («paid») where a cell says «Pagada». Fixing it is web-ui's.
+ */
+export declare function modelOf(meta: Meta, locale?: string): ModelDefinition;
+/**
+ * Where a typed text can be looked for: the fields the entity's own search template names
+ * first (what «search by name» means for THIS entity), then every other text field it can
+ * filter on.
+ */
+export declare function facetsOf(meta: Meta, locale?: string): SearchFacet[];