@fusion.dev/helix-headless 0.151.0 → 0.153.0

package/dist/tabs/root/tabs-root.js

@@ -4,7 +4,7 @@ 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 { AriaForwardController, customElement, HelixElement, IndicatorController, KeyboardNavigationController, MixinControllerActive, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, deepActiveElement, HelixActivateEvent, HelixElement, IndicatorController, KeyboardNavigationController, MixinControllerActive, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { HelixHeadlessTabPanel } from '../panel/tab-panel.js';
@@ -35,9 +35,15 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
             }
             this.requestActive(event.detail.value);
         };
+        this.held = [];
+        this.handleFocusIn = (event) => {
+            const path = event.composedPath();
+            this.focused = this.tabs.find((tab) => path.includes(tab));
+        };
         this.handleSlotChange = () => {
             this.sync();
             this.indicator.place();
+            this.refocus();
         };
     }
     static { this.words = 'helix-tabs'; }
@@ -54,6 +60,13 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
         const tabs = this.tabs;
         const declared = this.active === '' ? tabs.find((tab) => tab.selected) : undefined;
         const value = (declared ?? this.resolveActive(tabs))?.value ?? '';
+        const previous = this.active;
+        const gone = this.held.includes(previous) && !tabs.some((tab) => tab.value === previous);
+        this.held = tabs.map((tab) => tab.value);
+        if (gone && value !== '') {
+            this.active = value;
+            this.dispatchEvent(new HelixActivateEvent({ previous, value }));
+        }
         for (const tab of tabs) {
             const selected = tab.value === value;
             whenHydrated(tab, () => {
@@ -77,13 +90,27 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
             });
         }
     }
+    refocus() {
+        const gone = this.focused;
+        if (!gone || this.tabs.includes(gone)) {
+            return;
+        }
+        this.focused = undefined;
+        const active = deepActiveElement();
+        if (active !== null && active !== document.body) {
+            return;
+        }
+        void this.updateComplete.then(() => this.tabs.find((tab) => tab.selected)?.focus());
+    }
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
+        this.addEventListener('focusin', this.handleFocusIn);
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelection);
+        this.removeEventListener('focusin', this.handleFocusIn);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);

package/dist/tour/naming.d.ts

@@ -15,6 +15,11 @@ export interface StopWords {
     heading: readonly Element[];
     /** Whether the stop has a `label` of its own. */
     labeled: boolean;
+    /**
+     * The region that holds the content, given where the content holds words
+     * with no element around them, which then describes the panel.
+     */
+    loose?: Element | null;
     /** The element that says the stop's place in the tour, such as "2 of 5". */
     progress: Element | null;
 }
@@ -24,7 +29,8 @@ export interface StopWords {
  * 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.
+ * slot, or where it is empty by the words at the start of the content, as a
+ * `Dialog` is, and then 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;
+export declare const stopNaming: ({ content, description, heading, labeled, loose, progress, }: StopWords) => StopNaming;

package/dist/tour/naming.js

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

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

@@ -40,11 +40,27 @@ declare const HelixHeadlessTour_base: (new (...args: any[]) => import("@fusion.d
  * 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.
  *
- * **The arrow keys move between stops** while focus is in one: the arrow that
- * points the way the line runs goes on, and the other goes back, so on a
- * right-to-left page `ArrowLeft` goes on. Neither finishes the tour at the last
- * stop, and a text field in a stop keeps its own arrows. `Escape` skips the
- * tour.
+ * **The target is scrolled into view** before its stop is shown, by the
+ * least distance that brings it on screen, so the stop that points at it is
+ * on screen too.
+ *
+ * **Keyboard.** Focus is on the current stop's panel, which is not in the
+ * `Tab` order itself.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Right | Goes to the next stop. On the last stop it does nothing, and Next finishes the tour. |
+ * | Left | Goes back to the previous stop. |
+ * | Escape | Skips the tour, and puts focus back where it was when the tour opened. |
+ * | Tab, Shift+Tab | Moves through the controls in the stop, and on out to the page. A stop does not trap focus. |
+ * | Enter, Space | On Back, Next, or Skip, presses it. |
+ *
+ * The arrow that points the way the line runs goes on, and the other goes
+ * back, so on a right-to-left page Left goes on and Right goes back. A text field in a stop keeps
+ * its own arrows.
+ *
+ * The tour is a region named by `label` while it runs. A development build
+ * warns when a tour opens with no `label`.
  *
  * @since 0.1.0
  * @status stable
@@ -186,6 +202,14 @@ export declare class HelixHeadlessTour extends HelixHeadlessTour_base {
     disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** The target last scrolled into view, so a render that moved nothing scrolls nothing. */
+    private revealed;
+    /**
+     * Scrolls the current target into view, by the least distance that brings
+     * it on screen, before its stop is shown beside it. Zag's tour does the same.
+     * A target already on screen does not move.
+     */
+    private reveal;
     /** Where focus was when the tour opened, to give it back when it ends. */
     private returnFocus;
     /** Whether `follow` has seen the first update. */

package/dist/tour/root/tour-root.js

@@ -4,7 +4,7 @@ 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 { controlsIn, customElement, deepActiveElement, deepContains, formatWords, HelixActivateEvent, HelixBeforeActivateEvent, HelixCompleteEvent, HelixElement, HelixTourStatusEvent, hostAria, inlineStep, keyClaimed, MixinControllerOpen, requestChange, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { auditName, controlsIn, customElement, deepActiveElement, deepContains, formatWords, HelixActivateEvent, HelixBeforeActivateEvent, HelixCompleteEvent, HelixElement, HelixTourStatusEvent, hostAria, inlineStep, keyClaimed, MixinControllerOpen, requestChange, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property, queryAssignedElements, state } from 'lit/decorators.js';
 import { stopBefore } from '../back.js';
@@ -151,11 +151,23 @@ let HelixHeadlessTour = class HelixHeadlessTour extends MixinControllerOpen(Heli
     }
     updated(changed) {
         super.updated(changed);
+        this.reveal();
         this.settle();
         this.light();
+        if (changed.has('open') && this.open) {
+            auditName(this, () => null, 'Give it a `label`, such as "Getting started".', () => this.label !== '');
+        }
         this.follow(changed);
         this.wait();
     }
+    reveal() {
+        const target = this.lit ?? undefined;
+        if (target === this.revealed) {
+            return;
+        }
+        this.revealed = target;
+        target?.scrollIntoView?.({ block: 'nearest', inline: 'nearest' });
+    }
     follow(changed) {
         if (!this.followed) {
             this.followed = true;

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

@@ -37,7 +37,8 @@ import '../../button/index.js';
  * The panel is a `group`, and a `dialog` for a dialog stop, only while the
  * stop is shown. It is named by the `heading` slot, then by the first heading
  * in the content, then by `label`, and otherwise by its place in the tour. It
- * is described by the `description` slot and by its place, such as "2 of 5",
+ * is described by the `description` slot, or where that is empty by the words
+ * at the start of the content, and by its place, such as "2 of 5",
  * so a screen reader says where the reader is at every stop. `focus()` moves
  * focus to the panel, which is what the tour does when it opens or moves on.
  *

package/dist/tour/stop/tour-stop.js

@@ -68,6 +68,9 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
             description: slotted('description'),
             heading: slotted('heading'),
             labeled: this.label !== '',
+            loose: [...this.childNodes].some((one) => one.nodeType === Node.TEXT_NODE && (one.textContent ?? '').trim() !== '')
+                ? this.partNamed('content')
+                : null,
             progress: this.position === '' ? null : this.partNamed('progress'),
         });
         reflectElements(bubble, 'ariaLabelledByElements', labelledBy, true);
@@ -127,7 +130,7 @@ let HelixHeadlessTourStop = class HelixHeadlessTourStop extends HelixElement {
       ></div>
       <slot name="heading" part="heading" @slotchange=${this.nameByHeading}></slot>
       <slot name="description" part="description" @slotchange=${this.nameByHeading}></slot>
-      <div part="content"><slot></slot></div>
+      <div part="content"><slot @slotchange=${this.nameByHeading}></slot></div>
       ${this.position === ''
             ? ''
             : html `<span part="progress" ?hidden=${!this.progress}>${this.position}</span>`}

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

@@ -36,6 +36,9 @@ declare const HelixHeadlessTree_base: (new (...args: any[]) => import("@fusion.d
  * tree of check marks, Control+A (Command+A on an Apple keyboard) checks every
  * item or clears them all, and Shift with Up or Down Arrow moves and checks.
  *
+ * Removing the item that has focus moves focus to the item after it among its
+ * siblings, or the one before, or its parent, so focus stays in the tree.
+ *
  * **`reorderable` lets you move items among their siblings.** Alt with Up or
  * Down moves the focused item a place, and Alt with Home or End to the first
  * or the last place among its siblings, as the APG's rearrangeable listbox
@@ -183,6 +186,16 @@ export declare class HelixHeadlessTree extends HelixHeadlessTree_base {
     /** Whether many items can be checked. */
     private get multiple();
     private watcher;
+    /** The item that last had focus, so its removal can hand focus on. */
+    private focused;
+    private readonly handleFocusIn;
+    /**
+     * Puts focus back in the tree where the item that had it was removed and
+     * focus fell to the page: on the item after it among its siblings, or the
+     * one before, or its parent. Read from the removal itself, which knows where
+     * the item stood.
+     */
+    private refocus;
     /**
      * Every item, in the order a reader moving down would meet them.
      *

package/dist/tree/root/tree-root.js

@@ -4,7 +4,7 @@ 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 { AriaForwardController, closestInstance, commaList, customElement, HelixElement, inlineStep, keyClaimed, MixinCollection, MixinControllerActive, ReorderController, scrollItemIntoView, selectsAll, slottedWords, Typeahead, treeArrow, typesCharacter, whenHydrated, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, closestInstance, commaList, customElement, deepActiveElement, HelixElement, inlineStep, keyClaimed, MixinCollection, MixinControllerActive, ReorderController, scrollItemIntoView, selectsAll, slottedWords, Typeahead, treeArrow, typesCharacter, whenHydrated, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { fromGrip } from '../grip.js';
@@ -52,6 +52,11 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         });
         this.pickedUpLabel = 'Picked up {name}';
         this.reorderable = false;
+        this.handleFocusIn = (event) => {
+            this.focused = event
+                .composedPath()
+                .find((node) => node instanceof HelixHeadlessTreeItem);
+        };
         this.handleSelection = (event) => {
             const origin = event.target;
             if (!(origin instanceof HelixHeadlessTreeItem) || !this.items.includes(origin)) {
@@ -162,6 +167,36 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
     get multiple() {
         return this.selectionMode === 'multiple';
     }
+    refocus(records) {
+        const gone = this.focused;
+        if (!gone || this.items.includes(gone)) {
+            return;
+        }
+        this.focused = undefined;
+        const active = deepActiveElement();
+        if (active !== null && active !== document.body) {
+            return;
+        }
+        const record = records.find((one) => [...one.removedNodes].some((node) => node === gone || node.contains(gone)));
+        const near = (from, forward) => {
+            let node = from ?? null;
+            while (node) {
+                if (node instanceof HelixHeadlessTreeItem && !node.disabled && node.isConnected) {
+                    return node;
+                }
+                node = forward ? node.nextSibling : node.previousSibling;
+            }
+            return undefined;
+        };
+        const parent = record ? closestInstance(record.target, HelixHeadlessTreeItem) : null;
+        const next = near(record?.nextSibling, true) ??
+            near(record?.previousSibling, false) ??
+            (parent instanceof HelixHeadlessTreeItem && this.items.includes(parent)
+                ? parent
+                : undefined) ??
+            this.visibleItems.find((item) => !item.disabled);
+        this.focusOn(next);
+    }
     get items() {
         return [...this.querySelectorAll('*')].filter((node) => node instanceof HelixHeadlessTreeItem);
     }
@@ -305,7 +340,11 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         this.addEventListener('helix-select', this.handleSelection);
         this.addEventListener('toggle', this.handleBranch, true);
         this.addEventListener('keydown', this.handleKeydown);
-        this.watcher = new MutationObserver(() => this.syncItems());
+        this.addEventListener('focusin', this.handleFocusIn);
+        this.watcher = new MutationObserver((records) => {
+            this.syncItems();
+            this.refocus(records);
+        });
         this.watcher.observe(this, { childList: true, subtree: true });
     }
     disconnectedCallback() {
@@ -313,6 +352,7 @@ let HelixHeadlessTree = class HelixHeadlessTree extends MixinCollection(MixinCon
         this.removeEventListener('helix-select', this.handleSelection);
         this.removeEventListener('toggle', this.handleBranch, true);
         this.removeEventListener('keydown', this.handleKeydown);
+        this.removeEventListener('focusin', this.handleFocusIn);
         this.watcher?.disconnect();
         this.watcher = undefined;
     }