@fusion.dev/helix-headless 0.142.1 → 0.144.0

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

@@ -10,24 +10,32 @@ declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusio
  * does not clip it and no `z-index` is needed. `FloatingController` positions
  * it and flips it to another side when the preferred side does not fit.
  *
- * Wrapping the trigger is the convenient form. Use it where the trigger already
- * has an accessible name, because the tooltip cannot describe a slotted
- * trigger: an IDREF cannot cross a shadow boundary.
- *
- * To add a description, place the tooltip beside the trigger and name the
- * trigger with `for`:
+ * **The tooltip describes its trigger itself, in both forms.** Wrap the
+ * trigger, or place the tooltip beside it and name the trigger with `for`:
  *
  * ```html
- * <helix-headless-button id="save" aria-describedby="save-tip">Save</helix-headless-button>
- * <helix-headless-tooltip id="save-tip" for="save" content="Save your work"></helix-headless-tooltip>
+ * <helix-headless-button id="save">Save</helix-headless-button>
+ * <helix-headless-tooltip for="save" content="Save your work"></helix-headless-tooltip>
  * ```
  *
- * Write the `aria-describedby` yourself, pointing at the tooltip host. Setting
- * it at runtime causes a hydration mismatch that React does not fix. With
- * `for`, the tooltip warns once on first open if the attribute is missing.
+ * The link is an element reference on the control that takes focus, and it is
+ * never written into your markup before a reader has acted. A trigger that is a
+ * Helix component is described at once, inside its own shadow root. A plain
+ * element in your markup is described when a reader first points at it or
+ * focuses it, which is after any hydration, and only where you have written no
+ * `aria-describedby` or `aria-labelledby` of your own. Write
+ * `aria-describedby` pointing at the tooltip yourself to have the link in the
+ * server's markup. Where the browser has no element references, write it
+ * yourself; the tooltip warns once on first open if nothing links the two.
  *
  * The tooltip shows on hover and on focus. It hides on pointer leave, on blur,
- * on Escape, and when the trigger is activated.
+ * on Escape, and when the trigger is activated. The pointer can move from the
+ * trigger onto the bubble and the bubble stays.
+ *
+ * Once one tooltip is showing, moving to another trigger shows its tooltip
+ * with no `delay`, and the first one hides. The same holds for `skip-delay`
+ * milliseconds after a tooltip hides, 300 unless you set it. `show-on="focus"`
+ * shows the tooltip on keyboard focus only, for a hint a pointer does not need.
  *
  * @since 0.1.0
  * @status stable
@@ -35,13 +43,14 @@ declare const HelixHeadlessTooltip_base: (new (...args: any[]) => import("@fusio
  * @aliases Hint, Popup label
  * @documentation https://fusion.dev/helix/components/tooltip
  *
- * @slot - The trigger: the element the tooltip describes.
+ * @slot - The trigger, in the wrapping form. The tooltip describes it, as it
+ * describes the element `for` names.
  * @slot content - Rich content for the bubble. It replaces the `content`
  * property.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - The bubble is about to hide. Cancelable: cancel it to keep it shown.
  * @event {HelixBeforeOpenEvent} helix-before-open - The bubble is about to show. Cancelable: cancel it to keep it hidden.
- * @event {Event} toggle - The bubble opened or closed. The event carries `newState` and `oldState`.
+ * @event {ToggleEvent} toggle - The bubble opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart arrow - The arrow that points at the trigger.
  * @csspart arrow-bottom - Added to `arrow` while the bubble is below its trigger, with the arrow on the bubble's top edge.
@@ -142,6 +151,18 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * It moves if that side does not fit.
      */
     placement: Placement;
+    /**
+     * What shows the bubble. Unset, it is a pointer resting on the trigger and
+     * keyboard focus. `focus` is keyboard focus alone, for a hint a pointer does
+     * not need, such as a shortcut a mouse reader has no use for.
+     */
+    showOn?: 'focus';
+    /**
+     * How long after a tooltip hides the next one still shows at once, with no
+     * `delay`, in milliseconds. The same skip delay Radix uses. Zero makes every
+     * tooltip wait.
+     */
+    skipDelay: number;
     /**
      * The id of a box to keep the bubble inside. Defaults to the viewport.
      *
@@ -249,8 +270,27 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * the reader had moved on to.
      */
     hide(): void;
-    /** Shows after the pointer has rested for `delay`. */
+    /**
+     * Shows after the pointer has rested for `delay`, or at once while the
+     * tooltips are warm.
+     *
+     * **Warm is another tooltip showing, or one that hid within `skipDelay`.**
+     * A reader scanning a toolbar has already waited once, and waiting again on
+     * every control turns the scan into a series of pauses.
+     */
     private readonly showLater;
+    /**
+     * The pointer reached the bubble, in the `for` form.
+     *
+     * The bubble is not inside the element `for` names, so moving onto it leaves
+     * the trigger and would hide it after `delay-out`. WCAG 1.4.13 asks that a
+     * reader can move onto it, to read it under a magnifier or to select its
+     * text. Wrapping, the bubble is inside the host and the host's own pointer
+     * listeners already hold it.
+     */
+    private readonly holdOnBubble;
+    /** The pointer left the bubble, in the `for` form. */
+    private readonly leaveBubble;
     /** Hides after `delayOut`, so crossing the gap to the bubble does not close it. */
     private readonly hideLater;
     /**
@@ -318,6 +358,17 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * have upgraded, or existed, when this one connected.
      */
     private bind;
+    /** The control this tooltip has described, so the link can be taken back. */
+    private linked;
+    /**
+     * Describes the control that takes the trigger's focus by this tooltip.
+     *
+     * `light` says a reader has just acted, which is what allows a write onto a
+     * plain element in the consumer's markup. See `linkDescription`.
+     */
+    private link;
+    /** A reader arriving on the trigger, which is late enough to write the link. */
+    private readonly linkOnArrival;
     private unbind;
     /** Said once per element, however many times it opens. */
     private audited;
@@ -342,6 +393,13 @@ export declare class HelixHeadlessTooltip extends HelixHeadlessTooltip_base {
      * this should not be the thing to settle it.
      */
     private auditDescription;
+    /**
+     * Whether the wrapped trigger's own name is the tooltip's text.
+     *
+     * The name a consumer writes: `aria-label`, then a `label` a Helix control
+     * renders as its name, then the trigger's text.
+     */
+    private triggerSays;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;

package/dist/tooltip/root/tooltip-root.js

@@ -4,10 +4,17 @@ 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 { anchorElement, customElement, elementById, HelixElement, hostAria, MixinControllerOpen, PopoverController, reportRuntime, } from '@fusion.dev/helix-core';
+import { anchorElement, arrowReach, customElement, elementById, HelixElement, hostAria, linkDescription, MixinControllerOpen, PopoverController, reportRuntime, sideOf, unlinkDescription, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { focusTarget } from '../focus-target.js';
 const GENERIC = new Set(['div', 'p', 'section', 'span']);
+const WARMTH = Symbol.for('fusion.helix.tooltip.warmth');
+const warmth = () => {
+    const globals = globalThis;
+    globals[WARMTH] ??= { hidAt: Number.NEGATIVE_INFINITY, showing: new Set() };
+    return globals[WARMTH];
+};
 let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
@@ -19,22 +26,20 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         this.offset = 8;
         this.persist = false;
         this.placement = 'top';
+        this.skipDelay = 300;
         this.within = '';
         this.holds = new Set();
         this.bubbleLayer = new PopoverController(this, {
             anchor: () => this.trigger,
             arrow: () => this.partNamed('arrow'),
             boundary: () => [this, this.named],
-            offset: () => {
-                const point = this.partNamed('arrow');
-                return this.offset + (point?.offsetWidth ?? 0) / Math.SQRT2;
-            },
+            offset: () => this.offset + arrowReach(this.partNamed('arrow')),
             onDismiss: () => {
                 this.holds.clear();
                 this.hide();
             },
             onPlace: (placement) => {
-                const side = placement.split('-')[0];
+                const side = sideOf(placement);
                 this.toggleState('placed-bottom', side === 'bottom');
                 this.toggleState('placed-left', side === 'left');
                 this.toggleState('placed-right', side === 'right');
@@ -49,10 +54,31 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             this.requestUpdate();
         };
         this.showLater = () => {
+            if (this.showOn === 'focus') {
+                return;
+            }
             this.holds.add('pointer');
             clearTimeout(this.timer);
+            const warm = warmth();
+            const others = [...warm.showing].some((one) => one !== this);
+            if (others || performance.now() - warm.hidAt < this.skipDelay) {
+                this.show();
+                return;
+            }
             this.timer = setTimeout(() => this.show(), this.delay);
         };
+        this.holdOnBubble = () => {
+            if (!this.named) {
+                return;
+            }
+            this.holds.add('pointer');
+            clearTimeout(this.timer);
+        };
+        this.leaveBubble = () => {
+            if (this.named) {
+                this.hideLater();
+            }
+        };
         this.hideLater = () => {
             this.holds.delete('pointer');
             clearTimeout(this.timer);
@@ -77,6 +103,10 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             this.holds.clear();
             this.hide();
         };
+        this.linkOnArrival = (event) => {
+            const first = event.composedPath()[0];
+            this.link(true, event.type === 'focusin' && first instanceof Element ? first : undefined);
+        };
         this.audited = false;
     }
     get trigger() {
@@ -154,14 +184,41 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             return;
         }
         this.unbind();
+        target.addEventListener('pointerenter', this.linkOnArrival);
+        target.addEventListener('focusin', this.linkOnArrival);
         target.addEventListener('pointerenter', this.showLater);
         target.addEventListener('pointerleave', this.hideLater);
         target.addEventListener('focusin', this.showNow);
         target.addEventListener('focusout', this.releaseFocus);
         target.addEventListener('click', this.handleActivate);
         this.bound = target;
+        this.link(false);
+        const drawn = this.trigger.updateComplete;
+        void drawn?.then(() => {
+            if (this.bound === target) {
+                this.link(false);
+            }
+        });
+    }
+    link(light, target = focusTarget(this.trigger)) {
+        if (this.linked === target) {
+            return;
+        }
+        if (this.linked) {
+            unlinkDescription(this.linked, this);
+            this.linked = undefined;
+        }
+        if (linkDescription(target, this, light)) {
+            this.linked = target;
+        }
     }
     unbind() {
+        if (this.linked) {
+            unlinkDescription(this.linked, this);
+            this.linked = undefined;
+        }
+        this.bound?.removeEventListener('pointerenter', this.linkOnArrival);
+        this.bound?.removeEventListener('focusin', this.linkOnArrival);
         this.bound?.removeEventListener('pointerenter', this.showLater);
         this.bound?.removeEventListener('pointerleave', this.hideLater);
         this.bound?.removeEventListener('click', this.handleActivate);
@@ -174,7 +231,13 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             return;
         }
         this.audited = true;
+        if (this.linked) {
+            return;
+        }
         if (this.for === '') {
+            if (this.triggerSays(this.describedText)) {
+                return;
+            }
             reportRuntime({
                 kind: 'wrapped-trigger',
                 message: `<${this.localName}> is wrapping its trigger rather than naming one, so its text ` +
@@ -211,6 +274,12 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             tag: this.localName,
         });
     }
+    triggerSays(text) {
+        const flat = (words) => (words ?? '').replace(/\s+/gu, ' ').trim();
+        const trigger = this.trigger;
+        const name = trigger.getAttribute('aria-label') ?? trigger.getAttribute('label') ?? trigger.textContent;
+        return text !== '' && flat(name) === flat(text);
+    }
     connectedCallback() {
         super.connectedCallback();
         if (this.hasUpdated) {
@@ -222,6 +291,7 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         this.unbind();
         this.holds.clear();
         clearTimeout(this.timer);
+        warmth().showing.delete(this);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -233,11 +303,22 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
             this.bind();
         }
         if (changed.has('open')) {
+            const warm = warmth();
             if (this.open) {
+                for (const other of [...warm.showing]) {
+                    if (other !== this) {
+                        other.holds.clear();
+                        other.hide();
+                    }
+                }
+                warm.showing.add(this);
                 this.bubbleLayer.show();
                 this.auditDescription();
             }
             else {
+                if (warm.showing.delete(this)) {
+                    warm.hidAt = performance.now();
+                }
                 this.bubbleLayer.hide();
             }
         }
@@ -247,7 +328,7 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         }
         hostAria(this.internals, {
             describedBy: this.hasContent ? [bubble] : [],
-            label: this.for === '' ? '' : this.describedText,
+            label: this.describedText,
         });
     }
     render() {
@@ -257,6 +338,8 @@ let HelixHeadlessTooltip = class HelixHeadlessTooltip extends MixinControllerOpe
         part="tooltip${side ? { bottom: ' tooltip-bottom', left: ' tooltip-left', right: ' tooltip-right', top: ' tooltip-top' }[side] : ''}"
         popover="manual"
         role="tooltip"
+        @pointerenter=${this.holdOnBubble}
+        @pointerleave=${this.leaveBubble}
       >
         <span
           part="arrow${side ? { bottom: ' arrow-bottom', left: ' arrow-left', right: ' arrow-right', top: ' arrow-top' }[side] : ''}"
@@ -291,6 +374,12 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessTooltip.prototype, "placement", void 0);
+__decorate([
+    property({ attribute: 'show-on' })
+], HelixHeadlessTooltip.prototype, "showOn", void 0);
+__decorate([
+    property({ attribute: 'skip-delay', type: Number })
+], HelixHeadlessTooltip.prototype, "skipDelay", void 0);
 __decorate([
     property()
 ], HelixHeadlessTooltip.prototype, "within", void 0);

package/dist/tour/naming.d.ts

@@ -0,0 +1,30 @@
+/** What names and describes a stop's panel. */
+export interface StopNaming {
+    /** The elements that describe the panel, in reading order. */
+    describedBy: Element[];
+    /** The elements that name the panel, or none where a label names it. */
+    labelledBy: Element[];
+}
+/** Where a stop's words are. */
+export interface StopWords {
+    /** The elements in the stop's default slot. */
+    content: readonly Element[];
+    /** The elements in its `description` slot. */
+    description: readonly Element[];
+    /** The elements in its `heading` slot. */
+    heading: readonly Element[];
+    /** Whether the stop has a `label` of its own. */
+    labeled: boolean;
+    /** The element that says the stop's place in the tour, such as "2 of 5". */
+    progress: Element | null;
+}
+/**
+ * What names a tour stop's panel and what describes it.
+ *
+ * Named by the `heading` slot, then by the first heading in the content, then
+ * by the stop's own `label`, and where there is none of those, by its place in
+ * the tour, so no stop is an unnamed group. Described by the `description`
+ * slot and by its place, which is how a screen reader hears where it is as
+ * focus moves from one stop to the next.
+ */
+export declare const stopNaming: ({ content, description, heading, labeled, progress, }: StopWords) => StopNaming;

package/dist/tour/naming.js

@@ -0,0 +1,10 @@
+import { headingIn } from '@fusion.dev/helix-core';
+export const stopNaming = ({ content, description, heading, labeled, progress, }) => {
+    const first = heading.length > 0 ? null : headingIn(content);
+    const found = heading.length > 0 ? [...heading] : first ? [first] : [];
+    const place = progress ? [progress] : [];
+    if (found.length === 0 && !labeled) {
+        return { describedBy: [...description], labelledBy: place };
+    }
+    return { describedBy: [...description, ...place], labelledBy: found };
+};

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

@@ -1,6 +1,7 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
+declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
  * @summary A guided tour of an interface, one stop at a time.
  *
@@ -17,6 +18,23 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  * The root measures the target's position in the browser. Nothing is measured
  * on the server, because a tour starts only on request.
  *
+ * `open`, `default-open`, `helix-before-open`, `helix-before-close` and
+ * `toggle` work as they do on `Dialog`. Setting `open` starts the run, and
+ * `skip()` and `requestOpen(false)` end it early.
+ *
+ * Each stop is told its place in the run, from `progress-label`, such as "2 of
+ * 5". It describes the stop's panel, so a screen reader says it at every stop,
+ * and `progress` draws it in the panel as well. A dialog or a floating stop,
+ * which has nothing to light, is shown over the `backdrop` part. At a `wait`
+ * stop the run waits for that stop's target to be on the page, and moves on by
+ * itself.
+ *
+ * **Focus follows the run.** Opening moves focus to the first stop's panel,
+ * and moving on from a control in a stop moves it to the next one. Ending the
+ * tour puts focus back on the element that had it when the tour opened, unless
+ * you have moved it somewhere else on the page. A stop does not trap focus, so
+ * you can still `Tab` out to the element it describes.
+ *
  * @since 0.1.0
  * @status stable
  * @category overlays
@@ -25,15 +43,21 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  *
  * @slot - The stops, in the order they are shown.
  *
+ * @event {HelixActivateEvent} helix-activate - Fired after the current stop changes, with the new index.
  * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current stop changes, with the new index. Cancelable: call `preventDefault()` to stay on the current stop.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the user ends the tour early. Cancelable: call `preventDefault()` to keep the tour open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before `requestOpen(true)` starts the tour. Cancelable: call `preventDefault()` to keep it closed.
  * @event {HelixCompleteEvent} helix-complete - Fired when the last stop is
  * finished.
  * @event {HelixTourAskEvent} helix-tour-ask - Fired when a stop's control is pressed to move the tour. The stop sends it, and the tour handles it.
+ * @event {ToggleEvent} toggle - Sent when the tour starts or ends, with `newState` and `oldState`.
  *
+ * @csspart backdrop - Behind a dialog or a floating stop, which lights nothing. It draws no box until you give it one.
  * @csspart spotlight - The box over the current target. It also draws the dimmed area around the target.
+ *
+ * @cssstate open - While the tour is running.
  */
-export declare class HelixHeadlessTour extends HelixElement {
+export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
     /**
      * Label for the control that goes back, passed to every stop.
      */
@@ -71,9 +95,14 @@ export declare class HelixHeadlessTour extends HelixElement {
      */
     nextLabel: string;
     /**
-     * Whether the tour is running.
+     * Draws each stop's place in the run in its panel, as well as saying it.
      */
-    open: boolean;
+    progress: boolean;
+    /**
+     * Each stop's place in the run, with `{index}` and `{count}` filled in.
+     * Translate it with the rest of your text.
+     */
+    progressLabel: string;
     /**
      * Label for the control that leaves the tour.
      */
@@ -121,6 +150,22 @@ export declare class HelixHeadlessTour extends HelixElement {
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** Where focus was when the tour opened, to give it back when it ends. */
+    private returnFocus;
+    /** Whether `follow` has seen the first update. */
+    private followed;
+    /**
+     * Moves focus with the run.
+     *
+     * Opening takes it to the current stop. Moving takes it to the new stop when
+     * it was in the tour, which is where a reader pressing Next is, and leaves it
+     * where it is otherwise. Closing gives it back to where it was before, again
+     * only when it was in the tour: a reader who moved to the target has chosen
+     * where to be.
+     */
+    private follow;
+    /** Focuses the current stop's panel once the stop has shown it. */
+    private focusCurrent;
     /**
      * Tells each stop where it is in the run.
      *
@@ -132,6 +177,24 @@ export declare class HelixHeadlessTour extends HelixElement {
     private settle;
     /** The current stop's target while the run is open, which is what the light falls on. */
     private get lit();
+    /** The stop being shown, or nothing where there are no stops. */
+    private get current();
+    /** Stops waiting, where a `wait` stop is waiting. */
+    private unwait;
+    /** The `wait` stop being waited on, so a render that changed nothing starts nothing. */
+    private waiting;
+    /**
+     * Waits at a `wait` stop for its target to be on the page, then moves on.
+     *
+     * On the stop's own root, which is where its `for` resolves.
+     */
+    private wait;
+    /**
+     * Whether the current stop is shown over the backdrop: a dialog or a floating
+     * stop, or one with no target, which have nothing to light. Read with the
+     * light, after the stops are known, since the first render cannot know them.
+     */
+    private veiled;
     /** Reads the current target's box, which is where the light falls. */
     private light;
     /** Keeps `sizer` on the lit target, and on nothing once there is none. */
@@ -143,3 +206,4 @@ declare global {
         'helix-headless-tour': HelixHeadlessTour;
     }
 }
+export {};