@fusion.dev/helix-headless 0.2.0 → 0.3.0

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

@@ -7,39 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/** Keys the toolbar handles, per the APG toolbar pattern. */
 const KEYS = new Set(['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown', 'Home', 'End']);
-/**
- * A control that owns its tab stop rather than taking one on its host.
- *
- * Checked as a property rather than with `instanceof`, for the same reason the
- * control list is: a toolbar holds anything, so the contract has to be
- * something a foreign element can satisfy.
- */
 const ownsTabStop = (node) => 'focusable' in node;
-/**
- * Input types with no text to move a caret through and no value an arrow moves.
- *
- * Everything else claims the arrows for itself: a caret in a text field, a
- * spinner on `number`, a value on `range`, a group on `radio`.
- */
 const CARETLESS = new Set(['button', 'checkbox', 'color', 'file', 'image', 'reset', 'submit']);
-/**
- * Whether the press was already the business of whatever it landed on.
- *
- * A toolbar holds anything, and some of what it holds uses the arrow keys for
- * itself. Moving the toolbar regardless makes an input in a toolbar
- * uneditable: ArrowRight moves focus to the next control, and `preventDefault`
- * means the caret never moves at all.
- *
- * `composedPath()[0]` rather than `event.target`, which is retargeted to the
- * control's host at the shadow boundary and cannot tell a text field inside a
- * component from the component itself.
- *
- * `defaultPrevented` first, because a control that has already answered the
- * press has said so in the way the platform provides, and a foreign control
- * this package has never heard of has no other way to say it.
- */
 const claimed = (event) => {
     if (event.defaultPrevented) {
         return true;
@@ -53,36 +23,9 @@ const claimed = (event) => {
     }
     return inner.localName === 'input' && !CARETLESS.has(inner.type);
 };
-/**
- * @summary A group of controls that share one tab stop.
- *
- * @description
- * Separate from a button group, and the difference is what it holds: a group is
- * homogeneous, a toolbar is not. A toolbar mixes buttons, toggles, and menus,
- * which is why it is its own component rather than a variant of something.
- *
- * The whole toolbar is one tab stop and the arrows move between controls, so a
- * page with three toolbars costs three presses of Tab to get past rather than
- * thirty. Controls are found by asking the browser what is focusable rather
- * than by matching tag names, so a toolbar works with anything put in it,
- * including a consumer's own elements.
- *
- * @since 0.1.0
- * @status stable
- * @category layout
- * @aliases Actions, Action bar
- * @documentation https://helix.fusion.dev/components/toolbar
- *
- * @slot - The toolbar's controls.
- *
- * @csspart toolbar - The toolbar container.
- */
 let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the toolbar.
-         */
         this.label = 'Toolbar';
         this.handleFocusIn = (event) => {
             const control = this.controls.find((entry) => entry.contains(event.target));
@@ -90,18 +33,6 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
                 this.setTabStop(control);
             }
         };
-        /**
-         * 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: a control this package
-         * has never heard of that was never given `tabindex="-1"` is still in the
-         * document's own tab order, so it is never the one that gets stranded.
-         */
         this.restoreTabStop = () => {
             const controls = this.controls;
             const held = controls.some((control) => ownsTabStop(control) ? control.focusable : control.tabIndex === 0);
@@ -134,7 +65,6 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
                 next = controls.length - 1;
             }
             else {
-                // An arrow along the other axis is not ours; leave it to the page.
                 return;
             }
             event.preventDefault();
@@ -143,19 +73,6 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             target?.focus();
         };
     }
-    /**
-     * Children that can take the tab stop, in document order.
-     *
-     * Every child that is not `disabled` and not `aria-hidden`, which is
-     * deliberately a test on the element rather than a list of tag names: a
-     * toolbar holds anything, including elements this package has never heard of.
-     * Client only, there being no tree to walk on the server.
-     *
-     * **It does not ask a child whether it is focusable.** Reading a `focusable`
-     * property is what `setTabStop` does when moving the stop, not what this does
-     * when choosing the set, so an element that is neither disabled nor hidden and
-     * still cannot take focus is counted here and skipped there.
-     */
     get controls() {
         return [...this.children].filter((child) => {
             if (!(child instanceof HTMLElement)) {
@@ -164,17 +81,6 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             return !child.hasAttribute('disabled') && child.getAttribute('aria-hidden') !== 'true';
         });
     }
-    /**
-     * 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.
-     */
     setTabStop(active, foreign = true) {
         for (const control of this.controls) {
             const stop = control === active;
@@ -186,29 +92,11 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             }
         }
     }
-    /**
-     * 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.
-     */
     async claimTabStop() {
         const pending = [...new Set(this.controls.map((control) => control.localName))].filter((name) => name.includes('-'));
         await Promise.all(pending.map((name) => customElements.whenDefined(name)));
-        // Foreign controls are left alone until focus arrives. Writing `tabindex`
-        // on one before any interaction changes markup the consumer rendered while
-        // React is still hydrating it, which it reports and does not patch up.
-        // Until then they keep the tab order the document already gave them, and
-        // the first `focusin` takes over from there.
         this.setTabStop(this.controls[0], false);
     }
-    /**
-     * The orientation in force.
-     *
-     * Unset is horizontal, and stays unset: the default is the absent attribute,
-     * so a reflected default cannot appear on the host after hydration.
-     */
     get axis() {
         return this.orientation ?? 'horizontal';
     }
@@ -216,10 +104,6 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
         super.connectedCallback();
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('focusin', this.handleFocusIn);
-        /* `disabled` and `aria-hidden` are what `controls` filters on, so a change
-           to either is a change to the set the stop has to live in. Nothing else is
-           watched, which also keeps `setTabStop` writing `tabindex` from feeding
-           back into this. */
         this.watcher = new MutationObserver(this.restoreTabStop);
         this.watcher.observe(this, {
             attributeFilter: ['disabled', 'aria-hidden'],