be-intl 0.0.51 → 0.0.52

package/README.md

@@ -97,6 +97,66 @@ The semantic example above involves a lot of keyboard tapping of the letters "be
 🌐-weekday=long 🌐-year=numeric 🌐-month=long 🌐-day=numeric></time>
 ```
 
+## Programmatic attachment (no attribute)
+
+The attribute syntax shown above shines for server-rendered HTML and progressive enhancement:  the markup alone says how each value should be formatted.  But most web development today renders on the client, with a framework (Lit, React, Vue, Svelte, etc.) that already has a JavaScript reference to each element it creates.  In that setting, attaching be-intl programmatically is the better fit:
+
+1.  **A less clunky API.**  Frameworks tend to be awkward about setting arbitrary (let alone emoji) attributes, and quoting JSON inside an attribute, like `be-intl='{ "style": "currency", "currency": "EUR" }'`, is error prone.  Setting `format` to `{style: 'currency', currency: 'EUR'}` is ordinary JavaScript, which TypeScript can check against `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions`.  You can also set `locale` directly, which has no attribute equivalent.
+2.  **Less stringifying and parsing.**  With an attribute, the framework serializes the format options to JSON, and be-intl then parses that JSON back into an object.  Setting `format` directly skips both steps.
+3.  **Less overhead monitoring attributes.**  The attribute approach relies on [be-hive](https://github.com/bahrus/be-hive) / [mount-observer](https://github.com/bahrus/mount-observer) watching the DOM for elements that carry (or gain) the attribute, and for changes to its value.  The programmatic approach needs none of that -- `def.js` just registers the enhancement's config, and the enhancement is attached exactly when, and to exactly the elements, your code says.
+
+Both approaches produce the same enhancement, with the same locale resolution and formatting rules, so you can mix them in one app -- attributes for server-rendered islands, programmatic attachment inside client-rendered components.
+
+First register the enhancement's config once:
+
+```JS
+import { defBeIntl } from 'be-intl/def.js';
+const emc = await defBeIntl(document.body); // or a shadow root's host, for a scoped registry
+```
+
+Then set any of these properties:
+
+| Attribute                                   | Property                          | Notes                                                                                  |
+|---------------------------------------------|-----------------------------------|----------------------------------------------------------------------------------------|
+| `be-intl` / `🌐`                            | `format`                          | An `Intl.NumberFormatOptions` / `Intl.DateTimeFormatOptions` object.  A bare attribute is `{}`.  |
+| `be-intl-style`, `-currency`, `-weekday`, `-year`, `-month`, `-day` | `style`, `currency`, `weekday`, `year`, `month`, `day` | Folded into `format`; keys set explicitly in `format` win.  |
+| `be-intl-observe-lang`                      | `observeLang`                     | `true` / `false`.                                                                      |
+| `be-intl-announce`                          | `announce`                        | `true` / `false`.                                                                      |
+| *(none -- `lang`)*                          | `locale`                          | A BCP-47 tag.  Overrides the locale resolved from `lang`.                              |
+
+### Declarative -- via `enh.set`
+
+```JS
+// equivalent to <data value=123456.789 lang="de-DE" be-intl='{ "style": "currency", "currency": "EUR" }'>
+data.enh.set.beIntl.format = {style: 'currency', currency: 'EUR'};
+```
+
+Only the first property needs `.set` -- it's what triggers the attachment.  This can be done before or after `defBeIntl` has been called.
+
+### Imperative -- via `enh.get()`
+
+```JS
+Object.assign(data.enh.get(emc), {
+    locale: 'de-DE',
+    style: 'currency',
+    currency: 'USD',
+});
+```
+
+`data.enh.get(emc)` with no properties at all is equivalent to a bare `be-intl` attribute.
+
+### Changing the formatting later
+
+After the first render, setting `locale`, `format` or one of the semantic properties re-formats the element:
+
+```JS
+data.enh.beIntl.currency = 'EUR';
+```
+
+`format` is compared by reference, so assign a new object rather than mutating the existing one.
+
+See [demo/Programmatic](demo/Programmatic/) for runnable examples.
+
 ## Viewing Demos Locally
 
 1. Install git

package/be-intl.js

@@ -1,168 +1,170 @@
-// @ts-check
-/** @import {Actions, PAP, AllProps, AP} from './types/be-intl/types' */;
-/** @import {RoundaboutOptions} from './types/roundabout/types' */;
-/** @import {ElementEnhancementGateway, SpawnContext} from './types/assign-gingerly/types' */;
-/** @import {EMC} from './types/mount-observer/types' */;
-/** @import {RAConfig} from './types/roundabout/types' */;
-
-const defaultLocale = new Intl.NumberFormat().resolvedOptions().locale;
-
-/** Semantic sugar attributes folded into `format`. */
-const SEMANTIC_KEYS = ['style', 'currency', 'weekday', 'year', 'month', 'day'];
-
-/**
- * @implements {Actions}
- */
-class BeIntl {
-
-    /**
-     * @this {AllProps & Actions}
-     * @param {Element & ElementEnhancementGateway} enhancedElement
-     * @param {SpawnContext} ctx
-     * @param {PAP} initVals
-     */
-    constructor(enhancedElement, ctx, initVals){
-        this.init(this, enhancedElement, ctx, initVals);
-    }
-
-    /**
-     * @param {AllProps} self
-     * @param {Element & ElementEnhancementGateway} enhancedElement
-     * @param {SpawnContext} ctx
-     * @param {PAP} initVals
-     */
-    async init(self, enhancedElement, ctx, initVals){
-        const {customData} = /** @type {EMC<any, AllProps, Element, RAConfig<AllProps, Actions>>} */ (ctx.emc);
-        /**
-         * @type {RoundaboutOptions}
-         */
-        const raOptions = {
-            ...customData,
-            vm: self,
-            initialPropVals: {
-                enhancedElement,
-                ...customData?.defaultPropVals,
-                ...initVals
-            }
-        };
-        await (await import('roundabout-lib/roundabout.js')).roundabout(raOptions);
-        self.initialized = true;
-    }
-
-    /**
-     * Wire up live-update observation, resolve the locale, and seed the value.
-     * @param {AP} self
-     * @returns {Promise<PAP>}
-     */
-    async hydrate(self){
-        const {enhancedElement} = self;
-
-        // Re-format whenever the element's underlying value property changes.
-        // <data>/<output> reflect through `value`, <time> through `dateTime`.
-        const valueProp = enhancedElement.localName === 'time' ? 'dateTime' : 'value';
-        const inference = await infer(enhancedElement);
-        const propagator = await inference.getPropagator();
-        propagator.addEventListener(valueProp, () => {
-            self.value = inference.value;
-        });
-
-        // Opt-in: track lang changes on the element itself. Container-`lang`
-        // changes after mount aren't observed (rare); `inference.lang` still
-        // walks ancestors + shadow hosts on each read.
-        if(self.observeLang && enhancedElement instanceof HTMLElement){
-            const langObserver = new MutationObserver(() => {
-                self.locale = inference.lang || defaultLocale;
-            });
-            langObserver.observe(enhancedElement, {attributes: true, attributeFilter: ['lang']});
-        }
-
-        const locale = self.locale || inference.lang || defaultLocale;
-        return {locale, value: inference.value};
-    }
-
-    /**
-     * (Re)build the Intl formatter. `value` is seeded by `hydrate` and kept
-     * fresh by the propagator, so it isn't read here.
-     * @param {AP} self
-     * @returns {PAP}
-     */
-    onFormattingChange(self){
-        const {enhancedElement, locale} = self;
-        // Explicit JSON (`self.format`) wins; semantic sub-attributes fill the gaps.
-        const format = {.../** @type {Record<string, any>} */ (self.format || {})};
-        for(const key of SEMANTIC_KEYS){
-            const val = /** @type {Record<string, any>} */ (self)[key];
-            if(val !== undefined && format[key] === undefined) format[key] = val;
-        }
-        if(enhancedElement.localName === 'time'){
-            return {
-                intlDateFormat: new Intl.DateTimeFormat(locale, /** @type {Intl.DateTimeFormatOptions} */ (format)),
-                resolved: true,
-            };
-        }
-        return {
-            intlNumberFormat: new Intl.NumberFormat(locale, /** @type {Intl.NumberFormatOptions} */ (format)),
-            resolved: true,
-        };
-    }
-
-    /**
-     * @param {AP} self
-     * @returns {PAP | void}
-     */
-    formatNumber(self){
-        const {enhancedElement, value, intlNumberFormat} = self;
-        if(intlNumberFormat === undefined || value === undefined || value === null){
-            enhancedElement.textContent = '';
-            return;
-        }
-        enhancedElement.textContent = intlNumberFormat.format(/** @type {number} */ (value));
-        if(!self.rendered) return {rendered: true};
-    }
-
-    /**
-     * @param {AP} self
-     * @returns {PAP | void}
-     */
-    formatDate(self){
-        const {enhancedElement, value, intlDateFormat} = self;
-        if(intlDateFormat === undefined || value === undefined || value === null) return;
-        enhancedElement.textContent = intlDateFormat.format(/** @type {Date} */ (value));
-        if(!self.rendered) return {rendered: true};
-    }
-
-    /**
-     * Opt-in via `be-intl-announce`. Once the value has rendered at least once,
-     * mark the element as a polite ARIA live region so subsequent re-formats
-     * (value or locale changes) are announced by assistive tech. Deliberately
-     * deferred past the first render so the initial value isn't spoken on load,
-     * and `aria-live` is skipped for `<output>` (already an implicit polite live
-     * region). `aria-atomic` keeps multi-token output (e.g. a formatted date)
-     * announcing as one unit.
-     * @param {AP} self
-     */
-    armLiveRegion(self){
-        const {enhancedElement} = self;
-        if(!(enhancedElement instanceof HTMLElement)) return;
-        enhancedElement.setAttribute('aria-atomic', 'true');
-        if(enhancedElement.localName !== 'output'){
-            enhancedElement.setAttribute('aria-live', 'polite');
-        }
-    }
-}
-
-/**
- * Resolve the `inferencer` enhancement instance for an element. Typed loosely
- * (`Promise<any>`) so the class doesn't couple to the `Infer` shape; `.value`
- * is a live, type-coerced read (`Date` for `<time>`, `number` for `<data>`),
- * `getPropagator()` emits on value-property changes.
- * @param {Element & ElementEnhancementGateway} from
- * @returns {Promise<any>}
- */
-async function infer(from){
-    return /** @type {any} */ (
-        from.enh.get((await import('assign-gingerly/inferencer/inferencer.js')).registryItem)
-    );
-}
-
-export { BeIntl };
+// @ts-check
+/** @import {Actions, PAP, AllProps, AP} from './types/be-intl/types' */;
+/** @import {RoundaboutOptions} from './types/roundabout/types' */;
+/** @import {ElementEnhancementGateway, SpawnContext} from './types/assign-gingerly/types' */;
+/** @import {EMC} from './types/mount-observer/types' */;
+/** @import {RAConfig} from './types/roundabout/types' */;
+
+const defaultLocale = new Intl.NumberFormat().resolvedOptions().locale;
+
+/** Semantic sugar attributes folded into `format`. */
+const SEMANTIC_KEYS = ['style', 'currency', 'weekday', 'year', 'month', 'day'];
+
+/**
+ * @implements {Actions}
+ */
+class BeIntl {
+
+    /**
+     * @this {AllProps & Actions}
+     * @param {Element & ElementEnhancementGateway} enhancedElement
+     * @param {SpawnContext} ctx
+     * @param {PAP} initVals
+     */
+    constructor(enhancedElement, ctx, initVals){
+        this.init(this, enhancedElement, ctx, initVals);
+    }
+
+    /**
+     * @param {AllProps} self
+     * @param {Element & ElementEnhancementGateway} enhancedElement
+     * @param {SpawnContext} ctx
+     * @param {PAP} initVals
+     */
+    async init(self, enhancedElement, ctx, initVals){
+        // ctx.emc is only populated on the attribute (mount-observer) path;
+        // enh.get() / enh.set only pass the registry item -- see def.js.
+        const {customData} = /** @type {EMC<any, AllProps, Element, RAConfig<AllProps, Actions>>} */ (ctx.emc || ctx.config);
+        /**
+         * @type {RoundaboutOptions}
+         */
+        const raOptions = {
+            ...customData,
+            vm: self,
+            initialPropVals: {
+                enhancedElement,
+                ...customData?.defaultPropVals,
+                ...initVals
+            }
+        };
+        await (await import('roundabout-lib/roundabout.js')).roundabout(raOptions);
+        self.initialized = true;
+    }
+
+    /**
+     * Wire up live-update observation, resolve the locale, and seed the value.
+     * @param {AP} self
+     * @returns {Promise<PAP>}
+     */
+    async hydrate(self){
+        const {enhancedElement} = self;
+
+        // Re-format whenever the element's underlying value property changes.
+        // <data>/<output> reflect through `value`, <time> through `dateTime`.
+        const valueProp = enhancedElement.localName === 'time' ? 'dateTime' : 'value';
+        const inference = await infer(enhancedElement);
+        const propagator = await inference.getPropagator();
+        propagator.addEventListener(valueProp, () => {
+            self.value = inference.value;
+        });
+
+        // Opt-in: track lang changes on the element itself. Container-`lang`
+        // changes after mount aren't observed (rare); `inference.lang` still
+        // walks ancestors + shadow hosts on each read.
+        if(self.observeLang && enhancedElement instanceof HTMLElement){
+            const langObserver = new MutationObserver(() => {
+                self.locale = inference.lang || defaultLocale;
+            });
+            langObserver.observe(enhancedElement, {attributes: true, attributeFilter: ['lang']});
+        }
+
+        const locale = self.locale || inference.lang || defaultLocale;
+        return {locale, value: inference.value};
+    }
+
+    /**
+     * (Re)build the Intl formatter. `value` is seeded by `hydrate` and kept
+     * fresh by the propagator, so it isn't read here.
+     * @param {AP} self
+     * @returns {PAP}
+     */
+    onFormattingChange(self){
+        const {enhancedElement, locale} = self;
+        // Explicit JSON (`self.format`) wins; semantic sub-attributes fill the gaps.
+        const format = {.../** @type {Record<string, any>} */ (self.format || {})};
+        for(const key of SEMANTIC_KEYS){
+            const val = /** @type {Record<string, any>} */ (self)[key];
+            if(val !== undefined && format[key] === undefined) format[key] = val;
+        }
+        if(enhancedElement.localName === 'time'){
+            return {
+                intlDateFormat: new Intl.DateTimeFormat(locale, /** @type {Intl.DateTimeFormatOptions} */ (format)),
+                resolved: true,
+            };
+        }
+        return {
+            intlNumberFormat: new Intl.NumberFormat(locale, /** @type {Intl.NumberFormatOptions} */ (format)),
+            resolved: true,
+        };
+    }
+
+    /**
+     * @param {AP} self
+     * @returns {PAP | void}
+     */
+    formatNumber(self){
+        const {enhancedElement, value, intlNumberFormat} = self;
+        if(intlNumberFormat === undefined || value === undefined || value === null){
+            enhancedElement.textContent = '';
+            return;
+        }
+        enhancedElement.textContent = intlNumberFormat.format(/** @type {number} */ (value));
+        if(!self.rendered) return {rendered: true};
+    }
+
+    /**
+     * @param {AP} self
+     * @returns {PAP | void}
+     */
+    formatDate(self){
+        const {enhancedElement, value, intlDateFormat} = self;
+        if(intlDateFormat === undefined || value === undefined || value === null) return;
+        enhancedElement.textContent = intlDateFormat.format(/** @type {Date} */ (value));
+        if(!self.rendered) return {rendered: true};
+    }
+
+    /**
+     * Opt-in via `be-intl-announce`. Once the value has rendered at least once,
+     * mark the element as a polite ARIA live region so subsequent re-formats
+     * (value or locale changes) are announced by assistive tech. Deliberately
+     * deferred past the first render so the initial value isn't spoken on load,
+     * and `aria-live` is skipped for `<output>` (already an implicit polite live
+     * region). `aria-atomic` keeps multi-token output (e.g. a formatted date)
+     * announcing as one unit.
+     * @param {AP} self
+     */
+    armLiveRegion(self){
+        const {enhancedElement} = self;
+        if(!(enhancedElement instanceof HTMLElement)) return;
+        enhancedElement.setAttribute('aria-atomic', 'true');
+        if(enhancedElement.localName !== 'output'){
+            enhancedElement.setAttribute('aria-live', 'polite');
+        }
+    }
+}
+
+/**
+ * Resolve the `inferencer` enhancement instance for an element. Typed loosely
+ * (`Promise<any>`) so the class doesn't couple to the `Infer` shape; `.value`
+ * is a live, type-coerced read (`Date` for `<time>`, `number` for `<data>`),
+ * `getPropagator()` emits on value-property changes.
+ * @param {Element & ElementEnhancementGateway} from
+ * @returns {Promise<any>}
+ */
+async function infer(from){
+    return /** @type {any} */ (
+        from.enh.get((await import('assign-gingerly/inferencer/inferencer.js')).registryItem)
+    );
+}
+
+export { BeIntl };

package/def.js

@@ -0,0 +1,21 @@
+import 'assign-gingerly/object-extension.js';
+
+/**
+ * Registers be-intl's config, so it can be attached programmatically
+ * via el.enh.set.beIntl / el.enh.get(emc).
+ * @param {Element | undefined} ref element whose customElementRegistry to register against
+ */
+export async function defBeIntl(ref){
+    const {default: emc} = await import('./emc.json', {with: {type: 'json'}});
+    return await push(ref, emc);
+}
+
+async function push(ref, emc){
+    const {BeIntl} = await import('./be-intl.js');
+    const {enhConfig} = emc;
+    enhConfig.spawn = BeIntl;
+    enhConfig.customData = emc.customData; // the registry only stores enhConfig, not the full emc
+    const registry = (ref?.customElementRegistry ?? customElements).enhancementRegistry;
+    registry.push(enhConfig);
+    return enhConfig;
+}

package/emc.json

@@ -1,6 +1,6 @@
 {
     "enhConfig": {
-        "enhKey": "BeIntl",
+        "enhKey": "beIntl",
         "spawn": "be-intl/be-intl.js",
         "withAttrs": {
             "base": "be-intl",
@@ -49,6 +49,12 @@
                 "ifKeyIn": [
                     "locale",
                     "format",
+                    "style",
+                    "currency",
+                    "weekday",
+                    "year",
+                    "month",
+                    "day",
                     "initialized"
                 ]
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "be-intl",
-  "version": "0.0.51",
+  "version": "0.0.52",
   "keywords": [
     "web-components",
     "web-component",
@@ -14,6 +14,7 @@
     ".": "./be-intl.js",
     "./be-intl.js": "./be-intl.js",
     "./🌐.js": "./🌐.js",
+    "./def.js": "./def.js",
     "./emc.json": "./emc.json",
     "./🌐.json": "./🌐.json"
   },
@@ -31,14 +32,14 @@
     "update": "ncu -u && npm install"
   },
   "dependencies": {
-    "assign-gingerly": "0.0.93",
+    "assign-gingerly": "0.0.97",
     "be-hive": "0.1.18",
     "mount-observer": "0.1.53",
-    "roundabout-lib": "0.0.36"
+    "roundabout-lib": "0.0.38"
   },
   "devDependencies": {
     "spa-ssi": "0.0.28",
-    "@playwright/test": "1.62.1"
+    "@playwright/test": "1.63.0"
   },
   "author": "anderson.bruce.b@gmail.com",
   "license": "MIT"

package//360/237/214/220.json

@@ -49,6 +49,12 @@
                 "ifKeyIn": [
                     "locale",
                     "format",
+                    "style",
+                    "currency",
+                    "weekday",
+                    "year",
+                    "month",
+                    "day",
                     "initialized"
                 ]
             },