@sincpro/web-framework 0.0.0-stage → 0.2.0

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>;

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

@@ -0,0 +1,71 @@
+import type { Criteria, Dropped, Meta, Page, Problem } from "@sincpro/criteria";
+/**
+ * The one seam between this package and a server.
+ *
+ * Context: a list and a record are the same two questions whatever the wire is — «a page of
+ * these, under this criteria» and «this one». REST today; JSON-RPC and gRPC are the other
+ * wires sincpro_framework serves. Each of those is
+ * one adapter implementing this, and nothing above it changes. A route is a string the adapter
+ * understands: a path for REST, a method for RPC.
+ *
+ * Every adapter throws `TransportError` for a refusal, so a screen explains a failure once
+ * whichever wire it came over.
+ */
+export interface Transport {
+    /** A page of records under the criteria. */
+    list<T>(route: string, criteria: Criteria<T>, signal?: AbortSignal): Promise<Page<T>>;
+    /** 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, 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;
+    meta: Meta | null;
+    dropped: Dropped[];
+    /** What this caller kept of an edit between requests (sincpro_framework `Drafts`). */
+    draft: Draft | null;
+};
+/** A kept edit: the values typed, the version of the draft, the record version it started on. */
+export type Draft = {
+    values: Record<string, unknown>;
+    version: number;
+    origin_version?: number;
+};
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export declare class TransportError extends Error {
+    readonly route: string;
+    readonly status: number | null;
+    readonly problem: Problem | null;
+    constructor(route: string, status: number | null, problem: Problem | null, message?: string);
+}
+/**
+ * What a person reads about a failure: a heading, and a sentence with what happened and what
+ * to do. The server's own words first; the copy table's when it sent none.
+ *
+ *     explain(new TransportError("/x", 403, { kind: "permission_denied", guidance: "Pedí acceso.", … }))
+ *       -> { heading: "No tenés acceso", sentence: "Pedí acceso.", retryable: false }
+ */
+export declare function explain(error: unknown): {
+    heading: string;
+    sentence: string;
+    retryable: boolean;
+};

package/dist/core/transport.js

@@ -0,0 +1,43 @@
+import { frameworkCopy } from "./copy.js";
+/**
+ * A refusal, from any wire. `problem` is what the server said about it (RFC 9457 plus the
+ * engine's `kind`, `next_step`, `guidance`) or `null` when it said nothing readable — a proxy's
+ * HTML page. `status` is `null` when the request never got an answer.
+ */
+export class TransportError extends Error {
+    route;
+    status;
+    problem;
+    constructor(route, status, problem, message) {
+        super(message ?? problem?.detail ?? problem?.title ?? `${status ?? "no answer"} at ${route}`);
+        this.route = route;
+        this.status = status;
+        this.problem = problem;
+        this.name = "TransportError";
+    }
+}
+/**
+ * What a person reads about a failure: a heading, and a sentence with what happened and what
+ * to do. The server's own words first; the copy table's when it sent none.
+ *
+ *     explain(new TransportError("/x", 403, { kind: "permission_denied", guidance: "Pedí acceso.", … }))
+ *       -> { heading: "No tenés acceso", sentence: "Pedí acceso.", retryable: false }
+ */
+export function explain(error) {
+    const copy = frameworkCopy().failure;
+    if (error instanceof TransportError && error.problem !== null) {
+        const { kind, title, detail, guidance, retryable } = error.problem;
+        return {
+            heading: title ?? copy.kind[kind] ?? copy.status(error.status ?? 0),
+            sentence: [detail, guidance].filter(Boolean).join(" "),
+            retryable,
+        };
+    }
+    if (error instanceof TransportError && error.status !== null)
+        return { heading: copy.status(error.status), sentence: error.message, retryable: true };
+    return {
+        heading: copy.unreachable,
+        sentence: error instanceof Error ? error.message : String(error),
+        retryable: true,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Public entry of @sincpro/web-framework — the web client of sincpro_framework, married to
+ * `@sincpro/web-ui` (how it looks) and `@sincpro/web-composer` (where it opens).
+ *
+ * Inside, three folders with one direction: `core/` is plain logic with no React (tested in
+ * Node), `react/` holds state and draws nothing, `web/` draws. `make doctor` keeps the arrows.
+ */
+export * from "./core/index.js";
+export * from "./react/index.js";
+export * from "./web/index.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * Public entry of @sincpro/web-framework — the web client of sincpro_framework, married to
+ * `@sincpro/web-ui` (how it looks) and `@sincpro/web-composer` (where it opens).
+ *
+ * Inside, three folders with one direction: `core/` is plain logic with no React (tested in
+ * Node), `react/` holds state and draws nothing, `web/` draws. `make doctor` keeps the arrows.
+ */
+export * from "./core/index.js";
+export * from "./react/index.js";
+export * from "./web/index.js";

package/dist/react/context.d.ts

@@ -0,0 +1,38 @@
+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";
+/**
+ * Who answers, in which language a screen reads, and which model definitions are already
+ * known — for everything under it.
+ *
+ * Context: a view receives its record reference and nothing else — the composer hands it no
+ * client on purpose — so the transport reaches it through context, set once where the
+ * application starts.
+ */
+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, 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

@@ -0,0 +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, 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 [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

@@ -0,0 +1,14 @@
+/**
+ * The state of a list and a record and the gestures that drive them. It draws nothing — no
+ * DOM, no design system — so a screen can drop `EntityList` and still keep it. `make doctor`
+ * keeps it that way.
+ */
+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

@@ -0,0 +1,14 @@
+/**
+ * The state of a list and a record and the gestures that drive them. It draws nothing — no
+ * DOM, no design system — so a screen can drop `EntityList` and still keep it. `make doctor`
+ * keeps it that way.
+ */
+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

@@ -0,0 +1,30 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import { type Entity } from "../core/entity.js";
+/**
+ * One Command of an entity: run it, or ask first what it would do.
+ *
+ * Context: sincpro_framework runs a Command dry when it carries `dry_run: true` (a
+ * `DryRunnable`): the handler's `preview` answers what it WOULD do — «provider odoo deletes
+ * env-42; its record and history stay» — and nothing is touched. That is the confirmation a
+ * 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. 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;
+    data: Record<string, unknown>;
+};
+export type CommandState<R> = {
+    run: (id?: string, body?: AnyRecord) => Promise<R | undefined>;
+    /** The dry run: what it would do, nothing touched. */
+    rehearse: (id?: string, body?: AnyRecord) => Promise<Rehearsal | undefined>;
+    busy: boolean;
+    error: unknown;
+    /** The last dry run's answer, until `reset`. */
+    rehearsal: Rehearsal | null;
+    reset: () => void;
+};
+export declare function useCommand<T extends AnyRecord, R = unknown>(entity: Entity<T>, name: string): CommandState<R>;

package/dist/react/useCommand.js

@@ -0,0 +1,60 @@
+"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) {
+    const { transport } = useFramework();
+    const route = entity.commands[name];
+    if (route === undefined)
+        throw new Error(`${entity.key} declares no command "${name}"`);
+    const [busy, setBusy] = useState(false);
+    const [error, setError] = useState(null);
+    const [rehearsal, setRehearsal] = useState(null);
+    // A Command is never aborted once sent — the server may have done it — but its answer must
+    // not land on a screen that left.
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => void (mounted.current = false);
+    }, []);
+    // 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 {
+            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;
+        }
+        finally {
+            if (mounted.current)
+                setBusy(false);
+        }
+    }, [transport, route]);
+    return {
+        run: (id, body = {}) => send(id, body, keys.current),
+        rehearse: async (id, body = {}) => {
+            const answer = await send(id, { ...body, dry_run: true }, retryKeys());
+            if (answer !== undefined && mounted.current)
+                setRehearsal(answer);
+            return answer;
+        },
+        busy,
+        error,
+        rehearsal,
+        reset: () => {
+            setRehearsal(null);
+            setError(null);
+        },
+    };
+}

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/useHistory.d.ts

@@ -0,0 +1,5 @@
+import type { AnyRecord } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import { type HistoryEntry } from "../core/history.js";
+import { type DependencyList } from "react";
+export declare function useHistory<T extends AnyRecord>(entity: Entity<T>, id: string, deps?: DependencyList): HistoryEntry[] | undefined;

package/dist/react/useHistory.js

@@ -0,0 +1,41 @@
+"use client";
+import { historyOf } from "../core/history.js";
+import { useFramework } from "./context.js";
+import { useEffect, useState } from "react";
+/**
+ * A record's business events, newest first — what `Record.Activity` draws.
+ *
+ * Context: the history of a record is a criteria over its context's events — `entity_type`
+ * and `entity_id` — so it is read like any list, with the same transport. `undefined` while it
+ * is not read, or when it cannot be: an empty history says «nothing happened», which is a
+ * different claim from «you may not see it». Pass the record among `deps` so a write that
+ * reloads it reads its new facts too.
+ *
+ * Named after sincpro_framework's `history_of`; web-ui's `useActivity` is something else (the
+ * panel's open state).
+ */
+const SHOWN = 100;
+export function useHistory(entity, id, deps = []) {
+    const { transport, locale } = useFramework();
+    const [entries, setEntries] = useState(undefined);
+    const history = entity.history;
+    useEffect(() => {
+        if (history === undefined)
+            return;
+        const aborter = new AbortController();
+        const criteria = {
+            where: {
+                all: [
+                    { field: "entity_type", operator: "=", value: history.type },
+                    { field: "entity_id", operator: "=", value: id },
+                ],
+            },
+            order: [{ field: "created_at", descending: true }],
+            pagination: { limit: SHOWN },
+        };
+        transport.list(history.route, criteria, aborter.signal).then((page) => aborter.signal.aborted || setEntries(historyOf(page.rows, page.meta, locale)), () => aborter.signal.aborted || setEntries(undefined));
+        return () => aborter.abort();
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- the caller names what reloads it
+    }, [transport, history, id, locale, ...deps]);
+    return entries;
+}