npm - be-intl - Versions diffs - 0.0.49 → 0.0.51 - Mend

be-intl 0.0.49 → 0.0.51

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -36,6 +36,58 @@ We can also employ more semantic syntax:
 <data value=123456.789 lang="de-DE" be-intl-style=currency be-intl-currency=EUR></data>
 ```
+## Locale resolution
+The examples above put `lang` right on the formatted element, but that isn't required.
+`be-intl` uses the element's **effective language**, resolved the same way the browser's
+`:lang()` selector works:
+1. the nearest ancestor with a `lang` (or `xml:lang`) attribute — crossing shadow-root
+   boundaries via the host element;
+2. otherwise `<html lang>`;
+3. otherwise the browser's own `navigator.language`.
+So in practice you set `lang` once, high up:
+```html
+<html lang="de-DE">
+  ...
+  <data value=123456.789 be-intl-style=currency be-intl-currency=EUR></data>
+  <!-- emits 123.456,79 € -->
+```
+Changing the formatted element's **own** `lang` after it has been enhanced re-formats it only
+if you opt in with `be-intl-observe-lang` (`🌐-observe-lang`); changes to an ancestor's `lang`
+after enhancement are not tracked.
+## Announcing updates to assistive technology
+`be-intl` writes the formatted string into `textContent` on first render and again whenever the
+bound value or the effective locale changes. By default it leaves ARIA untouched — most
+formatted `<data>` / `<time>` elements are static readouts, and turning every one into a live
+region (especially for a locale switch that only changes *presentation*, not the value) is
+usually just screen-reader noise.
+When a particular value *is* something the user is watching change, opt that element in with
+`be-intl-announce` (`🌐-announce`):
+```html
+<output be-intl be-intl-announce></output>
+<data be-intl be-intl-announce value="0" id="unread"></data>
+```
+With the attribute set, `be-intl` — **after** the element's first render, so the initial value
+isn't spoken on load — marks it as a polite live region:
+- `aria-live="polite"` (skipped for `<output>`, which is already an implicit polite live
+  region), and
+- `aria-atomic="true"`, so multi-token output such as a formatted date is announced as one
+  phrase rather than word-by-word.
+Later re-formats then mutate an already-registered region and are announced. `assertive` is
+intentionally not offered — interrupting the user to read out a reformatted number is almost
+never the right call.
 ## Alternative names
 The semantic example above involves a lot of keyboard tapping of the letters "be-intl".  To avoid blisters on your itty bitty fingers, we provide an alternative base attribute you can use:

package/be-intl.js CHANGED Viewed

@@ -1,148 +1,168 @@
-// @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;
-        if(enhancedElement instanceof HTMLElement){
-            enhancedElement.ariaLive = 'polite';
-        }
-        // 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.
-        if(self.observeLang && enhancedElement instanceof HTMLElement){
-            const langObserver = new MutationObserver(() => {
-                self.locale = enhancedElement.lang || defaultLocale;
-            });
-            langObserver.observe(enhancedElement, {attributes: true, attributeFilter: ['lang']});
-        }
-        const locale = self.locale
-            || (enhancedElement instanceof HTMLElement ? enhancedElement.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
-     */
-    formatNumber(self){
-        const {enhancedElement, value, intlNumberFormat} = self;
-        if(intlNumberFormat === undefined || value === undefined || value === null){
-            enhancedElement.textContent = '';
-            return;
-        }
-        enhancedElement.textContent = intlNumberFormat.format(/** @type {number} */ (value));
-    }
-    /**
-     * @param {AP} self
-     */
-    formatDate(self){
-        const {enhancedElement, value, intlDateFormat} = self;
-        if(intlDateFormat === undefined || value === undefined || value === null) return;
-        enhancedElement.textContent = intlDateFormat.format(/** @type {Date} */ (value));
-    }
-}
-/**
- * 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('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){
+        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 };

package/emc.json CHANGED Viewed

@@ -18,6 +18,10 @@
             "observeLang": "${base}-observe-lang",
             "_observeLang": {
                 "instanceOf": "Boolean"
+            },
+            "announce": "${base}-announce",
+            "_announce": {
+                "instanceOf": "Boolean"
             }
         }
     },
@@ -65,6 +69,15 @@
                     "value",
                     "intlDateFormat"
                 ]
+            },
+            "armLiveRegion": {
+                "ifAllOf": [
+                    "announce",
+                    "rendered"
+                ],
+                "ifKeyIn": [
+                    "rendered"
+                ]
             }
         }
     }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "be-intl",
-  "version": "0.0.49",
+  "version": "0.0.51",
   "keywords": [
     "web-components",
     "web-component",
@@ -31,14 +31,13 @@
     "update": "ncu -u && npm install"
   },
   "dependencies": {
-    "assign-gingerly": "0.0.92",
+    "assign-gingerly": "0.0.93",
     "be-hive": "0.1.18",
-    "inferencer": "0.0.13",
     "mount-observer": "0.1.53",
     "roundabout-lib": "0.0.36"
   },
   "devDependencies": {
-    "spa-ssi": "0.0.27",
+    "spa-ssi": "0.0.28",
     "@playwright/test": "1.62.1"
   },
   "author": "anderson.bruce.b@gmail.com",

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

@@ -18,6 +18,10 @@
             "observeLang": "${base}-observe-lang",
             "_observeLang": {
                 "instanceOf": "Boolean"
+            },
+            "announce": "${base}-announce",
+            "_announce": {
+                "instanceOf": "Boolean"
             }
         }
     },
@@ -65,6 +69,15 @@
                     "value",
                     "intlDateFormat"
                 ]
+            },
+            "armLiveRegion": {
+                "ifAllOf": [
+                    "announce",
+                    "rendered"
+                ],
+                "ifKeyIn": [
+                    "rendered"
+                ]
             }
         }
     }