@fieldia/core 0.23.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.2"`, `FORMAT_VERSION`; a page in 0.1 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,58 @@ 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
+a person sent it (`botCheck`): a box no person sees or reaches, which a bot
+filling every box fills (`honeypot`, on unless `false`); the fewest seconds a
+person takes from the page shown to its send (`minSeconds`, 3 unless said; 0
+tells none); and the slot the app draws its own captcha in (`captcha`: a slot's
+name — Turnstile, reCAPTCHA, hCaptcha):
+
+```json
+"layout": { "type": "sections", "id": "signup", "children": [
+  …,
+  { "type": "slot", "id": "s-captcha", "name": "captcha" }
+] },
+"botCheck": { "minSeconds": 3, "captcha": "captcha" }
+```
+
+Nothing is refused for it on the page: each send tells the app what it saw,
+beside the answers (`submit({ pageId, values, bot })`, and the `send` event), and
+the app decides — keep the response aside, check the token with its service, or
+refuse it:
+
+```ts
+async submit({ pageId, values, bot }) {
+  // bot: { honeypot: false, tooFast: false, seconds: 41.2, captcha: '0.Zx…' }
+  if (bot?.honeypot || bot?.tooFast) return keepAside(pageId, values);
+  if (bot && !(await verifyTurnstile(bot.captcha))) throw saveRefused({ kind: 'rule', message: 'Tick “I am human” first' });
+  return store(pageId, values);
+}
+```
+
+The app's captcha widget hands its token to the form, `form.botCheck({ captcha: token })`
+(null once it expires); a token goes once it is sent, as a captcha's is spent. The
+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.
+
 ## Files stored as they are picked
 
 Give the data source `upload(file, request)` and a file or picture field sends
@@ -96,6 +148,112 @@ your words and offers no Retry; any other error offers Retry. Stop with an
 one. Without `upload`, files travel inside the record as base64, as before.
 See [files stored as they are picked](https://fieldia.dev/data/#upload).
 
+## Lists that add up, and filter by time
+
+A list asks its source's optional `totals({ model, filter, totals, groupBy?,
+interval?, currencies? })` for a column's sum, average, lowest, highest or
+count — over the search, under each group, or the rows ticked (`id in` their
+ids) — and its `groups` for a date by the span it falls in (`interval`: `day`,
+`week`, `month`, `quarter` or `year`, with `weekStart` and `timeZone`), each
+group's value its span's first day. An amount named in `currencies` (by the
+field holding each record's currency) is totalled within one currency only:
+over several, its sum is `null`, and `currencies` in the answer names the one
+it is in. A period a list's filter names ("This month", "Overdue") arrives as
+plain conditions. `spanStart(value, interval, { weekStart, timeZone })` finds
+the span a value falls in as the list counts it, and `dayIn` and `dayStarts`
+a day in a time zone; `createMemoryDataSource` does it all. See
+[lists that add up](https://fieldia.dev/lists/#totals).
+
+## Time zones and booking slots
+
+A page may name the time zone its dates and times are in, by its IANA name —
+a branch's, a clinic's — and a date and time field may name its own:
+
+```json
+{ "timeZone": "Europe/Berlin", "fields": { "flight": { "type": "datetime", "label": "Departs", "timeZone": "Africa/Cairo" } } }
+```
+
+A date and time is still kept as an instant, as before (`2026-10-15T12:30:00.000Z`;
+one written with its offset is read the same). It is shown and typed on the
+zone's clock wherever the person is, with the zone's short name beside it where
+the browser's zone is another ("14:30 CEST"). Today is the zone's day: a date's
+default `"today"`, its earliest and latest counted from today, `today()`, a
+rule's past and future, and `form.today()`. A time the clocks skip, or repeat, on
+a change day is said, never moved. `zonedPage(page)` writes the page's zone into
+each date and time field that names none, as the form and the viewer read it;
+`wallTime`, `instantsAt`, `dayIn` and `clocksSkip` are the clock arithmetic
+they use. `checkPage` and `validatePage` refuse a zone the browser does not know.
+Without `timeZone`, the browser's own zone, as before.
+
+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
+`length` and the minutes `between` two as the page says, the record and its
+values. It answers each day's state — `open`, `full`, `closed`, `holiday` with a
+`note` — and the times free, as instants, and may say the booking's `length`.
+`form.findSlots(field, { from, to })` asks it for a widget of your own;
+`form.canFindSlots()` says whether the source can. Without `slots`, the field is
+the plain date and time box. For demos and tests, `scheduleSlots(schedules)`
+answers from booking schedules — hours by the day of the week on a zone's clock,
+a booking's length, the minutes kept free after one, holidays, and the records
+the bookings are:
+
+```ts
+import { createMemoryDataSource, scheduleSlots } from '@fieldia/core';
+
+const weekday: [string, string][] = [['09:00', '13:00'], ['14:00', '18:00']];
+const dataSource = createMemoryDataSource({
+  records,
+  slots: scheduleSlots({
+    showroom: {
+      timeZone: 'Europe/Berlin',
+      hours: { 1: weekday, 2: weekday, 3: weekday, 4: weekday, 5: weekday, 6: [['10:00', '14:00']] },
+      length: 45,
+      between: 15,
+      holidays: { '2026-12-25': 'Christmas Day' },
+      bookings: { model: 'drive.booking', field: 'start', endField: 'stop', same: ['car'] },
+    },
+  }),
+});
+```
+
+## 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
@@ -141,7 +299,8 @@ values. It asks only about the person's work at risk (`workAtRisk(state)`):
 each change of theirs the last finished save of the record did not send —
 typed while it was on its way, while the run that saved went on, or since
 (`state.unsent`, told against the record as that save left it; a value set by
-a step, a rule, a compute or your app is never theirs) — a file the store holds
+a step, a rule, a compute or your app is never theirs; text they left since
+that does not read, "12a", counts as "12" does) — a file the store holds
 that no save sent, files still on their way, and changes Reload set aside. Then
 it asks "Discard your changes?" through the host's `ask(message, { discard:
 true })`, or `confirm`; Cancel keeps the person where they are, and with
@@ -150,13 +309,62 @@ out behaves as it did in 0.20: a change not saved goes where a step leaves the
 record. `form.leaveNow()` says whether a way out can go at once. Call
 `form.leave()` before your app's own ways out — a route change, an unmount —
 and `unsavedWork(state)` (any change, file or change set aside) for a browser's
-`beforeunload`. What `can` does
+`beforeunload`, or let the viewer keep it (`warnOnLeave`). A save refused for a
+conflict, waiting for Reload or Keep mine, is at risk too: the person asked for
+it to be saved. Discard lets the changes no save took go back to the record as
+the last save left it. Every answer that comes late — an onchange, a step's
+Archive, Duplicate or Delete, Keep mine's read, a name a box looks up — is laid
+only on the record it was asked for: anything of your own that waits and then
+writes on the form asks `form.recordShown()` first (taken as it asks, true
+while that record is still shown, as it was). What `can` does
 not allow is kept to before any source is asked: fields locked or hidden (and
 left out of what a save sends), a save refused with the source's `reason`, the
 gear menu's Archive, Duplicate and Delete and the buttons whose steps would do
 them hidden. `createMemoryDataSource({ versions: { by: 'Sara' }, can })` does
 it all in memory, and `changeElsewhere` changes a record as someone else would.
 
+## Many records at once
+
+A list's "Select all 1,284 that match", its Export and its Edit of many
+records read three optional members. `list({ …, allIds: true })` answers with
+`allIds`, every matching id in the list's order (fewer than `total` means the
+source stopped short, and the list says so). `writeMany({ model, ids, values,
+fields, versions })` writes one value in a field of each record and answers
+`{ failed: [{ id, message, problem? }] }`; without it the list saves each record
+in turn (`save` with `partial: true` and the version it was listed at).
+`exportRecords(request)` writes an export on the server: answer with the file
+(`{ name, data }`, data a Blob, bytes or text, or `{ name, url }`), with
+`{ message }` when it is handed over another way, or with `false` to let the
+browser write it. A page offers Edit with its list's `bulkEdit` (`true`, or the
+fields), and Export with `"export": true` — each off unless asked; `bulkEditFields(page, list)`
+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.23.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",