@fusion.dev/helix-headless 0.147.0 → 0.149.0

package/dist/button-group/root/button-group-root.d.ts

@@ -9,19 +9,62 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * controls, and a development build warns once with the kind `missing-name`.
  *
  * The group does not manage focus, so each button keeps its own tab stop. For
- * one tab stop with arrow keys between the buttons, the APG toolbar pattern,
- * use Toolbar.
+ * one tab stop with arrow keys between a mix of controls, the APG toolbar
+ * pattern, use Toolbar.
  *
  * Buttons are slotted, so they stay your own elements and keep their own
  * appearance and size.
  *
+ * **Buttons that stay pressed.** With `selection-mode`, each button with a
+ * `value` is a toggle button: a press presses or releases it, and it says so
+ * with `aria-pressed`. `single` keeps one pressed at a time, and a press on the
+ * pressed one releases it. `multiple` lets any number be pressed. `value` is
+ * the pressed values, comma separated. A press sends a cancelable
+ * `helix-before-change` with the value it would leave, then `change`.
+ *
+ * The pressed state is written on the control inside each button's shadow
+ * root, so the markup you rendered is never changed and a framework hydrating
+ * it sees what its server sent. That is also why only Helix buttons are
+ * toggles: a native `<button>` or a button without a `value` stays a plain
+ * action button in the group, and a native one without its own
+ * `aria-pressed` warns once, with the runtime kind `untold-toggle`. The inner
+ * control also carries
+ * `--button-group-pressed`, `1` or `0`, for a `::part(button)` rule of yours.
+ *
+ * Use Toggle Group instead for a choice that belongs in a form, or one where
+ * the arrow keys choose as they move: it is a `radiogroup` of options with a
+ * form value, `required` and validation. A Button Group in a selection mode is
+ * a set of actions that stay on, such as bold and italic, or a view that a
+ * press switches, and it submits nothing.
+ *
+ * **Keyboard.** In a selection mode the group is one tab stop: the button
+ * focus was last on, then the first pressed one, then the first one.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Right, Down | Moves to the next button, from the last back to the first. |
+ * | Left, Up | Moves to the button before, from the first round to the last. |
+ * | Home, End | Moves to the first or the last button. |
+ * | Space, Enter | Presses or releases the focused button. |
+ *
+ * Left and Right swap on a right-to-left page, and a disabled button is
+ * passed over. In a selection mode the group is a `toolbar`, with
+ * `aria-orientation` under `orientation="vertical"`. Inside a toolbar it stays
+ * a named `group`, and the toolbar's own arrow keys walk its buttons, so a
+ * reader meets one toolbar.
+ *
  * @since 0.1.0
  * @status stable
  * @category actions
- * @aliases Segmented buttons, Split button
+ * @aliases Segmented buttons, Split button, Toggle buttons
  * @documentation https://fusion.dev/helix/components/button-group
  *
  * @slot - The buttons in the group.
+ *
+ * @event {Event} change - Fired after a press changes `value`, in a selection mode.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before a press changes `value`, with the value it would leave in `detail.value`. Cancelable: call `preventDefault()` to keep the buttons as they are.
+ *
+ * @cssproperty --button-group-pressed - Written on the control inside each toggle button of a group with `selection-mode`: `1` while it is pressed and `0` while it is not. Read it in a `::part(button)` rule to draw the pressed look.
  */
 export declare class HelixHeadlessButtonGroup extends HelixElement {
     /**
@@ -51,8 +94,106 @@ export declare class HelixHeadlessButtonGroup extends HelixElement {
      * column.
      */
     orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether the buttons stay pressed: `single` keeps one pressed at a time and
+     * `multiple` any number. Unset, they are action buttons, each its own tab
+     * stop, as before.
+     *
+     * Optional, so the attribute is absent until a consumer writes it.
+     */
+    selectionMode?: 'multiple' | 'single';
+    /**
+     * The values of the pressed buttons, comma separated, in a selection mode.
+     * A button's own `value` names it, so a value holds no comma.
+     *
+     * The attribute is the seed, and a press changes the property, which does
+     * not reflect, as a native control's `value` does not.
+     */
+    value: string;
+    /**
+     * The Helix buttons of a group in a selection mode, in the order they are
+     * written, and none otherwise. Empty on a server, which has no tree.
+     */
+    private get buttons();
+    /**
+     * Whether the group holds the tab stop and the arrow keys: in a selection
+     * mode, and not inside a toolbar, whose own keys walk the buttons.
+     *
+     * Truthiness, as `buttons` reads it: a removed attribute leaves the property
+     * null, which is no selection mode.
+     */
+    private get roving();
+    /** Whether a button is pressed: its value is among the group's. */
+    private pressed;
+    /** The button focus was last on, which holds the tab stop. */
+    private lastFocused;
+    /**
+     * The buttons this group has told something, each with whether it moved
+     * their tab stop, so a button that leaves the group, or a group that leaves
+     * its selection mode, is put back as it was.
+     */
+    private readonly told;
+    private watcher;
+    /**
+     * Tells every button whether it is pressed and whether it holds the stop,
+     * and puts back the ones that left.
+     */
+    private sync;
+    /** Whether this group has said a native button in it cannot be a toggle, so it says so once. */
+    private warned;
+    /**
+     * Says once that a native `<button>` in a selection mode stays an action
+     * button, since its pressed state would be an attribute on the page's markup.
+     * One with its own `aria-pressed` is the page's to say, and is not reported.
+     */
+    private warn;
+    /**
+     * Writes a button's pressed state onto its control, once the button has
+     * rendered it, and takes it off a button the group no longer holds.
+     *
+     * **On the control inside the button's shadow root, never on the button.**
+     * An attribute written on the consumer's element is a hydration mismatch a
+     * React consumer's hydration reports and does not patch up, which is why
+     * `tellDisclosure` hands a trigger `expanded` as a property. Inside the
+     * button's own shadow root no framework compares the attribute, and the
+     * reader is on that control. Read at the moment of the write, so the last
+     * press wins whatever order renders finish in.
+     *
+     * The control is the `<button>` a Helix button renders, which is where its
+     * `delegatesFocus` sends focus and what a reader is on.
+     *
+     * A button that carries `aria-pressed` itself is the consumer's to say, and
+     * its own forwarding carries that down instead.
+     */
+    private mark;
+    /**
+     * Says on a button's control whether it is pressed, or that it is no toggle
+     * at all where `pressed` is undefined. A styled tier draws the look here.
+     *
+     * @param control The focusable control inside the button's shadow root.
+     * @param pressed Whether the button is pressed, or undefined where it is not a toggle.
+     */
+    protected markPressed(control: HTMLElement, pressed: boolean | undefined): void;
+    /**
+     * Presses or releases the button a press acted on. `helix-press` rather than
+     * `click`, since a button sends it only for a press that acted: never while
+     * it is disabled or pending.
+     */
+    private readonly handlePress;
+    /**
+     * Moves focus between the buttons without pressing them, a toolbar's
+     * reading: a press is its own act, on Space or Enter, which the button
+     * answers natively. Both axes, as every set here answers both, and the
+     * horizontal pair turns on a right-to-left page.
+     */
+    private readonly handleKeydown;
+    /** Moves the tab stop to the button focus arrived on. */
+    private readonly noteFocus;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {

package/dist/button-group/root/button-group-root.js

@@ -4,22 +4,156 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { auditName, customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { auditName, commaList, customElement, HelixElement, hostAria, inlineStep, pressedValue, reportRuntime, requestValue, rovingStop, toolbarAround, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { arrowTarget } from '../arrows.js';
+const isGroupButton = (child) => child instanceof HTMLElement && 'focusable' in child && 'value' in child;
 let HelixHeadlessButtonGroup = class HelixHeadlessButtonGroup extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
+        this.value = '';
+        this.lastFocused = undefined;
+        this.told = new Map();
+        this.warned = false;
+        this.handlePress = (event) => {
+            const mode = this.selectionMode;
+            const button = this.buttons.find((one) => event.composedPath().includes(one));
+            if (mode && button && button.value !== '') {
+                requestValue(this, pressedValue(mode, this.value, button.value), (next) => {
+                    this.value = next;
+                });
+            }
+        };
+        this.handleKeydown = (event) => {
+            const buttons = this.roving ? this.buttons.filter((one) => one.disabled !== true) : [];
+            const from = buttons.findIndex((one) => event.composedPath().includes(one));
+            const to = arrowTarget(event.key, inlineStep(this, event.key), from, buttons.length);
+            if (to >= 0 && !event.defaultPrevented) {
+                event.preventDefault();
+                buttons[to]?.focus();
+            }
+        };
+        this.noteFocus = (event) => {
+            const button = this.buttons.find((one) => event.composedPath().includes(one));
+            if (button && button !== this.lastFocused) {
+                this.lastFocused = button;
+                this.sync();
+            }
+        };
+    }
+    get buttons() {
+        return this.selectionMode && this.children ? [...this.children].filter(isGroupButton) : [];
+    }
+    get roving() {
+        return Boolean(this.selectionMode) && toolbarAround(this) === null;
+    }
+    pressed(button) {
+        return button.value !== '' && commaList(this.value).includes(button.value);
+    }
+    sync() {
+        const buttons = this.buttons;
+        const roving = this.roving;
+        const stop = roving
+            ? rovingStop(buttons, this.lastFocused, {
+                disabled: (button) => button.disabled === true,
+                selected: (button) => this.pressed(button),
+            })
+            : undefined;
+        for (const [button, roved] of this.told) {
+            if (!buttons.includes(button)) {
+                this.told.delete(button);
+                this.mark(button);
+                if (roved) {
+                    whenHydrated(button, () => {
+                        button.focusable = true;
+                    });
+                }
+            }
+        }
+        for (const button of buttons) {
+            this.told.set(button, roving);
+            this.mark(button);
+            if (roving) {
+                whenHydrated(button, () => {
+                    button.focusable = button === stop;
+                });
+            }
+        }
+        for (const child of this.selectionMode && this.children ? this.children : []) {
+            if (child.localName.includes('-') && !isGroupButton(child)) {
+                void customElements.whenDefined(child.localName).then(() => this.sync());
+            }
+            else if (child.localName === 'button' && !child.hasAttribute('aria-pressed')) {
+                this.warn(child);
+            }
+        }
+    }
+    warn(button) {
+        if (this.warned) {
+            return;
+        }
+        this.warned = true;
+        reportRuntime({
+            kind: 'untold-toggle',
+            message: `<${this.localName}> cannot press a native <button>: its state would be written onto your ` +
+                'markup. Slot a Helix button with a `value`, or set `aria-pressed` on the button yourself.',
+            tag: button.localName,
+        });
+    }
+    mark(button) {
+        void button.updateComplete.then(() => {
+            const control = button.shadowRoot?.querySelector('button');
+            if (control && !button.hasAttribute('aria-pressed')) {
+                const toggle = this.told.has(button) && button.value !== '';
+                this.markPressed(control, toggle ? this.pressed(button) : undefined);
+            }
+        });
+    }
+    markPressed(control, pressed) {
+        if (pressed === undefined) {
+            control.removeAttribute('aria-pressed');
+        }
+        else {
+            control.setAttribute('aria-pressed', String(pressed));
+        }
+        control.style.setProperty('--button-group-pressed', pressed === undefined ? '' : pressed ? '1' : '0');
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('focusin', this.noteFocus);
+        this.addEventListener('helix-press', this.handlePress);
+        this.addEventListener('keydown', this.handleKeydown);
+        this.watcher = new MutationObserver(() => this.sync());
+        this.watcher.observe(this, {
+            attributeFilter: ['disabled', 'value'],
+            childList: true,
+            subtree: true,
+        });
+        this.requestUpdate();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('focusin', this.noteFocus);
+        this.removeEventListener('helix-press', this.handlePress);
+        this.removeEventListener('keydown', this.handleKeydown);
+        this.watcher?.disconnect();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        hostAria(this.internals, { label: this.label, role: 'group' });
+        const toolbar = this.roving;
+        hostAria(this.internals, { label: this.label, role: toolbar ? 'toolbar' : 'group' });
+        this.internals.ariaOrientation = toolbar ? (this.orientation ?? null) : null;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         auditName(this, () => null, 'Give it a `label`, or an `aria-label` that says what the buttons are for.', () => this.label !== '');
     }
+    updated(changed) {
+        super.updated(changed);
+        this.sync();
+    }
     render() {
         return html `<slot></slot>`;
     }
@@ -30,6 +164,12 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessButtonGroup.prototype, "orientation", void 0);
+__decorate([
+    property({ attribute: 'selection-mode', reflect: true })
+], HelixHeadlessButtonGroup.prototype, "selectionMode", void 0);
+__decorate([
+    property()
+], HelixHeadlessButtonGroup.prototype, "value", void 0);
 HelixHeadlessButtonGroup = __decorate([
     customElement('helix-headless-button-group')
 ], HelixHeadlessButtonGroup);

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

@@ -42,6 +42,11 @@ declare const HelixHeadlessCallout_base: (new (...args: any[]) => import("@fusio
  * @csspart icon-mark - The icon for the tone, shown when no icon is slotted.
  */
 export declare class HelixHeadlessCallout extends HelixHeadlessCallout_base {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-callout': { toneLabels: { danger: 'Fehler' } } })`.
+     */
+    static words: string;
     protected willUpdate(changed: PropertyValues): void;
     /**
      * What kind of attention the passage needs.
@@ -55,10 +60,19 @@ export declare class HelixHeadlessCallout extends HelixHeadlessCallout_base {
     /**
      * What a screen reader is told the tone is, such as "Fehler".
      *
-     * Absent is the English for the tone: "Error", "Information", "Note",
-     * "Success" or "Warning".
+     * Absent is the tone's words in `tone-labels`, "Error", "Information",
+     * "Note", "Success" or "Warning" in English.
      */
     toneLabel: string;
+    /**
+     * What a screen reader is told each tone is, by the tone's name, written as
+     * JSON in the attribute: `tone-labels='{"danger":"Fehler"}'`. A tone left
+     * out keeps its English, and `tone-label` wins over both.
+     *
+     * `danger` is said as "Error", the word a reader understands, and
+     * `neutral` as "Note", for what the passage is.
+     */
+    toneLabels: Partial<Record<'danger' | 'info' | 'neutral' | 'success' | 'warning', string>>;
     /**
      * The mark for the callout's tone, behind a seam.
      *

package/dist/callout/root/callout-root.js

@@ -4,16 +4,23 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, drawDismiss, drawDismissGlyph, HelixElement, hostAria, MixinDismissible, TONE_MARKS, toneMark, } from '@fusion.dev/helix-core';
+import { customElement, drawDismiss, drawDismissGlyph, HelixElement, hostAria, MixinDismissible, TONE_MARKS, toneMark, words, wordsConverter, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-const NOTE = { icon: TONE_MARKS.info.icon, label: 'Note' };
 let HelixHeadlessCallout = class HelixHeadlessCallout extends MixinDismissible(HelixElement) {
     constructor() {
         super(...arguments);
         this.toneLabel = '';
+        this.toneLabels = {
+            danger: 'Error',
+            info: 'Information',
+            neutral: 'Note',
+            success: 'Success',
+            warning: 'Warning',
+        };
     }
+    static { this.words = 'helix-callout'; }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'note' });
@@ -31,8 +38,9 @@ let HelixHeadlessCallout = class HelixHeadlessCallout extends MixinDismissible(H
     </slot>`;
     }
     render() {
-        const { icon, label } = this.tone === 'neutral' ? NOTE : (toneMark(this.tone) ?? TONE_MARKS.info);
-        const named = this.toneLabel || label;
+        const tone = this.tone === 'neutral' ? 'neutral' : toneMark(this.tone) ? (this.tone ?? 'info') : 'info';
+        const { icon } = toneMark(tone) ?? TONE_MARKS.info;
+        const named = this.toneLabel || (this.toneLabels[tone] ?? '');
         return html `<span part="icon" role="img" aria-label=${named}>${this.renderIcon(icon, named)}</span>
       <div part="content">
         <slot name="heading"></slot>
@@ -52,6 +60,10 @@ __decorate([
 __decorate([
     property({ attribute: 'tone-label' })
 ], HelixHeadlessCallout.prototype, "toneLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'tone-labels', converter: wordsConverter })
+], HelixHeadlessCallout.prototype, "toneLabels", void 0);
 HelixHeadlessCallout = __decorate([
     customElement('helix-headless-callout')
 ], HelixHeadlessCallout);

package/dist/canvas/describe.d.ts

@@ -0,0 +1,10 @@
+/**
+ * The words that describe a card or a connection, such as whether it is
+ * selected, what its tone means and where its connections go, as one list in
+ * the way `locale` writes one: "selected, Blocked" in English, "selected und
+ * Blocked" in German. An empty word is left out, and nothing at all is empty.
+ *
+ * **A narrow conjunction**, which English writes with commas alone, so the
+ * English reads as it did when the words were joined with a comma.
+ */
+export declare const descriptionOf: (locale: string, words: readonly (string | undefined)[]) => string;

package/dist/canvas/describe.js

@@ -0,0 +1,9 @@
+const formatters = new Map();
+export const descriptionOf = (locale, words) => {
+    let found = formatters.get(locale);
+    if (!found) {
+        found = new Intl.ListFormat(locale || undefined, { style: 'narrow', type: 'conjunction' });
+        formatters.set(locale, found);
+    }
+    return found.format(words.filter((one) => Boolean(one)));
+};

package/dist/canvas/edge-pan.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Moving the view while something is carried to its edge: a card, a corner, a
+ * connection being drawn, or the box that selects.
+ *
+ * **A board is larger than its box, and a hand stops at the edge of the box.**
+ * Without this, carrying a card to a place off screen took a drop at the edge,
+ * a pan, and a second pick-up, and a connection to a card off screen could not
+ * be drawn by pointer at all.
+ */
+/** A point on screen, in pixels. */
+export interface EdgePoint {
+    x: number;
+    y: number;
+}
+/** The box the view is drawn in, on screen. */
+export interface EdgeRect {
+    bottom: number;
+    left: number;
+    right: number;
+    top: number;
+}
+/** How near an edge, in pixels, the view starts to move. */
+export declare const EDGE_ZONE = 32;
+/** The most the view moves in one frame, in pixels: at the edge and past it. */
+export declare const EDGE_MOST = 12;
+/**
+ * How far the view should move toward each side in one frame, in pixels, for
+ * a pointer at `point`: positive toward the right and the bottom, nothing
+ * outside the zone, and faster the nearer the edge, up to `most` at it and
+ * past it.
+ *
+ * A box narrower than two zones moves only once the pointer is past its edge,
+ * so a small board is not always moving.
+ */
+export declare const edgeSpeed: (point: EdgePoint, rect: EdgeRect, zone?: number, most?: number) => EdgePoint;
+/**
+ * The frames that move the view while a pointer holds something near an edge.
+ *
+ * `follow` with every pointer move keeps it going while the pointer is in the
+ * zone, and `stop` ends it, which the board calls when the gesture ends and
+ * when it leaves the page. Each frame hands `step` how far to move, and the
+ * board moves the view and carries what is in hand with it.
+ */
+export declare class EdgePan {
+    private readonly rect;
+    private readonly step;
+    private readonly ended;
+    /** The frame asked for, while the view is moving. */
+    private frame;
+    /** Where the pointer last was. */
+    private point;
+    constructor(rect: () => EdgeRect | undefined, step: (by: EdgePoint) => void, ended?: () => void);
+    /** Whether the view is moving. */
+    get moving(): boolean;
+    /** Where the pointer is now, which starts the frames where it is in the zone. */
+    follow(point: EdgePoint): void;
+    /** Ends the frames. */
+    stop(): void;
+    private speed;
+    private readonly tick;
+}

package/dist/canvas/edge-pan.js

@@ -0,0 +1,63 @@
+export const EDGE_ZONE = 32;
+export const EDGE_MOST = 12;
+export const edgeSpeed = (point, rect, zone = EDGE_ZONE, most = EDGE_MOST) => {
+    const along = (at, start, end) => {
+        if (at >= end) {
+            return 1;
+        }
+        if (at <= start) {
+            return -1;
+        }
+        const reach = end - start < zone * 2 ? 0 : zone;
+        if (reach > 0 && at > end - reach) {
+            return (at - (end - reach)) / reach;
+        }
+        if (reach > 0 && at < start + reach) {
+            return -(start + reach - at) / reach;
+        }
+        return 0;
+    };
+    return {
+        x: Math.round(along(point.x, rect.left, rect.right) * most),
+        y: Math.round(along(point.y, rect.top, rect.bottom) * most),
+    };
+};
+export class EdgePan {
+    constructor(rect, step, ended = () => undefined) {
+        this.rect = rect;
+        this.step = step;
+        this.ended = ended;
+        this.tick = () => {
+            const by = this.speed();
+            if (by.x === 0 && by.y === 0) {
+                this.frame = undefined;
+                this.ended();
+                return;
+            }
+            this.step(by);
+            this.frame = requestAnimationFrame(this.tick);
+        };
+    }
+    get moving() {
+        return this.frame !== undefined;
+    }
+    follow(point) {
+        this.point = point;
+        const by = this.speed();
+        if (this.frame === undefined && (by.x !== 0 || by.y !== 0)) {
+            this.frame = requestAnimationFrame(this.tick);
+        }
+    }
+    stop() {
+        this.point = undefined;
+        if (this.frame !== undefined) {
+            cancelAnimationFrame(this.frame);
+            this.frame = undefined;
+            this.ended();
+        }
+    }
+    speed() {
+        const rect = this.rect();
+        return this.point && rect ? edgeSpeed(this.point, rect) : { x: 0, y: 0 };
+    }
+}

package/dist/canvas/neighbor.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Where focus goes when a stop on a board leaves: the arithmetic, kept apart
+ * from the board that moves focus there.
+ *
+ * Shared by the two ways a stop leaves, Delete and the page taking it away,
+ * so a reader lands in the same place either way.
+ */
+/**
+ * The first stop after `at` in `walk` that `kept` keeps, or, with none after
+ * it, the nearest one before it. Undefined where none is kept.
+ *
+ * @param walk Every stop's key, in the order the arrow keys walk them.
+ * @param at Where the stop that left was, as an index into `walk`, or `-1`
+ *   for nowhere, which takes the first stop kept.
+ * @param kept Whether a stop is still there.
+ */
+export declare const neighborOf: (walk: readonly string[], at: number, kept: (key: string) => boolean) => string | undefined;

package/dist/canvas/neighbor.js

@@ -0,0 +1 @@
+export const neighborOf = (walk, at, kept) => walk.slice(at + 1).find(kept) ?? walk.slice(0, Math.max(at, 0)).reverse().find(kept);

package/dist/canvas/node/canvas-node.d.ts

@@ -150,6 +150,16 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      * point and one to a circle on its curve without the board knowing which.
      */
     shape?: 'circle' | 'diamond' | 'pill' | 'square';
+    /**
+     * @internal What the card's state adds to what it says, in the page's words,
+     * written by the board: its `selected-label` while it is selected. Read
+     * first, before what the tone means.
+     *
+     * **A selection a reader cannot see has to be said.** A card is an article,
+     * and an article has no selected state for `aria-selected` to carry, so a
+     * reader who selected three cards heard nothing on any of them.
+     */
+    status: string;
     /**
      * @internal Whether this is the card the reader selected, written by the
      * board. Kept apart from focus, so a reader who clicks a button beside the
@@ -211,8 +221,8 @@ export declare class HelixHeadlessCanvasNode extends HelixElement {
      */
     focus(options?: FocusOptions): void;
     /**
-     * The card, and the sentence that says what its tone means and where it
-     * leads.
+     * The card, and the sentence that says whether it is selected, what its
+     * tone means and where it leads.
      *
      * **`aria-describedby` at a hidden element, which is allowed and is the
      * point.** A description is computed from its target whether or not the

package/dist/canvas/node/canvas-node.js

@@ -4,9 +4,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, PlacementController } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, PlacementController, wordsLocale, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { descriptionOf } from '../describe.js';
 const DRAWN = [
     'group',
     'height',
@@ -33,6 +34,7 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
         this.links = '';
         this.meaning = '';
         this.readOnly = false;
+        this.status = '';
         this.selected = false;
         this.movable = false;
         this.resizable = false;
@@ -72,7 +74,7 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
           </svg>`
             : nothing}<div
       part="node"
-      aria-describedby=${this.meaning || this.links ? 'about' : nothing}
+      aria-describedby=${this.status || this.meaning || this.links ? 'about' : nothing}
       aria-label=${this.label || nothing}
       aria-labelledby=${this.label || this.group ? nothing : 'content'}
       aria-keyshortcuts=${this.connectable ? 'Enter F2 Space Shift+ArrowRight Shift+ArrowDown Alt+ArrowRight Alt+ArrowDown C Delete' : nothing}
@@ -81,7 +83,7 @@ let HelixHeadlessCanvasNode = class HelixHeadlessCanvasNode extends HelixElement
     >
       <slot id="content"></slot>
       <slot name="description"></slot>
-      <span id="about" hidden>${[this.meaning, this.links].filter(Boolean).join(', ')}</span>
+      <span id="about" hidden>${descriptionOf(wordsLocale(this), [this.status, this.meaning, this.links])}</span>
     </div>
     ${this.connectable
             ? html `<span part="handle handle-top" aria-hidden="true" data-side="top"></span>
@@ -131,6 +133,9 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessCanvasNode.prototype, "shape", void 0);
+__decorate([
+    state()
+], HelixHeadlessCanvasNode.prototype, "status", void 0);
 __decorate([
     state()
 ], HelixHeadlessCanvasNode.prototype, "selected", void 0);