@fieldia/core 0.27.0 → 0.29.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.6"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3, 0.4 or 0.5 is read as it is).
+A page says which format it is written in (`"fieldia": "0.8"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3, 0.4, 0.5, 0.6 or 0.7 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,15 @@ 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.
 
+It waits the same for an answer the form refuses: one shown that holds a value
+its checks do not take — an area of −50 under its `min` of 0, a day past its
+`max` of `today`, a pattern not met, an answer rule's error — on the record or
+in a line's cell, whether the value is the page's own formula, one of
+Fieldia's functions (`years(built_on, today())`) or your app's: "Fix Area (m²)
+to see Price per m²", never −120,000.00. An empty answer is none, required or
+not, and one no one is shown is never refused. What waits for an answer is told
+before what is asked of your app's server for it.
+
 ## Functions, and your app's own
 
 A value worked out (`compute`), a value set by a condition (`setWhen`) and every
@@ -177,8 +186,11 @@ app's list gave, or those picked where they are carried from (`picked: false`: t
 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
+offered, so it was taken out"), while it is true: it goes once the value is written
+again, or once what it names is offered again (Villa picked again, the treatment
+ticked again above, the list asked again offering it); one of several offered again
+leaves it naming the rest. 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.
@@ -192,6 +204,33 @@ carries no options from a question: its own, or one of the app's lists — the s
 `optionsFrom` as a page's own choice (`{ list, dependsOn }`, its `dependsOn` naming
 the line's columns or `parent.` and a field).
 
+## One text in several languages
+
+A line, a paragraph or formatted text may keep its text in several languages, each
+typed by a person — Fieldia never translates it (`translate`), and `requiredIn` says
+which a required answer is typed in (every one when left out):
+
+```json
+"title": { "type": "char", "label": "Title", "translate": ["ar", "en"], "required": true, "size": 80 },
+"description": { "type": "text", "label": "Description", "translate": ["ar", "en"], "required": true, "requiredIn": ["en"] }
+```
+
+Its value is an object of each language's text by its tag — `{ "ar": "شقة…", "en":
+"Nile-view flat" }` — a language not typed yet left out, none typed `null`; a plain
+text loaded for it is read as its first language's. The form checks it in each
+language: "Title is required in Arabic" while it is typed in some (`languagesNeeded`,
+or `languagesNeededQuestion` for a label that asks), "Title is required" in none;
+each language held to the field's `size` and `pattern`, named in the problem ("Title
+(English) is 4 characters too long: shorten it to 80"). `textIn(value, reader,
+languages)` reads it as a reader of a language does — theirs where typed, else the
+field's first typed, said to be another's — `languageName(tag, locale)` names a
+language, `checkTranslated` and `languagesAtFault` check it. They come in the
+languages part (`formLanguagesPart`), which a form with such a field asks for as it
+is made and a save waits for; `languagesOf(field)` and `hasLanguages(page)` say
+whether a page has one. A table's line keeps one language. The memory source finds
+such a text by a search in any of its languages, and reads one text — a link's
+name, a list's order — in its `language` option's.
+
 ## A public form's bot check
 
 A page of responses anyone may send — a sign-up, a contact form — can check that
@@ -258,7 +297,10 @@ form.endingWords('Your booking is {id}.');   // "Your booking is B-1043."
 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
+the field so ("Please answer “How was your visit to Zamalek?”": a label that is
+a question — ending with a question mark, or an ellipsis the answer completes —
+is quoted in the language's marks wherever a sentence names it, `isQuestion` and
+`quotedLabel`, and its required message is `requiredQuestion`). 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,
@@ -285,6 +327,10 @@ record (`model` and `recordId` are the record's, `field` is where it sits:
 `consent.deed`), and the record's save waits for them. A file picked while a save
 is on its way stays a change, to save next. A draft never keeps a file's bytes
 where the source has `upload`; without it, a draft keeps them, as before.
+The sending itself — each file made ready and sent, its link put in its field —
+is a part of its own (`formUploadsPart`), which comes with @fieldia/widgets'
+files part, or the first time a form sends a file: `form.upload` gives its ids
+at once, each file waiting its turn until the part is in.
 
 ```ts
 import { uploadTo } from '@fieldia/core';
@@ -302,6 +348,16 @@ 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).
 
+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
+the order a person put them (the first the cover), a photo's `caption`, and for a
+photo cropped or turned the photo as it was (`original`, a file value of its
+own) and what was done to it (`edit`: `{ turn: 90, crop: { x, y, width, height }
+}`, fractions of the turned original). A photo cropped is stored at once —
+`form.upload(field, [file], { replaces })`: its link takes the place of the
+bytes the field holds for it, with whatever stands beside them by then (a
+caption typed meanwhile).
+
 ## Lists that add up, and filter by time
 
 A list asks its source's optional `totals({ model, filter, totals, groupBy?,
@@ -318,6 +374,20 @@ 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).
 
+## A map's records counted where they crowd
+
+A list's map (@fieldia/map) asks its source's optional `clusters({ model,
+filter, field, longitude?, bbox, zoom, radius, fields, weight?, signal })` for
+the view's bubbles — `{ clusters: [{ lat, lng, count, bbox?, weight? }],
+points?: [{ id, values }], unplaced? }` — instead of loading at most 500 records
+and gathering them itself: every record a search finds, however many, a record
+standing alone with its values for its pin and its card. Answer `false` to let
+the map load the search's records, as it does without the member. The memory
+source has it where its `clusters` option says how it answers:
+`createMemoryDataSource({ records, clusters: gridClusters({ models: ['home'] }) })`
+gathers its records by a grid of squares fixed to the world, as a server does.
+See [lists on a map](https://fieldia.dev/lists/#map).
+
 ## Time zones and booking slots
 
 A page may name the time zone its dates and times are in, by its IANA name —
@@ -527,7 +597,11 @@ 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,
+messages)` says why it takes none ("This form closed on 20 Nov 2026."). Every
+message that names a day writes it as the page's date boxes do — its
+`look.dateOrder` (the form puts it on its messages, `messages.dateOrder`), its
+language, a time on its clock: "can’t be after 20 Oct 2026", "Oct 20, 2026"
+month first; `dayWords(day, messages, order?)` is that rule (a time after it: `whenWords`). 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
@@ -558,6 +632,60 @@ const form = createForm({ page, dataSource, resume: new URLSearchParams(location
 form.on('draft', ({ key, later, saved }) => later && console.log('Continue from', saved.link));
 ```
 
+## Approvals on a record
+
+A record's page may say its records wait for approval:
+
+```json
+{ "approval": { "open": ["notes"] } }
+```
+
+The data source tells where a record stands, `approvals({ model, recordId,
+user })` answering `{ levels, history, mine, together, why }` — each level its
+`id`, `name`, `approvers` (each `{ id, name, decision, at }` in the round asked
+now), `needs` (`any`, the default, or `all`) and `state` (`waiting`, `later`,
+`approved`, `rejected`, `skipped`); `history` oldest first (`{ decision:
+'requested' | 'approved' | 'rejected', level, by, at, reason }`); `mine` the
+levels this person may decide now — and takes the decisions, `decide({ model,
+recordId, level, decision, reason, user })`, a rejection always with why. Who is
+asked, and in what order, is the app's, or its approval engine's: Fieldia never
+works it out. The form asks as a saved record is shown, after each save and each
+decision, keeping what it told in `state.approval` (`status`: `none`, `needed`,
+`waiting`, `approved`, `rejected`); an answer for a record no longer shown is
+laid on none. While it waits, every field is read-only but those `open` names
+(`form.node(id).readonly`, `form.fieldReadonly`), `form.approvalLock(name)`
+saying why; `"lock": false` locks none. `form.decide(level, decision, reason?)`
+reads and saves what is typed first, then decides, then loads the record again;
+it refuses a level not this person's and a rejection with no reason, in words.
+The memory source's `approvals` option routes records as an engine would (in
+turn or together, any or all, a rejection ending the round), keeping each
+decision; `approvalHistory` is what it starts from.
+
+```ts
+await form.decide('finance', 'rejected', 'Over the quarter’s budget');
+form.getState().approval?.status; // 'rejected'
+```
+
+## AI help: values proposed, words written, a search read
+
+Three optional members answer with the app's own model — Fieldia ships no model
+and no keys. `suggest({ page, values, fields, from: { text?, files? } })` gives
+values for a form (a page's `suggest`: `fields`, `label`, `from`, `fromField`),
+a table's lines to add among them; `rewrite({ field, how, text, values })` a
+text field's words (its node's `options.rewrite`: `"draft"`, `"polish"`, or
+`{ "how", "label" }`); `searchToFilter({ text, fields })` a list's conditions
+(its `searchToFilter`). The viewer shows each value on its field to accept or
+reject first, and Undo after; `checkPage` and `validatePage` check the settings.
+The memory source has each member only where its `assist` option answers it;
+`assistStandIn({ drafts })` is a stand-in for demos and tests — no model, words
+read by their patterns, every answer saying so ("Stand-in AI, no model: …"):
+
+```ts
+import { assistStandIn, createMemoryDataSource } from '@fieldia/core';
+
+const dataSource = createMemoryDataSource({ records, assist: assistStandIn({ drafts: { 'enquiry.reply': (values) => `Dear ${values.partner_name},` } }) });
+```
+
 ## What a page's records are called
 
 A page may say what its records are, so Fieldia's own sentences name them as
@@ -725,6 +853,21 @@ 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 record found by a code a scanner read
+
+A link scanned into with the camera (`options.scan` on a many2one or a table's
+link column, drawn by @fieldia/widgets' scan part) finds the record a code names
+through the data source's `search`, with no member of its own:
+`form.search(field, code, 2, { field: 'barcode' })` asks for the records whose
+`barcode` holds the code exactly — the field's own filter kept, the condition
+added to it, the query empty — and `form.searchLine(…)` the same for a line's
+link. Without a field named, the code is searched as a name, the exact name
+first. The page check holds `options.scan` to a kind a code is written into —
+a char, a text, a many2one, or a one2many counted by a column (`field`) and a
+number (`count`) — and the fields a GS1 code fills (`fills`) to fields of the
+page, or of the line, that take a code's part; `ScanOptionSchema`
+gives its shape. See [scanning a code](https://fieldia.dev/fields/#scan).
+
 ## 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.27.0",
+  "version": "0.29.0",
   "description": "Headless form model for Fieldia: the page format, modifiers, validation and record state. No DOM.",
   "license": "MIT",
   "homepage": "https://fieldia.dev",

package/schema/page.schema.json

@@ -10,7 +10,9 @@
         "0.3",
         "0.4",
         "0.5",
-        "0.6"
+        "0.6",
+        "0.7",
+        "0.8"
       ]
     },
     "id": {
@@ -388,6 +390,12 @@
     },
     "continueLater": {
       "type": "boolean"
+    },
+    "approval": {
+      "$ref": "#/$defs/PageApproval"
+    },
+    "suggest": {
+      "$ref": "#/$defs/PageSuggest"
     }
   },
   "required": [
@@ -451,13 +459,36 @@
             "patternHint": {
               "type": "string",
               "minLength": 1
+            },
+            "translate": {
+              "minItems": 2,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
+            },
+            "requiredIn": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
             }
           },
           "required": [
             "type",
             "label"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "dependentSchemas": {
+            "requiredIn": {
+              "required": [
+                "translate"
+              ]
+            }
+          }
         },
         {
           "type": "object",
@@ -500,13 +531,36 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "translate": {
+              "minItems": 2,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
+            },
+            "requiredIn": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
             }
           },
           "required": [
             "type",
             "label"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "dependentSchemas": {
+            "requiredIn": {
+              "required": [
+                "translate"
+              ]
+            }
+          }
         },
         {
           "type": "object",
@@ -544,13 +598,36 @@
               "items": {
                 "$ref": "#/$defs/SetWhen"
               }
+            },
+            "translate": {
+              "minItems": 2,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
+            },
+            "requiredIn": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
             }
           },
           "required": [
             "type",
             "label"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "dependentSchemas": {
+            "requiredIn": {
+              "required": [
+                "translate"
+              ]
+            }
+          }
         },
         {
           "type": "object",
@@ -1683,6 +1760,17 @@
         }
       ]
     },
+    "LanguageTag": {
+      "type": "string",
+      "pattern": "^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$",
+      "description": "A language by its BCP 47 tag.",
+      "examples": [
+        "ar",
+        "en",
+        "fr",
+        "pt-BR"
+      ]
+    },
     "MoneyLook": {
       "type": "object",
       "properties": {
@@ -2013,13 +2101,36 @@
             "patternHint": {
               "type": "string",
               "minLength": 1
+            },
+            "translate": {
+              "minItems": 2,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
+            },
+            "requiredIn": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
             }
           },
           "required": [
             "type",
             "label"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "dependentSchemas": {
+            "requiredIn": {
+              "required": [
+                "translate"
+              ]
+            }
+          }
         },
         {
           "type": "object",
@@ -2062,13 +2173,36 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "translate": {
+              "minItems": 2,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
+            },
+            "requiredIn": {
+              "minItems": 1,
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/LanguageTag"
+              },
+              "uniqueItems": true
             }
           },
           "required": [
             "type",
             "label"
           ],
-          "additionalProperties": false
+          "additionalProperties": false,
+          "dependentSchemas": {
+            "requiredIn": {
+              "required": [
+                "translate"
+              ]
+            }
+          }
         },
         {
           "type": "object",
@@ -2658,6 +2792,12 @@
             "patternHint": {
               "type": "string",
               "minLength": 1
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -2707,6 +2847,12 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -2751,6 +2897,12 @@
               "items": {
                 "$ref": "#/$defs/SetWhen"
               }
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -3858,6 +4010,12 @@
             "patternHint": {
               "type": "string",
               "minLength": 1
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -3907,6 +4065,12 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -3951,6 +4115,12 @@
               "items": {
                 "$ref": "#/$defs/SetWhen"
               }
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -6368,7 +6538,8 @@
           "type": "string",
           "enum": [
             "narrow",
-            "always"
+            "always",
+            "never"
           ]
         },
         "fit": {
@@ -9539,6 +9710,9 @@
         "filterSheet": {
           "type": "boolean"
         },
+        "searchToFilter": {
+          "type": "boolean"
+        },
         "parentField": {
           "type": "string",
           "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
@@ -9721,6 +9895,16 @@
             ],
             "additionalProperties": false
           }
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/ListEditable"
+            }
+          ]
         }
       },
       "required": [
@@ -10023,6 +10207,26 @@
       },
       "additionalProperties": false
     },
+    "ListEditable": {
+      "type": "object",
+      "properties": {
+        "fields": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
+          }
+        },
+        "add": {
+          "type": "boolean"
+        },
+        "open": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
     "PageEvents": {
       "type": "object",
       "properties": {
@@ -10240,6 +10444,61 @@
         }
       },
       "additionalProperties": false
+    },
+    "PageApproval": {
+      "type": "object",
+      "properties": {
+        "open": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "lock": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
+    },
+    "PageSuggest": {
+      "type": "object",
+      "properties": {
+        "fields": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "from": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": [
+              "text",
+              "files"
+            ]
+          }
+        },
+        "label": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 60
+        },
+        "placeholder": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 200
+        },
+        "fromField": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
     }
   }
 }