@fieldia/core 0.21.0 → 0.23.0

package/src/lib/format/validate.js.map

@@ -1 +1 @@
-{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/validate.ts"],"names":[],"mappings":";;AAeA,oCAQC;AAtBD,iCAA+C;AAC/C,6CAAmE;AAInE;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,MAAM,MAAM,GAAG,iBAAU,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACjI,CAAC;IACD,MAAM,IAAI,GAAS,MAAM,CAAC,IAAI,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,2BAAc,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,UAAU,CAAC,IAA4B;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;SACvH,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,KAAuB;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,eAAe,IAAI,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACtF,OAAO,IAAI,KAAK,CAAC,aAAa,wCAAwC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC"}
+{"version":3,"file":"validate.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/validate.ts"],"names":[],"mappings":";;AAiBA,oCAQC;AAxBD,iCAA+C;AAC/C,uCAAwC;AACxC,6CAAmE;AAInE;;;;;;;;;GASG;AACH,SAAgB,YAAY,CAAC,KAAc;IACzC,MAAM,MAAM,GAAG,iBAAU,CAAC,SAAS,CAAC,IAAA,qBAAW,EAAC,KAAK,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACjI,CAAC;IACD,MAAM,IAAI,GAAS,MAAM,CAAC,IAAI,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,2BAAc,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,UAAU,CAAC,IAA4B;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;SACvH,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,KAAuB;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,eAAe,IAAI,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACtF,OAAO,IAAI,KAAK,CAAC,aAAa,wCAAwC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC"}

package/src/lib/format/validate.mjs

@@ -1,4 +1,5 @@
 import { PageSchema } from './page.mjs';
+import { upgradePage } from './upgrade.mjs';
 import { ReferenceCheck } from './references.mjs';
 /**
  * Check a page in two passes: its shape against the format, then every
@@ -7,10 +8,11 @@ import { ReferenceCheck } from './references.mjs';
  * readable and reading only fields of this page.
  *
  * Returns the page as validated. Nothing is coerced or filled in: a page that
- * passes is returned equal to the input.
+ * passes is returned equal to the input — one in an older format, brought up to
+ * date first (`upgradePage`), as every reader of it does.
  */
 export function validatePage(input) {
-    const parsed = PageSchema.safeParse(input);
+    const parsed = PageSchema.safeParse(upgradePage(input));
     if (!parsed.success) {
         return { ok: false, issues: parsed.error.issues.map((issue) => ({ path: formatPath(issue.path), message: describe(issue) })) };
     }

package/src/lib/format/validate.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"validate.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAa,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAuB,MAAM,cAAc,CAAC;AAInE;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACjI,CAAC;IACD,MAAM,IAAI,GAAS,MAAM,CAAC,IAAI,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,UAAU,CAAC,IAA4B;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;SACvH,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,KAAuB;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,eAAe,IAAI,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACtF,OAAO,IAAI,KAAK,CAAC,aAAa,wCAAwC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC"}
+{"version":3,"file":"validate.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/validate.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAa,MAAM,QAAQ,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,cAAc,EAAuB,MAAM,cAAc,CAAC;AAInE;;;;;;;;;GASG;AACH,MAAM,UAAU,YAAY,CAAC,KAAc;IACzC,MAAM,MAAM,GAAG,UAAU,CAAC,SAAS,CAAC,WAAW,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;IACjI,CAAC;IACD,MAAM,IAAI,GAAS,MAAM,CAAC,IAAI,CAAC;IAC/B,MAAM,MAAM,GAAG,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,CAAC;IAC9C,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AACpE,CAAC;AAED,SAAS,UAAU,CAAC,IAA4B;IAC9C,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,QAAQ,CAAC;IACvC,OAAO,IAAI;SACR,GAAG,CAAC,CAAC,OAAO,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;SACvH,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,SAAS,QAAQ,CAAC,KAAuB;IACvC,IAAI,KAAK,CAAC,IAAI,KAAK,eAAe,IAAI,eAAe,IAAI,KAAK,IAAI,KAAK,CAAC,aAAa,EAAE,CAAC;QACtF,OAAO,IAAI,KAAK,CAAC,aAAa,wCAAwC,CAAC;IACzE,CAAC;IACD,OAAO,KAAK,CAAC,OAAO,CAAC;AACvB,CAAC"}

package/src/lib/format/version.d.mts

@@ -1,2 +1,17 @@
 /** The page format version this build reads and writes. */
-export declare const FORMAT_VERSION: "0.1";
+export declare const FORMAT_VERSION: "0.2";
+/**
+ * Every format Fieldia has had, oldest first; the last is FORMAT_VERSION. A page in an older one is brought up to date
+ * by `upgradePage`, step by step (`PAGE_UPGRADES`), wherever it is read: `checkPage`, `validatePage`, the viewer, the
+ * designer. A release that changes what a page may say adds its version here (see the format's docs, "Versions").
+ */
+export declare const FORMAT_VERSIONS: readonly ["0.1", "0.2"];
+/** A format Fieldia has had: a page may say any of them, and is read in the current one. */
+export type FormatVersion = (typeof FORMAT_VERSIONS)[number];
+/** Which of two format versions is newer: below 0 when `a` is older, 0 when they are the same, null when either is not a version. */
+export declare function compareFormats(a: unknown, b: unknown): number | null;
+/**
+ * What is wrong with a page's `fieldia`, in words, or null when it is the current format. A page newer than this
+ * build says to update Fieldia; an older one, that `upgradePage` brings it up to date (the checks do that themselves).
+ */
+export declare function formatProblem(version: unknown, versions?: readonly string[]): string | null;

package/src/lib/format/version.d.ts

@@ -1,2 +1,17 @@
 /** The page format version this build reads and writes. */
-export declare const FORMAT_VERSION: "0.1";
+export declare const FORMAT_VERSION: "0.2";
+/**
+ * Every format Fieldia has had, oldest first; the last is FORMAT_VERSION. A page in an older one is brought up to date
+ * by `upgradePage`, step by step (`PAGE_UPGRADES`), wherever it is read: `checkPage`, `validatePage`, the viewer, the
+ * designer. A release that changes what a page may say adds its version here (see the format's docs, "Versions").
+ */
+export declare const FORMAT_VERSIONS: readonly ["0.1", "0.2"];
+/** A format Fieldia has had: a page may say any of them, and is read in the current one. */
+export type FormatVersion = (typeof FORMAT_VERSIONS)[number];
+/** Which of two format versions is newer: below 0 when `a` is older, 0 when they are the same, null when either is not a version. */
+export declare function compareFormats(a: unknown, b: unknown): number | null;
+/**
+ * What is wrong with a page's `fieldia`, in words, or null when it is the current format. A page newer than this
+ * build says to update Fieldia; an older one, that `upgradePage` brings it up to date (the checks do that themselves).
+ */
+export declare function formatProblem(version: unknown, versions?: readonly string[]): string | null;

package/src/lib/format/version.js

@@ -1,6 +1,43 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FORMAT_VERSION = void 0;
+exports.FORMAT_VERSIONS = exports.FORMAT_VERSION = void 0;
+exports.compareFormats = compareFormats;
+exports.formatProblem = formatProblem;
 /** The page format version this build reads and writes. */
-exports.FORMAT_VERSION = '0.1';
+exports.FORMAT_VERSION = '0.2';
+/**
+ * Every format Fieldia has had, oldest first; the last is FORMAT_VERSION. A page in an older one is brought up to date
+ * by `upgradePage`, step by step (`PAGE_UPGRADES`), wherever it is read: `checkPage`, `validatePage`, the viewer, the
+ * designer. A release that changes what a page may say adds its version here (see the format's docs, "Versions").
+ */
+exports.FORMAT_VERSIONS = ['0.1', '0.2'];
+/** `major.minor` as two numbers, or null when it is not a version at all. */
+function parts(version) {
+    const match = typeof version === 'string' ? /^(\d+)\.(\d+)$/.exec(version) : null;
+    return match ? [Number(match[1]), Number(match[2])] : null;
+}
+/** Which of two format versions is newer: below 0 when `a` is older, 0 when they are the same, null when either is not a version. */
+function compareFormats(a, b) {
+    const [x, y] = [parts(a), parts(b)];
+    if (!x || !y)
+        return null;
+    return x[0] - y[0] || x[1] - y[1];
+}
+/**
+ * What is wrong with a page's `fieldia`, in words, or null when it is the current format. A page newer than this
+ * build says to update Fieldia; an older one, that `upgradePage` brings it up to date (the checks do that themselves).
+ */
+function formatProblem(version, versions = exports.FORMAT_VERSIONS) {
+    const current = versions[versions.length - 1];
+    if (version === current)
+        return null;
+    const compared = compareFormats(version, current);
+    if (compared === null)
+        return `"fieldia" says which format the page is written in: "${current}" for this Fieldia`;
+    if (compared > 0)
+        return `this page is in format ${version}, newer than this Fieldia reads (${current}): update Fieldia to show it`;
+    if (versions.includes(version))
+        return `this page is in format ${version}: upgradePage(page) brings it to ${current}`;
+    return `format ${version} is not one Fieldia has had: this Fieldia reads ${current}`;
+}
 //# sourceMappingURL=version.js.map

package/src/lib/format/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/version.ts"],"names":[],"mappings":";;;AAAA,2DAA2D;AAC9C,QAAA,cAAc,GAAG,KAAc,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/version.ts"],"names":[],"mappings":";;;AAoBA,wCAIC;AAMD,sCAQC;AAtCD,2DAA2D;AAC9C,QAAA,cAAc,GAAG,KAAc,CAAC;AAE7C;;;;GAIG;AACU,QAAA,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,CAAsC,CAAC;AAKnF,6EAA6E;AAC7E,SAAS,KAAK,CAAC,OAAgB;IAC7B,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,qIAAqI;AACrI,SAAgB,cAAc,CAAC,CAAU,EAAE,CAAU;IACnD,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,OAAgB,EAAE,WAA8B,uBAAe;IAC3F,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9C,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,wDAAwD,OAAO,oBAAoB,CAAC;IAClH,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,0BAA0B,OAAiB,oCAAoC,OAAO,8BAA8B,CAAC;IAC9I,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAiB,CAAC;QAAE,OAAO,0BAA0B,OAAiB,oCAAoC,OAAO,EAAE,CAAC;IAC1I,OAAO,UAAU,OAAiB,mDAAmD,OAAO,EAAE,CAAC;AACjG,CAAC"}

package/src/lib/format/version.mjs

@@ -1,3 +1,38 @@
 /** The page format version this build reads and writes. */
-export const FORMAT_VERSION = '0.1';
+export const FORMAT_VERSION = '0.2';
+/**
+ * Every format Fieldia has had, oldest first; the last is FORMAT_VERSION. A page in an older one is brought up to date
+ * by `upgradePage`, step by step (`PAGE_UPGRADES`), wherever it is read: `checkPage`, `validatePage`, the viewer, the
+ * designer. A release that changes what a page may say adds its version here (see the format's docs, "Versions").
+ */
+export const FORMAT_VERSIONS = ['0.1', '0.2'];
+/** `major.minor` as two numbers, or null when it is not a version at all. */
+function parts(version) {
+    const match = typeof version === 'string' ? /^(\d+)\.(\d+)$/.exec(version) : null;
+    return match ? [Number(match[1]), Number(match[2])] : null;
+}
+/** Which of two format versions is newer: below 0 when `a` is older, 0 when they are the same, null when either is not a version. */
+export function compareFormats(a, b) {
+    const [x, y] = [parts(a), parts(b)];
+    if (!x || !y)
+        return null;
+    return x[0] - y[0] || x[1] - y[1];
+}
+/**
+ * What is wrong with a page's `fieldia`, in words, or null when it is the current format. A page newer than this
+ * build says to update Fieldia; an older one, that `upgradePage` brings it up to date (the checks do that themselves).
+ */
+export function formatProblem(version, versions = FORMAT_VERSIONS) {
+    const current = versions[versions.length - 1];
+    if (version === current)
+        return null;
+    const compared = compareFormats(version, current);
+    if (compared === null)
+        return `"fieldia" says which format the page is written in: "${current}" for this Fieldia`;
+    if (compared > 0)
+        return `this page is in format ${version}, newer than this Fieldia reads (${current}): update Fieldia to show it`;
+    if (versions.includes(version))
+        return `this page is in format ${version}: upgradePage(page) brings it to ${current}`;
+    return `format ${version} is not one Fieldia has had: this Fieldia reads ${current}`;
+}
 //# sourceMappingURL=version.mjs.map

package/src/lib/format/version.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"version.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/version.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAG,KAAc,CAAC"}
+{"version":3,"file":"version.mjs","sourceRoot":"","sources":["../../../../../../libs/core/src/lib/format/version.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,MAAM,CAAC,MAAM,cAAc,GAAG,KAAc,CAAC;AAE7C;;;;GAIG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,KAAK,EAAE,KAAK,CAAsC,CAAC;AAKnF,6EAA6E;AAC7E,SAAS,KAAK,CAAC,OAAgB;IAC7B,MAAM,KAAK,GAAG,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAClF,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AAC7D,CAAC;AAED,qIAAqI;AACrI,MAAM,UAAU,cAAc,CAAC,CAAU,EAAE,CAAU;IACnD,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IACpC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1B,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,OAAgB,EAAE,WAA8B,eAAe;IAC3F,MAAM,OAAO,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9C,IAAI,OAAO,KAAK,OAAO;QAAE,OAAO,IAAI,CAAC;IACrC,MAAM,QAAQ,GAAG,cAAc,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAClD,IAAI,QAAQ,KAAK,IAAI;QAAE,OAAO,wDAAwD,OAAO,oBAAoB,CAAC;IAClH,IAAI,QAAQ,GAAG,CAAC;QAAE,OAAO,0BAA0B,OAAiB,oCAAoC,OAAO,8BAA8B,CAAC;IAC9I,IAAI,QAAQ,CAAC,QAAQ,CAAC,OAAiB,CAAC;QAAE,OAAO,0BAA0B,OAAiB,oCAAoC,OAAO,EAAE,CAAC;IAC1I,OAAO,UAAU,OAAiB,mDAAmD,OAAO,EAAE,CAAC;AACjG,CAAC"}

package/src/lib/record/data-source.d.mts

@@ -8,9 +8,18 @@ import type { RunStop } from './run.mjs';
  * and every method is optional so a page uses only what it needs.
  */
 export interface DataSource {
-    /** Read a record. Needed to edit an existing record. */
-    load?(request: LoadRequest): Promise<Values>;
-    /** Create (`id: null`) or update a record. Needed to save a record page. */
+    /**
+     * Read a record. Needed to edit an existing record. Its values, or
+     * `loadedRecord(values, { version, can })` to tell also its version — so a
+     * save can tell that someone else changed it since — and what this person
+     * may do with it. `loadedRecordOf` reads either the same way.
+     */
+    load?(request: LoadRequest): Promise<Values | LoadedRecord>;
+    /**
+     * Create (`id: null`) or update a record. Needed to save a record page. A
+     * source that keeps versions compares `request.version` with the record's
+     * and throws a `ConflictError` when someone else saved it since.
+     */
     save?(request: SaveRequest): Promise<SaveResult>;
     /** Recalculate after a value changes, the way a backend's onchange does. */
     onchange?(request: OnchangeRequest): Promise<OnchangeResult>;
@@ -20,7 +29,7 @@ export interface DataSource {
     create?(request: CreateRequest): Promise<RelatedRecord>;
     /** Store one response to a `responses` page, such as a survey. */
     submit?(request: SubmitRequest): Promise<SubmitResult>;
-    /** Records for a list: filtered, sorted and one page of them, with how many there are in all. */
+    /** Records for a list: filtered, sorted and one page of them, with how many there are in all; with `allIds`, the ids of every one that matches. */
     list?(request: ListRequest): Promise<ListResult>;
     /** How many records fall under each value of a field, for a list's Group By. */
     groups?(request: GroupRequest): Promise<Group[]>;
@@ -43,7 +52,76 @@ export interface DataSource {
      * preview: each a file with its `url` (or its `data`) and its media type.
      */
     attachments?(request: RecordRequest): Promise<FileValue[]>;
+    /**
+     * Totals over the records a search finds — each field's sum, average,
+     * least, most or count — over them all and, with `groupBy`, under each
+     * value of a field: the row under a list and the sums on its Group By
+     * headings. Without it, a list shows no totals.
+     */
+    totals?(request: TotalsRequest): Promise<TotalsResult>;
+    /**
+     * Store one file where the app keeps files, as soon as it is picked, for a
+     * file or picture field: the record then keeps only its link. Without it,
+     * a file travels inside the record as base64, as it always has. To fail,
+     * throw: the field offers Retry, except after `saveRefused({ kind: 'rule',
+     * message })`, which says the store refuses this file (its kind, its
+     * size) and is shown as it is.
+     */
+    upload?(file: UploadFile, request: UploadRequest): Promise<UploadedFile>;
+}
+/**
+ * Which state of a record a page opened, as its source keeps it: an etag, a
+ * write date, a revision number — Fieldia only hands `token` back — with who
+ * changed the record last and when, for the words a conflict shows ("Mona
+ * changed this at 10:42").
+ */
+export interface RecordVersion {
+    token: string;
+    /** Who changed it last, by the name people know them by. */
+    by?: string;
+    /** When, as an ISO date and time: `2026-10-13T10:42:00Z`. */
+    at?: string;
+}
+/**
+ * What this person may do with one record. Each is allowed unless it says
+ * `false`, so a source that tells nothing keeps today's behaviour. The page
+ * hides what is not allowed — never shows it disabled — and says why.
+ */
+export interface RecordPermissions {
+    /** False: the form is read-only for this person, and Save is hidden. */
+    edit?: boolean;
+    /** False: Delete is hidden, and the `delete` step's buttons. */
+    delete?: boolean;
+    /** False: Archive and Unarchive are hidden, and those steps' buttons. */
+    archive?: boolean;
+    /** False: Duplicate is hidden, and the `duplicate` step's buttons. */
+    duplicate?: boolean;
+    /** Fields this person may see but not change on this record, by name. */
+    readonlyFields?: string[];
+    /** Fields this person may not see on this record, by name: hidden, and the source leaves their values out. */
+    hiddenFields?: string[];
+    /** Why not everything is allowed, in the person's language, for the page to say: "Only Mona, the lead's agent, can change it." */
+    reason?: string;
 }
+/**
+ * A record as `load` gives it to tell more than its values. A field cannot
+ * be named `$loaded`, so the mark keeps it apart from bare values.
+ */
+export interface LoadedRecord {
+    $loaded: true;
+    values: Values;
+    /** The version it was read at: each save carries it back. */
+    version?: RecordVersion;
+    /** What this person may do with it. */
+    can?: RecordPermissions;
+}
+/** What `load` returns to tell a record's version, or what this person may do with it, beside its values. */
+export declare function loadedRecord(values: Values, more?: {
+    version?: RecordVersion;
+    can?: RecordPermissions;
+}): LoadedRecord;
+/** What a load gave, in one shape: bare values, as every source gave them before, are a record with nothing more to tell. */
+export declare function loadedRecordOf(loaded: Values | LoadedRecord): LoadedRecord;
 /** One stored record, by its model and id. */
 export interface RecordRequest {
     model: string;
@@ -83,11 +161,31 @@ export interface SaveRequest {
     changes: RecordChanges;
     /** Every value, for sources that save whole records. */
     values: Values;
+    /**
+     * True when the save carries some of the record's fields, not all of it:
+     * `values` then holds the fields in `changes` alone and `fields` names
+     * them alone — a save from outside a form, which never had the rest, as a
+     * calendar's move and its Undo. A source that saves whole records writes
+     * these over the record as stored and keeps every other field.
+     */
+    partial?: boolean;
+    /**
+     * The version the record was opened at — from its load, or from the last
+     * save — for a source that refuses a save over someone else's. None for a
+     * new record, nor from a source that tells no versions. "Keep mine" after
+     * a conflict saves again with the conflict's `version`: these changes over
+     * the record as it is now.
+     */
+    version?: RecordVersion;
 }
 export interface SaveResult {
     id: RecordId;
     /** The record as stored, when the source recalculated anything. */
     values?: Values;
+    /** Its version now, for the next save to carry. */
+    version?: RecordVersion;
+    /** What the person may do with it now, when the save changed that (a stage that locks it). */
+    can?: RecordPermissions;
 }
 export interface OnchangeRequest {
     model: string;
@@ -137,14 +235,28 @@ export interface ListRequest {
     sort: SortOrder[];
     offset: number;
     limit: number;
+    /**
+     * Give also the id of every record that matches, in this order, in
+     * `ListResult.allIds`: for "Select all 1,284 that match", export and bulk
+     * edit. A source that leaves it out is paged through instead.
+     */
+    allIds?: boolean;
 }
 export interface ListResult {
-    records: {
-        id: RecordId;
-        values: Values;
-    }[];
+    records: ListedRecord[];
     /** How many records match in all, for the pager. */
     total: number;
+    /** With `allIds`: every matching record's id. Fewer than `total` means the source stopped short, and the page says so. */
+    allIds?: RecordId[];
+}
+/** One row of a list. */
+export interface ListedRecord {
+    id: RecordId;
+    values: Values;
+    /** Its version, for a bulk edit that saves it to carry. */
+    version?: RecordVersion;
+    /** What the person may do with it: its row's buttons and a bulk edit keep to it. */
+    can?: RecordPermissions;
 }
 export interface GroupRequest {
     model: string;
@@ -157,6 +269,82 @@ export interface Group {
     label: string;
     count: number;
 }
+/** How a field is totalled: added up, averaged, its least or its most, or how many records hold a value in it. */
+export type TotalKind = 'sum' | 'avg' | 'min' | 'max' | 'count';
+export interface TotalsRequest {
+    model: string;
+    /** The list's search, as `list` gets it. For the ticked rows alone, add `{ field: 'id', op: 'in', value: ids }`. */
+    filter: ResolvedFilter[];
+    /** What to total, by field: `{ amount: ['sum'], hours: ['sum', 'avg'] }`. */
+    totals: Record<string, TotalKind[]>;
+    /** Total under each value of this field as well, grouped as `groups` groups it: a Group By heading's sums. */
+    groupBy?: string;
+}
+/**
+ * Each field's totals, by field and then by kind: `totals.amount.sum`. The
+ * sum and the count of nothing are 0, the others null. A total the source
+ * cannot make honestly — amounts in more than one currency — is null, and
+ * the page shows none.
+ */
+export type Totals = Record<string, Partial<Record<TotalKind, number | null>>>;
+export interface TotalsResult {
+    /** How many records match. */
+    count: number;
+    totals: Totals;
+    /** With `groupBy`: each value's totals, in the order `groups` gives them. */
+    groups?: TotalsGroup[];
+}
+export interface TotalsGroup extends Group {
+    totals: Totals;
+}
+/**
+ * A file to store: what an upload reads of a browser's `File`. Core names no
+ * DOM types; an adapter may type its parameter `File` and hand it to `fetch`
+ * or a storage SDK as it is.
+ */
+export interface UploadFile {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** An `AbortSignal`, as far as an upload listens to it. */
+export interface UploadSignal {
+    readonly aborted: boolean;
+    addEventListener(type: 'abort', listener: () => void): void;
+    removeEventListener(type: 'abort', listener: () => void): void;
+}
+export interface UploadRequest {
+    /** The page's model: for a saved form placed in a record, the record's. */
+    model: string;
+    /**
+     * The file or picture field the file is for. In a saved form placed in a
+     * record, whose answers the record keeps under the part's name, the field's
+     * place in them: `consent.doc`, as a line's table is `consent.items`.
+     */
+    field: string;
+    /** The record it is for; null while that record is new — its first save links the file to it. */
+    recordId: RecordId | null;
+    /** For a field on a line of a table: the table's field, the line's key and, once saved, its id. */
+    line?: {
+        field: string;
+        key: string;
+        id?: RecordId;
+    };
+    /** Aborts when the person takes the file away or leaves before it is stored: stop, and reject with an error named `AbortError`. */
+    signal?: UploadSignal;
+    /** How far it has got, bytes sent of the bytes in all, for its progress bar; without a call the bar moves with no number. */
+    onProgress?: (sent: number, total: number) => void;
+}
+/** A stored file, as the field keeps it — a `FileValue` with its link instead of its bytes. */
+export interface UploadedFile {
+    url: string;
+    name: string;
+    size: number;
+    type: string;
+    /** Its id, where the source keeps files as records of their own (Flectra's attachments): a save links it by this. */
+    fileId?: RecordId;
+}
 /**
  * A filter as a search receives it: each `valueFrom` already replaced by its
  * value. An adapter must keep the groups: `any` is an OR, `all` an AND.
@@ -213,16 +401,42 @@ export type LinkOp = {
 /**
  * Why a save was refused, so each kind is shown where it belongs: `fields`
  * under those fields, a `rule` (a backend's business rule) in a dialog,
- * `network` in a banner with Retry, and `other` beside Save with Retry.
+ * `network` in a banner with Retry, `other` beside Save with Retry, and a
+ * `conflict` with Reload and Keep mine.
  */
 export interface SaveProblem {
     /** `stopped`: a step of the page's `beforeSave` stopped it, with `reason` — no data source was asked. */
-    kind: 'fields' | 'rule' | 'network' | 'other' | 'stopped';
+    kind: 'fields' | 'rule' | 'network' | 'other' | 'stopped' | 'conflict';
     message: string;
     /** For `fields`: a message for each field, by name. */
     fields?: Record<string, string>;
     /** For `stopped`: why the step stopped. */
     reason?: RunStop;
+    /** For `conflict`: who changed the record, when, and what it holds now. */
+    conflict?: SaveConflict;
+}
+/** Someone else saved the record after this page opened it. */
+export interface SaveConflict {
+    /** The version the record has now, with who changed it and when. Saving with it is "Keep mine". */
+    version: RecordVersion;
+    /**
+     * The record as the other person left it, when the source has it: what
+     * Reload shows without asking again, and what a source that saves whole
+     * records keeps of theirs under Keep mine — their values, with this
+     * person's changes over them.
+     */
+    theirs?: Values;
+}
+/**
+ * What a source's save throws when the record changed after the page opened
+ * it: `saveProblemOf` reads it as a `conflict`, and the page names who
+ * changed it and when (`conflict.version.by`, `.at`) and offers Reload or
+ * Keep mine.
+ */
+export declare class ConflictError extends Error {
+    readonly conflict: SaveConflict;
+    readonly problem: SaveProblem;
+    constructor(conflict: SaveConflict, message?: string);
 }
 /** An error for a data source's save to throw when the backend refuses it. */
 export declare function saveRefused(problem: SaveProblem): Error & {