@sincpro/web-framework 0.1.0 → 0.2.0

package/README.md

@@ -8,7 +8,7 @@ server — entities, criteria, commands, drafts, events — and puts it on scree
 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
+yarn add @sincpro/web-framework @sincpro/web-ui @sincpro/web-composer @sincpro/criteria @sincpro/criteria-react react react-dom
 ```
 
 Requires React 19 or newer.
@@ -61,64 +61,231 @@ be able to build it here, without asking us and without fighting us. So:
 | **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
+## How it fits together
+
+Three packages, one direction. **web-ui draws and tells** («they pressed this name, and asked
+for a modal»); it never imports composer and never knows where anything opens. **Composer
+decides where** — page, modal, preview, side panel, window, the breadcrumb, the phone — and never
+draws a record. **This package connects them**, from what the server publishes about each model.
+
+```mermaid
+flowchart LR
+  subgraph server["sincpro_framework · the backend"]
+    api["entities · criteria · commands<br/>drafts · events · model definition"]
+  end
+  subgraph fw["@sincpro/web-framework · connects"]
+    direction TB
+    core["core/<br/>Transport · entity() · Meta<br/>textOf · summaryOf"]
+    react["react/<br/>useListing · useRecord<br/>useLookup · useSummaryOf"]
+    web["web/<br/>EntityList · EntityPicker · RelatedRecord<br/>openIn · entityView · SincproApp"]
+    core --> react --> web
+  end
+  ui["@sincpro/web-ui · draws and tells<br/>List · Record · Picker<br/>RelationValue · RecordCard"]
+  composer["@sincpro/web-composer · decides where<br/>page · modal · preview · side · window<br/>crumbs · ⌘K · phone"]
+  app["your application<br/>entity() + its screens"]
+
+  api <-->|"criteria over the wire<br/>(@sincpro/criteria)"| core
+  web -->|"props read from the model"| ui
+  ui -->|"gestures: onOpenIn(to), onChoose,<br/>onBrowseAll, onCreate"| web
+  web -->|"api.open · api.pick · api.setTitle"| composer
+  composer -->|"mounts the entity's view"| web
+  app -->|"declares"| fw
+```
 
-Declare an entity once — where it is read, and its key in the workspace:
+What happens when a person presses the customer of an invoice:
+
+```mermaid
+sequenceDiagram
+  actor person as Person
+  participant value as RelationValue<br/>(web-ui)
+  participant related as RelatedRecord / openIn<br/>(this package)
+  participant composer as Composer
+  participant view as Customer view<br/>(entityView)
+  participant server as Server
+
+  person->>value: presses «Globex Bolivia»
+  value->>related: onOpenIn("modal") — the first of openTargets
+  related->>related: targetsFor(api): inside a modal? then beside, never a modal
+  related->>composer: api.open(ventas:cliente/C-004, { to: "modal", size: 760×560 })
+  composer->>view: mounts the registered view over the invoice
+  view->>server: useRecord → the record (and its model, once)
+  server-->>view: record + meta
+  view->>composer: api.setTitle("Globex Bolivia") — the modal and the crumb say its name
+```
 
-```ts
-import { entity, restTransport } from "@sincpro/web-framework";
+Everything a screen shows about a value or a record is read from the model the same way, so a
+cell, a fact, a card and a link cannot disagree:
+
+```mermaid
+flowchart LR
+  meta["Meta<br/>(server, defineMeta or OpenAPI)"] --> text["textOf<br/>«Pagada» · 12 mar 2026 · 1 150,50"]
+  meta --> summary["summaryOf<br/>name · description · state · type<br/>image · created · updated"]
+  record["a record"] --> text
+  record --> summary
+  declared["entity(…, { summary })"] -.->|"its own field names"| summary
+  text --> cells["columns · facts · chips"]
+  summary --> card["cardOf → RecordCard"]
+  summary --> relation["relationOf → RelationValue"]
+```
+
+## Integrating it in an application
+
+**1. Styles.** web-ui's tokens, and Tailwind told to look inside the packages (Tailwind v4 skips
+`node_modules`, so their classes would never be generated). Composer brings its own sheet.
+
+```css
+@import "@sincpro/web-ui/tokens.css";
+@source "../node_modules/@sincpro/web-ui/dist";
+@source "../node_modules/@sincpro/web-framework/dist";
+@source "./";
+```
+
+**2. The transport** — the one door to the backend. The session is the application's: it puts
+its headers here.
 
-export const invoices = entity<Invoice>("billing:invoice", { list: "/invoices" });
+```ts
 export const transport = restTransport({
   base: "/v1",
   headers: () => ({ Authorization: `Bearer ${session.token}` }),
 });
 ```
 
-Provide the transport where the application starts:
+**3. The entities** — declared once: where each is read and written, and its key in the
+workspace (`domain:kind`). `summary` only when its fields are not the conventional ones.
+
+```ts
+export const customers = entity<Customer>("sales:customer", {
+  list: "/customers",
+  summary: { image: "logo", person: true },
+});
+export const invoices = entity<Invoice>("sales:invoice", {
+  list: "/invoices",
+  create: "POST /invoices",
+  save: "PUT /invoices/{id}",
+  commands: { post: "POST /invoices/{id}/post" },
+  history: { route: "/sales-events", type: "Invoice" },
+});
+```
+
+**4. The views** — each entity becomes a composer view: its list without an id, its record with
+one, its search in ⌘K. Declared and nothing more, it already has both screens, drawn from its
+model: `EntityList` (literal search on Enter, pages, «New») and `EntityRecord` (its name, type and
+state on top; its fields in the model's order, a many2one as a picker of its entity; each
+one2many in a tab; «save / discard», the conflict, the restored draft, who made it, its history;
+«3 / 64» and the arrows to its neighbours when it was opened from a list).
+
+```ts
+const views = [
+  entityView(invoices, { transport, name: "Invoices" }), // both screens, from the model
+];
+```
+
+They are defaults, not cages: give your own screens, or keep `EntityRecord` and choose what it
+shows.
+
+```ts
+const views = [
+  entityView(invoices, {
+    transport,
+    name: "Invoices",
+    list: InvoiceList,
+    record: InvoiceView,
+  }),
+  entityView(customers, {
+    transport,
+    name: "Customers",
+    list: CustomerList,
+    record: CustomerView,
+  }),
+];
+```
+
+**5. The application** — transport, language (web-ui's, composer's and the framework's words),
+cache, toasts and the workspace, in one place:
 
 ```tsx
-<FrameworkProvider transport={transport} locale="es">
-  <App />
-</FrameworkProvider>
+<SincproApp
+  transport={transport}
+  views={views}
+  entities={[invoices, customers]} // a relation of a model resolves to one of these, alone
+  start={invoices.ref()}
+  language="es"
+/>
 ```
 
-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:
+An application with its own shell mounts the same pieces itself: `FrameworkProvider`, composer's
+`Composer` with `webUiSkin`, and the three copy tables.
+
+**6. The screens.** A list is the entity and the names of its fields — the server searches,
+filters, orders, groups and pages; a row opens the record's page:
 
 ```tsx
-function Invoices({ api }: ViewProps) {
+function InvoiceList({ 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))}
+      api={api}
+      columns={["number", "customer", "state", "amount_total"]}
     />
   );
 }
 ```
 
-One record keeps writing web-ui's `Record` tree; what comes from the model are its props:
+A record keeps writing web-ui's `Record` tree. Its fields come from the model; a related record
+is read with its summary and opened where it belongs; a many2one is chosen with a literal search
+on the server, and «Buscar más…» opens the customers' own list to choose from:
 
 ```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>;
+function InvoiceView({ api, resource }: ViewProps) {
+  const invoice = useRecord(invoices, resource.id ?? "");
+  const crumbs = useCrumbs(api);
+  useRecordInWorkspace(api, invoice); // its real name in the crumb, «unsaved» asks first
+  const dirty = dirtyOf(invoice); // «Save / Discard» while something was typed
+  if (invoice.status !== "ready") return <Skeleton rows={4} label="Loading" />;
+  return (
+    <Record
+      identity={{ title: invoice.record.number }}
+      {...(dirty === undefined ? {} : { dirty })}
+    >
+      <Record.Rail>
+        <Record.Crumbs crumbs={crumbs} />
+        {/* Always there on an edited record: without them web-ui remounts the paper on «dirty». */}
+        <Record.Actions>
+          <CommandButton entity={invoices} id={invoice.id} command="post" label="Post" />
+        </Record.Actions>
+      </Record.Rail>
+      <Record.Paper>
+        <Field label="Customer">
+          <RelatedRecord api={api} entity={customers} value={invoice.record.customer} />
+        </Field>
+        <RecordField
+          record={invoice}
+          name="customer_id"
+          as={({ value, set }) => (
+            <EntityPicker
+              entity={customers}
+              value={String(value ?? "")}
+              onChange={set}
+              onBrowseAll={chooserIn(api, customers, set)}
+            />
+          )}
+        />
+        <RecordField record={invoice} name="notes" />
+      </Record.Paper>
+    </Record>
+  );
+}
+```
+
+Any record, at any size, from its summary:
+
+```tsx
+const summarize = useSummaryOf(customers);
+<RecordCard
+  {...cardOf(summarize(row))}
+  onOpen={() => openIn(api, customers.ref(row.id), "page")}
+/>;
 ```
 
 A domain with no sincpro_framework behind it declares its model by hand and is drawn the same
@@ -138,17 +305,53 @@ const tickets = defineMeta({
 });
 ```
 
+## The abstractions
+
+Each answers one question, and each comes in the three levels — use the component, drop to the
+hook and draw your own, or go straight to the loose piece.
+
+| Question                         | Declarative                                   | Hook                                  | Loose piece                          |
+| -------------------------------- | --------------------------------------------- | ------------------------------------- | ------------------------------------ |
+| Where is the data?               | `entity()`                                    | —                                     | `restTransport`, `memoryTransport`   |
+| What is each field?              | `Meta` from the server, or `defineMeta`       | —                                     | `textOf`, `viewOf`, `metaFromSchema` |
+| What is a record, at any size?   | `cardOf`, `relationOf`                        | `useSummaryOf`                        | `summaryOf`                          |
+| N records: search, filter, page  | `EntityList`, `EntitySearchBar`               | `useListing`, `useGroups`             | `transport.list(route, criteria)`    |
+| A named slice (to collect, …)    | `defineList` + `listView`                     | `useListing(list)`                    | `scopeOf`                            |
+| A record's whole screen          | `EntityRecord`, `entityView` without `record` | —                                     | `formOf`                             |
+| Previous / next from a record    | `EntityRecord` (from a list)                  | —                                     | `placeOf`, `stepIn` (`Trail`)        |
+| How much each group adds up      | `EntityList sums`                             | `useGroups` (`sums`)                  | `sumsOf`, `detailOf`                 |
+| One record: read, edit, save     | `RecordField`, `factsOf`, `RecordLines`       | `useRecord`                           | `transport.one`, `transport.send`    |
+| Its relations, inside it         | `RelatedList`                                 | `useRelated`                          | `relatedOf`                          |
+| Choose one (literal search)      | `EntityPicker`, `chooserIn`                   | `useLookup`                           | `lookupOf` + criteria's `matching`   |
+| Choose several (many2many)       | `EntityTags`                                  | `useLookup` (`values`)                | `lookupOf`                           |
+| A relation, from the model alone | `RecordField name="customer_id"`              | `useEntityFor`                        | `relationFieldOf`, `entityFor`       |
+| Open it where it belongs         | `RelatedRecord`, `entityView`                 | —                                     | `openIn`, `targetsFor`               |
+| Act on it (with a dry run)       | `CommandButton`, `commands` on rows           | `useCommand`                          | `transport.send`                     |
+| What happened to it              | `Record.Activity` fed by `useHistory`         | `useHistory`                          | `historyOf`                          |
+| The application context          | `SincproApp`                                  | `useRecordInWorkspace`, `useFollowed` | `FrameworkProvider`, `webUiSkin`     |
+
+The rules behind them, in short:
+
+- **A reference names any record** (`domain:kind/id`, `entity.ref(id)`). Two contexts talk by
+  reference, never by import; whatever must survive a reload travels in it.
+- **A related record opens in a modal** the size of a record, and «Abrir en…» offers preview,
+  side and page. **From inside a modal**, beside or as a preview — never a modal over a modal.
+  `openIn` decides it from what composer says about the view, so no screen writes it.
+- **What a record does not have is not drawn**: no picture, no image; no state, no tag.
+- **Every word on screen** is the model's (`labelOf`, `choiceLabelOf`) or the framework's copy
+  table (`frameworkCopy()`), never a string in a component.
+
 ### 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               |
+| Folder          | Knows                                                                         | Why apart                                             |
+| --------------- | ----------------------------------------------------------------------------- | ----------------------------------------------------- |
+| `core`          | transport, cache, entity, model definition, what a value and a record read as | plain logic, tested in Node in milliseconds           |
+| `react`         | `useListing`, `useRecord`, `useRelated`, `useSummaryOf`…, 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`, `cardOf` | works outside a workspace (no composer)               |
+| `web/workspace` | the composer: `entityView`, `openIn`, `RelatedRecord`, `<SincproApp>`         | where it opens, the application context               |
 
 Everything is imported from `@sincpro/web-framework`.
 
@@ -174,6 +377,24 @@ Everything is imported from `@sincpro/web-framework`.
 | `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           | ✅     |
+| `useRecord(entity, "")`, `create`      | A new record: the model's defaults, saved to `create`, then it IS the record it became     | ✅     |
+| `retryKeys`, `Idempotency-Key`         | A Command or a create retried after a lost answer runs once, not twice                     | ✅     |
+| `entity.newRef()`, «New» in the list   | The record's form with no id, in a page or a window; replaced by the record once created   | ✅     |
+| `EntityPicker criteria`                | A many2one narrowed by another field: the invoices OF the chosen customer                  | ✅     |
+| `chooserIn`, `entity.chooserRef()`     | «see all…» as the composer's chooser: a row answers (`api.pick`)                           | ✅     |
+| `useGroups`, «Group by»                | Groups counted by the server over the whole set; a group's rows read when it is opened     | ✅     |
+| `defineList`, `listView`               | A named list (a fixed scope, its columns and filters) as data, and as a workspace view     | ✅     |
+| `EntityPicker` `browse`, `columns`     | The chooser always a click away, as a table searched literally by the server               | ✅     |
+| `useFollowed`                          | A detail panel follows the record the person is on, without knowing the list               | ✅     |
+| `commands`, `useRowCommands`           | An entity's Commands on each row, idempotent, offered only where `when` holds              | ✅     |
+| `summaryOf`, `cardOf`, `relationOf`    | Any record at any size: name, description, state, type, picture, who made and changed it   | ✅     |
+| `openIn`, `RelatedRecord`              | A related record opens in a modal; «Abrir en…» for the rest; never a modal over a modal    | ✅     |
+| Literal search everywhere              | Picker: the first ten, the server's search as you type; tables: «Buscar «X»» on Enter      | ✅     |
+| `EntityTags`                           | A many2many as chips over thousands: the server's search, faces, the chosen never again    | ✅     |
+| `RecordField` + `entities`             | A many2one / one2many drawn from the model alone, opened where the view says               | ✅     |
+| `EntityRecord`, `formOf`               | Any entity's record screen without writing it                                              | ✅     |
+| `Trail`, `Record.Pager`                | Previous / next from a record, across the server's pages                                   | ✅     |
+| `EntityList sums`                      | Each group says how much it adds up, summed by the server over all of it                   | ✅     |
 
 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

package/dist/core/cache.js

@@ -30,11 +30,11 @@ export function cachedTransport(transport, options = {}) {
         one(route, signal) {
             return remembered(`one ${route}`, () => transport.one(route, signal));
         },
-        async send(method, route, body, signal) {
+        async send(method, route, body, signal, sending) {
             // 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);
+                return await transport.send(method, route, body, signal, sending);
             }
             finally {
                 // Even a refused write may have changed something (a 409 says someone else did).

package/dist/core/copy.d.ts

@@ -30,6 +30,12 @@ export type FrameworkCopy = {
         capped: (shown: number) => string;
         /** Conditions the server could not answer: the list is WIDER than asked. */
         dropped: (fields: readonly string[]) => string;
+        /** The group of the records that hold no value in the field grouped by. */
+        noValue: string;
+        /** More groups than shown: narrow the set instead of scrolling them. */
+        groupsCapped: (shown: number) => string;
+        /** «12 groups · 187 records»: what the grouping split. */
+        groups: (groups: number, records: number) => string;
     };
     record: {
         /** A draft this caller kept is back on screen. */
@@ -43,6 +49,24 @@ export type FrameworkCopy = {
         loading: string;
         /** Under an embedded list the record holds only one page of. */
         partial: (shown: number, total: number) => string;
+        /** The title of a record that does not exist yet, after the model's name. */
+        creating: (name: string) => string;
+        /** The list's button that opens the form of a new record. */
+        create: string;
+    };
+    picker: {
+        /** The button beside a many2one that opens the chooser over the whole set. */
+        browse: string;
+    };
+    summary: {
+        /** The facts of a record's summary: when it was made and last changed. */
+        created: string;
+        updated: string;
+        /** «12 mar 2026 · Ana Rojas»: when, and who when it is known. */
+        when: (at: string, by: string | null) => string;
+        /** A card's last line: «Updated 12 Mar 2026 by Ana», or «Created …» if never changed. */
+        updatedLine: (at: string, by: string | null) => string;
+        createdLine: (at: string, by: string | null) => string;
     };
     command: {
         /** The confirmation of an action that cannot be undone, after its dry run. */

package/dist/core/copy.js

@@ -15,6 +15,9 @@ export const ENGLISH_FRAMEWORK_COPY = {
         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.`,
+        noValue: "No value",
+        groupsCapped: (shown) => `The first ${shown} groups. Narrow the search to see the rest.`,
+        groups: (groups, records) => `${groups} ${groups === 1 ? "group" : "groups"} · ${records} ${records === 1 ? "record" : "records"}`,
     },
     record: {
         restored: "A draft you kept is back. Save it or discard it.",
@@ -24,6 +27,18 @@ export const ENGLISH_FRAMEWORK_COPY = {
         keep: "Keep draft",
         loading: "Loading the record",
         partial: (shown, total) => `Showing ${shown} of ${total}.`,
+        creating: (name) => (name ? `${name} · new` : "New"),
+        create: "New",
+    },
+    picker: {
+        browse: "Search all",
+    },
+    summary: {
+        created: "Created",
+        updated: "Updated",
+        when: (at, by) => (by === null ? at : `${at} · ${by}`),
+        updatedLine: (at, by) => (by === null ? `Updated ${at}` : `Updated ${at} by ${by}`),
+        createdLine: (at, by) => (by === null ? `Created ${at}` : `Created ${at} by ${by}`),
     },
     command: {
         confirm: "Do it",
@@ -67,6 +82,9 @@ export const SPANISH_FRAMEWORK_COPY = {
         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.`,
+        noValue: "Sin valor",
+        groupsCapped: (shown) => `Los primeros ${shown} grupos. Acotá la búsqueda para ver el resto.`,
+        groups: (groups, records) => `${groups} ${groups === 1 ? "grupo" : "grupos"} · ${records} ${records === 1 ? "registro" : "registros"}`,
     },
     record: {
         restored: "Volvió un borrador que guardaste. Guardalo o descartalo.",
@@ -76,6 +94,18 @@ export const SPANISH_FRAMEWORK_COPY = {
         keep: "Guardar borrador",
         loading: "Cargando el registro",
         partial: (shown, total) => `Se muestran ${shown} de ${total}.`,
+        creating: (name) => (name ? `${name} · nuevo` : "Nuevo"),
+        create: "Nuevo",
+    },
+    picker: {
+        browse: "Buscar en todos",
+    },
+    summary: {
+        created: "Creado",
+        updated: "Actualizado",
+        when: (at, by) => (by === null ? at : `${at} · ${by}`),
+        updatedLine: (at, by) => by === null ? `Actualizado el ${at}` : `Actualizado el ${at} por ${by}`,
+        createdLine: (at, by) => (by === null ? `Creado el ${at}` : `Creado el ${at} por ${by}`),
     },
     command: {
         confirm: "Hacerlo",

package/dist/core/edit.d.ts

@@ -25,3 +25,16 @@ export declare function changesOf(record: AnyRecord, values: AnyRecord): AnyReco
 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>;
+/**
+ * A record that does not exist yet: the defaults the model publishes for each field
+ * (`FieldMeta.default`, sincpro_framework's `defaults_of`), and nothing else.
+ *
+ *     defaultsOf(invoiceMeta)  ->  { state: "draft", payment: "cash", discount: "0" }
+ */
+export declare function defaultsOf(meta: Meta | null | undefined): AnyRecord;
+/**
+ * What a create sends: every value on screen the caller may write. A field the model marks
+ * `readonly` is the server's to fill (the number, the totals), and an empty one is left for
+ * the server's own default — never sent as `""`.
+ */
+export declare function creationOf(meta: Meta | null | undefined, values: AnyRecord): AnyRecord;

package/dist/core/edit.js

@@ -49,3 +49,33 @@ export function errorsByField(errors) {
     }
     return found;
 }
+/**
+ * A record that does not exist yet: the defaults the model publishes for each field
+ * (`FieldMeta.default`, sincpro_framework's `defaults_of`), and nothing else.
+ *
+ *     defaultsOf(invoiceMeta)  ->  { state: "draft", payment: "cash", discount: "0" }
+ */
+export function defaultsOf(meta) {
+    const values = {};
+    for (const [name, field] of Object.entries(meta?.fields ?? {}))
+        if (field.default !== null && field.default !== undefined)
+            values[name] = field.default;
+    return values;
+}
+/**
+ * What a create sends: every value on screen the caller may write. A field the model marks
+ * `readonly` is the server's to fill (the number, the totals), and an empty one is left for
+ * the server's own default — never sent as `""`.
+ */
+export function creationOf(meta, values) {
+    const sent = {};
+    for (const [name, value] of Object.entries(values)) {
+        const field = meta?.fields[name];
+        if (field?.readonly === true)
+            continue;
+        if (value === undefined || value === null || value === "")
+            continue;
+        sent[name] = value;
+    }
+    return sent;
+}

package/dist/core/entity.d.ts

@@ -1,4 +1,5 @@
 import type { AnyRecord } from "@sincpro/criteria";
+import type { SummaryFields } from "./summary.js";
 import type { Method } from "./transport.js";
 /**
  * Everything a screen needs to know about where an entity lives on the server, declared once.
@@ -13,6 +14,7 @@ import type { Method } from "./transport.js";
  *
  *     export const invoices = entity<Invoice>("billing:invoice", {
  *       list: "/invoices",
+ *       create: "POST /invoices",
  *       save: "PUT /invoices/{id}",
  *       preview: "POST /invoices/preview",
  *       commands: { confirm: "POST /invoices/{id}/confirm", cancel: "POST /invoices/{id}/cancel" },
@@ -27,12 +29,19 @@ export type Entity<T extends AnyRecord = AnyRecord> = {
     /** Where the workspace finds it: the list without an id, one record with it — the shape of a
      *  composer `ResourceRef`, built here so no screen writes `{ domain, kind, id }` by hand. */
     ref: (id?: string) => EntityRef;
+    /** A record that does not exist yet — the form that creates one. Its view is the record's. */
+    newRef: () => EntityRef;
+    /** Its list opened to CHOOSE one: a row answers whoever asked (composer's `api.pick`). With
+     *  `query`, the list opens on that literal search — what was typed in the picker. */
+    chooserRef: (query?: string) => EntityRef;
     /** The route of its list. */
     list: string;
     /** The route of one record. */
     one: (id: string) => string;
     /** Its Commands, by name. */
     commands: Readonly<Record<string, WriteRoute>>;
+    /** How a new record is created: the list's own route, usually. */
+    create?: WriteRoute;
     /** How an edit is saved: the record's own route with `{id}`. */
     save?: WriteRoute;
     /** «What does this record become?» before saving — sincpro_framework's `Preview`. */
@@ -44,6 +53,12 @@ export type Entity<T extends AnyRecord = AnyRecord> = {
         route: string;
         type: string;
     };
+    /** Which fields are its description, state, picture… when they are not the conventional
+     *  ones (`summaryOf`). Empty: the convention decides. */
+    summary: SummaryFields;
+    /** The aggregate it is, as a relation of another model names it (`relation: "Cliente"`).
+     *  Without it, the `aggregate` of its model definition, once known. */
+    aggregate?: string;
     /** Only carries the record type; never read. */
     readonly _record?: T;
 };
@@ -52,7 +67,19 @@ export type EntityRef = {
     domain: string;
     kind: string;
     id?: string;
+    params?: Readonly<Record<string, string>>;
 };
+/**
+ * The params that say what a reference without an id is for: `new` is the form of a record
+ * that does not exist yet, `pick` is the list opened to choose one. Params, because they are
+ * what a composer reference carries and survives a reload with.
+ */
+export declare const NEW_PARAM = "new";
+export declare const PICK_PARAM = "pick";
+/** What was typed where the chooser was asked for: its list opens on that search. */
+export declare const QUERY_PARAM = "q";
+/** The list a record was opened from (its `Trail`): «3 / 64» and the arrows to its neighbours. */
+export declare const TRAIL_PARAM = "from";
 /** A write: its method and its path, `{id}` where the record's key goes. */
 export type WriteRoute = {
     method: Method;
@@ -64,6 +91,8 @@ export type EntityRoutes = {
     one?: string;
     /** `"POST /invoices/{id}/confirm"`, by name. */
     commands?: Readonly<Record<string, string>>;
+    /** `"POST /invoices"`: where a new record goes. */
+    create?: string;
     save?: string;
     preview?: string;
     draft?: string;
@@ -71,6 +100,11 @@ export type EntityRoutes = {
         route: string;
         type: string;
     };
+    /** `{ image: "logo", state: "estado_pago", person: true }` — not a route, but declared once
+     *  with the rest of what a screen should not have to know. */
+    summary?: SummaryFields;
+    /** `"Cliente"`: what a many2one of another model calls it, so a form resolves it alone. */
+    aggregate?: string;
 };
 /** `"POST /invoices/{id}/confirm"` → its method and path. A write without a method is a bug. */
 export declare function writeRoute(text: string): WriteRoute;

package/dist/core/entity.js

@@ -1,3 +1,14 @@
+/**
+ * The params that say what a reference without an id is for: `new` is the form of a record
+ * that does not exist yet, `pick` is the list opened to choose one. Params, because they are
+ * what a composer reference carries and survives a reload with.
+ */
+export const NEW_PARAM = "new";
+export const PICK_PARAM = "pick";
+/** What was typed where the chooser was asked for: its list opens on that search. */
+export const QUERY_PARAM = "q";
+/** The list a record was opened from (its `Trail`): «3 / 64» and the arrows to its neighbours. */
+export const TRAIL_PARAM = "from";
 const METHODS = new Set(["POST", "PUT", "PATCH", "DELETE"]);
 /** `"POST /invoices/{id}/confirm"` → its method and path. A write without a method is a bug. */
 export function writeRoute(text) {
@@ -21,12 +32,26 @@ export function entity(key, routes) {
         domain,
         kind,
         ref: (id) => ({ domain, kind, ...(id === undefined || id === "" ? {} : { id }) }),
+        newRef: () => ({ domain, kind, params: { [NEW_PARAM]: "1" } }),
+        chooserRef: (query) => ({
+            domain,
+            kind,
+            params: {
+                [PICK_PARAM]: "1",
+                ...(query === undefined || query.trim() === ""
+                    ? {}
+                    : { [QUERY_PARAM]: query.trim() }),
+            },
+        }),
         list: routes.list,
         one: (id) => template.replace("{id}", encodeURIComponent(id)),
         commands: Object.fromEntries(Object.entries(routes.commands ?? {}).map(([name, text]) => [name, writeRoute(text)])),
+        ...(routes.create === undefined ? {} : { create: writeRoute(routes.create) }),
         ...(routes.save === undefined ? {} : { save: writeRoute(routes.save) }),
         ...(routes.preview === undefined ? {} : { preview: writeRoute(routes.preview) }),
         ...(routes.draft === undefined ? {} : { draft: writeRoute(routes.draft) }),
         ...(routes.history === undefined ? {} : { history: routes.history }),
+        summary: routes.summary ?? {},
+        ...(routes.aggregate === undefined ? {} : { aggregate: routes.aggregate }),
     };
 }