@fusion.dev/helix-core 0.109.2 → 0.110.0

package/custom-elements.json

@@ -8362,6 +8362,15 @@
               ],
               "description": "The same words for a screen reader, in a region that is always there.\n\nRendered by the component outside its rows, where a status is allowed."
             },
+            {
+              "kind": "field",
+              "name": "announced",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "description": "News the component has for the live region while there are rows and nothing is loading."
+            },
             {
               "kind": "method",
               "name": "countRows",
@@ -8535,6 +8544,16 @@
                 }
               ],
               "description": "The same words for a screen reader, in a region that is always there.\n\n**A region is heard when what it holds changes, not when it arrives.**\nThe loading line was a `role=\"status\"` inserted with its words already\nin it, which is read inconsistently at best, and the empty line was no\nregion at all, so a filter that emptied a list said nothing. This one is\nrendered on every pass and only its words move: \"Loading\", then\n\"No matches\", then nothing once there are rows.\n\n**Outside the rows, which is the component's to place.** A status is not\na child a `listbox`, a `table` or a `tree` may hold, so the component\nrenders this beside its container rather than inside it. The styled\ntier clips it; the visible lines are `renderStatus`."
+            },
+            {
+              "kind": "field",
+              "name": "announced",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "protected",
+              "default": "''",
+              "description": "What the region says while there are rows and nothing is loading, which\nis nothing unless the component has news of its own.\n\n**One region, so two messages never talk over each other.** Data Table\nsays a sort and a selection here; a second `role=\"status\"` beside this\none would be heard in whichever order the reader happens to queue them.\nLoading and empty win, being the larger news. Set before the render that\nshows it, in `willUpdate`, and not reactive: it changes only when\nsomething else already asked for a render."
             }
           ],
           "attributes": [
@@ -9640,6 +9659,15 @@
               "readonly": true,
               "description": "Id of the description node, for `aria-describedby` on the control.\n\n`undefined` when there is nothing to point at, so the attribute is absent\nrather than pointing at an id that renders nothing."
             },
+            {
+              "kind": "field",
+              "name": "invalidity",
+              "type": {
+                "text": "'true' | undefined"
+              },
+              "readonly": true,
+              "description": "`'true'` for `aria-invalid` on the control while a message is shown, and\n`undefined` otherwise, so the attribute is absent."
+            },
             {
               "kind": "field",
               "name": "feedback",
@@ -11566,6 +11594,25 @@
               ],
               "description": "What one pan control is called, for a family that draws its own."
             },
+            {
+              "kind": "method",
+              "name": "sideOf",
+              "privacy": "protected",
+              "return": {
+                "type": {
+                  "text": "string"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "way",
+                  "type": {
+                    "text": "ViewportWay"
+                  }
+                }
+              ],
+              "description": "The side of the screen a reading-order way is on: `up`, `down`, `left` or `right`."
+            },
             {
               "kind": "method",
               "name": "panGlyph",
@@ -11902,7 +11949,7 @@
             {
               "kind": "method",
               "name": "sideOf",
-              "privacy": "private",
+              "privacy": "protected",
               "return": {
                 "type": {
                   "text": "string"
@@ -13830,9 +13877,16 @@
               "type": {
                 "text": "boolean"
               }
+            },
+            {
+              "name": "popup",
+              "optional": true,
+              "type": {
+                "text": "'dialog' | 'grid' | 'listbox' | 'menu' | 'tree'"
+              }
             }
           ],
-          "description": "Tells a slotted trigger that it opens something, and whether it is open.\n\n**Writing `aria-expanded` onto the consumer's element is a hydration\nmismatch, so it is not written.** The gap that answer was reaching for is\nreal: a consumer who has to mirror `open` back onto their own trigger is a\nconsumer who will forget, and the failure is silent to everyone who can see\nthe screen. It is still the wrong answer, because a component decorating a\nconsumer's markup after upgrading is one whose output a React consumer's\nhydration disagrees with.\n\n**Measured 28 Aug 2026 against React 19.2.8.** Four\nfamilies were server-rendered as React emits them and hydrated with the\nelement definitions loaded either side of `hydrateRoot`:\n\n```\ncase        writes to trigger   hydration mismatch\nmegamenu    aria-expanded       yes, both load orders\nspeed dial  aria-expanded       yes, both load orders\npopover     nothing             no\nmenu        nothing             no\n```\n\nReact reports \"some attributes of the server rendered HTML didn't match the\nclient properties. This won't be patched up\", and the cost is not the console\nline: it answers a mismatch by discarding the server's HTML for that subtree\nand rebuilding it, which is what the carousel's own note records blinding an\n`<helix-aura>` two sections away.\n\n**A property crosses the gap that an attribute cannot.** React diffs the\nattributes it rendered and never looks at a property, so the state reaches\nthe trigger, lands as `aria-expanded` inside *that element's* shadow root,\nand the consumer's markup is exactly what they served. Both positions get\nwhat they were protecting: nothing is written onto the consumer's element,\nand the reader is still told what the control does.\n\n**Set before upgrade is safe**, which is what lets this run without waiting\nfor a definition: `ReactiveElement` captures an instance property assigned\nbefore it upgrades and re-applies it, so a trigger whose module has not\nloaded yet still ends up with the value.\n\n**A plain element is warned about rather than written to.** A\n`<button slot=\"trigger\">` has no shadow root to keep the state out of the\nmarkup and no property to take it, and a consumer cannot mirror it themselves\nbecause the open state belongs to the component. Saying so once is the same\nanswer `Tooltip` gives about the link it will not write for them, and not at\nall to a trigger that already carries `aria-expanded`, which is a consumer\nmirroring the state from the component's `toggle` event."
+          "description": "Tells a slotted trigger that it opens something, whether it is open, and,\nwhere `popup` names it, what kind of thing it opens.\n\n**Writing `aria-expanded` onto the consumer's element is a hydration\nmismatch, so it is not written.** The gap that answer was reaching for is\nreal: a consumer who has to mirror `open` back onto their own trigger is a\nconsumer who will forget, and the failure is silent to everyone who can see\nthe screen. It is still the wrong answer, because a component decorating a\nconsumer's markup after upgrading is one whose output a React consumer's\nhydration disagrees with.\n\n**Measured 28 Aug 2026 against React 19.2.8.** Four\nfamilies were server-rendered as React emits them and hydrated with the\nelement definitions loaded either side of `hydrateRoot`:\n\n```\ncase        writes to trigger   hydration mismatch\nmegamenu    aria-expanded       yes, both load orders\nspeed dial  aria-expanded       yes, both load orders\npopover     nothing             no\nmenu        nothing             no\n```\n\nReact reports \"some attributes of the server rendered HTML didn't match the\nclient properties. This won't be patched up\", and the cost is not the console\nline: it answers a mismatch by discarding the server's HTML for that subtree\nand rebuilding it, which is what the carousel's own note records blinding an\n`<helix-aura>` two sections away.\n\n**A property crosses the gap that an attribute cannot.** React diffs the\nattributes it rendered and never looks at a property, so the state reaches\nthe trigger, lands as `aria-expanded` inside *that element's* shadow root,\nand the consumer's markup is exactly what they served. Both positions get\nwhat they were protecting: nothing is written onto the consumer's element,\nand the reader is still told what the control does.\n\n**Set before upgrade is safe**, which is what lets this run without waiting\nfor a definition: `ReactiveElement` captures an instance property assigned\nbefore it upgrades and re-applies it, so a trigger whose module has not\nloaded yet still ends up with the value.\n\n**A plain element is warned about rather than written to.** A\n`<button slot=\"trigger\">` has no shadow root to keep the state out of the\nmarkup and no property to take it, and a consumer cannot mirror it themselves\nbecause the open state belongs to the component. Saying so once is the same\nanswer `Tooltip` gives about the link it will not write for them, and not at\nall to a trigger that already carries `aria-expanded`, which is a consumer\nmirroring the state from the component's `toggle` event."
         }
       ],
       "exports": [

package/dist/mixins/mixin-collection/mixin-collection.d.ts

@@ -25,6 +25,8 @@ export declare class CollectionElement {
      * Rendered by the component outside its rows, where a status is allowed.
      */
     protected renderLive(hasContent: boolean): TemplateResult;
+    /** News the component has for the live region while there are rows and nothing is loading. */
+    protected announced: string;
     /** Binds to a rows slot's `slotchange`, and answers `hasRows` from it. */
     protected countRows(event: Event): void;
     /** What the rows slot is given, read from the host so a first render has it. */

package/dist/mixins/mixin-collection/mixin-collection.js

@@ -15,6 +15,7 @@ export const MixinCollection = (Base) => {
             this.loadingText = 'Loading';
             this.slotCounted = false;
             this.slotRows = 0;
+            this.announced = '';
         }
         countRows(event) {
             this.slotCounted = true;
@@ -51,7 +52,7 @@ export const MixinCollection = (Base) => {
             return html `<p part="empty">${this.emptyText}</p>`;
         }
         renderLive(hasContent) {
-            const said = this.loading ? this.loadingText : hasContent ? '' : this.emptyText;
+            const said = this.loading ? this.loadingText : hasContent ? this.announced : this.emptyText;
             return html `<span part="live" role="status">${said}</span>`;
         }
     }

package/dist/mixins/mixin-field/mixin-field.d.ts

@@ -33,6 +33,11 @@ export declare class MixinFieldInterface {
      * rather than pointing at an id that renders nothing.
      */
     readonly describedBy: string | undefined;
+    /**
+     * `'true'` for `aria-invalid` on the control while a message is shown, and
+     * `undefined` otherwise, so the attribute is absent.
+     */
+    readonly invalidity: 'true' | undefined;
     /**
      * The validation message shown under the control. It replaces the browser's
      * message.

package/dist/mixins/mixin-field/mixin-field.js

@@ -44,6 +44,9 @@ export const MixinField = (Base) => {
             }
             return this.hint === '' ? undefined : HINT_ID;
         }
+        get invalidity() {
+            return this.resolvedFeedback === '' ? undefined : 'true';
+        }
         renderGroupLabel() {
             const hidden = this.label === '' ? this.getAttribute('aria-label') : null;
             if (this.label === '' && !hidden) {

package/dist/mixins/mixin-viewport/mixin-viewport.d.ts

@@ -71,6 +71,8 @@ export declare class ViewportElement {
     protected handleMoreKeys(event: KeyboardEvent): boolean;
     /** What one pan control is called, for a family that draws its own. */
     protected panLabel(way: ViewportWay): string;
+    /** The side of the screen a reading-order way is on: `up`, `down`, `left` or `right`. */
+    protected sideOf(way: ViewportWay): string;
     /** The arrow drawn on one pan control, for a family that draws its own. */
     protected panGlyph(way: ViewportWay): string;
 }

package/dist/utils/tell-disclosure/tell-disclosure.d.ts

@@ -1,5 +1,6 @@
 /**
- * Tells a slotted trigger that it opens something, and whether it is open.
+ * Tells a slotted trigger that it opens something, whether it is open, and,
+ * where `popup` names it, what kind of thing it opens.
  *
  * **Writing `aria-expanded` onto the consumer's element is a hydration
  * mismatch, so it is not written.** The gap that answer was reaching for is
@@ -47,4 +48,4 @@
  * all to a trigger that already carries `aria-expanded`, which is a consumer
  * mirroring the state from the component's `toggle` event.
  */
-export declare const tellDisclosure: (trigger: Element | null | undefined, open: boolean) => void;
+export declare const tellDisclosure: (trigger: Element | null | undefined, open: boolean, popup?: 'dialog' | 'grid' | 'listbox' | 'menu' | 'tree') => void;

package/dist/utils/tell-disclosure/tell-disclosure.js

@@ -1,11 +1,15 @@
 const warned = new WeakSet();
-export const tellDisclosure = (trigger, open) => {
+export const tellDisclosure = (trigger, open, popup) => {
     if (!trigger) {
         return;
     }
     if (trigger.localName.includes('-')) {
         ;
         trigger.expanded = open;
+        if (popup) {
+            ;
+            trigger.popup = popup;
+        }
         return;
     }
     if (warned.has(trigger) || trigger.hasAttribute('aria-expanded')) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.109.2",
+  "version": "0.110.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -34,11 +34,11 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.109.2"
+    "@fusion.dev/helix-icons": "0.110.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.109.2",
-    "@fusion.dev/helix-testing": "0.109.2",
+    "@fusion.dev/helix-cem": "0.110.0",
+    "@fusion.dev/helix-testing": "0.110.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },