@sincpro/web-framework 0.0.0-stage → 0.2.0

package/dist/react/useListing.d.ts

@@ -0,0 +1,93 @@
+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.
+ *
+ * Context: `useReading` from `@sincpro/criteria-react` already owns the hard rules — the
+ * definition asked for once, the stale answer dropped, the cursor never seen. What a screen
+ * still wrote by hand around it (forge's `listState`, `More`, the search box, the order) is
+ * the same on every list, so it lives here. Three things narrow the reading, and they AND:
+ *
+ *     search(text)   the entity's own search template (`meta.search`), as the server fills it
+ *     filter(where)  what a search bar or a criteria builder put — any depth of all/any/negate
+ *     orderBy(sort)  the order, asked of the SERVER: a page sorted locally lies about page two
+ *
+ * All three refine the same reading instead of starting another. It holds state and draws
+ * nothing: `EntityList` draws it, and a screen that needs another shape draws it itself.
+ */
+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;
+    dropped: Dropped[];
+    status: ReadingStatus;
+    error: unknown;
+    hasMore: boolean;
+    locale: string | undefined;
+    more: () => void;
+    reload: () => void;
+    /** What was typed in the search box. */
+    text: string;
+    /** 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;
+    /** The order the server was asked for; `null` is the entity's own default. */
+    order: Sort | null;
+    orderBy: (order: Sort | null) => void;
+    /** How the set is walked: a page at a time, or «load more» up to a ceiling. */
+    paging: Paging;
+    /** Where the page on screen is — `pages` mode. `from`/`to` count from 1. */
+    page: {
+        index: number;
+        size: number;
+        from: number;
+        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;
+    /** `more` mode reached its ceiling: refine the search instead of loading on. */
+    capped: boolean;
+};
+/**
+ * - `pages`: one page on screen at a time, walked by the server's own cursor (keyset — no
+ *   `offset`, so page 4 000 costs what page 1 costs). The DOM holds one page: a set of millions
+ *   never freezes the screen. The default.
+ * - `more`: «load more» appends — natural for short sets, a feed — up to `maxRows`; past it the
+ *   list asks to narrow the search instead of growing the page until it freezes.
+ */
+export type Paging = "pages" | "more";
+export type ListingOptions<T> = {
+    /** The route's own parameters: `{ tenant_id: "acme" }` → `/projects?tenant_id=acme`. */
+    params?: Readonly<Record<string, string>>;
+    /** What this list always asks — a scope. Search, filter and order AND it. */
+    criteria?: Criteria<T>;
+    paging?: Paging;
+    /** Rows per page (or per «load more»). 50 by default; the server's own default too. */
+    pageSize?: number;
+    /** `more` mode: the most rows ever on screen. 500 by default. */
+    maxRows?: number;
+};
+export declare function useListing<T extends AnyRecord>(given: Entity<T> | ListDefinition<T>, own?: ListingOptions<T>): Listing<T>;

package/dist/react/useListing.js

@@ -0,0 +1,156 @@
+"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. */
+const TYPING_PAUSE = 200;
+function routeOf(list, params) {
+    const query = new URLSearchParams(Object.entries(params ?? {}).filter(([, value]) => value !== "")).toString();
+    if (query === "")
+        return list;
+    return `${list}${list.includes("?") ? "&" : "?"}${query}`;
+}
+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
+    // again. Deciding it later would change the criteria and restart the reading.
+    const [preloaded] = useState(() => metas.get(entity.key));
+    const paging = options.paging ?? "pages";
+    const size = options.pageSize ?? options.criteria?.pagination?.limit ?? 50;
+    const maxRows = options.maxRows ?? 500;
+    const asked = {
+        ...options.criteria,
+        pagination: { ...options.criteria?.pagination, limit: size },
+    };
+    const base = preloaded ? { ...asked, meta: false } : asked;
+    const reading = useReading(source, base);
+    // `pages` mode: the cursor that opens each page walked so far — page 0 opens with none.
+    const [cursors, setCursors] = useState([null]);
+    // The definition is kept across refinements: a refine in flight must not blank the columns.
+    const known = useRef(preloaded ?? null);
+    if (reading.meta && reading.meta !== known.current) {
+        known.current = reading.meta;
+        metas.set(entity.key, reading.meta);
+    }
+    const meta = reading.meta ?? known.current;
+    const [narrowing, setNarrowing] = useState({
+        text: "",
+        where: undefined,
+        order: null,
+    });
+    const typing = useRef(null);
+    useEffect(() => () => void (typing.current && clearTimeout(typing.current)), []);
+    const narrowed = (next) => {
+        let criteria = base;
+        const found = searchOver(meta, next.text);
+        if (found !== undefined)
+            criteria = merge(criteria, { where: found });
+        if (next.where !== undefined)
+            criteria = merge(criteria, { where: next.where });
+        if (next.order !== null)
+            criteria = merge(criteria, { order: [next.order] });
+        return criteria;
+    };
+    const refine = useCallback((next) => {
+        // Another question starts on its first page: a cursor belongs to one order and one filter.
+        setCursors([null]);
+        void reading.refine(narrowed(next));
+    }, 
+    // `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);
+        void reading.refine(resumingFrom(narrowed(narrowing), to[to.length - 1] ?? null));
+    };
+    const capped = paging === "more" && reading.rows.length >= maxRows;
+    const narrow = (change, debounce) => {
+        const next = { ...narrowing, ...change };
+        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(() => latest.current(next), TYPING_PAUSE);
+        else
+            refine(next);
+    };
+    return {
+        entity,
+        ...(definition === undefined ? {} : { definition }),
+        route,
+        question: narrowed(narrowing),
+        rows: reading.rows,
+        meta,
+        count: reading.count,
+        dropped: reading.dropped,
+        status: reading.status,
+        error: reading.error,
+        hasMore: paging === "more" && reading.hasMore && !capped,
+        locale,
+        more: () => {
+            if (paging === "more" && !capped)
+                void reading.more();
+        },
+        reload: () => void reading.reload(),
+        text: narrowing.text,
+        search: (text, options) => narrow({ text }, options?.now !== true),
+        where: narrowing.where,
+        filter: (where) => narrow({ where }, false),
+        order: narrowing.order,
+        orderBy: (order) => narrow({ order }, false),
+        paging,
+        page: {
+            index,
+            size,
+            from: reading.rows.length === 0 ? 0 : index * size + 1,
+            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)
+                turn([...cursors, reading.cursor]);
+        },
+        prev: () => {
+            if (paging === "pages" && index > 0)
+                turn(cursors.slice(0, -1));
+        },
+        capped,
+    };
+}

package/dist/react/useLookup.d.ts

@@ -0,0 +1,47 @@
+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`). 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>(
+/** 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

@@ -0,0 +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";
+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 ?? 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: 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

@@ -0,0 +1,89 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+import { type FieldState } from "../core/edit.js";
+import { type Entity } from "../core/entity.js";
+import { type Draft } from "../core/transport.js";
+/**
+ * ONE record of an entity, with the definition of its model — read, and edited.
+ *
+ * Context: forge's console wrote the reading as `useAnswer` and never edited at all, though its
+ * backend had an update route: editing by hand (dirty state, save, discard, conflicts) cost more
+ * than the screen was worth. Here it is the same object:
+ *
+ *   - **reading** — the record and its meta travel together (sincpro_framework's
+ *     `ResponseRecord`); an answer that arrives after the view moved on is dropped.
+ *   - **editing** — `set` keeps what is typed apart from the record; each field's state comes
+ *     from the model's hints evaluated over what is on screen (`fieldStateOf`), refined by the
+ *     server's `Preview` when the entity has one (computed values, states, advice).
+ *   - **saving** — only what changed travels, with the version that was read: if someone saved
+ *     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";
+    record: null;
+    meta: Meta | null;
+    error: null;
+} | {
+    status: "ready";
+    record: T;
+    meta: Meta | null;
+    error: null;
+} | {
+    status: "failed";
+    record: null;
+    meta: Meta | null;
+    error: unknown;
+};
+export type Advice = {
+    field?: string;
+    text: string;
+};
+export type Editing = {
+    /** The record as on screen: what was read, what the server computed, what was typed. */
+    values: AnyRecord;
+    changed: AnyRecord;
+    dirty: boolean;
+    set: (name: string, value: unknown) => void;
+    state: (name: string) => FieldState;
+    /** The server's word on fields that did not validate, by field. */
+    errors: Record<string, string>;
+    advice: Advice[];
+    /** Required, visible, editable and empty: what blocks a save. */
+    missing: string[];
+    saving: boolean;
+    /** The last save's refusal, when it was not a conflict. */
+    failure: unknown;
+    /** Someone saved after this was read: nothing was overwritten. */
+    conflict: boolean;
+    /** The values came back from a kept draft. */
+    restored: boolean;
+    /** The draft this caller keeps on the server, when there is one. */
+    draft: Draft | null;
+    save: () => Promise<boolean>;
+    discard: () => void;
+    /** 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>, given: string): RecordReading<T>;