@fusion.dev/helix-headless 0.0.0-dev → 0.0.2

package/dist/menu/item/menu-item.d.ts

@@ -31,15 +31,11 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @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.
+ * @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.
  */
 export declare class HelixHeadlessMenuItem extends HelixElement {
-    /**
-     * What this row stands for, carried in the event when it is chosen.
-     */
-    value: string;
     /**
      * Whether the row is one of a set of choices.
      *
@@ -60,6 +56,14 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * Whether the row can be chosen.
      */
     disabled: boolean;
+    /**
+     * 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.
+     */
+    download: boolean;
     /**
      * Where the row goes, which makes it a real link.
      *
@@ -67,7 +71,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * `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 manoeuvre `Tree.Item` makes and the reason `href`
+     * 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
@@ -81,22 +85,6 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * focus really moves to the row.
      */
     href: string;
-    /**
-     * Where the link opens, for the rows that should leave the page.
-     */
-    target: string;
-    /**
-     * The relationship, which `target="_blank"` should always set.
-     */
-    rel: string;
-    /**
-     * 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.
-     */
-    download: boolean;
     /**
      * Whether this row is on the page currently showing.
      *
@@ -105,6 +93,10 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * writes: which page is open is the menu's business.
      */
     onPage: boolean;
+    /**
+     * The relationship, which `target="_blank"` should always set.
+     */
+    rel: string;
     /**
      * Whether this row's submenu is the page showing.
      *
@@ -115,6 +107,14 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      * page has to keep the slot even when it shows no row of its own.
      */
     showingSubmenu: boolean;
+    /**
+     * Where the link opens, for the rows that should leave the page.
+     */
+    target: string;
+    /**
+     * What this row stands for, carried in the event when it is chosen.
+     */
+    value: string;
     /**
      * @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
@@ -124,15 +124,8 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
     /**
      * Whether anything was slotted into `submenu`.
      *
-     * Client only, and the `?? []` is what makes that true rather than merely
-     * documented. Lit's element shim carries attributes but not a tree, so
-     * `children` is undefined on the server, and this getter is read during
-     * `render`: spreading it threw, and a menu row could not be served at all.
-     * Found by writing this component's SSR spec, which is the only place it
-     * could have been found, because every other path runs in a browser.
-     *
-     * False on the server is also the right answer rather than a safe one: the
-     * server cannot know whether a submenu was slotted, and a row that served a
+     * 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.
      */
@@ -140,36 +133,29 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
     /**
      * Whether anything is slotted into `submenu`. Read after first render.
      *
-     * State rather than a getter over `children`, which is what it was: read
-     * during `render()` with nothing to re-read it, a submenu arriving after the
-     * row's first render produced no caret and no `aria-haspopup` while selecting
-     * the row still drilled in. A framework filling a submenu on demand hit that
-     * every time. `Tree.Item` backs `branch` the same way for the same reason.
+     * 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: bound once, a single drill-in left
-     * it false for good.
-     *
-     * False on the server 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.
+     * once at first render. See the note there.
      */
     private submenu;
     protected firstUpdated(changed: PropertyValues): void;
     /**
      * Re-reads whether anything is in the submenu, from whichever slot is current.
      *
-     * **Bound in the template, and it has to be.** It was `addEventListener` on
-     * the slot found at `firstUpdated`, which is a different element from the one
-     * showing a moment later: 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. The
-     * listener stayed on the discarded slot, and the discarded slot fired
-     * `slotchange` on its way out with nothing assigned to it any more. So one
-     * drill-in set `submenu` false and nothing was left listening to set it back:
-     * every caret in the menu vanished and every row stopped opening. Reported
-     * from a recording of the sandbox's Environment menu.
+     * **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.

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

@@ -40,17 +40,13 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
  * @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.
+ * @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);
-        /**
-         * What this row stands for, carried in the event when it is chosen.
-         */
-        this.value = '';
         /**
          * Whether the row is one of a set of choices.
          *
@@ -71,6 +67,14 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
          * 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.
          *
@@ -78,7 +82,7 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
          * `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 manoeuvre `Tree.Item` makes and the reason `href`
+         * 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
@@ -92,22 +96,6 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
          * focus really moves to the row.
          */
         this.href = '';
-        /**
-         * Where the link opens, for the rows that should leave the page.
-         */
-        this.target = '';
-        /**
-         * The relationship, which `target="_blank"` should always set.
-         */
-        this.rel = '';
-        /**
-         * 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;
         /**
          * Whether this row is on the page currently showing.
          *
@@ -116,6 +104,10 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
          * 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.
          *
@@ -126,6 +118,14 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
          * 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
@@ -135,35 +135,28 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
         /**
          * Whether anything is slotted into `submenu`. Read after first render.
          *
-         * State rather than a getter over `children`, which is what it was: read
-         * during `render()` with nothing to re-read it, a submenu arriving after the
-         * row's first render produced no caret and no `aria-haspopup` while selecting
-         * the row still drilled in. A framework filling a submenu on demand hit that
-         * every time. `Tree.Item` backs `branch` the same way for the same reason.
+         * 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: bound once, a single drill-in left
-         * it false for good.
-         *
-         * False on the server 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.
+         * 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.** It was `addEventListener` on
-         * the slot found at `firstUpdated`, which is a different element from the one
-         * showing a moment later: 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. The
-         * listener stayed on the discarded slot, and the discarded slot fired
-         * `slotchange` on its way out with nothing assigned to it any more. So one
-         * drill-in set `submenu` false and nothing was left listening to set it back:
-         * every caret in the menu vanished and every row stopped opening. Reported
-         * from a recording of the sandbox's Environment menu.
+         * **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.
@@ -211,15 +204,8 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
     /**
      * Whether anything was slotted into `submenu`.
      *
-     * Client only, and the `?? []` is what makes that true rather than merely
-     * documented. Lit's element shim carries attributes but not a tree, so
-     * `children` is undefined on the server, and this getter is read during
-     * `render`: spreading it threw, and a menu row could not be served at all.
-     * Found by writing this component's SSR spec, which is the only place it
-     * could have been found, because every other path runs in a browser.
-     *
-     * False on the server is also the right answer rather than a safe one: the
-     * server cannot know whether a submenu was slotted, and a row that served a
+     * 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.
      */
@@ -366,9 +352,6 @@ let HelixHeadlessMenuItem = class HelixHeadlessMenuItem extends HelixElement {
       <slot name="submenu" @slotchange=${this.readSubmenu}></slot>`;
     }
 };
-__decorate([
-    property()
-], HelixHeadlessMenuItem.prototype, "value", void 0);
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessMenuItem.prototype, "checkable", void 0);
@@ -378,24 +361,27 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessMenuItem.prototype, "disabled", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessMenuItem.prototype, "download", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "href", void 0);
 __decorate([
-    property()
-], HelixHeadlessMenuItem.prototype, "target", void 0);
+    property({ attribute: false })
+], HelixHeadlessMenuItem.prototype, "onPage", void 0);
 __decorate([
     property()
 ], HelixHeadlessMenuItem.prototype, "rel", void 0);
-__decorate([
-    property({ type: Boolean })
-], HelixHeadlessMenuItem.prototype, "download", void 0);
-__decorate([
-    property({ attribute: false })
-], HelixHeadlessMenuItem.prototype, "onPage", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessMenuItem.prototype, "showingSubmenu", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenuItem.prototype, "target", void 0);
+__decorate([
+    property()
+], HelixHeadlessMenuItem.prototype, "value", void 0);
 __decorate([
     state()
 ], HelixHeadlessMenuItem.prototype, "submenu", void 0);

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

@@ -46,32 +46,29 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  */
 export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     /**
-     * Preferred side.
-     *
-     * It moves if that side does not fit.
-     */
-    placement: Placement;
-    /**
-     * Space between the trigger and the surface, in pixels.
+     * What the row returning from a submenu reads.
      */
-    offset: number;
+    backLabel: string;
     /**
      * Accessible name for the surface.
      */
     label: string;
     /**
-     * What the row returning from a submenu reads.
+     * Space between the trigger and the surface, in pixels.
      */
-    backLabel: string;
+    offset: number;
+    /**
+     * Preferred side.
+     *
+     * It moves if that side does not fit.
+     */
+    placement: Placement;
     /**
      * Which page is showing, and what is on it.
      *
-     * This was a `page` field, a title getter and an items getter written here.
-     * None of them were about menus: a settings panel or a navigation tree wants
-     * the same thing, and could not have it without being a menu. The controller
-     * holds the same shape, so the port is a rename rather than a rewrite, and it
-     * adds a real stack: `back()` returns one level instead of to the root, which
-     * this could not do because it only ever went two deep.
+     * 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.
      */
     private readonly drilldown;
     /**
@@ -81,14 +78,12 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * 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, which took a wrong turn first and is worth
-     * recording. `focus` looks like the right reading, since a menu's current row
-     * is the focused one, but that origin also carries a rule a menu must not
-     * follow: a press that 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. It moved nothing, and the specs
-     * written alongside this are what said so.
+     * 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
@@ -99,11 +94,10 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     /**
      * Tells a slotted trigger the disclosure state, by property.
      *
-     * This menu wrote nothing onto its trigger, which was the right call and cost
-     * a reader the one thing they needed: a control that opens a menu and never
-     * says so. The class note above already gives the mechanism for the way out,
-     * that items are "told by property, not by attribute", and `tellDisclosure`
-     * is that argument applied one level up. See #322.
+     * 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.
      */
     private tellTrigger;
     /** The element the surface opens against. */
@@ -122,12 +116,9 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     /**
      * Keeps whatever has focus in sight, however it got there.
      *
-     * This was done in the arrow branches, which meant it was true of the arrow
-     * keys and of nothing else: a row reached by Tab, or focused by the drilldown
-     * on the way into a page, could sit below the fold of a scrolled panel. On
-     * `focusin` it is one rule about focus rather than a line repeated in every
-     * branch that moves it, and it survived the arrow keys moving out to a shared
-     * controller that knows nothing about this panel.
+     * 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.
      */
     private readonly handleFocusIn;
     private readonly handleKeydown;
@@ -138,11 +129,10 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     /**
      * Walks the tree marking which rows are on the page showing.
      *
-     * Two levels were marked by hand and nothing wrote `showingSubmenu` on a
-     * nested row, so drilling into a third-level submenu rendered the header over
-     * an empty panel: the page existed, its rows were still marked as belonging
-     * to the level above, and none of them rendered. `Drilldown.mark()` is the
-     * same walk and was already recursive.
+     * 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.