@fusion.dev/helix-headless 0.215.3 → 0.216.0

package/dist/menu/root/menu-root.js

@@ -1,5 +1,5 @@
 import { __decorate } from "tslib";
-import { AriaForwardController, anchorElement, auditEntry, customElement, DrilldownController, deepActiveElement, deepContains, focusTarget, HelixElement, inlineStep, KeyboardNavigationController, linkDescription, MIRROR_RULE, MixinCollection, MixinControllerOpen, numberConverter, OpenPhaseController, onUnlessFalse, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, anchorElement, auditEntry, customElement, DrilldownController, deepActiveElement, deepContains, elementById, focusTarget, HelixElement, inlineStep, KeyboardNavigationController, linkDescription, MIRROR_RULE, MixinCollection, MixinControllerOpen, numberConverter, OpenPhaseController, onUnlessFalse, PopoverController, scrollItemIntoView, sideOf, slottedWords, tellDisclosure, typeaheadBy, unlinkDescription, words, } from '@fusion.dev/helix-core';
 import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -32,6 +32,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.filter = '';
         this.filterable = false;
         this.filterLabel = 'Filter';
+        this.for = '';
         this.label = '';
         this.longPressLabel = 'Long press or press Alt+Down to show the menu';
         this.noResultsText = 'No matches';
@@ -54,6 +55,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.placement = 'bottom-start';
         this.resultsLabel = '{count, plural, one {# result} other {# results}}';
         this.submenus = 'drill';
+        this.targets = '';
         this.drilldown = new DrilldownController(this, {
             isRow: (element) => 'isMenuItem' in element && element.isMenuItem === true,
             root: () => [...this.children]
@@ -80,9 +82,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             target: () => this.menuBox,
         });
         this.panel = new PopoverController(this, {
-            anchor: () => this.context && this.point
-                ? this.renderRoot?.querySelector('#point')
-                : this.trigger,
+            anchor: () => this.point ? this.renderRoot?.querySelector('#point') : this.trigger,
             boundary: () => this,
             offset: () => this.offset,
             onDismiss: () => this.hide(),
@@ -129,21 +129,25 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 this.trigger.focus();
             }
         };
+        this.contextTarget = undefined;
         this.handleContextMenu = (event) => {
             if (!this.context) {
                 return;
             }
-            const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
-            const areas = slot?.assignedElements({ flatten: true }) ?? [];
-            if (!event.composedPath().some((node) => areas.includes(node))) {
+            const keyed = event.clientX === 0 && event.clientY === 0;
+            if (event.shiftKey && !keyed) {
+                return;
+            }
+            const target = this.targetOf(event);
+            if (!target) {
                 return;
             }
             event.preventDefault();
             if (this.open && this.longPress.takeClick()) {
                 return;
             }
-            const box = this.trigger.getBoundingClientRect();
-            const keyed = event.clientX === 0 && event.clientY === 0;
+            this.contextTarget = target;
+            const box = target.getBoundingClientRect();
             this.openContextAt(keyed ? { x: box.left, y: box.top } : { x: event.clientX, y: event.clientY });
         };
         this.handleSelect = (event) => {
@@ -221,10 +225,14 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             }
         };
         this.handlePointerDown = (event) => {
-            if (this.open || !this.fromTrigger(event)) {
+            if (this.open) {
                 return;
             }
-            if (this.pressHeld || (this.context && event.pointerType !== 'mouse')) {
+            const held = this.context && event.pointerType !== 'mouse' ? this.targetOf(event) : undefined;
+            if (held) {
+                this.contextTarget = held;
+            }
+            if ((this.pressHeld && this.fromTrigger(event)) || held) {
                 this.heldAt = { x: event.clientX, y: event.clientY };
                 this.longPress.down(event);
             }
@@ -308,6 +316,11 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 until: Date.now() + GRACE,
             };
         };
+        this.handleAreaKeydown = (event) => {
+            if (!this.open) {
+                this.handleClosedKeydown(event);
+            }
+        };
         this.namedByPage = false;
     }
     static { this.markRules = [MIRROR_RULE]; }
@@ -431,11 +444,32 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.reach(undefined);
         if (deepContains(this, deepActiveElement())) {
             ;
-            (this.context ? (this.returnTo ?? this.trigger) : this.trigger).focus();
+            (this.returnTo ?? this.trigger).focus();
         }
         this.point = undefined;
         this.returnTo = undefined;
     }
+    showAt(point, target) {
+        this.contextTarget = target;
+        this.openContextAt(point);
+    }
+    get contextAreas() {
+        const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
+        const named = this.isConnected && this.for !== '' ? elementById(this, this.for) : null;
+        return [...(slot?.assignedElements({ flatten: true }) ?? []), ...(named ? [named] : [])];
+    }
+    targetOf(event) {
+        const path = event.composedPath().filter((node) => node instanceof Element);
+        const areas = this.contextAreas;
+        const area = path.find((node) => areas.includes(node));
+        if (!area) {
+            return undefined;
+        }
+        if (this.targets === '') {
+            return area;
+        }
+        return path.slice(0, path.indexOf(area) + 1).find((node) => node.matches(this.targets));
+    }
     openContextAt(point) {
         this.point = point;
         if (this.open) {
@@ -512,9 +546,11 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         scrollItemIntoView(item, { padding: 4, ...(surface ? { scroller: surface } : {}) });
     }
     handleClosedKeydown(event) {
-        if (this.context && event.shiftKey && event.key === 'F10' && this.fromTrigger(event)) {
+        const asked = this.context && event.shiftKey && event.key === 'F10' ? this.targetOf(event) : undefined;
+        if (asked) {
             event.preventDefault();
-            const box = this.trigger.getBoundingClientRect();
+            this.contextTarget = asked;
+            const box = asked.getBoundingClientRect();
             this.openContextAt({ x: box.left, y: box.top });
             return;
         }
@@ -574,6 +610,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.rowWatch = new MutationObserver(this.followRemoved);
         this.rowWatch.observe(this, { childList: true, subtree: true });
         void this.whenSettled.then(() => {
+            this.watchArea();
             this.settledOnce = true;
             if (!this.context) {
                 this.tellTrigger();
@@ -595,6 +632,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         this.removeEventListener('pointercancel', this.handlePointerCancel);
         this.removeEventListener('click', this.handleHeldClick, true);
         this.removeEventListener('focusin', this.handleTriggerFocusIn);
+        this.unwatchArea();
         this.rowWatch?.disconnect();
         this.rowWatch = undefined;
         if (this.described) {
@@ -602,8 +640,41 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             this.described = undefined;
         }
     }
+    watchArea() {
+        const area = this.context && this.isConnected && this.for !== '' ? elementById(this, this.for) : null;
+        if (area === this.watched) {
+            return;
+        }
+        this.unwatchArea();
+        if (!area) {
+            return;
+        }
+        area.addEventListener('contextmenu', this.handleContextMenu);
+        area.addEventListener('pointerdown', this.handlePointerDown);
+        area.addEventListener('pointermove', this.handlePointerMove);
+        area.addEventListener('pointerup', this.handlePointerUp);
+        area.addEventListener('pointercancel', this.handlePointerCancel);
+        area.addEventListener('keydown', this.handleAreaKeydown);
+        this.watched = area;
+    }
+    unwatchArea() {
+        const area = this.watched;
+        if (!area) {
+            return;
+        }
+        area.removeEventListener('contextmenu', this.handleContextMenu);
+        area.removeEventListener('pointerdown', this.handlePointerDown);
+        area.removeEventListener('pointermove', this.handlePointerMove);
+        area.removeEventListener('pointerup', this.handlePointerUp);
+        area.removeEventListener('pointercancel', this.handlePointerCancel);
+        area.removeEventListener('keydown', this.handleAreaKeydown);
+        this.watched = undefined;
+    }
     updated(changed) {
         super.updated(changed);
+        if (changed.has('for') || changed.has('context')) {
+            this.watchArea();
+        }
         if (changed.has('open') && this.open) {
             this.toldChecked = this.checkedValues.join('\u0000');
         }
@@ -699,7 +770,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         }
     }
     render() {
-        const point = this.context && this.point;
+        const point = this.point;
         const filters = this.filters;
         this.announced = '';
         const none = filters?.status();
@@ -768,6 +839,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessMenu.prototype, "filterMatch", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenu.prototype, "for", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "label", void 0);
@@ -795,6 +869,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessMenu.prototype, "submenus", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenu.prototype, "targets", void 0);
 HelixHeadlessMenu = __decorate([
     customElement('helix-headless-menu')
 ], HelixHeadlessMenu);

package/dist/pagination/size/pagination-size.d.ts

@@ -65,6 +65,9 @@ import '../../select/index.js';
  * @csspart control-listbox-loading - The text shown while the options load.
  * @csspart control-listbox-search - The region that holds the filter field.
  * @csspart control-listbox-search-field - The filter field.
+ * @csspart control-listbox-voice - The dictation button in the filter field.
+ * @csspart control-listbox-voice-listening - The dictation button while it listens.
+ * @csspart control-listbox-voice-status - What a screen reader hears as dictation starts and stops.
  * @csspart control-live - The select's `live` part, the region a screen reader hears a choice made on the closed trigger from.
  * @csspart control-surface - The floating panel.
  * @csspart control-trigger - The closed control, which shows the chosen size.

package/dist/pagination/size/pagination-size.js

@@ -94,7 +94,8 @@ let HelixHeadlessPaginationSize = class HelixHeadlessPaginationSize extends Heli
         listbox-filter-mark: control-listbox-filter-mark, listbox-hint: control-listbox-hint,
         listbox-items: control-listbox-items, listbox-label: control-listbox-label,
         listbox-live: control-listbox-live, listbox-loading: control-listbox-loading, listbox-search: control-listbox-search,
-        listbox-search-field: control-listbox-search-field, live: control-live, surface: control-surface,
+        listbox-search-field: control-listbox-search-field, listbox-voice: control-listbox-voice,
+        listbox-voice-listening: control-listbox-voice-listening, listbox-voice-status: control-listbox-voice-status, live: control-live, surface: control-surface,
         trigger: control-trigger, value: control-value"
       label=${named ? '' : this.label}
       aria-label=${named || nothing}

package/dist/scatter-chart/root/scatter-chart-root.d.ts

@@ -122,6 +122,7 @@ declare const HelixHeadlessScatterChart_base: typeof HelixElement & (new (...arg
  * @csspart point-active - The point of the row the reading rests on, one for each series with a point in that row, drawn over the others as an element of its own and placed by `--chart-point-x` and `--chart-point-y`. Under `size-by`, it carries its size as `--chart-point-weight`.
  * @csspart point-ring - The points of a `point` path again, under it, to stroke a little wider in the page's color, so each point keeps its edge where it overlaps another.
  * @csspart points - The points of one series that do not overlap one another, as a group of their `point-ring` and `point` paths. Its opacity is each point's, so where points overlap they darken. Carries its series color as `--chart-series`.
+ * @csspart sonify - The button that plays the chart as sound, under `sonify`.
  * @csspart summary - The text that says how strongly the measures relate, for people who cannot see the points.
  * @csspart svg - The drawing surface the gridlines and the trend lines sit on.
  * @csspart table - The readings as a table, for a screen reader, rendered only where they were drawn from `data`, a page of them at a time past a few hundred. Hide it visually.

package/dist/scatter-chart/root/scatter-chart-root.js

@@ -269,7 +269,7 @@ let HelixHeadlessScatterChart = class HelixHeadlessScatterChart extends MixinCha
         <span aria-hidden="true" dir="auto" part="x-name">${field.xName}</span>
         <span aria-hidden="true" dir="auto" part="y-name">${field.yNames.join(', ')}</span>
       </div>
-      ${this.renderSummary(field)}${this.renderTable()}`;
+      ${this.renderSummary(field)}${this.renderSonify()}${this.renderTable()}`;
     }
     renderPlot(field, along, up) {
         const at = this.pointer.at;

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, type DataOptionItem, HelixFormElement, PopoverController, UpgradeController } from '@fusion.dev/helix-core';
+import { AriaForwardController, type DataOptionItem, HelixFormElement, ListedController, PopoverController, UpgradeController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import type { HelixHeadlessOption } from '../../option/root/option-root.js';
 import '../../listbox/index.js';
@@ -111,6 +111,9 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * @csspart listbox-loading - The text shown while the options load.
  * @csspart listbox-search - The region that holds the filter field.
  * @csspart listbox-search-field - The filter field.
+ * @csspart listbox-voice - The dictation button in the filter field.
+ * @csspart listbox-voice-listening - The dictation button while it listens.
+ * @csspart listbox-voice-status - What a screen reader hears as dictation starts and stops.
  * @csspart live - The region a screen reader announces a choice made on the closed trigger from, drawn once there is one to say. Visually hidden in the styled tier.
  * @csspart surface - The floating panel.
  * @csspart trigger - The closed control, which shows the chosen value.
@@ -125,6 +128,8 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * @cssstate placed-top - While the open list sits above the trigger, where there was no room below.
  */
 export declare class HelixHeadlessSelect extends HelixHeadlessSelect_base {
+    /** On the page's list of controls, where a command palette and a shortcut overlay find it. */
+    protected readonly listed: ListedController;
     /**
      * The key this family's words are registered under, its styled tag:
      * `registerWords('de', { 'helix-select': { placeholder: 'Auswählen' } })`.

package/dist/select/root/select-root.js

@@ -1,5 +1,5 @@
 import { __decorate } from "tslib";
-import { AriaForwardController, afterLinkFollowed, auditChildren, chosenValues, customElement, dataOptions, drawAutofill, drawStatus, HelixFormElement, hostAria, hostWords, inlineStep, isRtl, labelsOf, MixinControllerOpen, MixinControllerValue, MixinField, onApple, PopoverController, reportValues, StatusController, sideOf, typesCharacter, UpgradeController, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { AriaForwardController, afterLinkFollowed, auditChildren, chosenValues, customElement, dataOptions, drawAutofill, drawStatus, HelixFormElement, hostAria, hostWords, inlineStep, isRtl, ListedController, labelsOf, MixinControllerOpen, MixinControllerValue, MixinField, onApple, PopoverController, reportValues, StatusController, sideOf, typesCharacter, UpgradeController, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { caretDown } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -11,6 +11,7 @@ import { over } from '../align.js';
 let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(MixinControllerValue(MixinField(HelixFormElement))) {
     constructor() {
         super(...arguments);
+        this.listed = new ListedController(this, 'focus', () => this.internals?.ariaKeyShortcuts);
         this.aria = new AriaForwardController(this, {
             labelledByAfter: () => {
                 const value = this.partNamed('value');
@@ -322,7 +323,8 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
       exportparts="empty: listbox-empty, error: listbox-error, feedback: listbox-feedback,
         filter-icon: listbox-filter-icon, filter-mark: listbox-filter-mark, hint: listbox-hint,
         items: listbox-items, label: listbox-label, live: listbox-live, loading: listbox-loading,
-        search: listbox-search, search-field: listbox-search-field"
+        search: listbox-search, search-field: listbox-search-field,
+        voice: listbox-voice, voice-listening: listbox-voice-listening, voice-status: listbox-voice-status"
       .value=${this.value}
       ?multiple=${this.multiple}
       ?filterable=${this.filterable}

package/dist/shortcut-overlay/index.d.ts

@@ -0,0 +1 @@
+export * from './root/shortcut-overlay-root.js';

package/dist/shortcut-overlay/index.js

@@ -0,0 +1 @@
+export * from './root/shortcut-overlay-root.js';

package/dist/shortcut-overlay/root/shortcut-overlay-root.d.ts

@@ -0,0 +1,128 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type CSSResultGroup, type PropertyValues, type TemplateResult } from 'lit';
+import '../../dialog/index.js';
+/** A key a reader holds to see the badges. */
+type HoldKey = 'alt' | 'ctrl' | 'mod' | 'shift';
+/**
+ * @summary Shows every control's shortcut and what it does while a key is held.
+ *
+ * @description
+ * Place one in the app. Hold the platform's modifier, Command on an Apple
+ * keyboard and Control elsewhere, for `delay` and a badge appears beside each
+ * control on screen that has a shortcut, with its keys and its name. Release
+ * the key and the badges go. Pressing any other key during the hold cancels
+ * it, so a reader pressing ⌘K never sees them.
+ *
+ * What a badge says comes from what the controls already carry: the
+ * `aria-keyshortcuts` a Kbd's `for` writes onto its control, a Menu Item's
+ * `shortcut`, and the hotkeys Command and Toast register. A control's name is
+ * its label. A shortcut with no control on screen, such as a palette's ⌘K, is
+ * listed in the sheet.
+ *
+ * Press `?` outside a text field, or call `showSheet()`, to open the sheet: a
+ * dialog listing every shortcut on the page by name, which is how a keyboard
+ * or screen reader user gets the same list. Set `sheet-keys` to another chord,
+ * or to nothing to leave `?` to the page.
+ *
+ * Many apps, GitHub and Gmail among them, already give `?` to their own help,
+ * so a page that answers `?` itself opens both on one press. Such a page sets
+ * `sheet-keys` to another chord, or to nothing and calls `showSheet()` from
+ * its own handler.
+ *
+ * The badges are a picture of what the controls already expose, so they are
+ * hidden from assistive technology.
+ *
+ * @since 0.216.0
+ * @status experimental
+ * @category navigation
+ * @aliases Keyboard shortcuts, Shortcut hints, Key tips, Cheat sheet
+ * @documentation https://fusion.dev/helix/components/shortcut-overlay
+ *
+ * @csspart badge - One control's badge.
+ * @csspart badge-keys - A badge's keys.
+ * @csspart badge-name - A badge's name for the control.
+ * @csspart badges - The layer the badges are drawn in.
+ * @csspart empty - What the sheet says when the page has no shortcuts.
+ * @csspart keys - A row's keys.
+ * @csspart list - The sheet's list.
+ * @csspart name - A row's name for what the shortcut does.
+ * @csspart row - One shortcut in the sheet.
+ * @csspart sheet - The dialog listing every shortcut.
+ * @csspart sheet-body - The dialog's `body` part.
+ * @csspart sheet-dismiss - The dialog's `dismiss` part.
+ * @csspart sheet-dismiss-mark - The dialog's `dismiss-mark` part.
+ * @csspart sheet-footer - The dialog's `footer` part.
+ * @csspart sheet-header - The dialog's `header` part.
+ * @csspart sheet-surface - The dialog's `surface` part.
+ *
+ * @cssstate showing - While the badges are drawn.
+ */
+export declare class HelixHeadlessShortcutOverlay extends HelixElement {
+    static styles: CSSResultGroup;
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-shortcut-overlay': { label: 'Tastenkürzel' } })`.
+     */
+    static words: string;
+    /** How long the key is held before the badges show, in milliseconds or as `0.6s`. */
+    delay: number;
+    /** What the sheet says when the page has no shortcuts. */
+    emptyLabel: string;
+    /**
+     * The key a reader holds: `mod` (Command on an Apple keyboard, Control
+     * elsewhere), `alt`, `ctrl`, or `shift`.
+     */
+    hold: HoldKey;
+    /** The sheet's name and heading. */
+    label: string;
+    /**
+     * The chord that opens the sheet, `?` by default, which a press in a text
+     * field never answers. Empty leaves the key to the page, which wants it
+     * where the page already answers `?` itself.
+     */
+    sheetKeys: string;
+    /** The badges drawn while the key is held. */
+    private badges;
+    /** Whether the sheet is open. */
+    private sheetOpen;
+    /** The sheet's rows, read when it opens. */
+    private rows;
+    private timer;
+    /** Whether the badges are showing. */
+    get showing(): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Draws a badge beside every control on screen that has a shortcut. */
+    show(): void;
+    /** Takes the badges away. */
+    hide(): void;
+    /** Opens the sheet listing every shortcut on the page. */
+    showSheet(): void;
+    /** Closes the sheet. */
+    hideSheet(): void;
+    /** Every shortcut on the page, the controls' first and then the page's own, each once. */
+    private sheetRows;
+    private readonly cancel;
+    private readonly handleKeydown;
+    private readonly handleKeyup;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Places each badge centered under its control, a few pixels below its
+     * bottom edge so it hides none of the control's words, on whole pixels
+     * and inside the viewport, where it overlaps no badge placed before it.
+     *
+     * **A badge that would overlap a neighbor drops its name**, keeping the
+     * keys, which is what a reader holding the key is looking for; one that
+     * still overlaps moves down a row. Controls side by side in a toolbar are
+     * narrower than a key and a name together, and badges drawn over each other
+     * read as neither.
+     */
+    private arrange;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-shortcut-overlay': HelixHeadlessShortcutOverlay;
+    }
+}
+export {};