@fusion.dev/helix-core 0.142.1 → 0.144.0

package/dist/controllers/aria-forward-controller/aria-forward-controller.d.ts

@@ -1,8 +1,44 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
 /** What the controller needs to know: which element inside is the control. */
 export interface AriaForwardOptions {
+    /**
+     * Whether a host `aria-label` names the control too.
+     *
+     * For a control named by its content, a button or a switch, which has no
+     * `label` to render it into. A field renders its `aria-label` as a clipped
+     * label already, so it leaves this off. A function is asked on every
+     * forward, for a subclass that names the control itself.
+     */
+    label?: boolean | (() => boolean);
+    /**
+     * Elements read after whatever names the control from outside, the host's
+     * `aria-labelledby` or its `<label>`.
+     *
+     * For a control whose name is the label and then what it shows, as a
+     * native `<select>` is named. Added only where the host gives a name, so a
+     * control named by its own template keeps its own.
+     */
+    labelledByAfter?: () => Element[];
+    /**
+     * Whether the control has a name of its own, where its own labels do not
+     * say.
+     *
+     * A file input is labeled by the trigger that opens its picker, "Choose
+     * files", which is an action rather than a name, so a page's `<label>`
+     * should still name it. Absent, the control's own `aria-label`,
+     * `aria-labelledby` and labels with words in them decide.
+     */
+    named?: () => boolean;
     /** The focusable thing in the shadow root, or null before it renders. */
     target: () => HTMLElement | null;
+    /**
+     * How to name the control, said in a warning when it has no accessible
+     * name once it has rendered. Absent, the name is not checked.
+     *
+     * For a control named by its content or a host attribute, as a button is. A
+     * field is checked by `MixinField`, which knows its label.
+     */
+    unnamed?: string;
 }
 /**
  * Carries a host's ARIA references down to the control inside it.
@@ -42,6 +78,13 @@ export interface AriaForwardOptions {
  * a framework rendering a tooltip after this element upgrades, or a consumer
  * pointing `aria-describedby` at a different id, changes an attribute and
  * nothing schedules a Lit update.
+ *
+ * **A `<label>` that names the host names the control too**, when the control
+ * has no name of its own. The platform gives a form-associated host its labels
+ * and the host is a generic the reader never lands on, so a `<label for>` or a
+ * wrapping `<label>` left the textbox unnamed. The labels travel the same way a
+ * forwarded `aria-labelledby` does, as element references, and are read again
+ * when focus arrives, since a label can be added without the host hearing.
  */
 export declare class AriaForwardController implements ReactiveController {
     private readonly host;
@@ -51,7 +94,27 @@ export declare class AriaForwardController implements ReactiveController {
     private readonly forwarded;
     /** The control the record above is about, so a replacement resets it. */
     private recorded;
+    /** Whether a host `aria-label` is carried down. See the option. */
+    private readonly asked;
+    private get label();
+    /** The component's own answer to whether the control is named. See the option. */
+    private readonly named;
+    /** What is read after the host's names. See the option. */
+    private readonly after;
+    /** How to name the control, where its name is checked. See the option. */
+    private readonly unnamed;
     constructor(host: ReactiveControllerHost & HTMLElement, options: AriaForwardOptions);
+    /**
+     * Whether the control has a name that did not come from this controller: an
+     * `aria-label`, an `aria-labelledby` of its own, or a label of its own with
+     * words in it.
+     */
+    private namedByItself;
+    /**
+     * The labels the platform associated with the host, for a control with no
+     * name of its own, and none otherwise.
+     */
+    private hostLabels;
     /**
      * Resolves the host's references and hands them to the control.
      *
@@ -65,5 +128,7 @@ export declare class AriaForwardController implements ReactiveController {
     forward(): void;
     hostConnected(): void;
     hostDisconnected(): void;
+    /** Forwards again as focus arrives, for a label added since the last update. */
+    private readonly refresh;
     hostUpdated(): void;
 }

package/dist/controllers/aria-forward-controller/aria-forward-controller.js

@@ -1,16 +1,63 @@
+import { auditName } from '../../utils/audit-name/audit-name.js';
 import { elementById } from '../../utils/element-by-id/element-by-id.js';
+const shownText = (node) => {
+    if (node instanceof HTMLSlotElement) {
+        return node.assignedNodes({ flatten: true }).map(shownText).join('');
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? '';
+    }
+    if (node instanceof HTMLElement && node.hidden) {
+        return '';
+    }
+    return [...node.childNodes].map(shownText).join('');
+};
 const RELATIONSHIPS = [
     ['aria-describedby', 'ariaDescribedByElements'],
     ['aria-labelledby', 'ariaLabelledByElements'],
 ];
-const STATES = ['aria-expanded', 'aria-haspopup', 'aria-controls', 'aria-invalid'];
+const STATES = [
+    'aria-expanded',
+    'aria-haspopup',
+    'aria-controls',
+    'aria-invalid',
+    'aria-pressed',
+];
 export class AriaForwardController {
+    get label() {
+        return typeof this.asked === 'function' ? this.asked() : this.asked;
+    }
     constructor(host, options) {
         this.forwarded = new Set();
+        this.refresh = () => {
+            this.forward();
+        };
         this.host = host;
         this.target = options.target;
+        this.asked = options.label ?? false;
+        this.named = options.named;
+        this.after = options.labelledByAfter;
+        this.unnamed = options.unnamed;
         host.addController(this);
     }
+    namedByItself(target) {
+        if (target.getAttribute('aria-label')) {
+            return true;
+        }
+        if (!this.forwarded.has('aria-labelledby') && target.hasAttribute('aria-labelledby')) {
+            return true;
+        }
+        const own = target.labels;
+        return [...(own ?? [])].some((label) => shownText(label).trim() !== '');
+    }
+    hostLabels(target) {
+        const labels = this.host.labels;
+        const named = this.named ? this.named() : this.namedByItself(target);
+        if (!labels || labels.length === 0 || named) {
+            return [];
+        }
+        return [...labels].filter((label) => label instanceof HTMLElement);
+    }
     forward() {
         const target = this.target();
         if (!target) {
@@ -20,17 +67,34 @@ export class AriaForwardController {
             this.forwarded.clear();
             this.recorded = target;
         }
+        for (const attribute of this.label ? [...STATES, 'aria-label'] : STATES) {
+            const value = this.host.getAttribute(attribute);
+            if (value === null) {
+                if (this.forwarded.has(attribute)) {
+                    target.removeAttribute(attribute);
+                    this.forwarded.delete(attribute);
+                }
+                continue;
+            }
+            target.setAttribute(attribute, value);
+            this.forwarded.add(attribute);
+        }
         for (const [attribute, property] of RELATIONSHIPS) {
             if (!(property in target)) {
                 continue;
             }
             const ids = (this.host.getAttribute(attribute) ?? '').split(/\s+/).filter(Boolean);
-            const elements = ids
+            const referenced = ids
                 .map((id) => elementById(this.host, id))
                 .filter((element) => element !== null);
+            const elements = referenced.length === 0 && attribute === 'aria-labelledby'
+                ? this.hostLabels(target)
+                : referenced;
             const reflect = target;
             if (elements.length > 0) {
-                reflect[property] = elements;
+                const after = attribute === 'aria-labelledby' ? (this.after?.() ?? []) : [];
+                const named = elements;
+                reflect[property] = [...named, ...after.filter((one) => !named.includes(one))];
                 this.forwarded.add(attribute);
                 continue;
             }
@@ -39,30 +103,27 @@ export class AriaForwardController {
                 this.forwarded.delete(attribute);
             }
         }
-        for (const attribute of STATES) {
-            const value = this.host.getAttribute(attribute);
-            if (value === null) {
-                if (this.forwarded.has(attribute)) {
-                    target.removeAttribute(attribute);
-                    this.forwarded.delete(attribute);
-                }
-                continue;
-            }
-            target.setAttribute(attribute, value);
-            this.forwarded.add(attribute);
-        }
     }
     hostConnected() {
         this.observer = new MutationObserver(() => this.forward());
         this.observer.observe(this.host, {
-            attributeFilter: [...RELATIONSHIPS.map(([attribute]) => attribute), ...STATES],
+            attributeFilter: [
+                ...RELATIONSHIPS.map(([attribute]) => attribute),
+                ...STATES,
+                ...(this.asked === false ? [] : ['aria-label']),
+            ],
         });
+        this.host.addEventListener('focusin', this.refresh);
     }
     hostDisconnected() {
         this.observer?.disconnect();
         this.observer = undefined;
+        this.host.removeEventListener('focusin', this.refresh);
     }
     hostUpdated() {
         this.forward();
+        if (this.unnamed !== undefined) {
+            auditName(this.host, this.target, this.unnamed);
+        }
     }
 }

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

@@ -5,6 +5,11 @@ export interface ArrivalOptions {
     text: () => string;
     /** Whether the element is arriving now, rather than with the page. */
     arriving: () => boolean;
+    /**
+     * How long the region keeps the words once it has said them, in
+     * milliseconds. Defaults to seven seconds.
+     */
+    hold?: number;
 }
 /**
  * The words of an element that is announced when it appears, for a region that
@@ -24,6 +29,12 @@ export interface ArrivalOptions {
  * second time on the headless tier, which has no sheet to clip the region, and
  * a served page changed its picture on hydrating.
  *
+ * **And emptied again once it has been heard.** The words stay in the element
+ * itself, so a region that kept its copy put the message in the accessibility
+ * tree twice, and a reader moving through the page met it twice. The region
+ * keeps the copy for `hold` and then lets it go, which a polite region does not
+ * read out, removals being no news.
+ *
  * The component renders `said` into its region and calls `say` when what it
  * holds changes, from a `slotchange`.
  */
@@ -35,6 +46,7 @@ export declare class ArrivalController implements ReactiveController {
     /** The words last accounted for, said or not. */
     private heard;
     private frame;
+    private timer;
     constructor(host: ReactiveControllerHost, options: ArrivalOptions);
     hostConnected(): void;
     hostDisconnected(): void;

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

@@ -1,3 +1,4 @@
+const HOLD = 7000;
 export class ArrivalController {
     constructor(host, options) {
         this.host = host;
@@ -22,6 +23,9 @@ export class ArrivalController {
     hostDisconnected() {
         cancelAnimationFrame(this.frame);
         this.frame = 0;
+        clearTimeout(this.timer);
+        this.timer = undefined;
+        this.said = '';
     }
     say() {
         const next = this.options.text();
@@ -31,5 +35,11 @@ export class ArrivalController {
         this.heard = next;
         this.said = next;
         this.host.requestUpdate();
+        clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            this.timer = undefined;
+            this.said = '';
+            this.host.requestUpdate();
+        }, this.options.hold ?? HOLD);
     }
 }

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.d.ts

@@ -1,4 +1,19 @@
 import type { ReactiveController, ReactiveControllerHost } from 'lit';
+/**
+ * The id every chart puts on its plot, and the boundary a bubble is kept inside.
+ *
+ * **A name six templates and two files have to agree on is a name that will
+ * stop agreeing**, which is `PALETTE`'s argument and it holds harder here: the
+ * failure is silent. `within` resolves by id, so a plot renamed on one side
+ * returns null, the boundary falls back to the viewport, and the bubble goes
+ * back to hanging past the drawing with nothing reported anywhere. The plot is
+ * also what takes focus, and this controller finds it by the same id.
+ *
+ * Fixed rather than generated: it is scoped to one chart's shadow root, where
+ * it is the only one. Declared here, beside the keys that read it, and
+ * re-exported from `drawTooltip`'s module, where it was first declared.
+ */
+export declare const CHART_PLOT = "helix-chart-plot";
 /** What the controller needs of its host, which is a Lit element and a count. */
 export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
     /**
@@ -9,6 +24,16 @@ export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
      * Where the chart drew itself, which is where the plot is looked for.
      */
     readonly renderRoot: DocumentFragment | HTMLElement;
+    /**
+     * The positions of the cells in a row that hold numbers, which the series
+     * keys move through. Absent, a reading is one series.
+     */
+    readonly plottedColumns?: number[];
+    /**
+     * The palette slot for a cell, or `undefined` for a column no series was
+     * drawn from, such as a scatter's measure across.
+     */
+    seriesOf?(cell: number): number | undefined;
 }
 /**
  * Which reading a pointer is nearest, for a chart that draws no markers.
@@ -33,6 +58,21 @@ export interface ChartPointerHost extends ReactiveControllerHost, HTMLElement {
  * lifts. The table underneath is the readable version and is what a phone
  * should be given, so this listens for `pointermove` and ignores anything whose
  * `pointerType` is not fine.
+ *
+ * **The keyboard moves the same reading, which is what makes it the reading
+ * and not the pointer's.** A chart's plot takes focus (`tabindex="0"` on the
+ * element carrying `CHART_PLOT`), and while it has it the arrow keys walk the
+ * readings, Home and End go to the first and the last, and the other pair of
+ * arrows walks the series within a reading. Escape puts the bubble away, as it
+ * does a tooltip. The tooltip follows because it already follows `at`, and the
+ * chart's readout, a polite live region `drawTooltip` renders, says the
+ * reading in words. It speaks only for a key: a pointer crossing a chart is a
+ * sighted reader looking, and a region speaking on every slot it crossed would
+ * talk over everything else on the page.
+ *
+ * No peer charting library ships this, which is the reason it is spelled out
+ * rather than assumed: the table beside the chart has every number, and this
+ * is for a reader who wants the picture's own order, a reading at a time.
  */
 export declare class ChartPointerController implements ReactiveController {
     private host;
@@ -40,6 +80,22 @@ export declare class ChartPointerController implements ReactiveController {
     private plot;
     /** The reading under the pointer, or -1 when the pointer is elsewhere. */
     at: number;
+    /**
+     * How many readings stand in one column of the drawing, for a chart laid out
+     * as a grid.
+     *
+     * `1` is a row of readings, which is every chart but a heatmap. A heatmap's
+     * calendar week stands seven days to a column, so the up and down arrows move
+     * a day and the across pair moves a week, which is where the eye goes.
+     */
+    grid: number;
+    /** Whether the reading was last moved by a key, which is when the readout speaks. */
+    keyed: boolean;
+    /**
+     * The series the keyboard is reading within a reading, as its place among
+     * the plotted columns, or -1 while the whole reading is read.
+     */
+    series: number;
     /**
      * Which axis the readings are laid out along.
      *
@@ -60,6 +116,17 @@ export declare class ChartPointerController implements ReactiveController {
     constructor(host: ChartPointerHost);
     hostConnected(): void;
     hostDisconnected(): void;
+    /**
+     * The cell of the reading the series keys rest on, by its place in the row,
+     * or `undefined` while the whole reading is read.
+     *
+     * The tooltip marks this cell and the readout says it alone. A place in the
+     * row and not a series depth, because a row holds columns nothing was drawn
+     * from, and the bubble lists every one of them.
+     */
+    get column(): number | undefined;
+    /** The cells a series key can rest on: every column a series was drawn from. */
+    private columns;
     /**
      * Tells the tooltip its anchor moved, which nothing else would.
      *
@@ -110,8 +177,40 @@ export declare class ChartPointerController implements ReactiveController {
      * can change its direction without the chart updating.
      */
     get mirrored(): boolean;
+    /**
+     * Whether a pointer event may move the reading, which only a mouse or a pen
+     * may.
+     *
+     * Public for a chart that hears the pointer itself, a donut's slices and a
+     * heatmap's cells, so the rule a coarse pointer gets is this one everywhere.
+     * Heard unfiltered, a touch opened the bubble under the finger and left it
+     * there after the finger lifted.
+     */
+    accepts(event: Event): boolean;
     /** Puts the pointer on a reading, for a chart that resolves it some other way. */
     set(at: number): void;
+    /**
+     * Whether an event came from the plot itself, which is the one element in
+     * the chart the keys are for.
+     *
+     * By the id every chart gives its plot, asked of the first node on the
+     * event's path: a key pressed in a donut's middle, which a consumer can fill
+     * with a link, is that link's and not the chart's.
+     */
+    private fromPlot;
+    /** Puts the reading away, as Escape and leaving the plot both do. */
+    private clear;
+    private readonly key;
+    /**
+     * Shows the first reading when the plot is reached from the keyboard, so the
+     * bubble and the readout say where the reader has arrived.
+     *
+     * A pointer pressing the plot focuses it too, and is left alone: the
+     * pointer is already showing a reading, and `:focus-visible` is how the
+     * platform says which of the two arrived.
+     */
+    private readonly arrive;
+    private readonly depart;
     private readonly move;
     private readonly leave;
 }

package/dist/controllers/chart-pointer-controller/chart-pointer-controller.js

@@ -1,11 +1,76 @@
 import { isRtl } from '../../utils/is-rtl/is-rtl.js';
+import { stepReading } from './reading-step.js';
+export const CHART_PLOT = 'helix-chart-plot';
 export class ChartPointerController {
     constructor(host) {
         this.moved = false;
         this.at = -1;
+        this.grid = 1;
+        this.keyed = false;
+        this.series = -1;
         this.axis = 'inline';
+        this.key = (event) => {
+            if (!this.fromPlot(event) || event.altKey || event.ctrlKey || event.metaKey) {
+                return;
+            }
+            const count = this.host.readings;
+            if (count === 0) {
+                return;
+            }
+            if (event.key === 'Escape') {
+                if (this.at >= 0) {
+                    event.preventDefault();
+                    this.clear();
+                }
+                return;
+            }
+            const next = stepReading(event.key, { at: this.at, series: this.series }, {
+                axis: this.axis,
+                count,
+                grid: this.grid,
+                rtl: isRtl(this.host),
+                series: this.columns().length,
+            });
+            if (next === undefined) {
+                return;
+            }
+            const { at, series } = next;
+            event.preventDefault();
+            if (at === this.at && series === this.series && this.keyed) {
+                return;
+            }
+            this.at = at;
+            this.series = series;
+            this.keyed = true;
+            this.moved = true;
+            this.host.requestUpdate();
+        };
+        this.arrive = (event) => {
+            if (!this.fromPlot(event) || this.at >= 0) {
+                return;
+            }
+            const plot = event.composedPath()[0];
+            let visible = true;
+            try {
+                visible = plot.matches(':focus-visible');
+            }
+            catch {
+            }
+            if (!visible || this.host.readings === 0) {
+                return;
+            }
+            this.at = 0;
+            this.keyed = true;
+            this.moved = true;
+            this.host.requestUpdate();
+        };
+        this.depart = (event) => {
+            if (this.fromPlot(event) && this.keyed) {
+                this.clear();
+            }
+        };
         this.move = (event) => {
-            if (this.axis === 'none' || (event.pointerType !== 'mouse' && event.pointerType !== 'pen')) {
+            if (this.axis === 'none' || !this.accepts(event)) {
                 return;
             }
             const box = this.box();
@@ -23,12 +88,14 @@ export class ChartPointerController {
             const next = Math.min(Math.max(slot, 0), count - 1);
             if (next !== this.at) {
                 this.at = next;
+                this.keyed = false;
+                this.series = -1;
                 this.moved = true;
                 this.host.requestUpdate();
             }
         };
         this.leave = () => {
-            if (this.at !== -1) {
+            if (this.at !== -1 && !this.keyed) {
                 this.at = -1;
                 this.host.requestUpdate();
             }
@@ -39,11 +106,29 @@ export class ChartPointerController {
     hostConnected() {
         this.host.addEventListener('pointermove', this.move);
         this.host.addEventListener('pointerleave', this.leave);
+        this.host.addEventListener('keydown', this.key);
+        this.host.addEventListener('focusin', this.arrive);
+        this.host.addEventListener('focusout', this.depart);
     }
     hostDisconnected() {
         this.host.removeEventListener('pointermove', this.move);
         this.host.removeEventListener('pointerleave', this.leave);
+        this.host.removeEventListener('keydown', this.key);
+        this.host.removeEventListener('focusin', this.arrive);
+        this.host.removeEventListener('focusout', this.depart);
         this.at = -1;
+        this.series = -1;
+        this.keyed = false;
+    }
+    get column() {
+        return this.series < 0 ? undefined : this.columns()[this.series];
+    }
+    columns() {
+        const host = this.host;
+        const all = host.plottedColumns ?? [];
+        return host.seriesOf === undefined
+            ? all
+            : all.filter((one) => host.seriesOf?.(one) !== undefined);
     }
     hostUpdated() {
         if (!this.moved) {
@@ -63,11 +148,31 @@ export class ChartPointerController {
     get mirrored() {
         return isRtl(this.host);
     }
+    accepts(event) {
+        const type = event.pointerType;
+        return type === 'mouse' || type === 'pen';
+    }
     set(at) {
         if (at !== this.at) {
             this.at = at;
+            this.keyed = false;
             this.moved = true;
             this.host.requestUpdate();
         }
     }
+    fromPlot(event) {
+        const target = event.composedPath()[0];
+        return (target instanceof Element &&
+            target.id === CHART_PLOT &&
+            target.getRootNode() === this.host.renderRoot);
+    }
+    clear() {
+        const was = this.at;
+        this.at = -1;
+        this.series = -1;
+        this.keyed = false;
+        if (was !== -1) {
+            this.host.requestUpdate();
+        }
+    }
 }

package/dist/controllers/chart-pointer-controller/reading-step.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Where a key moves the reading of a chart, as arithmetic with no element in
+ * it.
+ *
+ * `ChartPointerController` hears the key and asks this where it goes, so the
+ * map of keys to readings is one function every chart shares, and a spec can
+ * hold it without a page.
+ */
+/** How the readings of a chart are laid out, which decides what each arrow does. */
+export interface ReadingLayout {
+    /**
+     * The axis the readings run along: `inline` along the line of text, `block`
+     * down the box, as a horizontal bar chart runs its categories, and `none`
+     * for a ring or a plane, whose readings are walked in the table's order.
+     */
+    axis: 'block' | 'inline' | 'none';
+    /** How many readings there are. */
+    count: number;
+    /** How many readings stand in one column, for a grid. `1` is a row of them. */
+    grid: number;
+    /** Whether the line of text runs right to left, which turns the inline arrows. */
+    rtl: boolean;
+    /** How many series a reading holds, which the cross pair of arrows walks. */
+    series: number;
+}
+/** A reading and the series within it, `-1` for none and for the whole reading. */
+export interface ReadingPlace {
+    /** The reading, or `-1` for none. */
+    at: number;
+    /** The series within it, by its place among the plotted ones, or `-1` for all of them. */
+    series: number;
+}
+/**
+ * Which way a key moves along the readings: `1`, `-1`, or `0` for a key that
+ * moves something else.
+ *
+ * The arrows along the line on an inline chart, down the box on a block one,
+ * and a whole column across on a grid. The cross pair walks the readings too
+ * wherever a reading holds one series, so no arrow is dead.
+ */
+export declare const alongReadings: (key: string, layout: ReadingLayout) => number;
+/**
+ * Which way a key moves among the series of a reading: the pair of arrows
+ * that does not walk the readings, and only where a reading holds two or more.
+ * Down the bubble's list for the arrow pointing down, or along the line.
+ */
+export declare const amongSeries: (key: string, layout: ReadingLayout) => number;
+/**
+ * Where a key moves the reading, or `undefined` for a key that moves nothing,
+ * which the page keeps.
+ *
+ * Home and End go to the first and the last. From no reading, an arrow moving
+ * on starts at the first and one moving back at the last, so either arrow
+ * starts somewhere a reader expects. A series key on no reading starts on the
+ * first. Nothing walks off either end.
+ */
+export declare const stepReading: (key: string, from: ReadingPlace, layout: ReadingLayout) => ReadingPlace | undefined;