@optionfactory/fml 9.0.0-rc30 → 9.0.0-rc31

package/dist/ftl.d.mts

@@ -36,6 +36,16 @@ declare class Expressions {
      * `{{{ }}}` (html) or `{{{{ }}}}` (node) interpolation, in order.
      */
     static MODE_TEMPLATED: symbol;
+    /**
+     * The key under which the receiver of a module function answers a lookup
+     * against the bound data alone: `this[Expressions.BOUND](name)` resolves
+     * the name in the layers the scope was created with (a registry's data,
+     * the data handed to a Template factory) and never in an overlay pushed
+     * afterwards, by `data-tpl-each`, `data-tpl-with` or `withOverlay`. It is
+     * how a module reads what the page configured without the rendered data
+     * being able to supply or replace it. No name on the data stack reaches it.
+     */
+    static BOUND: symbol;
     /**
      * Parses an expression, caching the ast by mode and text.
      * @param {string} expression
@@ -50,38 +60,45 @@ declare class Expressions {
      * @param {any[]} dataStack innermost overlay last
      * @param {any} ast what `parse` answered
      * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] the mode it was parsed in
+     * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
      * @returns {any} the value, or the list of parts in MODE_TEMPLATED
      */
     static evaluate(modules: {
         [k: string]: any;
-    } | null | undefined, dataStack: any[], ast: any, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null): any;
+    } | null | undefined, dataStack: any[], ast: any, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null, bound?: number): any;
     /**
      * Parses and evaluates an expression.
      * @param {{ [x: string]: any; } | null | undefined} modules
      * @param {any[]} dataStack innermost overlay last
      * @param {string} expression
      * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] MODE_EXPRESSION when omitted
+     * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
      * @returns {any} the value, or the list of parts in MODE_TEMPLATED
      */
     static interpret(modules: {
         [x: string]: any;
-    } | null | undefined, dataStack: any[], expression: string, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null): any;
+    } | null | undefined, dataStack: any[], expression: string, mode?: (typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED) | null, bound?: number): any;
 }
 /**
  * A scope: the modules that `#name:fn()` resolves against and the data stack
  * that a bare identifier resolves against, as a single value. Adding an overlay
  * returns a new evaluator instead of modifying this one, so a template can add
  * data for one subtree without affecting the rest of the render.
+ *
+ * The layers an evaluator is created with are its bound data; the overlays
+ * pushed afterwards are not. A bare identifier resolves against both, while a
+ * module function can ask for the bound data alone through `Expressions.BOUND`.
  */
 declare class ExpressionEvaluator {
     #private;
     /**
      * @param {{ [k: string]: any } | null | undefined} modules
      * @param {any[]} dataStack innermost overlay last
+     * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
      */
     constructor(modules: {
         [k: string]: any;
-    } | null | undefined, dataStack: any[]);
+    } | null | undefined, dataStack: any[], bound?: number);
     /**
      * A new evaluator with one more module: `#name:fn()` resolves into it, and an
      * empty name merges a whole map whose functions resolve bare, as `#fn()`.
@@ -92,7 +109,7 @@ declare class ExpressionEvaluator {
     withModule(name: string, value: object): ExpressionEvaluator;
     /**
      * A new evaluator with the data pushed as the innermost overlays, the last
-     * one winning a shared name.
+     * one winning a shared name. The bound data stays what it was.
      * @param {...any} data
      * @returns {ExpressionEvaluator}
      */
@@ -565,7 +582,9 @@ declare class Registry {
     }): Registry;
     /**
      * Defines every element deferred so far; from then on, defineElement takes
-     * effect immediately.
+     * effect immediately. Readiness waits for the first call: a page that
+     * configures late (translations fetched first) gets its ftl:ready once the
+     * elements this defines have upgraded, not at DOMContentLoaded.
      * @returns {Registry} this registry
      */
     configure(): Registry;
@@ -592,9 +611,11 @@ declare class Registry {
     /**
      * Waits for this registry's readiness: resolves right after its ftl:ready
      * event is dispatched on the document, and immediately when that already
-     * happened. Never rejects: a failed upgrade counts as settled, and its
-     * rejection is left unhandled so it still reaches the console and the
-     * page's error reporting.
+     * happened. The event is dispatched once DOMContentLoaded has passed,
+     * configure() has been called and the queue has drained, so a registry
+     * that is never configured is never ready. Never rejects: a failed
+     * upgrade counts as settled, and its rejection is left unhandled so it
+     * still reaches the console and the page's error reporting.
      * @returns {Promise<void>}
      */
     ready(): Promise<void>;
@@ -811,7 +832,9 @@ export type Receiver = {
  * The translations as a template module: `#l10n:t()` for messages, plus date,
  * number and bytes formatting in the page's locale. The template form and the
  * imperative `of()` facade both resolve through the registry's scope, so they
- * always produce the same result for the same key.
+ * always produce the same result for the same key. A template reads `l10n`
+ * and `locale` from its bound data only, the most recent layer winning: an
+ * overlay pushed while rendering (a row, a response) never reaches them.
  */
 declare class Localization {
     /**

package/dist/ftl.iife.js

@@ -2850,6 +2850,8 @@ var ftl = (function (exports) {
         return undefined;
     };
 
+    const BOUND = Symbol('BOUND');
+
     /**
      * Evaluates a parsed expression against a scope. One instance per evaluation:
      * it holds the modules and the data stack that names resolve against, and keeps
@@ -2858,9 +2860,11 @@ var ftl = (function (exports) {
     class EvaluatingVisitor {
         #modules;
         #dataStack;
-        constructor(modules, dataStack) {
+        #bound;
+        constructor(modules, dataStack, bound) {
             this.#modules = modules;
             this.#dataStack = dataStack;
+            this.#bound = bound ?? dataStack.length;
         }
         #resolve(prop) {
             return resolveInStack(this.#dataStack, prop);
@@ -2884,8 +2888,9 @@ var ftl = (function (exports) {
         #cached_resolve_proxy;
         #resolve_proxy() {
             if (!this.#cached_resolve_proxy) {
+                const bound = (name) => resolveInStack(this.#dataStack.slice(0, this.#bound), name);
                 this.#cached_resolve_proxy = new Proxy(this.#dataStack, {
-                    get: (target, prop) => this.#resolve(prop),
+                    get: (target, prop) => (prop === BOUND ? bound : this.#resolve(prop)),
                 });
             }
             return this.#cached_resolve_proxy;
@@ -3038,6 +3043,16 @@ var ftl = (function (exports) {
          * `{{{ }}}` (html) or `{{{{ }}}}` (node) interpolation, in order.
          */
         static MODE_TEMPLATED = Symbol('MODE_TEMPLATED');
+        /**
+         * The key under which the receiver of a module function answers a lookup
+         * against the bound data alone: `this[Expressions.BOUND](name)` resolves
+         * the name in the layers the scope was created with (a registry's data,
+         * the data handed to a Template factory) and never in an overlay pushed
+         * afterwards, by `data-tpl-each`, `data-tpl-with` or `withOverlay`. It is
+         * how a module reads what the page configured without the rendered data
+         * being able to supply or replace it. No name on the data stack reaches it.
+         */
+        static BOUND = BOUND;
 
         static #astCache = new BoundedCache(1000);
 
@@ -3062,10 +3077,11 @@ var ftl = (function (exports) {
          * @param {any[]} dataStack innermost overlay last
          * @param {any} ast what `parse` answered
          * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] the mode it was parsed in
+         * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
          * @returns {any} the value, or the list of parts in MODE_TEMPLATED
          */
-        static evaluate(modules, dataStack, ast, mode) {
-            return new EvaluatingVisitor(modules, dataStack).visitRoot(ast, mode === Expressions.MODE_TEMPLATED);
+        static evaluate(modules, dataStack, ast, mode, bound) {
+            return new EvaluatingVisitor(modules, dataStack, bound).visitRoot(ast, mode === Expressions.MODE_TEMPLATED);
         }
         /**
          * Parses and evaluates an expression.
@@ -3073,10 +3089,11 @@ var ftl = (function (exports) {
          * @param {any[]} dataStack innermost overlay last
          * @param {string} expression
          * @param {(typeof Expressions.MODE_EXPRESSION | typeof Expressions.MODE_TEMPLATED)?} [mode] MODE_EXPRESSION when omitted
+         * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
          * @returns {any} the value, or the list of parts in MODE_TEMPLATED
          */
-        static interpret(modules, dataStack, expression, mode) {
-            return Expressions.evaluate(modules, dataStack, Expressions.parse(expression, mode), mode);
+        static interpret(modules, dataStack, expression, mode, bound) {
+            return Expressions.evaluate(modules, dataStack, Expressions.parse(expression, mode), mode, bound);
         }
     }
 
@@ -3085,17 +3102,24 @@ var ftl = (function (exports) {
      * that a bare identifier resolves against, as a single value. Adding an overlay
      * returns a new evaluator instead of modifying this one, so a template can add
      * data for one subtree without affecting the rest of the render.
+     *
+     * The layers an evaluator is created with are its bound data; the overlays
+     * pushed afterwards are not. A bare identifier resolves against both, while a
+     * module function can ask for the bound data alone through `Expressions.BOUND`.
      */
     class ExpressionEvaluator {
         #modules;
         #dataStack;
+        #bound;
         /**
          * @param {{ [k: string]: any } | null | undefined} modules
          * @param {any[]} dataStack innermost overlay last
+         * @param {number} [bound] how many layers, from the outermost, are the bound data; all of them when omitted
          */
-        constructor(modules, dataStack) {
+        constructor(modules, dataStack, bound) {
             this.#modules = modules;
             this.#dataStack = dataStack;
+            this.#bound = bound ?? dataStack.length;
         }
         /**
          * A new evaluator with one more module: `#name:fn()` resolves into it, and an
@@ -3106,11 +3130,11 @@ var ftl = (function (exports) {
          */
         withModule(name, value) {
             const module = name ? { [name]: value } : value;
-            return new ExpressionEvaluator({ ...this.#modules, ...module }, this.#dataStack);
+            return new ExpressionEvaluator({ ...this.#modules, ...module }, this.#dataStack, this.#bound);
         }
         /**
          * A new evaluator with the data pushed as the innermost overlays, the last
-         * one winning a shared name.
+         * one winning a shared name. The bound data stays what it was.
          * @param {...any} data
          * @returns {ExpressionEvaluator}
          */
@@ -3118,6 +3142,7 @@ var ftl = (function (exports) {
             return new ExpressionEvaluator(
                 this.#modules,
                 data.length === 0 ? this.#dataStack : [...this.#dataStack, ...data],
+                this.#bound,
             );
         }
         /**
@@ -3135,7 +3160,13 @@ var ftl = (function (exports) {
          * @returns {any}
          */
         evaluateExpression(expression) {
-            return Expressions.interpret(this.#modules, this.#dataStack, expression, Expressions.MODE_EXPRESSION);
+            return Expressions.interpret(
+                this.#modules,
+                this.#dataStack,
+                expression,
+                Expressions.MODE_EXPRESSION,
+                this.#bound,
+            );
         }
         /**
          * Evaluates a templated text, the `{{ }}` form, against this scope.
@@ -3143,7 +3174,7 @@ var ftl = (function (exports) {
          * @returns {{ type: symbol, value: any }[]} its parts, as MODE_TEMPLATED describes
          */
         evaluateTemplated(text) {
-            return Expressions.interpret(this.#modules, this.#dataStack, text, Expressions.MODE_TEMPLATED);
+            return Expressions.interpret(this.#modules, this.#dataStack, text, Expressions.MODE_TEMPLATED, this.#bound);
         }
     }
 
@@ -4039,14 +4070,22 @@ var ftl = (function (exports) {
         #ready = new Promise((resolve) => {
             this.#readyResolve = resolve;
         });
+        #configured = /** @type {PromiseWithResolvers<void>} */ (Promise.withResolvers());
         constructor() {
-            Nodes.waitDomContentLoaded(document).then(() => {
+            Promise.all([Nodes.waitDomContentLoaded(document), this.#configured.promise]).then(() => {
                 this.#start();
             });
         }
         ready() {
             return this.#ready;
         }
+        /**
+         * Marks the registry as configured: until then nothing is defined, so an
+         * empty queue says nothing about the page and readiness is held back.
+         */
+        configured() {
+            this.#configured.resolve();
+        }
         async #start() {
             await this.settled();
             document.dispatchEvent(
@@ -4089,7 +4128,10 @@ var ftl = (function (exports) {
          * @returns {Promise<void>}
          */
         settled() {
-            return this.#drain(() => true, (entry) => entry.finished);
+            return this.#drain(
+                () => true,
+                (entry) => entry.finished,
+            );
         }
         /**
          * Waits for the accepted upgrades, the ones enqueued meanwhile included,
@@ -4343,7 +4385,9 @@ var ftl = (function (exports) {
         }
         /**
          * Defines every element deferred so far; from then on, defineElement takes
-         * effect immediately.
+         * effect immediately. Readiness waits for the first call: a page that
+         * configures late (translations fetched first) gets its ftl:ready once the
+         * elements this defines have upgraded, not at DOMContentLoaded.
          * @returns {Registry} this registry
          */
         configure() {
@@ -4352,6 +4396,7 @@ var ftl = (function (exports) {
                 delete this.#tagToClass[tag];
             }
             this.#configured = true;
+            this.#upgradeQueue.configured();
             return this;
         }
         /**
@@ -4383,9 +4428,11 @@ var ftl = (function (exports) {
         /**
          * Waits for this registry's readiness: resolves right after its ftl:ready
          * event is dispatched on the document, and immediately when that already
-         * happened. Never rejects: a failed upgrade counts as settled, and its
-         * rejection is left unhandled so it still reaches the console and the
-         * page's error reporting.
+         * happened. The event is dispatched once DOMContentLoaded has passed,
+         * configure() has been called and the queue has drained, so a registry
+         * that is never configured is never ready. Never rejects: a failed
+         * upgrade counts as settled, and its rejection is left unhandled so it
+         * still reaches the console and the page's error reporting.
          * @returns {Promise<void>}
          */
         ready() {
@@ -4729,12 +4776,27 @@ var ftl = (function (exports) {
      */
 
     /**
-     * The receiver contract of the module functions: bound to a proxy over the
-     * data stack when called from a template, or to a plain object by Localization.of().
+     * The receiver contract of the module functions: a plain object carrying the
+     * translations and the locale, as Localization.of() binds them, or the proxy
+     * over the data stack a template calls them with.
      *
      * @typedef {{ l10n?: Messages, locale?: string }} Receiver
      */
 
+    /**
+     * The translations or the locale of a receiver. From a template they are read
+     * from the bound data alone (the registry's overlays, or the data handed to
+     * the Template factory): the rows and responses a render pushes on top are
+     * what arrives later, and must not supply or replace the page's own messages.
+     * @param {any} receiver
+     * @param {'l10n' | 'locale'} name
+     * @returns {any}
+     */
+    const configured = (receiver, name) => {
+        const bound = receiver[Expressions.BOUND];
+        return typeof bound === 'function' ? bound(name) : receiver[name];
+    };
+
     const PLACEHOLDER = /\{(\w+)\}/g;
     const POSITIONAL = /\{(\d+)\}/g;
     /** @param {any} v @returns {v is Record<string, string>} */
@@ -4769,7 +4831,9 @@ var ftl = (function (exports) {
      * The translations as a template module: `#l10n:t()` for messages, plus date,
      * number and bytes formatting in the page's locale. The template form and the
      * imperative `of()` facade both resolve through the registry's scope, so they
-     * always produce the same result for the same key.
+     * always produce the same result for the same key. A template reads `l10n`
+     * and `locale` from its bound data only, the most recent layer winning: an
+     * overlay pushed while rendering (a row, a response) never reaches them.
      */
     class Localization {
         /**
@@ -4788,7 +4852,7 @@ var ftl = (function (exports) {
          * @returns {string} the message, or the key itself when the translations do not carry it
          */
         static t(key, ...args) {
-            const messages = this.l10n ?? {};
+            const messages = configured(this, 'l10n') ?? {};
             let message = Object.hasOwn(messages, key) ? messages[key] : undefined;
             if (message === undefined) {
                 warnOnce(`missing message "${key}"`);
@@ -4800,7 +4864,7 @@ var ftl = (function (exports) {
                     warnOnce(`plural message "${key}" needs a numeric {count}`);
                     message = message.other;
                 } else {
-                    const locale = this.locale ?? navigator?.language ?? 'en';
+                    const locale = configured(this, 'locale') ?? navigator?.language ?? 'en';
                     const category = formatter(Intl.PluralRules, locale).select(named.count);
                     message = message[category] ?? message.other;
                 }
@@ -4840,7 +4904,7 @@ var ftl = (function (exports) {
          * @returns {string}
          */
         static date(value, options) {
-            return formatter(Intl.DateTimeFormat, this.locale, options).format(value);
+            return formatter(Intl.DateTimeFormat, configured(this, 'locale'), options).format(value);
         }
 
         /**
@@ -4852,7 +4916,7 @@ var ftl = (function (exports) {
          * @returns {string}
          */
         static number(value, options) {
-            return formatter(Intl.NumberFormat, this.locale, options).format(value);
+            return formatter(Intl.NumberFormat, configured(this, 'locale'), options).format(value);
         }
 
         /**
@@ -4865,7 +4929,7 @@ var ftl = (function (exports) {
          * @returns {string}
          */
         static bytes(value) {
-            const format = formatter(Intl.NumberFormat, this.locale, { maximumFractionDigits: 2 }).format;
+            const format = formatter(Intl.NumberFormat, configured(this, 'locale'), { maximumFractionDigits: 2 }).format;
             if (value >= 1024 * 1024 * 1024) {
                 return `${format(value / 1024 / 1024 / 1024)}GiB`;
             }