@fusion.dev/helix-headless 0.208.1 → 0.210.0

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement, ToolbarController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A group of controls that share one tab stop.
@@ -55,6 +55,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * tab stop while the toolbar's is elsewhere, so Tab stops once in the
  * toolbar. A composite without one keeps its own tab stop.
  *
+ * A `<slot>` in the toolbar counts as the controls assigned to it, for a
+ * toolbar a component draws in its own shadow root with your controls passed
+ * into it: they share its tab stop and its arrows with the component's own.
+ *
  * A toolbar inside another toolbar, a Helix one or the page's own
  * `role="toolbar"`, is a `group` of the outer one, as React Aria's is: the
  * outer toolbar's arrows walk through its controls and on past them, and it
@@ -90,13 +94,6 @@ export declare class HelixHeadlessToolbar extends HelixElement {
     label: string;
     /** Carries a host `aria-label` and `aria-labelledby` to the toolbar. */
     protected readonly aria: AriaForwardController;
-    /**
-     * Whether the stop has been written onto controls this package does not
-     * know, which happens on the first focus. From then on, every move of the
-     * stop has to write them too, or the one at `0` can be removed or disabled
-     * and leave every other one at `-1`.
-     */
-    private wroteForeign;
     /**
      * The direction the arrow keys move focus in.
      */
@@ -106,67 +103,12 @@ export declare class HelixHeadlessToolbar extends HelixElement {
      * wrap around from one end to the other.
      */
     stopAtEnds: boolean;
-    private watcher;
-    /**
-     * The children that take part in the toolbar, in document order, each with
-     * the elements in it that take focus.
-     *
-     * A test on the element rather than a list of tag names: a toolbar holds
-     * anything, including elements this package has never heard of. A child
-     * that takes no focus and holds nothing that does is skipped. Client only,
-     * there being no tree to walk on the server.
-     */
-    private get controls();
-    /** The elements in a child's light DOM that take focus. */
-    private within;
-    /**
-     * The stops of a child that takes focus itself: the child, or the members of
-     * a composite that owns its tab stop, such as a toggle group, which the
-     * toolbar enters at a member and moves the stop of through `focusable`.
-     */
-    private inside;
-    /**
-     * Where focus lands on arriving at a control. A nested composite is entered
-     * at the stop it holds, which for a toggle group is the chosen toggle.
-     */
-    private entry;
-    /** The control a press or a focus came from, by its path. */
-    private origin;
-    /**
-     * Moves the single tab stop to one control.
-     *
-     * Prefers the control's own `focusable` property to writing `tabindex` on it.
-     * The attribute is a change to markup the consumer rendered, which a React
-     * consumer's hydration reports and does not patch up; a control that offers
-     * the property moves the stop inside its own shadow root instead.
-     *
-     * `tabindex` stays as the fallback, because a toolbar has to hold controls
-     * this package has never heard of.
-     */
-    private setTabStop;
     /**
-     * Sets the first tab stop once every custom control has upgraded.
-     *
-     * A custom element has no properties at all before it upgrades, so a pass
-     * that ran first would find no `focusable`, take the `tabindex` fallback, and
-     * write the very attribute this exists to avoid.
+     * The one tab stop and the arrow keys, shared with every toolbar a
+     * component draws: the controls are the children, a slot among them read as
+     * the elements assigned to it.
      */
-    private claimTabStop;
-    private readonly handleFocusIn;
-    /**
-     * Gives the tab stop back to a control that still exists.
-     *
-     * `controls` excludes anything disabled or hidden, so disabling the control
-     * holding the stop drops it out of the list while every other control is
-     * already at `-1`, leaving a toolbar the keyboard cannot reach at all. A Save
-     * button disabling itself once the form is clean is enough to do it.
-     *
-     * `foreign` stays false, the same as the first claim, until a focus has
-     * written `tabindex="-1"` onto foreign controls. From then on `setTabStop`
-     * writes them as well, so removing or disabling the native button that held
-     * the stop hands it to the first one left.
-     */
-    private readonly restoreTabStop;
+    protected readonly tabStop: ToolbarController;
     /**
      * Whether this toolbar sits inside another, which then owns the keys and the
      * tab stop: a toolbar inside a toolbar held the reader's arrows inside it.
@@ -181,18 +123,7 @@ export declare class HelixHeadlessToolbar extends HelixElement {
      * so a reflected default cannot appear on the host after hydration.
      */
     private get axis();
-    /**
-     * The toolbar's own keys, from inside a nested composite.
-     *
-     * In capture, ahead of the composite, which answers every arrow itself and
-     * would otherwise hold the reader inside it. Only the keys along the
-     * toolbar's axis and Home and End are taken, so the arrows across it still
-     * move inside the composite.
-     */
-    private readonly handleCompositeKeydown;
-    private readonly handleKeydown;
     connectedCallback(): void;
-    disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected willUpdate(changed: PropertyValues): void;
     protected render(): TemplateResult;

package/dist/toolbar/root/toolbar-root.js

@@ -1,44 +1,8 @@
 var HelixHeadlessToolbar_1;
 import { __decorate } from "tslib";
-import { AriaForwardController, closestInstance, customElement, HelixElement, inlineStep, keyClaimed, toolbarAround, words, } from '@fusion.dev/helix-core';
+import { AriaForwardController, closestInstance, customElement, HelixElement, ToolbarController, toolbarAround, words, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-const KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End']);
-const ownsTabStop = (node) => 'focusable' in node;
-const NATIVE = 'a[href], button, input, select, textarea, [tabindex], [contenteditable=""], [contenteditable="true"]';
-const TABBABLE = NATIVE.replace('[tabindex]', '[tabindex]:not([tabindex="-1"])');
-const innerStops = new WeakMap();
-const takesFocus = (node) => {
-    if (!(node instanceof HTMLElement) ||
-        node.hasAttribute('disabled') ||
-        node.getAttribute('aria-hidden') === 'true') {
-        return false;
-    }
-    return (node.matches(NATIVE) ||
-        ownsTabStop(node) ||
-        node.shadowRoot?.delegatesFocus === true ||
-        node.shadowRoot?.querySelector(TABBABLE) != null ||
-        innerStops.get(node)?.isConnected === true);
-};
-const stopOf = (node) => {
-    if (node.hasAttribute('tabindex')) {
-        return node;
-    }
-    const held = innerStops.get(node);
-    if (held?.isConnected && held.getRootNode() === node.shadowRoot) {
-        return held;
-    }
-    const inner = node.localName.includes('-')
-        ? node.shadowRoot?.querySelector(TABBABLE)
-        : null;
-    if (!inner) {
-        return node;
-    }
-    innerStops.set(node, inner);
-    return inner;
-};
-const flattens = (node) => ownsTabStop(node) &&
-    node.selectionMode === 'multiple';
 let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
     constructor() {
         super(...arguments);
@@ -47,177 +11,16 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             label: true,
             target: () => this.partNamed('toolbar'),
         });
-        this.wroteForeign = false;
         this.stopAtEnds = false;
-        this.handleFocusIn = (event) => {
-            if (this.nested) {
-                return;
-            }
-            const control = this.origin(event);
-            if (control) {
-                this.setTabStop(control);
-            }
-        };
-        this.restoreTabStop = () => {
-            if (this.nested) {
-                return;
-            }
-            const controls = this.controls;
-            const held = controls.some((control) => {
-                if (control.group) {
-                    return control.group.focusable;
-                }
-                const composite = control.stops.length !== 1;
-                const element = composite ? control.child : control.stops[0];
-                if (ownsTabStop(element)) {
-                    return element.focusable;
-                }
-                return composite || stopOf(element).tabIndex === 0;
-            });
-            if (controls.length > 0 && !held) {
-                this.setTabStop(controls[0], false);
-            }
-        };
-        this.handleCompositeKeydown = (event) => {
-            if (this.nested) {
-                return;
-            }
-            const control = this.origin(event);
-            if (!control || (control.stops.length === 1 && !control.group)) {
-                return;
-            }
-            this.handleKeydown(event);
-            if (event.defaultPrevented) {
-                event.stopPropagation();
-            }
-        };
-        this.handleKeydown = (event) => {
-            if (this.nested || !KEYS.has(event.key) || keyClaimed(event)) {
-                return;
-            }
-            const along = inlineStep(this, event.key);
-            const forward = this.axis === 'horizontal' ? along === 1 : event.key === 'ArrowDown';
-            const back = this.axis === 'horizontal' ? along === -1 : event.key === 'ArrowUp';
-            const controls = this.controls;
-            const origin = this.origin(event);
-            const current = origin ? controls.findIndex((control) => control.child === origin.child) : -1;
-            if (current === -1) {
-                return;
-            }
-            let next = current;
-            const last = controls.length - 1;
-            if (forward) {
-                next = this.stopAtEnds ? Math.min(current + 1, last) : (current + 1) % controls.length;
-            }
-            else if (back) {
-                next = this.stopAtEnds
-                    ? Math.max(current - 1, 0)
-                    : (current - 1 + controls.length) % controls.length;
-            }
-            else if (event.key === 'Home') {
-                next = 0;
-            }
-            else if (event.key === 'End') {
-                next = controls.length - 1;
-            }
-            else {
-                return;
-            }
-            event.preventDefault();
-            const target = controls[next];
-            this.setTabStop(target);
-            const element = target ? this.entry(target) : undefined;
-            if (element && 'focusItem' in element && typeof element.focusItem === 'function') {
-                element.focusItem();
-            }
-            else if (element) {
-                ;
-                (ownsTabStop(element) ? element : stopOf(element)).focus();
-            }
-        };
+        this.tabStop = new ToolbarController(this, {
+            arrows: () => this.axis,
+            members: () => [...this.children],
+            nested: () => this.nested,
+            stopAtEnds: () => this.stopAtEnds,
+        });
     }
     static { HelixHeadlessToolbar_1 = this; }
     static { this.words = 'helix-toolbar'; }
-    get controls() {
-        const controls = [];
-        for (const child of this.children) {
-            if (!(child instanceof HTMLElement) ||
-                child.hasAttribute('disabled') ||
-                child.getAttribute('aria-hidden') === 'true') {
-                continue;
-            }
-            if (takesFocus(child)) {
-                const stops = this.inside(child);
-                if (stops.length > 1 && flattens(child)) {
-                    for (const stop of stops) {
-                        controls.push({ child: stop, group: child, stops: [stop] });
-                    }
-                    continue;
-                }
-                controls.push({ child, stops });
-                continue;
-            }
-            for (const stop of this.within(child)) {
-                controls.push({ child: stop, stops: [stop] });
-            }
-        }
-        return controls;
-    }
-    within(child) {
-        return [...child.querySelectorAll('*')].filter(takesFocus);
-    }
-    inside(child) {
-        if (!ownsTabStop(child)) {
-            return [child];
-        }
-        const members = this.within(child);
-        return members.length > 1 ? members : [child];
-    }
-    entry(control) {
-        const { stops } = control;
-        if (stops.length === 1) {
-            return stops[0];
-        }
-        return (stops.find((stop) => (ownsTabStop(stop) && stop.focusable) ||
-            stop.selected === true) ?? stops[0]);
-    }
-    origin(event) {
-        const path = event.composedPath();
-        return this.controls.find((control) => control.stops.some((stop) => path.includes(stop)));
-    }
-    setTabStop(active, foreign = true) {
-        if (foreign) {
-            this.wroteForeign = true;
-        }
-        for (const control of this.controls) {
-            if (control.group) {
-                control.group.focusable = control.group === active?.group;
-                continue;
-            }
-            if (control.stops.length !== 1) {
-                if (ownsTabStop(control.child)) {
-                    control.child.focusable = control.child === active?.child;
-                }
-                continue;
-            }
-            const element = control.stops[0];
-            const stop = control.child === active?.child;
-            if (ownsTabStop(element)) {
-                element.focusable = stop;
-            }
-            else if (foreign || this.wroteForeign) {
-                stopOf(element).tabIndex = stop ? 0 : -1;
-            }
-        }
-    }
-    async claimTabStop() {
-        if (this.nested) {
-            return;
-        }
-        const pending = [...new Set([...this.children].map((child) => child.localName))].filter((name) => name.includes('-'));
-        await Promise.all(pending.map((name) => customElements.whenDefined(name)));
-        this.setTabStop(this.controls[0], false);
-    }
     get nested() {
         const parent = this.parentElement;
         if (!parent) {
@@ -231,27 +34,10 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
     connectedCallback() {
         super.connectedCallback();
         this.requestUpdate();
-        this.addEventListener('keydown', this.handleCompositeKeydown, true);
-        this.addEventListener('keydown', this.handleKeydown);
-        this.addEventListener('focusin', this.handleFocusIn);
-        this.watcher = new MutationObserver(this.restoreTabStop);
-        this.watcher.observe(this, {
-            attributeFilter: ['disabled', 'aria-hidden'],
-            attributes: true,
-            subtree: true,
-        });
-    }
-    disconnectedCallback() {
-        super.disconnectedCallback();
-        this.removeEventListener('keydown', this.handleCompositeKeydown, true);
-        this.removeEventListener('keydown', this.handleKeydown);
-        this.removeEventListener('focusin', this.handleFocusIn);
-        this.watcher?.disconnect();
-        this.watcher = undefined;
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        void this.claimTabStop();
+        void this.tabStop.claim();
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -259,7 +45,7 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
         this.toggleState('horizontal', this.axis === 'horizontal');
         this.toggleState('vertical', this.axis === 'vertical');
         if (this.hasUpdated && changed.has('orientation')) {
-            for (const child of this.children) {
+            for (const child of this.tabStop.members) {
                 ;
                 child.requestUpdate?.();
             }
@@ -273,7 +59,7 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
       aria-label=${this.label}
       aria-orientation=${nested ? nothing : this.axis}
     >
-      <slot @slotchange=${() => this.claimTabStop()}></slot>
+      <slot @slotchange=${() => this.tabStop.claim()}></slot>
     </div>`;
     }
 };