@fusion.dev/helix-headless 0.215.2 → 0.216.0

package/dist/code-input/index.d.ts

@@ -0,0 +1 @@
+export * from './root/code-input-root.js';

package/dist/code-input/index.js

@@ -0,0 +1 @@
+export * from './root/code-input-root.js';

package/dist/code-input/root/code-input-root.d.ts

@@ -0,0 +1,119 @@
+import { type PropertyValues, type TemplateResult } from 'lit';
+import { type CodeBlockHighlighter, HighlighterController } from '../../code-block/highlighter.js';
+import { HelixHeadlessTextarea } from '../../textarea/root/textarea-root.js';
+/**
+ * @summary A field for a short piece of code, highlighted as it is typed.
+ *
+ * @description
+ * A `Textarea` for code: the same field in a form, with the same label, hint,
+ * validation, `voice` and selection methods, drawing its text in the
+ * highlighter's colors. The reader types in a real `<textarea>`, so the caret,
+ * selection, undo, spellcheck being off and autofill being off are the
+ * platform's, and the field works before any script loads.
+ *
+ * - `language` picks the grammar, such as `json`, `css`, `ts`, `html` or `sh`.
+ * - The field grows with its text from `rows` lines to `max-rows`, and
+ *   scrolls past them.
+ * - Lines keep their length and the field scrolls sideways, unless `wrap` is
+ *   `soft`.
+ *
+ * **The colors are the page's choice.** Helix ships no grammar, so a page
+ * that wants color registers a highlighter once, the one Code Block uses:
+ * `import '@fusion.dev/helix-sandbox/code-block'` registers Helix's own, or
+ * `registerHighlighter` takes Shiki or Prism. Without one the code is drawn
+ * plain, and `highlight` sets one for a single field.
+ *
+ * For a whole file, with line numbers, folding, search and problems listed by
+ * line, use `Code Editor`. Code Input is for a few dozen lines in a form: a
+ * setting in JSON, a style rule, a query, a template.
+ *
+ * **Keyboard.** Tab indents the line, or every line the selection touches,
+ * and Shift+Tab takes the indent away. Enter starts the next line at the same
+ * indent. Escape then Tab leaves the field, so it is never a trap for a reader
+ * without a pointer.
+ *
+ * @since 0.216.0
+ * @status experimental
+ * @category forms
+ * @aliases Code field, Code textarea, JSON input, Syntax highlighted input
+ * @documentation https://fusion.dev/helix/components/code-input
+ *
+ * @slot clear-icon - Replaces the cross on the clear button, under `clearable`.
+ * @slot end - After the code, for an icon or an action beside it.
+ * @slot feedback - The message that says what is wrong, for content richer than a string. It shows while there is a message.
+ * @slot hint - Help under the field, for content richer than the `hint` text.
+ * @slot label - The label, for content richer than the `label` text.
+ * @slot start - Before the code, for an icon.
+ *
+ * @event {Event} change - Sent from the textarea when the user finishes an edit.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
+ * @event {HelixBeforeListenEvent} helix-before-listen - The dictation button was pressed. Cancelable: cancel it to keep the field from listening.
+ * @event {HelixClearEvent} helix-clear - Fired after the clear button has emptied the field, after `input` and `change`.
+ * @event {HelixListenEvent} helix-listen - Dictation settled on a phrase and put it in the value, after the field's own `input`.
+ * @event {Event} input - Fired after the value changes.
+ *
+ * @csspart clear - The button that empties the field, under `clearable`.
+ * @csspart control - The textarea the reader types in, whose own text is transparent over the highlighted text.
+ * @csspart feedback - The message that says what is wrong.
+ * @csspart field - The box that holds the code.
+ * @csspart highlight - The highlighted text, drawn under the textarea.
+ * @csspart hint - Help under the field, while nothing is wrong.
+ * @csspart label - The label above the field.
+ * @csspart layers - The highlighted text and the textarea, one over the other.
+ * @csspart scroller - The box that scrolls past `max-rows`, and sideways past a long line.
+ * @csspart voice - The dictation button, under `voice`.
+ * @csspart voice-listening - The dictation button while it listens. Set alongside `voice`.
+ * @csspart voice-status - What a screen reader hears as dictation starts and stops, drawn for no one else.
+ *
+ * @cssstate blank - The field holds no text.
+ * @cssstate invalid - The control has an error to show, from the browser's validation, `validate`, or your `feedback`.
+ * @cssstate listening - While the field listens for dictation. The element sets `--dictation-level` on itself meanwhile, from 0 to 1, for a meter.
+ */
+export declare class HelixHeadlessCodeInput extends HelixHeadlessTextarea {
+    protected static markRules: string[];
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-code-input': { clearLabel: 'Leeren' } })`.
+     */
+    static words: string;
+    /**
+     * Turns the code into highlighted markup for its `language`, for this field
+     * alone. Absent, the field draws with the highlighter `registerHighlighter`
+     * gave the page, and plain where there is none. The markup is drawn as
+     * given, so it escapes the code, as every highlighter does.
+     */
+    highlight?: CodeBlockHighlighter | undefined;
+    /** The grammar to highlight, such as `json`, `css`, `ts`, `html` or `sh`. Empty is plain text. */
+    language: string;
+    /**
+     * How long lines are drawn: `off` keeps each line its length and scrolls
+     * sideways, as code reads, and `soft` wraps at the field's edge.
+     */
+    wrap: 'hard' | 'off' | 'soft';
+    /** Whether Escape came just before, which lets Tab leave the field. */
+    private escaped;
+    /** On the page's list of elements a highlighter registration reaches. */
+    protected readonly highlighting: HighlighterController;
+    /** The page registered another highlighter: draws again with it. */
+    highlighterChanged(): void;
+    /** The layers grow with the highlighted text, so the textarea never measures itself. */
+    protected grow(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /** The code as markup: highlighted where a highlighter reads its language, plain otherwise. */
+    private markup;
+    /** Indents or outdents every line the selection touches, and keeps them selected. */
+    private shift;
+    private readonly handleKeydown;
+    /**
+     * The textarea over its highlighted text. The text ends in a space where
+     * the code ends in a line break, or the highlight would be a line shorter
+     * than the textarea and the caret on the last line would sit below it.
+     */
+    protected renderControl(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-code-input': HelixHeadlessCodeInput;
+    }
+}

package/dist/code-input/root/code-input-root.js

@@ -0,0 +1,142 @@
+import { __decorate } from "tslib";
+import { customElement, LAYERS_RULE, SCROLLER_RULE, SPOKEN_RULE } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+import { highlightedLines } from '../../code-block/highlight.js';
+import { HighlighterController, registeredHighlighter, } from '../../code-block/highlighter.js';
+import { keyedLines } from '../../code-block/keyed-lines.js';
+import { HelixHeadlessTextarea } from '../../textarea/root/textarea-root.js';
+const escapeText = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+const INDENT = '  ';
+const lineStart = (text, at) => text.lastIndexOf('\n', at - 1) + 1;
+const lineEnd = (text, at) => {
+    const end = text.indexOf('\n', at);
+    return end === -1 ? text.length : end;
+};
+const typeText = (control, text) => {
+    const typed = typeof document.execCommand === 'function' && document.execCommand('insertText', false, text);
+    if (!typed) {
+        control.setRangeText(text, control.selectionStart, control.selectionEnd, 'end');
+        control.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
+    }
+};
+let HelixHeadlessCodeInput = class HelixHeadlessCodeInput extends HelixHeadlessTextarea {
+    constructor() {
+        super(...arguments);
+        this.language = '';
+        this.wrap = 'off';
+        this.escaped = false;
+        this.highlighting = new HighlighterController(this);
+        this.handleKeydown = (event) => {
+            const control = event.target;
+            if (event.key === 'Escape') {
+                this.escaped = true;
+                return;
+            }
+            const escaped = this.escaped;
+            this.escaped = false;
+            if (this.readOnly ||
+                event.isComposing ||
+                event.altKey ||
+                event.ctrlKey ||
+                event.metaKey ||
+                !(control instanceof HTMLTextAreaElement)) {
+                return;
+            }
+            if (event.key === 'Tab' && !escaped) {
+                event.preventDefault();
+                const { selectionEnd, selectionStart, value } = control;
+                if (event.shiftKey || value.slice(selectionStart, selectionEnd).includes('\n')) {
+                    this.shift(control, event.shiftKey);
+                }
+                else {
+                    typeText(control, INDENT);
+                }
+                return;
+            }
+            if (event.key === 'Enter' && !event.shiftKey) {
+                const { selectionStart, value } = control;
+                const indent = /^[ \t]*/.exec(value.slice(lineStart(value, selectionStart), selectionStart));
+                if (indent?.[0]) {
+                    event.preventDefault();
+                    typeText(control, `\n${indent[0]}`);
+                }
+            }
+        };
+    }
+    static { this.markRules = [SCROLLER_RULE, LAYERS_RULE, SPOKEN_RULE]; }
+    static { this.words = 'helix-code-input'; }
+    highlighterChanged() {
+        this.requestUpdate();
+    }
+    grow() { }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        const control = this.control;
+        control?.setAttribute('autocapitalize', 'off');
+        control?.setAttribute('autocorrect', 'off');
+    }
+    updated(changed) {
+        super.updated(changed);
+        const scroller = this.partNamed('scroller');
+        if (scroller && changed.has('maxRows')) {
+            scroller.style.maxBlockSize = this.maxRows ? `${this.maxRows}lh` : '';
+        }
+    }
+    markup() {
+        const highlight = this.highlight ?? registeredHighlighter();
+        try {
+            const markup = highlight && this.value !== '' ? highlight(this.value, this.language) : undefined;
+            if (markup !== undefined) {
+                return highlightedLines(markup);
+            }
+        }
+        catch (error) {
+            globalThis.reportError?.(error);
+        }
+        return escapeText(this.value);
+    }
+    shift(control, outdent) {
+        const text = control.value;
+        const start = lineStart(text, control.selectionStart);
+        const end = lineEnd(text, Math.max(control.selectionStart, control.selectionEnd - 1));
+        const lines = text.slice(start, end).split('\n');
+        const next = lines.map((line) => outdent ? line.replace(/^(?: {1,2}|\t)/, '') : `${INDENT}${line}`);
+        const block = next.join('\n');
+        if (block === text.slice(start, end)) {
+            return;
+        }
+        control.setSelectionRange(start, end);
+        typeText(control, block);
+        control.setSelectionRange(start, start + block.length);
+    }
+    renderControl() {
+        const tail = this.value === '' || this.value.endsWith('\n') ? ' ' : '';
+        return html `<div part="scroller" data-scroller>
+      <div
+        part="layers"
+        data-layers
+        ?data-wrap=${this.wrap !== 'off'}
+        spellcheck="false"
+        translate="no"
+        @keydown=${this.handleKeydown}
+      >
+        <pre part="highlight" aria-hidden="true">${keyedLines(this.markup())}${tail}</pre>
+        ${super.renderControl()}
+      </div>
+    </div>`;
+    }
+};
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessCodeInput.prototype, "highlight", void 0);
+__decorate([
+    property()
+], HelixHeadlessCodeInput.prototype, "language", void 0);
+__decorate([
+    property()
+], HelixHeadlessCodeInput.prototype, "wrap", void 0);
+HelixHeadlessCodeInput = __decorate([
+    customElement('helix-headless-code-input')
+], HelixHeadlessCodeInput);
+export { HelixHeadlessCodeInput };

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, HelixFormElement, PopoverController, UpgradeController } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixFormElement, ListedController, PopoverController, UpgradeController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../listbox/index.js';
 import '../../tag/root/index.js';
@@ -120,6 +120,9 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @csspart listbox-loading - Shown while the options are loading.
  * @csspart listbox-search - The region holding the field that narrows the list.
  * @csspart listbox-search-field - The filter field inside that region.
+ * @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 VoiceOver hears the highlight, the count and a choice from on Apple devices, drawn once there is one to say. Visually hidden in the styled tier.
  * @csspart rest - The count of choices held beyond `max-tags`. A `<button>` with `expandable`, a `<span>` without it.
  * @csspart surface - The floating panel.
@@ -140,6 +143,8 @@ declare const HelixHeadlessCombobox_base: (new (...args: any[]) => import("@fusi
  * @cssstate open - While the list is open.
  */
 export declare class HelixHeadlessCombobox extends HelixHeadlessCombobox_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-combobox': { emptyText: 'Keine Treffer' } })`.

package/dist/combobox/root/combobox-root.js

@@ -1,5 +1,5 @@
 import { __decorate } from "tslib";
-import { AriaForwardController, afterLinkFollowed, auditChildren, chosenValues, countLabel, customElement, DelayController, drawAutofill, drawStatus, formatWords, HelixCreateEvent, HelixFilterEvent, HelixFormElement, handedLocale, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, onApple, PopoverController, reportValues, StatusController, submitImplicitly, timeConverter, UpgradeController, words, wordsLocale, } from '@fusion.dev/helix-core';
+import { AriaForwardController, afterLinkFollowed, auditChildren, chosenValues, countLabel, customElement, DelayController, drawAutofill, drawStatus, formatWords, HelixCreateEvent, HelixFilterEvent, HelixFormElement, handedLocale, ListedController, MixinControllerOpen, MixinControllerValue, MixinField, MixinTokens, onApple, PopoverController, reportValues, StatusController, submitImplicitly, timeConverter, UpgradeController, words, wordsLocale, } from '@fusion.dev/helix-core';
 import { caretDown } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -13,6 +13,7 @@ const isInsertion = (event) => !event.inputType?.startsWith('delete');
 let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerOpen(MixinTokens(MixinControllerValue(MixinField(HelixFormElement)))) {
     constructor() {
         super(...arguments);
+        this.listed = new ListedController(this, 'focus', () => this.internals?.ariaKeyShortcuts);
         this.aria = new AriaForwardController(this, {
             target: () => this.partNamed('control'),
         });
@@ -586,7 +587,8 @@ let HelixHeadlessCombobox = class HelixHeadlessCombobox extends MixinControllerO
       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"
       aria-label=${this.listLabel}
       empty-text=${this.emptyText}
       load-error=${this.loadError}

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

@@ -1,7 +1,8 @@
 import { type DataOptionItem, HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../dialog/index.js';
 import '../../listbox/index.js';
+import '../../option/index.js';
 declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary A command palette: a list of commands that opens from anywhere on the page and filters as you type.
@@ -72,17 +73,17 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * Aria's `Autocomplete` is. The commands are a `listbox` of `option`s. How many commands typing left, the empty text and
  * the loading text are said in a polite live region.
  *
- * **The commands are an import of their own.** A command is an option, the
- * Option family's, which the palette does not register, so a page that writes
- * one imports it beside the palette:
+ * **The palette registers Option**, since it draws the controls on screen as
+ * options itself with `controls`, so a page that writes commands imports the
+ * palette alone. A tier of your own registers its own option, and in
+ * development a palette holding one nobody registered says so.
  *
- * ```js
- * import '@fusion.dev/helix/command'
- * import '@fusion.dev/helix/option'
- * ```
- *
- * In development, a palette holding an option nobody registered says so once
- * the page has loaded, with the line to add.
+ * **Set `controls` to find anything on screen.** Every labeled Helix control
+ * puts itself on the page's list while it is connected, and the palette lists
+ * the ones a reader can reach under its own commands once they type, with
+ * each one's shortcut. Choosing one closes the palette and presses it, or
+ * moves focus into a field. `unlisted` on a control, or on a region around it,
+ * leaves it out.
  *
  * @since 0.1.0
  * @status stable
@@ -106,6 +107,16 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * @event {HelixSelectEvent} helix-select - A command was chosen, with its `href` where the option is a link. Cancelable: cancel it to keep the palette open, and to keep the browser from following the link.
  * @event {ToggleEvent} toggle - The palette opened or closed. The event carries `newState` and `oldState`.
  *
+ * @csspart control - A control on screen, listed with `controls`.
+ * @csspart control-description - Its region's name.
+ * @csspart control-item - Its row.
+ * @csspart control-item-active - Its row while the keyboard is on it.
+ * @csspart control-item-selected - Its row while selected.
+ * @csspart control-label - Its name.
+ * @csspart control-text - Its name and region, as one column.
+ * @csspart controls - The group of controls on screen.
+ * @csspart controls-items - What holds the group's controls.
+ * @csspart controls-label - The group's heading.
  * @csspart dialog-body - The dialog's slot for its content, which holds the list. It draws no box until you give it one.
  * @csspart dialog-dismiss - The dialog's close control, drawn when the dialog is `dismissible`.
  * @csspart dialog-dismiss-mark - The glyph on the dialog's close control, where none is slotted.
@@ -126,6 +137,9 @@ declare const HelixHeadlessCommand_base: (new (...args: any[]) => import("@fusio
  * @csspart listbox-loading - The text shown while the commands are loading.
  * @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, under `voice`.
+ * @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 the page shown from, by the words of the command that opens it, drawn once there is one to say. Visually hidden in the styled tier.
  *
  * @cssstate empty - The list shows no commands: there are none, or typing hid every one.
@@ -140,6 +154,19 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * `registerWords('de', { 'helix-command': { placeholder: 'Befehle suchen' } })`.
      */
     static words: string;
+    /**
+     * Lists the controls on screen below the palette's own commands, once the
+     * reader types: every labeled Helix button, field, tab, switch and the
+     * rest, by its name, with its shortcut. Choosing one closes the palette and
+     * presses the control, or moves focus into a field.
+     *
+     * A control that is disabled, inert, hidden or under `unlisted` is left out,
+     * and so is anything inside the palette. Off by default, so a palette used
+     * as a search box lists only what it holds.
+     */
+    controls: boolean;
+    /** The heading over the controls on screen. */
+    controlsLabel: string;
     /**
      * The text shown when the filter matches no commands.
      */
@@ -178,6 +205,11 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * with: one key, said once.
      */
     hotkey: string;
+    /**
+     * What the hotkey does, as a list of the page's shortcuts says it, with
+     * `{label}` for the palette's `label`.
+     */
+    hotkeyLabel: string;
     /**
      * Draws the palette in the page, where it stands, with no dialog: a search
      * over a list of commands, as React Aria's Autocomplete is drawn.
@@ -263,6 +295,11 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * {# poleceń} other {# polecenia}}`.
      */
     resultsLabel: string;
+    /**
+     * Draws a dictation button in the search field, which listens through the
+     * page's speech engine and types what it hears, as a field's `voice` does.
+     */
+    voice: boolean;
     /**
      * Whether the consumer put anything under the list.
      *
@@ -359,6 +396,12 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
     private readonly handleAlternate;
     private readonly swallowOptionSelect;
     connectedCallback(): void;
+    /** Takes the hotkey off the page's list of shortcuts. */
+    private unregister;
+    /** The controls on screen, read as the palette opens. */
+    private onScreen;
+    /** What the reader has typed, since the controls are listed only once they type. */
+    private typed;
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
@@ -388,6 +431,13 @@ export declare class HelixHeadlessCommand extends HelixHeadlessCommand_base {
      * from the same template.
      */
     protected renderDialog(): TemplateResult;
+    /** Reads the controls a reader can reach now, leaving out the palette and anything in it. */
+    private readControls;
+    /**
+     * The controls on screen as a group of options, once the reader types, on
+     * the first page and only where the commands are children.
+     */
+    protected renderControls(): TemplateResult | typeof nothing;
     /**
      * The filterable list of commands, which the dialog holds, or the page with
      * `inline`, behind a seam the styled tier can move.

package/dist/command/root/command-root.js

@@ -1,11 +1,12 @@
 import { __decorate } from "tslib";
-import { auditChildren, customElement, drawStatus, HelixElement, HelixSelectEvent, MixinControllerOpen, matchesChord, StatusController, timeConverter, words, } from '@fusion.dev/helix-core';
+import { auditChildren, chordParts, customElement, drawStatus, formatWords, HelixElement, HelixSelectEvent, keyNames, listControls, MixinControllerOpen, matchesChord, onApple, registerShortcut, runControl, StatusController, timeConverter, words, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import { optionsAmong } from '../../option/among.js';
 import '../../dialog/index.js';
 import '../../listbox/index.js';
+import '../../option/index.js';
 const says = (element, state) => {
     try {
         return element?.matches(`:state(${state})`) ?? false;
@@ -14,12 +15,16 @@ const says = (element, state) => {
         return false;
     }
 };
+const CONTROL = 'helix-control:';
 let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
+        this.controls = false;
+        this.controlsLabel = 'On this screen';
         this.emptyText = 'No commands';
         this.filterDelay = 0;
         this.hotkey = 'mod+k';
+        this.hotkeyLabel = 'Open {label}';
         this.inline = false;
         this.items = undefined;
         this.label = 'Commands';
@@ -30,6 +35,7 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
         this.trail = [];
         this.placeholder = 'Search commands';
         this.resultsLabel = '{count, plural, one {# command} other {# commands}}';
+        this.voice = false;
         this.footed = false;
         this.handleHotkey = (event) => {
             if (!matchesChord(event, this.hotkey, true) && !matchesChord(event, this.hotkey, false)) {
@@ -46,6 +52,14 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             event.stopPropagation();
             event.preventDefault();
             const { value } = event.detail;
+            const control = value.startsWith(CONTROL)
+                ? this.onScreen[Number(value.slice(CONTROL.length))]
+                : undefined;
+            if (control) {
+                this.requestOpen(false);
+                void this.updateComplete.then(() => runControl(control));
+                return;
+            }
             if (!this.dispatchEvent(new HelixSelectEvent({ value }))) {
                 return;
             }
@@ -103,7 +117,14 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             }
             this.requestOpen(false);
         };
-        this.handleFilter = () => {
+        this.onScreen = [];
+        this.typed = '';
+        this.handleFilter = (event) => {
+            const typed = event.detail?.value ?? '';
+            if (this.typed.trim() === '' && typed.trim() !== '') {
+                this.readControls();
+            }
+            this.typed = typed;
             void Promise.resolve()
                 .then(() => this.listbox?.updateComplete)
                 .then(() => this.markStatus());
@@ -148,9 +169,15 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
         this.addEventListener('keydown', this.handleBack);
         this.addEventListener('click', this.handleAlternate, { capture: true });
         document.addEventListener('keydown', this.handleHotkey);
+        this.unregister = registerShortcut({
+            keys: () => (this.inline ? '' : this.hotkey),
+            label: () => formatWords(this, 'hotkeyLabel', { label: this.label }),
+            owner: this,
+        });
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.unregister?.();
         this.removeEventListener('helix-select', this.swallowOptionSelect);
         this.removeEventListener('keydown', this.handleAlternate, { capture: true });
         this.removeEventListener('keydown', this.handleBack);
@@ -196,6 +223,9 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
             return;
         }
         if (this.open) {
+            this.onScreen = this.controls
+                ? listControls().filter((control) => control.element !== this && !this.contains(control.element))
+                : [];
             this.listbox?.highlight('none');
             this.searchField?.focus();
         }
@@ -226,13 +256,46 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
       ${this.renderFooter('footer')}
     </${this.tag('dialog')}>`;
     }
+    readControls() {
+        this.onScreen = this.controls
+            ? listControls().filter((control) => control.element !== this && !this.contains(control.element))
+            : [];
+    }
+    renderControls() {
+        if (!this.controls ||
+            this.typed.trim() === '' ||
+            this.page !== '' ||
+            this.items !== undefined) {
+            return nothing;
+        }
+        const apple = onApple();
+        const group = this.tag('option-group');
+        const option = this.tag('option');
+        return html `<${group}
+      part="controls"
+      exportparts="items: controls-items, label: controls-label"
+      label=${this.controlsLabel}
+    >${this.onScreen.map((control, index) => {
+            const [keys] = control.keys;
+            const names = keys ? keyNames(chordParts(keys), apple) : undefined;
+            return html `<${option}
+        part="control"
+        exportparts="description: control-description, item: control-item, item-active: control-item-active,
+          item-selected: control-item-selected, label: control-label, text: control-text"
+        value=${`${CONTROL}${index}`}
+        text-value=${control.name}
+        description=${control.group || nothing}
+      >${control.name}${names ? html `<span slot="end" aria-hidden="true">${names.keys.join(names.separator)}</span>` : nothing}</${option}>`;
+        })}</${group}>`;
+    }
     renderListbox() {
         return html `<${this.tag('listbox')}
         part="listbox"
         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"
         aria-label=${this.listName}
         empty-text=${this.emptyText}
         filter-delay=${this.filterDelay}
@@ -247,6 +310,7 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
         .items=${this.items}
         .fieldHomeEnd=${this.homeEnd === 'list'}
         layout=${this.layout ?? nothing}
+        ?voice=${this.voice}
         filterable
         @helix-before-change=${this.handleChange}
         @helix-filter=${this.handleFilter}
@@ -254,6 +318,7 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
         @input=${this.stopInner}
       >
         ${this.page === '' ? html `<slot></slot>` : html `<slot name=${`page:${this.page}`}></slot>`}
+        ${this.renderControls()}
         <!-- Handed on with the text as the fallback, for the reason Combobox
              gives: the list's own fallback never shows behind a passed slot. -->
         <slot name="empty" slot="empty">${this.emptyText}</slot>
@@ -290,6 +355,13 @@ let HelixHeadlessCommand = class HelixHeadlessCommand extends MixinControllerOpe
         return html `${this.renderDialog()}`;
     }
 };
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessCommand.prototype, "controls", void 0);
+__decorate([
+    words,
+    property({ attribute: 'controls-label' })
+], HelixHeadlessCommand.prototype, "controlsLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'empty-text' })
@@ -306,6 +378,10 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessCommand.prototype, "hotkey", void 0);
+__decorate([
+    words,
+    property({ attribute: 'hotkey-label' })
+], HelixHeadlessCommand.prototype, "hotkeyLabel", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessCommand.prototype, "inline", void 0);
@@ -346,9 +422,18 @@ __decorate([
     words,
     property({ attribute: 'results-label' })
 ], HelixHeadlessCommand.prototype, "resultsLabel", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessCommand.prototype, "voice", void 0);
 __decorate([
     state()
 ], HelixHeadlessCommand.prototype, "footed", void 0);
+__decorate([
+    state()
+], HelixHeadlessCommand.prototype, "onScreen", void 0);
+__decorate([
+    state()
+], HelixHeadlessCommand.prototype, "typed", void 0);
 HelixHeadlessCommand = __decorate([
     customElement('helix-headless-command')
 ], HelixHeadlessCommand);

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

@@ -78,6 +78,7 @@ declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args:
  * @csspart segment-active - The slice under the pointer. Set alongside `segment`.
  * @csspart segment-edge - One slice as a closed shape, used to draw its outline.
  * @csspart slice-label - One slice's share, written on the slice under `slice-labels`. Placed with `left` and `top`, or `inset-inline-start` and `top` on a half ring, and carries its series color as `--chart-series`.
+ * @csspart sonify - The button that plays the chart as sound, under `sonify`.
  * @csspart summary - The chart's name and each slice's share, written as a sentence for screen readers. Hide it visually.
  * @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.
  * @csspart table-pages - Which readings a page of the `table` holds, and the buttons that show the previous and the next page, rendered only while it holds a page. Hide it visually.