@optionfactory/fml 9.0.0-rc30 → 9.0.0-rc32

package/dist/ftl.mjs

@@ -2847,6 +2847,8 @@ const resolveInStack = (dataStack, prop) => {
     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
@@ -2855,9 +2857,11 @@ const resolveInStack = (dataStack, prop) => {
 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);
@@ -2881,8 +2885,9 @@ class EvaluatingVisitor {
     #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;
@@ -3035,6 +3040,16 @@ class Expressions {
      * `{{{ }}}` (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);
 
@@ -3059,10 +3074,11 @@ 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, 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.
@@ -3070,10 +3086,11 @@ class Expressions {
      * @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);
     }
 }
 
@@ -3082,17 +3099,24 @@ class Expressions {
  * 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
@@ -3103,11 +3127,11 @@ class ExpressionEvaluator {
      */
     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}
      */
@@ -3115,6 +3139,7 @@ class ExpressionEvaluator {
         return new ExpressionEvaluator(
             this.#modules,
             data.length === 0 ? this.#dataStack : [...this.#dataStack, ...data],
+            this.#bound,
         );
     }
     /**
@@ -3132,7 +3157,13 @@ class ExpressionEvaluator {
      * @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.
@@ -3140,7 +3171,7 @@ class ExpressionEvaluator {
      * @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);
     }
 }
 
@@ -4036,14 +4067,22 @@ class UpgradeQueue {
     #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(
@@ -4086,7 +4125,10 @@ class UpgradeQueue {
      * @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,
@@ -4340,7 +4382,9 @@ class 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() {
@@ -4349,6 +4393,7 @@ class Registry {
             delete this.#tagToClass[tag];
         }
         this.#configured = true;
+        this.#upgradeQueue.configured();
         return this;
     }
     /**
@@ -4380,9 +4425,11 @@ 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() {
@@ -4726,12 +4773,27 @@ class ParsedElement extends HTMLElement {
  */
 
 /**
- * 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>} */
@@ -4766,7 +4828,9 @@ const formatter = (ctor, locale, options) => {
  * 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 {
     /**
@@ -4785,7 +4849,7 @@ class Localization {
      * @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}"`);
@@ -4797,7 +4861,7 @@ class Localization {
                 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;
             }
@@ -4837,7 +4901,7 @@ class Localization {
      * @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);
     }
 
     /**
@@ -4849,7 +4913,7 @@ class Localization {
      * @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);
     }
 
     /**
@@ -4862,7 +4926,7 @@ class Localization {
      * @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`;
         }