@fusion.dev/helix-core 0.171.0 → 0.173.0

package/custom-elements.json

@@ -983,12 +983,83 @@
               "readonly": true,
               "default": "options"
             },
+            {
+              "kind": "field",
+              "name": "invokers",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new Set<Element>()",
+              "description": "The invokers this host tells whether it is open: each one that sent an\nopening command, unless it carried `aria-expanded` of its own before then."
+            },
+            {
+              "kind": "field",
+              "name": "theirs",
+              "privacy": "private",
+              "readonly": true,
+              "default": "new WeakSet<Element>()",
+              "description": "Invokers that carried `aria-expanded` before a command, which stay the consumer's."
+            },
             {
               "kind": "field",
               "name": "handle",
               "privacy": "private",
               "readonly": true
             },
+            {
+              "kind": "method",
+              "name": "note",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "source",
+                  "type": {
+                    "text": "Element | null"
+                  }
+                }
+              ],
+              "description": "Takes the invoker on as one to tell, for a host that opens.\n\n**The platform says it for a native popover and not for this.** Chromium\nexposes a `popovertarget` button, or one with `command=\"toggle-popover\"`,\nas expanded or collapsed, and a custom command reaches a custom element\nwith nothing said. Measured before this: a `command=\"--toggle\"` button\nopened a Popover and its node had no expanded state. React Aria's trigger\nsays `aria-expanded` on every overlay it opens.\n\nFrom the first command on, so nothing is written onto markup a server\nsent until a reader presses. A plain invoker is also pointed at the host\nthrough `ariaControlsElements`, which writes no attribute."
+            },
+            {
+              "kind": "method",
+              "name": "tell",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "description": "Writes the host's state on each invoker it tells, forgetting one that has left."
+            },
+            {
+              "kind": "method",
+              "name": "write",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "invoker",
+                  "type": {
+                    "text": "Element"
+                  }
+                },
+                {
+                  "name": "open",
+                  "type": {
+                    "text": "boolean"
+                  }
+                }
+              ],
+              "description": "Says `open` on one invoker: a Helix control through its `expanded`\nproperty, which its own button carries and which puts nothing in the\nmarkup, and a plain element through `aria-expanded`."
+            },
             {
               "kind": "method",
               "name": "hostConnected",
@@ -998,6 +1069,15 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "hostUpdated",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
+            },
             {
               "kind": "method",
               "name": "hostDisconnected",
@@ -2675,6 +2755,25 @@
                 }
               }
             },
+            {
+              "kind": "method",
+              "name": "span",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "Pick<DOMRect, 'bottom' | 'height' | 'left' | 'right' | 'top' | 'width'>"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "active",
+                  "type": {
+                    "text": "HTMLElement"
+                  }
+                }
+              ],
+              "description": "The box from `active` through the element `through` names, or `active`'s own."
+            },
             {
               "kind": "method",
               "name": "stopWaiting",
@@ -3923,7 +4022,7 @@
               },
               "privacy": "private",
               "readonly": true,
-              "default": "new FloatingController(host, { anchor: options.anchor, ...(options.arrow === undefined ? {} : { arrow: options.arrow }), floating: options.surface, ...(options.offset === undefined ? {} : { offset: options.offset }), ...(options.onPlace === undefined ? {} : { onPlace: options.onPlace }), ...(options.placement === undefined ? {} : { placement: options.placement }), ...(options.within === undefined ? {} : { within: options.within }), })"
+              "default": "new FloatingController(host, { anchor: options.anchor, ...(options.arrow === undefined ? {} : { arrow: options.arrow }), floating: options.surface, ...(options.offset === undefined ? {} : { offset: options.offset }), ...(options.crossOffset === undefined ? {} : { crossOffset: options.crossOffset }), ...(options.flip === undefined ? {} : { flip: options.flip }), ...(options.padding === undefined ? {} : { padding: options.padding }), ...(options.onPlace === undefined ? {} : { onPlace: options.onPlace }), ...(options.placement === undefined ? {} : { placement: options.placement }), ...(options.within === undefined ? {} : { within: options.within }), })"
             },
             {
               "kind": "field",
@@ -21133,7 +21232,7 @@
                   "text": "TemplateResult | typeof nothing"
                 }
               },
-              "description": "The `feedback` line, or nothing while there is none."
+              "description": "The `feedback` line, or nothing while there is none.\n\n`role=\"alert\"`, as a field's feedback line has, so the message is\nannounced when it appears and the label and hint are not read with it."
             }
           ],
           "attributes": [
@@ -33711,7 +33810,7 @@
           "type": {
             "text": "string"
           },
-          "default": "'0.171.0'",
+          "default": "'0.173.0'",
           "description": "The version of the package this file ships in.\n\n**Written by `fusion/scripts/version.mjs`** wherever it writes the package's\n`package.json`, and stamped back into the repository beside it after a\nrelease, so the two never disagree; a spec beside this holds them to it.\nNothing else in the running code knows which release it is."
         }
       ],
@@ -34271,6 +34370,6 @@
   ],
   "helix": {
     "package": "@fusion.dev/helix-core",
-    "version": "0.171.0"
+    "version": "0.173.0"
   }
 }

package/dist/controllers/command-controller/command-controller.d.ts

@@ -40,6 +40,12 @@ export declare class HelixFallbackCommandEvent extends Event {
 export interface CommandOptions {
     /** Each command the host implements, keyed by the name a trigger writes. */
     commands: Record<string, (source: Element | null) => void>;
+    /**
+     * Whether the host is open, for a host a command opens and closes. Given,
+     * each invoker that has sent `--show` or `--toggle` says so with
+     * `aria-expanded`.
+     */
+    expanded?: () => boolean;
 }
 /**
  * Lets a control elsewhere on the page operate this one, declaratively.
@@ -75,7 +81,38 @@ export declare class CommandController implements ReactiveController {
     private readonly host;
     private readonly options;
     constructor(host: ReactiveControllerHost & HTMLElement, options: CommandOptions);
+    /**
+     * The invokers this host tells whether it is open: each one that sent an
+     * opening command, unless it carried `aria-expanded` of its own before then.
+     */
+    private readonly invokers;
+    /** Invokers that carried `aria-expanded` before a command, which stay the consumer's. */
+    private readonly theirs;
     private readonly handle;
+    /**
+     * Takes the invoker on as one to tell, for a host that opens.
+     *
+     * **The platform says it for a native popover and not for this.** Chromium
+     * exposes a `popovertarget` button, or one with `command="toggle-popover"`,
+     * as expanded or collapsed, and a custom command reaches a custom element
+     * with nothing said. Measured before this: a `command="--toggle"` button
+     * opened a Popover and its node had no expanded state. React Aria's trigger
+     * says `aria-expanded` on every overlay it opens.
+     *
+     * From the first command on, so nothing is written onto markup a server
+     * sent until a reader presses. A plain invoker is also pointed at the host
+     * through `ariaControlsElements`, which writes no attribute.
+     */
+    private note;
+    /** Writes the host's state on each invoker it tells, forgetting one that has left. */
+    private tell;
+    /**
+     * Says `open` on one invoker: a Helix control through its `expanded`
+     * property, which its own button carries and which puts nothing in the
+     * markup, and a plain element through `aria-expanded`.
+     */
+    private write;
     hostConnected(): void;
+    hostUpdated(): void;
     hostDisconnected(): void;
 }

package/dist/controllers/command-controller/command-controller.js

@@ -6,24 +6,78 @@ export class HelixFallbackCommandEvent extends Event {
         this.source = source;
     }
 }
+const OPENING = new Set(['--show', '--toggle']);
 export class CommandController {
     constructor(host, options) {
+        this.invokers = new Set();
+        this.theirs = new WeakSet();
         this.handle = (event) => {
             const command = event.command;
             const run = this.options.commands[command];
             if (!run) {
                 return;
             }
-            run(event.source);
+            const source = event.source;
+            if (OPENING.has(command)) {
+                this.note(source);
+            }
+            run(source);
         };
         this.host = host;
         this.options = options;
         host.addController(this);
     }
+    note(source) {
+        if (!this.options.expanded || !source || this.invokers.has(source) || this.theirs.has(source)) {
+            return;
+        }
+        if (source.hasAttribute('aria-expanded')) {
+            this.theirs.add(source);
+            return;
+        }
+        this.invokers.add(source);
+        if (!source.localName.includes('-') && 'ariaControlsElements' in source) {
+            ;
+            source.ariaControlsElements = [
+                this.host,
+            ];
+        }
+        this.tell();
+    }
+    tell() {
+        const expanded = this.options.expanded;
+        if (!expanded) {
+            return;
+        }
+        const open = expanded();
+        for (const invoker of this.invokers) {
+            if (invoker.isConnected) {
+                this.write(invoker, open);
+            }
+            else {
+                this.invokers.delete(invoker);
+            }
+        }
+    }
+    write(invoker, open) {
+        if (invoker.localName.includes('-')) {
+            ;
+            invoker.expanded = open;
+        }
+        else if (invoker.getAttribute('aria-expanded') !== String(open)) {
+            invoker.setAttribute('aria-expanded', String(open));
+        }
+    }
     hostConnected() {
         this.host.addEventListener('command', this.handle);
     }
+    hostUpdated() {
+        this.tell();
+    }
     hostDisconnected() {
         this.host.removeEventListener('command', this.handle);
+        for (const invoker of this.invokers) {
+            this.write(invoker, false);
+        }
     }
 }

package/dist/controllers/floating-controller/floating-controller.d.ts

@@ -25,6 +25,13 @@ export type Placement = 'bottom' | 'bottom-end' | 'bottom-start' | 'left' | 'lef
 export interface FloatingOptions {
     /** The element being pointed at. */
     anchor: () => HTMLElement | null | undefined;
+    /**
+     * How far to slide the floating element along the side it is placed on, in
+     * pixels: rightward on the top or the bottom, downward on the left or the
+     * right, and toward the end of the line where the placement names `-end`.
+     * Floating UI's `crossAxis` offset, React Aria's `crossOffset`.
+     */
+    crossOffset?: number | (() => number);
     /**
      * An element to point at the anchor, positioned against whichever side the
      * floating element landed on.
@@ -32,13 +39,20 @@ export interface FloatingOptions {
     arrow?: () => HTMLElement | null | undefined;
     /** The element being placed. */
     floating: () => HTMLElement | null | undefined;
+    /**
+     * How close to the window's edges the floating element may come, in
+     * pixels, when it slides or is capped to fit, and, where it is given, when
+     * it flips. Defaults to 8 for the first two and none for flipping. React
+     * Aria's `containerPadding`, Radix's `collisionPadding`.
+     */
+    padding?: number | (() => number | undefined);
     /**
      * Whether to try another side when the preferred one does not fit.
      *
      * On by default. A menu that opens off the bottom of the window is one the
      * reader cannot use.
      */
-    flip?: boolean;
+    flip?: boolean | (() => boolean);
     /**
      * Told the placement the element landed on, after every measurement, and
      * how wide the window leaves it room to be.

package/dist/controllers/floating-controller/floating-controller.js

@@ -37,17 +37,24 @@ export class FloatingController {
             const preferred = typeof this.options.placement === 'function'
                 ? this.options.placement()
                 : this.options.placement;
-            const middleware = [offset(gap ?? 0)];
+            const cross = typeof this.options.crossOffset === 'function'
+                ? this.options.crossOffset()
+                : (this.options.crossOffset ?? 0);
+            const asked = typeof this.options.padding === 'function' ? this.options.padding() : this.options.padding;
+            const margin = asked ?? 8;
+            const edge = asked === undefined ? {} : { padding: asked };
+            const middleware = [offset({ crossAxis: cross, mainAxis: gap ?? 0 })];
             let room;
-            if (this.options.flip !== false) {
+            const flips = typeof this.options.flip === 'function' ? this.options.flip() : this.options.flip;
+            if (flips !== false) {
                 const side = (preferred ?? 'bottom-start').split('-')[0];
                 middleware.push(flip(side === 'left' || side === 'right'
-                    ? { crossAxis: 'alignment', fallbackAxisSideDirection: 'end' }
-                    : {}));
+                    ? { crossAxis: 'alignment', fallbackAxisSideDirection: 'end', ...edge }
+                    : edge));
             }
             if (this.options.shift !== false) {
                 const inside = this.options.within?.();
-                middleware.push(shift({ padding: 8, ...(inside ? { boundary: inside } : {}) }));
+                middleware.push(shift({ padding: margin, ...(inside ? { boundary: inside } : {}) }));
             }
             if (this.options.resize !== false) {
                 middleware.push(size({
@@ -56,7 +63,7 @@ export class FloatingController {
                         elements.floating.style.setProperty('--floating-available-block-size', `${Math.round(availableHeight)}px`);
                         elements.floating.style.setProperty('--floating-anchor-inline-size', `${matchedInlineSize(rects.reference.width, availableWidth)}px`);
                     },
-                    padding: 8,
+                    padding: margin,
                 }));
             }
             if (pointer) {

package/dist/controllers/indicator-controller/indicator-controller.d.ts

@@ -21,6 +21,12 @@ export interface IndicatorOptions {
      * re-read costs nothing and needs no bookkeeping about who is watched.
      */
     observe?: () => readonly Element[];
+    /**
+     * The last element marked, where the mark runs from `active` through several,
+     * as an outline marking every section on screen. The mark then covers both
+     * and everything between. Absent, or the same element, it covers `active`.
+     */
+    through?: () => HTMLElement | null | undefined;
     /**
      * The box the mark is positioned against, which is its containing block.
      *
@@ -96,6 +102,8 @@ export declare class IndicatorController implements ReactiveController {
      */
     private waiting;
     place(): void;
+    /** The box from `active` through the element `through` names, or `active`'s own. */
+    private span;
     /** Takes the pending listener and its guard off, wherever they came from. */
     private stopWaiting;
 }

package/dist/controllers/indicator-controller/indicator-controller.js

@@ -35,7 +35,7 @@ export class IndicatorController {
             indicator.removeAttribute('data-placed');
             return;
         }
-        const box = active.getBoundingClientRect();
+        const box = this.span(active);
         const own = surface.getBoundingClientRect();
         if (box.width === 0 && box.height === 0) {
             return;
@@ -69,6 +69,19 @@ export class IndicatorController {
         this.waiting = { on: indicator, settle };
         this.settling = setTimeout(settle, 1000);
     }
+    span(active) {
+        const first = active.getBoundingClientRect();
+        const end = this.options.through?.();
+        if (!end || end === active) {
+            return first;
+        }
+        const last = end.getBoundingClientRect();
+        const top = Math.min(first.top, last.top);
+        const bottom = Math.max(first.bottom, last.bottom);
+        const left = Math.min(first.left, last.left);
+        const right = Math.max(first.right, last.right);
+        return { bottom, height: bottom - top, left, right, top, width: right - left };
+    }
     stopWaiting() {
         clearTimeout(this.settling);
         this.settling = undefined;

package/dist/controllers/popover-controller/popover-controller.d.ts

@@ -21,6 +21,12 @@ export interface PopoverOptions {
     boundary?: () => Element | readonly (Element | null | undefined)[] | null | undefined;
     /** Space between the anchor and the surface, in pixels. */
     offset?: number | (() => number);
+    /** Whether the surface may move to the other side to fit. On by default. See `FloatingController`. */
+    flip?: boolean | (() => boolean);
+    /** How far to slide the surface along its side, in pixels. See `FloatingController`. */
+    crossOffset?: number | (() => number);
+    /** How close to the window's edges the surface may come, in pixels. See `FloatingController`. */
+    padding?: number | (() => number | undefined);
     /**
      * A box to keep the surface inside, instead of the viewport.
      *

package/dist/controllers/popover-controller/popover-controller.js

@@ -10,6 +10,9 @@ export class PopoverController {
             ...(options.arrow === undefined ? {} : { arrow: options.arrow }),
             floating: options.surface,
             ...(options.offset === undefined ? {} : { offset: options.offset }),
+            ...(options.crossOffset === undefined ? {} : { crossOffset: options.crossOffset }),
+            ...(options.flip === undefined ? {} : { flip: options.flip }),
+            ...(options.padding === undefined ? {} : { padding: options.padding }),
             ...(options.onPlace === undefined ? {} : { onPlace: options.onPlace }),
             ...(options.placement === undefined ? {} : { placement: options.placement }),
             ...(options.within === undefined ? {} : { within: options.within }),

package/dist/mixins/mixin-picker-feedback/mixin-picker-feedback.js

@@ -57,7 +57,7 @@ export const MixinPickerFeedback = (Base) => {
         renderPickerFeedback() {
             return this.feedback === ''
                 ? nothing
-                : html `<p part="feedback" id="feedback">${this.feedback}</p>`;
+                : html `<p part="feedback" id="feedback" role="alert">${this.feedback}</p>`;
         }
     }
     __decorate([

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.171.0";
+export declare const VERSION = "0.173.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.171.0';
+export const VERSION = '0.173.0';

package/package.json

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