@fieldia/core 0.28.0 → 0.30.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.7"`, `FORMAT_VERSION`; a page in 0.1, 0.2, 0.3, 0.4, 0.5 or 0.6 is read as it is).
+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).
 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
@@ -204,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
@@ -300,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';
@@ -317,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?,
@@ -333,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 —
@@ -577,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
@@ -744,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.28.0",
+  "version": "0.30.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

@@ -11,7 +11,9 @@
         "0.4",
         "0.5",
         "0.6",
-        "0.7"
+        "0.7",
+        "0.8",
+        "0.9"
       ]
     },
     "id": {
@@ -389,6 +391,12 @@
     },
     "continueLater": {
       "type": "boolean"
+    },
+    "approval": {
+      "$ref": "#/$defs/PageApproval"
+    },
+    "suggest": {
+      "$ref": "#/$defs/PageSuggest"
     }
   },
   "required": [
@@ -452,13 +460,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",
@@ -501,13 +532,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",
@@ -545,13 +599,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",
@@ -1684,6 +1761,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": {
@@ -2014,13 +2102,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",
@@ -2063,13 +2174,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",
@@ -2659,6 +2793,12 @@
             "patternHint": {
               "type": "string",
               "minLength": 1
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -2708,6 +2848,12 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -2752,6 +2898,12 @@
               "items": {
                 "$ref": "#/$defs/SetWhen"
               }
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -3859,6 +4011,12 @@
             "patternHint": {
               "type": "string",
               "minLength": 1
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -3908,6 +4066,12 @@
               "type": "integer",
               "exclusiveMinimum": 0,
               "maximum": 9007199254740991
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -3952,6 +4116,12 @@
               "items": {
                 "$ref": "#/$defs/SetWhen"
               }
+            },
+            "translate": {
+              "not": {}
+            },
+            "requiredIn": {
+              "not": {}
             }
           },
           "required": [
@@ -7249,6 +7419,10 @@
           "type": "string",
           "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*$"
         },
+        "type": {
+          "type": "string",
+          "const": "divider"
+        },
         "label": {
           "type": "string"
         },
@@ -7300,6 +7474,17 @@
         },
         "roles": {
           "$ref": "#/$defs/Roles"
+        },
+        "menu": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/MenuItem"
+          }
+        },
+        "menuFrom": {
+          "type": "string",
+          "minLength": 1
         }
       },
       "required": [
@@ -9541,6 +9726,9 @@
         "filterSheet": {
           "type": "boolean"
         },
+        "searchToFilter": {
+          "type": "boolean"
+        },
         "parentField": {
           "type": "string",
           "pattern": "^[A-Za-z_][A-Za-z0-9_]*$"
@@ -9723,6 +9911,16 @@
             ],
             "additionalProperties": false
           }
+        },
+        "editable": {
+          "anyOf": [
+            {
+              "type": "boolean"
+            },
+            {
+              "$ref": "#/$defs/ListEditable"
+            }
+          ]
         }
       },
       "required": [
@@ -10025,6 +10223,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": {
@@ -10242,6 +10460,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
     }
   }
 }

package/src/index.d.mts

@@ -1,11 +1,14 @@
 export * from './runtime.mjs';
 export { takingWords, whenWords } from './lib/record/form-limits.mjs';
 export { isQuestion } from './lib/record/record-words.mjs';
+export { checkTranslated, languageName, languagesAtFault, textIn, textOf } from './lib/record/languages-part.mjs';
 export { dayWords } from './lib/record/day-words.mjs';
 export { scheduleSlots, type MemorySchedule } from './lib/record/memory-schedules.mjs';
 export { alikeRecords, nameLikeness } from './lib/record/memory-duplicates.mjs';
-export { FieldSchema, FieldsSchema, LineFieldSchema, LinkedFieldSchema, LineKindsSchema, OptionSchema, PropertyDefinitionSchema, FilterConditionSchema, FilterItemSchema, MoneyLookSchema, ShrinkSchema, PERIODS, TimeZoneSchema, } from './lib/format/field.mjs';
-export { ModifierSchema, RolesSchema, CellRulesSchema, ToneWhenSchema, LayoutNodeSchema, RootLayoutSchema, ListNodeSchema, ListCellSchema, ListCalendarSchema, ListCardSchema, ListGallerySchema, FilterRangeSchema, FilterPeriodSchema, RelatedNodeSchema } from './lib/format/layout.mjs';
+export { assistStandIn, polishText, readSignature, standInNumber, type StandInFound, type StandInOptions } from './lib/record/memory-assist.mjs';
+export { gridClusters } from './lib/record/memory-clusters.mjs';
+export { FieldSchema, FieldsSchema, LanguageTagSchema, LineFieldSchema, LinkedFieldSchema, LineKindsSchema, OptionSchema, PropertyDefinitionSchema, FilterConditionSchema, FilterItemSchema, MoneyLookSchema, ShrinkSchema, PERIODS, TimeZoneSchema, } from './lib/format/field.mjs';
+export { ModifierSchema, RolesSchema, CellRulesSchema, ToneWhenSchema, LayoutNodeSchema, RootLayoutSchema, ListNodeSchema, ListCellSchema, ListCalendarSchema, ListCardSchema, ListGallerySchema, ListEditableSchema, FilterRangeSchema, FilterPeriodSchema, RelatedNodeSchema } from './lib/format/layout.mjs';
 export { PageSchema } from './lib/format/page.mjs';
 export { ActionStepSchema, PageEventsSchema } from './lib/format/actions.mjs';
 export { pageWarnings, validatePage } from './lib/format/validate.mjs';
@@ -16,10 +19,13 @@ export { PathPickerOptionsSchema, StateDotOptionsSchema } from './lib/format/pic
 export { PagePhoneSchema, PhoneOptionsSchema } from './lib/format/phone.mjs';
 export { SlotsOptionsSchema } from './lib/format/slots-options.mjs';
 export { SignatureOptionsSchema } from './lib/format/signature-options.mjs';
+export { PhotosOptionsSchema } from './lib/format/photos-options.mjs';
+export { SCAN_FORMATS, ScanFillSchema, ScanOptionSchema, ScanSettingsSchema } from './lib/format/scan-options.mjs';
 export { PageDuplicatesSchema } from './lib/format/duplicates.mjs';
 export { PageRecordsSchema } from './lib/format/records.mjs';
 export { PageEndingSchema } from './lib/format/endings.mjs';
 export { PageLimitsSchema } from './lib/format/limits.mjs';
+export { PageApprovalSchema } from './lib/format/approval.mjs';
 export { DUPLICATE_KINDS, comparable } from './lib/format/duplicate-kinds.mjs';
 export { pageJsonSchema } from './lib/format/json-schema.mjs';
 export { AUTOFILL, AUTOFILL_CONTACT, AUTOFILL_NAMES, autofillProblem, autofillPurpose } from './lib/format/autofill.mjs';