be-intl 0.0.50 → 0.0.51

package/README.md

@@ -60,6 +60,34 @@ Changing the formatted element's **own** `lang` after it has been enhanced re-fo
 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

@@ -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 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
-     */
-    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

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "be-intl",
-  "version": "0.0.50",
+  "version": "0.0.51",
   "keywords": [
     "web-components",
     "web-component",
@@ -33,12 +33,11 @@
   "dependencies": {
     "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

@@ -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"
+                ]
             }
         }
     }