@sincpro/web-framework 0.0.0-stage → 0.2.0

package/dist/react/useRecord.js

@@ -0,0 +1,272 @@
+"use client";
+import { changesOf, creationOf, defaultsOf, errorsByField, fieldStateOf, missingOf, } from "../core/edit.js";
+import { pathFor } from "../core/entity.js";
+import { retryKeys } from "../core/retry.js";
+import { TransportError } from "../core/transport.js";
+import { useFramework } from "./context.js";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+/** How long typing has to pause before the server is asked what the record becomes. */
+const PREVIEW_PAUSE = 300;
+export function useRecord(entity, given) {
+    const { transport, locale, metas } = useFramework();
+    // A create that answered its identity turns this into that record — until the screen asks
+    // for another one.
+    const [born, setBorn] = useState(null);
+    const id = born !== null && born.from === given ? born.id : given;
+    const isNew = id === "";
+    const [created, setCreated] = useState(null);
+    const creating = useRef(retryKeys());
+    const [state, setState] = useState({
+        status: "loading",
+        record: null,
+        meta: null,
+        error: null,
+    });
+    // Which record `state` was read for: the render after the id changed — a create that answered,
+    // another record asked — must not show the previous one under the new id.
+    const [readFor, setReadFor] = useState(null);
+    const [round, setRound] = useState(0);
+    const [typed, setTyped] = useState({});
+    const [computed, setComputed] = useState({});
+    const [fromServer, setFromServer] = useState({});
+    const [advice, setAdvice] = useState([]);
+    const [saving, setSaving] = useState(false);
+    const [failure, setFailure] = useState(null);
+    const [conflict, setConflict] = useState(false);
+    const [draft, setDraft] = useState(null);
+    const pause = useRef(null);
+    // The preview in flight. A newer one cancels it, and so do a save, a discard and leaving:
+    // an answer about values that are no longer on screen must never land on them.
+    const asking = useRef(null);
+    const mounted = useRef(true);
+    const cancelPreview = () => {
+        if (pause.current)
+            clearTimeout(pause.current);
+        asking.current?.abort();
+        asking.current = null;
+    };
+    const forget = () => {
+        cancelPreview();
+        setTyped({});
+        setComputed({});
+        setFromServer({});
+        setAdvice([]);
+        setFailure(null);
+        setConflict(false);
+    };
+    useEffect(() => {
+        const aborter = new AbortController();
+        // Read again — after a save, a reload — the record on screen STAYS until the answer: a form
+        // that blinked through a skeleton lost its focus, its scroll and the click that landed then.
+        // Only a record not shown yet (another id, the first read) starts as «loading».
+        const again = !isNew && readFor === id;
+        if (!again)
+            setState((now) => ({ status: "loading", record: null, meta: now.meta, error: null }));
+        if (isNew) {
+            // Nothing to read but the model: known already, or asked of the list with no rows.
+            const known = metas.get(entity.key);
+            const asked = known
+                ? Promise.resolve(known)
+                : transport
+                    .list(entity.list, { pagination: { limit: 1 } }, aborter.signal)
+                    .then((page) => page.meta);
+            asked.then((meta) => {
+                if (meta)
+                    metas.set(entity.key, meta);
+                if (aborter.signal.aborted)
+                    return;
+                forget();
+                setDraft(null);
+                setReadFor(id);
+                setState({
+                    status: "ready",
+                    record: defaultsOf(meta),
+                    meta: meta ?? null,
+                    error: null,
+                });
+            }, (error) => {
+                if (aborter.signal.aborted)
+                    return;
+                setReadFor(id);
+                setState((now) => ({ status: "failed", record: null, meta: now.meta, error }));
+            });
+            return () => aborter.abort();
+        }
+        transport.one(entity.one(id), aborter.signal).then((answer) => {
+            if (answer.meta)
+                metas.set(entity.key, answer.meta);
+            if (aborter.signal.aborted)
+                return;
+            forget();
+            setReadFor(id);
+            setDraft(answer.draft);
+            if (answer.draft)
+                setTyped(answer.draft.values);
+            setState({
+                status: "ready",
+                record: answer.record,
+                meta: answer.meta ?? metas.get(entity.key) ?? null,
+                error: null,
+            });
+        }, (error) => {
+            if (aborter.signal.aborted)
+                return;
+            setReadFor(id);
+            setState((now) => ({ status: "failed", record: null, meta: now.meta, error }));
+        });
+        return () => aborter.abort();
+        // `forget` only resets this hook's own state; listing it would reload the record on every
+        // render. What reloads it is the transport, the entity, the id or an explicit `reload()`.
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [transport, metas, entity, id, isNew, round]);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+            cancelPreview();
+        };
+    }, []);
+    const reload = useCallback(() => setRound((n) => n + 1), []);
+    const record = useMemo(() => (state.record ?? {}), [state.record]);
+    const values = useMemo(() => ({ ...record, ...computed, ...typed }), [record, computed, typed]);
+    const changed = useMemo(() => changesOf(record, typed), [record, typed]);
+    const version = record["version"];
+    const ask = (next, name) => {
+        const preview = entity.preview;
+        if (preview === undefined)
+            return;
+        cancelPreview();
+        pause.current = setTimeout(() => {
+            const aborter = new AbortController();
+            asking.current = aborter;
+            transport
+                .send(preview.method, pathFor(preview, isNew ? undefined : id), {
+                id: isNew ? null : id,
+                values: isNew ? { ...record, ...next } : changesOf(record, next),
+                changed: [name],
+            }, aborter.signal)
+                .then((answer) => {
+                if (aborter.signal.aborted || !mounted.current)
+                    return;
+                setComputed(answer.values ?? {});
+                setFromServer(answer.fields ?? {});
+                setAdvice(answer.advice ?? []);
+            }, () => undefined);
+        }, PREVIEW_PAUSE);
+    };
+    const refused = (error) => {
+        if (error instanceof TransportError && error.problem?.kind === "conflict")
+            setConflict(true);
+        else
+            setFailure(error);
+    };
+    const edit = {
+        values,
+        changed,
+        dirty: Object.keys(changed).length > 0,
+        set: (name, value) => {
+            const next = { ...typed, [name]: value };
+            setTyped(next);
+            ask(next, name);
+        },
+        state: (name) => fieldStateOf(state.meta, name, values, fromServer),
+        errors: failure instanceof TransportError ? errorsByField(failure.problem?.errors) : {},
+        advice,
+        missing: missingOf(state.meta, values, fromServer),
+        saving,
+        failure,
+        conflict,
+        restored: draft !== null && Object.keys(changed).length > 0,
+        draft,
+        save: async () => {
+            if (isNew)
+                return create();
+            const route = entity.save;
+            if (route === undefined)
+                throw new Error(`${entity.key} declares no save route`);
+            cancelPreview();
+            setSaving(true);
+            setFailure(null);
+            try {
+                await transport.send(route.method, pathFor(route, id), {
+                    ...changed,
+                    ...(version === undefined ? {} : { version }),
+                });
+                setDraft(null);
+                reload();
+                return true;
+            }
+            catch (error) {
+                // A write is never aborted — the server may have done it — but an answer that comes
+                // back after the screen left lands nowhere.
+                if (mounted.current)
+                    refused(error);
+                return false;
+            }
+            finally {
+                if (mounted.current)
+                    setSaving(false);
+            }
+        },
+        discard: forget,
+        created,
+        ...(entity.draft === undefined || isNew
+            ? {}
+            : {
+                keep: async () => {
+                    const route = entity.draft;
+                    try {
+                        const kept = await transport.send(route.method, pathFor(route, id), {
+                            values: changed,
+                            expected: draft?.version ?? 0,
+                        });
+                        setDraft(kept);
+                    }
+                    catch (error) {
+                        refused(error);
+                    }
+                },
+            }),
+    };
+    async function create() {
+        const route = entity.create;
+        if (route === undefined)
+            throw new Error(`${entity.key} declares no create route`);
+        cancelPreview();
+        setSaving(true);
+        setFailure(null);
+        setCreated(null);
+        const body = creationOf(state.meta, values);
+        const idempotencyKey = creating.current.keyFor(body);
+        try {
+            const answer = await transport.send(route.method, pathFor(route), body, undefined, { idempotencyKey });
+            creating.current.settle(null);
+            if (!mounted.current)
+                return true;
+            const key = state.meta?.get_id || state.meta?.identity || "id";
+            const made = typeof answer === "object" && answer !== null
+                ? answer[key]
+                : undefined;
+            forget();
+            if (typeof made === "string" || typeof made === "number")
+                setBorn({ from: given, id: String(made) });
+            else
+                setCreated(answer);
+            return true;
+        }
+        catch (error) {
+            creating.current.settle(error);
+            if (mounted.current)
+                refused(error);
+            return false;
+        }
+        finally {
+            if (mounted.current)
+                setSaving(false);
+        }
+    }
+    const shown = readFor === id
+        ? state
+        : { status: "loading", record: null, meta: state.meta, error: null };
+    return { ...shown, entity, id, isNew, locale, reload, edit };
+}

package/dist/react/useRelated.d.ts

@@ -0,0 +1,21 @@
+import type { AnyRecord, Criteria } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import type { Listing, ListingOptions } from "./useListing.js";
+import type { RecordReading } from "./useRecord.js";
+/**
+ * The records a relation of ONE record points to, as a live listing of the related entity.
+ *
+ * Context: sincpro_framework sends a one2many inside its record as ONE page (`RecordLines` draws
+ * it). A customer with forty thousand invoices, a tenant with a thousand members, the lines of a
+ * big order need more than that page: search in them, order them, walk them. The model says how
+ * to ask — the related aggregate's key that points back (`identified_by`) — so the relation is
+ * a criteria over the related entity, `where <that key> = <this record's key>`, answered by the
+ * server like any list. The relation's scope is AND-ed with everything else, so no search, filter
+ * or page can ever leave it.
+ *
+ *     const facturas = useRelated(cliente, "invoices", invoicesEntity);
+ *     <EntityList listing={facturas} embedded />
+ */
+export declare function useRelated<P extends AnyRecord, T extends AnyRecord>(record: RecordReading<P>, name: string, related: Entity<T>, options?: Omit<ListingOptions<T>, "criteria"> & {
+    criteria?: Criteria<T>;
+}): Listing<T>;

package/dist/react/useRelated.js

@@ -0,0 +1,32 @@
+"use client";
+import { useListing } from "./useListing.js";
+/**
+ * The records a relation of ONE record points to, as a live listing of the related entity.
+ *
+ * Context: sincpro_framework sends a one2many inside its record as ONE page (`RecordLines` draws
+ * it). A customer with forty thousand invoices, a tenant with a thousand members, the lines of a
+ * big order need more than that page: search in them, order them, walk them. The model says how
+ * to ask — the related aggregate's key that points back (`identified_by`) — so the relation is
+ * a criteria over the related entity, `where <that key> = <this record's key>`, answered by the
+ * server like any list. The relation's scope is AND-ed with everything else, so no search, filter
+ * or page can ever leave it.
+ *
+ *     const facturas = useRelated(cliente, "invoices", invoicesEntity);
+ *     <EntityList listing={facturas} embedded />
+ */
+export function useRelated(record, name, related, options = {}) {
+    const field = record.meta?.fields[name];
+    const key = field?.identified_by ?? "";
+    const own = record.meta?.get_id || record.meta?.identity || "id";
+    const value = record.record === null ? null : record.record[own];
+    const scope = {
+        ...options.criteria,
+        where: {
+            all: [
+                ...(options.criteria?.where ? [options.criteria.where] : []),
+                { field: key, operator: "=", value: value },
+            ],
+        },
+    };
+    return useListing(related, { pageSize: 10, ...options, criteria: scope });
+}

package/dist/react/useSummary.d.ts

@@ -0,0 +1,15 @@
+import type { AnyRecord, Meta } from "@sincpro/criteria";
+import type { Entity } from "../core/entity.js";
+import { type RecordSummary } from "../core/summary.js";
+/**
+ * The summary of any record of an entity, read with the model this application already knows
+ * for it (a list or a record of it was read, or `metas` preloaded it) and in its language.
+ *
+ * Context: a function, not a summary, so a list of N rows asks once and summarizes each row.
+ * The model is looked up on every call: it may arrive after the first render (the first page
+ * of a list brings it), and the next render of whoever holds the rows reads it.
+ *
+ *     const summarize = useSummaryOf(contactos);
+ *     <RecordCard {...cardOf(summarize(row))} />
+ */
+export declare function useSummaryOf<T extends AnyRecord>(entity: Entity<T>): (record: AnyRecord, meta?: Meta | null) => RecordSummary;

package/dist/react/useSummary.js

@@ -0,0 +1,22 @@
+"use client";
+import { summaryOf } from "../core/summary.js";
+import { useFramework } from "./context.js";
+import { useCallback } from "react";
+/**
+ * The summary of any record of an entity, read with the model this application already knows
+ * for it (a list or a record of it was read, or `metas` preloaded it) and in its language.
+ *
+ * Context: a function, not a summary, so a list of N rows asks once and summarizes each row.
+ * The model is looked up on every call: it may arrive after the first render (the first page
+ * of a list brings it), and the next render of whoever holds the rows reads it.
+ *
+ *     const summarize = useSummaryOf(contactos);
+ *     <RecordCard {...cardOf(summarize(row))} />
+ */
+export function useSummaryOf(entity) {
+    const { metas, locale } = useFramework();
+    return useCallback((record, meta) => summaryOf(meta ?? metas.get(entity.key) ?? null, record, {
+        fields: entity.summary,
+        ...(locale === undefined ? {} : { locale }),
+    }), [metas, entity, locale]);
+}

package/dist/web/Refused.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A failure, said the way the server said it: its title, what happened and what to do —
+ * `guidance` included, which is the part a person acts on. Retry only when retrying can help:
+ * a «you have no access» with a retry button is a button that lies.
+ */
+export declare function Refused({ error, onRetry }: {
+    error: unknown;
+    onRetry?: () => void;
+}): import("react").JSX.Element;

package/dist/web/Refused.js

@@ -0,0 +1,14 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { frameworkCopy } from "../core/copy.js";
+import { explain } from "../core/transport.js";
+import { Button, Failed } from "@sincpro/web-ui";
+/**
+ * A failure, said the way the server said it: its title, what happened and what to do —
+ * `guidance` included, which is the part a person acts on. Retry only when retrying can help:
+ * a «you have no access» with a retry button is a button that lies.
+ */
+export function Refused({ error, onRetry }) {
+    const { heading, sentence, retryable } = explain(error);
+    return (_jsx(Failed, { heading: heading, sentence: sentence, action: onRetry !== undefined && retryable ? (_jsx(Button, { size: "sm", role: "secondary", onClick: onRetry, children: frameworkCopy().failure.retry })) : undefined }));
+}

package/dist/web/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The web bindings: what draws a `Listing` and a record with `@sincpro/web-ui`.
+ */
+export { type ColumnOptions, columnsOf } from "./list/columns.js";
+export { EntityList, type EntityListProps } from "./list/EntityList.js";
+export { EntitySearchBar } from "./list/EntitySearchBar.js";
+export { groupableOf, pilesOf } from "./list/groups.js";
+export { type RowCommand, type RowCommands, useRowCommands, } from "./list/rowCommands.js";
+export { facetsOf, modelOf } from "./list/search.js";
+export { CommandButton } from "./record/CommandButton.js";
+export { dirtyOf, type FieldControl, RecordField, } from "./record/edit.js";
+export { EntityPicker } from "./record/EntityPicker.js";
+export { EntityTags } from "./record/EntityTags.js";
+export { countOf, factsOf, RecordLines } from "./record/record.js";
+export { RelatedList } from "./record/RelatedList.js";
+export { cardOf, relationOf } from "./record/summary.js";
+export { Refused } from "./Refused.js";
+export { entityView, type EntityViewOptions, listView, type ListViewOptions, } from "./workspace/composer.js";
+export { openIn, openOptions, RECORD_SIZE, RelatedRecord, targetsFor, } from "./workspace/open.js";
+export { EntityRecord } from "./workspace/record.js";
+export { SincproApp } from "./workspace/SincproApp.js";
+export { webUiSkin } from "./workspace/skin.js";
+export { chooserIn, useFollowed, useRecordInWorkspace, } from "./workspace/workspace.js";

package/dist/web/index.js

@@ -0,0 +1,23 @@
+/**
+ * The web bindings: what draws a `Listing` and a record with `@sincpro/web-ui`.
+ */
+export { columnsOf } from "./list/columns.js";
+export { EntityList } from "./list/EntityList.js";
+export { EntitySearchBar } from "./list/EntitySearchBar.js";
+export { groupableOf, pilesOf } from "./list/groups.js";
+export { useRowCommands, } from "./list/rowCommands.js";
+export { facetsOf, modelOf } from "./list/search.js";
+export { CommandButton } from "./record/CommandButton.js";
+export { dirtyOf, RecordField, } from "./record/edit.js";
+export { EntityPicker } from "./record/EntityPicker.js";
+export { EntityTags } from "./record/EntityTags.js";
+export { countOf, factsOf, RecordLines } from "./record/record.js";
+export { RelatedList } from "./record/RelatedList.js";
+export { cardOf, relationOf } from "./record/summary.js";
+export { Refused } from "./Refused.js";
+export { entityView, listView, } from "./workspace/composer.js";
+export { openIn, openOptions, RECORD_SIZE, RelatedRecord, targetsFor, } from "./workspace/open.js";
+export { EntityRecord } from "./workspace/record.js";
+export { SincproApp } from "./workspace/SincproApp.js";
+export { webUiSkin } from "./workspace/skin.js";
+export { chooserIn, useFollowed, useRecordInWorkspace, } from "./workspace/workspace.js";

package/dist/web/list/EntityList.d.ts

@@ -0,0 +1,92 @@
+import { type AnyRecord } from "@sincpro/criteria";
+import { type WorkspaceApi } from "@sincpro/web-composer";
+import type { NamedFilter } from "../../core/list.js";
+import type { Listing } from "../../react/useListing.js";
+import { type RowCommand } from "./rowCommands.js";
+import { type ListCrumb, type RowAction } from "@sincpro/web-ui";
+import { type ReactNode } from "react";
+/**
+ * A whole collection from a `Listing`: the bar, the search, the set in the views it offers,
+ * and the way through it — the screen forge wrote five times by hand, written once.
+ *
+ * Context: this is the ready-made composition, not a cage. Everything it does is reachable on
+ * its own — `columnsOf` for the columns, `EntitySearchBar` for the search, `useListing` for the
+ * state — so a screen that needs its own bar or a second table writes `List` with those.
+ *
+ * Built for sets of any size: in `pages` mode (the default) the screen holds ONE page and walks
+ * the server's cursor, so a million rows cost what fifty do; in `more` mode it stops growing at
+ * its ceiling and asks to narrow the search. Nothing is filtered, ordered or counted on the
+ * page: every gesture is a question to the server.
+ *
+ * Grouping obeys the same rule: «Group by» in the search bar asks the SERVER for the groups of
+ * the whole set (`useGroups`), drawn as piles with their real count; a group's rows are read
+ * when it is opened. Grouped, the list shows rows: web-ui's table groups the page it holds.
+ *
+ * Where a record opens is the composer's question: with `api`, a row opens the page and the
+ * identity column is the composer's `RecordLink` (peek, side panel, window); without it, the
+ * screen passes `onOpen`.
+ */
+export type { NamedFilter };
+export type EntityListProps<T extends AnyRecord> = {
+    listing: Listing<T>;
+    /**
+     * The workspace this list is a view of. With it, a row opens its record as a page, the
+     * identity column is the composer's `RecordLink` (peek, side panel, window on hover) and the
+     * breadcrumb is the composer's — nothing for the screen to write.
+     */
+    api?: WorkspaceApi;
+    /** The fields shown, in order. Without it, the named list's, or every scalar field. */
+    columns?: readonly string[];
+    /** The cells that are not plain text: a link, a tag. Memoise it: compared by identity. */
+    cells?: Readonly<Partial<Record<string, (row: T) => ReactNode>>>;
+    /**
+     * The ways to look at the set, the first one shown: `table` (columns), `rows` (a name and
+     * its facts, what a narrow panel wants) and `board` (cards). The same set, the same search,
+     * the same page in each.
+     */
+    views?: readonly ("table" | "rows" | "board")[];
+    /** Without it, the model's own name. */
+    title?: string;
+    description?: string;
+    crumbs?: readonly ListCrumb[];
+    actions?: ReactNode;
+    onOpen?: (row: T) => void;
+    onPeek?: (row: T) => void;
+    /** What an empty list says. */
+    empty?: string;
+    /**
+     * `"bar"` (the default) is the full search bar with the criteria builder; `"box"` is one
+     * text box over the entity's search template — a chooser, a narrow panel; `false` is none.
+     * Both ask the server on Enter, never per keystroke: a table is searched on purpose.
+     */
+    search?: "bar" | "box" | false;
+    /** What each group adds up when the list is grouped — «Total 1.204.933,00» in its header,
+     *  summed by the server over every row of it. Without it, the figures the model computes
+     *  (read-only exact numbers, `sumsOf`); `false` adds nothing up. */
+    sums?: readonly string[] | false;
+    /** The cuts this list offers by name: «sólo pagadas», «vencidas». */
+    filters?: readonly NamedFilter<T>[];
+    /**
+     * Rows can be ticked. With `api`, what is ticked is PUBLISHED to the workspace
+     * (`api.select`): a panel beside it follows the selection without knowing this list.
+     */
+    selectable?: boolean;
+    /** What to do with what is ticked: drawn in the bar while something is. */
+    selectionActions?: ReactNode;
+    /** The list is a FIELD of a record — its lines, its members — and not a screen. */
+    embedded?: boolean;
+    /**
+     * With `api` and an entity that declares `create`, the bar offers «New», which opens the
+     * record's form with no id (`entity.newRef()`). `false` hides it — a list of what only a
+     * Command produces, or a caller who may not create.
+     */
+    create?: boolean;
+    /**
+     * The entity's Commands offered on each row («Confirmar»), sent with their idempotency key;
+     * the list is read again when one is done (`useRowCommands`).
+     */
+    commands?: readonly RowCommand<T>[];
+    /** Any other action of a row — or the commands built by hand with `useRowCommands`. */
+    rowActions?: (row: T) => readonly RowAction[];
+};
+export declare function EntityList<T extends AnyRecord>({ listing, api, columns: askedColumns, cells, views: askedViews, title: askedTitle, description: askedDescription, crumbs, actions, onOpen, onPeek, empty, search, sums, filters: askedFilters, selectable, selectionActions, embedded, create, commands, rowActions: askedRowActions, }: EntityListProps<T>): import("react").JSX.Element;