@fieldia/core 0.30.0 → 0.31.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.9"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7 or 0.8 is read as it is).
+A page says which format it is written in (`"fieldia": "0.10"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3, 0.4, 0.5, 0.6, 0.7, 0.8 or 0.9 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,92 @@ settings each kind has are `PART_LOOKS`:
 }
 ```
 
+The validation messages (`MESSAGES`) come in English, Arabic, German and French,
+and in Turkish (`tr`), Persian (`fa`), Urdu (`ur`) and Spanish (`es`) —
+**machine-assisted, not yet reviewed by a native speaker**: every message
+English has, with its blanks, not yet read by a native speaker (corrections
+welcome). Persian and Urdu are written right to left; `readNumber` reads their
+digits (۰–۹) and marks (٫ ٬) as it reads Arabic-Indic ones; a day a message
+names is written by Intl on the Gregorian calendar a value is kept in
+(`dayTag`: Intl's own for Persian is the Solar Hijri — Fieldia shows the
+Gregorian day, in Latin digits, in Persian too, for now). `listComma` gives the
+Arabic comma in Arabic, Persian and Urdu.
+
+`firstWeekday(language, page?)` is the week's first day, `0` Sunday to `6`
+Saturday — the one every week Fieldia draws starts on: a list's "this week" and
+its weeks, a calendar's and a timeline's, a date's and a range's month, booking
+slots' month, a week's hours, a repeat's days, a chatter's history. CLDR's day
+for a region, which is decided in this order:
+
+1. the region of the language's own tag: the page's (`"language": "en-GB"`,
+   where the page is shown in its own language) or the one given (`en-GB`);
+2. else the reader's, where the browser asks for the same language with a
+   region (`navigator.languages`, the first that does): an `en` page read in
+   `en-EG` starts on Saturday, in `en-GB` on Monday, in `en-US` on Sunday;
+3. else the region CLDR has the language most spoken in: the United States'
+   for `en` (Sunday), Egypt's for `ar` and Iran's for `fa` (Saturday),
+   Pakistan's for `ur` (Sunday), Germany's, France's, Turkey's and Spain's
+   (Monday).
+
+The day is the engine's own `Intl.Locale` week info, else CLDR's table (Firefox
+has none). A third argument gives the reader's languages instead of the
+browser's, for a server or a test. In the one-tag script it comes with the parts
+that draw a week (`fieldia.list.js`, `fieldia.date.js`), not with `fieldia.js`:
+`Fieldia.firstWeekday` answers once one has come — `await
+Fieldia.datePart.load()` first where your own code calls it on a page that has
+drawn no week.
+
+Those four come in a chunk each of their own, so an app never carries the words
+of a language it does not show: each package says how it fetches its words
+(`wordsInChunks(tableInChunks(table, { tr: () => import('./tr') … }))`), and
+`wordsReady(tag)` fetches every package's for a language, once — the viewer, a
+map and a chatter wait for it before they draw. Asked for, a package's table for
+the language is there at once, English's words, and filled in place as its chunk
+comes; `wordsComing(tag)` says whether it has yet. Something that reads them
+without waiting gets English, and the console says once what to await.
+
+```ts
+import { wordsReady, createForm, MESSAGES } from '@fieldia/core';
+await wordsReady('tr');
+const form = createForm({ page, messages: MESSAGES.tr });
+```
+
+## A starting page from a schema
+
+`pageFromSchema(input, options)` makes a page from what an app already has: a
+**JSON Schema**, an **OpenAPI** document (a component's schema, or an
+operation's request body and parameters — `schema: 'POST /enquiries'`, an
+`operationId`, or a component's name; `schemaChoices(doc)` lists them), or a
+**model's fields** — Fieldia's own, or a backend's field list such as
+Flectra's `fields_get` (`string`, `selection` pairs, `relation`). Each property
+becomes a field of its kind, with its label (`title`, else its name in words),
+help (`description`), required, read-only, limits (`minimum`, `maximum`,
+`maxLength`, `multipleOf` as decimals), pattern (found anywhere, as JSON Schema
+reads it), choices (`enum`, a union of `const`s) and default; `format` picks the
+box (`date`, `date-time`, `email`, `uri`, `time`, a phone, a password, a
+colour, a file); a list of choices is several picked, a list of files several
+files, a list of objects a table of lines; an object's properties are fields of
+their own in a section of its name. `$ref`s inside the document are followed,
+`allOf` merged, `null` set aside.
+
+```ts
+import { pageFromSchema, validatePage } from '@fieldia/core';
+
+const { page, notes, unmapped } = pageFromSchema(openApi, { schema: 'POST /enquiries', kind: 'screen' });
+validatePage(page).ok; // true: a page Fieldia reads, to edit in the designer
+```
+
+Nothing is dropped quietly: what is kept with a change is in `notes` (a name a
+field cannot have, renamed; an object's properties flattened; a value of a kind
+no field holds — a list of text, a union of kinds — kept as JSON; a limit no
+setting holds, such as `minLength`, left to your server), and what is left out
+in `unmapped` (a `$ref` outside the document, a property of no kind). Each has a
+`code` and the property's path; `schemaNoteWords(note)` says it in English. A
+survey (`kind: 'survey'`) is a step for the page and one for each object, sent
+as responses; a screen keeps a record of `model` (its title's words joined by
+dots unless given). A schema that gives no page throws `SchemaRefused`, its
+`code` saying why. In the designer: **Start from a schema…** on a blank page.
+
 ## Values that wait for a line
 
 A value worked out from others waits while one of them holds text that does
@@ -311,6 +397,94 @@ refused by the page check. `createMemoryDataSource`
 answers each response as a server would with ``submitted: (request, count) =>
 ({ id: `B-${1042 + count}` })``.
 
+## A quiz's results
+
+A page of responses with `quiz` shows the person their results once the answers
+are sent: their score, each question marked right or wrong, the right answer to
+one missed and the question's own feedback. A choice's right answers are its
+options marked `correct`; a question typed — a word, a number — names the
+answers it takes (`quiz.answers`: words whatever their case and spaces, a number
+by its value). A right answer earns its question's `quiz.points`, else the
+page's, else 1; a choice whose options carry points (`score`) earns those, as
+before, marked neither right nor wrong. With several answers, right is exactly
+the right ones.
+
+```json
+"quiz": { "results": "now", "points": 1, "rightAnswers": true },
+"fields": {
+  "reversible": { "type": "selection", "label": "Which filler can be dissolved?",
+    "options": [{ "value": "ha", "label": "Hyaluronic acid", "correct": true }, { "value": "caha", "label": "Calcium hydroxylapatite" }],
+    "quiz": { "feedback": { "right": "Yes: hyaluronidase dissolves it.", "wrong": "Only hyaluronic acid can be dissolved." } } },
+  "enzyme": { "type": "char", "label": "Which enzyme dissolves it?", "quiz": { "answers": ["Hyaluronidase"] } }
+}
+```
+
+The form marks the answers as they go — `form.getState().sent.quiz` is
+`{ score, max, questions: [{ field, points, max, right, answered, rightAnswer?,
+feedback? }] }`, in the order they were asked — with the survey flow's part
+(`formSurveyPart`, asked for as the form opens). `results: "later"` says the
+results come once you have reviewed them, and shows none; `rightAnswers: false`
+keeps the right answers back. The right answers travel in the page, where
+anyone who reads its JSON finds them: a test where that matters keeps them out
+of the page, marks the answers on your server and answers the send with them —
+`submit` returns `{ quiz: { score, max, questions } }`, shown in place of the
+page's. `quizResults(page, values, asked?)` marks answers the page's way for
+your own code. A quiz has no pass mark of its own yet: your server may answer
+the send with a value of its own (`values: { passed: true }`), which an
+ending's `when` reads.
+
+## A review before sending
+
+`review` on a page of responses shows every answer before it is sent — by step
+on a wizard, by titled group on a page of sections — each with Edit back to its
+question, then Send: `true` in Fieldia's words ("Check your answers"), or
+`{ "title": "Before you send", "text": "Press Edit to change one." }` in the
+page's. The viewer draws it (the survey flow's part); the answers are checked as a
+step's are before they show. `form.validate(within)` checks the answers inside
+one part alone — a step, a question — as the review and one question at a time
+do.
+
+## One question at a time
+
+`"flow": "one"` on a page of responses asks one question at a time (the
+viewer's survey part draws it): each question on a screen of its own, Enter or
+OK going on once its answer is checked (`form.validate(within)`, the question's
+part alone), a choice picked going on by itself. A wizard's steps are entered,
+checked and kept as ever. A record's sheet, and a list, are refused it.
+
+## Questions in an order drawn, and N of M
+
+On a page of responses, a wizard's `"order": "random"` shows its steps in an
+order drawn for each respondent — a step `"fixed": true` keeps its place (a
+welcome first, a page about you last) — and a step's or a group's shows its
+questions so: words and pictures, and a question `fixed`, keep their places.
+`"draw": 5` asks 5 of its questions, drawn, the rest never asked (nor
+required, nor sent). The draw is seeded — `createForm`'s `seed` (an
+invitation's code, a candidate's id), else the person's `user.id`, else one of
+the browser's for each response — so the same seed draws the same in every
+engine. The form keeps it as `state.order` (by part, its parts' ids in the
+order shown), in its drafts — a page opened again shows the same questions —
+and sends it with the answers (`SubmitRequest.order`). A quiz's results follow
+the order shown. The draw comes in the survey flow's part (`formSurveyPart`, asked for
+as the form opens; a form made before it came draws once it has).
+
+## A time limit
+
+`"timeLimit": { "minutes": 20, "warn": 2, "then": "send" }` on a page of
+responses, or on one of its steps. A page's clock starts with
+`form.startTimer()` (the viewer's Start), a step's as it is first entered; each
+runs on the form's clock (`now`, `scheduler`) and runs out on time
+(`state.timeUp`, by scope: `#form`, or the step's id). Its answers are then
+locked, and their checks refuse nothing: they go as they stood — a required
+answer not given goes empty. `then: "send"` (a page's default) leaves the send
+to the viewer, at once; a headless app calls `form.save()` as `timeUp` changes.
+`lock` (a step's default) keeps them for the person to send; a step's that
+locks gives way to the next step. `form.countdown()` is the countdown showing
+now (`{ scope, left, ends, stage: 'running' | 'warning' | 'up', … }`). Their
+starts are kept in drafts (`StoredDraft.timers`), so a page opened again goes on
+counting; the send tells `started` and `timeUp`. The clock is the browser's: a
+server that must be sure keeps its own.
+
 ## Files stored as they are picked
 
 Give the data source `upload(file, request)` and a file or picture field sends
@@ -347,6 +521,8 @@ your words and offers no Retry; any other error offers Retry. Stop with an
 { bytesPerSecond, fails } })` is a store as slow, or as unreliable, as a real
 one. Without `upload`, files travel inside the record as base64, as before.
 See [files stored as they are picked](https://fieldia.dev/data/#upload).
+`uploadTo`'s work comes in the files part (0.31), asked for as its first file
+goes — a page with a file field has it already; one with none never downloads it.
 
 A photo set (`"widget": "photos"`, @fieldia/widgets' README) keeps everything in
 the field's value, so any source that keeps a file value keeps it: the photos in
@@ -686,6 +862,105 @@ import { assistStandIn, createMemoryDataSource } from '@fieldia/core';
 const dataSource = createMemoryDataSource({ records, assist: assistStandIn({ drafts: { 'enquiry.reply': (values) => `Dear ${values.partner_name},` } }) });
 ```
 
+## Fields filled from the link
+
+A page may fill fields from the link it is opened with — a campaign's, a
+broker's, a unit's — with no code of the app's:
+
+```json
+{
+  "prefill": { "fromUrl": ["utm_source", "utm_campaign", { "param": "agent", "field": "agent_code" }, "unit"] },
+  "fields": { "utm_source": { "type": "char", "label": "Source" }, "agent_code": { "type": "char", "label": "Agent" }, "unit": { "type": "char", "label": "Unit" } }
+}
+```
+
+`https://homes.example/enquiry?utm_source=whatsapp&agent=mona&unit=B-12` starts
+the form with those values: each parameter named fills the field of its name, or
+the `field` it names, as a new record or response starts — and again after
+Submit another. A field the page fills so and places nowhere is a hidden field:
+sent with the answers (a page of responses otherwise sends only what its
+questions show), seen by no one. One placed on the page shows the value, for the
+person to keep or change. Words are read as the field reads them — a number as a
+number, `yes`/`no`/`1`/`0` for a yes or no, a choice by one of its options'
+values, a day as 2026-10-20, a day and time with its offset — and one that does
+not read so, or that the field's own checks would refuse (its most characters,
+its pattern, its least and most), is left out: a hidden field no one can put
+right never stops a send. The link never writes over an answer: a draft opened
+over it, and what the person types, are theirs; a stored record opened is never
+filled. The form reads `url` (the address, its `?…` part, or the parameters by
+name), else the page's own address (`location.href`) — an app rendered on a
+server, or embedded, gives the one it knows (the React, Vue and Angular
+wrappers' `url`) — and `linkValues(page, url)` is the reading, exported. The page's checks refuse a
+field it has not, a link's field, one worked out, a choice of the app's own
+list, and a field filled twice.
+
+## Proof of an email or a phone
+
+A field drawn as an email or a phone may ask the person to prove it is theirs
+before the answers go — `"options": { "verify": true }`, or `{ "by":
+["whatsapp", "sms"] }` for the ways a code may be sent — where the data source
+has `sendCode({ pageId, model, recordId, field, value, kind, by, language })`
+(answering `{ id, expiresAt, retryAfter, length, message }`) and
+`checkCode({ …, value, code, id })` (answering `{ ok, proof }`, or `{ ok:
+false, triesLeft, expired }`). Fieldia sends nothing and holds no keys: the app
+sends the code its own way. `form.joined('verify')?.mark(field, { value, proof
+})` keeps a proof while the field holds that value (`state.verified`); a send is refused
+while a shown field asking for a code holds a value not proved ("Mobile is not
+confirmed: send a code and type it in"), and every send carries `verified` — by
+field, the value and the proof — for the server to trust.
+`form.joined('verify')?.asks(field)` says whether a field asks for one: never
+where the source lacks either member.
+The memory source sends and checks codes as a service would (its `codes`
+option), each kept in `codes`.
+
+## A payment the answers wait for
+
+A page may take a payment before its answers go — a reservation fee, a deposit
+— through the app's own provider: `"payment": { "label": "Reservation fee",
+"amount": 10000, "currency": "EGP", "when": "visit == 'reserve'" }` (the amount
+a number or a number or money field's name, the currency a code or a field's,
+else a money field's own). Where the data source has `pay(request)` (answering
+`{ status: 'paid' | 'failed' | 'cancelled', reference, message }`), a send
+checks the answers, then waits for the payment — through the host's payment
+step (the viewer's, else `ActionHost.pay`), else the source's `pay` itself — and
+sends nothing unpaid; paid, the send carries `payment` (`{ amount, currency,
+key, reference }`). `request.key` is the same for every try of one response's
+payment: the provider's idempotency key. A send that failed after paying is
+sent again without paying twice. `form.joined('pay')?.due()` says what is due
+now, `state.paid` what was taken. A new payment in the designer asks 100 USD
+until its amount and currency are set. Fieldia holds no keys and no provider's code. The
+memory source answers paid unless its `pay` option says otherwise.
+
+## Sends kept without signal
+
+A page with `"outbox": true` keeps a send that finds no network — a site
+visit's report in a compound, a delivery's proof — on the device and sends it
+when the signal comes back. The form goes on as though it went: a response ends
+"Kept on this device" (`state.outbox.kept`), and `state.outbox` says how many
+wait (`{ waiting, sending, offline, kept, refused }`). The items are kept in the browser's
+IndexedDB (`indexedOutbox()`: never lost on a reload, shared by a site's tabs),
+or the store given as `outbox` (`memoryOutbox()` for tests). A photo the network
+could not take stays in its field as its bytes and is stored through `upload`
+just before its send goes. `form.joined('outbox')` sends what waits in order —
+each item claimed by one sender, sent with `queued: { key, at }` so a server
+can refuse a second try — and keeps a refusal to `retry` or `discard`. Kept sends
+go in the order they were kept; a send made once the signal is back goes first,
+and what waited goes right after it. A new record
+saved twice without signal is saved once, and the form takes its id when it
+went. The memory source's `offline` option fails as a network does.
+
+## Parts that join a form
+
+The four above are parts of their own, asked for as a page needs them
+(`formJoins(page)`): the form knows only that its page asks for one, and each
+joins it by one hook into its send (`FormJoin`) — `before` the send, once the
+form's own checks ran (a field not proved added to what they found; a payment
+not taken, nothing sent), `around` the send itself (what it carries added, or
+kept on the device), and `reset` as another response or record starts. Their
+state, their words and their checks come with them. `form.joined(name)` is a
+part's side of the form once it came — null before, and on a page that asks for
+none; a send made before it came waits for it.
+
 ## What a page's records are called
 
 A page may say what its records are, so Fieldia's own sentences name them as
@@ -737,6 +1012,61 @@ 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.
 
+## Undo and Redo while filling
+
+A form keeps the person's changes to the record shown, for `form.undo()` and
+`form.redo()` (the viewer's Ctrl+Z and Ctrl+Shift+Z): each field written
+(`setValue`), each cell typed in (`updateLine`), each line added, taken away or
+moved — typing on in one box is one change until the box is left
+(`boxLeft`). Each returns what it took (`{ field, line? }`), or null when
+nothing is left; `form.history()` names the next of each without taking it.
+The changes are noted from the first; walking them is the undo part's
+(`pressUndoPart`), asked for with the first change — in by the time a person
+presses Ctrl+Z, and in at once where an app loads it first (`await
+pressUndoPart.load()`): until it has come, `undo` and `redo` take nothing.
+
+```ts
+form.setValue('price', 1200);
+form.boxLeft('price');
+form.undo();        // { field: 'price' }: back to what it held, as the person's own change back
+form.redo();        // { field: 'price' }: 1200 again
+```
+
+What it writes is the person's own change back: the page's `change` steps and
+the source's onchange run as for any, and what is worked out from it follows. A
+step's, a rule's or the app's writes are never a change to take back, and a
+change whose field one of them wrote since — or that is locked now — is passed
+over, never written over theirs. Another record shown, a reload, or `reset()`
+starts with nothing to take back; a form not being edited takes nothing back.
+
+## Changes pushed as they happen, and who else is here
+
+Two optional data source members make an open record live. `subscribe(record,
+push) → stop` is asked as a record is shown and stopped as another is; push
+`{ type: 'record', version?, values?, by?, at? }` as someone else saves it, or
+`{ type: 'deleted', by? }`. Where the person changed nothing, their values are
+laid on the record as stored (`arrived` is told, `conflict: false`); after a
+change of theirs it waits as the conflict a save would meet (`state.conflict`,
+with Reload and Keep mine), their typing untouched. A change without `values`
+is read with `load`; one carrying this form's own version is let go.
+`presence(request, push) → stop` is asked with the form's `user` and whether
+they have changes not saved (`editing`), asked again as that turns; what it
+pushes — the others with the record open — is `state.present`. Both are the
+same call as @fieldia/chatter's `subscribe`, with types that never meet: one
+function may serve both. It comes in a part of its own (`recordLivePart`),
+asked for as a form is made where the source has either member, and never
+where it has neither. The memory source does both with `live: true`
+(`changeElsewhere`, `arrive`, `leave`), and has none of them without.
+
+## Record templates
+
+A record page's `templates` (`true`, or `{ fields }`) keeps a record's values
+by a name, to start new records from. The data source's `templates`,
+`saveTemplate` and `deleteTemplate` keep them on your server
+(`RecordTemplate`: `{ id, name, values, by? }`); the viewer keeps them in its
+`preferences` without them. The memory source has them where its `templates`
+option is given (`{}` for none yet), kept by page id.
+
 ## Two people, one record
 
 A source that keeps versions returns each record with its version, and what this
@@ -1019,6 +1349,37 @@ onAction: async ({ action, values }) => {
 warning. Nothing answered means go on: an `onAction` that returns nothing
 works as it always did.
 
+### Undo after a one-tap press
+
+A button or a gear menu item with `"undo": true` offers Undo in place of
+asking first: once its press has run whole, the words it said — its last `say`,
+or the app's — are given to the host's `say` with a third argument, `{ undo }`
+(else "Done: {label}", the built-in Archive's "Archived."); the words before
+them are said plainly. `undo()` takes the press back and resolves to a
+`RunResult`: the app's own undos (an answer's `undo`, latest first, each
+answered as a call is), the record archived brought back (or the reverse), and
+the values its steps and answers wrote put back — each only while it holds what
+they left — saved again where the press saved. It is offered only where all of
+it can be taken back: a copy, a delete, a post, a page opened, an address, a
+form put back or closed, or a call answered without `undo` say plainly. Steps in
+place of `true` are what Undo runs instead. A call's answer with `undo` offers it
+by itself, for what the app did:
+
+```ts
+onAction: async ({ action, recordId }) => {
+  if (action === 'mark_done') {
+    await api.done(recordId);
+    return { say: { message: 'Follow-up marked done', tone: 'success' }, undo: () => api.reopen(recordId).then(() => ({ reload: true })) };
+  }
+},
+```
+
+Undo's run is told as `run` with the press's id and `.undo` after it
+(`b-done.undo`); a built-in Archive or Delete with `undo` asks nothing first
+unless it says `confirm`. Saying it with Undo and taking it back come in a part
+of their own (`pressUndoPart`, `fieldia.undo.js`): asked for with a page whose
+buttons offer Undo, else as an answer first brings one.
+
 ### The moments
 
 - `open` runs once the form has its values: as soon as a new one is made, and

package/package.json

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