@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/loader/root/loader-root.js

@@ -7,49 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Says that something indeterminate is in progress.
- *
- * @description
- * Two concentric circles rather than one arc: the track is what makes the
- * moving part read as a proportion of a whole rather than as a shape drifting
- * on its own, and it costs one element.
- *
- * **The center is a slot and is empty by default.** A loader with a mark in the
- * middle is a brand's loader, and this library does not know whose. The slot is
- * the capability; the logo is the application's, put in once wherever the app
- * wraps it. Nothing is rendered when nothing is slotted, so an unbranded loader
- * is still two circles and no extra box.
- *
- * What is slotted does not turn. Only the arc moves, because a mark rotating
- * with it stops reading as a mark and becomes part of the animation, and a
- * wordmark upside down twice a second is worse than no wordmark.
- *
- * The semantics are on the host through `ElementInternals`, not on an inner
- * span. A `role` written into the shadow root announces correctly but leaves
- * the host itself anonymous to anything walking the light DOM, and a `role`
- * written onto the host as an attribute is one a React consumer's server markup
- * never had.
- *
- * @since 0.1.0
- * @status stable
- * @category feedback
- * @aliases Spinner, Busy, Activity
- * @documentation https://helix.fusion.dev/components/loader
- *
- * @slot - A mark to sit still at the center, usually a logo. Empty by default.
- *
- * @csspart indicator - The arc that turns.
- * @csspart mark - The region holding what was slotted at the center.
- * @csspart svg - The rotating circle pair.
- * @csspart track - The full circle behind the indicator.
- */
 let HelixHeadlessLoader = class HelixHeadlessLoader extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name, announced while the work is outstanding.
-         */
         this.label = 'Loading';
     }
     willUpdate(changed) {

package/dist/megamenu/root/megamenu-root.js

@@ -8,123 +8,12 @@ var HelixHeadlessMegamenu_1;
 import { anchorElement, customElement, HelixElement, MixinControllerOpen, PopoverController, tellDisclosure, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * The panel showing now, so opening one closes the last.
- *
- * A page has one of these open at a time: a nav bar whose Products panel is
- * still down while Solutions opens is a nav bar with two panels over the page.
- * Module scope rather than a coordinating parent, because there is nothing to
- * coordinate through: these sit in whatever container the consumer used, which
- * is usually `helix-navigation` and is not required to be. `Video` holds the
- * media session the same way and for the same reason.
- */
 let showing;
-/**
- * @summary A section of a navigation that opens a panel of destinations.
- *
- * @description
- * **A disclosure, not a menu, and that is the whole design.** `role="menu"` and
- * `menuitem` are for an application's commands: they take over the arrow keys,
- * announce "menu" to a reader who asked for navigation, and put every link
- * inside a role that is not a link. What this is, is a button that shows and
- * hides a region of the consumer's own anchors, which is the pattern the APG
- * gives for site navigation and the one that leaves a middle click, a modified
- * click and the status bar working. `Menu` remains right for a row of commands.
- *
- * **It renders no links**, for the reason `Navigation` gives: a router renders
- * its own anchor and cannot render one inside this shadow root. The panel is a
- * slot, and what goes in it is lists and headings the consumer wrote.
- *
- * **It opens on hover, and a press is always the fallback.** `open-on` says
- * which, and hover is the resting value because a nav bar is the one place a
- * reader expects to sweep along a row and see each section: making them click,
- * read, click again to compare two is the interaction hover exists to save.
- *
- * Hover is not the only way in, and the code is mostly about that. There is no
- * hover on a touch screen, so a tap opens the panel there whatever `open-on`
- * says, which is why the pointer type is checked rather than assumed. Focus
- * still opens nothing, for the same reason a tab through a nav bar should not
- * unfold it, but Enter on the trigger does, and a keyboard press arrives as a
- * click with no pointer behind it.
- *
- * A mouse click on a trigger the pointer is already sitting on is the case
- * worth naming: toggling there would close the panel and the pointer, still on
- * the trigger, would open it again, so the trigger would flicker and never
- * close. In hover mode the mouse's own clicks are left alone and hover governs
- * on its own. Escape and a click away still close it.
- *
- * The delays are intent, not decoration. Opening waits, so a pointer crossing
- * the bar on its way somewhere else opens nothing; closing waits longer, so the
- * diagonal from the trigger down into the panel does not pass through a gap and
- * shut it. Moving along a bar where a panel is already down opens the next one
- * at once, because at that point the reader is reading the bar, not crossing it.
- *
- * **Focus is not trapped and not moved.** A disclosure leaves the reader on the
- * trigger and the panel follows in the tab order, which is what the markup
- * already says, so Tab walks into the links and out the far side without
- * anything managing it. Escape closes and puts focus back, because Escape is
- * the one key that has to return the reader to where they were.
- *
- * The custom property below is written by this component and read by whoever
- * draws it. A consumer never sets it: it carries a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
- *
- * @since 0.1.0
- * @status experimental
- * @category navigation
- * @aliases Mega menu, Flyout, Nav panel
- * @documentation https://helix.fusion.dev/components/megamenu
- *
- * @slot - The panel's contents: the consumer's own lists and headings.
- * @slot trigger - The control that opens it. Falls back to a button named by `label`.
- *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart surface - The floating panel, which is what opens.
- * @csspart trigger - The default trigger, where none was slotted.
- *
- * @cssproperty --megamenu-top - Where the panel starts, measured from the bar above it.
- */
 let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * The width, in pixels, under which a card becomes a band. Zero never does.
-         *
-         * A card is a panel hung off one word, and there is no room to hang anything
-         * off a word on a phone: the columns do not shrink past
-         * `--megamenu-column-size`, so four of them stay four of them and the panel
-         * runs off the side of the screen rather than reflowing. Below this it takes
-         * the whole width and its columns stack, which is the only arrangement that
-         * fits.
-         *
-         * **In script rather than a media query, and only once.** Whether the panel is
-         * a band is not a question of paint: a band is not placed against the trigger,
-         * so the controller has to be told not to measure, and that decision is here
-         * whatever the stylesheet says. Writing the width in both places would be one
-         * number in two languages, drifting the first time either moved. This sets
-         * `data-narrow` on the host and the stylesheet arranges itself off that.
-         */
         this.fullBelow = 640;
-        /**
-         * The section's name, which names the default trigger and the panel.
-         */
         this.label = '';
-        /**
-         * Whether hovering the trigger opens the panel, or only a press does.
-         *
-         * A press always works. This says whether a mouse also opens it by resting on
-         * the trigger, and it is the default because that is what a navigation bar
-         * does. `click` is for a trigger that does something else as well, or a panel
-         * heavy enough that opening it on the way past is rude.
-         */
-        /* Read, never written back. It has a default, and a reflected default puts an
-           attribute on the host that the consumer did not write, which the server
-           then ships: the SSR spec for this element checks exactly that. Nothing
-           selects on it, so there is nothing to reflect for. */
         this.openOn = 'hover';
         this.narrow = false;
         this.handleWidth = (event) => {
@@ -132,34 +21,12 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
         this.panel = new PopoverController(this, {
             anchor: () => this.trigger,
-            /* The host, not the panel. A press on the trigger is a press on this
-               element, and counting it as outside would close the panel on the way to
-               the click that toggles it. `Menu` says the same about its own. */
             boundary: () => this,
             onDismiss: () => this.close(),
             place: () => !this.banded,
             placement: () => 'bottom-start',
             surface: () => this.renderRoot?.querySelector('[part="surface"]'),
         });
-        /**
-         * Keeps a band under its bar while the page moves, and closes it when the bar
-         * goes.
-         *
-         * The band is fixed and its offset is measured once, when it opens. That is
-         * fine until the page scrolls: a header that scrolls away leaves the band
-         * pinned where the header used to be, open, in the middle of the page with
-         * nothing above it. Measured at a scroll of 300: header bottom at -243 and the
-         * band still sitting at 57.
-         *
-         * The card has none of this, because the floating controller follows its
-         * anchor. The band turns that controller off, having nothing to be placed
-         * against, and this is the half of it still wanted.
-         *
-         * A sticky bar does not move, so re-measuring returns the same number and the
-         * band stays where it is. `requestOpen` rather than `close`, because closing
-         * puts focus back on the trigger and a reader who has scrolled away should not
-         * be dragged back up to it.
-         */
         this.handleScroll = () => {
             if (!this.open || !this.banded) {
                 return;
@@ -174,14 +41,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             this.pointer = event.pointerType;
         };
         this.handlePointerEnter = (event) => {
-            /* Mouse only. A touch screen synthesizes an enter on tap, and acting on it
-               would open the panel and then let the click that follows close it again,
-               so a tap would do nothing at all. */
             if (this.openOn !== 'hover' || event.pointerType !== 'mouse') {
                 return;
             }
-            /* No wait when a panel is already down: the bar is open, and the reader
-               moving along it is choosing, not passing through. */
             this.schedule(showing && showing !== this ? 0 : HelixHeadlessMegamenu_1.OPEN_DELAY, () => {
                 this.requestOpen(true);
             });
@@ -191,9 +53,6 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
                 return;
             }
             this.schedule(HelixHeadlessMegamenu_1.CLOSE_DELAY, () => {
-                /* Not `close()`: leaving with the pointer should not pull focus back to
-                   the trigger, which would scroll the page to a nav bar the reader has
-                   moved on from. Escape is the one that returns them. */
                 this.requestOpen(false);
             });
         };
@@ -203,39 +62,10 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
                 this.requestOpen(!this.open);
                 return;
             }
-            /* In hover mode the mouse's own clicks are hover's business. Toggling here
-               would close a panel the pointer is still standing on, and the pointer
-               would reopen it. A keyboard press arrives with no clicks behind it, and a
-               tap arrives with a pointer that is not a mouse: both are the only way in
-               for the people making them, so both toggle. */
             if (event.detail === 0 || (this.pointer !== undefined && this.pointer !== 'mouse')) {
                 this.requestOpen(!this.open);
             }
         };
-        /**
-         * Shuts the panel when a reader takes one of the destinations in it.
-         *
-         * Without this a click navigates and leaves the panel hanging over wherever
-         * the reader landed. With a router that navigates in place, that is a panel
-         * covering the page it was asked to go to.
-         *
-         * **A modified click leaves it open**, which is the same position this
-         * element already takes on middle clicks and the status bar: `cmd` on a link
-         * opens a tab behind this page rather than navigating it, so the reader is
-         * still standing in the menu and collecting, and shutting it under them would
-         * make the second choice cost a second open.
-         *
-         * `requestOpen(false)` rather than `close()`, for the reason `pointerleave`
-         * gives: the trigger is not where the reader is going, and pulling focus back
-         * to a nav bar they have just left is a scroll they did not ask for.
-         *
-         * **On the host rather than on the panel**, which is the same reason the
-         * pointer handlers give and one more. A row is slotted light DOM and the
-         * panel is in the shadow root, so a click only reaches the panel through the
-         * flattened tree: real ones do, and a DOM that does not implement slot
-         * propagation never delivers it, which makes every case here pass by never
-         * running this at all. The host is the row's own ancestor in both.
-         */
         this.handleContentClick = (event) => {
             if (!this.open || event.defaultPrevented || event.button !== 0) {
                 return;
@@ -243,14 +73,8 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             if (event.altKey || event.ctrlKey || event.metaKey || event.shiftKey) {
                 return;
             }
-            /* Asking for the destination rather than for any click, so the headings,
-               the gaps between rows and a reader's stray click on the panel's own
-               padding leave it where it is. */
             const target = event.target;
             const chosen = target?.closest?.('a[href], button:not([disabled]), [role="menuitem"]');
-            /* Inside this element and not the trigger. A press on the trigger is the
-               trigger's to answer, and a shadow-rendered one retargets to the host, so
-               `closest` there climbs past this element entirely. */
             if (!chosen || !this.contains(chosen) || chosen.closest('[slot="trigger"]')) {
                 return;
             }
@@ -258,12 +82,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         };
     }
     static { HelixHeadlessMegamenu_1 = this; }
-    /** A band, whether because it was asked for or because there is no room. */
     get banded() {
         return this.variant === 'full' || this.narrow;
     }
-    /* Rebuilt rather than kept, because the width is a property and a query
-       cannot be edited once it is made. */
     watchWidth() {
         this.query?.removeEventListener('change', this.handleWidth);
         this.query = undefined;
@@ -275,69 +96,31 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         this.query.addEventListener('change', this.handleWidth);
         this.handleWidth(this.query);
     }
-    /** Tells a slotted trigger the disclosure state, by property. See `tellDisclosure`. */
     tellTrigger() {
         const slotted = this.slotted;
         if (slotted) {
             tellDisclosure(slotted, this.open);
         }
     }
-    /** What the consumer slotted, if they slotted anything. */
     get slotted() {
         const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
         return slot?.assignedElements({ flatten: false })[0];
     }
-    /** Whatever the consumer slotted, or the button rendered in its place. */
     get trigger() {
         return anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this.renderRoot?.querySelector('[part="trigger"]') ?? this);
     }
-    /** Shuts it and puts the reader back where they were. */
     close() {
         if (!this.requestOpen(false)) {
             return;
         }
         this.trigger.focus();
     }
-    /**
-     * Where a full-bleed band starts, which is the only number it needs.
-     *
-     * The placing pass is off for that appearance, so nothing else is measuring:
-     * a band spans the viewport and has only one degree of freedom, how far down
-     * it sits, and that is the bottom of the trigger in viewport coordinates
-     * because the panel is fixed. A header that scrolls takes the band with it,
-     * which is what a panel hanging off a header should do.
-     *
-     * Written as a custom property rather than an inline `top`, so the stylesheet
-     * keeps the arrangement and this contributes the one measurement it cannot
-     * make. Nothing to do for the card, which the controller places.
-     */
     band() {
         if (!this.banded) {
             return;
         }
         this.style.setProperty('--megamenu-top', `${Math.round(this.bar())}px`);
     }
-    /**
-     * The bottom edge of the bar this hangs from.
-     *
-     * The trigger's own bottom is the obvious answer and is the wrong one: a
-     * header is taller than the word inside it, so a band starting at the word
-     * starts partway up the header, over its lower padding and its border.
-     * Measured: trigger bottom 44, header bottom 57, thirteen pixels of header
-     * with a band drawn across it.
-     *
-     * **The first ancestor as wide as the window, which is a fact and not a tag
-     * name.** A band spans the viewport, so what it should hang from is whatever
-     * else does: that is what makes something a bar. Asking for `helix-app-header`
-     * by name would make this element know about that one, which is the coupling
-     * `Menu` is careful not to have with `Drilldown`, and would leave a consumer
-     * who wrote their own header with a band across it.
-     *
-     * `body` ends the walk. It is as wide as the window and is not a bar, and its
-     * bottom is the foot of the page: without the guard a megamenu on a plain page
-     * would put its band down there. Nothing found means nothing to hang from, and
-     * the trigger is the honest answer again.
-     */
     bar() {
         const wide = document.documentElement.clientWidth;
         let node = this.parentElement;
@@ -350,14 +133,6 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         }
         return this.trigger.getBoundingClientRect().bottom;
     }
-    /**
-     * How long a pointer has to mean it, in milliseconds.
-     *
-     * Opening is the shorter wait: too long and the panel feels stuck, too short
-     * and crossing the bar opens things. Closing is longer because the pointer
-     * has to get from the trigger to the panel, and the straight line between
-     * them is not the line anybody moves along.
-     */
     static { this.OPEN_DELAY = 120; }
     static { this.CLOSE_DELAY = 220; }
     schedule(delay, then) {
@@ -370,15 +145,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             this.timer = undefined;
         }
     }
-    /* On the host, and here rather than in the template, because Lit templates
-       bind inside a shadow root and these have to hear the panel too. Not the
-       constructor: the server runs that and has no events. */
     connectedCallback() {
         super.connectedCallback();
         this.watchWidth();
-        /* On the window and capturing, so a band over a scrolling panel hears that
-           too rather than only the page's own scrolling. Passive: this measures and
-           never prevents. */
         addEventListener('scroll', this.handleScroll, { capture: true, passive: true });
         this.addEventListener('pointerdown', this.handlePointerDown);
         this.addEventListener('click', this.handleContentClick);
@@ -404,51 +173,9 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
         if (changed.has('fullBelow')) {
             this.watchWidth();
         }
-        /* The one thing the stylesheet cannot work out for itself, since the
-           breakpoint is declared up here. */
         this.toggleAttribute('data-narrow', this.narrow);
-        /* A slotted trigger is told the disclosure state, by property.
-    
-           `render` writes `aria-expanded` onto the button it renders itself, and a
-           consumer who takes the documented `trigger` slot replaces that button, so
-           without this the panel opens and closes and nothing announces it. Silent,
-           because the slot works in every other respect and the failure is only
-           audible.
-    
-           **Never `setAttribute` here: that is a hydration mismatch.** Measured
-           against React 19.2.8, four families server-rendered and hydrated with the
-           definitions loaded either side of `hydrateRoot`: this one and `SpeedDial`
-           produced "some attributes of the server rendered HTML didn't match the
-           client properties. This won't be patched up" in both orders, and
-           `Popover` and `Menu`, which write nothing, were clean in both. React
-           answers a mismatch by discarding the server's HTML for that subtree and
-           rebuilding it, which is the expensive half rather than the console line.
-    
-           **The property is the way through**, as `Menu` already does for its items.
-           React diffs the attributes it rendered and never looks at a property, so
-           `expanded` travels to the trigger, lands as `aria-expanded` inside that
-           element's shadow root, and the consumer's markup is left as they served
-           it.
-    
-           **What it cannot reach is a trigger that is not a Helix element.** A plain
-           `<button slot="trigger">` has no shadow root to hide the state in and no
-           property to take it, and a React consumer cannot mirror it themselves
-           because the open state is this element's. That case is warned about rather
-           than written to, on the same argument `Tooltip` makes about a link it
-           will not write for the consumer.
-    
-           **`aria-controls` is not written here and cannot be.** It would name
-           `panel`, an id inside this shadow root, and an IDREF resolves only within
-           the tree that holds it: from a light-DOM trigger looking in, the reference
-           is to nothing. Measured, `document.querySelector('#panel')` came back
-           `null` while the same id resolved inside `megamenu.shadowRoot`. An inert
-           `aria-controls` is worse than none, an audit tool reporting it satisfied
-           and a screen reader following it nowhere. */
         this.tellTrigger();
         if (this.open) {
-            /* Before showing this one, so the two are never both up for a frame. The
-               other closes through `requestOpen`, so a consumer holding it open is
-               asked rather than overruled. */
             if (showing && showing !== this) {
                 showing.requestOpen(false);
             }
@@ -463,13 +190,6 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
             this.panel.hide();
         }
     }
-    /**
-     * The control that opens it, behind a seam the styled tier can move.
-     *
-     * The same case `SpeedDial` records: a bare `<button>` is what this tier can
-     * write, `helix-button` lives a tier above, and a render method is how a tier
-     * that has one reaches this without reimplementing the panel below it.
-     */
     renderTrigger() {
         return html `<slot name="trigger" @click=${this.handleTriggerClick}>
       <button
@@ -483,10 +203,6 @@ let HelixHeadlessMegamenu = class HelixHeadlessMegamenu extends MixinControllerO
     </slot>`;
     }
     render() {
-        /* The listeners sit on the host rather than the trigger, so the panel counts
-           as inside it: the top layer changes where the panel is painted and not
-           where it is in the tree, so a pointer moving off the trigger and onto the
-           panel has not left this element and fires no leave. */
         return html `${this.renderTrigger()}
       <div
         part="surface"