@sincpro/web-framework 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,19 @@
+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.
+ *
+ * Context: sincpro_framework answers this question on its own — `LiteralSearch`, the entity's
+ * `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. 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[], summary?: SummaryFields): LookupOption[];

package/dist/core/lookup.js

@@ -0,0 +1,14 @@
+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);
+        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.d.ts

@@ -0,0 +1,43 @@
+import type { AnyRecord, Criteria, Meta, Problem } from "@sincpro/criteria";
+import { type Draft, type Method, type Transport } from "./transport.js";
+/**
+ * A server held in memory: tables of rows with their definition, answered with the same
+ * engine sincpro_framework's criteria runs on.
+ *
+ * Context: not a test double. It is what a screen runs against before its server exists,
+ * what Storybook and the tests run against, and what a domain with no server at all uses —
+ * rows a screen already holds. It filters, orders, pages and counts
+ * exactly as the server would (`answer` from `@sincpro/criteria/engine`), drops what the
+ * model cannot answer and reports it, and refuses what the server would refuse. So the day a
+ * real server answers, only the transport changes.
+ *
+ * A record is found at `<list route>/<id>`, by the field the model fetches by (`get_id`, else
+ * the identity) — the convention sincpro_framework's REST routes follow.
+ *
+ *     const transport = memoryTransport({
+ *       "/invoices": { meta: invoiceMeta, rows: invoices },
+ *     }, { latency: 300 });
+ */
+export type MemoryTable = {
+    meta: Meta;
+    rows: readonly AnyRecord[];
+};
+export type MemoryOptions = {
+    /** Milliseconds every answer waits, so a screen's «loading» can be seen and tested. */
+    latency?: number;
+    /**
+     * Answer a Command — a write, an action, a preview — the way the service would. It may
+     * change the tables' rows (they are read on every request) and throw a `TransportError` to
+     * refuse. Without it, every Command is a 404.
+     */
+    handle?: (method: Method, route: string, body: unknown) => unknown;
+    /** The draft this caller kept of a record, answered with it — sincpro_framework's `Drafts`. */
+    draft?: (route: string) => Draft | null;
+    /** Every list request, as it arrived: what a story or a test checks was really asked. */
+    observe?: (route: string, criteria: Criteria) => void;
+    /** Refuse a route the way a server would: return the problem it answers with. */
+    refuse?: (route: string) => (Problem & {
+        status?: number;
+    }) | undefined;
+};
+export declare function memoryTransport(tables: Readonly<Record<string, MemoryTable>>, options?: MemoryOptions): Transport;

package/dist/core/memory.js

@@ -0,0 +1,99 @@
+import { answer, answerGroups } from "@sincpro/criteria/engine";
+import { TransportError, } from "./transport.js";
+function wait(ms, signal) {
+    if (ms <= 0)
+        return Promise.resolve();
+    return new Promise((done, failed) => {
+        const timer = setTimeout(done, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            failed(signal.reason);
+        });
+    });
+}
+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);
+        if (refused !== undefined)
+            throw new TransportError(route, refused.status ?? 400, refused);
+    }
+    function tableAt(route) {
+        const path = route.split("?")[0] ?? route;
+        const table = tables[path];
+        if (table === undefined)
+            throw new TransportError(route, 404, {
+                kind: "not_found",
+                reason: "ROUTE_NOT_FOUND",
+                next_step: "fix_request",
+                retryable: false,
+                errors: [],
+                extensions: {},
+                detail: `No table answers ${path}.`,
+            });
+        return table;
+    }
+    return {
+        async list(route, criteria, signal) {
+            options.observe?.(route, criteria);
+            await check(route, signal);
+            const table = tableAt(route);
+            // 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) };
+        },
+        async one(route, signal) {
+            await check(route, signal);
+            const slash = route.lastIndexOf("/");
+            const table = tableAt(route.slice(0, slash));
+            const id = decodeURIComponent(route.slice(slash + 1));
+            const key = table.meta.get_id || table.meta.identity;
+            const record = table.rows.find((row) => String(row[key]) === id);
+            if (record === undefined)
+                throw new TransportError(route, 404, {
+                    kind: "not_found",
+                    reason: "AGGREGATE_NOT_FOUND",
+                    next_step: "do_not_retry",
+                    retryable: false,
+                    errors: [],
+                    extensions: {},
+                    detail: `${table.meta.aggregate} ${id} does not exist.`,
+                });
+            return {
+                record: structuredClone(record),
+                meta: table.meta,
+                dropped: [],
+                draft: options.draft?.(route) ?? null,
+            };
+        },
+        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",
+                    reason: "ROUTE_NOT_FOUND",
+                    next_step: "fix_request",
+                    retryable: false,
+                    errors: [],
+                    extensions: {},
+                    detail: `Nothing answers ${method} ${route}.`,
+                });
+            // A deep copy: what the caller sent is not what the server keeps.
+            const answer = await options.handle(method, route, structuredClone(body));
+            if (key !== undefined)
+                answered.set(key, structuredClone(answer));
+            return answer;
+        },
+    };
+}

package/dist/core/meta.d.ts

@@ -0,0 +1,114 @@
+import type { Expression, FieldMeta, FieldType, Meta, Operator } from "@sincpro/criteria";
+/**
+ * A model definition written by hand, in the shape sincpro_framework publishes.
+ *
+ * Context: everything in this package reads a `Meta` — the labels, the columns, the controls,
+ * the search box. A service built with sincpro_framework sends one with every answer. A domain
+ * that has none (another backend, rows a screen already holds, a prototype
+ * with no server yet) declares it here, and from then on it is indistinguishable: the same
+ * list, the same record, the same criteria. `describeRows` from `@sincpro/criteria` guesses
+ * one from rows; this one is written on purpose, with the words a person reads.
+ *
+ *     const tickets = defineMeta({
+ *       aggregate: "Ticket", identity: "id", display: "title", search: ["title"],
+ *       name: { es: "Tickets" },
+ *       fields: {
+ *         id: field.text({ readonly: true }),
+ *         title: field.text({ label: { es: "Título" }, required: true }),
+ *         stage: field.choice(["new", "done"], { labels: { new: { es: "Nuevo" } } }),
+ *         opened_at: field.datetime({ label: { es: "Abierto" } }),
+ *       },
+ *     });
+ */
+/** A word in several languages, `{default?, es?, en?, …}`; a bare string is the default. */
+export type Words = string | Readonly<Record<string, string>>;
+export type FieldOptions = {
+    label?: Words;
+    help?: Words;
+    required?: boolean;
+    readonly?: boolean;
+    /** Holds no value sometimes. A nullable field is never sortable: keyset paging over it
+     *  loses the rows that hold NULL, which is why the framework refuses to order by one. */
+    nullable?: boolean;
+    default?: unknown;
+    /** Form hints over the record, as sincpro_framework's `Presentation` publishes them. */
+    readonlyWhen?: Expression;
+    requiredWhen?: Expression;
+    visibleWhen?: Expression;
+};
+/** The field builders: one per type the framework publishes. */
+export declare const field: {
+    text: (options?: FieldOptions) => FieldMeta;
+    integer: (options?: FieldOptions) => FieldMeta;
+    /** A decimal travels as text so no digit is lost (`"10.50"`): pass `exact: true`. */
+    number: (options?: FieldOptions & {
+        exact?: boolean;
+    }) => {
+        exact?: boolean;
+        type: FieldType;
+        nullable: boolean;
+        choices?: unknown[];
+        choice_labels?: Record<string, Record<string, string>>;
+        label?: Record<string, string>;
+        help?: Record<string, string>;
+        groupable?: boolean;
+        aggregates?: string[];
+        computed?: boolean;
+        owner?: string | null;
+        readonly?: boolean;
+        required?: boolean;
+        default?: unknown;
+        readonly_when?: Expression | null;
+        required_when?: Expression | null;
+        visible_when?: Expression | null;
+        sortable: boolean;
+        ops: Operator[];
+        many?: boolean;
+        relation?: string | null;
+        identified_by?: string | null;
+        parent_field?: string | null;
+        related_field?: string | null;
+        definition?: Meta | null;
+        kind: import("@sincpro/criteria").FieldKind;
+    };
+    boolean: (options?: FieldOptions) => FieldMeta;
+    date: (options?: FieldOptions) => FieldMeta;
+    datetime: (options?: FieldOptions) => FieldMeta;
+    tags: (options?: FieldOptions) => FieldMeta;
+    /** An enum: the values in order, and the word each one is read as. */
+    choice: (values: readonly string[], options?: FieldOptions & {
+        labels?: Readonly<Record<string, Words>>;
+    }) => FieldMeta;
+    /** Points at ONE record of another aggregate, by the scalar key this record holds. */
+    many2one: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    /** The records of another aggregate that point back here, by THEIR key. */
+    one2many: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    many2many: (relation: string, keys: {
+        identifiedBy: string;
+        definition?: Meta;
+    }, options?: FieldOptions) => FieldMeta;
+    /** A value object kept inside the record — an address, a specification. No identity. */
+    embedded: (definition: Meta, options?: FieldOptions & {
+        many?: boolean;
+    }) => FieldMeta;
+};
+export type MetaSpec = {
+    aggregate: string;
+    identity: string;
+    fields: Record<string, FieldMeta>;
+    name?: Words;
+    /** The field shown beside the identity: what a select and a many2one show. */
+    display?: string;
+    /** `"-created_at"`, the way a URL writes it. Without it, the identity ascending. */
+    defaultOrder?: string;
+    /** The text fields a typed text is looked for in — the entity's search template. */
+    search?: readonly string[];
+};
+/** A whole definition, from its fields. See the file header. */
+export declare function defineMeta(spec: MetaSpec): Meta;

package/dist/core/meta.js

@@ -0,0 +1,130 @@
+function hints(options) {
+    return {
+        ...(options.readonlyWhen ? { readonly_when: options.readonlyWhen } : {}),
+        ...(options.requiredWhen ? { required_when: options.requiredWhen } : {}),
+        ...(options.visibleWhen ? { visible_when: options.visibleWhen } : {}),
+    };
+}
+/** The comparisons each type takes — the same table sincpro_framework publishes. */
+const OPS = {
+    text: ["=", "!=", "like", "starts with", "in", "not in"],
+    integer: ["=", "!=", ">", ">=", "<", "<=", "between", "in", "not in"],
+    number: ["=", "!=", ">", ">=", "<", "<=", "between", "in", "not in"],
+    date: ["=", "!=", ">", ">=", "<", "<=", "between"],
+    datetime: ["=", "!=", ">", ">=", "<", "<=", "between"],
+    boolean: ["="],
+    "text[]": ["contains", "not contains", "=", "!="],
+};
+function words(value) {
+    if (value === undefined)
+        return undefined;
+    return typeof value === "string" ? { default: value } : { ...value };
+}
+function scalar(type, options = {}) {
+    const nullable = options.nullable ?? false;
+    const ops = [...(OPS[type] ?? [])];
+    if (nullable && type !== "text[]" && type !== "boolean")
+        ops.push("is null");
+    const listed = type === "text[]";
+    return {
+        type,
+        kind: "scalar",
+        nullable,
+        sortable: !nullable && !listed,
+        groupable: !listed,
+        ops,
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+        ...(options.help === undefined ? {} : { help: words(options.help) }),
+        ...(options.required === undefined ? {} : { required: options.required }),
+        ...(options.readonly === undefined ? {} : { readonly: options.readonly }),
+        ...(options.default === undefined ? {} : { default: options.default }),
+        ...hints(options),
+    };
+}
+function relational(type, relation, keys, options = {}) {
+    return {
+        type,
+        kind: "relation",
+        nullable: options.nullable ?? type === "many2one",
+        sortable: false,
+        ops: [],
+        many: type !== "many2one",
+        relation,
+        identified_by: keys.identifiedBy,
+        ...(keys.definition === undefined ? {} : { definition: keys.definition }),
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+        ...(options.help === undefined ? {} : { help: words(options.help) }),
+        ...(options.readonly === undefined ? {} : { readonly: options.readonly }),
+    };
+}
+/** The field builders: one per type the framework publishes. */
+export const field = {
+    text: (options) => scalar("text", options),
+    integer: (options) => scalar("integer", options),
+    /** A decimal travels as text so no digit is lost (`"10.50"`): pass `exact: true`. */
+    number: (options) => ({
+        ...scalar("number", options),
+        ...(options?.exact ? { exact: true } : {}),
+    }),
+    boolean: (options) => scalar("boolean", options),
+    date: (options) => scalar("date", options),
+    datetime: (options) => scalar("datetime", options),
+    tags: (options) => scalar("text[]", options),
+    /** An enum: the values in order, and the word each one is read as. */
+    choice: (values, options = {}) => ({
+        ...scalar("text", options),
+        ops: ["=", "!=", "in", "not in", ...(options.nullable ? ["is null"] : [])],
+        choices: [...values],
+        ...(options.labels === undefined
+            ? {}
+            : {
+                choice_labels: Object.fromEntries(Object.entries(options.labels).map(([value, said]) => [value, words(said) ?? {}])),
+            }),
+    }),
+    /** Points at ONE record of another aggregate, by the scalar key this record holds. */
+    many2one: (relation, keys, options) => relational("many2one", relation, keys, options),
+    /** The records of another aggregate that point back here, by THEIR key. */
+    one2many: (relation, keys, options) => relational("one2many", relation, keys, options),
+    many2many: (relation, keys, options) => relational("many2many", relation, keys, options),
+    /** A value object kept inside the record — an address, a specification. No identity. */
+    embedded: (definition, options = {}) => ({
+        type: "embedded",
+        kind: "embedded",
+        nullable: options.nullable ?? false,
+        sortable: false,
+        ops: [],
+        definition,
+        ...(options.many ? { many: true } : {}),
+        ...(options.label === undefined ? {} : { label: words(options.label) }),
+    }),
+};
+/** The template a typed text fills: `like` over each field, any of them matching. */
+function searchTemplate(fields) {
+    if (fields.length === 0)
+        return null;
+    const like = (name) => ({
+        field: name,
+        operator: "like",
+        value: { $: "param", name: "text" },
+    });
+    const [only] = fields;
+    return {
+        where: fields.length === 1 && only !== undefined ? like(only) : { any: fields.map(like) },
+    };
+}
+/** A whole definition, from its fields. See the file header. */
+export function defineMeta(spec) {
+    const missing = [spec.identity, spec.display, ...(spec.search ?? [])].filter((name) => name !== undefined && name !== "" && !(name in spec.fields));
+    if (missing.length > 0)
+        throw new Error(`${spec.aggregate}: ${missing.join(", ")} named but not declared`);
+    return {
+        aggregate: spec.aggregate,
+        identity: spec.identity,
+        default_order: spec.defaultOrder ?? spec.identity,
+        fields: spec.fields,
+        get_id: spec.identity,
+        ...(spec.name === undefined ? {} : { name: words(spec.name) }),
+        ...(spec.display === undefined ? {} : { display: spec.display }),
+        search: searchTemplate(spec.search ?? []),
+    };
+}

package/dist/core/metas.d.ts

@@ -0,0 +1,18 @@
+import type { Meta } from "@sincpro/criteria";
+/**
+ * The model definitions already known, by entity key (`"billing:invoice"`).
+ *
+ * Context: sincpro_framework sends `entity_meta_data` with every answer that does not say
+ * `meta: false`, and it is not small — forge's `Project` weighs ~97 KB even with zero rows.
+ * A reading already asks for it only on its first page; this keeps it ACROSS readings, so the
+ * second list of the same entity, the record opened from it and the select that points at it
+ * ask with `meta: false` and draw their labels before the rows arrive.
+ *
+ * Seeded, it is the preload: definitions written at build time (a snapshot of the server's,
+ * or `defineMeta`) reach the first screen with no request at all.
+ */
+export type MetaStore = {
+    get(key: string): Meta | undefined;
+    set(key: string, meta: Meta): void;
+};
+export declare function metaStore(seed?: Readonly<Record<string, Meta>>): MetaStore;

package/dist/core/metas.js

@@ -0,0 +1,7 @@
+export function metaStore(seed = {}) {
+    const known = new Map(Object.entries(seed));
+    return {
+        get: (key) => known.get(key),
+        set: (key, meta) => void known.set(key, meta),
+    };
+}

package/dist/core/present.d.ts

@@ -0,0 +1,48 @@
+import { type FieldMeta, type Meta } from "@sincpro/criteria";
+/**
+ * How a field is SHOWN, decided once from the model and nowhere else.
+ *
+ * Context: this is the part of "render from the metadata" that is the same in every
+ * piece. A table column, a fact of a record and a search chip all need the word for the field, whether it is a
+ * number, whether it orders, and the text a value reads as («Pagada», «12/03/2026», «sí»,
+ * «3 elementos»). What they draw it WITH is theirs; what it SAYS is decided here, so they
+ * cannot disagree.
+ */
+export type FieldView = {
+    name: string;
+    label: string;
+    help: string | undefined;
+    type: FieldMeta["type"];
+    kind: FieldMeta["kind"];
+    /** Right-aligned, tabular: integer and number. */
+    numeric: boolean;
+    /** The server can order by it — never a nullable column. */
+    sortable: boolean;
+    required: boolean;
+    readonly: boolean;
+};
+export declare function viewOf(meta: Meta | null | undefined, name: string, locale?: string): FieldView;
+/**
+ * The fields a screen shows when it names none: every scalar the model holds, in the order it
+ * declares them. Relations and value objects are left out — they are not a column, they are a
+ * page of their own (`RecordLines`) or a section.
+ */
+export declare function defaultFields(meta: Meta | null | undefined): string[];
+/** The bookkeeping every framework entity carries; shown on demand, never by default. */
+export declare const BOOKKEEPING: ReadonlySet<string>;
+/**
+ * The text a value reads as. `null` when there is nothing to read — the caller draws its own
+ * «empty» (a dash in a fact, nothing in a cell).
+ *
+ *     textOf(meta, "state", "paid", "es")            -> "Pagada"     (choice_labels)
+ *     textOf(meta, "active", true, "es")              -> "sí"
+ *     textOf(meta, "due", "2026-03-12", "es")         -> "12 mar 2026"
+ *     textOf(meta, "total", "1150.5", "es")           -> "1150,5"     (exact: digits kept)
+ *     textOf(meta, "lines", {items, count: {value: 30}}) -> "30 elementos"
+ */
+export declare function textOf(meta: Meta | null | undefined, name: string, value: unknown, locale?: string): string | null;
+/**
+ * The value a column orders and groups on: the raw scalar, never the text. ISO dates order
+ * as text; a decimal that travels as text orders as a number.
+ */
+export declare function sortKeyOf(meta: Meta | null | undefined, name: string, value: unknown): string | number | boolean | null;