@fusion.dev/helix-headless 0.144.0 → 0.145.0

package/dist/menu/section/menu-section.js

@@ -0,0 +1,60 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
+let HelixHeadlessMenuSection = class HelixHeadlessMenuSection extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = '';
+        this.onPage = true;
+        this.isMenuSection = true;
+        this.heading = false;
+        this.readHeading = (event) => {
+            this.heading = event.target.assignedNodes().length > 0;
+        };
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        if (this.childrenKnown) {
+            this.heading = this.knownChildren.some((child) => child.slot === 'heading');
+        }
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
+    }
+    render() {
+        if (!this.onPage) {
+            return nothing;
+        }
+        return html `<div part="section" role="group" aria-labelledby="heading">
+      <div
+        id="heading"
+        part="heading"
+        role="presentation"
+        ?hidden=${this.label === '' && !this.heading}
+      >
+        <slot name="heading" @slotchange=${this.readHeading}>${this.label}</slot>
+      </div>
+      <slot></slot>
+    </div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessMenuSection.prototype, "label", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMenuSection.prototype, "onPage", void 0);
+__decorate([
+    state()
+], HelixHeadlessMenuSection.prototype, "heading", void 0);
+HelixHeadlessMenuSection = __decorate([
+    customElement('helix-headless-menu-section')
+], HelixHeadlessMenuSection);
+export { HelixHeadlessMenuSection };

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

@@ -1,4 +1,4 @@
-import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
+import { AriaForwardController, HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
  * @summary A set of destinations, with a marker on the current one.
@@ -22,6 +22,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * Set `orientation="vertical"` to stack the destinations in a column, for a
  * sidebar.
  *
+ * Set `arrows` and the arrow keys move focus between the destinations, as
+ * Radix's navigation menu does: left and right along a row, up and down a
+ * column, Home and End to the ends. A `Megamenu` among them is reached at its
+ * trigger. Tab still stops at every link, since a navigation is a list of
+ * links and not a single control, and the keys across the other axis are
+ * left to the page and to an open panel.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -35,6 +42,13 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessNavigation extends HelixElement {
     private readonly indicator;
+    /**
+     * Whether the arrow keys move focus between the destinations.
+     *
+     * Off by default, so a page whose readers scroll with the arrow keys while
+     * a link has focus keeps doing so.
+     */
+    arrows: boolean;
     /**
      * The landmark's name, read by screen readers.
      *
@@ -43,6 +57,7 @@ export declare class HelixHeadlessNavigation extends HelixElement {
      * second "Main".
      */
     label: string;
+    protected readonly keys: KeyboardNavigationController;
     /** Carries a host `aria-label` and `aria-labelledby` to the `<nav>`. */
     protected readonly aria: AriaForwardController;
     /**

package/dist/navigation/root/navigation-root.js

@@ -4,9 +4,24 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, customElement, HelixElement, IndicatorController, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, focusableElements, HelixElement, IndicatorController, KeyboardNavigationController, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+const FOCUSABLE = 'a[href], button, input, select, textarea, [tabindex]:not([tabindex="-1"])';
+const navigable = (item) => {
+    const control = () => item.navigationControl ??
+        (item.matches(FOCUSABLE) ? item : focusableElements(item)[0]);
+    return {
+        contains: (node) => {
+            const target = control();
+            return target !== undefined && node !== null && (node === target || target.contains(node));
+        },
+        disabled: false,
+        focusItem: () => control()?.focus(),
+        select: () => { },
+        selected: false,
+    };
+};
 let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement {
     constructor() {
         super(...arguments);
@@ -23,7 +38,15 @@ let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement
             observe: () => this.items,
             surface: () => this.partNamed('nav'),
         });
+        this.arrows = false;
         this.label = 'Main';
+        this.keys = new KeyboardNavigationController(this, {
+            items: () => (this.arrows ? this.items.map(navigable) : []),
+            origin: 'focus',
+            reserved: () => this.orientation === 'vertical' ? ['ArrowLeft', 'ArrowRight'] : ['ArrowDown', 'ArrowUp'],
+            selects: () => false,
+            wrap: false,
+        });
         this.aria = new AriaForwardController(this, {
             label: true,
             target: () => this.partNamed('nav'),
@@ -62,6 +85,9 @@ let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement
     </nav>`;
     }
 };
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessNavigation.prototype, "arrows", void 0);
 __decorate([
     property()
 ], HelixHeadlessNavigation.prototype, "label", void 0);

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

@@ -29,6 +29,11 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * the feed holds one page of a longer list, and each row says its place in the
  * whole of it.
  *
+ * **`load-more` adds a button after the list** that sends `helix-load-more`,
+ * for a feed that holds one page of a longer list. Append the next page, set
+ * `loading` while it is on its way, and take `load-more` off once there is
+ * nothing more. The button is hidden while the feed is loading.
+ *
  * @since 0.1.0
  * @status stable
  * @category feedback
@@ -40,6 +45,7 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * @slot header - Above the list, for a title and the mark-all control.
  *
  * @event {HelixDismissEvent} helix-dismiss - Fired when the user dismisses a row. The row dispatches it, and you can listen for it on the feed. Cancelable: cancel it to keep the row.
+ * @event {HelixLoadMoreEvent} helix-load-more - Fired when a reader presses the `load-more` button, asking for the next page of the feed.
  * @event {HelixReadEvent} helix-read - Fired by an item when it is marked read or unread, and by the feed when everything is marked read. Cancelable.
  *
  * @csspart empty - Shown when there is nothing in the feed.
@@ -49,6 +55,7 @@ declare const HelixHeadlessNotifications_base: (new (...args: any[]) => import("
  * @csspart live - A copy of the empty and loading messages, in a live region that screen readers announce when they change. Visually hidden in the styled tier.
  * @csspart loading - Shown while the feed is loading.
  * @csspart mark-all - The control that marks everything read.
+ * @csspart more - The button after the list that asks for more, while `load-more` is set and the feed is not loading.
  *
  * @cssstate media - While a notification in the list holds something in its media slot, so every row keeps that column.
  */
@@ -67,6 +74,15 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
      * The feed's name, read by screen readers.
      */
     label: string;
+    /**
+     * Whether to draw a button after the list that asks for the next page, by
+     * sending `helix-load-more`. Take it off once there is nothing more.
+     */
+    loadMore: boolean;
+    /**
+     * The text of the `load-more` button.
+     */
+    loadMoreLabel: string;
     /**
      * Whether to draw a control that marks everything read.
      */
@@ -244,6 +260,8 @@ export declare class HelixHeadlessNotifications extends HelixHeadlessNotificatio
     private markEmpty;
     protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
+    /** Asks for the next page, for the `load-more` button. */
+    private readonly askForMore;
     /**
      * Marks everything read, and keeps focus in the feed.
      *

package/dist/notifications/root/notifications-root.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, deepContains, focusableElements, HelixElement, HelixReadEvent, hostAria, MixinCollection, markRegion, rovingStop, whenHydrated, } from '@fusion.dev/helix-core';
+import { customElement, deepContains, focusableElements, HelixElement, HelixLoadMoreEvent, HelixReadEvent, hostAria, MixinCollection, markRegion, rovingStop, whenHydrated, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { feedStep } from '../feed-keys.js';
@@ -12,6 +12,8 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
     constructor() {
         super(...arguments);
         this.label = '';
+        this.loadMore = false;
+        this.loadMoreLabel = 'Load more';
         this.markAll = false;
         this.markAllLabel = 'Mark all as read';
         this.handleSlotChange = () => {
@@ -51,6 +53,9 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
                 rowBox(next)?.focus();
             }
         };
+        this.askForMore = () => {
+            this.dispatchEvent(new HelixLoadMoreEvent());
+        };
         this.handleMarkAll = (event) => {
             const button = event.currentTarget;
             const focused = this.shadowRoot?.activeElement === button;
@@ -210,12 +215,23 @@ let HelixHeadlessNotifications = class HelixHeadlessNotifications extends MixinC
         ${this.renderStatus(hasItems)}
       </div>
       ${this.renderLive(hasItems)}
+      ${this.loadMore && !this.loading
+            ? html `<button part="more" type="button" @click=${this.askForMore}>
+              ${this.loadMoreLabel}
+            </button>`
+            : nothing}
       <div part="footer"><slot name="footer"></slot></div>`;
     }
 };
 __decorate([
     property()
 ], HelixHeadlessNotifications.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'load-more', type: Boolean })
+], HelixHeadlessNotifications.prototype, "loadMore", void 0);
+__decorate([
+    property({ attribute: 'load-more-label' })
+], HelixHeadlessNotifications.prototype, "loadMoreLabel", void 0);
 __decorate([
     property({ attribute: 'mark-all', type: Boolean })
 ], HelixHeadlessNotifications.prototype, "markAll", void 0);

package/dist/object-inspector/root/object-inspector-root.d.ts

@@ -1,18 +1,7 @@
 import { AriaForwardController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
-/** One visible line of the tree: a value, where it sits, and whether it is open. */
-interface Row {
-    branch: boolean;
-    depth: number;
-    /** The property name or array index this value is under; absent for the root. */
-    key?: string;
-    open: boolean;
-    path: string;
-    position: number;
-    siblings: number;
-    value: unknown;
-}
+import { type Row } from '../rows.js';
 /**
  * @summary A structured value shown as a tree, where you can close branches,
  * see how many entries each holds, and copy any part.
@@ -34,6 +23,22 @@ interface Row {
  * row. Each row carries its real level, position, and set size, including in
  * a windowed tree.
  *
+ * `active` is the active row's path, written the way a JSON Pointer writes it:
+ * the empty string for the root and `/meta/tags/0` for an entry under it.
+ * Moving to another row sends `helix-before-activate`, which you can cancel,
+ * and then `helix-activate`, both with the path. Writing `active` moves there
+ * and opens the branches around it, and sends nothing. `expanded` holds the
+ * open branches by path, and writing it opens those and closes the rest. A row
+ * that closes around the active one hands it to the nearest open branch.
+ *
+ * `filter` narrows the tree to the entries whose key or value holds the text,
+ * ignoring case, and the branches that lead to them, which it opens. A matched
+ * branch keeps everything under it. Each matched row carries `row-match`, and
+ * a screen reader hears how many entries matched from `result-label` and
+ * `results-label`. `filterable` adds a field that sets it: typing sends
+ * `helix-filter`, which you can cancel, and then `helix-filtered`, and Down
+ * moves from the field to the tree.
+ *
  * A new `value` keeps the branches a reader opened or closed, and the active
  * row, where the new value still has them. A branch the old value did not have
  * opens to `default-depth`.
@@ -53,7 +58,11 @@ interface Row {
  * @aliases JSON viewer, Object viewer, Inspector, Data explorer
  * @documentation https://fusion.dev/helix/components/object-inspector
  *
+ * @event {HelixActivateEvent} helix-activate - The active row moved, by a key or a click. The detail's `value` is its path.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - The active row is about to move, with its new path. Cancelable: cancel it to keep the row where it is.
  * @event {HelixCopyEvent} helix-copy - A value was put on the clipboard, from the copy button or the keyboard.
+ * @event {HelixFilterEvent} helix-filter - Text was typed in the filter field, with what it now holds. Cancelable: cancel it to keep the filter as it was.
+ * @event {HelixFilteredEvent} helix-filtered - The filter field changed `filter`, which now holds the text.
  *
  * @csspart after - The space the rows below the drawn rows would take, when `windowed` is set.
  * @csspart before - The space the rows above the drawn rows would take, when `windowed` is set.
@@ -78,10 +87,13 @@ interface Row {
  * @csspart header - The bar that holds the label, when there is one.
  * @csspart key - A property name or an array index.
  * @csspart label - The label.
+ * @csspart live - How many entries a filter matched, in a region that screen readers announce when it changes. Drawn from the first filter on. Visually hidden in the styled tier.
  * @csspart null - A `null`.
  * @csspart number - A number.
  * @csspart row - One entry, as a tree item.
  * @csspart row-active - The entry the keyboard is on. Set alongside `row`.
+ * @csspart row-match - An entry whose key or value holds the filter. Set alongside `row`.
+ * @csspart search-field - The field that sets `filter`, with `filterable`.
  * @csspart string - A string, in quotes.
  * @csspart summary - The brackets that stand for a branch's contents.
  * @csspart toggle - The caret on a branch. It points down when the branch is open and sideways when it is closed.
@@ -90,6 +102,17 @@ interface Row {
  * @cssproperty --object-inspector-level - How deep a row is, from 0 at the root, for indenting it.
  */
 export declare class HelixHeadlessObjectInspector extends HelixElement {
+    /**
+     * The active row's path, such as `/meta/tags/0`, and the empty string for the
+     * root.
+     *
+     * Reading gives the row the keys are on. Writing moves there, opening the
+     * branches around it, and sends no event, the way a script's write to any
+     * current value sends none. A path the value does not hold moves to the
+     * nearest branch above it that it does.
+     */
+    get active(): string;
+    set active(path: string);
     /**
      * The copy button's accessible name on a row with a key, with the key filled
      * in as `{name}`.
@@ -109,6 +132,23 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * wall of text this exists to avoid.
      */
     defaultDepth: number;
+    /**
+     * The open branches, by path, in no set order.
+     *
+     * Writing opens exactly these and closes every other, keeping the active row
+     * where it stays visible. A property, never an attribute.
+     */
+    get expanded(): string[];
+    set expanded(paths: string[]);
+    /**
+     * Text the tree is narrowed to: the entries whose key or value holds it,
+     * ignoring case, and the branches that lead to them. Empty shows everything.
+     */
+    filter: string;
+    /** Whether to show a field that sets `filter`. */
+    filterable: boolean;
+    /** The filter field's placeholder and accessible name. */
+    filterLabel: string;
     /**
      * The id of a `<script type="application/json">` holding the value.
      *
@@ -143,6 +183,13 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * reach a value.
      */
     noCopy: boolean;
+    /** What a screen reader hears when a filter matches one entry. `{count}` is the count. */
+    resultLabel: string;
+    /**
+     * What a screen reader hears when a filter matches any other number of
+     * entries. `{count}` is the count. The two are chosen by `Intl.PluralRules`.
+     */
+    resultsLabel: string;
     /**
      * The tree's accessible name when `label` is empty and the host names it
      * with neither `aria-label` nor `aria-labelledby`.
@@ -169,7 +216,18 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     /** Which branches are open, by path. */
     private opened;
     /** The row the arrow keys are on, by its place among the visible rows. */
-    private active;
+    private cursor;
+    /** A path written to `active` and not yet found among the rows. */
+    private wanted;
+    /**
+     * The branches written to `expanded`, until the next update applies them.
+     *
+     * Its own field, because a property declared with an accessor is in the
+     * first update's changes whether or not anybody wrote it.
+     */
+    private declared;
+    /** The paths the filter matched, or nothing while there is no filter. */
+    private found;
     /** Set by a keyboard move, so the next render brings the active row into view. */
     private revealing;
     /** What has been typed toward a key, and when the last letter came. */
@@ -178,6 +236,8 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     private branches;
     /** Carries a host `aria-label` and `aria-labelledby` to the tree, which is what takes focus. */
     protected readonly aria: AriaForwardController;
+    /** Says how many entries a filter matched. */
+    private readonly status;
     /**
      * How tall a row is taken to be before it has been drawn, in pixels.
      *
@@ -193,8 +253,6 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     /** Every visible row, in order, worked out once per change rather than per read. */
     private rows;
     private readonly copier;
-    /** Every visible row, in order, for the tree as it stands. */
-    private flatten;
     /**
      * Opens every branch shallower than `defaultDepth`.
      *
@@ -205,7 +263,17 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * place on every update.
      */
     private seed;
+    /** Opens the branches around each path, where the value has them. */
+    private openAround;
     protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Where the active row goes once the rows have moved: onto `path` where it
+     * is still shown, onto the first match where a filter just hid it, and
+     * otherwise onto the nearest branch around it that is.
+     */
+    private place;
+    /** Says how many entries the filter matched, and nothing for an empty one. */
+    private tell;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     private load;
@@ -225,6 +293,10 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
     /** What copying takes: a branch as indented JSON, a string as itself. */
     private copyable;
     private toggle;
+    /**
+     * Moves the active row, asking first: `helix-before-activate` with the path,
+     * then `helix-activate` once it has moved. Returns whether it is there.
+     */
     private move;
     private readonly handleKeydown;
     /** Opens every branch at the active row's level under the same parent, as `*` asks. */
@@ -237,7 +309,12 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * keys that start with it.
      */
     private typeahead;
+    /** A press opens or closes the row it lands on, once that row is the active one. */
     private handleRowClick;
+    /** Text typed in the filter field, asked for before the tree narrows to it. */
+    private readonly handleFilterInput;
+    /** Down from the filter field goes to the tree, where the matches are. */
+    private readonly handleFilterKeydown;
     private renderValue;
     /**
      * One entry, named for its state where it holds one.
@@ -248,6 +325,11 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      * attribute would be a second spelling with no reader. The name is the one a
      * consumer can reach, nothing being able to follow `::part()` with an
      * attribute selector.
+     *
+     * **`aria-selected="false"` on every row**, because nothing here is chosen.
+     * Chromium takes the active descendant of a single-selection tree as selected
+     * when no row says otherwise, so every arrow press was also announced as a
+     * selection. An explicit false is the one thing that turns that off.
      */
     private renderRow;
     /** The copy button, behind the seam Code Block's uses, so each tier renders its own. */
@@ -259,4 +341,3 @@ declare global {
         'helix-headless-object-inspector': HelixHeadlessObjectInspector;
     }
 }
-export {};