@fusion.dev/helix-core 0.215.2 → 0.216.0

package/dist/mixins/mixin-chart-source/mixin-chart-source.js

@@ -1,9 +1,14 @@
 import { __decorate } from "tslib";
+import { speakerHigh } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { ChartPointerController } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
 import { SourceController } from '../../controllers/source-controller/source-controller.js';
+import { drawIcon } from '../../utils/draw-icon/draw-icon.js';
+import { keyClaimed } from '../../utils/key-claimed/key-claimed.js';
+import { timeConverter } from '../../utils/number-converter/number-converter.js';
 import { seriesKey } from '../../utils/read-series/read-series.js';
+import { ChartSound, panOf, pitchOf, sweepPlan, } from '../../utils/sonify/sonify.js';
 import { writtenList } from '../../utils/written-list/written-list.js';
 import { formatWords, words } from '../../words/words.js';
 export const PALETTE = 24;
@@ -19,6 +24,32 @@ export const MixinChartSource = (Base) => {
             super(...arguments);
             this.source = new SourceController(this);
             this.pointer = new ChartPointerController(this);
+            this.playingReadings = false;
+            this.sound = new ChartSound();
+            this.toned = { at: -1, series: -1 };
+            this.handleSonifyKey = (event) => {
+                if (event.key === 'Escape' && this.playingReadings) {
+                    this.stopReadings();
+                    return;
+                }
+                if (!this.sonify ||
+                    event.defaultPrevented ||
+                    keyClaimed(event) ||
+                    event.altKey ||
+                    event.ctrlKey ||
+                    event.metaKey) {
+                    return;
+                }
+                if (event.key === 'l' || event.key === 'L') {
+                    event.preventDefault();
+                    if (this.playingReadings) {
+                        this.stopReadings();
+                    }
+                    else {
+                        void this.playReadings();
+                    }
+                }
+            };
             this.data = undefined;
             this.for = '';
             this.label = '';
@@ -27,9 +58,101 @@ export const MixinChartSource = (Base) => {
             this.positionLabel = '{position} of {count}';
             this.previousReadingsLabel = 'Previous readings';
             this.readingsLabel = 'Readings {first} to {last} of {count}';
+            this.sonify = false;
+            this.sonifyDuration = 3000;
+            this.sonifyLabel = 'Listen';
+            this.sonifyStopLabel = 'Stop';
             this.tablePage = 0;
         }
         static { this.words = ''; }
+        get sounding() {
+            return this.playingReadings;
+        }
+        soundSeries() {
+            const count = this.readings;
+            return this.series
+                .filter((one) => this.showsSeries(one.name))
+                .map((one) => {
+                const values = Array.from({ length: count }, () => null);
+                for (const point of one.points) {
+                    values[point.at] = point.value;
+                }
+                return { name: one.name, values };
+            });
+        }
+        soundRange(series) {
+            const values = series.flatMap((one) => one.values.filter((value) => value !== null));
+            return { max: Math.max(...values, 0), min: Math.min(...values, 0) };
+        }
+        async playReadings() {
+            const series = this.soundSeries();
+            if (series.length === 0) {
+                return;
+            }
+            this.playingReadings = true;
+            await this.sound.play(sweepPlan(series, { duration: this.sonifyDuration / 1000, ...this.soundRange(series) }));
+            this.playingReadings = false;
+        }
+        stopReadings() {
+            this.sound.stop();
+            this.playingReadings = false;
+        }
+        connectedCallback() {
+            super.connectedCallback();
+            this.addEventListener('keydown', this.handleSonifyKey);
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.removeEventListener('keydown', this.handleSonifyKey);
+            this.stopReadings();
+            this.sound.close();
+        }
+        updated(changed) {
+            super.updated(changed);
+            const { at, keyed, series } = this.pointer;
+            if (!this.sonify ||
+                !keyed ||
+                at < 0 ||
+                (at === this.toned.at && series === this.toned.series)) {
+                return;
+            }
+            this.toned = { at, series };
+            const all = this.soundSeries();
+            const one = all[Math.max(0, series)];
+            const value = one?.values[at];
+            if (one === undefined || value === null || value === undefined) {
+                return;
+            }
+            const range = this.soundRange(all);
+            void this.sound.play([
+                {
+                    frequency: pitchOf(value, range.min, range.max),
+                    kind: 'tone',
+                    length: 0.18,
+                    pan: panOf(at, this.readings),
+                    series: Math.max(0, series),
+                    time: 0,
+                },
+            ]);
+        }
+        renderSonify() {
+            if (!this.sonify || !this.readingsKnown || !ChartSound.available) {
+                return nothing;
+            }
+            return html `<button
+        part="sonify"
+        type="button"
+        aria-pressed=${this.playingReadings ? 'true' : 'false'}
+        @click=${() => {
+                if (this.playingReadings) {
+                    this.stopReadings();
+                }
+                else {
+                    void this.playReadings();
+                }
+            }}
+      >${drawIcon(speakerHigh)}<span>${this.playingReadings ? this.sonifyStopLabel : this.sonifyLabel}</span></button>`;
+        }
         static get observedAttributes() {
             const inherited = Reflect.get(Base, 'observedAttributes', this);
             return [...(inherited ?? []), 'aria-label'];
@@ -146,6 +269,9 @@ export const MixinChartSource = (Base) => {
       </div>`;
         }
     }
+    __decorate([
+        state()
+    ], ChartSourceElement.prototype, "playingReadings", void 0);
     __decorate([
         property({ attribute: false })
     ], ChartSourceElement.prototype, "data", void 0);
@@ -174,6 +300,23 @@ export const MixinChartSource = (Base) => {
         words,
         property({ attribute: 'readings-label' })
     ], ChartSourceElement.prototype, "readingsLabel", void 0);
+    __decorate([
+        property({ reflect: true, type: Boolean })
+    ], ChartSourceElement.prototype, "sonify", void 0);
+    __decorate([
+        property({ attribute: 'sonify-duration', converter: timeConverter('sonify-duration', 3000) })
+    ], ChartSourceElement.prototype, "sonifyDuration", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'sonify-label' })
+    ], ChartSourceElement.prototype, "sonifyLabel", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'sonify-stop-label' })
+    ], ChartSourceElement.prototype, "sonifyStopLabel", void 0);
+    __decorate([
+        property({ reflect: true })
+    ], ChartSourceElement.prototype, "summary", void 0);
     __decorate([
         state()
     ], ChartSourceElement.prototype, "tablePage", void 0);

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

@@ -0,0 +1,40 @@
+import { nothing, type TemplateResult } from 'lit';
+import type { HelixElement } from '../../helix-element/helix-element.js';
+import { type SpeechEngine } from '../../utils/speech/speech.js';
+type Constructor<T> = new (...args: any[]) => T;
+export declare class VoiceElement {
+    /** Whether the field is listening now. */
+    readonly listening: boolean;
+    listeningLabel: string;
+    speechEngine: SpeechEngine | undefined;
+    stoppedListeningLabel: string;
+    voice: boolean;
+    voiceLabel: string;
+    voiceStopLabel: string;
+    /** Starts listening, and returns whether it did. */
+    startListening(): boolean;
+    /** Stops listening, keeping what was heard. */
+    stopListening(): void;
+    /** The dictation button and its status, behind a seam a tier can move. */
+    protected renderVoice(): TemplateResult | typeof nothing;
+    /** The native field dictation types into. */
+    protected voiceField(): HTMLInputElement | HTMLTextAreaElement | null;
+    /** The type of the field dictation types into. Dictation listens only in `text`, `search`, `tel` and `url`. */
+    protected get voiceType(): string;
+}
+/**
+ * Adds dictation to a field: `voice` draws a button that listens through the
+ * page's speech engine and types what it hears at the caret.
+ *
+ * **What is heard goes in through the field's own `input` event.** A guess is
+ * written where the caret was and replaced by each better guess, and the
+ * settled phrase replaces the last guess, each an `input` like a key press, so
+ * a field's value, its validation and a framework's state follow it with no
+ * code of their own. A space is put before a phrase that does not start with
+ * punctuation when the text before it does not end in one.
+ *
+ * The button is drawn only once the page has been read, since a server cannot
+ * ask whether the browser has an engine, and only where it has one.
+ */
+export declare const MixinVoice: <T extends Constructor<HelixElement>>(Base: T) => Constructor<VoiceElement> & T;
+export {};

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

@@ -0,0 +1,198 @@
+import { __decorate } from "tslib";
+import { microphone } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+import { HelixBeforeListenEvent, HelixListenEvent } from '../../events/events.js';
+import { drawIcon } from '../../utils/draw-icon/draw-icon.js';
+import { pageSpeechEngine, } from '../../utils/speech/speech.js';
+import { words } from '../../words/words.js';
+import { wordsLocale } from '../../words/words-locale.js';
+const JOINS = /^[\s.,!?;:)\]}]/;
+const DICTATED = new Set(['search', 'tel', 'text', 'url']);
+const HELD = new Set(['Alt', 'CapsLock', 'Control', 'Meta', 'Shift']);
+export const MixinVoice = (Base) => {
+    class Voice extends Base {
+        constructor() {
+            super(...arguments);
+            this.listeningLabel = 'Listening';
+            this.speechEngine = undefined;
+            this.stoppedListeningLabel = 'Stopped listening';
+            this.voice = false;
+            this.voiceLabel = 'Dictate';
+            this.voiceStopLabel = 'Stop dictation';
+            this.heard = false;
+            this.said = '';
+            this.guess = [0, 0];
+            this.handleVoiceKey = (event) => {
+                const { key } = event;
+                if (!this.heard || HELD.has(key)) {
+                    return;
+                }
+                if (key === 'Escape') {
+                    event.preventDefault();
+                    event.stopPropagation();
+                }
+                this.stopListening();
+            };
+            this.handleVoicePointer = () => {
+                this.stopListening();
+            };
+        }
+        static { this.words = ''; }
+        get listening() {
+            return this.heard;
+        }
+        voiceField() {
+            return null;
+        }
+        get engine() {
+            return this.speechEngine ?? pageSpeechEngine();
+        }
+        get voiceType() {
+            return 'text';
+        }
+        get voiceReady() {
+            return (DICTATED.has(this.voiceType) &&
+                this.childrenKnown &&
+                this.engine.available());
+        }
+        firstUpdated(changed) {
+            super.firstUpdated(changed);
+            if (this.voice) {
+                this.finishHydration();
+            }
+        }
+        updated(changed) {
+            super.updated(changed);
+            if ((changed.has('voice') && !this.voice) || (this.heard && !this.voiceReady)) {
+                this.stopListening();
+            }
+        }
+        disconnectedCallback() {
+            super.disconnectedCallback();
+            this.stopListening();
+        }
+        startListening() {
+            if (this.heard) {
+                return true;
+            }
+            const field = this.voiceField();
+            if (!field || !this.voiceReady || !this.dispatchEvent(new HelixBeforeListenEvent())) {
+                return false;
+            }
+            this.guess = [
+                field.selectionStart ?? field.value.length,
+                field.selectionEnd ?? field.value.length,
+            ];
+            this.heard = true;
+            this.said = this.listeningLabel;
+            this.toggleState('listening', true);
+            field.addEventListener('keydown', this.handleVoiceKey);
+            field.addEventListener('pointerdown', this.handleVoicePointer);
+            this.session = this.engine.listen({
+                lang: wordsLocale(this),
+                listener: {
+                    end: () => this.ended(),
+                    final: (text) => this.place(text, true),
+                    level: (level) => {
+                        this.style.setProperty('--dictation-level', level.toFixed(3));
+                    },
+                    partial: (text) => this.place(text, false),
+                },
+            });
+            return true;
+        }
+        stopListening() {
+            this.session?.stop();
+            this.ended();
+        }
+        ended() {
+            if (!this.heard) {
+                return;
+            }
+            this.session = undefined;
+            this.heard = false;
+            this.said = this.stoppedListeningLabel;
+            this.style.removeProperty('--dictation-level');
+            this.toggleState('listening', false);
+            this.voiceField()?.removeEventListener('keydown', this.handleVoiceKey);
+            this.voiceField()?.removeEventListener('pointerdown', this.handleVoicePointer);
+        }
+        place(text, settled) {
+            const field = this.voiceField();
+            if (!field || !this.heard) {
+                return;
+            }
+            const [start, end] = this.guess;
+            const before = field.value.slice(0, start);
+            const spaced = text !== '' && before !== '' && !/\s$/.test(before) && !JOINS.test(text) ? ` ${text}` : text;
+            field.setRangeText(spaced, start, end, 'end');
+            this.guess = settled
+                ? [start + spaced.length, start + spaced.length]
+                : [start, start + spaced.length];
+            field.dispatchEvent(new InputEvent('input', {
+                bubbles: true,
+                composed: true,
+                data: spaced,
+                inputType: 'insertText',
+            }));
+            if (settled && text !== '') {
+                this.dispatchEvent(new HelixListenEvent({ text }));
+            }
+        }
+        renderVoice() {
+            if (!this.voice || !this.voiceReady) {
+                return nothing;
+            }
+            const off = this.isDisabled === true;
+            const readOnly = this.readOnly === true;
+            return html `<button
+          part="voice${this.heard ? ' voice-listening' : ''}"
+          type="button"
+          aria-label=${this.heard ? this.voiceStopLabel : this.voiceLabel}
+          aria-pressed=${this.heard ? 'true' : 'false'}
+          ?disabled=${off || readOnly}
+          @click=${() => {
+                if (this.heard) {
+                    this.stopListening();
+                }
+                else {
+                    this.startListening();
+                }
+            }}
+        >
+          ${drawIcon(microphone)}
+        </button
+        ><span part="voice-status" data-spoken role="status">${this.said}</span>`;
+        }
+    }
+    __decorate([
+        words,
+        property({ attribute: 'listening-label' })
+    ], Voice.prototype, "listeningLabel", void 0);
+    __decorate([
+        property({ attribute: false })
+    ], Voice.prototype, "speechEngine", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'stopped-listening-label' })
+    ], Voice.prototype, "stoppedListeningLabel", void 0);
+    __decorate([
+        property({ type: Boolean })
+    ], Voice.prototype, "voice", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'voice-label' })
+    ], Voice.prototype, "voiceLabel", void 0);
+    __decorate([
+        words,
+        property({ attribute: 'voice-stop-label' })
+    ], Voice.prototype, "voiceStopLabel", void 0);
+    __decorate([
+        state()
+    ], Voice.prototype, "heard", void 0);
+    __decorate([
+        state()
+    ], Voice.prototype, "said", void 0);
+    return Voice;
+};

package/dist/utils/controls/controls.d.ts

@@ -0,0 +1,64 @@
+/** What running a listed control does: press it, or move focus into it. */
+export type ControlKind = 'focus' | 'press';
+/** A control on the page, as it registers itself. */
+export interface ControlEntry {
+    element: HTMLElement;
+    kind: ControlKind;
+    /**
+     * The shortcuts the control answers, as `aria-keyshortcuts` spells them,
+     * where they are not on its `aria-keyshortcuts` attribute, such as a value
+     * written through `ElementInternals`.
+     */
+    keys?: (() => string | null | undefined) | undefined;
+}
+/** A shortcut that belongs to the page or a region rather than to one control, such as ⌘K for a palette. */
+export interface ShortcutEntry {
+    /** The chord, as Kbd writes it: `mod+k`, `F8`. Read when the list is asked for. */
+    keys: () => string;
+    /** What the shortcut does, such as "Open the command palette". */
+    label: () => string;
+    /** The element it belongs to, which has to be connected for the shortcut to be listed. */
+    owner: Element;
+    /** The control the shortcut acts on, where it acts on one, so a list can name it once. */
+    target?: Element | undefined;
+}
+/** A control as a list of what is on screen gives it. */
+export interface ListedControl {
+    element: HTMLElement;
+    /** The name of the nearest labeled region around it, or empty. */
+    group: string;
+    /** Its shortcuts as chords, `mod+k` style, each one written once. */
+    keys: string[];
+    kind: ControlKind;
+    name: string;
+}
+/** Adds a control to the page's list. */
+export declare const registerControl: (entry: ControlEntry) => void;
+/** Takes a control off the page's list. */
+export declare const unregisterControl: (element: HTMLElement) => void;
+/** Adds a shortcut that belongs to no one control, and returns what takes it away again. */
+export declare const registerShortcut: (entry: ShortcutEntry) => (() => void);
+/** One `aria-keyshortcuts` chord, `Meta+Shift+K`, as Kbd's grammar writes it: `meta+shift+k`. */
+export declare const chordOfAria: (aria: string) => string;
+/**
+ * The name a reader is given for a control: its `label`, then `aria-label`,
+ * then the text `aria-labelledby` points at, then its own content.
+ */
+export declare const controlName: (element: HTMLElement) => string;
+/**
+ * Whether a control is one a reader can reach now: drawn, not disabled, and
+ * not inside anything inert or `unlisted`. `unlisted` on the control or on any
+ * element around it, across shadow roots, leaves it off every list.
+ */
+export declare const controlReachable: (element: HTMLElement) => boolean;
+/** Every control a reader can reach now, in document order, with its name, keys and group. */
+export declare const listControls: () => ListedControl[];
+/** Every shortcut that belongs to no one control, whose owner is on the page. */
+export declare const listShortcuts: () => Array<{
+    keys: string;
+    label: string;
+    owner: Element;
+    target?: Element | undefined;
+}>;
+/** Runs a listed control as a reader would: brings it into view, then presses it or focuses it. */
+export declare const runControl: (control: Pick<ListedControl, 'element' | 'kind'>) => void;

package/dist/utils/controls/controls.js

@@ -0,0 +1,136 @@
+import { nameText } from '../name-text/name-text.js';
+const KEY = Symbol.for('fusion.helix.controls');
+const globals = globalThis;
+if (globals[KEY] === undefined) {
+    globals[KEY] = { controls: new Map(), shortcuts: new Set() };
+}
+const registry = globals[KEY];
+export const registerControl = (entry) => {
+    registry.controls.set(entry.element, entry);
+};
+export const unregisterControl = (element) => {
+    registry.controls.delete(element);
+};
+export const registerShortcut = (entry) => {
+    registry.shortcuts.add(entry);
+    return () => {
+        registry.shortcuts.delete(entry);
+    };
+};
+const CHORD = {
+    ' ': 'space',
+    arrowdown: 'down',
+    arrowleft: 'left',
+    arrowright: 'right',
+    arrowup: 'up',
+    control: 'ctrl',
+    delete: 'del',
+    escape: 'esc',
+    meta: 'meta',
+};
+export const chordOfAria = (aria) => aria
+    .split('+')
+    .map((part) => {
+    const name = part.trim().toLowerCase();
+    return CHORD[name] ?? name;
+})
+    .join('+');
+const parentOf = (element) => element.parentElement ??
+    element.getRootNode().host ??
+    null;
+export const controlName = (element) => {
+    const own = element.label;
+    if (typeof own === 'string' && own.trim() !== '') {
+        return own.trim();
+    }
+    const label = element.getAttribute('aria-label');
+    if (label?.trim()) {
+        return label.trim();
+    }
+    const ids = element.getAttribute('aria-labelledby');
+    if (ids) {
+        const scope = element.getRootNode();
+        const words = ids
+            .split(/\s+/)
+            .map((id) => scope.getElementById?.(id)?.textContent ?? '')
+            .join(' ')
+            .trim();
+        if (words !== '') {
+            return words;
+        }
+    }
+    return nameText(element).replace(/\s+/g, ' ').trim();
+};
+const groupOf = (element) => {
+    for (let at = parentOf(element); at; at = parentOf(at)) {
+        const label = at.getAttribute('aria-label') ?? at.label;
+        if (typeof label === 'string' && label.trim() !== '' && at.localName !== 'helix-command') {
+            return label.trim();
+        }
+    }
+    return '';
+};
+export const controlReachable = (element) => {
+    if (!element.isConnected) {
+        return false;
+    }
+    if (element.disabled === true ||
+        element.getAttribute('aria-disabled') === 'true') {
+        return false;
+    }
+    for (let at = element; at; at = parentOf(at)) {
+        if (at.hasAttribute('unlisted') ||
+            at.hasAttribute('inert') ||
+            at.inert === true) {
+            return false;
+        }
+    }
+    return typeof element.checkVisibility === 'function'
+        ? element.checkVisibility({ visibilityProperty: true })
+        : true;
+};
+const keysOf = (entry) => {
+    const written = [entry.element.getAttribute('aria-keyshortcuts'), entry.keys?.()]
+        .filter((list) => typeof list === 'string')
+        .flatMap((list) => list.split(/\s+/))
+        .filter((one) => one !== '')
+        .map(chordOfAria);
+    return [...new Set(written)];
+};
+export const listControls = () => {
+    const listed = [...registry.controls.values()]
+        .filter((entry) => controlReachable(entry.element))
+        .map((entry) => ({
+        element: entry.element,
+        group: groupOf(entry.element),
+        keys: keysOf(entry),
+        kind: entry.kind,
+        name: controlName(entry.element),
+    }))
+        .filter((control) => control.name !== '');
+    return listed.sort((a, b) => {
+        const position = a.element.compareDocumentPosition(b.element);
+        return position & Node.DOCUMENT_POSITION_FOLLOWING
+            ? -1
+            : position & Node.DOCUMENT_POSITION_PRECEDING
+                ? 1
+                : 0;
+    });
+};
+export const listShortcuts = () => [...registry.shortcuts]
+    .filter((entry) => entry.owner.isConnected)
+    .map((entry) => ({
+    keys: entry.keys(),
+    label: entry.label(),
+    owner: entry.owner,
+    target: entry.target,
+}))
+    .filter((entry) => entry.keys !== '');
+export const runControl = (control) => {
+    control.element.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+    if (control.kind === 'focus') {
+        control.element.focus();
+        return;
+    }
+    control.element.click();
+};

package/dist/utils/report-runtime/report-runtime.d.ts

@@ -85,6 +85,8 @@ export type RuntimeKind =
  * Development builds only.
  */
  | 'solid-handler-syntax'
+/** A page's copy of the sandbox's compiler worker file is from another release. */
+ | 'stale-worker'
 /** A stencil's regions went unused: no named parts, or parts too small. */
  | 'stencil-regions-unused'
 /** A stencil has no inside to place the notes in. */