@sincpro/web-framework 0.0.0-stage → 0.1.0

package/dist/react/useRelated.d.ts

@@ -0,0 +1,21 @@
+import type { AnyRecord, Criteria } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import type { Listing, ListingOptions } from "./useListing.js";
+import type { RecordReading } from "./useRecord.js";
+/**
+ * The records a relation of ONE record points to, as a live listing of the related entity.
+ *
+ * Context: sincpro_framework sends a one2many inside its record as ONE page (`RecordLines` draws
+ * it). A customer with forty thousand invoices, a tenant with a thousand members, the lines of a
+ * big order need more than that page: search in them, order them, walk them. The model says how
+ * to ask — the related aggregate's key that points back (`identified_by`) — so the relation is
+ * a criteria over the related entity, `where <that key> = <this record's key>`, answered by the
+ * server like any list. The relation's scope is AND-ed with everything else, so no search, filter
+ * or page can ever leave it.
+ *
+ *     const facturas = useRelated(cliente, "invoices", invoicesEntity);
+ *     <EntityList listing={facturas} embedded />
+ */
+export declare function useRelated<P extends AnyRecord, T extends AnyRecord>(record: RecordReading<P>, name: string, related: Entity<T>, options?: Omit<ListingOptions<T>, "criteria"> & {
+    criteria?: Criteria<T>;
+}): Listing<T>;

package/dist/react/useRelated.js

@@ -0,0 +1,32 @@
+"use client";
+import { useListing } from "./useListing.js";
+/**
+ * The records a relation of ONE record points to, as a live listing of the related entity.
+ *
+ * Context: sincpro_framework sends a one2many inside its record as ONE page (`RecordLines` draws
+ * it). A customer with forty thousand invoices, a tenant with a thousand members, the lines of a
+ * big order need more than that page: search in them, order them, walk them. The model says how
+ * to ask — the related aggregate's key that points back (`identified_by`) — so the relation is
+ * a criteria over the related entity, `where <that key> = <this record's key>`, answered by the
+ * server like any list. The relation's scope is AND-ed with everything else, so no search, filter
+ * or page can ever leave it.
+ *
+ *     const facturas = useRelated(cliente, "invoices", invoicesEntity);
+ *     <EntityList listing={facturas} embedded />
+ */
+export function useRelated(record, name, related, options = {}) {
+    const field = record.meta?.fields[name];
+    const key = field?.identified_by ?? "";
+    const own = record.meta?.get_id || record.meta?.identity || "id";
+    const value = record.record === null ? null : record.record[own];
+    const scope = {
+        ...options.criteria,
+        where: {
+            all: [
+                ...(options.criteria?.where ? [options.criteria.where] : []),
+                { field: key, operator: "=", value: value },
+            ],
+        },
+    };
+    return useListing(related, { pageSize: 10, ...options, criteria: scope });
+}

package/dist/web/Refused.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A failure, said the way the server said it: its title, what happened and what to do —
+ * `guidance` included, which is the part a person acts on. Retry only when retrying can help:
+ * a «you have no access» with a retry button is a button that lies.
+ */
+export declare function Refused({ error, onRetry }: {
+    error: unknown;
+    onRetry?: () => void;
+}): import("react").JSX.Element;

package/dist/web/Refused.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { frameworkCopy } from "../core/copy.js";
+import { explain } from "../core/transport.js";
+import { Button, Failed } from "@sincpro/web-ui";
+/**
+ * A failure, said the way the server said it: its title, what happened and what to do —
+ * `guidance` included, which is the part a person acts on. Retry only when retrying can help:
+ * a «you have no access» with a retry button is a button that lies.
+ */
+export function Refused({ error, onRetry }) {
+    const { heading, sentence, retryable } = explain(error);
+    return (_jsx(Failed, { heading: heading, sentence: sentence, action: onRetry !== undefined && retryable ? (_jsx(Button, { size: "sm", role: "secondary", onClick: onRetry, children: frameworkCopy().failure.retry })) : undefined }));
+}

package/dist/web/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 { EntitySearchBar } from "./list/EntitySearchBar.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 { countOf, factsOf, RecordLines } from "./record/record.js";
+export { RelatedList } from "./record/RelatedList.js";
+export { Refused } from "./Refused.js";
+export { entityView, type EntityViewOptions, } from "./workspace/composer.js";
+export { SincproApp } from "./workspace/SincproApp.js";
+export { webUiSkin } from "./workspace/skin.js";
+export { useRecordInWorkspace } from "./workspace/workspace.js";

package/dist/web/index.js

@@ -0,0 +1,17 @@
+/**
+ * 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 { EntitySearchBar } from "./list/EntitySearchBar.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 { countOf, factsOf, RecordLines } from "./record/record.js";
+export { RelatedList } from "./record/RelatedList.js";
+export { Refused } from "./Refused.js";
+export { entityView, } from "./workspace/composer.js";
+export { SincproApp } from "./workspace/SincproApp.js";
+export { webUiSkin } from "./workspace/skin.js";
+export { useRecordInWorkspace } from "./workspace/workspace.js";

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

@@ -0,0 +1,69 @@
+import { type AnyRecord } from "@sincpro/criteria";
+import { type WorkspaceApi } from "@sincpro/web-composer";
+import type { Listing } from "../../react/useListing.js";
+import { type NamedFilter } from "./EntitySearchBar.js";
+import { type ListCrumb } 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,
+ * and the way through it — the screen forge wrote five times by hand, written once.
+ *
+ * Context: this is the ready-made composition, not a cage. Everything it does is reachable on
+ * its own — `columnsOf` for the columns, `EntitySearchBar` for the search, `useListing` for the
+ * state — so a screen that needs its own bar or a second table writes `List` with those.
+ *
+ * Built for sets of any size: in `pages` mode (the default) the screen holds ONE page and walks
+ * the server's cursor, so a million rows cost what fifty do; in `more` mode it stops growing at
+ * 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.
+ *
+ * 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`.
+ */
+export type { NamedFilter };
+export type EntityListProps<T extends AnyRecord> = {
+    listing: Listing<T>;
+    /**
+     * The workspace this list is a view of. With it, a row opens its record as a page, the
+     * identity column is the composer's `RecordLink` (peek, side panel, window on hover) and the
+     * 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. */
+    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>>>;
+    /**
+     * The ways to look at the set, the first one shown: `table` (columns), `rows` (a name and
+     * its facts, what a narrow panel wants) and `board` (cards). The same set, the same search,
+     * the same page in each.
+     */
+    views?: readonly ("table" | "rows" | "board")[];
+    /** Without it, the model's own name. */
+    title?: string;
+    description?: string;
+    crumbs?: readonly ListCrumb[];
+    actions?: ReactNode;
+    onOpen?: (row: T) => void;
+    onPeek?: (row: T) => void;
+    /** What an empty list says. */
+    empty?: string;
+    /**
+     * `"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.
+     */
+    search?: "bar" | "box" | false;
+    /** The cuts this list offers by name: «sólo pagadas», «vencidas». */
+    filters?: readonly NamedFilter<T>[];
+    /**
+     * Rows can be ticked. With `api`, what is ticked is PUBLISHED to the workspace
+     * (`api.select`): a panel beside it follows the selection without knowing this list.
+     */
+    selectable?: boolean;
+    /** What to do with what is ticked: drawn in the bar while something is. */
+    selectionActions?: ReactNode;
+    /** The list is a FIELD of a record — its lines, its members — and not a screen. */
+    embedded?: boolean;
+};
+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;

package/dist/web/list/EntityList.js

@@ -0,0 +1,82 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { nameOf } from "@sincpro/criteria";
+import { RecordLink } from "@sincpro/web-composer";
+import { frameworkCopy } from "../../core/copy.js";
+import { textOf, viewOf } from "../../core/present.js";
+import { explain } from "../../core/transport.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, }) {
+    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");
+    const opening = onOpen ?? (api ? (row) => api.open(listing.entity.ref(idOf(row))) : 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
+        ? cells
+        : {
+            ...cells,
+            [identity]: (row) => (_jsx(RecordLink, { api: api, resource: listing.entity.ref(idOf(row)), children: idOf(row) })),
+        };
+    const trail = crumbs ?? (embedded ? undefined : api?.crumbs());
+    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(" · "),
+    });
+    return (_jsxs(List, { items: listing.rows, keyOf: idOf, embedded: embedded, present: present, onPresentChange: (next) => setPresent(next), 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
+                ? null
+                : [failed.heading, failed.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] }));
+}

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

@@ -0,0 +1,26 @@
+import type { AnyRecord, Expression } from "@sincpro/criteria";
+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:
+ *
+ *   - «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`).
+ *
+ *     <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, }: {
+    listing: Listing<T>;
+    /** The cuts this set offers by name: «sólo pagadas», «vencidas». */
+    filters?: readonly NamedFilter<T>[];
+}): import("react").JSX.Element | null;

package/dist/web/list/EntitySearchBar.js

@@ -0,0 +1,43 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { frameworkCopy } from "../../core/copy.js";
+import { facetsOf, modelOf } from "./search.js";
+import { CriteriaBuilder, describeFilter, Dialog, filterCriteria, hasNamed, SearchBar, toggleNamed, whereOf, } from "@sincpro/web-ui";
+import { useMemo, useState } from "react";
+export function EntitySearchBar({ listing, filters = [], }) {
+    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]);
+    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 }));
+                        },
+                    }), onOpenBuilder: () => setBuilding(true) }), 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/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[];

package/dist/web/list/search.js

@@ -0,0 +1,72 @@
+import { labelOf } from "@sincpro/criteria";
+/**
+ * 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 function modelOf(meta, locale) {
+    const names = Object.keys(meta.fields);
+    return {
+        aggregate: meta.aggregate,
+        identity: meta.identity,
+        fields: Object.fromEntries(Object.entries(meta.fields).map(([name, field]) => [
+            name,
+            {
+                type: field.type,
+                nullable: field.nullable,
+                sortable: field.sortable,
+                ops: field.ops,
+                kind: field.kind,
+                ...(field.many === undefined ? {} : { many: field.many }),
+                ...(field.relation === undefined ? {} : { relation: field.relation }),
+                ...(field.identified_by === undefined ? {} : { identifiedBy: field.identified_by }),
+                ...(field.choices && field.choices.length > 0 ? { choices: field.choices } : {}),
+            },
+        ])),
+        translations: {
+            name: {
+                default: meta.name?.[locale ?? ""] ?? meta.name?.["default"] ?? meta.aggregate,
+            },
+            labels: Object.fromEntries(names.map((name) => [name, { default: labelOf(meta, name, locale) }])),
+        },
+    };
+}
+/** The fields its search template looks in, as named in `meta.search`. */
+function searchedFields(meta) {
+    const found = [];
+    const walk = (node) => {
+        if (typeof node !== "object" || node === null)
+            return;
+        const record = node;
+        if (typeof record["field"] === "string")
+            found.push(record["field"]);
+        for (const value of Object.values(record)) {
+            if (Array.isArray(value))
+                value.forEach(walk);
+            else
+                walk(value);
+        }
+    };
+    walk(meta.search?.["where"]);
+    return found;
+}
+/**
+ * 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 function facetsOf(meta, locale) {
+    const first = searchedFields(meta);
+    const texts = Object.entries(meta.fields)
+        .filter(([, field]) => field.type === "text" && field.ops.includes("like") && !field.choices?.length)
+        .map(([name]) => name);
+    const order = [...new Set([...first, ...texts])];
+    return order.map((name) => ({ id: name, label: labelOf(meta, name, locale) }));
+}

package/dist/web/record/CommandButton.d.ts

@@ -0,0 +1,22 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import type { Entity } from "../../core/entity.js";
+/**
+ * An entity's Command as a button.
+ *
+ * Context: two kinds of action, two gestures. One that can be undone runs on the click — asking
+ * «are you sure?» before every confirm teaches people to click «yes» without reading. One that
+ * destroys (`destructive`) asks the server FIRST what it would do — the Command's dry run — and
+ * shows THAT in the window: the confirmation is the consequence, in the server's words, not a
+ * question. A refusal is shown where it happened, with what to do.
+ */
+export declare function CommandButton<T extends AnyRecord, R = unknown>({ entity, command, id, body, label, destructive, role, onDone, }: {
+    entity: Entity<T>;
+    command: string;
+    id?: string;
+    body?: AnyRecord;
+    label: string;
+    /** Asks the server what it would do before doing it. */
+    destructive?: boolean;
+    role?: "primary" | "secondary" | "ghost";
+    onDone?: (answer: R) => void;
+}): import("react").JSX.Element;

package/dist/web/record/CommandButton.js

@@ -0,0 +1,40 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { frameworkCopy } from "../../core/copy.js";
+import { useCommand } from "../../react/useCommand.js";
+import { Refused } from "../Refused.js";
+import { Button, Dialog } from "@sincpro/web-ui";
+import { useState } from "react";
+/**
+ * An entity's Command as a button.
+ *
+ * Context: two kinds of action, two gestures. One that can be undone runs on the click — asking
+ * «are you sure?» before every confirm teaches people to click «yes» without reading. One that
+ * destroys (`destructive`) asks the server FIRST what it would do — the Command's dry run — and
+ * shows THAT in the window: the confirmation is the consequence, in the server's words, not a
+ * question. A refusal is shown where it happened, with what to do.
+ */
+export function CommandButton({ entity, command, id, body, label, destructive = false, role = "secondary", onDone, }) {
+    const copy = frameworkCopy().command;
+    const action = useCommand(entity, command);
+    const [open, setOpen] = useState(false);
+    const run = async () => {
+        const answer = await action.run(id, body);
+        if (answer !== undefined) {
+            setOpen(false);
+            action.reset();
+            onDone?.(answer);
+        }
+        else
+            setOpen(true);
+    };
+    const ask = async () => {
+        setOpen(true);
+        await action.rehearse(id, body);
+    };
+    const close = () => {
+        setOpen(false);
+        action.reset();
+    };
+    return (_jsxs(_Fragment, { children: [_jsx(Button, { size: "sm", role: destructive ? "secondary" : role, disabled: action.busy, onClick: () => void (destructive ? ask() : run()), children: label }), open ? (_jsx(Dialog, { open: true, title: label, onClose: close, footer: destructive && action.error === null ? (_jsxs("div", { className: "flex justify-end gap-2", children: [_jsx(Button, { size: "sm", role: "secondary", onClick: close, children: copy.cancel }), _jsx(Button, { size: "sm", role: "primary", disabled: action.busy || action.rehearsal === null, onClick: () => void run(), children: copy.confirm })] })) : undefined, children: action.error !== null ? (_jsx(Refused, { error: action.error })) : action.rehearsal === null ? (_jsx("p", { className: "text-meta text-muted", children: copy.rehearsing })) : (_jsx("p", { className: "text-ink", children: action.rehearsal.text })) })) : null] }));
+}

package/dist/web/record/EntityPicker.d.ts

@@ -0,0 +1,27 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import type { Entity } from "../../core/entity.js";
+/**
+ * A many2one: pick ONE record of an entity — web-ui's `Picker` fed by `useLookup`, with a way
+ * into the whole set however big it is.
+ *
+ * Context: two ways to choose, for two sizes. The picker holds the first page of choices and
+ * narrows it as you type — instant for a set of tens. For a set of millions, «browse
+ * everything» opens a chooser: the entity's full list, searched, ordered and paged by the
+ * SERVER, where clicking a row answers the field. web-ui's `Picker` keeps what is typed to
+ * itself and cannot ask the server by text; the chooser is how this scales without it.
+ *
+ * Inside a workspace, «open» and the chooser can be the composer's instead (`api.open`,
+ * `api.pick`): pass `onOpen` / `onBrowseAll` and they replace the defaults.
+ */
+export declare function EntityPicker<T extends AnyRecord>({ entity, value, onChange, onOpen, onBrowseAll, placeholder, disabled, "aria-label": ariaLabel, }: {
+    entity: Entity<T>;
+    value?: string;
+    onChange: (id: string) => void;
+    /** Open the chosen record — in composer, `(id) => api.open(entity.ref(id), { to: "window" })`. */
+    onOpen?: (id: string) => void;
+    /** Replace the built-in chooser — in composer, `api.pick(entity.ref(), …)`. */
+    onBrowseAll?: () => void;
+    placeholder?: string;
+    disabled?: boolean;
+    "aria-label"?: string;
+}): import("react").JSX.Element;

package/dist/web/record/EntityPicker.js

@@ -0,0 +1,39 @@
+"use client";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { nameOf } from "@sincpro/criteria";
+import { useListing } from "../../react/useListing.js";
+import { useLookup } from "../../react/useLookup.js";
+import { EntityList } from "../list/EntityList.js";
+import { Dialog, Picker } from "@sincpro/web-ui";
+import { useState } from "react";
+/**
+ * A many2one: pick ONE record of an entity — web-ui's `Picker` fed by `useLookup`, with a way
+ * into the whole set however big it is.
+ *
+ * Context: two ways to choose, for two sizes. The picker holds the first page of choices and
+ * narrows it as you type — instant for a set of tens. For a set of millions, «browse
+ * everything» opens a chooser: the entity's full list, searched, ordered and paged by the
+ * SERVER, where clicking a row answers the field. web-ui's `Picker` keeps what is typed to
+ * itself and cannot ask the server by text; the chooser is how this scales without it.
+ *
+ * Inside a workspace, «open» and the chooser can be the composer's instead (`api.open`,
+ * `api.pick`): pass `onOpen` / `onBrowseAll` and they replace the defaults.
+ */
+export function EntityPicker({ entity, value, onChange, onOpen, onBrowseAll, placeholder, disabled, "aria-label": ariaLabel, }) {
+    const lookup = useLookup(entity);
+    const [choosing, setChoosing] = useState(false);
+    return (_jsxs(_Fragment, { children: [_jsx(Picker, { items: lookup.options.map((one) => ({
+                    id: one.id,
+                    name: one.label,
+                    ...(one.detail === undefined ? {} : { meta: one.detail, haystack: one.detail }),
+                })), ...(value === undefined ? {} : { value }), onChange: onChange, loading: lookup.loading, ...(onOpen === undefined ? {} : { onOpen }), onBrowseAll: onBrowseAll ?? (() => setChoosing(true)), ...(placeholder === undefined ? {} : { placeholder }), ...(disabled === undefined ? {} : { disabled }), ...(ariaLabel === undefined ? {} : { "aria-label": ariaLabel }) }), choosing ? (_jsx(Chooser, { entity: entity, onChoose: (id) => {
+                    onChange(id);
+                    setChoosing(false);
+                }, onClose: () => setChoosing(false) })) : null] }));
+}
+/** The whole set in a window: search and pages on the server, a row answers the field. */
+function Chooser({ entity, onChoose, onClose, }) {
+    const listing = useListing(entity, { pageSize: 20 });
+    const key = listing.meta?.get_id || listing.meta?.identity || "id";
+    return (_jsx(Dialog, { open: true, width: "lg", title: nameOf(listing.meta, listing.locale) || entity.kind, onClose: onClose, children: _jsx(EntityList, { listing: listing, embedded: true, search: "box", onOpen: (row) => onChoose(String(row[key])) }) }));
+}