@sincpro/web-framework 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SINCPRO S.R.L
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,225 @@
-# Temporary Holding Version
+# @sincpro/web-framework
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+**The web side of how Sincpro builds business software.** It takes what
+[`sincpro_framework`](https://github.com/Sincpro-SRL/sincpro_framework) already resolves on the
+server — entities, criteria, commands, drafts, events — and puts it on screen with
+[`@sincpro/web-ui`](https://github.com/Sincpro-SRL/sincpro_web_ui), opened where
+[`@sincpro/web-composer`](https://github.com/Sincpro-SRL/sincpro_web_composer) says. An
+application declares its entities and names its fields; the rest follows.
+
+```bash
+yarn add @sincpro/web-framework @sincpro/web-ui @sincpro/criteria @sincpro/criteria-react react react-dom
+```
+
+Requires React 19 or newer.
+
+## What we believe
+
+**An ERP is modular, so its framework must be open.** Somebody will always have the case nobody
+foresaw — a reconciliation screen, a strange relation, a wizard over three entities. They must
+be able to build it here, without asking us and without fighting us. So:
+
+1. **Defaults, never cages.** Every piece comes in three levels, and any of them can be skipped:
+
+   | Level        | What you write                              | Example                                                    |
+   | ------------ | ------------------------------------------- | ---------------------------------------------------------- |
+   | Declarative  | names of fields and entities                | `<EntityList listing={l} columns={["number", "state"]} />` |
+   | Hooks        | your own screen over our state              | `useListing` + web-ui's `List`                             |
+   | Loose pieces | straight to criteria, the transport, web-ui | `transport.list(route, criteria)`                          |
+
+   Adding a piece obliges nothing else; removing it breaks nothing else.
+
+2. **We ship good practice, not business rules.** A rule lives in the backend. Here the
+   framework reads what the backend publishes — the model definition, the form hints, the
+   preview, the refusal — and never re-implements it. If a rule matters, the server keeps it.
+
+3. **Integration should be solved once, here.** Every Sincpro application used to write its
+   own client, its own date formatting, its own error box, its own "load more". That is the
+   same code everywhere, and it belongs in one place, written well.
+
+4. **The server describes, the screen decides.** The backend says what a field _is_ — its
+   word, its type, what it accepts, what it points at. Where it goes, how prominent it is and
+   what colour a state is stay in the screen's code. That keeps us out of server-side view
+   XML, which is where frameworks like Odoo stop being extensible.
+
+5. **Many entities, one screen.** Business work happens _between_ records: a list with its
+   detail beside it, an invoice with its lines, a statement reconciled against invoices. The
+   framework is built for that, not for one form at a time.
+
+6. **Use the whole Sincpro stack, not a copy of it.** Composer already knows where things open,
+   what is selected and which keys do what; web-ui already knows how a record looks. This
+   package uses them — it does not wrap them in a second, weaker version.
+
+## The stack
+
+| Project                 | Brings                                                                                                                                                             |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `sincpro_framework`     | Entities, criteria, reads (`Get`, `LiteralSearch`, `Search`, `Preview`), commands and dry runs, drafts, events, permissions, protocols (REST, JSON-RPC, gRPC, MCP) |
+| `@sincpro/criteria`     | The contract with the server: `Criteria`, `Meta`, `Page`, `Problem`                                                                                                |
+| `@sincpro/web-ui`       | What a screen looks like: `List`, `Record`, `SearchBar`, `Picker`, `Activity`                                                                                      |
+| `@sincpro/web-composer` | Where it opens and the context: page, peek, window, panels, shared selection, ⌘K, shortcuts                                                                        |
+| **this package**        | The glue: entity + model definition + state + actions, drawn with web-ui, opened with composer                                                                     |
+| Your application        | What an invoice is                                                                                                                                                 |
+
+## How it works
+
+Declare an entity once — where it is read, and its key in the workspace:
+
+```ts
+import { entity, restTransport } from "@sincpro/web-framework";
+
+export const invoices = entity<Invoice>("billing:invoice", { list: "/invoices" });
+export const transport = restTransport({
+  base: "/v1",
+  headers: () => ({ Authorization: `Bearer ${session.token}` }),
+});
+```
+
+Provide the transport where the application starts:
+
+```tsx
+<FrameworkProvider transport={transport} locale="es">
+  <App />
+</FrameworkProvider>
+```
+
+A list is the entity and the names of its fields. Headers come from the model's labels, each
+cell reads as its value means («Pagada», a local date, an amount with its decimals, a many2one
+as the name of what it points at), the search bar and the criteria builder ask the server, and
+«load more» pages with its cursor:
+
+```tsx
+function Invoices({ api }: ViewProps) {
+  const listing = useListing(invoices);
+  return (
+    <EntityList
+      listing={listing}
+      columns={["number", "customer", "state", "invoice_date", "amount_total"]}
+      filters={[
+        {
+          id: "paid",
+          label: "Only paid",
+          where: { field: "state", operator: "=", value: "paid" },
+        },
+      ]}
+      onOpen={(row) => api.open(invoiceRef(row.number))}
+    />
+  );
+}
+```
+
+One record keeps writing web-ui's `Record` tree; what comes from the model are its props:
+
+```tsx
+const invoice = useRecord(invoices, id);
+// …
+<Record.Paper>
+  <Record.Facts fields={factsOf(invoice.record, invoice.meta, ["customer", "due_date"])} />
+  <Record.Page id="lines" label="Lines" count={countOf(invoice.record, "lines")}>
+    <RecordLines record={invoice.record} meta={invoice.meta} name="lines" />
+  </Record.Page>
+</Record.Paper>;
+```
+
+A domain with no sincpro_framework behind it declares its model by hand and is drawn the same
+way:
+
+```ts
+const tickets = defineMeta({
+  aggregate: "Ticket",
+  identity: "id",
+  display: "title",
+  search: ["title"],
+  fields: {
+    id: field.text({ readonly: true }),
+    title: field.text({ label: { es: "Título" }, required: true }),
+    stage: field.choice(["new", "done"], { labels: { new: { es: "Nuevo" } } }),
+  },
+});
+```
+
+### Inside
+
+Three folders, one direction — `make doctor` keeps the arrows:
+
+| Folder          | Knows                                                                                | Why apart                                             |
+| --------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------- |
+| `core`          | transport, cache, entity, model definition, what a value reads as                    | plain logic, tested in Node in milliseconds           |
+| `react`         | `useListing`, `useRecord`, `useRelated`, `useCommand`…, the provider                 | state that draws nothing: usable without `EntityList` |
+| `web/list`      | a collection: `EntityList`, `EntitySearchBar`, `columnsOf`                           | N records, any size                                   |
+| `web/record`    | one record: `RecordField`, `factsOf`, `RelatedList`, `EntityPicker`, `CommandButton` | works outside a workspace (no composer)               |
+| `web/workspace` | the composer: `entityView`, `webUiSkin`, `useRecordInWorkspace`, `<SincproApp>`      | where it opens, the application context               |
+
+Everything is imported from `@sincpro/web-framework`.
+
+## Where it stands
+
+| Piece                                  | What it solves                                                                             | Status |
+| -------------------------------------- | ------------------------------------------------------------------------------------------ | ------ |
+| `restTransport`, `memoryTransport`     | The backend, or the same engine in memory                                                  | ✅     |
+| `defineMeta`, `metaFromSchema`         | A model by hand, or completed from OpenAPI                                                 | ✅     |
+| `useListing`, `EntityList`             | N records: criteria, search bar, builder, paging                                           | ✅     |
+| `useRecord`, `factsOf`, `RecordLines`  | One record: facts, relations with their real total                                         | ✅     |
+| Preloaded definitions                  | `FrameworkProvider metas`: the model asked once, or never                                  | ✅     |
+| `useLookup`, `EntityPicker`            | Literal search: a many2one select, ⌘K                                                      | ✅     |
+| `useRecord` + `RecordField`, `dirtyOf` | Editing: hints evaluated live, preview, save with version (409), server drafts             | ✅     |
+| `useCommand`, `CommandButton`          | An entity's actions, with a dry run before what destroys                                   | ✅     |
+| `useHistory`                           | Business events in `Record.Activity` (comments: backend first)                             | ✅     |
+| `entityView`                           | An entity as a composer view: list, record, ⌘K search                                      | ✅     |
+| `<SincproApp>`                         | The application context in one place, the workspace dressed as web-ui (`webUiSkin`)        | ✅     |
+| `useRecordInWorkspace`                 | A record tells the workspace its real name and its unsaved work (composer 1.0)             | ✅     |
+| Paging by pages, ceiling on «more»     | One page on screen, walked by the server's cursor: a million rows never freeze it          | ✅     |
+| `cachedTransport`                      | Repeated reads from memory, forgotten when a write touches the entity (on in `SincproApp`) | ✅     |
+| `EntitySearchBar`                      | The search bar + criteria builder as a loose piece, for any `List`                         | ✅     |
+| `EntityList` views                     | The same set as table, rows or board                                                       | ✅     |
+| `useRelated`, `RelatedList`            | A record's relation as a live list: searched and paged by the server, inside a form        | ✅     |
+| `EntityPicker` chooser                 | «see all…» opens the whole set, searched on the server: a many2one over millions           | ✅     |
+
+What it does **not** do: mobile (`sincpro_mobile` has its own core), sessions and login (the
+application's), routing (composer's), string-named widget registries, technical logs on a
+record's screen, business rules.
+
+The full purpose — literal search, drafts, composer context, several entities per screen — is
+in [`docs/PURPOSE.md`](docs/PURPOSE.md); what was found while building and what comes next is in
+[`docs/ROADMAP.md`](docs/ROADMAP.md) (both in Spanish).
+
+## Built for large sets
+
+Nothing is filtered, ordered, counted or grouped on the page: every gesture is a question the
+server answers. A list holds ONE page by default and walks the server's keyset cursor (page
+4 000 costs what page 1 costs); «load more» stops at a ceiling and asks to narrow the search; the
+count is the server's, capped; typing waits for a pause; a newer question cancels the older one;
+the model definition is asked once per entity; repeated reads come from a cache that a write
+clears. Story «15 · Un conjunto grande sin congelar» runs it over 200 000 rows.
+
+## The use cases are the tests
+
+Every use case is a Storybook story run against an in-memory server that answers with the same
+criteria engine as sincpro_framework, and each one carries a `play`. The story IS the test:
+`make test` runs every story in a real Chrome with vitest (`@storybook/addon-vitest`), awaits its
+play and checks its a11y — and the same tests run from Storybook's sidebar («Run tests»). The
+plain logic is tested in Node by the same runner. A case the framework cannot do yet shows up
+there first.
+
+## Development
+
+```bash
+nvm use       # Node 26, from .nvmrc
+make init     # pre-commit + yarn install
+make test     # vitest: the logic in Node + every use case (story + play) in Chrome
+make dev      # Storybook on :6008 — the use cases, «Run tests» in the sidebar
+make build
+```
+
+Every operation — local or CI — goes through the `Makefile`; run `make` to list the targets.
+Working on this repository, human or agent: read [`AGENTS.md`](AGENTS.md) first.
+
+## CI/CD
+
+The workflows in `.github/workflows/` only delegate to the shared `Sincpro-SRL/.github`
+pipeline, which calls `make init`, `make verify-format`, `make test`,
+`make update-version VERSION=x` and `make publish`.
+
+## License
+
+MIT © Sincpro S.R.L.

package/dist/core/cache.d.ts

@@ -0,0 +1,30 @@
+import type { Transport } from "./transport.js";
+/**
+ * A transport that remembers what it read, for a while, and forgets it when something writes.
+ *
+ * Context: in a workspace the same questions come back all the time — the list you go back to
+ * through the breadcrumb, the record reopened from ⌘K, the select that points at the same
+ * customers, two panels on the same entity. Each one was a request. This answers a repeated
+ * read from memory while it is fresh (`ttl`), and drops every answer of an entity the moment
+ * a write touches it: a save, a Command, a draft. Stale data after a write is worse than a
+ * request, so a write always wins.
+ *
+ * What it keys on is the question as it travels — the route and the criteria — so two
+ * different filters, orders or pages never share an answer. A read that fails is not kept.
+ * Only completed answers are remembered: a request aborted half-way is simply not cached.
+ *
+ *     const transport = cachedTransport(restTransport({ base: "/v1" }), { ttl: 30_000 });
+ *     transport.invalidate("/facturas");   // forget an entity by hand (a push from the server)
+ */
+export type CachedTransport = Transport & {
+    /** Forget every answer whose route starts with this path: `"/facturas"` forgets the list,
+     *  every page and filter of it, and every record under it. */
+    invalidate: (path?: string) => void;
+};
+export type CacheOptions = {
+    /** How long an answer is served from memory, in milliseconds. */
+    ttl?: number;
+    /** The clock — for tests. */
+    now?: () => number;
+};
+export declare function cachedTransport(transport: Transport, options?: CacheOptions): CachedTransport;

package/dist/core/cache.js

@@ -0,0 +1,47 @@
+/** The entity a route belongs to: its first segment, `"/facturas/F-1/confirm"` → `"/facturas"`. */
+function rootOf(route) {
+    const path = route.split("?")[0] ?? route;
+    const [, first = ""] = path.split("/");
+    return `/${first}`;
+}
+export function cachedTransport(transport, options = {}) {
+    const ttl = options.ttl ?? 30_000;
+    const now = options.now ?? (() => Date.now());
+    const entries = new Map();
+    async function remembered(key, read) {
+        const kept = entries.get(key);
+        if (kept !== undefined && now() - kept.at < ttl)
+            return kept.answer;
+        const answer = await read();
+        entries.set(key, { at: now(), answer });
+        return answer;
+    }
+    const invalidate = (path) => {
+        if (path === undefined)
+            return entries.clear();
+        for (const key of [...entries.keys()])
+            if (key.slice(key.indexOf(" ") + 1).startsWith(path))
+                entries.delete(key);
+    };
+    return {
+        list(route, criteria, signal) {
+            return remembered(`list ${route} ${JSON.stringify(criteria)}`, () => transport.list(route, criteria, signal));
+        },
+        one(route, signal) {
+            return remembered(`one ${route}`, () => transport.one(route, signal));
+        },
+        async send(method, route, body, signal) {
+            // A preview writes nothing; anything else may have changed what was read.
+            const preview = route.endsWith("/preview");
+            try {
+                return await transport.send(method, route, body, signal);
+            }
+            finally {
+                // Even a refused write may have changed something (a 409 says someone else did).
+                if (!preview)
+                    invalidate(rootOf(route));
+            }
+        },
+        invalidate,
+    };
+}

package/dist/core/copy.d.ts

@@ -0,0 +1,69 @@
+import type { FailureKind } from "@sincpro/criteria";
+/**
+ * Every word the framework writes on its own, in one table — the way `@sincpro/web-ui` and the
+ * composer do it. English by default; an application installs its language ONCE with
+ * `installFrameworkCopy`, and nothing carries a hard-coded string.
+ *
+ * Context: it lives in `core/` and not next to the components because a value is turned into
+ * text here («sí», «3 elementos»), and a cell, a fact and a chip must read it the same.
+ */
+export type FrameworkCopy = {
+    value: {
+        yes: string;
+        no: string;
+        /** A one2many/many2many cell: how many there are, `exact: false` meaning «at least». */
+        items: (count: number, exact: boolean) => string;
+    };
+    list: {
+        loadMore: string;
+        loading: string;
+        /** «12 of 120»: what is on screen against what matches. */
+        shown: (shown: number, total: number, exact: boolean) => string;
+        empty: string;
+        emptyFiltered: string;
+        search: string;
+        /** The search bar, which also takes `#` to pick a field. */
+        searchBar: string;
+        /** The title of the criteria builder's window. */
+        builder: string;
+        /** `more` mode reached its ceiling: what is on screen, and what to do instead. */
+        capped: (shown: number) => string;
+        /** Conditions the server could not answer: the list is WIDER than asked. */
+        dropped: (fields: readonly string[]) => string;
+    };
+    record: {
+        /** A draft this caller kept is back on screen. */
+        restored: string;
+        /** Someone saved it after it was read: nothing was overwritten. */
+        conflict: string;
+        reload: string;
+        /** What is missing before it can be saved. */
+        missing: (fields: readonly string[]) => string;
+        keep: string;
+        loading: string;
+        /** Under an embedded list the record holds only one page of. */
+        partial: (shown: number, total: number) => string;
+    };
+    command: {
+        /** The confirmation of an action that cannot be undone, after its dry run. */
+        confirm: string;
+        cancel: string;
+        /** While the dry run is asked. */
+        rehearsing: string;
+    };
+    failure: {
+        /** The server could not be reached at all — nothing it said is known. */
+        unreachable: string;
+        /** It answered with a status and no problem to read. */
+        status: (status: number) => string;
+        retry: string;
+        /** What each kind of refusal is called when the server sent no title of its own. */
+        kind: Record<FailureKind, string>;
+    };
+};
+export declare const ENGLISH_FRAMEWORK_COPY: FrameworkCopy;
+export declare const SPANISH_FRAMEWORK_COPY: FrameworkCopy;
+/** Install the framework's words once, where the application starts. */
+export declare function installFrameworkCopy(copy: FrameworkCopy): void;
+/** The words in use. A plain read: they are installed before anything draws. */
+export declare const frameworkCopy: () => FrameworkCopy;

package/dist/core/copy.js

@@ -0,0 +1,111 @@
+export const ENGLISH_FRAMEWORK_COPY = {
+    value: {
+        yes: "yes",
+        no: "no",
+        items: (count, exact) => `${count}${exact ? "" : "+"} ${count === 1 ? "item" : "items"}`,
+    },
+    list: {
+        loadMore: "Load more",
+        loading: "Loading…",
+        shown: (shown, total, exact) => `${shown} of ${total}${exact ? "" : "+"}`,
+        empty: "Nothing here yet.",
+        emptyFiltered: "Nothing matches.",
+        search: "Search",
+        searchBar: "Search, or # to pick a field…",
+        builder: "Criteria builder",
+        capped: (shown) => `Showing the first ${shown}. Narrow the search to see the rest.`,
+        dropped: (fields) => `The server ignored a condition on ${fields.join(", ")}: the list shows more than asked.`,
+    },
+    record: {
+        restored: "A draft you kept is back. Save it or discard it.",
+        conflict: "Someone saved this record after you opened it. Nothing was overwritten: read it again.",
+        reload: "Read it again",
+        missing: (fields) => `Missing: ${fields.join(", ")}.`,
+        keep: "Keep draft",
+        loading: "Loading the record",
+        partial: (shown, total) => `Showing ${shown} of ${total}.`,
+    },
+    command: {
+        confirm: "Do it",
+        cancel: "Cancel",
+        rehearsing: "Checking what it would do…",
+    },
+    failure: {
+        unreachable: "The server could not be reached",
+        status: (status) => `The server answered ${status}`,
+        retry: "Retry",
+        kind: {
+            invalid: "The request is not valid",
+            unauthenticated: "Sign in again",
+            permission_denied: "You do not have access",
+            not_found: "It does not exist",
+            conflict: "Someone changed it first",
+            in_progress: "It is still in progress",
+            key_reused: "That request was already sent",
+            domain: "The operation was refused",
+            exhausted: "Too many requests",
+            unavailable: "The service is not available",
+            unknown_outcome: "It is not known whether it was done",
+            internal: "Something failed on the server",
+        },
+    },
+};
+export const SPANISH_FRAMEWORK_COPY = {
+    value: {
+        yes: "sí",
+        no: "no",
+        items: (count, exact) => `${count}${exact ? "" : "+"} ${count === 1 ? "elemento" : "elementos"}`,
+    },
+    list: {
+        loadMore: "Cargar más",
+        loading: "Cargando…",
+        shown: (shown, total, exact) => `${shown} de ${total}${exact ? "" : "+"}`,
+        empty: "Todavía no hay nada.",
+        emptyFiltered: "Nada coincide.",
+        search: "Buscar",
+        searchBar: "Buscar, o # para elegir el campo…",
+        builder: "Constructor de criteria",
+        capped: (shown) => `Se muestran los primeros ${shown}. Refiná la búsqueda para ver el resto.`,
+        dropped: (fields) => `El servidor ignoró una condición sobre ${fields.join(", ")}: la lista muestra más de lo pedido.`,
+    },
+    record: {
+        restored: "Volvió un borrador que guardaste. Guardalo o descartalo.",
+        conflict: "Alguien guardó este registro después de que lo abriste. No se pisó nada: volvé a leerlo.",
+        reload: "Volver a leer",
+        missing: (fields) => `Falta: ${fields.join(", ")}.`,
+        keep: "Guardar borrador",
+        loading: "Cargando el registro",
+        partial: (shown, total) => `Se muestran ${shown} de ${total}.`,
+    },
+    command: {
+        confirm: "Hacerlo",
+        cancel: "Cancelar",
+        rehearsing: "Revisando qué haría…",
+    },
+    failure: {
+        unreachable: "No se pudo hablar con el servidor",
+        status: (status) => `El servidor respondió ${status}`,
+        retry: "Reintentar",
+        kind: {
+            invalid: "El pedido no es válido",
+            unauthenticated: "Volvé a iniciar sesión",
+            permission_denied: "No tenés acceso",
+            not_found: "No existe",
+            conflict: "Alguien lo cambió antes",
+            in_progress: "Todavía está en curso",
+            key_reused: "Ese pedido ya se envió",
+            domain: "La operación fue rechazada",
+            exhausted: "Demasiados pedidos",
+            unavailable: "El servicio no está disponible",
+            unknown_outcome: "No se sabe si se hizo",
+            internal: "Algo falló en el servidor",
+        },
+    },
+};
+let installed = ENGLISH_FRAMEWORK_COPY;
+/** Install the framework's words once, where the application starts. */
+export function installFrameworkCopy(copy) {
+    installed = copy;
+}
+/** The words in use. A plain read: they are installed before anything draws. */
+export const frameworkCopy = () => installed;

package/dist/core/edit.d.ts

@@ -0,0 +1,27 @@
+import { type AnyRecord, type FieldError, type Meta } from "@sincpro/criteria";
+/**
+ * What an edit is, as plain functions: the state of each field and what changed.
+ *
+ * Context: sincpro_framework publishes form HINTS on each field — `readonly`, `required`, and
+ * `readonly_when` / `required_when` / `visible_when` as criteria conditions over the record —
+ * and says they are evaluated «with the same evaluator a client filters with». So a field's
+ * state is `matches(values, condition, meta)` over what is on screen NOW: typing «card» in the
+ * payment makes «card reference» required at once, with no round trip. A `Preview` from the
+ * server, when the entity has one, refines it — the server's word wins.
+ *
+ * Hints are defaults for a screen, never protection: the server keeps whatever rule matters.
+ */
+export type FieldState = {
+    readonly: boolean;
+    required: boolean;
+    visible: boolean;
+};
+/** What a server preview said about a field. */
+export type FieldStates = Readonly<Record<string, Partial<FieldState>>>;
+export declare function fieldStateOf(meta: Meta | null | undefined, name: string, values: AnyRecord, fromServer?: FieldStates): FieldState;
+/** The fields whose value differs from the record's — what a save or a draft sends. */
+export declare function changesOf(record: AnyRecord, values: AnyRecord): AnyRecord;
+/** What is missing before it can be saved: a required, visible, editable field left empty. */
+export declare function missingOf(meta: Meta | null | undefined, values: AnyRecord, fromServer?: FieldStates): string[];
+/** The server's word on a field that did not validate: `errors[].pointer` is a JSON pointer. */
+export declare function errorsByField(errors: readonly FieldError[] | undefined): Record<string, string>;

package/dist/core/edit.js

@@ -0,0 +1,51 @@
+import { matches, } from "@sincpro/criteria";
+function holds(values, condition, meta) {
+    if (condition === null || condition === undefined)
+        return false;
+    return matches(values, condition, meta);
+}
+export function fieldStateOf(meta, name, values, fromServer) {
+    const field = meta?.fields[name];
+    const own = field === undefined || meta == null
+        ? { readonly: false, required: false, visible: true }
+        : {
+            readonly: (field.readonly ?? false) || holds(values, field.readonly_when, meta),
+            required: (field.required ?? false) || holds(values, field.required_when, meta),
+            visible: field.visible_when === null || field.visible_when === undefined
+                ? true
+                : holds(values, field.visible_when, meta),
+        };
+    return { ...own, ...fromServer?.[name] };
+}
+/** The fields whose value differs from the record's — what a save or a draft sends. */
+export function changesOf(record, values) {
+    const changed = {};
+    for (const [name, value] of Object.entries(values))
+        if (JSON.stringify(value) !== JSON.stringify(record[name]))
+            changed[name] = value;
+    return changed;
+}
+/** What is missing before it can be saved: a required, visible, editable field left empty. */
+export function missingOf(meta, values, fromServer) {
+    if (!meta)
+        return [];
+    return Object.keys(meta.fields).filter((name) => {
+        const state = fieldStateOf(meta, name, values, fromServer);
+        const value = values[name];
+        const empty = value === null ||
+            value === undefined ||
+            value === "" ||
+            (Array.isArray(value) && value.length === 0);
+        return state.required && state.visible && !state.readonly && empty;
+    });
+}
+/** The server's word on a field that did not validate: `errors[].pointer` is a JSON pointer. */
+export function errorsByField(errors) {
+    const found = {};
+    for (const error of errors ?? []) {
+        const name = error.pointer.replace(/^\/(values\/)?/, "").split("/")[0] ?? "";
+        if (name !== "" && found[name] === undefined)
+            found[name] = error.detail;
+    }
+    return found;
+}