@fusion.dev/helix-core 0.218.0 → 0.220.0

package/dist/utils/audit-children/audit-children.d.ts

@@ -1,3 +1,14 @@
+/**
+ * How long, in milliseconds, the page goes without loading a resource or
+ * registering a Helix family before a child still undefined counts as missing.
+ *
+ * **An app that imports its families with `import()` registers them after
+ * the page has loaded**, each as its chunk arrives, so a container can be
+ * defined and painted while the chunk holding its children is still in
+ * flight. Measured in the Hartley desktop app on October 14, 2026: Command was
+ * defined 90 ms before Option, and its families arrived over 230 ms.
+ */
+export declare const QUIET = 500;
 /**
  * Reports a child from another family that a container holds and nobody
  * registered, naming the entry to import.
@@ -9,8 +20,10 @@
  * This says so, once for each container tag and child tag on the page, with
  * the line to add.
  *
- * Asked once the page has loaded and painted, so an entry a later module
- * imports is not taken for a missing one.
+ * Asked once the page has loaded and painted. A child still undefined then
+ * is reported once the page has loaded and registered nothing for `QUIET`
+ * milliseconds and the tag is still undefined, so an entry a later module or
+ * a later chunk imports is not taken for a missing one.
  *
  * **In a development build only**, as `missing-name` is: every container would
  * pay for a sentence meant for the person writing the page. Core imports it as
@@ -40,6 +53,8 @@ export declare const auditChildren: (host: HTMLElement, part: string, entry: str
  * `attribute` is the one the page set, `entry` the entry after the tier's
  * package, such as `menu/filter`, and `consequence` what the missing entry
  * costs, after "so". `missing` is asked once the page has loaded and painted,
- * so an entry a later module imports is not taken for a missing one.
+ * and again once the page has loaded and registered nothing for `QUIET`
+ * milliseconds, so an entry a later module or a later chunk imports is not
+ * taken for a missing one.
  */
 export declare const auditEntry: (host: HTMLElement, attribute: string, entry: string, consequence: string, missing: () => boolean) => void;

package/dist/utils/audit-children/audit-children.js

@@ -1,3 +1,4 @@
+import { definedTags } from '../custom-element/custom-element.js';
 import { howToRegister } from '../how-to-register/how-to-register.js';
 import { reportRuntime } from '../report-runtime/report-runtime.js';
 const reported = new Set();
@@ -12,6 +13,27 @@ const afterPaint = (check) => {
         window.addEventListener('load', frame, { once: true });
     }
 };
+export const QUIET = 500;
+const activity = () => definedTags().length + (performance.getEntriesByType?.('resource').length ?? 0);
+const whenQuiet = () => new Promise((resolve) => {
+    let seen = activity();
+    let periods = 0;
+    const wait = () => {
+        setTimeout(() => {
+            const now = activity();
+            periods += 1;
+            if (now === seen || periods >= 20) {
+                resolve();
+            }
+            else {
+                seen = now;
+                wait();
+            }
+        }, QUIET);
+    };
+    wait();
+});
+const settled = (tag) => Promise.race([customElements.whenDefined(tag), whenQuiet()]);
 export const auditChildren = (host, part, entry, consequence, drawn = false) => {
     if (typeof window === 'undefined') {
         return;
@@ -22,11 +44,16 @@ export const auditChildren = (host, part, entry, consequence, drawn = false) =>
     if (reported.has(key)) {
         return;
     }
-    const check = () => {
-        if (reported.has(key) ||
-            !host.isConnected ||
-            customElements.get(tag) !== undefined ||
-            (!drawn && host.querySelector(tag) === null)) {
+    const fine = () => reported.has(key) ||
+        !host.isConnected ||
+        customElements.get(tag) !== undefined ||
+        (!drawn && host.querySelector(tag) === null);
+    const check = async () => {
+        if (fine()) {
+            return;
+        }
+        await settled(tag);
+        if (fine()) {
             return;
         }
         reported.add(key);
@@ -36,7 +63,7 @@ export const auditChildren = (host, part, entry, consequence, drawn = false) =>
             tag: host.localName,
         });
     };
-    afterPaint(check);
+    afterPaint(() => void check());
 };
 export const auditEntry = (host, attribute, entry, consequence, missing) => {
     if (typeof window === 'undefined') {
@@ -46,8 +73,13 @@ export const auditEntry = (host, attribute, entry, consequence, missing) => {
     if (reported.has(key)) {
         return;
     }
-    afterPaint(() => {
-        if (reported.has(key) || !host.isConnected || !missing()) {
+    const fine = () => reported.has(key) || !host.isConnected || !missing();
+    const check = async () => {
+        if (fine()) {
+            return;
+        }
+        await whenQuiet();
+        if (fine()) {
             return;
         }
         reported.add(key);
@@ -58,5 +90,6 @@ export const auditEntry = (host, attribute, entry, consequence, missing) => {
             message: `<${host.localName}> has \`${attribute}\` and its entry is not imported, so ${consequence}. Import '${pkg}/${entry}'.`,
             tag: host.localName,
         });
-    });
+    };
+    afterPaint(() => void check());
 };

package/dist/utils/find-text/find-text.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Finding words in what a page shows, as ranges over its text, and painting
+ * them with the Custom Highlight API: the query every finder takes, and the
+ * finder Find uses for the content its `for` names.
+ *
+ * **Painted, and nothing is inserted.** The text is the page's own light DOM,
+ * often written by React or by another Helix family, and a `<mark>` wrapped
+ * around a match would be undone by the next render or would break it, as
+ * `filter-marks` explains for a filtered list.
+ */
+/** What every match is painted as, in `CSS.highlights` and in `base.css`. */
+export declare const FIND_MATCH = "helix-find-match";
+/** What the current match is painted as, over the others. */
+export declare const FIND_CURRENT = "helix-find-current";
+/** The search Find hands a finder. */
+export interface FindQuery {
+    /** Whether case has to match, so "Error" does not find "error". */
+    caseSensitive: boolean;
+    /** Whether `search` is a regular expression, in JavaScript's syntax. */
+    regex: boolean;
+    /** What Replace puts in place of a match. */
+    replace: string;
+    /** What the reader typed. */
+    search: string;
+    /** Whether a match has to be a whole word. */
+    wholeWord: boolean;
+}
+/** Where a search stands: how many matches, and which is current, counting from 0, or -1 for none. */
+export interface FindResult {
+    count: number;
+    index: number;
+}
+/**
+ * Which match a search makes current. `first` stays on the current match
+ * where it still matches, as while the reader types, and otherwise takes the
+ * next one from there. `next` and `previous` move one match either way, and
+ * wrap around at the ends.
+ */
+export type FindDirection = 'first' | 'next' | 'previous';
+/**
+ * Whatever searches content for Find: the text finder Find makes for the
+ * content `for` names, or one a frame or a page attaches, as Terminal's
+ * emulator and Code Editor's engine are.
+ */
+export interface Finder {
+    /** Takes away the marks a search drew, as Find closes or its field empties. */
+    end(): void;
+    /**
+     * Finds `query`, marks every match, and makes one current by `direction`.
+     * Returns where the search stands, or `undefined` from a finder that reports
+     * it later through the sink `attach` returned, as one that searches in a
+     * worker does.
+     */
+    find(query: FindQuery, direction: FindDirection): FindResult | undefined;
+    /**
+     * Replaces the current match, or every match with `all`, and returns where
+     * the search stands after. Find offers replacing only to a finder that has
+     * this.
+     */
+    replace?(query: FindQuery, all: boolean): FindResult | undefined;
+}
+/** The pattern a query reads as, or nothing for an empty search or a regular expression that cannot be read. */
+export declare const findPattern: (query: FindQuery) => RegExp | undefined;
+/** Where a query matches in a text, as `[from, to]` offsets, with no empty match. */
+export declare const findRanges: (text: string, query: FindQuery) => Array<[number, number]>;
+/**
+ * Every place the text under `root` matches `query`, as ranges in the order
+ * they come. A match may run across the elements inside one block, as
+ * "**bold** words" does, and never from one block into the next.
+ */
+export declare const findTextRanges: (root: Element, query: FindQuery, skip?: string) => Range[];
+/** What `textFinder` takes beside its root. */
+export interface TextFinderOptions {
+    /**
+     * Called with where the search stands once the content has changed under
+     * it, as a log that keeps writing does. A search that `find` returned is
+     * not reported again here.
+     */
+    found?: ((result: FindResult) => void) | undefined;
+    /**
+     * Elements under the root whose text is not searched, as a selector, such
+     * as line numbers or the buttons beside each message.
+     */
+    skip?: string | undefined;
+}
+/**
+ * A finder over the text a reader sees under `root`, in its light DOM and
+ * what is slotted there: Find's own, for the content its `for` names.
+ *
+ * Every match is painted as `helix-find-match`, and the current one as
+ * `helix-find-current`, by the Custom Highlight API. The first search starts
+ * at the first match in sight. The current match is scrolled into the middle
+ * of its scroller unless it is already in sight, and what hides it until found
+ * is opened first. While a search is open, a change to the content searches
+ * again once it has been still for 150ms, staying on the current match, and
+ * reports through `found`.
+ *
+ * Nothing is painted where the API is missing, as on a server or in a test
+ * DOM, and the count is still right there.
+ */
+export declare const textFinder: (root: Element, options?: TextFinderOptions) => Finder;

package/dist/utils/find-text/find-text.js

@@ -0,0 +1,330 @@
+export const FIND_MATCH = 'helix-find-match';
+export const FIND_CURRENT = 'helix-find-current';
+export const findPattern = (query) => {
+    if (query.search === '') {
+        return undefined;
+    }
+    const source = query.regex ? query.search : query.search.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    try {
+        return new RegExp(query.wholeWord ? `\\b(?:${source})\\b` : source, query.caseSensitive ? 'gu' : 'giu');
+    }
+    catch {
+        return undefined;
+    }
+};
+export const findRanges = (text, query) => {
+    const pattern = findPattern(query);
+    if (!pattern) {
+        return [];
+    }
+    return [...text.matchAll(pattern)]
+        .filter((match) => match[0] !== '')
+        .map((match) => [match.index, match.index + match[0].length]);
+};
+const NEVER = 'script, style, template, noscript, textarea, select, [inert], [aria-hidden="true"], [hidden]:not([hidden="until-found"])';
+const BETWEEN = '\u0000';
+const flatParent = (node) => {
+    const slot = node.assignedSlot;
+    if (slot) {
+        return slot;
+    }
+    const parent = node.parentNode;
+    if (parent?.nodeType === Node.ELEMENT_NODE) {
+        return parent;
+    }
+    return parent !== null && 'host' in parent ? parent.host : null;
+};
+const revealers = (node) => {
+    const found = [];
+    let below = node;
+    for (let element = flatParent(node); element !== null; element = flatParent(element)) {
+        const closed = element.localName === 'details' &&
+            !element.open &&
+            !(below instanceof Element && below.localName === 'summary');
+        if (closed || element.getAttribute('hidden') === 'until-found') {
+            found.unshift(element);
+        }
+        below = element;
+    }
+    return found;
+};
+const seen = (element) => {
+    if (typeof element.checkVisibility !== 'function') {
+        for (let at = element; at !== null; at = flatParent(at)) {
+            const hidden = at.getAttribute('hidden');
+            if (hidden !== null && hidden !== 'until-found') {
+                return false;
+            }
+        }
+        return true;
+    }
+    if (element.checkVisibility({ visibilityProperty: true })) {
+        return true;
+    }
+    const outer = revealers(element)[0];
+    return (outer && flatParent(outer)?.checkVisibility({ visibilityProperty: true })) ?? false;
+};
+const INLINE = /^(?:inline|contents|ruby|$)/;
+const blockOf = (text, root, inline) => {
+    const view = root.ownerDocument.defaultView;
+    for (let element = text.parentElement; element !== null && element !== root; element = element.parentElement) {
+        let flows = inline.get(element);
+        if (flows === undefined) {
+            flows = view ? INLINE.test(view.getComputedStyle(element).display) : false;
+            inline.set(element, flows);
+        }
+        if (!flows) {
+            return element;
+        }
+    }
+    return root;
+};
+const textsOf = (root, skip) => {
+    const nodes = [];
+    let joined = '';
+    if (root.closest(NEVER)) {
+        return { joined, nodes };
+    }
+    const never = skip === '' ? NEVER : `${NEVER}, ${skip}`;
+    const shown = new Map();
+    const inline = new Map();
+    const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_ELEMENT | NodeFilter.SHOW_TEXT, {
+        acceptNode: (node) => {
+            if (node.nodeType === Node.ELEMENT_NODE) {
+                const element = node;
+                if (element.matches(never)) {
+                    return NodeFilter.FILTER_REJECT;
+                }
+                return element.localName === 'br' ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_SKIP;
+            }
+            const parent = node.parentElement;
+            if (parent === null || node.nodeValue === '') {
+                return NodeFilter.FILTER_REJECT;
+            }
+            let visible = shown.get(parent);
+            if (visible === undefined) {
+                visible = seen(parent);
+                shown.set(parent, visible);
+            }
+            return visible ? NodeFilter.FILTER_ACCEPT : NodeFilter.FILTER_REJECT;
+        },
+    });
+    let block;
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        if (node.nodeType === Node.ELEMENT_NODE) {
+            joined += BETWEEN;
+            continue;
+        }
+        const text = node;
+        const here = blockOf(text, root, inline);
+        if (block !== undefined && here !== block) {
+            joined += BETWEEN;
+        }
+        block = here;
+        nodes.push([text, joined.length]);
+        joined += text.data;
+    }
+    return { joined, nodes };
+};
+const placed = (nodes, at, end) => {
+    let low = 0;
+    let high = nodes.length - 1;
+    while (low < high) {
+        const middle = Math.ceil((low + high) / 2);
+        const from = nodes[middle]?.[1] ?? 0;
+        if (from < at || (!end && from === at)) {
+            low = middle;
+        }
+        else {
+            high = middle - 1;
+        }
+    }
+    const [node, from] = nodes[low];
+    return [node, at - from];
+};
+export const findTextRanges = (root, query, skip = '') => {
+    if (findPattern(query) === undefined) {
+        return [];
+    }
+    const { joined, nodes } = textsOf(root, skip);
+    return findRanges(joined, query)
+        .filter(([from, to]) => !joined.slice(from, to).includes(BETWEEN))
+        .map(([from, to]) => {
+        const range = root.ownerDocument.createRange();
+        range.setStart(...placed(nodes, from, false));
+        range.setEnd(...placed(nodes, to, true));
+        return range;
+    });
+};
+const painted = new Map();
+const paint = (owner, ranges, current) => {
+    const registry = globalThis.CSS?.highlights;
+    if (registry === undefined) {
+        return;
+    }
+    if (ranges.length === 0) {
+        painted.delete(owner);
+    }
+    else {
+        painted.set(owner, { current, others: ranges.filter((range) => range !== current) });
+    }
+    const entries = [...painted.values()];
+    const layers = [
+        [FIND_MATCH, entries.flatMap((entry) => entry.others), 0],
+        [FIND_CURRENT, entries.flatMap((entry) => (entry.current ? [entry.current] : [])), 1],
+    ];
+    for (const [name, ranges, priority] of layers) {
+        if (ranges.length === 0) {
+            registry.delete(name);
+        }
+        else {
+            const highlight = new Highlight(...ranges);
+            highlight.priority = priority;
+            registry.set(name, highlight);
+        }
+    }
+};
+const against = (range, anchor) => {
+    try {
+        return range.compareBoundaryPoints(Range.START_TO_START, anchor);
+    }
+    catch {
+        return 1;
+    }
+};
+const firstInView = (ranges, root) => {
+    const top = Math.max(0, root.getBoundingClientRect().top);
+    const at = ranges.findIndex((range) => typeof range.getBoundingClientRect === 'function' &&
+        range.getBoundingClientRect().bottom > top);
+    return Math.max(at, 0);
+};
+const pick = (ranges, anchor, direction, root) => {
+    if (ranges.length === 0) {
+        return -1;
+    }
+    if (anchor === undefined) {
+        const first = firstInView(ranges, root);
+        return direction === 'previous' ? (first - 1 + ranges.length) % ranges.length : first;
+    }
+    const index = direction === 'previous'
+        ? ranges.findLastIndex((range) => against(range, anchor) < 0)
+        : ranges.findIndex((range) => direction === 'next' ? against(range, anchor) > 0 : against(range, anchor) >= 0);
+    if (index !== -1) {
+        return index;
+    }
+    return direction === 'previous' ? ranges.length - 1 : 0;
+};
+const scrollerOf = (element) => {
+    const view = element.ownerDocument.defaultView;
+    for (let at = flatParent(element); at !== null; at = flatParent(at)) {
+        if (at === element.ownerDocument.documentElement || at === element.ownerDocument.body) {
+            return null;
+        }
+        const overflow = view?.getComputedStyle(at).overflowY ?? '';
+        if (/auto|scroll/.test(overflow) && at.scrollHeight > at.clientHeight) {
+            return at;
+        }
+    }
+    return null;
+};
+const bringIntoView = (range) => {
+    const element = range.startContainer.parentElement;
+    if (element === null || typeof range.getBoundingClientRect !== 'function') {
+        return;
+    }
+    const scroller = scrollerOf(element);
+    const box = scroller?.getBoundingClientRect() ?? {
+        bottom: innerHeight,
+        left: 0,
+        right: innerWidth,
+        top: 0,
+    };
+    const rect = range.getBoundingClientRect();
+    if (rect.top >= box.top &&
+        rect.bottom <= box.bottom &&
+        rect.left >= box.left &&
+        rect.right <= box.right) {
+        return;
+    }
+    element.scrollIntoView?.({ behavior: 'instant', block: 'center', inline: 'nearest' });
+    const after = range.getBoundingClientRect();
+    if (scroller && (after.top < box.top || after.bottom > box.bottom)) {
+        scroller.scrollTop += after.top + after.height / 2 - (box.top + (box.bottom - box.top) / 2);
+    }
+};
+const reveal = (range) => {
+    const hiding = revealers(range.startContainer);
+    for (const element of hiding) {
+        if (element.localName === 'details') {
+            ;
+            element.open = true;
+        }
+        else {
+            element.dispatchEvent(new Event('beforematch', { bubbles: true }));
+            if (element.getAttribute('hidden') === 'until-found') {
+                element.removeAttribute('hidden');
+            }
+        }
+    }
+    return hiding.length > 0;
+};
+const SETTLE = 150;
+export const textFinder = (root, options = {}) => {
+    const owner = {};
+    let ranges = [];
+    let current;
+    let query;
+    let observer;
+    let settling;
+    const search = (direction, show) => {
+        ranges = query ? findTextRanges(root, query, options.skip ?? '') : [];
+        const index = pick(ranges, current, direction, root);
+        current = ranges[index];
+        paint(owner, ranges, current);
+        const shown = current;
+        if (shown && show) {
+            if (reveal(shown)) {
+                setTimeout(() => bringIntoView(shown));
+            }
+            else {
+                bringIntoView(shown);
+            }
+        }
+        return { count: ranges.length, index };
+    };
+    const watch = () => {
+        if (observer !== undefined || typeof MutationObserver === 'undefined') {
+            return;
+        }
+        observer = new MutationObserver(() => {
+            clearTimeout(settling);
+            settling = setTimeout(() => {
+                if (query) {
+                    options.found?.(search('first', false));
+                }
+            }, SETTLE);
+        });
+        observer.observe(root, {
+            attributeFilter: ['aria-hidden', 'hidden', 'inert'],
+            characterData: true,
+            childList: true,
+            subtree: true,
+        });
+    };
+    return {
+        end() {
+            observer?.disconnect();
+            observer = undefined;
+            clearTimeout(settling);
+            query = undefined;
+            ranges = [];
+            current = undefined;
+            paint(owner, ranges, current);
+        },
+        find(next, direction) {
+            query = next;
+            watch();
+            return search(direction, true);
+        },
+    };
+};

package/dist/utils/toolbar-around/toolbar-around.d.ts

@@ -8,7 +8,8 @@
  * import Toolbar's class; Toolbar adds its own class for a third tag.
  *
  * `closest` stops at a shadow root, which is what a slotted child wants: its
- * toolbar is its light-DOM parent or above.
+ * toolbar is its light-DOM parent or above. It also stops at a panel, so a row
+ * in a menu opened from a toolbar is in no toolbar.
  */
 export declare const toolbarAround: (element: Element) => Element | null;
 /**

package/dist/utils/toolbar-around/toolbar-around.js

@@ -1,5 +1,24 @@
 const TOOLBAR = '[role="toolbar"], helix-toolbar, helix-headless-toolbar';
-export const toolbarAround = (element) => element.parentElement?.closest(TOOLBAR) ?? null;
+const PANEL = [
+    'helix-dialog',
+    'helix-drawer',
+    'helix-headless-dialog',
+    'helix-headless-drawer',
+    'helix-headless-megamenu',
+    'helix-headless-menu',
+    'helix-headless-popover',
+    'helix-megamenu',
+    'helix-menu',
+    'helix-popover',
+    '[popover]',
+    '[role="dialog"]',
+    '[role="menu"]',
+    'dialog',
+].join(', ');
+export const toolbarAround = (element) => {
+    const found = element.parentElement?.closest(`${TOOLBAR}, ${PANEL}`);
+    return found?.matches(TOOLBAR) ? found : null;
+};
 export const toolbarAxis = (toolbar) => (toolbar.getAttribute('orientation') ?? toolbar.getAttribute('aria-orientation')) === 'vertical'
     ? 'vertical'
     : 'horizontal';

package/dist/version.d.ts

@@ -6,4 +6,4 @@
  * release, so the two never disagree; a spec beside this holds them to it.
  * Nothing else in the running code knows which release it is.
  */
-export declare const VERSION = "0.218.0";
+export declare const VERSION = "0.220.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.218.0';
+export const VERSION = '0.220.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.218.0",
+  "version": "0.220.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -81,12 +81,12 @@
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.218.0",
+    "@fusion.dev/helix-icons": "0.220.0",
     "tslib": "^2.8.1"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.218.0",
-    "@fusion.dev/helix-testing": "0.218.0",
+    "@fusion.dev/helix-cem": "0.220.0",
+    "@fusion.dev/helix-testing": "0.220.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },