@sincpro/web-framework 0.1.0 → 0.2.0

package/dist/react/useRecord.js

@@ -1,19 +1,30 @@
 "use client";
-import { changesOf, errorsByField, fieldStateOf, missingOf, } from "../core/edit.js";
+import { changesOf, creationOf, defaultsOf, errorsByField, fieldStateOf, missingOf, } from "../core/edit.js";
 import { pathFor } from "../core/entity.js";
+import { retryKeys } from "../core/retry.js";
 import { TransportError } from "../core/transport.js";
 import { useFramework } from "./context.js";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 /** How long typing has to pause before the server is asked what the record becomes. */
 const PREVIEW_PAUSE = 300;
-export function useRecord(entity, id) {
+export function useRecord(entity, given) {
     const { transport, locale, metas } = useFramework();
+    // A create that answered its identity turns this into that record — until the screen asks
+    // for another one.
+    const [born, setBorn] = useState(null);
+    const id = born !== null && born.from === given ? born.id : given;
+    const isNew = id === "";
+    const [created, setCreated] = useState(null);
+    const creating = useRef(retryKeys());
     const [state, setState] = useState({
         status: "loading",
         record: null,
         meta: null,
         error: null,
     });
+    // Which record `state` was read for: the render after the id changed — a create that answered,
+    // another record asked — must not show the previous one under the new id.
+    const [readFor, setReadFor] = useState(null);
     const [round, setRound] = useState(0);
     const [typed, setTyped] = useState({});
     const [computed, setComputed] = useState({});
@@ -45,13 +56,49 @@ export function useRecord(entity, id) {
     };
     useEffect(() => {
         const aborter = new AbortController();
-        setState((now) => ({ status: "loading", record: null, meta: now.meta, error: null }));
+        // Read again — after a save, a reload — the record on screen STAYS until the answer: a form
+        // that blinked through a skeleton lost its focus, its scroll and the click that landed then.
+        // Only a record not shown yet (another id, the first read) starts as «loading».
+        const again = !isNew && readFor === id;
+        if (!again)
+            setState((now) => ({ status: "loading", record: null, meta: now.meta, error: null }));
+        if (isNew) {
+            // Nothing to read but the model: known already, or asked of the list with no rows.
+            const known = metas.get(entity.key);
+            const asked = known
+                ? Promise.resolve(known)
+                : transport
+                    .list(entity.list, { pagination: { limit: 1 } }, aborter.signal)
+                    .then((page) => page.meta);
+            asked.then((meta) => {
+                if (meta)
+                    metas.set(entity.key, meta);
+                if (aborter.signal.aborted)
+                    return;
+                forget();
+                setDraft(null);
+                setReadFor(id);
+                setState({
+                    status: "ready",
+                    record: defaultsOf(meta),
+                    meta: meta ?? null,
+                    error: null,
+                });
+            }, (error) => {
+                if (aborter.signal.aborted)
+                    return;
+                setReadFor(id);
+                setState((now) => ({ status: "failed", record: null, meta: now.meta, error }));
+            });
+            return () => aborter.abort();
+        }
         transport.one(entity.one(id), aborter.signal).then((answer) => {
             if (answer.meta)
                 metas.set(entity.key, answer.meta);
             if (aborter.signal.aborted)
                 return;
             forget();
+            setReadFor(id);
             setDraft(answer.draft);
             if (answer.draft)
                 setTyped(answer.draft.values);
@@ -62,14 +109,16 @@ export function useRecord(entity, id) {
                 error: null,
             });
         }, (error) => {
-            if (!aborter.signal.aborted)
-                setState((now) => ({ status: "failed", record: null, meta: now.meta, error }));
+            if (aborter.signal.aborted)
+                return;
+            setReadFor(id);
+            setState((now) => ({ status: "failed", record: null, meta: now.meta, error }));
         });
         return () => aborter.abort();
         // `forget` only resets this hook's own state; listing it would reload the record on every
         // render. What reloads it is the transport, the entity, the id or an explicit `reload()`.
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [transport, metas, entity, id, round]);
+    }, [transport, metas, entity, id, isNew, round]);
     useEffect(() => {
         mounted.current = true;
         return () => {
@@ -91,7 +140,11 @@ export function useRecord(entity, id) {
             const aborter = new AbortController();
             asking.current = aborter;
             transport
-                .send(preview.method, pathFor(preview, id), { id, values: changesOf(record, next), changed: [name] }, aborter.signal)
+                .send(preview.method, pathFor(preview, isNew ? undefined : id), {
+                id: isNew ? null : id,
+                values: isNew ? { ...record, ...next } : changesOf(record, next),
+                changed: [name],
+            }, aborter.signal)
                 .then((answer) => {
                 if (aborter.signal.aborted || !mounted.current)
                     return;
@@ -126,6 +179,8 @@ export function useRecord(entity, id) {
         restored: draft !== null && Object.keys(changed).length > 0,
         draft,
         save: async () => {
+            if (isNew)
+                return create();
             const route = entity.save;
             if (route === undefined)
                 throw new Error(`${entity.key} declares no save route`);
@@ -154,7 +209,8 @@ export function useRecord(entity, id) {
             }
         },
         discard: forget,
-        ...(entity.draft === undefined
+        created,
+        ...(entity.draft === undefined || isNew
             ? {}
             : {
                 keep: async () => {
@@ -172,5 +228,45 @@ export function useRecord(entity, id) {
                 },
             }),
     };
-    return { ...state, entity, locale, reload, edit };
+    async function create() {
+        const route = entity.create;
+        if (route === undefined)
+            throw new Error(`${entity.key} declares no create route`);
+        cancelPreview();
+        setSaving(true);
+        setFailure(null);
+        setCreated(null);
+        const body = creationOf(state.meta, values);
+        const idempotencyKey = creating.current.keyFor(body);
+        try {
+            const answer = await transport.send(route.method, pathFor(route), body, undefined, { idempotencyKey });
+            creating.current.settle(null);
+            if (!mounted.current)
+                return true;
+            const key = state.meta?.get_id || state.meta?.identity || "id";
+            const made = typeof answer === "object" && answer !== null
+                ? answer[key]
+                : undefined;
+            forget();
+            if (typeof made === "string" || typeof made === "number")
+                setBorn({ from: given, id: String(made) });
+            else
+                setCreated(answer);
+            return true;
+        }
+        catch (error) {
+            creating.current.settle(error);
+            if (mounted.current)
+                refused(error);
+            return false;
+        }
+        finally {
+            if (mounted.current)
+                setSaving(false);
+        }
+    }
+    const shown = readFor === id
+        ? state
+        : { status: "loading", record: null, meta: state.meta, error: null };
+    return { ...shown, entity, id, isNew, locale, reload, edit };
 }

package/dist/react/useSummary.d.ts

@@ -0,0 +1,15 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import { type RecordSummary } from "../core/summary.js";
+/**
+ * The summary of any record of an entity, read with the model this application already knows
+ * for it (a list or a record of it was read, or `metas` preloaded it) and in its language.
+ *
+ * Context: a function, not a summary, so a list of N rows asks once and summarizes each row.
+ * The model is looked up on every call: it may arrive after the first render (the first page
+ * of a list brings it), and the next render of whoever holds the rows reads it.
+ *
+ *     const summarize = useSummaryOf(contactos);
+ *     <RecordCard {...cardOf(summarize(row))} />
+ */
+export declare function useSummaryOf<T extends AnyRecord>(entity: Entity<T>): (record: AnyRecord, meta?: Meta | null) => RecordSummary;

package/dist/react/useSummary.js

@@ -0,0 +1,22 @@
+"use client";
+import { summaryOf } from "../core/summary.js";
+import { useFramework } from "./context.js";
+import { useCallback } from "react";
+/**
+ * The summary of any record of an entity, read with the model this application already knows
+ * for it (a list or a record of it was read, or `metas` preloaded it) and in its language.
+ *
+ * Context: a function, not a summary, so a list of N rows asks once and summarizes each row.
+ * The model is looked up on every call: it may arrive after the first render (the first page
+ * of a list brings it), and the next render of whoever holds the rows reads it.
+ *
+ *     const summarize = useSummaryOf(contactos);
+ *     <RecordCard {...cardOf(summarize(row))} />
+ */
+export function useSummaryOf(entity) {
+    const { metas, locale } = useFramework();
+    return useCallback((record, meta) => summaryOf(meta ?? metas.get(entity.key) ?? null, record, {
+        fields: entity.summary,
+        ...(locale === undefined ? {} : { locale }),
+    }), [metas, entity, locale]);
+}

package/dist/web/index.d.ts

@@ -2,16 +2,22 @@
  * The web bindings: what draws a `Listing` and a record with `@sincpro/web-ui`.
  */
 export { type ColumnOptions, columnsOf } from "./list/columns.js";
-export { EntityList, type EntityListProps, type NamedFilter, } from "./list/EntityList.js";
+export { EntityList, type EntityListProps } from "./list/EntityList.js";
 export { EntitySearchBar } from "./list/EntitySearchBar.js";
+export { groupableOf, pilesOf } from "./list/groups.js";
+export { type RowCommand, type RowCommands, useRowCommands, } from "./list/rowCommands.js";
 export { facetsOf, modelOf } from "./list/search.js";
 export { CommandButton } from "./record/CommandButton.js";
 export { dirtyOf, type FieldControl, RecordField, } from "./record/edit.js";
 export { EntityPicker } from "./record/EntityPicker.js";
+export { EntityTags } from "./record/EntityTags.js";
 export { countOf, factsOf, RecordLines } from "./record/record.js";
 export { RelatedList } from "./record/RelatedList.js";
+export { cardOf, relationOf } from "./record/summary.js";
 export { Refused } from "./Refused.js";
-export { entityView, type EntityViewOptions, } from "./workspace/composer.js";
+export { entityView, type EntityViewOptions, listView, type ListViewOptions, } from "./workspace/composer.js";
+export { openIn, openOptions, RECORD_SIZE, RelatedRecord, targetsFor, } from "./workspace/open.js";
+export { EntityRecord } from "./workspace/record.js";
 export { SincproApp } from "./workspace/SincproApp.js";
 export { webUiSkin } from "./workspace/skin.js";
-export { useRecordInWorkspace } from "./workspace/workspace.js";
+export { chooserIn, useFollowed, useRecordInWorkspace, } from "./workspace/workspace.js";

package/dist/web/index.js

@@ -2,16 +2,22 @@
  * The web bindings: what draws a `Listing` and a record with `@sincpro/web-ui`.
  */
 export { columnsOf } from "./list/columns.js";
-export { EntityList, } from "./list/EntityList.js";
+export { EntityList } from "./list/EntityList.js";
 export { EntitySearchBar } from "./list/EntitySearchBar.js";
+export { groupableOf, pilesOf } from "./list/groups.js";
+export { useRowCommands, } from "./list/rowCommands.js";
 export { facetsOf, modelOf } from "./list/search.js";
 export { CommandButton } from "./record/CommandButton.js";
 export { dirtyOf, RecordField, } from "./record/edit.js";
 export { EntityPicker } from "./record/EntityPicker.js";
+export { EntityTags } from "./record/EntityTags.js";
 export { countOf, factsOf, RecordLines } from "./record/record.js";
 export { RelatedList } from "./record/RelatedList.js";
+export { cardOf, relationOf } from "./record/summary.js";
 export { Refused } from "./Refused.js";
-export { entityView, } from "./workspace/composer.js";
+export { entityView, listView, } from "./workspace/composer.js";
+export { openIn, openOptions, RECORD_SIZE, RelatedRecord, targetsFor, } from "./workspace/open.js";
+export { EntityRecord } from "./workspace/record.js";
 export { SincproApp } from "./workspace/SincproApp.js";
 export { webUiSkin } from "./workspace/skin.js";
-export { useRecordInWorkspace } from "./workspace/workspace.js";
+export { chooserIn, useFollowed, useRecordInWorkspace, } from "./workspace/workspace.js";

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

@@ -1,8 +1,9 @@
 import { type AnyRecord } from "@sincpro/criteria";
 import { type WorkspaceApi } from "@sincpro/web-composer";
+import type { NamedFilter } from "../../core/list.js";
 import type { Listing } from "../../react/useListing.js";
-import { type NamedFilter } from "./EntitySearchBar.js";
-import { type ListCrumb } from "@sincpro/web-ui";
+import { type RowCommand } from "./rowCommands.js";
+import { type ListCrumb, type RowAction } from "@sincpro/web-ui";
 import { type ReactNode } from "react";
 /**
  * A whole collection from a `Listing`: the bar, the search, the set in the views it offers,
@@ -17,6 +18,10 @@ import { type ReactNode } from "react";
  * its ceiling and asks to narrow the search. Nothing is filtered, ordered or counted on the
  * page: every gesture is a question to the server.
  *
+ * Grouping obeys the same rule: «Group by» in the search bar asks the SERVER for the groups of
+ * the whole set (`useGroups`), drawn as piles with their real count; a group's rows are read
+ * when it is opened. Grouped, the list shows rows: web-ui's table groups the page it holds.
+ *
  * Where a record opens is the composer's question: with `api`, a row opens the page and the
  * identity column is the composer's `RecordLink` (peek, side panel, window); without it, the
  * screen passes `onOpen`.
@@ -30,7 +35,7 @@ export type EntityListProps<T extends AnyRecord> = {
      * breadcrumb is the composer's — nothing for the screen to write.
      */
     api?: WorkspaceApi;
-    /** The fields shown, in order. Without it, every scalar field of the model. */
+    /** The fields shown, in order. Without it, the named list's, or every scalar field. */
     columns?: readonly string[];
     /** The cells that are not plain text: a link, a tag. Memoise it: compared by identity. */
     cells?: Readonly<Partial<Record<string, (row: T) => ReactNode>>>;
@@ -52,8 +57,13 @@ export type EntityListProps<T extends AnyRecord> = {
     /**
      * `"bar"` (the default) is the full search bar with the criteria builder; `"box"` is one
      * text box over the entity's search template — a chooser, a narrow panel; `false` is none.
+     * Both ask the server on Enter, never per keystroke: a table is searched on purpose.
      */
     search?: "bar" | "box" | false;
+    /** What each group adds up when the list is grouped — «Total 1.204.933,00» in its header,
+     *  summed by the server over every row of it. Without it, the figures the model computes
+     *  (read-only exact numbers, `sumsOf`); `false` adds nothing up. */
+    sums?: readonly string[] | false;
     /** The cuts this list offers by name: «sólo pagadas», «vencidas». */
     filters?: readonly NamedFilter<T>[];
     /**
@@ -65,5 +75,18 @@ export type EntityListProps<T extends AnyRecord> = {
     selectionActions?: ReactNode;
     /** The list is a FIELD of a record — its lines, its members — and not a screen. */
     embedded?: boolean;
+    /**
+     * With `api` and an entity that declares `create`, the bar offers «New», which opens the
+     * record's form with no id (`entity.newRef()`). `false` hides it — a list of what only a
+     * Command produces, or a caller who may not create.
+     */
+    create?: boolean;
+    /**
+     * The entity's Commands offered on each row («Confirmar»), sent with their idempotency key;
+     * the list is read again when one is done (`useRowCommands`).
+     */
+    commands?: readonly RowCommand<T>[];
+    /** Any other action of a row — or the commands built by hand with `useRowCommands`. */
+    rowActions?: (row: T) => readonly RowAction[];
 };
-export declare function EntityList<T extends AnyRecord>({ listing, api, columns, cells, views, title, description, crumbs, actions, onOpen, onPeek, empty, search, filters, selectable, selectionActions, embedded, }: EntityListProps<T>): import("react").JSX.Element;
+export declare function EntityList<T extends AnyRecord>({ listing, api, columns: askedColumns, cells, views: askedViews, title: askedTitle, description: askedDescription, crumbs, actions, onOpen, onPeek, empty, search, sums, filters: askedFilters, selectable, selectionActions, embedded, create, commands, rowActions: askedRowActions, }: EntityListProps<T>): import("react").JSX.Element;

package/dist/web/list/EntityList.js

@@ -1,15 +1,38 @@
 "use client";
-import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { nameOf } from "@sincpro/criteria";
-import { RecordLink } from "@sincpro/web-composer";
+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 { Button, List, Pagination, SearchField, Tag } from "@sincpro/web-ui";
-import { useMemo, useState } from "react";
-export function EntityList({ listing, api, columns, cells, views = ["table"], title, description, crumbs, actions, onOpen, onPeek, empty, search = "bar", filters = [], selectable = false, selectionActions, embedded = false, }) {
+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";
@@ -17,17 +40,88 @@ export function EntityList({ listing, api, columns, cells, views = ["table"], ti
     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");
-    const opening = onOpen ?? (api ? (row) => api.open(listing.entity.ref(idOf(row))) : undefined);
+    // 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 || cells?.[identity] !== undefined
+    const linked = api === undefined || choosing || cells?.[identity] !== undefined
         ? cells
         : {
             ...cells,
-            [identity]: (row) => (_jsx(RecordLink, { api: api, resource: listing.entity.ref(idOf(row)), children: idOf(row) })),
+            [identity]: (row) => (_jsx(RecordLink, { api: api, resource: refOf(row), children: idOf(row) })),
         };
-    const trail = crumbs ?? (embedded ? undefined : api?.crumbs());
+    // `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);
@@ -68,15 +162,68 @@ export function EntityList({ listing, api, columns, cells, views = ["table"], ti
             ...facts.map((c) => textOf(meta, c.id, row[c.id], locale)).filter(Boolean),
         ].join(" · "),
     });
-    return (_jsxs(List, { items: listing.rows, keyOf: idOf, embedded: embedded, present: present, onPresentChange: (next) => setPresent(next), sort: listing.order === null
+    // 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: {
-            loading: listing.status === "loading",
-            error: failed === null
+            // 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
-                : [failed.heading, failed.sentence].filter(Boolean).join(". "),
+                : [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 }) })) : null, search === "box" && meta?.search != null ? (_jsx(List.Search, { children: _jsx(SearchField, { value: listing.text, onChange: listing.search, placeholder: copy.search, "aria-label": copy.search }) })) : null, actions === undefined ? null : _jsx(List.Actions, { children: actions }), _jsxs(List.Pagination, { children: [dropped.length === 0 ? null : (_jsx(Tag, { tone: "warn", title: copy.dropped(dropped), children: copy.dropped(dropped) })), 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 }) : null, views.includes("rows") ? _jsx(List.Rows, { row: rowOf }) : null, views.includes("board") ? _jsx(List.Board, {}) : null] }));
+        }, ...(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

@@ -1,4 +1,6 @@
-import type { AnyRecord, Expression } from "@sincpro/criteria";
+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`.
@@ -7,20 +9,26 @@ import type { Listing } from "../../react/useListing.js";
  * 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`).
+ *   - 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<T> = {
-    id: string;
-    label: string;
-    where: Expression<T>;
-};
-export declare function EntitySearchBar<T extends AnyRecord>({ listing, filters, }: {
+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;