@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/menu/item/menu-item.js

@@ -9,158 +9,21 @@ import { caretRight, check } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary One row in a menu: a command, a choice, or a way into a submenu.
- *
- * @description
- * Three shapes, one element, because a reader moving down a menu with the
- * arrow keys does not care which kind each row is and neither should the
- * markup. What it is follows from what it was given: something slotted into
- * `submenu` makes it a way in, `checked` makes it a choice, and neither makes
- * it a command.
- *
- * **The role follows the shape.** A row that can be ticked is
- * `menuitemcheckbox` and carries `aria-checked`, because a reader is told "one
- * of these is on" rather than "here is a button". A row that opens a page keeps
- * `menuitem` and says `aria-haspopup`, since the page it opens is a menu.
- *
- * Whether it is on the page showing is set by the menu as a property, never as
- * an attribute: an attribute written onto a consumer's element after it
- * upgrades is a hydration mismatch waiting to happen.
- *
- * @since 0.1.0
- * @status experimental
- * @aliases Menu option, Menu row
- * @documentation https://helix.fusion.dev/components/menu
- *
- * @slot - The label.
- * @slot start - Before the label. A mark about the row.
- * @slot submenu - Rows this one opens, which makes it a way in.
- *
- * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
- *
- * @csspart item - The row, which is an `<a>` where `href` is set.
- * @csspart mark - The trailing mark: a tick when checked, a caret when it opens
- * a page. One column, because a row is never both.
- * @csspart start - The leading column, which is a slot and is always there.
- */
 let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the row is one of a set of choices.
-         *
-         * Separate from `checked`, and it has to be. A row that is off is still a
-         * choice, and `checked` alone cannot say so: an unticked row and a row that
-         * was never tickable look identical from here. Announcing only the ticked one
-         * as a checkbox tells a reader its siblings are commands, which is the one
-         * thing they are not.
-         *
-         * `checked` implies it, so a row that is on never has to say both.
-         */
         this.checkable = false;
-        /**
-         * Whether the row is ticked.
-         */
         this.checked = false;
-        /**
-         * Whether the row can be chosen.
-         */
         this.disabled = false;
-        /**
-         * Whether the link saves the file rather than opening it.
-         *
-         * Only meaningful beside an `href`, and only for a file served from this
-         * origin: the attribute is ignored cross-origin, which is the browser's rule
-         * about who may name a file on somebody's disk rather than a gap here.
-         */
         this.download = false;
-        /**
-         * Where the row goes, which makes it a real link.
-         *
-         * **The row itself becomes an `<a>`, and the role goes with it.** A
-         * `menuitem` cannot contain a link: measured in Chromium, an anchor inside
-         * one is exposed as a child and the row loses its accessible name entirely.
-         * So the anchor *is* the row, carrying `menuitem` and the `tabindex` the menu
-         * roves, which is the same maneuver `Tree.Item` makes and the reason `href`
-         * changes the markup rather than only adding an attribute.
-         *
-         * **`Option` cannot have this and the reason is worth knowing**, since a
-         * command palette is the obvious place to want it. A listbox has to keep
-         * focus somewhere else, in the text field for a combobox, so it says which
-         * option is current with `aria-activedescendant`. That reference can only
-         * point at the option's host, measured: assigning
-         * `ariaActiveDescendantElement` an element inside a sibling shadow root reads
-         * back `null`. So `role="option"` is pinned to the host, and an anchor under
-         * it hits the naming failure above. A menu has no such constraint because
-         * focus really moves to the row.
-         */
         this.href = '';
-        /**
-         * Whether this row is on the page currently showing.
-         *
-         * Set by the menu, and a property rather than an attribute for that reason.
-         * Public because the menu has to reach it, and not something a consumer
-         * writes: which page is open is the menu's business.
-         */
         this.onPage = true;
-        /**
-         * The relationship, which `target="_blank"` should always set.
-         */
         this.rel = '';
-        /**
-         * Whether this row's submenu is the page showing.
-         *
-         * Separate from `onPage`, and it has to be. A row that opened a page is not
-         * itself on that page, so both are false for it, and rendering nothing on
-         * that basis takes its `slot[name="submenu"]` with it: the rows inside have
-         * nowhere to be assigned and are never laid out. The element that holds the
-         * page has to keep the slot even when it shows no row of its own.
-         */
         this.showingSubmenu = false;
-        /**
-         * Where the link opens, for the rows that should leave the page.
-         */
         this.target = '';
-        /**
-         * What this row stands for, carried in the event when it is chosen.
-         */
         this.value = '';
-        /**
-         * @internal Read by a parent to identify its children across the light DOM,
-         * which is cheaper than `instanceof` and is why this is public rather than
-         * protected. Not a consumer's to read or set.
-         */
         this.isMenuItem = true;
-        /**
-         * Whether anything is slotted into `submenu`. Read after first render.
-         *
-         * State rather than a getter over `children`. A getter is read during
-         * `render()` with nothing to re-read it, so a submenu arriving after the
-         * row's first render produces no caret and no `aria-haspopup` while selecting
-         * the row still drills in, which is what a framework filling a submenu on
-         * demand hits every time. `Tree.Item` backs `branch` the same way for the
-         * same reason.
-         *
-         * Kept in step by `readSubmenu`, which is bound in the template rather than
-         * once at first render. See the note there.
-         */
         this.submenu = false;
-        /**
-         * Re-reads whether anything is in the submenu, from whichever slot is current.
-         *
-         * **Bound in the template, and it has to be.** This row renders a
-         * `slot[name="submenu"]` in two template branches, one for the row and one
-         * for the page it opens, and moving between them makes Lit build a new slot
-         * and throw the old one away. A listener added at `firstUpdated` stays on the
-         * discarded slot, which fires `slotchange` on its way out with nothing
-         * assigned to it any more: one drill-in sets `submenu` false and nothing is
-         * left listening to set it back, so every caret in the menu vanishes and
-         * every row stops opening.
-         *
-         * The live slot is asked rather than `event.target`, so it does not matter
-         * which of the two fired or in what order.
-         */
         this.readSubmenu = () => {
             const slot = this.renderRoot.querySelector('slot[name="submenu"]');
             this.submenu = (slot?.assignedElements().length ?? 0) > 0;
@@ -168,23 +31,6 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.handleClick = () => {
             this.choose();
         };
-        /**
-         * Enter and Space choose the row, which a `<div>` would not do on its own.
-         *
-         * It is not a `<button>`: a button inside a menu is announced as a button,
-         * and the roles a menu needs are not roles a button can take.
-         *
-         * **A linked row hands Enter back to the browser.** An anchor answers Enter
-         * itself, by firing a click and following the link, so preventing the default
-         * here would mean re-issuing that navigation by hand and losing whatever the
-         * browser does around it. `Tree.Item` records the same trap from the other
-         * side: its tree prevents every key it handles, which is exactly what was
-         * swallowing Enter on its rows.
-         *
-         * Space is different, and that is the platform rather than a choice: an
-         * anchor ignores it. So the row presses itself, and the click that comes back
-         * both announces and navigates.
-         */
         this.handleKeydown = (event) => {
             if (event.key !== 'Enter' && event.key !== ' ') {
                 return;
@@ -201,14 +47,6 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
             this.handleClick();
         };
     }
-    /**
-     * Whether anything was slotted into `submenu`.
-     *
-     * False on the server, which is the right answer rather than a safe one: the
-     * server cannot know whether a submenu was slotted, and a row that served an
-     * `aria-haspopup` it might not have would be a promise made to a screen
-     * reader on the strength of a guess.
-     */
     get hasSubmenu() {
         return this.submenu;
     }
@@ -216,46 +54,16 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         super.firstUpdated(changed);
         this.readSubmenu();
     }
-    /**
-     * Moves focus onto the row itself.
-     *
-     * The host is not focusable: what takes focus is the row inside this shadow
-     * root, and a menu moving between rows with the arrow keys has to reach it.
-     */
     focus() {
         this.renderRoot.querySelector('[part="item"]')?.focus();
     }
-    /**
-     * `NavigableItem`, so the arrow keys can be the shared controller's business.
-     *
-     * `focus()` above already puts focus on the control inside the row rather than
-     * on the row, which is the whole of what moving here means.
-     */
     focusItem() {
         this.focus();
     }
-    /** Chooses the row, which is the same act as pressing it. */
     select() {
         this.choose();
     }
-    /**
-     * Whether this is the row the set is on, which in a menu is where focus is.
-     *
-     * A radio group's selection is an answer it holds; a menu has no answer, only
-     * a row the reader has walked to, so focus is the whole of what "the current
-     * one" can mean here. Read from the shadow root rather than kept as state,
-     * because focus moves for reasons this element is not told about: a press, a
-     * Tab, the drilldown putting the reader on the first row of a page it has
-     * just opened.
-     */
     get selected() {
-        /* Asked of the document, not of the shadow root. Focus lands on the control
-           inside this row, and the platform retargets it: from outside a shadow
-           tree, `activeElement` is the host, which is this element. So the document
-           already answers the question and nothing has to walk a tree to do it.
-           `ShadowRoot.activeElement` is also the reading that does not survive
-           happy-dom, which climbs `getRootNode()` to the top and then dereferences
-           what it ran out of. */
         return this.ownerDocument.activeElement === this;
     }
     choose() {
@@ -265,47 +73,19 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         this.dispatchEvent(new HelixSelectEvent({ value: this.value }));
     }
     render() {
-        // The page this row opened is showing, so what it contributes is the slot
-        // its rows are assigned to and nothing else. Its own row belongs to the
-        // page above.
         if (this.showingSubmenu) {
             return html `<slot name="submenu" @slotchange=${this.readSubmenu}></slot>`;
         }
-        // Not on the page showing, so there is nothing to draw. Rendering nothing
-        // rather than hiding it with an attribute, because the attribute would be
-        // one this element wrote onto itself, and there is no state to keep: the
-        // rows are in the light DOM and come back as they were.
         if (!this.onPage) {
             return nothing;
         }
         const submenu = this.hasSubmenu;
-        /* One row, two tags. Everything about it is the same but the element, which
-           is what an `href` changes: the anchor carries the role and the tab stop
-           rather than sitting inside something that does, for the reason the
-           property's own note records. `Tree.Item` writes its two the same way.
-    
-           A disabled row renders no `href`. A disabled anchor is not a thing the
-           platform has, and `aria-disabled` alone still navigates. */
         const linked = this.href !== '' && !this.disabled;
         const role = this.checkable || this.checked ? 'menuitemcheckbox' : 'menuitem';
         const checkedState = this.checkable || this.checked ? (this.checked ? 'true' : 'false') : nothing;
         const inside = html `<span part="start"><slot name="start"></slot></span>
         <slot></slot>
-        ${
-        // One trailing column, and a row is never both: a way into a page has
-        // nothing to tick, and a choice opens nothing. The tick sits after the
-        // label rather than before it, so the labels start at the edge of the
-        // row and the marks line up down the side they are read from.
-        //
-        // `data-submenu` is what tells the two apart from CSS. They share a
-        // part name because they share a column, and only one of them is
-        // directional: a caret has to mirror in a right-to-left document and a
-        // tick must not, which Unicode's own mirroring list agrees on. The
-        // attribute is on an element in this shadow root rather than on the
-        // host, so it is the divider's `data-empty` and not a hydration
-        // hazard. `hasSubmenu` is derived from slot assignment and has no
-        // attribute a selector could read instead.
-        submenu
+        ${submenu
             ? html `<svg
                 part="mark"
                 data-submenu

package/dist/menu/root/menu-root.js

@@ -9,100 +9,18 @@ import { caretLeft } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary A menu of commands, opened from a trigger.
- *
- * @description
- * The trigger is slotted and stays the consumer's own element, the same way the
- * tooltip takes one. The surface is rendered here, in the top layer through the
- * popover API, so it clears any ancestor with `overflow: hidden` without a
- * `z-index` anywhere.
- *
- * **It drills down rather than flying out.** A submenu replaces what is on
- * screen and a back row returns, instead of opening a second panel beside the
- * first. Panels beside panels need a diagonal path a pointer has to travel
- * without straying, they run off the edge of a narrow window, and on a touch
- * screen there is no hover to open them with at all. One panel that changes
- * what it holds has none of those problems and reads the same on a phone.
- *
- * The open page is held here rather than in each item, because only one page
- * shows at a time and something has to know which. Items are told by property,
- * not by attribute: an attribute written onto a consumer's element after it
- * upgrades is a hydration mismatch waiting to happen.
- *
- * @since 0.1.0
- * @status experimental
- * @category overlays
- * @aliases Dropdown, Action menu
- * @documentation https://helix.fusion.dev/components/menu
- *
- * @slot - The items.
- * @slot trigger - What opens it.
- *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart back - The control that returns from a submenu.
- * @csspart back-mark - The glyph on the back control of a submenu.
- * @csspart empty - Shown when there are no items to show.
- * @csspart header - The bar above a submenu, holding the way back and its name.
- * @csspart loading - Shown while the items are still on their way.
- * @csspart surface - The floating panel the menu is drawn on.
- * @csspart title - The name of the submenu that is showing.
- */
 let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinControllerOpen(HelixElement)) {
     constructor() {
         super(...arguments);
-        /**
-         * What the row returning from a submenu reads.
-         */
         this.backLabel = 'Back';
-        /**
-         * Accessible name for the surface.
-         */
         this.label = 'Menu';
-        /**
-         * Space between the trigger and the surface, in pixels.
-         */
         this.offset = 4;
-        /**
-         * Preferred side.
-         *
-         * It moves if that side does not fit.
-         */
         this.placement = 'bottom-start';
-        /**
-         * Which page is showing, and what is on it.
-         *
-         * A controller rather than fields here, because none of this is about menus:
-         * a settings panel or a navigation tree wants the same shape. It holds a real
-         * stack, so `back()` returns one level rather than to the root.
-         */
         this.drilldown = new DrilldownController(this, {
             isRow: (element) => 'isMenuItem' in element && element.isMenuItem === true,
             root: () => [...this.children].filter((child) => child.slot !== 'trigger'),
             slot: 'submenu',
         });
-        /**
-         * Moving between rows, which is not this element's own business any more.
-         *
-         * `selects` false, because arriving at Delete must not delete: moving and
-         * choosing are one act in a radio group and two acts here, which is the
-         * distinction the controller was already drawing for `Tabs`.
-         *
-         * The origin is the selection, and `focus` is the wrong reading however right
-         * it looks: that origin also carries a rule a menu must not follow, that a
-         * press which did not come from the set moves nothing. That rule is there for
-         * a tab panel, which is a tab stop beside the tabs; a menu's panel holds the
-         * rows and nothing else, and Down on a menu that has just opened is how a
-         * reader gets to the first row at all.
-         *
-         * The horizontal pair is reserved rather than released. Right opens a
-         * submenu and left comes back, which are the platform's own bindings for a
-         * menu that drills, so those keys are spoken for here rather than unhandled.
-         */
         this.keys = new KeyboardNavigationController(this, {
             items: () => this.items,
             reserved: () => ['ArrowLeft', 'ArrowRight'],
@@ -110,9 +28,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         });
         this.panel = new PopoverController(this, {
             anchor: () => this.trigger,
-            // The host is `display: contents`, so it has no box a press can land in.
-            // What counts as inside is the surface, plus the trigger, whose own click
-            // handler decides what a press there means.
             boundary: () => this,
             offset: () => this.offset,
             onDismiss: () => this.hide(),
@@ -126,34 +41,17 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             }
             const chosen = item;
             if (chosen.hasSubmenu) {
-                // A row that opens a page has not chosen anything, so its select does not
-                // leave this element: a consumer listening for a choice would otherwise
-                // hear one every time a reader looked in a submenu.
                 event.stopPropagation();
                 this.enter(chosen);
                 return;
             }
             this.hide();
         };
-        /**
-         * Keeps whatever has focus in sight, however it got there.
-         *
-         * On `focusin` rather than in the branches that move focus: a row reached by
-         * Tab, or focused by the drilldown on the way into a page, can otherwise sit
-         * below the fold of a scrolled panel.
-         */
         this.handleFocusIn = (event) => {
             const item = this.items.find((row) => row.contains(event.target));
             if (!item) {
                 return;
             }
-            /* `surface`, which is the part this template renders and the name the
-               whole library spells this box with.
-        
-               Keep the two in step. A lookup asking for a name the template does not
-               render finds null, and `scrollItemIntoView` then runs with no scroller and
-               takes the page behind the menu with it, which is the one thing that method
-               exists to prevent. */
             const surface = this.renderRoot.querySelector('[part="surface"]');
             scrollItemIntoView(item, { padding: 4, ...(surface ? { scroller: surface } : {}) });
         };
@@ -171,13 +69,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 this.leave();
             }
             else if (event.key === 'Tab') {
-                /* Out, and the panel goes with it.
-                 *
-                 * Nothing else closes the menu when focus leaves it, so tabbing out of an
-                 * open one would leave a shadowed panel in the top layer sitting over
-                 * whatever the reader tabbed to. Deliberately not prevented: focus carries on
-                 * outward, which is what the reader asked for. And deliberately not a
-                 * focus trap, because a menu is not a modal and Tab is a way out of one. */
                 this.hide();
                 return;
             }
@@ -195,87 +86,51 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             }
         };
     }
-    /**
-     * Tells a slotted trigger the disclosure state, by property.
-     *
-     * A control that opens a menu has to say so. By property rather than by
-     * attribute, which is the class note's rule about items applied one level up:
-     * an attribute written onto a consumer's element after it upgrades is a
-     * hydration mismatch waiting to happen.
-     */
     tellTrigger() {
         const slot = this.renderRoot?.querySelector('slot[name="trigger"]');
         tellDisclosure(slot?.assignedElements({ flatten: false })[0], this.open);
     }
-    /** The element the surface opens against. */
     get trigger() {
         return anchorElement(this.renderRoot?.querySelector('slot[name="trigger"]'), this);
     }
-    /** The items on the page that is showing, which is what the keys move over. */
     get items() {
-        /* Disabled rows are not there for the keyboard.
-         *
-         * A disabled row renders no `tabindex` and cannot take focus, so leaving it
-         * in the list has the arrow keys compute a move onto it, call `focus()` on
-         * something unfocusable, and stop: the keyboard is then stuck one row above
-         * every disabled item in the menu. `Drilldown` filters for the same
-         * reason. */
         return this.drilldown.rows.filter((row) => !row.disabled);
     }
-    /** Opens the menu. */
     show() {
         if (this.open || !this.requestOpen(true)) {
             return;
         }
         this.updateComplete.then(() => {
-            // Raised in `updated()`, which the state change has just scheduled.
             this.items[0]?.focus();
         });
     }
-    /** Closes the menu, and forgets which page was showing. */
     hide() {
         if (!this.open || !this.requestOpen(false)) {
             return;
         }
         this.panel.hide();
         this.drilldown.reset();
-        /* Only where the menu still had it. A dismissal that did not take focus with
-           it, a press somewhere else on the page, should leave focus where the
-           reader put it rather than yanking it back to the trigger. `Popover`
-           guards the same way, and `document.activeElement` retargets to the item
-           host here, which is what makes the containment test work. */
         if (this.contains(document.activeElement)) {
             this.trigger.focus();
         }
     }
-    /** Shows an item's submenu in place of the current page. */
     enter(item) {
         if (!this.drilldown.enter(item)) {
             return;
         }
         this.updateComplete.then(() => this.items[0]?.focusItem());
     }
-    /** Returns to the page above, or closes when there is none. */
     leave() {
         if (this.drilldown.atRoot) {
             this.hide();
             return;
         }
-        /* Held before going back, because focus returns to the row that opened the
-           page being left: a reader who drills in and comes straight out should be
-           on the row they pressed, not at the top of a list they have already
-           read. */
         const leaving = this.drilldown.page;
         this.drilldown.back();
         this.updateComplete.then(() => leaving?.focus());
     }
     connectedCallback() {
         super.connectedCallback();
-        /* Capture, so a drill-in never reaches a consumer's own listener on this
-           same host. The guarantee the class documents is that choosing a row that
-           opens a submenu is navigation rather than a choice, and stopping it in the
-           bubble phase stops it for ancestors and not for the siblings registered
-           here. `Drilldown` learned this already. */
         this.addEventListener('helix-select', this.handleSelect, true);
         this.addEventListener('keydown', this.handleKeydown);
         this.addEventListener('focusin', this.handleFocusIn);
@@ -288,15 +143,8 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
     }
     updated(changed) {
         super.updated(changed);
-        // Every update, so a trigger slotted after the first render is told too.
         this.tellTrigger();
-        /* Put the panel where `open` says, however it got there. Raising it in
-           `show()` and lowering it in `hide()` alone leaves a menu opened by
-           declaring `open` visible, out of the top layer and unanchored: every
-           imperative path works and every declarative one is half-open. */
         if (changed.has('open')) {
-            /* Here rather than a microtask later: `updated()` runs after the render,
-               so the panel is no longer `display: none` and `showPopover` is safe. */
             if (this.open) {
                 this.panel.show();
             }
@@ -304,9 +152,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
                 this.panel.hide();
             }
         }
-        // Every item shows or hides itself: which page is open is this element's
-        // business, and where an item belongs is the item's. Set as a property, so
-        // nothing is written onto a consumer's element.
         for (const child of this.children) {
             const item = child;
             if (item.isMenuItem !== true) {
@@ -315,17 +160,6 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
             this.mark(item, this.drilldown.atRoot);
         }
     }
-    /**
-     * Walks the tree marking which rows are on the page showing.
-     *
-     * Recursive rather than two levels by hand: without `showingSubmenu` on a
-     * nested row, drilling into a third-level submenu renders the header over an
-     * empty panel, the page existing while its rows are still marked as belonging
-     * to the level above. `Drilldown.mark()` is the same walk.
-     *
-     * `slot === 'submenu'` rather than every child, because a row's other
-     * children are its label and its icons.
-     */
     mark(item, onPage) {
         item.onPage = onPage;
         item.showingSubmenu = item === this.drilldown.page;
@@ -347,11 +181,7 @@ let HelixHeadlessMenu = class HelixHeadlessMenu extends MixinCollection(MixinCon
         data-drilled=${this.drilldown.atRoot ? nothing : ''}
         ?hidden=${!this.open}
       >
-        ${
-        // A header rather than a row in the list. The way back is not one of
-        // the things on this page, and putting it in the list means an arrow
-        // press lands on it as though it were.
-        this.drilldown.atRoot
+        ${this.drilldown.atRoot
             ? nothing
             : html `<div part="header">
                 <button