@sincpro/web-framework 0.1.0 → 0.2.0

package/dist/core/form.d.ts

@@ -0,0 +1,21 @@
+import type { Meta } from "@sincpro/criteria";
+import { type SummaryFields } from "./summary.js";
+/**
+ * What a record's form shows when the screen names nothing: its fields, and the pages beside
+ * them — read from the model, in the order it declares.
+ *
+ * Context: the default form must be useful on any entity, not a dump of every key. So:
+ *
+ * - the bookkeeping (`version`, `updated_at`) and who made and changed it are not fields: the
+ *   paper says them on its last line (`Record.Audit`); the picture is not a text box;
+ * - a read-only identity is the record's name, not a field to look at;
+ * - a many2one is written by its KEY (`customer_id`, a picker of customers): the expanded
+ *   relation beside it (`customer`) would be the same thing twice;
+ * - a one2many is a page of its own — a list, not a field;
+ * - a value object, and a many2many the backend cannot write yet, are left to the screen.
+ */
+export type FormLayout = {
+    fields: string[];
+    pages: string[];
+};
+export declare function formOf(meta: Meta | null | undefined, summary?: SummaryFields): FormLayout;

package/dist/core/form.js

@@ -0,0 +1,30 @@
+import { BOOKKEEPING } from "./present.js";
+import { summaryFieldsOf } from "./summary.js";
+export function formOf(meta, summary = {}) {
+    if (!meta)
+        return { fields: [], pages: [] };
+    const parts = summaryFieldsOf(meta, {}, summary);
+    const told = new Set([parts.createdAt, parts.createdBy, parts.updatedAt, parts.updatedBy, parts.image].filter((name) => name !== undefined));
+    const keys = new Set(Object.values(meta.fields)
+        .map((field) => (field.kind === "relation" ? field.identified_by : undefined))
+        .filter((name) => typeof name === "string" && name in meta.fields));
+    const fields = [];
+    const pages = [];
+    for (const [name, field] of Object.entries(meta.fields)) {
+        if (BOOKKEEPING.has(name) || told.has(name))
+            continue;
+        if (name === meta.identity && field.readonly)
+            continue;
+        if (field.kind === "embedded")
+            continue;
+        if (field.kind === "relation") {
+            if (field.type === "one2many")
+                pages.push(name);
+            else if (!field.many && !(field.identified_by && keys.has(field.identified_by)))
+                fields.push(name);
+            continue;
+        }
+        fields.push(name);
+    }
+    return { fields, pages };
+}

package/dist/core/index.d.ts

@@ -5,15 +5,22 @@
  */
 export { type CachedTransport, cachedTransport, type CacheOptions, } from "./cache.js";
 export { ENGLISH_FRAMEWORK_COPY, type FrameworkCopy, frameworkCopy, installFrameworkCopy, SPANISH_FRAMEWORK_COPY, } from "./copy.js";
-export { changesOf, errorsByField, type FieldState, fieldStateOf, type FieldStates, missingOf, } from "./edit.js";
-export { type Entity, entity, type EntityRef, type EntityRoutes, pathFor, type WriteRoute, writeRoute, } from "./entity.js";
+export { changesOf, creationOf, defaultsOf, errorsByField, type FieldState, fieldStateOf, type FieldStates, missingOf, } from "./edit.js";
+export { type Entity, entity, type EntityRef, type EntityRoutes, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, TRAIL_PARAM, type WriteRoute, writeRoute, } from "./entity.js";
+export { type FormLayout, formOf } from "./form.js";
 export { type HistoryEntry, historyOf } from "./history.js";
+export { defineList, type GroupLevel, isList, type ListDefinition, type ListSpec, type NamedFilter, scopeOf, } from "./list.js";
 export { lookupOf, type LookupOption } from "./lookup.js";
+export { detailOf, measuresOf, sumsOf } from "./measure.js";
 export { type MemoryOptions, type MemoryTable, memoryTransport, } from "./memory.js";
 export { defineMeta, field, type FieldOptions, type MetaSpec, type Words, } from "./meta.js";
 export { type MetaStore, metaStore } from "./metas.js";
 export { BOOKKEEPING, defaultFields, type FieldView, sortKeyOf, textOf, viewOf, } from "./present.js";
 export { type Related, relatedOf } from "./related.js";
+export { entityFor, type RelationField, relationFieldOf, } from "./relation.js";
 export { type RestOptions, restTransport, urlOf } from "./rest.js";
+export { type RetryKeys, retryKeys, unanswered } from "./retry.js";
 export { completeMeta, type JsonSchema, metaFromSchema, type SchemaComponents, } from "./schema.js";
-export { type Draft, explain, type Method, type One, type Transport, TransportError, } from "./transport.js";
+export { type RecordSummary, type SummaryFields, summaryFieldsOf, summaryOf, type SummaryPart, } from "./summary.js";
+export { placeOf, stepIn, type Trail } from "./trail.js";
+export { type Draft, explain, type Method, type One, type SendOptions, type Transport, TransportError, } from "./transport.js";

package/dist/core/index.js

@@ -5,15 +5,22 @@
  */
 export { cachedTransport, } from "./cache.js";
 export { ENGLISH_FRAMEWORK_COPY, frameworkCopy, installFrameworkCopy, SPANISH_FRAMEWORK_COPY, } from "./copy.js";
-export { changesOf, errorsByField, fieldStateOf, missingOf, } from "./edit.js";
-export { entity, pathFor, writeRoute, } from "./entity.js";
+export { changesOf, creationOf, defaultsOf, errorsByField, fieldStateOf, missingOf, } from "./edit.js";
+export { entity, NEW_PARAM, pathFor, PICK_PARAM, QUERY_PARAM, TRAIL_PARAM, writeRoute, } from "./entity.js";
+export { formOf } from "./form.js";
 export { historyOf } from "./history.js";
+export { defineList, isList, scopeOf, } from "./list.js";
 export { lookupOf } from "./lookup.js";
+export { detailOf, measuresOf, sumsOf } from "./measure.js";
 export { memoryTransport, } from "./memory.js";
 export { defineMeta, field, } from "./meta.js";
 export { metaStore } from "./metas.js";
 export { BOOKKEEPING, defaultFields, sortKeyOf, textOf, viewOf, } from "./present.js";
 export { relatedOf } from "./related.js";
+export { entityFor, relationFieldOf, } from "./relation.js";
 export { restTransport, urlOf } from "./rest.js";
+export { retryKeys, unanswered } from "./retry.js";
 export { completeMeta, metaFromSchema, } from "./schema.js";
+export { summaryFieldsOf, summaryOf, } from "./summary.js";
+export { placeOf, stepIn } from "./trail.js";
 export { explain, TransportError, } from "./transport.js";

package/dist/core/list.d.ts

@@ -0,0 +1,64 @@
+import type { AnyRecord, Criteria, Expression, Grain, Sort } from "@sincpro/criteria";
+import type { Entity, EntityRef } from "./entity.js";
+/**
+ * A named way of looking at an entity: «Por cobrar», «Borradores», «Mis tickets».
+ *
+ * Context: an ERP rarely shows ONE list of invoices. It shows the invoices to collect, the
+ * drafts, the overdue ones — the same entity under a fixed cut, each with its own columns,
+ * its own named filters and maybe its own grouping (Odoo's window actions with a `domain`).
+ * Written by hand, each of those is a screen repeating `useListing` options and `EntityList`
+ * props. Declared once, it is data: `useListing(list)` reads it, `EntityList` draws it,
+ * `listView(list)` opens it in the workspace with its own «Go to».
+ *
+ * The SCOPE is the cut: always asked, ANDed under whatever is searched, filtered or grouped,
+ * and never in the search bar — a person cannot remove the «por cobrar» of «Por cobrar». It is
+ * a convenience of the screen, not protection: the server answers whatever it allows.
+ *
+ *     export const porCobrar = defineList(facturas, {
+ *       id: "por-cobrar",
+ *       title: "Por cobrar",
+ *       scope: { where: { field: "state", operator: "=", value: "posted" } },
+ *       columns: ["number", "customer", "due_date", "amount_total"],
+ *       filters: [{ id: "vencidas", label: "Vencidas", where: … }],
+ *     });
+ */
+export type ListDefinition<T extends AnyRecord = AnyRecord> = {
+    entity: Entity<T>;
+    /** Unique within its entity: `"por-cobrar"`. */
+    id: string;
+    /** `domain:kind-id` — how the workspace and the definitions store refer to it. */
+    key: string;
+    /** Where the workspace opens it: a kind of its own, so ⌘K can offer it by name. */
+    ref: () => EntityRef;
+    title: string;
+    description?: string;
+    /** The fixed cut, ANDed under everything a person searches or filters. */
+    scope?: Criteria<T>;
+    /** The order it opens in, before anyone clicks a header. */
+    order?: Sort;
+    /** The fields shown, in order. */
+    columns?: readonly string[];
+    /** The cuts it offers by name in the search bar. */
+    filters?: readonly NamedFilter<T>[];
+    /** The faces it offers, the first one shown. */
+    views?: readonly ("table" | "rows" | "board")[];
+    /** Grouped from the start — the server counts the groups. */
+    groupBy?: readonly GroupLevel[];
+};
+/** A cut offered by name in the search bar: «sólo pagadas», «vencidas». */
+export type NamedFilter<T> = {
+    id: string;
+    label: string;
+    where: Expression<T>;
+};
+/** One level of a grouping: by which field, and by which cut of time when it is a date. */
+export type GroupLevel = {
+    field: string;
+    grain?: Grain;
+};
+export type ListSpec<T extends AnyRecord> = Omit<ListDefinition<T>, "entity" | "key" | "ref">;
+export declare function defineList<T extends AnyRecord>(entity: Entity<T>, spec: ListSpec<T>): ListDefinition<T>;
+/** Whether what `useListing` was handed is a list definition rather than a bare entity. */
+export declare function isList<T extends AnyRecord>(given: Entity<T> | ListDefinition<T>): given is ListDefinition<T>;
+/** The criteria a definition always asks: its scope, in its order. */
+export declare function scopeOf<T extends AnyRecord>(list: ListDefinition<T>): Criteria<T>;

package/dist/core/list.js

@@ -0,0 +1,22 @@
+export function defineList(entity, spec) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(spec.id))
+        throw new Error(`list id "${spec.id}" is not kebab-case: it becomes a workspace kind`);
+    const kind = `${entity.kind}-${spec.id}`;
+    return {
+        ...spec,
+        entity,
+        key: `${entity.domain}:${kind}`,
+        ref: () => ({ domain: entity.domain, kind }),
+    };
+}
+/** Whether what `useListing` was handed is a list definition rather than a bare entity. */
+export function isList(given) {
+    return "entity" in given && "title" in given;
+}
+/** The criteria a definition always asks: its scope, in its order. */
+export function scopeOf(list) {
+    return {
+        ...list.scope,
+        ...(list.order === undefined ? {} : { order: [list.order] }),
+    };
+}

package/dist/core/lookup.d.ts

@@ -1,4 +1,5 @@
 import type { AnyRecord, Meta } from "@sincpro/criteria";
+import { type SummaryFields } from "./summary.js";
 /**
  * A record as a choice: what a many2one select, a «share with» and ⌘K show for it.
  *
@@ -6,11 +7,13 @@ import type { AnyRecord, Meta } from "@sincpro/criteria";
  * `DEFAULT_LITERAL_SEARCH` and `DEFAULT_DISPLAY` — and publishes both in the model definition
  * (`meta.search`, `meta.display`). So a choice is read from the model: its key is the field a
  * record is fetched by, its label the display, and the key again beside it when the two differ
- * («Globex Bolivia · C-004»), which is what tells two «Globex» apart.
+ * («Globex Bolivia · C-004»), which is what tells two «Globex» apart. Its picture is the
+ * record's summary image (`entity(…, { summary })`): a person is chosen by their face.
  */
 export type LookupOption = {
     id: string;
     label: string;
     detail?: string;
+    image?: string;
 };
-export declare function lookupOf(meta: Meta | null | undefined, rows: readonly AnyRecord[]): LookupOption[];
+export declare function lookupOf(meta: Meta | null | undefined, rows: readonly AnyRecord[], summary?: SummaryFields): LookupOption[];

package/dist/core/lookup.js

@@ -1,10 +1,14 @@
-export function lookupOf(meta, rows) {
+import { summaryFieldsOf } from "./summary.js";
+export function lookupOf(meta, rows, summary = {}) {
     const key = meta?.get_id || meta?.identity || "id";
     const display = meta?.display || key;
     return rows.map((row) => {
         const id = String(row[key] ?? "");
         const shown = row[display];
         const label = shown === undefined || shown === null || shown === "" ? id : String(shown);
-        return label === id ? { id, label } : { id, label, detail: id };
+        const imageField = summaryFieldsOf(meta, row, summary).image;
+        const picture = imageField === undefined ? undefined : row[imageField];
+        const image = typeof picture === "string" && picture !== "" ? { image: picture } : {};
+        return label === id ? { id, label, ...image } : { id, label, detail: id, ...image };
     });
 }

package/dist/core/measure.d.ts

@@ -0,0 +1,16 @@
+import { type Measure, type Meta } from "@sincpro/criteria";
+/**
+ * What a group ADDS UP TO — «Total 1.204.933,00» beside «Pagadas · 187» — summed by the server
+ * over every row of the group, never the page.
+ *
+ * Context: a count says how many; whoever groups invoices by state wants to know how much. Which
+ * fields add up is the domain's, and the model does not say it yet, so the default is the
+ * figure a record computes: an exact number that is read-only (a total, a subtotal, a balance).
+ * What a person types — a discount, a percentage, a limit — is not added up: a sum of
+ * percentages means nothing. A screen names its own (`EntityList sums`).
+ */
+export declare function sumsOf(meta: Meta | null | undefined): string[];
+/** The grouping's measures for these fields, each under its own name. */
+export declare function measuresOf(fields: readonly string[]): Record<string, Measure>;
+/** What a group's measures read as: «Total 1.204.933,00 · Saldo 12,50». */
+export declare function detailOf(meta: Meta | null | undefined, measures: Readonly<Record<string, unknown>> | undefined, locale?: string): string | undefined;

package/dist/core/measure.js

@@ -0,0 +1,38 @@
+import { labelOf, measure } from "@sincpro/criteria";
+import { BOOKKEEPING, textOf } from "./present.js";
+/**
+ * What a group ADDS UP TO — «Total 1.204.933,00» beside «Pagadas · 187» — summed by the server
+ * over every row of the group, never the page.
+ *
+ * Context: a count says how many; whoever groups invoices by state wants to know how much. Which
+ * fields add up is the domain's, and the model does not say it yet, so the default is the
+ * figure a record computes: an exact number that is read-only (a total, a subtotal, a balance).
+ * What a person types — a discount, a percentage, a limit — is not added up: a sum of
+ * percentages means nothing. A screen names its own (`EntityList sums`).
+ */
+export function sumsOf(meta) {
+    if (!meta)
+        return [];
+    return Object.entries(meta.fields)
+        .filter(([name, field]) => !BOOKKEEPING.has(name) &&
+        (field.type === "number" || field.type === "integer") &&
+        field.exact === true &&
+        field.readonly === true)
+        .map(([name]) => name);
+}
+/** The grouping's measures for these fields, each under its own name. */
+export function measuresOf(fields) {
+    return Object.fromEntries(fields.map((field) => [field, measure.sum(field)]));
+}
+/** What a group's measures read as: «Total 1.204.933,00 · Saldo 12,50». */
+export function detailOf(meta, measures, locale) {
+    if (measures === undefined)
+        return undefined;
+    const parts = Object.entries(measures)
+        .map(([field, value]) => {
+        const text = textOf(meta, field, value, locale);
+        return text === null ? null : `${labelOf(meta, field, locale)} ${text}`;
+    })
+        .filter((part) => part !== null);
+    return parts.length === 0 ? undefined : parts.join(" · ");
+}

package/dist/core/memory.js

@@ -1,4 +1,4 @@
-import { answer } from "@sincpro/criteria/engine";
+import { answer, answerGroups } from "@sincpro/criteria/engine";
 import { TransportError, } from "./transport.js";
 function wait(ms, signal) {
     if (ms <= 0)
@@ -12,6 +12,7 @@ function wait(ms, signal) {
     });
 }
 export function memoryTransport(tables, options = {}) {
+    const answered = new Map();
     async function check(route, signal) {
         await wait(options.latency ?? 0, signal);
         const refused = options.refuse?.(route);
@@ -38,7 +39,12 @@ export function memoryTransport(tables, options = {}) {
             options.observe?.(route, criteria);
             await check(route, signal);
             const table = tableAt(route);
-            const page = answer(table.rows, criteria, table.meta);
+            // A grouped question is answered with the groups — counted over EVERY row that matches,
+            // each with the criteria that opens it — the way the server's aggregation answers it.
+            const grouped = (criteria.grouping?.group_by?.length ?? 0) > 0;
+            const page = grouped
+                ? answerGroups(table.rows, criteria, table.meta)
+                : answer(table.rows, criteria, table.meta);
             // A copy, as over a wire: a screen holding a row must not see the server change it.
             return { ...page, rows: structuredClone(page.rows) };
         },
@@ -66,8 +72,13 @@ export function memoryTransport(tables, options = {}) {
                 draft: options.draft?.(route) ?? null,
             };
         },
-        async send(method, route, body, signal) {
+        async send(method, route, body, signal, sending) {
             await check(route, signal);
+            // A key already answered is answered again, without running the Command twice — what
+            // sincpro_framework's `@idempotency` does with a repeated `Idempotency-Key`.
+            const key = sending?.idempotencyKey;
+            if (key !== undefined && answered.has(key))
+                return structuredClone(answered.get(key));
             if (options.handle === undefined)
                 throw new TransportError(route, 404, {
                     kind: "not_found",
@@ -79,7 +90,10 @@ export function memoryTransport(tables, options = {}) {
                     detail: `Nothing answers ${method} ${route}.`,
                 });
             // A deep copy: what the caller sent is not what the server keeps.
-            return (await options.handle(method, route, structuredClone(body)));
+            const answer = await options.handle(method, route, structuredClone(body));
+            if (key !== undefined)
+                answered.set(key, structuredClone(answer));
+            return answer;
         },
     };
 }

package/dist/core/relation.d.ts

@@ -0,0 +1,28 @@
+import type { FieldMeta, Meta } from "@sincpro/criteria";
+import type { Entity } from "./entity.js";
+/**
+ * Which record a field of a form is about, read from the model — so a form draws a many2one
+ * as a picker of the right entity without being told.
+ *
+ * Context: sincpro_framework publishes a many2one twice: the RELATION (`customer`, expanded as
+ * the record it points at, read-only) and its scalar KEY (`customer_id`, what is written),
+ * joined by `identified_by`. A form may name either; both mean «the customer». A relation
+ * names the other side by its AGGREGATE («Cliente»), which says nothing about where it is read
+ * — that is the entity the application declared (`entityFor`).
+ */
+export type RelationField = {
+    /** The relation field: `customer`. */
+    relation: string;
+    /** The scalar written for it: `customer_id` (the relation itself when it has none). */
+    key: string;
+    /** The aggregate on the other side: `"Cliente"`. */
+    target: string;
+    many: boolean;
+    field: FieldMeta;
+};
+export declare function relationFieldOf(meta: Meta | null | undefined, name: string): RelationField | undefined;
+/**
+ * The declared entity a relation points at: the one that says it is that aggregate, else the
+ * one whose model definition is, else the one whose key it is (`"ventas:cliente"`).
+ */
+export declare function entityFor(entities: readonly Entity[], target: string, metaOf?: (key: string) => Meta | undefined): Entity | undefined;

package/dist/core/relation.js

@@ -0,0 +1,30 @@
+export function relationFieldOf(meta, name) {
+    if (!meta)
+        return undefined;
+    const of = (relation, field) => field.kind !== "relation" || !field.relation
+        ? undefined
+        : {
+            relation,
+            key: field.identified_by || relation,
+            target: field.relation,
+            many: field.many === true,
+            field,
+        };
+    const own = meta.fields[name];
+    if (own?.kind === "relation")
+        return of(name, own);
+    // A scalar that a relation is identified by: `customer_id` IS the customer.
+    for (const [relation, field] of Object.entries(meta.fields))
+        if (field.kind === "relation" && field.identified_by === name)
+            return of(relation, field);
+    return undefined;
+}
+/**
+ * The declared entity a relation points at: the one that says it is that aggregate, else the
+ * one whose model definition is, else the one whose key it is (`"ventas:cliente"`).
+ */
+export function entityFor(entities, target, metaOf = () => undefined) {
+    return (entities.find((one) => one.aggregate === target) ??
+        entities.find((one) => metaOf(one.key)?.aggregate === target) ??
+        entities.find((one) => one.key === target));
+}

package/dist/core/rest.js

@@ -14,7 +14,13 @@ export function restTransport(options = {}) {
     const doFetch = options.fetch ?? ((input, init) => fetch(input, init));
     async function get(route, url, signal, write) {
         const own = typeof options.headers === "function" ? options.headers() : (options.headers ?? {});
-        const headers = write ? { ...own, "Content-Type": "application/json" } : own;
+        const headers = write
+            ? {
+                ...own,
+                "Content-Type": "application/json",
+                ...(write.key === undefined ? {} : { "Idempotency-Key": write.key }),
+            }
+            : own;
         const response = await doFetch(url, {
             headers,
             ...(write ? { method: write.method, body: JSON.stringify(write.body) } : {}),
@@ -43,8 +49,12 @@ export function restTransport(options = {}) {
                 draft: answer["draft"] ?? null,
             };
         },
-        async send(method, route, body, signal) {
-            return (await get(route, urlOf(base, route), signal, { method, body }));
+        async send(method, route, body, signal, sending) {
+            return (await get(route, urlOf(base, route), signal, {
+                method,
+                body,
+                key: sending?.idempotencyKey,
+            }));
         },
     };
 }

package/dist/core/retry.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The `Idempotency-Key` of a gesture: one per thing a person meant to do, the SAME one while
+ * that thing is retried.
+ *
+ * Context: a Command that got no answer — the network dropped, a proxy answered 502 — may have
+ * run. Sending it again with a new key could pay twice; with the same key the server answers
+ * what it already did (sincpro_framework's `@idempotency`). So a key lives until the server
+ * gives a definite answer: done, or refused for a reason a retry does not change. Changing the
+ * body is a different gesture, and gets a new key — the server refuses a key that comes back
+ * with another payload.
+ *
+ *     const keys = retryKeys();
+ *     const key = keys.keyFor(body);          // the same while the previous one went unanswered
+ *     try { await send(…, { idempotencyKey: key }); keys.settle(null); }
+ *     catch (error) { keys.settle(error); }   // kept when nobody knows what happened
+ */
+export type RetryKeys = {
+    keyFor: (body: unknown) => string;
+    /** What the last attempt ended in: `null` when it was answered. */
+    settle: (error: unknown) => void;
+};
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export declare function unanswered(error: unknown): boolean;
+export declare function retryKeys(make?: () => string): RetryKeys;

package/dist/core/retry.js

@@ -0,0 +1,25 @@
+import { TransportError } from "./transport.js";
+/** Whether a failure leaves it unknown if the Command ran — so a retry must reuse its key. */
+export function unanswered(error) {
+    if (!(error instanceof TransportError))
+        return true;
+    if (error.status === null || error.status >= 500)
+        return true;
+    // The same key is still running elsewhere: retry once it completes, with that key.
+    return error.problem?.kind === "in_progress";
+}
+export function retryKeys(make = () => globalThis.crypto.randomUUID()) {
+    let pending = null;
+    return {
+        keyFor: (body) => {
+            const sent = JSON.stringify(body ?? null);
+            if (pending === null || pending.body !== sent)
+                pending = { body: sent, key: make() };
+            return pending.key;
+        },
+        settle: (error) => {
+            if (error === null || !unanswered(error))
+                pending = null;
+        },
+    };
+}

package/dist/core/summary.d.ts

@@ -0,0 +1,50 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+/**
+ * What is known about ANY record, the same for every entity: its name and, when it has them,
+ * a description, a state, a type, a picture and who made and last changed it.
+ *
+ * Context: a link, a chip, a card, the summary that floats from a name and the header of a
+ * record all say the same few things about a record — only how much of it changes. Read once
+ * here, from the model, they cannot disagree, and a new entity looks right without a line
+ * written for it. What a record does not have is `null`, and nothing is drawn for it.
+ *
+ * Which field plays each part: the one the entity declares (`entity(…, { summary })`), else
+ * the first conventional name the model holds (`description`, `state`/`status`, `created_at`,
+ * …). The name is the model's own `display`. When the backend publishes these parts in its
+ * model definition, they are read from there and the convention steps aside.
+ */
+export type SummaryPart = "description" | "state" | "type" | "image" | "createdAt" | "createdBy" | "updatedAt" | "updatedBy";
+/** Which field of the entity plays each part, when it is not the conventional one.
+ *  `person`: its records are people or companies — a round face, initials without a photo. */
+export type SummaryFields = Partial<Record<SummaryPart, string>> & {
+    person?: boolean;
+};
+export type RecordSummary = {
+    id: string;
+    name: string;
+    description: string | null;
+    state: string | null;
+    type: string | null;
+    /** The picture's address, as the server sent it. */
+    image: string | null;
+    person: boolean;
+    created: {
+        at: string | null;
+        by: string | null;
+    };
+    updated: {
+        at: string | null;
+        by: string | null;
+    };
+};
+/** The field that plays each part. With a model, only fields it declares; without one (a
+ *  record that came alone), the record's own keys. */
+export declare function summaryFieldsOf(meta: Meta | null | undefined, record: AnyRecord, declared?: SummaryFields): Partial<Record<SummaryPart, string>>;
+/**
+ *     summaryOf(meta, invoice, { locale: "es" })
+ *       -> { name: "F-2026-0004", state: "Pagada", created: { at: "4 ene 2026, 14:13", … } }
+ */
+export declare function summaryOf(meta: Meta | null | undefined, record: AnyRecord, options?: {
+    fields?: SummaryFields;
+    locale?: string;
+}): RecordSummary;

package/dist/core/summary.js

@@ -0,0 +1,54 @@
+import { textOf } from "./present.js";
+const CONVENTION = {
+    description: ["description", "summary"],
+    state: ["state", "status"],
+    type: ["type", "kind", "category"],
+    image: ["image", "image_url", "avatar", "avatar_url", "photo", "picture", "logo"],
+    createdAt: ["created_at"],
+    createdBy: ["created_by"],
+    updatedAt: ["updated_at"],
+    updatedBy: ["updated_by"],
+};
+const PARTS = Object.keys(CONVENTION);
+/** The field that plays each part. With a model, only fields it declares; without one (a
+ *  record that came alone), the record's own keys. */
+export function summaryFieldsOf(meta, record, declared = {}) {
+    const holds = (name) => meta?.fields ? name in meta.fields : Object.hasOwn(record, name);
+    const found = {};
+    for (const part of PARTS) {
+        const name = declared[part] ?? CONVENTION[part].find(holds);
+        if (name !== undefined)
+            found[part] = name;
+    }
+    return found;
+}
+/**
+ *     summaryOf(meta, invoice, { locale: "es" })
+ *       -> { name: "F-2026-0004", state: "Pagada", created: { at: "4 ene 2026, 14:13", … } }
+ */
+export function summaryOf(meta, record, options = {}) {
+    const { fields = {}, locale } = options;
+    const parts = summaryFieldsOf(meta, record, fields);
+    const text = (part) => {
+        const name = parts[part];
+        return name === undefined ? null : textOf(meta, name, record[name], locale);
+    };
+    const key = meta?.get_id || meta?.identity || "id";
+    const id = String(record[key] ?? record["id"] ?? "");
+    const display = meta?.display || undefined;
+    const shown = display === undefined
+        ? (record["display_name"] ?? record["name"])
+        : textOf(meta, display, record[display], locale);
+    const image = parts.image === undefined ? null : record[parts.image];
+    return {
+        id,
+        name: shown === undefined || shown === null || shown === "" ? id : String(shown),
+        description: text("description"),
+        state: text("state"),
+        type: text("type"),
+        image: typeof image === "string" && image !== "" ? image : null,
+        person: fields.person ?? false,
+        created: { at: text("createdAt"), by: text("createdBy") },
+        updated: { at: text("updatedAt"), by: text("updatedBy") },
+    };
+}

package/dist/core/trail.d.ts

@@ -0,0 +1,44 @@
+import type { Criteria } from "@sincpro/criteria";
+import type { Transport } from "./transport.js";
+/**
+ * Where a record was opened from: the page of the list it was a row of, so the record can go
+ * to the previous and the next one — «3 / 64» and two arrows — without going back to the list.
+ *
+ * Context: Odoo keeps the ids of the whole search in the browser to page through records. That
+ * caps at what was loaded. Here the trail keeps ONE page and the server's cursors around it: at
+ * the edge of the page it asks the server for the neighbouring page, with the same question —
+ * scope, search, filter, order — so the record after the last of page 4 000 is one request, as
+ * cheap as the first. Over a list of millions the arrows never stop at the page.
+ */
+export type Trail = {
+    route: string;
+    /** The list's question, without a page: what the neighbouring pages are asked with. */
+    question: Criteria;
+    /** The field the ids are read from. */
+    key: string;
+    /** The ids of the page on screen, in order. */
+    ids: readonly string[];
+    /** Where that page starts in the whole set, counting from 0. */
+    offset: number;
+    /** Rows per page: the cursors belong to pages of this size, and only to them. */
+    size: number;
+    /** The cursors that start each page up to this one (`null`: the first page). */
+    cursors: readonly (string | null)[];
+    /** The cursor that starts the next page; `null` when this is the last. */
+    after: string | null;
+    /** How many there are in all, when the server counted them. */
+    total: number | null;
+};
+/** Where a record stands in its trail: «3 of 64», 1-based. */
+export declare function placeOf(trail: Trail, id: string): {
+    index: number;
+    total: number;
+} | null;
+/**
+ * The record next to `id` (`step` 1) or before it (`step` -1), with the trail moved to its page
+ * when it lies on the neighbouring one. `null` at either end of the set.
+ */
+export declare function stepIn(transport: Transport, trail: Trail, id: string, step: 1 | -1): Promise<{
+    id: string;
+    trail: Trail;
+} | null>;