@sincpro/web-framework 0.1.0 → 0.2.0

package/dist/core/trail.js

@@ -0,0 +1,70 @@
+import { resumingFrom } from "@sincpro/criteria";
+/** Where a record stands in its trail: «3 of 64», 1-based. */
+export function placeOf(trail, id) {
+    const at = trail.ids.indexOf(id);
+    if (at < 0)
+        return null;
+    const index = trail.offset + at + 1;
+    return { index, total: Math.max(trail.total ?? 0, trail.offset + trail.ids.length, index) };
+}
+async function page(transport, trail, cursor) {
+    const sized = {
+        ...trail.question,
+        pagination: { ...trail.question.pagination, limit: trail.size },
+    };
+    const answer = await transport.list(trail.route, {
+        ...resumingFrom(sized, cursor),
+        meta: false,
+    });
+    return {
+        ids: answer.rows.map((row) => String(row[trail.key] ?? "")),
+        after: answer.cursor,
+    };
+}
+/**
+ * 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 async function stepIn(transport, trail, id, step) {
+    const at = trail.ids.indexOf(id);
+    if (at < 0)
+        return null;
+    const there = trail.ids[at + step];
+    if (there !== undefined)
+        return { id: there, trail };
+    if (step === 1) {
+        if (trail.after === null)
+            return null;
+        const next = await page(transport, trail, trail.after);
+        const [first] = next.ids;
+        if (first === undefined)
+            return null;
+        return {
+            id: first,
+            trail: {
+                ...trail,
+                ids: next.ids,
+                offset: trail.offset + trail.ids.length,
+                cursors: [...trail.cursors, trail.after],
+                after: next.after,
+            },
+        };
+    }
+    if (trail.cursors.length < 2)
+        return null;
+    const cursors = trail.cursors.slice(0, -1);
+    const before = await page(transport, trail, cursors[cursors.length - 1] ?? null);
+    const last = before.ids[before.ids.length - 1];
+    if (last === undefined)
+        return null;
+    return {
+        id: last,
+        trail: {
+            ...trail,
+            ids: before.ids,
+            offset: Math.max(0, trail.offset - before.ids.length),
+            cursors,
+            after: trail.cursors[trail.cursors.length - 1] ?? null,
+        },
+    };
+}

package/dist/core/transport.d.ts

@@ -17,9 +17,21 @@ export interface Transport {
     /** One record, with the definition of its model. */
     one<T>(route: string, signal?: AbortSignal): Promise<One<T>>;
     /** A Command — a write, an action, a preview: `method` and a JSON body, its answer back. */
-    send<T>(method: Method, route: string, body: unknown, signal?: AbortSignal): Promise<T>;
+    send<T>(method: Method, route: string, body: unknown, signal?: AbortSignal, options?: SendOptions): Promise<T>;
 }
 export type Method = "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * How a Command travels besides its body.
+ *
+ * Context: sincpro_framework runs a Command declared `@idempotency` once per key (REST: the
+ * `Idempotency-Key` header; 400 `IDEMPOTENCY_KEY_MISSING` without it) and answers a repeat with
+ * the first answer. That is what makes «retry» safe after a request that got no answer: the
+ * server may have created the invoice, and the same key cannot create it twice.
+ */
+export type SendOptions = {
+    /** One per gesture, kept while it is retried — `retryKeys()`. */
+    idempotencyKey?: string;
+};
 /** One record as sincpro_framework answers it (`ResponseRecord`): the record, its model. */
 export type One<T> = {
     record: T;

package/dist/react/context.d.ts

@@ -1,5 +1,7 @@
 import type { Meta } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
 import { type MetaStore } from "../core/metas.js";
+import type { Trail } from "../core/trail.js";
 import type { Transport } from "../core/transport.js";
 import { type ReactNode } from "react";
 /**
@@ -14,14 +16,23 @@ type FrameworkContextValue = {
     transport: Transport;
     locale: string | undefined;
     metas: MetaStore;
+    /** The application's entities: what a relation of a model is resolved to. */
+    entities: readonly Entity[];
+    /** Where each open record came from (`Trail`), by the key its reference carries. */
+    trails: Map<string, Trail>;
 };
-export declare function FrameworkProvider({ transport, locale, metas: seed, children, }: {
+export declare function FrameworkProvider({ transport, locale, metas: seed, entities, children, }: {
     transport: Transport;
     /** The language labels and values are read in (`"es"`); the model's `default` without it. */
     locale?: string;
     /** Definitions known before any request, by entity key: the preload. */
     metas?: Readonly<Record<string, Meta>>;
+    /** The entities of the application: a form draws a many2one as a picker of the one its
+     *  model points at (`relation: "Cliente"`) without being told. */
+    entities?: readonly Entity[];
     children: ReactNode;
 }): import("react").JSX.Element;
 export declare function useFramework(): FrameworkContextValue;
+/** The declared entity a relation points at (`"Cliente"`), or `undefined`. */
+export declare function useEntityFor(target: string | undefined): Entity | undefined;
 export {};

package/dist/react/context.js

@@ -1,18 +1,26 @@
 "use client";
 import { jsx as _jsx } from "react/jsx-runtime";
 import { metaStore } from "../core/metas.js";
+import { entityFor } from "../core/relation.js";
 import { createContext, useContext, useMemo, useState } from "react";
 const FrameworkContext = createContext(null);
-export function FrameworkProvider({ transport, locale, metas: seed, children, }) {
+export function FrameworkProvider({ transport, locale, metas: seed, entities = NO_ENTITIES, children, }) {
     // One store for the provider's life: a new seed object on a re-render must not forget what
     // the screens already learned.
     const [metas] = useState(() => metaStore(seed));
-    const value = useMemo(() => ({ transport, locale, metas }), [transport, locale, metas]);
+    const [trails] = useState(() => new Map());
+    const value = useMemo(() => ({ transport, locale, metas, entities, trails }), [transport, locale, metas, entities, trails]);
     return _jsx(FrameworkContext.Provider, { value: value, children: children });
 }
+const NO_ENTITIES = [];
 export function useFramework() {
     const value = useContext(FrameworkContext);
     if (value === null)
         throw new Error("useFramework outside a FrameworkProvider");
     return value;
 }
+/** The declared entity a relation points at (`"Cliente"`), or `undefined`. */
+export function useEntityFor(target) {
+    const { entities, metas } = useFramework();
+    return target === undefined ? undefined : entityFor(entities, target, metas.get);
+}

package/dist/react/index.d.ts

@@ -3,10 +3,12 @@
  * DOM, no design system — so a screen can drop `EntityList` and still keep it. `make doctor`
  * keeps it that way.
  */
-export { FrameworkProvider, useFramework } from "./context.js";
+export { FrameworkProvider, useEntityFor, useFramework, } from "./context.js";
 export { type CommandState, type Rehearsal, useCommand, } from "./useCommand.js";
+export { type Groups, useGroups } from "./useGroups.js";
 export { useHistory } from "./useHistory.js";
 export { type Listing, type ListingOptions, type Paging, useListing, } from "./useListing.js";
 export { type Lookup, useLookup } from "./useLookup.js";
 export { type Advice, type Editing, type RecordReading, type RecordState, useRecord, } from "./useRecord.js";
 export { useRelated } from "./useRelated.js";
+export { useSummaryOf } from "./useSummary.js";

package/dist/react/index.js

@@ -3,10 +3,12 @@
  * DOM, no design system — so a screen can drop `EntityList` and still keep it. `make doctor`
  * keeps it that way.
  */
-export { FrameworkProvider, useFramework } from "./context.js";
+export { FrameworkProvider, useEntityFor, useFramework, } from "./context.js";
 export { useCommand, } from "./useCommand.js";
+export { useGroups } from "./useGroups.js";
 export { useHistory } from "./useHistory.js";
 export { useListing, } from "./useListing.js";
 export { useLookup } from "./useLookup.js";
 export { useRecord, } from "./useRecord.js";
 export { useRelated } from "./useRelated.js";
+export { useSummaryOf } from "./useSummary.js";

package/dist/react/useCommand.d.ts

@@ -9,7 +9,9 @@ import { type Entity } from "../core/entity.js";
  * destructive action deserves: not «are you sure?», but what is about to happen. forge's
  * console had the backend for it and no screen that asked.
  *
- * One at a time: `busy` turns the button off, because a payment sent twice is two payments.
+ * One at a time: `busy` turns the button off, because a payment sent twice is two payments. And
+ * once sent, the same gesture keeps its `Idempotency-Key` until the server answers: a retry
+ * after a dropped request is the same payment, never a second one (`retryKeys`).
  */
 export type Rehearsal = {
     text: string;

package/dist/react/useCommand.js

@@ -1,5 +1,6 @@
 "use client";
 import { pathFor } from "../core/entity.js";
+import { retryKeys } from "../core/retry.js";
 import { useFramework } from "./context.js";
 import { useCallback, useEffect, useRef, useState } from "react";
 export function useCommand(entity, name) {
@@ -17,13 +18,20 @@ export function useCommand(entity, name) {
         mounted.current = true;
         return () => void (mounted.current = false);
     }, []);
-    const send = useCallback(async (id, body) => {
+    // One key per gesture, kept while it goes unanswered: «retry» after a dropped request must
+    // not run it twice. A dry run touches nothing, so each one gets a key of its own.
+    const keys = useRef(retryKeys());
+    const send = useCallback(async (id, body, gesture) => {
         setBusy(true);
         setError(null);
+        const idempotencyKey = gesture.keyFor({ id, body });
         try {
-            return await transport.send(route.method, pathFor(route, id), body);
+            const answer = await transport.send(route.method, pathFor(route, id), body, undefined, { idempotencyKey });
+            gesture.settle(null);
+            return answer;
         }
         catch (failure) {
+            gesture.settle(failure);
             if (mounted.current)
                 setError(failure);
             return undefined;
@@ -34,9 +42,9 @@ export function useCommand(entity, name) {
         }
     }, [transport, route]);
     return {
-        run: (id, body = {}) => send(id, body),
+        run: (id, body = {}) => send(id, body, keys.current),
         rehearse: async (id, body = {}) => {
-            const answer = await send(id, { ...body, dry_run: true });
+            const answer = await send(id, { ...body, dry_run: true }, retryKeys());
             if (answer !== undefined && mounted.current)
                 setRehearsal(answer);
             return answer;

package/dist/react/useGroups.d.ts

@@ -0,0 +1,40 @@
+import type { AnyRecord, Bucket } from "@sincpro/criteria";
+import type { GroupLevel } from "../core/list.js";
+import type { Listing } from "./useListing.js";
+/**
+ * The set of a list, split into groups — counted by the SERVER over every row that matches.
+ *
+ * Context: grouping is the same question as filtering («which part of this am I looking at»),
+ * and it obeys the same rule: never on the page. Twelve rows on screen cannot say «187 paid»;
+ * whoever keeps the set can. So the listing's own question (scope, search, filter) goes to the
+ * server with `group_by`, and what comes back is the groups: their value, their real count, the
+ * level below, and the criteria that opens each one (sincpro_framework's aggregation; the
+ * in-memory server answers the same with criteria's engine). A group's rows are read when it is
+ * opened, with that criteria — nobody rebuilds a filter here.
+ *
+ *     const groups = useGroups(listing);
+ *     groups.group([{ field: "state" }, { field: "invoice_date", grain: "month" }]);
+ *     groups.buckets  // [{ field: "state", value: "paid", count: 187, groups: [...] }, ...]
+ *     groups.open(bucket); groups.rowsOf(bucket)  // its first page of rows
+ */
+export type { GroupLevel };
+export type Groups<T> = {
+    levels: readonly GroupLevel[];
+    /** Split by these levels, outermost first; none is no grouping. */
+    group: (levels: readonly GroupLevel[]) => void;
+    status: "idle" | "loading" | "ready" | "failed";
+    buckets: readonly Bucket<T>[];
+    error: unknown;
+    /** More groups exist than the ceiling shows: narrow the set instead. */
+    capped: boolean;
+    /** Read the rows of a group — its first page. */
+    open: (bucket: Bucket<T>) => void;
+    /** The rows of a group once read; `undefined` while it was never opened or is loading. */
+    rowsOf: (bucket: Bucket<T>) => readonly T[] | undefined;
+};
+export declare function useGroups<T extends AnyRecord>(listing: Listing<T>, options?: {
+    pageSize?: number;
+    /** The fields each group adds up, over every row of it (`detailOf` reads them). Without
+     *  it, the figures the model computes (`sumsOf`); `[]` adds nothing up. */
+    sums?: readonly string[];
+}): Groups<T>;

package/dist/react/useGroups.js

@@ -0,0 +1,69 @@
+"use client";
+import { measuresOf, sumsOf } from "../core/measure.js";
+import { useFramework } from "./context.js";
+import { useCallback, useEffect, useState } from "react";
+/** The most groups a level answers: a split into ten thousand groups is a list, not a split. */
+const MAX_GROUPS = 100;
+/** A group is known by its criteria: unique per group, and stable across renders. */
+const keyOf = (bucket) => JSON.stringify(bucket.criteria);
+export function useGroups(listing, options = {}) {
+    const { transport } = useFramework();
+    // A named list may open grouped (`groupBy`); a person regroups from there.
+    const [levels, setLevels] = useState(() => listing.definition?.groupBy ?? []);
+    const [state, setState] = useState({ status: "idle", buckets: [], error: null });
+    const [rows, setRows] = useState(new Map());
+    const pageSize = options.pageSize ?? 50;
+    // The question without what pages it: a cursor or a limit of rows has no meaning for groups.
+    const { pagination: _page, ...asked } = listing.question;
+    const question = JSON.stringify(asked);
+    const route = listing.route;
+    const sums = (options.sums ?? sumsOf(listing.meta)).join(",");
+    // What adds up by default is read from the model: without it yet, asking now and again when
+    // it arrives would be two questions — and the groups on screen replaced under the pointer.
+    const waiting = options.sums === undefined && listing.meta === null;
+    useEffect(() => {
+        setRows(new Map());
+        if (levels.length === 0) {
+            setState({ status: "idle", buckets: [], error: null });
+            return;
+        }
+        const aborter = new AbortController();
+        setState((now) => ({ ...now, status: "loading", error: null }));
+        if (waiting)
+            return () => aborter.abort();
+        const criteria = {
+            ...JSON.parse(question),
+            meta: false,
+            grouping: {
+                group_by: levels.map((level) => ({ ...level })),
+                ...(sums === "" ? {} : { measures: measuresOf(sums.split(",")) }),
+                pagination: { limit: MAX_GROUPS },
+            },
+            // One id per group is the least a grouped answer carries; the rows come on opening.
+            pagination: { limit: 1 },
+        };
+        transport.list(route, criteria, aborter.signal).then((page) => {
+            if (!aborter.signal.aborted)
+                setState({ status: "ready", buckets: page.rows, error: null });
+        }, (error) => {
+            if (!aborter.signal.aborted)
+                setState({ status: "failed", buckets: [], error });
+        });
+        return () => aborter.abort();
+    }, [transport, route, question, levels, sums, waiting]);
+    const open = useCallback((bucket) => {
+        const key = keyOf(bucket);
+        const { grouping: _grouping, pagination: _pagination, ...criteria } = bucket.criteria;
+        void transport
+            .list(route, { ...criteria, meta: false, pagination: { limit: pageSize } })
+            .then((page) => setRows((now) => new Map(now).set(key, page.rows)), (error) => setState((now) => ({ ...now, error })));
+    }, [transport, route, pageSize]);
+    return {
+        levels,
+        group: setLevels,
+        ...state,
+        capped: state.buckets.length >= MAX_GROUPS,
+        open,
+        rowsOf: (bucket) => rows.get(keyOf(bucket)),
+    };
+}

package/dist/react/useListing.d.ts

@@ -1,5 +1,6 @@
 import { type AnyRecord, type Count, type Criteria, type Dropped, type Expression, type Meta, type ReadingStatus, type Sort } from "@sincpro/criteria";
 import type { Entity } from "../core/entity.js";
+import { type ListDefinition } from "../core/list.js";
 /**
  * N records of an entity, live: what a list draws and the gestures that drive it.
  *
@@ -17,6 +18,16 @@ import type { Entity } from "../core/entity.js";
  */
 export type Listing<T> = {
     entity: Entity<T & AnyRecord>;
+    /** The named list it reads, when it was handed one (`defineList`): what `EntityList` draws
+     *  by default — its columns, filters, faces, title — and how `useGroups` starts. */
+    definition?: ListDefinition<T & AnyRecord>;
+    /** The route this list reads, with its own parameters (`/projects?tenant_id=acme`). */
+    route: string;
+    /**
+     * The question on screen — scope, search, filter and order — without a page: what a grouping
+     * of the same set asks with (`useGroups`), so groups and rows never disagree.
+     */
+    question: Criteria<T>;
     rows: T[];
     meta: Meta | null;
     count: Count | null;
@@ -29,8 +40,11 @@ export type Listing<T> = {
     reload: () => void;
     /** What was typed in the search box. */
     text: string;
-    /** Debounced: a request per pause, not per keystroke. */
-    search: (text: string) => void;
+    /** Debounced: a request per pause, not per keystroke. `now` asks at once — an explicit
+     *  Enter does not wait for a pause. */
+    search: (text: string, options?: {
+        now?: boolean;
+    }) => void;
     /** What the search bar put; `undefined` is nothing. */
     where: Expression<T> | undefined;
     filter: (where: Expression<T> | undefined) => void;
@@ -47,6 +61,10 @@ export type Listing<T> = {
         to: number;
         hasPrev: boolean;
         hasNext: boolean;
+        /** The server's cursors that start each page up to this one (`null` is the first) — and
+         *  the one that starts the next: what a record opened from here walks on (`trailOf`). */
+        cursors: readonly (string | null)[];
+        after: string | null;
     };
     next: () => void;
     prev: () => void;
@@ -72,4 +90,4 @@ export type ListingOptions<T> = {
     /** `more` mode: the most rows ever on screen. 500 by default. */
     maxRows?: number;
 };
-export declare function useListing<T extends AnyRecord>(entity: Entity<T>, options?: ListingOptions<T>): Listing<T>;
+export declare function useListing<T extends AnyRecord>(given: Entity<T> | ListDefinition<T>, own?: ListingOptions<T>): Listing<T>;

package/dist/react/useListing.js

@@ -1,6 +1,7 @@
 "use client";
 import { merge, resource, resumingFrom, searchOver, } from "@sincpro/criteria";
 import { useReading } from "@sincpro/criteria-react";
+import { isList, scopeOf } from "../core/list.js";
 import { useFramework } from "./context.js";
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 /** How long typing has to pause before the search goes out. */
@@ -11,8 +12,19 @@ function routeOf(list, params) {
         return list;
     return `${list}${list.includes("?") ? "&" : "?"}${query}`;
 }
-export function useListing(entity, options = {}) {
+export function useListing(given, own = {}) {
     const { transport, locale, metas } = useFramework();
+    // A named list is its entity under a fixed scope: the scope ANDs under the caller's own.
+    const definition = isList(given) ? given : undefined;
+    const entity = definition?.entity ?? given;
+    const options = definition === undefined
+        ? own
+        : {
+            ...own,
+            criteria: own.criteria === undefined
+                ? scopeOf(definition)
+                : merge(scopeOf(definition), own.criteria),
+        };
     const route = routeOf(entity.list, options.params);
     const source = useMemo(() => resource((criteria, signal) => transport.list(route, criteria, signal)), [transport, route]);
     // Decided once, at mount: a definition already known means the server is not asked for it
@@ -62,6 +74,22 @@ export function useListing(entity, options = {}) {
     // `base` is the caller's literal: its identity changes every render, its content does not.
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [reading.refine, meta]);
+    const latest = useRef(refine);
+    latest.current = refine;
+    // Typed before the definition arrived: the text had no template to fill, so it asked nothing.
+    // The moment the definition is known, the question on screen is asked again — what a person
+    // typed is never lost to a slow first answer.
+    const typedBeforeModel = useRef(false);
+    if (meta === null && narrowing.text !== "")
+        typedBeforeModel.current = true;
+    useEffect(() => {
+        if (meta === null || !typedBeforeModel.current)
+            return;
+        typedBeforeModel.current = false;
+        refine(narrowing);
+        // Only the arrival of the definition re-asks; `narrowing` is read as it is then.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [meta]);
     const index = cursors.length - 1;
     const turn = (to) => {
         setCursors(to);
@@ -73,13 +101,18 @@ export function useListing(entity, options = {}) {
         setNarrowing(next);
         if (typing.current)
             clearTimeout(typing.current);
+        // The pause ends with the refine of THAT moment, not of the keystroke: a model that arrived
+        // meanwhile fills the search, instead of a stale refine asking unfiltered (CI found it).
         if (debounce)
-            typing.current = setTimeout(() => refine(next), TYPING_PAUSE);
+            typing.current = setTimeout(() => latest.current(next), TYPING_PAUSE);
         else
             refine(next);
     };
     return {
         entity,
+        ...(definition === undefined ? {} : { definition }),
+        route,
+        question: narrowed(narrowing),
         rows: reading.rows,
         meta,
         count: reading.count,
@@ -94,7 +127,7 @@ export function useListing(entity, options = {}) {
         },
         reload: () => void reading.reload(),
         text: narrowing.text,
-        search: (text) => narrow({ text }, true),
+        search: (text, options) => narrow({ text }, options?.now !== true),
         where: narrowing.where,
         filter: (where) => narrow({ where }, false),
         order: narrowing.order,
@@ -107,6 +140,8 @@ export function useListing(entity, options = {}) {
             to: index * size + reading.rows.length,
             hasPrev: paging === "pages" && index > 0,
             hasNext: paging === "pages" && reading.cursor !== null,
+            cursors,
+            after: reading.cursor,
         },
         next: () => {
             if (paging === "pages" && reading.cursor !== null)

package/dist/react/useLookup.d.ts

@@ -1,22 +1,47 @@
-import type { AnyRecord } from "@sincpro/criteria";
+import type { AnyRecord, Criteria } from "@sincpro/criteria";
 import type { Entity } from "../core/entity.js";
+import { type ListDefinition } from "../core/list.js";
 import { type LookupOption } from "../core/lookup.js";
 /**
  * The records of an entity as choices — the literal search of a many2one.
  *
  * Context: it is a listing like any other — the entity's own search template fills with what
- * is typed, debounced, asked of the server — whose rows are read as choices (`lookupOf`). One
- * page at a time: a select over ten thousand customers loads the first page and the next on
- * demand, never the table.
+ * is typed, debounced, asked of the server — whose rows are read as choices (`lookupOf`). It
+ * opens on the first TEN in the entity's own order (what Odoo's many2one shows, and what fits
+ * a dropdown); typing asks the server, so the record 123 455 of 200 000 is found by its name
+ * though it was never among the ten. Never the table.
+ *
+ * The chosen record usually is NOT on the page on screen — a search narrowed it, or it lies
+ * past the first ten — so its name is kept: from the options it was seen among, or asked of
+ * the server once by its key (`chosen`).
  */
 export type Lookup = {
     options: LookupOption[];
     text: string;
     search: (text: string) => void;
+    /** The entity has a literal search template: typing asks the server. Without one the
+     *  options are filtered where they are. */
+    searchable: boolean;
     loading: boolean;
     hasMore: boolean;
     more: () => void;
+    /** The chosen record as a choice, whether or not it is among `options`. */
+    chosen: LookupOption | undefined;
+    /** The chosen records of a many2many (`values`), in their order, each as a choice — those
+     *  not known yet are asked of the server in one question. */
+    chosenAll: LookupOption[];
 };
-export declare function useLookup<T extends AnyRecord>(entity: Entity<T>, options?: {
+export declare function useLookup<T extends AnyRecord>(
+/** The entity, or a named list of it: «active customers» chooses only those. */
+entity: Entity<T> | ListDefinition<T>, options?: {
     pageSize?: number;
+    /**
+     * Which records may be chosen at all — the contacts OF the chosen customer, the warehouses
+     * OF the branch. The server applies it under whatever is typed; a new scope starts over.
+     */
+    criteria?: Criteria<T>;
+    /** The key of the chosen record, to keep its name (`chosen`). */
+    value?: string;
+    /** The keys chosen in a many2many, to keep their names (`chosenAll`). */
+    values?: readonly string[];
 }): Lookup;

package/dist/react/useLookup.js

@@ -1,15 +1,68 @@
 "use client";
+import { isList } from "../core/list.js";
 import { lookupOf } from "../core/lookup.js";
+import { useFramework } from "./context.js";
 import { useListing } from "./useListing.js";
-export function useLookup(entity, options = {}) {
+import { useEffect, useRef, useState } from "react";
+/** Ten: what a dropdown shows without scrolling, and what Odoo's many2one asks for. */
+const FIRST = 10;
+export function useLookup(
+/** The entity, or a named list of it: «active customers» chooses only those. */
+entity, options = {}) {
+    const { transport } = useFramework();
     // «More», not pages: a choice list grows downwards, and its ceiling keeps it light.
-    const listing = useListing(entity, { paging: "more", pageSize: options.pageSize ?? 50 });
+    const listing = useListing(entity, {
+        paging: "more",
+        pageSize: options.pageSize ?? FIRST,
+        ...(options.criteria === undefined ? {} : { criteria: options.criteria }),
+    });
+    const base = isList(entity) ? entity.entity : entity;
+    const choices = lookupOf(listing.meta, listing.rows, base.summary);
+    // Every choice seen is remembered: the chosen are named even after the page moved on.
+    const seen = useRef(new Map());
+    for (const one of choices)
+        seen.current.set(one.id, one);
+    const [, setNamed] = useState(0);
+    const value = options.value ?? "";
+    const wanted = options.values ?? (value === "" ? [] : [value]);
+    const missing = wanted.filter((id) => !seen.current.has(id));
+    const missingKey = missing.join("\u0000");
+    // Chosen but never seen (a form opened on a saved record): their names, asked ONCE by key.
+    const route = base.list;
+    const meta = listing.meta;
+    useEffect(() => {
+        if (missingKey === "" || meta === null)
+            return;
+        const keys = missingKey.split("\u0000");
+        const key = meta.get_id || meta.identity || "id";
+        const aborter = new AbortController();
+        transport
+            .list(route, {
+            where: keys.length === 1
+                ? { field: key, operator: "=", value: keys[0] ?? "" }
+                : { field: key, operator: "in", value: keys },
+            pagination: { limit: keys.length },
+            meta: false,
+        }, aborter.signal)
+            .then((page) => {
+            for (const one of lookupOf(meta, page.rows, base.summary))
+                seen.current.set(one.id, one);
+            setNamed((n) => n + 1);
+        })
+            .catch(() => undefined); // unnamed is not an error: the field shows its key
+        return () => aborter.abort();
+    }, [transport, route, meta, missingKey, base.summary]);
+    const known = value === "" ? undefined : seen.current.get(value);
+    const chosenAll = wanted.map((id) => seen.current.get(id) ?? { id, label: id });
     return {
-        options: lookupOf(listing.meta, listing.rows),
+        options: choices,
         text: listing.text,
         search: listing.search,
+        searchable: listing.meta?.search != null,
         loading: listing.status === "loading",
         hasMore: listing.hasMore,
         more: listing.more,
+        chosen: known,
+        chosenAll,
     };
 }

package/dist/react/useRecord.d.ts

@@ -18,6 +18,14 @@ import { type Draft } from "../core/transport.js";
  *     in between, the server answers 409 and the screen says so instead of overwriting.
  *   - **drafts** — an edit kept between requests (sincpro_framework's `Drafts`) comes back with
  *     the record and is shown as restored; `keep()` stores the current one.
+ *   - **creating** — with no id it is a record that does not exist yet: it starts from the
+ *     defaults the model publishes, previews like any other, and `save()` sends it to the
+ *     entity's `create` route with an `Idempotency-Key` (a retry never creates two). When the
+ *     answer carries the new identity, the hook becomes that record; otherwise `edit.created`
+ *     holds the answer and the screen decides where to go.
+ *
+ *     const invoice = useRecord(invoices, "");          // a new one
+ *     const invoice = useRecord(invoices, "F-2026-7");  // an existing one
  */
 export type RecordState<T> = {
     status: "loading";
@@ -62,13 +70,20 @@ export type Editing = {
     draft: Draft | null;
     save: () => Promise<boolean>;
     discard: () => void;
-    /** Store the current edit as a draft — only when the entity declares where. */
+    /** Store the current edit as a draft — only when the entity declares where, and the record
+     *  exists: a draft is kept against a record. */
     keep?: () => Promise<void>;
+    /** What the last create answered, when it did not say the new record's identity. */
+    created: unknown;
 };
 export type RecordReading<T> = RecordState<T> & {
     entity: Entity<T & AnyRecord>;
+    /** The record's key — `""` while it is new, its identity once created. */
+    id: string;
+    /** It does not exist on the server yet. */
+    isNew: boolean;
     locale: string | undefined;
     reload: () => void;
     edit: Editing;
 };
-export declare function useRecord<T extends AnyRecord>(entity: Entity<T>, id: string): RecordReading<T>;
+export declare function useRecord<T extends AnyRecord>(entity: Entity<T>, given: string): RecordReading<T>;