@fieldia/core 0.26.1 → 0.27.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.5"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3 or 0.4 is read as it is).
+A page says which format it is written in (`"fieldia": "0.6"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3, 0.4 or 0.5 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
@@ -78,6 +78,120 @@ 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.
 
+## Functions, and your app's own
+
+A value worked out (`compute`), a value set by a condition (`setWhen`) and every
+condition call functions by name. Fieldia's own: `round`, `roundMoney`, `min`,
+`max`, `abs`, `sum`, `count`, `average` on numbers; `today`, `days`, `age`,
+`years`, `months`, `addDays`, `addMonths`, `addYears` on dates; `contains`,
+`startsWith`, `endsWith`, `upper`, `lower`, `join`, `len` on words; `if`,
+`empty`, `firstOf` to choose.
+
+```json
+"age":        { "type": "integer",  "label": "Age",            "compute": "age(birth_date)" },
+"second_due": { "type": "date",     "label": "Second payment", "compute": "addMonths(first_due, 1)" },
+"per_meter":  { "type": "monetary", "label": "Price per m²",   "compute": "roundMoney(price / area, currency_id)", "currencyField": "currency_id" },
+"code":       { "type": "char",     "label": "Code",           "compute": "upper(join('-', city, firstOf(nickname, name)))" }
+```
+
+- `age(birth, on?)` counts whole years to today on the page's clock (its `timeZone`),
+  or to a day given; `years(from, to)` and `months(from, to)` count whole ones,
+  negative when the second day comes first.
+- `addMonths(day, n)` ends on a shorter month's last day — 31 January and a month
+  is 28 February — and `months` counts the same way, so the two agree. A date and
+  time keeps its time. `addYears` moves 29 February to the 28th.
+- `contains`, `startsWith` and `endsWith` read text whatever its case; `contains`
+  also finds a value in a list (choices ticked, links).
+- `join(between, values…)` joins the values — lists opened — with the words given
+  first, leaving the empty ones out: `join(' ', first_name, last_name)`.
+- `average` takes values or a list, or a field of the lines where a condition holds,
+  as `sum` does: `average(lines, 'price', "qty > 0")`.
+- `roundMoney(amount, currency)` rounds to the currency's places — three for a
+  Jordanian dinar, none for a yen — the currency a code (`'JOD'`) or a link to one,
+  read by its name.
+- `empty(value)` holds for nothing, words of only spaces, an empty list; zero and
+  no are values. `firstOf(a, b, …)` is the first that is not empty.
+
+Each is read as the page is. **Refused**, by `validatePage`, `checkPage` and so as a
+form is made: a function there is not, or one given too many or too few values.
+**A warning**, never a refusal: a value of a kind a function does not take —
+`age(notes)`: "age takes a date as its first value; "notes" is text". `validatePage`
+passes such a page and says it in `warnings` beside it (`pageWarnings(page)` gives
+them alone; `kindProblems` to your own tools); the designer says it as a fix to make;
+the viewer runs the page as it always did, the call giving nothing — a function given
+a value it cannot use gives nothing, never an error. A page that passed before still
+passes.
+
+**Your app's own.** Give the form `functions` — the viewer and the React, Vue and
+Angular components take the same option — and a page calls them by name, beside
+Fieldia's. A plain function will do; say what it takes and gives, and the page's
+checks and the designer read it:
+
+```ts
+createForm({
+  page,
+  functions: {
+    vatRate: { takes: [1, 1], values: ['text'], gives: 'number', tip: 'The VAT rate of a country: vatRate(country)', call: (country) => RATES[country] ?? 0 },
+    // One that asks your server: a promise.
+    districtPrice: { asks: true, call: (district) => api.get(`/districts/${district}/price`).then((r) => r.perMeter) },
+  },
+});
+```
+
+A number one gives is tidied as Fieldia's own arithmetic tidies one — `price * 1.1`
+of 100 is 110, never 110.00000000000001 — and one that is no number (NaN, Infinity) is
+nothing. A function that asks your server gives a promise. What is worked out from it waits
+while it is asked — empty meanwhile, `form.getState().asked` says so by field
+(`{ total: {} }`), `form.waitsFor('total')` gives `{ field: 'total', asking: true }`,
+and the viewer shows an ellipsis, said in words ("Working out Total…") — then its
+answer is worked into everything after it. It is asked once for the same values,
+for the record shown: another record shown, its answer is laid on none. A save waits
+for every answer; one that failed (`{ failed: 'why' }`) is asked again as the person
+saves, and stops the save under its field when it fails again ("Total could not be
+worked out: …"). A condition calling one does not hold while it is asked. A name a
+page cannot call — Fieldia's own, a word of the language — is refused as the form is
+made. `validatePage(page, { functions })` and `checkPage(page, { functions })` read
+pages that call them.
+
+## Options that follow the answers
+
+An option of a choice may show only while a condition holds, written as a part's
+`invisible`; and a choice may offer the options picked in an earlier one
+(`optionsFrom: { "field": … }`), its own options after them:
+
+```json
+"features": { "type": "selection", "label": "Features", "multiple": true, "options": [
+  { "value": "garden", "label": "Garden",  "invisible": "unit_type != 'villa'" },
+  { "value": "lift",   "label": "Lift",    "invisible": "unit_type == 'villa'" },
+  { "value": "security", "label": "24-hour security" }
+] },
+"again": { "type": "selection", "label": "Which would you have again?",
+  "options": [{ "value": "none", "label": "None of them" }],
+  "optionsFrom": { "field": "treatments" } },
+"try_next": { "type": "selection", "label": "Which would you like to try?", "multiple": true,
+  "options": [], "optionsFrom": { "field": "treatments", "picked": false } }
+```
+
+`form.offered(field)` gives the options a choice offers now: its own — or those its
+app's list gave, or those picked where they are carried from (`picked: false`: those
+left unpicked; a "None of these" is never carried) — less those whose condition hides
+them. A chosen option a change no longer offers is taken out of the answer, never
+silently kept: `form.getState().takenOut` says so by path ("Garden is no longer
+offered, so it was taken out"), until that value is written again — the same words
+for a choice its app's list no longer offers, a page's or a line's. One a record held
+as it was opened stays chosen, and the choice says it is no longer offered. The
+page's checks read each option's condition and refuse a choice carried from itself,
+from a field that is no choice, or round a circle.
+
+A table line's choice takes conditions on its options too, read on the line's own
+values and the record it is on (`parent.`): a room's "Garden room" only on the
+ground floor, a "Pool house" only for a villa. `form.offered("rooms.k1.use")` gives
+a line's by its cell's path; an option a change of the line, or of the record, hides
+is taken out and said by that path (`takenOut["rooms.k1.use"]`). A line's choice
+carries no options from a question: its own, or one of the app's lists — the same
+`optionsFrom` as a page's own choice (`{ list, dependsOn }`, its `dependsOn` naming
+the line's columns or `parent.` and a field).
+
 ## A public form's bot check
 
 A page of responses anyone may send — a sign-up, a contact form — can check that
@@ -115,6 +229,46 @@ viewer draws the hidden box and tells the form when it is filled
 (`form.botCheck({ honeypot: true })`). A page without `botCheck` sends what it
 always did.
 
+## What a page says once it is sent, and answers in its words
+
+A page of responses' `endings` say what it shows once its answers are sent: the
+first whose `when` holds on the answers as they were sent — with what the data
+source answered, the id it gave the response and the values it added — else the
+one with no `when`, shown otherwise, which comes last. `{id}` in its words is
+that reference:
+
+```json
+"endings": [
+  { "when": "overall <= 2", "title": "We are sorry, {name}", "text": "{branch} will call you today.", "again": false },
+  { "title": "Thank you, {name}", "text": "Your booking is {id}.", "again": "Book another" }
+]
+```
+
+```ts
+async submit({ pageId, values }) {
+  const kept = await store(pageId, values);
+  return { id: kept.reference, values: { confirmed_at: kept.confirmedAt } };   // what the ending reads
+}
+form.getState().sent;          // { id: 'B-1043', values: { …the answers sent, confirmed_at } } until reset()
+form.ending();                 // the ending for them, or null
+form.endingWords('Your booking is {id}.');   // "Your booking is B-1043."
+```
+
+`{field}` shows an answer in the page's own words too — a field's label and
+help, each choice's words, a step's title and words, a wizard's and a button's
+words — as in a text's and an alert's: `form.words('How was your visit to
+{branch}?')` is "How was your visit to Zamalek?", and the form's messages name
+the field so ("How was your visit to Zamalek? is required"). How a value reads
+there is the viewer's (`valueWords` in `createForm`'s options: a choice by its
+label, money with its currency, a day in the page's order); without one, a
+choice's label, a link's name, Yes or No, anything else as held. After a bar,
+the words said while the answer is empty — `{branch|this branch}` reads "this
+branch" until one is chosen, translated with the page's other words; without
+them an empty answer says nothing. A `{name}` that is no field of the page is
+refused by the page check. `createMemoryDataSource`
+answers each response as a server would with ``submitted: (request, count) =>
+({ id: `B-${1042 + count}` })``.
+
 ## Files stored as they are picked
 
 Give the data source `upload(file, request)` and a file or picture field sends
@@ -185,6 +339,20 @@ each date and time field that names none, as the form and the viewer read it;
 they use. `checkPage` and `validatePage` refuse a zone the browser does not know.
 Without `timeZone`, the browser's own zone, as before.
 
+A selection's choices may come from the app's own lists (`optionsFrom: { list,
+dependsOn }`), through the data source's `options({ list, values })`, asked again
+when a field in `dependsOn` changes — by the person, a step or the app: a choice
+the new answer does not offer is then taken out and said (`state.takenOut`, as a
+condition's is, until its value changes again); a record that comes in with one
+keeps it, and its save says why. On a table's line they are that line's:
+asked with the line's values and the record it is on as `parent`
+(`dependsOn` naming the line's columns, or `parent.` and a field), shared by the
+lines whose columns hold the same values, and kept by the cell's path in
+`state.choices` (`form.loadChoices("tool_ids.k1.tool")`), taken out and said the
+same way, by the cell's path, as a column they change with changes on that line. `form.lineChoices(field, key, column,
+values)` asks a line's for a row about to be pasted on it. The memory source's
+`lists` functions take the request after the values.
+
 A date and time drawn as booking slots (`"widget": "slots"`) asks the data
 source's `slots(request)` for its free times: the days asked (`from`, `to`, in
 `timeZone`), the schedule its node names (`options.schedule`), the booking's
@@ -240,13 +408,22 @@ source's work, and `saveRefused({ kind: 'rule', message })` refuses it.
 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`).
+"It's someone new" is kept on the app's server where the source has both
+`notDuplicates({ model, recordId }) → ids` (asked as a saved record is shown,
+before its matches are said) and `markNotDuplicate({ model, recordId, matchId })`
+(as it is pressed on a saved record, or a new one is saved after it): a pair,
+answered from either side, so another device lets that record be too; without
+both, the person's browser keeps it (the viewer's `preferences`), as before.
+`form.keepsNotDuplicates()`, `form.notDuplicates()` and
+`form.markNotDuplicate(matchId)` reach them.
 `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:
+in the name field, a name close enough (`nameLikeness`) — its `merge`
+merges as a backend would, and its `notDuplicates` and `markNotDuplicate` keep
+what was let be as pairs (`notDuplicatePairs`, an option to start from):
 
 ```ts
 import { alikeRecords, createMemoryDataSource } from '@fieldia/core';
@@ -254,6 +431,133 @@ import { alikeRecords, createMemoryDataSource } from '@fieldia/core';
 const dataSource = createMemoryDataSource({ records, duplicates: alikeRecords() });
 ```
 
+## A signature that signs the answers
+
+A signature (`"widget": "signature"` on a binary field) may sign answers: `signs`
+names them — `"form"`, every answer shown on the page, or the fields by name —
+and `signerField` the field holding the signer's name (a text, or a link's
+record; left out, the name typed on the pad, else the form's `user`):
+
+```json
+{ "type": "field", "id": "f-signature", "field": "signature", "widget": "signature",
+  "options": { "signs": ["patient", "treatment", "areas", "risks_read"], "signerField": "patient" } }
+```
+
+Signed, it keeps beside its picture who, when and a fingerprint of the answers
+(`FileValue.signed`, a `SignatureEvidence`), once what is typed in them is read
+— an answer still to give, or text that does not read, is said, and nothing is
+signed:
+
+```json
+{ "name": "signature.png", "type": "image/png", "size": 5120, "data": "iVBOR…",
+  "signed": { "format": "fieldia-signature/1", "by": "Mona Adel", "at": "2026-10-19T08:42:00.000Z",
+              "fields": ["patient", "treatment", "areas", "risks_read"],
+              "sha256": "2e3b5fa2ca4b2012eeb1fe7895af5c05dda2c3f5a76246b78fff3b530dbae16d" } }
+```
+
+While a signature with evidence is kept, the form locks the answers it names —
+whatever the page's conditions say (`form.node(id).readonly`,
+`form.fieldReadonly(name)`) — until the person takes it away with Change
+answers, asked first, and signs again. `signedBy(fields, values)` says which
+signature locks which answer; `evidenceOf(value)` reads one. The evidence
+travels in the value: a store that keeps a signature as bytes keeps `signed`
+beside them (a save storing the picture keeps it, as it keeps a typed name's
+`text`). `form.now()`, `form.user()` and `form.shownFields()` are what a
+signature reads — the clock, the person, the answers shown.
+
+**The canonical form, `fieldia-signature/1`.** The fingerprint is the SHA-256,
+in small hexadecimal letters, of the UTF-8 bytes of this JSON, written as
+RFC 8785 (JCS) writes JSON — no spaces, each object's keys in the order of their
+UTF-16 code units, numbers as JavaScript writes them:
+
+```json
+{"answers":{"areas":["forehead"],"patient":"Mona Adel","risks_read":true,"treatment":"botox"},"at":"2026-10-19T08:42:00.000Z","by":"Mona Adel","field":"signature","format":"fieldia-signature/1","page":"clinic-consent"}
+```
+
+— the text of the evidence above, whose SHA-256 is its `sha256`.
+
+`answers` holds each field the evidence names, as the person saw it as they
+signed: nothing (null, an empty text, no choice) is `null`; yes and no `true`
+and `false`; a number itself; a text, a choice's value, a date and a time their
+text as kept; a date and time kept with its zone, its instant in UTC with
+milliseconds; a link its record's id (several, their ids in order); a reference
+`{ "id", "model" }`; a file `{ "name", "size", "type" }`; a table's lines an
+array of each line's own fields; anything else its JSON by these rules. `by` is
+left out when no one is named; `page` is the page's id and `field` the
+signature's. So an app checks a record it keeps in any language — or with the
+evidence part's own functions (@fieldia/widgets' `evidencePart`, the part a
+page whose signature signs answers loads), in a browser or on a server:
+
+```ts
+import { evidencePart } from '@fieldia/widgets';
+
+const { answersMatch, signatureText, sha256Hex } = await evidencePart.load();
+const same = await answersMatch(record.signature.signed, page, 'signature', record);   // true while no signed answer changed
+```
+
+Only a signature the page has sign answers locks them (`signsAnswers(node)`):
+a page whose signature no longer says `signs` treats it as a picture, whatever
+its value carries.
+
+`checkPage` and `validatePage` refuse `signs` that is neither `"form"` nor a
+list of the page's fields, a signature signing itself, and a `signerField` that
+holds no name. Two people signing in turn is the app's (a flow's) to order: each
+signature signs its answers.
+
+## Opening, closing and limiting a form
+
+A page of responses may say when it takes answers, and how many; any choice's
+options may say how many may pick each:
+
+```json
+{
+  "limits": { "opens": "2026-11-01T09:00", "closes": "2026-11-20", "maxResponses": 200, "onePerPerson": true, "message": "See you in December." },
+  "fields": { "session": { "type": "selection", "label": "Session", "options": [{ "value": "am", "label": "Morning", "seats": 30 }] } }
+}
+```
+
+`opens` and `closes` are read on the page's clock (`timeZone`): a day and a
+time, or a day alone — opening at its first minute, closing at its end. The
+data source's `limits({ pageId, model, recordId, fields, user })` answers
+`{ responses, mine, perChoice }`: the responses sent so far, this person's, and
+for each choice field asked how many hold each option (the record edited not
+counted). The form asks it as it opens — `state.limits.state` is `asking`
+meanwhile where the page counts responses — after a record loads, after every
+send, as it starts again, and just before its answers go. `state.limits` tells
+whether it takes answers now (`open`, `soon`, `closed`, `full`, `sent`), when it
+opens and closes, the responses it takes still, and each choice's places
+(`seats[field][value]`: `{ seats, taken, left }`); `takingWords(page, limits,
+messages)` says why it takes none. A full option the person picks is refused,
+said under its field ("Afternoon workshop is full"); one that filled up while
+held, or a page closed since it was opened, stops the send. The app's own
+`setValues` is never refused: the check says it. Without `limits` in the
+source, the page keeps to its dates alone. The memory source counts its own
+responses over its `limits` option's starting counts, and
+`answeredElsewhere(pageId, values)` takes one as someone else would.
+
+## Save and resume on another device
+
+A page with `continueLater` keeps its answers on the app's server as they are
+typed — and as a wizard's step is entered — through the data source's
+`saveDraft({ pageId, model, recordId, key, draft, later })`, which answers with
+the draft's key (and, on Continue later, the `link` to carry on from and words
+of its own); `loadDraft({ pageId, key })` gives the draft back. A draft keeps
+the answers, the wizard's step and the steps passed over, text typed that does
+not read (`unread`, as typed, with why) and the fields answered. The form's
+`resume` (the key from the link) opens it — at its step, or the nearest before
+it that still applies, its unread text said again — and a key that names none
+leaves `state.resume.missing`. `form.continueLater()` reads what is typed and
+keeps the draft (`later: true`); `form.canContinueLater()` says whether the
+page and its source can; the `draft` event tells each draft kept. A send
+carries the draft's key (`SubmitRequest.draft`, `SaveRequest.draft`). Without
+the two members, drafts stay in the browser's store (`drafts.store`), as before
+— with their wizard step now; with them, that store keeps only the key.
+
+```ts
+const form = createForm({ page, dataSource, resume: new URLSearchParams(location.search).get('resume') ?? undefined });
+form.on('draft', ({ key, later, saved }) => later && console.log('Continue from', saved.link));
+```
+
 ## What a page's records are called
 
 A page may say what its records are, so Fieldia's own sentences name them as

package/package.json

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