@fieldia/core 0.24.0 → 0.25.0

package/README.md

@@ -28,7 +28,7 @@ list of records — that your app implements;
 The page format is also a JSON Schema, for editors and other languages:
 `@fieldia/core/page.schema.json`.
 
-A page says which format it is written in (`"fieldia": "0.3"`, `FORMAT_VERSION`; a page in 0.1 or 0.2 is read as it is).
+A page says which format it is written in (`"fieldia": "0.4"`, `FORMAT_VERSION`; a page in 0.1 or 0.2 is read as it is).
 One in an older format is brought up to date as it is read — by `checkPage`,
 `validatePage` and `createForm`, so by the viewer and the designer too — and
 `upgradePage` does it for the pages your app keeps. One newer than this Fieldia
@@ -63,6 +63,21 @@ settings each kind has are `PART_LOOKS`:
 }
 ```
 
+## Values that wait for a line
+
+A value worked out from others waits while one of them holds text that does
+not read — "abc" in a line's Quantity — as the table's own total does, so it is
+never shown counting the value that text replaced. Who works it out does not
+matter: the page (a `compute`, such as `sum(lines, 'subtotal')`, and what is
+worked out from that in turn) or your app (an amount or totals kept whole, read
+only, which a source with an `onchange` works out as the lines change — a sales
+order's Untaxed, Taxes and Total, Flectra's `tax_totals`). `form.waitsFor(field)`
+says what it waits for — `{ field: 'line_ids', line: 1, column: 'qty' }`, the line
+as people count lines, or `{ field: 'rate' }` for a field of the record's own —
+and null when it shows its value; the viewer draws it as a dash, said in words
+("Fix line 1 of Order lines to see Untaxed amount"). An answer your onchange
+gives meanwhile is kept, and shown once the line reads.
+
 ## A public form's bot check
 
 A page of responses anyone may send — a sign-up, a contact form — can check that
@@ -202,6 +217,43 @@ const dataSource = createMemoryDataSource({
 });
 ```
 
+## Possible duplicates and Merge
+
+A record's page may name the fields records like the one typed are found by —
+the same phone, email or tax id, a name close enough:
+
+```json
+{ "duplicates": { "fields": ["name", "phone", "email", "vat"], "on": "type" } }
+```
+
+The data source's `duplicates({ model, recordId, values, fields })` is asked
+with the fields named that hold a value (none: nothing is asked), every value of
+the form and the record typed (null while new), and answers with the records
+like it — `{ matches: [{ id, name, why: ['phone'], score? }] }`, `why` naming
+the fields each matched on. `on: "type"` (the default) asks as those fields are
+typed in, as a saved record opens and as it is saved; `"save"` only as it is
+saved. Nothing is in the way of a save. `merge({ model, keepId, mergeIds,
+values, fields })` keeps `keepId` with the value picked for each field and takes
+`mergeIds` away; moving what was theirs (messages, activities, links) is the
+source's work, and `saveRefused({ kind: 'rule', message })` refuses it.
+`form.findDuplicates()`, `form.readRecord(id)` and `form.merge(…)` ask the
+source for a screen of your own, `form.canFindDuplicates()` and
+`form.canMerge()` say whether it can; the viewer says each match under the field
+it matched on, with Open it, "It's someone new" and Merge (`@fieldia/viewer`).
+`checkPage` and `validatePage` refuse a field the page has not, one named twice,
+and one of a kind records are not compared by (`DUPLICATE_KINDS`). Without
+`duplicates` in the source, nothing is asked. For demos and tests,
+`alikeRecords()` answers from the memory source's records — the same value as
+people write them apart (a phone's spaces, an email's case, a link's record) or,
+in the name field, a name close enough (`nameLikeness`) — and its `merge`
+merges as a backend would:
+
+```ts
+import { alikeRecords, createMemoryDataSource } from '@fieldia/core';
+
+const dataSource = createMemoryDataSource({ records, duplicates: alikeRecords() });
+```
+
 ## Two people, one record
 
 A source that keeps versions returns each record with its version, and what this
@@ -289,6 +341,30 @@ says which fields Edit offers. `createMemoryDataSource` gives `allIds` and
 `writeMany` (each record refused as its save would be), and no `exportRecords`.
 See [many records at once](https://fieldia.dev/data/#many).
 
+## Records that point at this one
+
+A page's `related` part lists another model's records whose link is this
+record — a customer's invoices — inside it (the viewer draws it). Its
+`model`, `field` (their many2one to this page's model), `fields` and `columns`
+say what it lists; `filter`, `sort`, `limit`, `cells`, `searchFields`,
+`viewAll` and `create` the rest. `form.relatedFilter(id)` gives what it asks
+the data source's `list` for, as the source gets it: the link to the record
+shown, then its own filter with each `valueFrom` read from that record — or null
+before the record's first save. No new data source member: `list` answers it.
+The page check holds its columns, order, search and cells to its own `fields`,
+its link to a many2one of theirs to this model, and it to a record's page.
+
+A list's Import makes records from a file's rows. `createMany({ model, records,
+fields })` makes many at once and answers each in order: `{ id }`, or `{ message,
+problem? }` for one it refused; without it the list saves each as a new record,
+`save(newRecordSave(model, fields, values))`. `importRecords({ model, file,
+columns, rows, fields, locale, dateOrder })` takes the file on the server once
+its columns are matched: answer `{ message }`, or `false` to let the browser
+import it. A page offers Import with its list's `import` (`true`, or the
+fields); `importFields(page, list)` says which fields a file's columns may fill.
+`createMemoryDataSource` gives `createMany`. See [many records made at
+once](https://fieldia.dev/data/#import).
+
 ## A saved form placed in another
 
 A block made once — an address, a contact person, a consent — is a page of its

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fieldia/core",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Headless form model for Fieldia: the page format, modifiers, validation and record state. No DOM.",
   "license": "MIT",
   "homepage": "https://fieldia.dev",