@fusion.dev/helix-headless 0.183.0 → 0.184.0

package/dist/code-block/root/code-block-root.d.ts

@@ -1,6 +1,29 @@
 import { HelixElement } from '@fusion.dev/helix-core';
-import { type PropertyValues, type TemplateResult } from 'lit';
+import { type CSSResult, type PropertyValues, type TemplateResult } from 'lit';
 import '../../copy-button/index.js';
+/**
+ * Turns code into highlighted markup for a block's `language`, or returns
+ * `undefined` for a language it does not read, which the block then draws
+ * plain.
+ */
+export type CodeBlockHighlighter = (code: string, language: string) => string | undefined;
+/**
+ * Gives every Code Block of both tiers a highlighter, for the blocks that set
+ * no `highlight` of their own, and the sheet that colors what it returns.
+ *
+ * **Opt-in, so a page that shows plain code carries no grammar.** Code Block
+ * ships none: a grammar is the larger part of any highlighter, and a block
+ * that registers one for every page makes every page pay for it. A page that
+ * wants color imports one entry that calls this, such as
+ * `@fusion.dev/helix-sandbox/code-block`, which reads `css`, `html`, `js`,
+ * `jsx`, `sh`, `ts` and `tsx` with the sandbox's Lezer grammars and colors
+ * them from the `--helix-color-syntax-*` tokens.
+ *
+ * A block's own `highlight` wins over this. Blocks already on the page draw
+ * again with it, and every block built after has it. `undefined` takes it
+ * away again.
+ */
+export declare const registerHighlighter: (highlighter: CodeBlockHighlighter | undefined, sheet?: CSSResult) => void;
 /**
  * @summary A block of code with an optional name and a copy button.
  *
@@ -37,6 +60,20 @@ import '../../copy-button/index.js';
  * the slot, so the copy button and the page's own text are the code as
  * written.
  *
+ * **Code Block ships no grammar**, so plain code costs you no parser. To color
+ * code without a highlighter of your own, import one more entry beside the
+ * block's. It colors every block by its `language` (`css`, `html`, `js`,
+ * `jsx`, `sh`, `ts`, or `tsx`) with the Lezer grammars of the sandbox's
+ * editor, in the editor's colors:
+ *
+ * ```js
+ * import '@fusion.dev/helix/code-block'
+ * import '@fusion.dev/helix-sandbox/code-block'
+ * ```
+ *
+ * That entry calls `registerHighlighter`, which you can also call yourself to
+ * give every block one highlighter of your own.
+ *
  * Set `expandable` on a block whose height is capped, such as by
  * `--code-block-max-block-size`, and a button under it shows every line and
  * then fewer again, as a docs site's long example does. The button is drawn
@@ -269,6 +306,10 @@ export declare class HelixHeadlessCodeBlock extends HelixElement {
      * in the slot, so the copy button copies it as written and a reader without
      * the script still has it. Not called on a server, which has no code to
      * read, nor for a diff.
+     *
+     * Absent, the block draws with the highlighter `registerHighlighter` gave
+     * every block, where an entry such as `@fusion.dev/helix-sandbox/code-block`
+     * registered one, and plain otherwise.
      */
     highlight?: (code: string, language: string) => string;
     /**

package/dist/code-block/root/code-block-root.js

@@ -8,6 +8,27 @@ import '../../copy-button/index.js';
 import { highlightedLines } from '../highlight.js';
 import { gutterNumbers, lineCount, lineRuns, lineSpans } from '../lines.js';
 import { foldContext, pairLines, parsePatch, } from '../patch.js';
+let registered;
+const adoptRegistered = (block) => {
+    const root = block.shadowRoot;
+    const sheet = registered?.sheet?.styleSheet;
+    if (root && sheet && !root.adoptedStyleSheets.includes(sheet)) {
+        root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+    }
+};
+const blocksOnPage = (root = document) => [...root.querySelectorAll('*')].flatMap((node) => [
+    ...(node instanceof HelixHeadlessCodeBlock ? [node] : []),
+    ...(node.shadowRoot ? blocksOnPage(node.shadowRoot) : []),
+]);
+export const registerHighlighter = (highlighter, sheet) => {
+    registered = highlighter ? { highlighter, sheet } : undefined;
+    if (typeof document !== 'undefined') {
+        for (const block of blocksOnPage()) {
+            adoptRegistered(block);
+            block.requestUpdate();
+        }
+    }
+};
 const stopPress = (event) => event.stopPropagation();
 const isBlock = (element) => element?.localName.endsWith('code-block') === true;
 const blocksIn = (host) => [...host.children].filter((child) => child.slot === '' && isBlock(child));
@@ -332,6 +353,7 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
+        adoptRegistered(this);
     }
     render() {
         const blocks = this.blocks;
@@ -344,11 +366,10 @@ let HelixHeadlessCodeBlock = class HelixHeadlessCodeBlock extends HelixElement {
         }
         const text = this.text;
         let highlighted;
+        const highlight = this.highlight ?? registered?.highlighter;
         try {
-            highlighted =
-                this.highlight && text !== ''
-                    ? highlightedLines(this.highlight(text, this.language))
-                    : undefined;
+            const markup = highlight && text !== '' ? highlight(text, this.language) : undefined;
+            highlighted = markup === undefined ? undefined : highlightedLines(markup);
         }
         catch (error) {
             globalThis.reportError?.(error);

package/dist/index.d.ts

@@ -63,6 +63,7 @@ export * from './listbox/index.js';
 export * from './loader/index.js';
 export * from './map/index.js';
 export * from './megamenu/index.js';
+export * from './menu/filter/index.js';
 export * from './menu/index.js';
 export * from './meter/index.js';
 export * from './navigation/index.js';

package/dist/index.js

@@ -54,6 +54,7 @@ export * from './listbox/index.js';
 export * from './loader/index.js';
 export * from './map/index.js';
 export * from './megamenu/index.js';
+export * from './menu/filter/index.js';
 export * from './menu/index.js';
 export * from './meter/index.js';
 export * from './navigation/index.js';

package/dist/menu/filter/index.d.ts

@@ -0,0 +1 @@
+export { filterMenu, MenuFilterController } from './menu-filter.js';

package/dist/menu/filter/index.js

@@ -0,0 +1,4 @@
+import { HelixHeadlessMenu } from '../root/menu-root.js';
+import { filterMenu } from './menu-filter.js';
+filterMenu(HelixHeadlessMenu);
+export { filterMenu, MenuFilterController } from './menu-filter.js';

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

@@ -0,0 +1,114 @@
+import { type CSSResult, nothing, type ReactiveController, type TemplateResult } from 'lit';
+import type { HelixHeadlessMenuItem } from '../item/menu-item.js';
+import type { HelixHeadlessMenu } from '../root/menu-root.js';
+type Row = HelixHeadlessMenuItem;
+/**
+ * The field and then the `menu`: a menu holds menu items and nothing else, so
+ * the field stands beside it, as React Aria's `Autocomplete` puts its search
+ * field beside its menu. The menu calls it through its filter, so the parts it
+ * writes are the menu's.
+ */
+export declare const drawFilter: (host: HelixHeadlessMenu, rows: TemplateResult, busy: string | typeof nothing, onInput: (event: Event) => void) => TemplateResult;
+/**
+ * Narrows a `filterable` menu's rows as the reader types in a field above
+ * them, with focus staying in the field and the highlight moving through the
+ * rows that are left.
+ *
+ * **Its own entry**, `@fusion.dev/helix-headless/menu/filter`, so a menu that
+ * never filters carries none of this. Importing the entry gives every menu of
+ * the tier one, and `filterable` turns it on. Menu's description says what a
+ * reader gets; this is the part of it the menu does not hold:
+ *
+ * - the field and the `menu` after it, which the menu draws in its surface
+ * - which rows the filter keeps, and the words each matched, marked
+ * - the keys the field answers: Up and Down move the highlight, Enter presses
+ *   the highlighted row, and Escape clears the filter before it closes
+ * - `helix-filter`, sent as the text changes, which a listener cancels to
+ *   keep every row showing
+ * - how many rows are kept, or `no-results-text`, said in the live region
+ *
+ * The styled tier's entry hands in the sheet that draws the field, which the
+ * menu adopts while it filters.
+ */
+export declare class MenuFilterController implements ReactiveController {
+    private readonly host;
+    /** The same menu, read through what it keeps to itself. */
+    private readonly inside;
+    /** The sheet the menu adopts while it filters, from the styled tier. */
+    sheet: CSSResult | undefined;
+    /** The row the keys reached while focus stays in the field. */
+    highlighted: Row | undefined;
+    /** The submenu the filter narrows, or null for the top page. */
+    private page;
+    /** The filter a listener refused, which narrows nothing. */
+    private refused;
+    /** The filter the last update saw, so a change moves a highlight it hid. */
+    private seen;
+    constructor(host: HelixHeadlessMenu, sheet?: CSSResult);
+    hostConnected(): void;
+    hostDisconnected(): void;
+    /** The field, while it is drawn. */
+    get field(): HTMLInputElement | null;
+    /** Whether the filter is narrowing the rows. */
+    get filtering(): boolean;
+    /** Whether the filter keeps a row: one of another page, or one whose words it matches. */
+    kept(row: Row): boolean;
+    /** The rows of the page the filter narrows that it keeps. */
+    private get keptRows();
+    /**
+     * Asks to filter by new text, which the field and `filter` then hold. A
+     * refusal keeps every row showing, for a page that narrows them itself.
+     */
+    request(value: string): void;
+    /** Filters by what the reader typed, and highlights the first row kept. */
+    private by;
+    /**
+     * Puts the highlight on a row, which the field names with
+     * `aria-activedescendant`. An element reference, because the field is in
+     * the menu's shadow root and the row in the tree around it, the one
+     * direction a reference crosses.
+     */
+    highlight(row: Row | undefined): void;
+    /**
+     * Answers a key the field takes, and returns whether it did: Up and Down
+     * move the highlight through the rows kept, Enter presses the highlighted
+     * row, and Escape over text empties the filter, the next one going back or
+     * closing.
+     */
+    keydown(event: KeyboardEvent, items: Row[], at: number): boolean;
+    /**
+     * Keeps focus in the field through a press on a row or the way back, as
+     * React Aria's virtual focus does: the press still chooses.
+     */
+    private readonly handleMouseDown;
+    private readonly handleInput;
+    /**
+     * What a filter that keeps no rows shows, or nothing where it keeps some.
+     *
+     * It sets what the live region says as well: `no-results-text` where the
+     * filter keeps no rows, and how many it keeps where it keeps some, as React
+     * Aria and Web Awesome say the count. Only "No matches" was said before
+     * that, so a filter that kept forty rows and one that kept one sounded the
+     * same.
+     */
+    status(): TemplateResult | undefined;
+    /** The field and then the `menu`, for the menu to draw in its surface. See `drawFilter`. */
+    drawFilter(rows: TemplateResult, busy: string | typeof nothing): TemplateResult;
+    /**
+     * Marks the words each kept row matched, as Listbox marks its options, and
+     * moves a highlight the filter hid to the first row it keeps. Called by the
+     * menu after it has marked which rows are on the page.
+     */
+    updated(): void;
+}
+/**
+ * Gives every menu of a class a `MenuFilterController`, which `filterable`
+ * turns on.
+ *
+ * The entries call it for their own tier's class: the headless entry for
+ * `HelixHeadlessMenu`, and the styled one for `HelixMenu`, with the sheet that
+ * draws the field. **Menus already on the page are given one too**, and drawn
+ * again, so a page that imports the menu and then this entry gets the field.
+ */
+export declare const filterMenu: (element: typeof HelixHeadlessMenu, sheet?: CSSResult) => void;
+export {};

package/dist/menu/filter/menu-filter.js

@@ -0,0 +1,172 @@
+import { filterKeeps, formatWords, HelixFilterEvent, markMatches, slottedWords, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+export const drawFilter = (host, rows, busy, onInput) => html `<input
+    part="search-field"
+    type="text"
+    autocomplete="off"
+    spellcheck="false"
+    .value=${host.filter}
+    placeholder=${host.filterLabel}
+    aria-label=${host.filterLabel}
+    aria-autocomplete="list"
+    aria-controls="items"
+    @input=${onInput}
+  /><div id="items" role="menu" aria-busy=${busy} aria-label=${host.label || nothing}>${rows}</div>`;
+export class MenuFilterController {
+    constructor(host, sheet) {
+        this.page = null;
+        this.seen = '';
+        this.handleMouseDown = (event) => {
+            if (this.host.filterable &&
+                this.host.open &&
+                event.composedPath()[0] !== this.field &&
+                !this.inside.fromTrigger(event)) {
+                event.preventDefault();
+            }
+        };
+        this.handleInput = (event) => {
+            event.stopPropagation();
+            this.by(event.target.value);
+        };
+        this.host = host;
+        this.inside = host;
+        this.sheet = sheet;
+        this.inside.filterer = this;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('mousedown', this.handleMouseDown);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('mousedown', this.handleMouseDown);
+        if (this.host.filterable) {
+            markMatches(this.host, [], '');
+        }
+    }
+    get field() {
+        return this.host.renderRoot?.querySelector('[part="search-field"]') ?? null;
+    }
+    get filtering() {
+        const { filter } = this.host;
+        return this.host.filterable && filter.trim() !== '' && filter !== this.refused;
+    }
+    kept(row) {
+        return (!this.filtering ||
+            this.inside.holderOf(row) !== this.page ||
+            filterKeeps(slottedWords(row, ['']), this.host.filter.trim(), this.host.filterMatch));
+    }
+    get keptRows() {
+        return this.inside.rowsOf(this.page).filter((row) => this.kept(row));
+    }
+    request(value) {
+        const { host, inside } = this;
+        if (value === host.filter) {
+            return;
+        }
+        this.page = inside.flies ? inside.keyPage : inside.drilldown.page;
+        this.refused = host.dispatchEvent(new HelixFilterEvent({ value })) ? undefined : value;
+        host.filter = value;
+    }
+    by(value) {
+        this.request(value);
+        void this.host.updateComplete.then(() => this.inside.reach(this.inside.items[0]));
+    }
+    highlight(row) {
+        if (this.highlighted && this.highlighted !== row) {
+            this.highlighted.highlighted = false;
+        }
+        this.highlighted = row;
+        const field = this.field;
+        if (field && 'ariaActiveDescendantElement' in field) {
+            field.ariaActiveDescendantElement = row ?? null;
+        }
+        if (row) {
+            row.highlighted = true;
+        }
+    }
+    keydown(event, items, at) {
+        if (event.key === 'Escape') {
+            if (this.host.filter === '') {
+                return false;
+            }
+            event.stopPropagation();
+            this.by('');
+            return true;
+        }
+        if (event.composedPath()[0] !== this.field) {
+            return false;
+        }
+        const step = event.key === 'ArrowDown' ? 1 : event.key === 'ArrowUp' ? -1 : 0;
+        if (step !== 0) {
+            const count = items.length;
+            this.inside.reach(items[at < 0 ? (step > 0 ? 0 : count - 1) : (at + step + count) % count]);
+            return true;
+        }
+        if (event.key === 'Enter') {
+            items[at]?.renderRoot.querySelector('[part="item"]')?.click();
+            return true;
+        }
+        return false;
+    }
+    status() {
+        const { host } = this;
+        const count = this.filtering ? this.keptRows.length : -1;
+        this.inside.announced =
+            count === 0
+                ? host.noResultsText
+                : count > 0
+                    ? formatWords(host, 'resultsLabel', { count })
+                    : '';
+        return count === 0
+            ? html `<p part="empty"><slot name="no-results">${host.noResultsText}</slot></p>`
+            : undefined;
+    }
+    drawFilter(rows, busy) {
+        return drawFilter(this.host, rows, busy, this.handleInput);
+    }
+    updated() {
+        const { host } = this;
+        adopt(host, this.sheet, host.filterable);
+        if (!host.filterable) {
+            return;
+        }
+        markMatches(host, this.keptRows, this.filtering ? host.filter.trim() : '');
+        const changed = host.filter !== this.seen;
+        this.seen = host.filter;
+        const items = this.inside.items;
+        if (changed && host.open && !items.includes(this.highlighted)) {
+            this.inside.reach(items[0]);
+        }
+    }
+}
+const adopt = (element, given, on) => {
+    const root = element.shadowRoot;
+    const sheet = given?.styleSheet;
+    if (!root || !sheet || root.adoptedStyleSheets.includes(sheet) === on) {
+        return;
+    }
+    root.adoptedStyleSheets = on
+        ? [...root.adoptedStyleSheets, sheet]
+        : root.adoptedStyleSheets.filter((one) => one !== sheet);
+};
+const onPage = (of, root = document) => [...root.querySelectorAll('*')].flatMap((node) => [
+    ...(node instanceof of ? [node] : []),
+    ...(node.shadowRoot ? onPage(of, node.shadowRoot) : []),
+]);
+export const filterMenu = (element, sheet) => {
+    const attach = (menu) => {
+        const inside = menu;
+        if (inside.filterer) {
+            inside.filterer.sheet ??= sheet;
+            return;
+        }
+        new MenuFilterController(menu, sheet);
+    };
+    element.addInitializer((host) => attach(host));
+    if (typeof document !== 'undefined') {
+        for (const menu of onPage(element)) {
+            attach(menu);
+            menu.requestUpdate();
+        }
+    }
+};

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

@@ -72,7 +72,15 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * opens it from the keyboard, and the trigger is described by
  * `long-press-label`, which says so.
  *
- * **A filter field.** With `filterable`, the menu opens with focus in a field
+ * **A filter field** is a separate import, `@fusion.dev/helix/menu/filter`, so
+ * a menu that never filters carries none of its code:
+ *
+ * ```js
+ * import '@fusion.dev/helix/menu'
+ * import '@fusion.dev/helix/menu/filter'
+ * ```
+ *
+ * With it imported and `filterable` set, the menu opens with focus in a field
  * above its rows, and typing narrows the rows of the page the keys move in,
  * as React Aria's `Autocomplete` around a `Menu` does. A row is kept where its
  * words hold the filter, in any case, or where `filterMatch` says so. Each
@@ -165,7 +173,11 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     filter: string;
     /**
      * Whether the menu shows a field above its rows that narrows them as the
-     * reader types, with focus staying in the field.
+     * reader types, with focus staying in the field, once
+     * `@fusion.dev/helix/menu/filter` (or `@fusion.dev/helix-headless/menu/filter`)
+     * is imported. Without that import it does nothing, so a menu that never
+     * filters carries none of the filter's code, and a development build says
+     * which import is missing.
      */
     filterable: boolean;
     /**
@@ -305,31 +317,23 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private get items();
     /** The element that is the `menu`: the surface, or with `filterable` the box after the field. */
     private get menuBox();
-    /** The filter field, with `filterable`. */
-    private get field();
-    /** The submenu the filter narrows, or null for the top page. */
-    private filterPage;
-    /** The filter a listener refused, which narrows nothing. */
-    private refused;
-    /** Whether the filter is narrowing the rows. */
-    private get filtering();
-    /** Whether the filter keeps a row: one of another page, or one whose words it matches. */
-    private kept;
     /**
-     * Asks to filter by new text, which the field and `filter` then hold. A
-     * refusal keeps every row showing, for a page that narrows them itself.
-     */
+     * The filter `menu/filter` gives this menu, which `filterable` turns on.
+     *
+     * Declared and never initialized, because the entry sets it from the
+     * constructor Lit runs initializers in, which is before this class's own
+     * fields: an initializer here would set it back to `undefined`.
+     */
+    private filterer;
+    /** The filter, while `filterable` is set and `menu/filter` is imported. */
+    private get filters();
+    /** Whether the filter keeps a row, which every row is without one. */
+    private kept;
+    /** Asks to filter by new text. See `MenuFilterController.request`. */
     private requestFilter;
-    private readonly handleFilterInput;
-    /** Filters by what the reader typed, and highlights the first row kept. */
-    private filterBy;
-    /** The row the keys reached while focus stays in the filter field. */
-    private highlighted;
     /**
-     * Moves the reader to a row: focus, or with `filterable` the highlight,
-     * which the field names with `aria-activedescendant`. An element reference,
-     * because the field is in this shadow root and the row in the tree around
-     * it, the one direction a reference crosses.
+     * Moves the reader to a row: focus, or with a filter the highlight, focus
+     * staying in the filter field.
      */
     private reach;
     /** Watches for rows taken away while the menu is open. */
@@ -408,11 +412,6 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      * `open-on="long-press"`, or a touch or a pen held on a context menu's area.
      */
     private readonly handlePointerDown;
-    /**
-     * Keeps focus in the filter field through a press on a row or the way
-     * back, as React Aria's virtual focus does: the press still chooses.
-     */
-    private readonly handleMouseDown;
     private readonly handlePointerMove;
     private readonly handlePointerUp;
     private readonly handlePointerCancel;