@fusion.dev/helix-headless 0.145.0 → 0.147.0

package/dist/toast/root/toast-root.js

@@ -4,15 +4,19 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, deepActiveElement, deepContains, FocusScopeController, fillTemplate, focusableElements, HelixElement, hostAria, scrollHolders, } from '@fusion.dev/helix-core';
+import { customElement, DelayController, deepActiveElement, deepContains, FocusScopeController, fillTemplate, focusableElements, HelixElement, hostAria, scrollHolders, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
-import { property } from 'lit/decorators.js';
+import { property, state } from 'lit/decorators.js';
 import { matchesHotkey, parseHotkey } from '../hotkey.js';
+import { messageWords } from '../words.js';
 let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
     constructor() {
         super(...arguments);
         this.hotkey = 'F8';
         this.label = 'Notifications ({hotkey})';
+        this.said = '';
+        this.urgent = '';
+        this.hush = new DelayController(this, { renders: false });
         this.scope = new FocusScopeController(this, {
             contents: () => this.showing.flatMap((one) => {
                 const target = focusTarget(one);
@@ -85,14 +89,59 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
             label: fillTemplate(this.label, { hotkey: this.hotkey }),
             role: 'region',
         });
-        this.internals.ariaLive = 'polite';
-        this.internals.ariaRelevant = 'additions';
-        this.internals.ariaAtomic = 'false';
+    }
+    announce(arrived) {
+        const urgent = arrived.filter(isDanger).map(messageWords).join(' ');
+        const said = arrived
+            .filter((one) => !isDanger(one))
+            .map(messageWords)
+            .join(' ');
+        if (said.trim() === '' && urgent.trim() === '') {
+            return;
+        }
+        this.said = '';
+        this.urgent = '';
+        const fill = () => {
+            this.said = said;
+            this.urgent = urgent;
+            this.hush.start(1000, () => {
+                this.said = '';
+                this.urgent = '';
+            });
+        };
+        if (typeof requestAnimationFrame === 'function') {
+            requestAnimationFrame(fill);
+        }
+        else {
+            fill();
+        }
+    }
+    tell(added) {
+        const showing = this.showing;
+        const arrived = added.filter((one) => one instanceof HTMLElement && showing.includes(one));
+        if (arrived.length === 0) {
+            return;
+        }
+        if (this.blocked()) {
+            this.notify(arrived);
+        }
+        else {
+            this.announce(arrived);
+        }
     }
     add(message, options = {}) {
         const tier = this.constructor.tier;
         const item = document.createElement(`${tier}toast-item`);
-        item.textContent = message;
+        if (options.heading === undefined) {
+            item.textContent = message;
+        }
+        else {
+            item.append(slotted('heading', options.heading), slotted('description', message));
+        }
+        if (options.action) {
+            options.action.setAttribute('slot', 'actions');
+            item.append(options.action);
+        }
         if (options.tone) {
             item.setAttribute('tone', options.tone);
         }
@@ -143,9 +192,6 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
         if (!open || blocked) {
             region.showPopover();
         }
-        if (blocked) {
-            this.notify(arrived);
-        }
     }
     lowerWhenStill(region) {
         const running = typeof this.getAnimations === 'function' ? this.getAnimations({ subtree: true }) : [];
@@ -173,9 +219,9 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
             return;
         }
         for (const one of arrived) {
-            const words = (one.textContent ?? '').replace(/\s+/gu, ' ').trim();
+            const words = messageWords(one);
             if (words !== '') {
-                speaker.ariaNotify(words);
+                speaker.ariaNotify(words, { priority: isDanger(one) ? 'high' : 'normal' });
             }
         }
     }
@@ -185,7 +231,9 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
         this.addEventListener('helix-dismiss', this.handleDismiss);
         document.addEventListener('keydown', this.handleHotkey);
         this.watcher = new MutationObserver((records) => {
-            this.place(records.flatMap((record) => [...record.addedNodes]));
+            const added = records.flatMap((record) => [...record.addedNodes]);
+            this.place(added);
+            this.tell(added);
             this.sweep();
         });
         this.watcher.observe(this, {
@@ -211,7 +259,7 @@ let HelixHeadlessToast = class HelixHeadlessToast extends HelixElement {
         this.place();
     }
     render() {
-        return html `<div part="region" popover="manual" tabindex="-1"><slot></slot></div>`;
+        return html `<div part="region" popover="manual" tabindex="-1"><slot></slot><span part="live" role="status">${this.said}</span><span part="live" role="alert">${this.urgent}</span></div>`;
     }
 };
 __decorate([
@@ -223,10 +271,17 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessToast.prototype, "placement", void 0);
+__decorate([
+    state()
+], HelixHeadlessToast.prototype, "said", void 0);
+__decorate([
+    state()
+], HelixHeadlessToast.prototype, "urgent", void 0);
 HelixHeadlessToast = __decorate([
     customElement('helix-headless-toast')
 ], HelixHeadlessToast);
 export { HelixHeadlessToast };
+const isDanger = (item) => (item.tone ?? item.getAttribute('tone')) === 'danger';
 const popoverOpen = (region) => {
     try {
         return region.matches(':popover-open');
@@ -238,3 +293,9 @@ const popoverOpen = (region) => {
 const focusTarget = (item) => item.shadowRoot?.querySelector('[part="dismiss"]') ??
     focusableElements(item)[0] ??
     null;
+const slotted = (slot, words) => {
+    const element = document.createElement('div');
+    element.slot = slot;
+    element.textContent = words;
+    return element;
+};

package/dist/toast/words.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pieces of a message joined into one line a screen reader says, with a full
+ * stop between two where the first does not already end a sentence, so a
+ * heading and its detail are heard as two sentences and not run together.
+ */
+export declare const joinSaid: (pieces: readonly string[]) => string;
+/**
+ * What a message says as it arrives: the word for its tone, then its heading,
+ * its description and its text, and never its actions or its dismiss control,
+ * which a reader finds by moving into the message.
+ */
+export declare const messageWords: (item: Element) => string;

package/dist/toast/words.js

@@ -0,0 +1,25 @@
+import { toneMark } from '@fusion.dev/helix-core';
+const UNSAID = new Set(['actions', 'dismiss-icon', 'icon']);
+export const joinSaid = (pieces) => pieces
+    .map((piece) => piece.replace(/\s+/gu, ' ').trim())
+    .filter((piece) => piece !== '')
+    .reduce((line, piece) => line === '' ? piece : `${line}${/[.!?:;]$/u.test(line) ? '' : '.'} ${piece}`, '');
+export const messageWords = (item) => {
+    const tone = item.tone ?? item.getAttribute('tone') ?? undefined;
+    const label = toneMark(tone)?.label;
+    const heading = [];
+    const rest = [];
+    for (const node of item.childNodes) {
+        if (node instanceof Element) {
+            const slot = node.getAttribute('slot') ?? '';
+            if (!UNSAID.has(slot)) {
+                ;
+                (slot === 'heading' ? heading : rest).push(node.textContent ?? '');
+            }
+        }
+        else if (node.nodeType === 3) {
+            rest.push(node.textContent ?? '');
+        }
+    }
+    return joinSaid([...(label ? [label] : []), ...heading, ...rest]);
+};

package/dist/toggle/group/toggle-group.d.ts

@@ -18,13 +18,33 @@ declare const HelixHeadlessToggleGroup_base: (new (...args: any[]) => import("@f
  * say whether they are pressed with `aria-pressed`, as React Aria's
  * ToggleButtonGroup and Radix's ToggleGroup do. A press presses or releases
  * one item, the arrow keys move focus without pressing, and `value` is the
- * pressed values, comma separated, which `values` also gives as a list. The
- * form receives one entry per pressed value. The indicator stays hidden, and
- * each pressed item is marked with `:state(pressed)`.
+ * pressed values, comma separated, which `values` also gives as a list. Use
+ * `values` where an item's value holds a comma. The form receives one entry
+ * per pressed value, and a page the browser brings back presses the same
+ * items again. The indicator stays hidden, and each pressed item is marked
+ * with `:state(pressed)`. Inside a toolbar it is a named group of that
+ * toolbar's controls instead, so a reader meets one toolbar.
  *
  * `orientation="vertical"` runs the items down a column, says so to the
  * accessibility tree, and the up and down arrows move between them.
  *
+ * **Keyboard.** The group is one tab stop: the chosen item, or the first that
+ * can be chosen, as in a radio group, and in a multiple group the item focus
+ * was last on.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Right, Down | Moves to the next item, from the last back to the first. In a single group, chooses it. |
+ * | Left, Up | Moves to the item before, from the first round to the last. In a single group, chooses it. |
+ * | Home, End | Moves to the first or the last item. In a single group, chooses it. |
+ * | Space, Enter | Chooses the focused item, or presses or releases it in a multiple group. |
+ *
+ * Left and Right swap on a right-to-left page, and a disabled item is passed
+ * over. A single group is a `radiogroup` of items with `role="radio"` and
+ * `aria-checked`. A multiple group is a `toolbar` of buttons with
+ * `aria-pressed`, or a `group` inside a toolbar. The group is named by
+ * `label` and carries `aria-orientation` under `orientation`.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases SegmentedControl, Segmented, Navigation, Switcher
@@ -112,6 +132,11 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
     /** The item focus was last on, in a toolbar, which holds its tab stop. */
     private lastFocused;
     private readonly noteFocus;
+    /**
+     * The item whose value is the group's, in a single group: the exact match,
+     * so nothing chosen marks nothing. A multiple group has none.
+     */
+    private get chosenItem();
     /** Whether several items can be pressed at once. */
     private get multiple();
     /**
@@ -178,12 +203,17 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
     disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    protected willUpdate(changed: PropertyValues): void;
     /**
-     * What the form receives: the value, or under `selection-mode="multiple"`
-     * one entry per pressed value, as a native `<select multiple>` sends.
+     * The group's role: a radio group, a toolbar of pressed buttons, or, for
+     * pressed buttons inside a toolbar, a group.
+     *
+     * **A toolbar inside a toolbar is a reader's dead end**, so inside one the
+     * pressed buttons are a named group of the outer toolbar, as React Aria's
+     * ToggleButtonGroup demotes itself. Read by tag and by role, since the
+     * outer toolbar is a Helix one or the page's own `role="toolbar"`.
      */
-    private formValue;
+    private get groupRole();
+    protected willUpdate(changed: PropertyValues): void;
     /**
      * The verdict on the answer `required` asks for.
      *
@@ -203,6 +233,14 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
      */
     get values(): string[];
     set values(next: string[]);
+    /** The pressed values as a list last written, which `values` reads. */
+    private chosen;
+    /**
+     * Presses the items a page the browser brings back held. Under
+     * `selection-mode="multiple"` the saved state is the form's entries, one per
+     * pressed value, which the shared restore leaves alone.
+     */
+    formStateRestoreCallback(state: string | File | FormData | null): void;
     /**
      * The row the track sits in, so something can sit beside it.
      *
@@ -217,6 +255,13 @@ export declare class HelixHeadlessToggleGroup extends HelixHeadlessToggleGroup_b
      * in it.
      */
     protected render(): TemplateResult;
+    /**
+     * Items that arrive after the first render, which is every item on a page
+     * the parser is still reading. Outside an update here, so taking the
+     * declaration schedules one rather than warning, and the update reports the
+     * form, which a removed answer no longer holds.
+     */
+    private readonly handleItems;
 }
 declare global {
     interface HTMLElementTagNameMap {

package/dist/toggle/group/toggle-group.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { commaList, customElement, DisabledCascadeController, HelixFormElement, hostAria, IndicatorController, KeyboardNavigationController, MixinControllerValue, MixinField, rovingStop, toggleValue, } from '@fusion.dev/helix-core';
+import { commaList, customElement, DisabledCascadeController, HelixFormElement, hostAria, IndicatorController, KeyboardNavigationController, MixinControllerValue, MixinField, reportValues, rovingStop, toggleValue, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessToggle } from '../root/toggle-root.js';
@@ -13,15 +13,15 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
         super(...arguments);
         this.lastFocused = undefined;
         this.noteFocus = (event) => {
-            const item = this.items.find((one) => one === event.target);
-            if (this.multiple && item && item !== this.lastFocused) {
+            const item = event.target;
+            if (this.multiple && item !== this.lastFocused && this.items.includes(item)) {
                 this.lastFocused = item;
                 this.sync();
             }
         };
         this.focusable = true;
         this.indicator = new IndicatorController(this, {
-            active: () => this.multiple ? undefined : this.items.find((item) => item.value === this.value),
+            active: () => this.chosenItem,
             indicator: () => this.partNamed('indicator'),
             observe: () => this.items,
             surface: () => this.partNamed('track'),
@@ -39,11 +39,25 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
                     return;
                 }
                 const value = event.detail.value;
-                this.requestValue(this.multiple
-                    ? toggleValue(this.values, value, this.items.map((item) => item.value)).join(',')
-                    : value);
+                if (!this.multiple) {
+                    this.requestValue(value);
+                    return;
+                }
+                const next = toggleValue(this.values, value, this.items.map((item) => item.value));
+                const was = this.chosen;
+                this.chosen = next;
+                if (!this.requestValue(next.join(','))) {
+                    this.chosen = was;
+                }
             });
         };
+        this.chosen = undefined;
+        this.handleItems = () => {
+            this.adopt();
+            this.sync();
+            this.indicator.place();
+            this.requestUpdate();
+        };
     }
     adopt() {
         if (this.value !== '' || this.children === undefined) {
@@ -55,7 +69,7 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
         }
     }
     sync() {
-        const active = this.multiple ? undefined : this.items.find((item) => item.value === this.value);
+        const active = this.chosenItem;
         const pressed = new Set(this.values);
         const entry = this.focusable ? this.entry() : undefined;
         for (const item of this.items) {
@@ -72,9 +86,12 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
                 selected: (item) => item.pressed === true,
             });
         }
-        const active = items.find((item) => item.value === this.value);
+        const active = this.chosenItem;
         return active && !active.disabled ? active : items.find((item) => !item.disabled);
     }
+    get chosenItem() {
+        return this.multiple ? undefined : this.items.find((item) => item.value === this.value);
+    }
     get multiple() {
         return this.selectionMode === 'multiple';
     }
@@ -90,14 +107,12 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
         if (this.value === '') {
             return false;
         }
-        if (this.multiple) {
-            return this.children === undefined || this.values.length > 0;
-        }
         if (this.children === undefined) {
             return true;
         }
-        const items = this.items;
-        return items.length === 0 || items.some((item) => item.value === this.value);
+        return this.multiple
+            ? this.values.length > 0
+            : this.items.length === 0 || this.chosenItem !== undefined;
     }
     connectedCallback() {
         super.connectedCallback();
@@ -120,56 +135,55 @@ let HelixHeadlessToggleGroup = class HelixHeadlessToggleGroup extends MixinContr
         this.validate();
         this.linkHost();
     }
+    get groupRole() {
+        if (!this.multiple) {
+            return 'radiogroup';
+        }
+        return this.parentElement?.closest('[role=toolbar],helix-toolbar,helix-headless-toolbar')
+            ? 'group'
+            : 'toolbar';
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         this.adopt();
-        hostAria(this.internals, { label: this.label, role: this.multiple ? 'toolbar' : 'radiogroup' });
+        hostAria(this.internals, { label: this.label, role: this.groupRole });
         this.internals.ariaOrientation = this.orientation ?? null;
-        this.internals.setFormValue(this.formValue());
-    }
-    formValue() {
         if (!this.answered) {
-            return null;
+            this.internals.setFormValue(null);
         }
-        if (!this.multiple || this.name === '') {
-            return this.value;
+        else if (this.multiple) {
+            reportValues(this.internals, this.name, this.values);
         }
-        const data = new FormData();
-        for (const value of this.values) {
-            data.append(this.name, value);
+        else {
+            this.internals.setFormValue(this.value);
         }
-        return data;
     }
     validate() {
         this.reportRequired(!this.answered, 'Choose one to continue.', 'track');
     }
     get values() {
-        return this.multiple ? commaList(this.value) : this.value === '' ? [] : [this.value];
+        if (!this.multiple) {
+            return this.value === '' ? [] : [this.value];
+        }
+        return this.chosen && this.chosen.join(',') === this.value
+            ? [...this.chosen]
+            : commaList(this.value);
     }
     set values(next) {
+        this.chosen = [...next];
         this.value = next.join(',');
     }
+    formStateRestoreCallback(state) {
+        if (!(state instanceof FormData) || !this.multiple) {
+            super.formStateRestoreCallback(state);
+            return;
+        }
+        this.values = state.getAll(this.name);
+    }
     render() {
         const inside = this.labelPlacement === 'start';
         const label = this.renderGroupLabel();
-        return html `${inside ? nothing : label}
-      <div part="row">
-        <slot name="start"></slot>
-        <div part="track">
-        ${inside ? label : nothing}
-        <div part="indicator" aria-hidden="true"></div>
-        <slot
-          @slotchange=${() => {
-            this.adopt();
-            this.sync();
-            this.indicator.place();
-            this.requestUpdate();
-        }}
-          ></slot>
-        </div>
-        <slot name="end"></slot>
-      </div>
-      ${this.renderHint()}${this.renderFeedback()}`;
+        return html `${inside ? nothing : label}<div part="row"><slot name="start"></slot><div part="track">${inside ? label : nothing}<div part="indicator" aria-hidden="true"></div><slot @slotchange=${this.handleItems}></slot></div><slot name="end"></slot></div>${this.renderHint()}${this.renderFeedback()}`;
     }
 };
 __decorate([

package/dist/toggle/root/toggle-root.js

@@ -31,14 +31,12 @@ let HelixHeadlessToggle = class HelixHeadlessToggle extends MixinSelectableItem(
       part="item"
       type="button"
       role=${this.pressed === undefined ? 'radio' : nothing}
-      aria-checked=${this.pressed === undefined ? (this.selected ? 'true' : 'false') : nothing}
+      aria-checked=${this.pressed === undefined ? String(this.selected) : nothing}
       aria-pressed=${this.pressed === undefined ? nothing : String(this.pressed)}
       ?disabled=${this.disabled}
       tabindex=${(this.focusable ?? this.selected) || !this.childrenKnown ? '0' : '-1'}
       @click=${() => this.select()}
-    >
-      <slot></slot>
-    </button>`;
+    ><slot></slot></button>`;
     }
 };
 __decorate([

package/dist/toolbar/root/toolbar-root.d.ts

@@ -20,11 +20,20 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * The arrows wrap from the last control to the first. Set `stop-at-ends` to
  * keep them at the ends, as Radix's `loop` set to false does.
  *
- * A nested composite, such as a toggle group, is one stop on the toolbar's
- * axis: the toolbar's arrows move past it, and the arrows across the toolbar
- * move inside it. A composite with a `focusable` property, as Toggle Group
- * has, gives up its own tab stop while the toolbar's is elsewhere, so Tab
- * stops once in the toolbar. A composite without one keeps its own tab stop.
+ * A toggle group of pressed buttons, `selection-mode="multiple"`, is walked
+ * through the same way, each toggle a stop on the toolbar's axis, as React
+ * Aria's toolbar walks its toggle buttons. Another nested composite, such as a
+ * radio-style toggle group, is one stop on the toolbar's axis: the toolbar's
+ * arrows move past it, and the arrows across the toolbar move inside it. A
+ * composite with a `focusable` property, as Toggle Group has, gives up its own
+ * tab stop while the toolbar's is elsewhere, so Tab stops once in the
+ * toolbar. A composite without one keeps its own tab stop.
+ *
+ * A toolbar inside another toolbar, a Helix one or the page's own
+ * `role="toolbar"`, is a `group` of the outer one, as React Aria's is: the
+ * outer toolbar's arrows walk through its controls and on past them, and it
+ * takes no keys and no tab stop of its own. A server renders it as a toolbar,
+ * having no parent to read, until it upgrades.
  *
  * @since 0.1.0
  * @status stable
@@ -123,6 +132,13 @@ export declare class HelixHeadlessToolbar extends HelixElement {
      * the stop hands it to the first one left.
      */
     private readonly restoreTabStop;
+    /**
+     * Whether this toolbar sits inside another, which then owns the keys and the
+     * tab stop: a toolbar inside a toolbar held the reader's arrows inside it.
+     * Read when it renders and when it connects, there being no parent on a
+     * server.
+     */
+    private get nested();
     /**
      * The orientation in force.
      *