be-intl 0.0.50 → 0.0.52

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:
@@ -69,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

@@ -32,7 +32,9 @@ class BeIntl {
      * @param {PAP} initVals
      */
     async init(self, enhancedElement, ctx, initVals){
-        const {customData} = /** @type {EMC<any, AllProps, Element, RAConfig<AllProps, Actions>>} */ (ctx.emc);
+        // 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}
          */
@@ -56,9 +58,6 @@ class BeIntl {
      */
     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`.
@@ -111,6 +110,7 @@ class BeIntl {
 
     /**
      * @param {AP} self
+     * @returns {PAP | void}
      */
     formatNumber(self){
         const {enhancedElement, value, intlNumberFormat} = self;
@@ -119,15 +119,37 @@ class BeIntl {
             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');
+        }
     }
 }
 
@@ -141,7 +163,7 @@ class BeIntl {
  */
 async function infer(from){
     return /** @type {any} */ (
-        from.enh.get((await import('inferencer/inferencer.js')).registryItem)
+        from.enh.get((await import('assign-gingerly/inferencer/inferencer.js')).registryItem)
     );
 }
 

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",
@@ -18,6 +18,10 @@
             "observeLang": "${base}-observe-lang",
             "_observeLang": {
                 "instanceOf": "Boolean"
+            },
+            "announce": "${base}-announce",
+            "_announce": {
+                "instanceOf": "Boolean"
             }
         }
     },
@@ -45,6 +49,12 @@
                 "ifKeyIn": [
                     "locale",
                     "format",
+                    "style",
+                    "currency",
+                    "weekday",
+                    "year",
+                    "month",
+                    "day",
                     "initialized"
                 ]
             },
@@ -65,6 +75,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.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,15 +32,14 @@
     "update": "ncu -u && npm install"
   },
   "dependencies": {
-    "assign-gingerly": "0.0.93",
+    "assign-gingerly": "0.0.97",
     "be-hive": "0.1.18",
-    "inferencer": "0.0.13",
     "mount-observer": "0.1.53",
-    "roundabout-lib": "0.0.36"
+    "roundabout-lib": "0.0.38"
   },
   "devDependencies": {
-    "spa-ssi": "0.0.27",
-    "@playwright/test": "1.62.1"
+    "spa-ssi": "0.0.28",
+    "@playwright/test": "1.63.0"
   },
   "author": "anderson.bruce.b@gmail.com",
   "license": "MIT"

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

@@ -18,6 +18,10 @@
             "observeLang": "${base}-observe-lang",
             "_observeLang": {
                 "instanceOf": "Boolean"
+            },
+            "announce": "${base}-announce",
+            "_announce": {
+                "instanceOf": "Boolean"
             }
         }
     },
@@ -45,6 +49,12 @@
                 "ifKeyIn": [
                     "locale",
                     "format",
+                    "style",
+                    "currency",
+                    "weekday",
+                    "year",
+                    "month",
+                    "day",
                     "initialized"
                 ]
             },
@@ -65,6 +75,15 @@
                     "value",
                     "intlDateFormat"
                 ]
+            },
+            "armLiveRegion": {
+                "ifAllOf": [
+                    "announce",
+                    "rendered"
+                ],
+                "ifKeyIn": [
+                    "rendered"
+                ]
             }
         }
     }