@fieldia/core 0.24.0 → 0.26.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.5"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3 or 0.4 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,94 @@ 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() });
+```
+
+## What a page's records are called
+
+A page may say what its records are, so Fieldia's own sentences name them as
+the business does — "A customer with this phone already exists", "17 customers
+imported", "Are you sure you want to delete this customer?", "New customer" —
+where they said "record", or no noun at all:
+
+```json
+{ "records": { "one": "customer", "other": "customers", "a": "a customer" }, "lowerLabels": true }
+```
+
+`one` and `other` are the words for one record and for more, as they stand
+inside a sentence; a sentence that counts picks one of them as its language does
+for the number. `a` is one with its article, where the language puts one before
+it ("an invoice", "une facture"): Fieldia never guesses an article, so a
+sentence that needs one says "A record …" until it is given.
+
+The page's own `lowerLabels`, beside `records` (label casing is no part of what
+records are called), writes a field's label with a small first letter wherever one of
+Fieldia's sentences puts it after a word of it — the form's messages ("Choose at
+least 2 for interests", "End date can’t be before start date"), a refused save's
+"Not saved. Check: email", a value that waits ("Fix tax rate to see total"), a
+help's, a lock's and a link's × names, a possible duplicate ("A customer with
+this phone already exists"), a conflict ("They changed: phone."), a column's
+grip, a filter's menu, a search's suggestion, a history's "changed status to …"
+— while a label that begins its sentence keeps its capital: "Phone is
+required", and a heading's place, "Status: nothing is called …" (an import's
+refusals, an input's). Off unless said, since only the page knows whether that
+is right: a label whose first word is a name ("IBAN", "VAT number", "WhatsApp",
+"E-mail") stays as written, its first letter alone ever changes ("found in
+Build"), and every label stays as written in a language that writes its nouns
+with a capital (German) or has none (Arabic). One rule says it, `labelAt(template,
+key, lower, locale)`; the form's messages carry the page's ask as
+`messages.lowerLabels` (`fillMessage`). A page asks it with its records named or
+not, a survey too. A line's own dialog says its labels as its record's page asks — a part
+of the same record — unless the line's own page (`lineOpens: "record"`) says
+otherwise; a list's Edit dialog as the list's page asks. Other languages come through the
+page's `translations`, as its other words do (`"customer": "عميل"`), and
+`pageWords` lists them for a translator.
+
+The form's own sentences say them — what it asks before the gear menu's Archive
+and Delete, why a person may not change, archive, copy or delete one, why a run
+of steps stopped, what letting changes go asks — and the viewer's (a list's, a
+record's, possible duplicates', a related list's in its model page's words: see
+`@fieldia/viewer`). Each such sentence is a message of its own beside the plain
+one (`deleteConfirmNoun`: "Are you sure you want to delete this {record}?",
+with `{record}`, `{records}` and `{aRecord}`); `recordSentence(records, named,
+plain, locale)` says one. A language, or an app's own `messages`, that has no
+such sentence says its plain one: a page that names no records reads as before.
+`checkPage` and `validatePage` refuse a word for one or for more left out.
+
 ## Two people, one record
 
 A source that keeps versions returns each record with its version, and what this
@@ -289,6 +392,35 @@ 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
+tab holding one may count its records (`"count": { "related": "<its id>" }`,
+`TabCount`); the check holds that id to a related list inside the tab, and
+`relatedInTab(tab, id)` finds it there. `"open": "app"` sends its rows and New
+the app's own way first (the viewer's `onOpen`), a dialog where it does not take
+them.
+
+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.26.0",
   "description": "Headless form model for Fieldia: the page format, modifiers, validation and record state. No DOM.",
   "license": "MIT",
   "homepage": "https://fieldia.dev",