@fusion.dev/helix-core 0.145.0 → 0.147.0

package/dist/utils/row-order/row-order.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Filter, sort, then window. In that order, over the whole set, every time.
+ *
+ * **This is the file that stops the classic virtualization bug.** Sorting the
+ * rendered window looks completely correct on the first screen and is wrong
+ * everywhere else, and it is the natural thing to write once rows are data and
+ * only some of them are drawn. Keeping the three operations here, as functions
+ * over an array with no knowledge of what is on screen, is what makes that
+ * mistake hard to make: nothing in this module can see a window, and `window()`
+ * is the last thing applied rather than the first.
+ *
+ * The order is not a preference. Filtering after sorting sorts rows that are
+ * about to be thrown away, which is only slower; paging before either is the bug.
+ * Filter narrows, sort arranges what is left, the page is a slice of that, and
+ * the count a reader is shown is the length after filtering rather than the
+ * length of the data, or the pagination promises pages that are empty.
+ */
+/**
+ * A row, which is whatever the consumer's data is.
+ *
+ * Not `DataRow`: `@fusion.dev/helix-core` already exports one, for a cell read out of a
+ * chart series, and the headless barrel re-exports both. Two different `DataRow`s
+ * reaching a consumer through one package is an ambiguity TypeScript refuses
+ * outright.
+ */
+export type DataRow = Readonly<Record<string, unknown>>;
+/** One column's contribution, reduced to the two functions this module needs. */
+export interface Axis {
+    /** The field this axis is named by, matched against a sort spec. */
+    field: string;
+    /** The value to compare and match on, which is not always what the cell shows. */
+    order: (row: DataRow) => unknown;
+}
+/** A parsed `field:direction`. */
+export interface Sort {
+    direction: 'asc' | 'desc';
+    field: string;
+}
+/**
+ * `field:asc` and `field:desc`, and nothing else.
+ *
+ * A bare `field` parses as ascending, because that is what a URL query usually
+ * carries and refusing it would make the common case the verbose one. Anything
+ * unparseable is no sort rather than an error: this value arrives from a query
+ * string as often as from code, and a bad one should leave the table in the
+ * order the data came in rather than break the page.
+ */
+export declare const parse: (spec: string) => Sort | undefined;
+/** A `Sort` written back out, so the property and the attribute agree. */
+export declare const format: (sort: Sort | undefined) => string;
+/**
+ * What a reader gets on the next click of a sortable heading.
+ *
+ * Ascending, descending, then none. **The third state is not an omission to be
+ * tidied away**: the order rows arrived in is information the data came with,
+ * often the server's own relevance ranking, and a two-state cycle makes it
+ * unreachable once a reader has sorted once.
+ */
+export declare const cycle: (current: Sort | undefined, field: string) => Sort | undefined;
+/**
+ * Rows matching a query, across every axis.
+ *
+ * One query over all columns rather than a predicate per column, which is what a
+ * reader means by a search box above a table. Per-column predicates are a
+ * different feature and compose with this rather than replacing it.
+ *
+ * Case-insensitive and substring, on the ordering value rather than the rendered
+ * one: a cell showing a formatted date should be findable by the text a reader
+ * sees, and a cell showing an icon should be findable by the value behind it.
+ * Where those differ, `compare` on the column is what decides, which is the same
+ * function sorting uses, so search and sort cannot disagree about what a column
+ * holds.
+ */
+export declare const filter: (rows: readonly DataRow[], query: string, axes: readonly Axis[]) => DataRow[];
+/**
+ * Rows in the asked-for order, stably.
+ *
+ * **Stable, and that is load-bearing rather than tidy.** `Array.prototype.sort`
+ * is required to be stable since ES2019, so equal rows keep the order they
+ * arrived in, which means sorting by one column and then another leaves the
+ * first as the tiebreak. A reader who sorts by status and then by name expects
+ * exactly that, and an unstable sort would shuffle equal rows on every
+ * re-render, which reads as the table twitching.
+ */
+export declare const sort: (rows: readonly DataRow[], spec: Sort | undefined, axes: readonly Axis[]) => DataRow[];
+/**
+ * One page of rows, clamped.
+ *
+ * A page past the end returns the last page rather than nothing, because the
+ * usual way to be past the end is a bookmarked link after the result shrank,
+ * and an empty table is a worse answer than the last page of a smaller one. The
+ * same clamp `Pagination` already applies to what it reports.
+ */
+export declare const window_: (rows: readonly DataRow[], page: number, size: number) => DataRow[];
+/** What arranging produces: the rows in order, with no page or window taken. */
+export interface Arranged {
+    /** Rows after filtering and sorting, in the order they are to be drawn. */
+    rows: DataRow[];
+    /** Rows before filtering, which is what tells a reader a filter is on. */
+    total: number;
+}
+/**
+ * Filtering and sorting, with nothing taken off the end.
+ *
+ * **Split out of `ordered` because a window moves and this does not.** A table
+ * drawing a window on a result re-renders every time a scroll reveals a row,
+ * and deriving that render from the whole result means filtering and sorting it
+ * again each time: 23.7ms at five thousand rows, a frame budget spent three
+ * times over before a cell is drawn. A caller that keeps this between renders
+ * pays it once per change to the data rather than once per frame.
+ *
+ * The two steps stay together for the reason `ordered` gives below: sorting a
+ * page is the classic bug, and one function doing both is what makes calling
+ * them in the wrong order impossible.
+ */
+export declare const arranged: (rows: readonly DataRow[], axes: readonly Axis[], { query, spec }: {
+    query: string;
+    spec: string;
+}) => Arranged;
+/** What one pass over the data produces: the window, and the counts around it. */
+export interface Ordered {
+    /** Rows after filtering, before paging. The number a pagination must page. */
+    matched: number;
+    /** The rows to draw. */
+    rows: DataRow[];
+    /** Rows before filtering, which is what tells a reader a filter is on. */
+    total: number;
+}
+/**
+ * The whole pass, in the one order that is correct.
+ *
+ * Exported as a single function so a caller cannot get the order wrong by
+ * calling the three in the sequence that reads naturally, which is the sequence
+ * that pages before it sorts.
+ */
+export declare const ordered: (rows: readonly DataRow[], axes: readonly Axis[], { page, query, size, spec }: {
+    page: number;
+    query: string;
+    size: number;
+    spec: string;
+}) => Ordered;

package/dist/utils/row-order/row-order.js

@@ -0,0 +1,76 @@
+export const parse = (spec) => {
+    const trimmed = spec.trim();
+    if (trimmed === '') {
+        return undefined;
+    }
+    const [field = '', direction = 'asc'] = trimmed.split(':');
+    if (field === '' || (direction !== 'asc' && direction !== 'desc')) {
+        return undefined;
+    }
+    return { direction, field };
+};
+export const format = (sort) => sort ? `${sort.field}:${sort.direction}` : '';
+export const cycle = (current, field) => {
+    if (current?.field !== field) {
+        return { direction: 'asc', field };
+    }
+    return current.direction === 'asc' ? { direction: 'desc', field } : undefined;
+};
+export const filter = (rows, query, axes) => {
+    const needle = query.trim().toLocaleLowerCase();
+    if (needle === '') {
+        return [...rows];
+    }
+    return rows.filter((row) => axes.some((axis) => text(axis.order(row)).toLocaleLowerCase().includes(needle)));
+};
+export const sort = (rows, spec, axes) => {
+    const axis = spec ? axes.find((one) => one.field === spec.field) : undefined;
+    if (!spec || !axis) {
+        return [...rows];
+    }
+    const sign = spec.direction === 'asc' ? 1 : -1;
+    return [...rows].sort((left, right) => compare(axis.order(left), axis.order(right), sign));
+};
+export const window_ = (rows, page, size) => {
+    if (size <= 0) {
+        return [...rows];
+    }
+    const pages = Math.max(1, Math.ceil(rows.length / size));
+    const wanted = Math.min(pages, Math.max(1, Math.floor(page) || 1));
+    const from = (wanted - 1) * size;
+    return rows.slice(from, from + size);
+};
+const text = (value) => {
+    if (value === null || value === undefined) {
+        return '';
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    return String(value);
+};
+const compare = (left, right, sign) => {
+    const leftMissing = left === null || left === undefined || left === '';
+    const rightMissing = right === null || right === undefined || right === '';
+    if (leftMissing || rightMissing) {
+        return leftMissing && rightMissing ? 0 : leftMissing ? 1 : -1;
+    }
+    if (typeof left === 'number' && typeof right === 'number') {
+        return sign * (left - right);
+    }
+    if (typeof left === 'boolean' && typeof right === 'boolean') {
+        return sign * (Number(left) - Number(right));
+    }
+    if (left instanceof Date && right instanceof Date) {
+        return sign * (left.getTime() - right.getTime());
+    }
+    return (sign * text(left).localeCompare(text(right), undefined, { numeric: true, sensitivity: 'base' }));
+};
+export const arranged = (rows, axes, { query, spec }) => ({
+    rows: sort(filter(rows, query, axes), parse(spec), axes),
+    total: rows.length,
+});
+export const ordered = (rows, axes, { page, query, size, spec }) => {
+    const { rows: inOrder, total } = arranged(rows, axes, { query, spec });
+    return { matched: inOrder.length, rows: window_(inOrder, page, size), total };
+};

package/dist/utils/scroll-item-into-view/scroll-item-into-view.d.ts

@@ -7,4 +7,37 @@ export interface ScrollItemOptions {
     /** Whether to animate. Ignored where the reader asked for less motion. */
     smooth?: boolean;
 }
+/**
+ * The nearest ancestor that actually scrolls, crossing shadow boundaries.
+ *
+ * **Not `item.offsetParent`**, which is the nearest *positioned* ancestor and
+ * has nothing whatever to do with overflow. The two coincide often enough to
+ * look right, because a scroller frequently is positioned, and they come apart
+ * exactly where it matters: put anything `position: relative` between the item
+ * and the box that scrolls, and the util scrolls the thing in between, which
+ * does not scroll, and reports nothing.
+ *
+ * The walk crosses shadow boundaries through the host, because the item is
+ * almost always in one and `parentElement` is null at the root. Without that
+ * step, a component whose scroller is its own `[part]` would find nothing.
+ *
+ * It stops before the document. Scrolling the page is the one thing this whole
+ * util exists not to do, so finding nothing inside the component and returning
+ * null is the honest answer: the caller no-ops rather than taking the address
+ * bar with it.
+ */
+export declare const scrollingAncestor: (item: HTMLElement, options?: ScrollerOptions) => HTMLElement | null;
+/** Where `scrollingAncestor` looks, and what it takes for a scroller. */
+export interface ScrollerOptions {
+    /** The axis whose overflow counts, or either where absent. */
+    readonly axis?: 'x' | 'y';
+    /**
+     * Only a box whose content is larger than it, along `axis`: one that can
+     * scroll now, rather than one that would once it fills. Outline asks this of
+     * the box its links and its sections scroll in.
+     */
+    readonly overflowing?: boolean;
+    /** Where the walk stops, unread: the document's body where absent. */
+    readonly stop?: Element | null;
+}
 export declare const scrollItemIntoView: (item: HTMLElement, options?: ScrollItemOptions) => void;

package/dist/utils/scroll-item-into-view/scroll-item-into-view.js

@@ -1,15 +1,25 @@
-const scrollingAncestor = (item) => {
-    const stop = item.ownerDocument.body;
+export const scrollingAncestor = (item, options = {}) => {
+    const { axis, overflowing = false, stop = item.ownerDocument.body } = options;
     let node = climb(item);
     while (node && node !== stop) {
         const style = getComputedStyle(node);
-        if (/\b(auto|scroll|overlay)\b/.test(`${style.overflowX} ${style.overflowY}`)) {
+        const overflow = axis === 'x'
+            ? style.overflowX
+            : axis === 'y'
+                ? style.overflowY
+                : `${style.overflowX} ${style.overflowY}`;
+        if (/\b(auto|scroll|overlay)\b/.test(overflow) && (!overflowing || overflows(node, axis))) {
             return node;
         }
         node = climb(node);
     }
     return null;
 };
+const overflows = (node, axis) => {
+    const tall = node.scrollHeight > node.clientHeight;
+    const wide = node.scrollWidth > node.clientWidth;
+    return axis === 'x' ? wide : axis === 'y' ? tall : tall || wide;
+};
 const climb = (node) => {
     if (node.parentElement) {
         return node.parentElement;

package/dist/utils/slotted-glyph/slotted-glyph.d.ts

@@ -0,0 +1,33 @@
+/**
+ * A glyph a consumer slots once and a component draws in many places: the
+ * marks of a rating, the remove icon on every row of a file list.
+ *
+ * A slotted element can be assigned to one slot only, so a component that
+ * draws it in several places draws copies. **One copy per place, kept**, so a
+ * render does not make them again: a drag renders on every pointer move, and
+ * handing Lit a fresh node each time swaps every copy on every frame.
+ */
+export declare class SlottedGlyph {
+    /** The copies made so far, by the place each is drawn in. */
+    private readonly copies;
+    /** The element slotted last, which every copy is made from. */
+    private source;
+    /** Whether a glyph is slotted, so the component draws copies of it. */
+    get slotted(): boolean;
+    /**
+     * Reads the slot after a `slotchange`: the first element assigned to it,
+     * through any slot it is forwarded by. The copies made of the last one go.
+     */
+    read(slot: HTMLSlotElement): void;
+    /**
+     * Takes `source` as the glyph, or none, as `read` does from a slot: the
+     * copies made of the last one go. For the first render, which reads the
+     * host's children before any `slotchange` answers.
+     */
+    take(source: Element | undefined): void;
+    /**
+     * The copy for one place, made the first time it is asked for and the same
+     * node after, or `undefined` while nothing is slotted.
+     */
+    copyFor(place: number | string): Node | undefined;
+}

package/dist/utils/slotted-glyph/slotted-glyph.js

@@ -0,0 +1,27 @@
+export class SlottedGlyph {
+    constructor() {
+        this.copies = new Map();
+    }
+    get slotted() {
+        return this.source !== undefined;
+    }
+    read(slot) {
+        this.take(slot.assignedElements({ flatten: true })[0]);
+    }
+    take(source) {
+        this.source = source;
+        this.copies.clear();
+    }
+    copyFor(place) {
+        if (!this.source) {
+            return undefined;
+        }
+        const key = String(place);
+        let copy = this.copies.get(key);
+        if (!copy) {
+            copy = this.source.cloneNode(true);
+            this.copies.set(key, copy);
+        }
+        return copy;
+    }
+}

package/dist/utils/tell-disclosure/tell-disclosure.d.ts

@@ -22,6 +22,10 @@
  * menu        nothing             no
  * ```
  *
+ * The popover row holds for the first render. Since then Popover writes
+ * `aria-expanded` onto a plain `<button>` trigger from the reader's first
+ * press on, after hydration, and calls this only for a Helix trigger.
+ *
  * React reports "some attributes of the server rendered HTML didn't match the
  * client properties. This won't be patched up", and the cost is not the console
  * line: it answers a mismatch by discarding the server's HTML for that subtree

package/dist/utils/tree-arrow/tree-arrow.d.ts

@@ -0,0 +1,23 @@
+/** What a tree row is, for the arrow along the line. */
+export interface TreeArrowRow {
+    /** Whether the row holds rows of its own. */
+    branch: boolean;
+    /** Whether a disabled branch, which neither opens nor shuts. */
+    disabled?: boolean;
+    /** Whether the branch is open. */
+    open: boolean;
+}
+/** What the arrow along the line does on a row. */
+export type TreeArrow = 'child' | 'close' | 'open' | 'parent';
+/**
+ * What Right or Left does on a tree row, as the APG tree view says: `along` is
+ * `1` for the key that points into a branch, where its caret points (Right on
+ * a left-to-right page), and `-1` for the other.
+ *
+ * In: a shut branch opens, and an open one moves to its first child; a leaf
+ * does nothing (`undefined`). Out: an open branch shuts, and anything else
+ * moves to its parent. A disabled branch neither opens nor shuts. Tree, Object
+ * Inspector and Data Table's tree column read their keys through this, and
+ * Data Table takes `child` and `undefined` as the next column.
+ */
+export declare const treeArrow: (row: TreeArrowRow, along: -1 | 1) => TreeArrow | undefined;

package/dist/utils/tree-arrow/tree-arrow.js

@@ -0,0 +1,9 @@
+export const treeArrow = (row, along) => {
+    if (along === 1) {
+        if (row.branch && !row.open && !row.disabled) {
+            return 'open';
+        }
+        return row.branch ? 'child' : undefined;
+    }
+    return row.branch && row.open && !row.disabled ? 'close' : 'parent';
+};

package/dist/utils/typeahead/typeahead.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Whether a press types a character, which is what typeahead reads.
+ *
+ * One character with no Control, Command or Alt held, so a shortcut such as
+ * Control+A is never taken for the letter A. Shift is allowed, because a
+ * capital is still a letter.
+ */
+export declare const typesCharacter: (event: KeyboardEvent) => boolean;
+/**
+ * Finds an item by the letters a reader types at a set, the way a native
+ * `<select>` does.
+ *
+ * Letters typed within `timeout` milliseconds of each other build one search,
+ * so typing "ca" moves to "Canada" past "Cambodia". The same letter typed again
+ * moves to the next item that starts with it, so pressing "c" three times visits
+ * the first three. A pause starts a new search.
+ *
+ * Matching ignores case and leading spaces, and searches from the reader's
+ * position, wrapping at the end. A search that matches nothing moves nothing.
+ *
+ * Holds only the letters, so one instance serves any set: the caller passes the
+ * words of the items and where the reader is on every key.
+ */
+export declare class Typeahead {
+    private letters;
+    private last;
+    private readonly timeout;
+    constructor({ timeout }?: {
+        timeout?: number;
+    });
+    /**
+     * Whether a search is under way.
+     *
+     * A set that chooses on Space asks this first, because a Space typed in the
+     * middle of a search is part of the words, as in "New York".
+     */
+    typing(now?: number): boolean;
+    /**
+     * Adds a character to the search, and returns the index of the item it
+     * matches, or `-1` where none does.
+     *
+     * `texts` are the words of the items a reader can reach, in order, and
+     * `from` is the index of the item the reader is on, or `-1`.
+     */
+    match(key: string, texts: readonly string[], from: number, now?: number): number;
+    /** Ends the search, so the next letter starts a new one. */
+    reset(): void;
+}
+/**
+ * A typeahead over a set's items: how to read an item's words, and the search
+ * that remembers the letters typed so far.
+ *
+ * What `KeyboardNavigationController` takes as its `typeahead` option. A set
+ * builds one with `typeaheadBy`, so the search's code ships only with the sets
+ * that type ahead, and Rating, Tabs or Radio, which never do, carry none of it.
+ */
+export interface TypeaheadBy<Item> {
+    /** The letters typed so far, matched against the words. */
+    readonly search: Typeahead;
+    /** The words of an item, which a reader types the start of. */
+    readonly words: (item: Item) => string;
+}
+/**
+ * Turns on typeahead for a set whose items have these words. See
+ * `TypeaheadBy`.
+ */
+export declare const typeaheadBy: <Item>(words: (item: Item) => string) => TypeaheadBy<Item>;
+/**
+ * Turns on typeahead for a set whose items carry their own `words`, as List's
+ * rows, Tag Group's tags and Drilldown's items do. An item with none is
+ * passed over.
+ */
+export declare const typeaheadByWords: () => TypeaheadBy<{
+    readonly words?: string;
+}>;

package/dist/utils/typeahead/typeahead.js

@@ -0,0 +1,37 @@
+export const typesCharacter = (event) => event.key.length === 1 && !event.ctrlKey && !event.metaKey && !event.altKey;
+export class Typeahead {
+    constructor({ timeout = 500 } = {}) {
+        this.letters = '';
+        this.last = 0;
+        this.timeout = timeout;
+    }
+    typing(now = Date.now()) {
+        return this.letters !== '' && now - this.last <= this.timeout;
+    }
+    match(key, texts, from, now = Date.now()) {
+        if (!this.typing(now)) {
+            this.letters = '';
+        }
+        this.last = now;
+        this.letters += key.toLowerCase();
+        const words = texts.map((text) => text.trim().toLowerCase());
+        const repeated = [...this.letters].every((letter) => letter === this.letters[0]);
+        const needle = repeated ? (this.letters[0] ?? '') : this.letters;
+        const start = repeated ? from + 1 : Math.max(from, 0);
+        for (let step = 0; step < words.length; step += 1) {
+            const at = (start + step) % words.length;
+            if (words[at]?.startsWith(needle)) {
+                return at;
+            }
+        }
+        return -1;
+    }
+    reset() {
+        this.letters = '';
+    }
+}
+export const typeaheadBy = (words) => ({
+    search: new Typeahead(),
+    words,
+});
+export const typeaheadByWords = () => typeaheadBy((item) => item.words ?? '');

package/dist/utils/value-as/value-as.d.ts

@@ -1,3 +1,12 @@
+/**
+ * Midnight UTC on a day, with the year as written.
+ *
+ * `Date.UTC` reads a year from 0 to 99 as 1900 to 1999, so year 1, which a
+ * native date input accepts and a year segment reaches with Home, became 1901
+ * and the date was refused. `setUTCFullYear` takes the year as given, and
+ * rolls a month or a day past its end the way `Date.UTC` does.
+ */
+export declare const utcDate: (year: number, month: number, day: number) => Date;
 /**
  * The date a `YYYY-MM-DD` value names, at midnight UTC, or `null`.
  *

package/dist/utils/value-as/value-as.js

@@ -1,13 +1,21 @@
 const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const ISO_TIME = /^(\d{2}):(\d{2})(?::(\d{2}(?:\.\d{1,3})?))?$/;
 const DAY = 86_400_000;
+export const utcDate = (year, month, day) => {
+    const date = new Date(0);
+    date.setUTCFullYear(year, month, day);
+    return date;
+};
 export const valueAsDate = (value) => {
     const parts = ISO_DATE.exec(value);
     if (!parts) {
         return null;
     }
     const [year, month, day] = [Number(parts[1]), Number(parts[2]), Number(parts[3])];
-    const date = new Date(Date.UTC(year, month - 1, day));
+    if (year < 1) {
+        return null;
+    }
+    const date = utcDate(year, month - 1, day);
     const rolled = date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day;
     return rolled ? null : date;
 };

package/dist/utils/verdict-flags/verdict-flags.d.ts

@@ -0,0 +1,13 @@
+/**
+ * What a picker field finds wrong: a message, reported as `badInput`, or the
+ * validity flag to set and its message. Empty means nothing is wrong.
+ */
+export type PickerVerdict = string | readonly [flag: keyof ValidityStateFlags, message: string];
+/**
+ * A verdict as the flags and the message `setValidity` takes, or `null` where
+ * there is nothing wrong.
+ *
+ * Shared by `MixinPickerField` and `MixinSegmentedField`, the two shapes a
+ * date, time or color field takes, which report the same verdicts.
+ */
+export declare const verdictFlags: (verdict: PickerVerdict) => [flags: ValidityStateFlags, message: string] | null;

package/dist/utils/verdict-flags/verdict-flags.js

@@ -0,0 +1,6 @@
+export const verdictFlags = (verdict) => {
+    if (typeof verdict === 'string') {
+        return verdict === '' ? null : [{ badInput: true }, verdict];
+    }
+    return [{ [verdict[0]]: true }, verdict[1]];
+};

package/dist/utils/watch-labels/watch-labels.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Calls `heard` whenever a `<label>` changes in the tree `host` is in: one is
+ * added or taken out, its `for` changes, or its words do.
+ *
+ * **For a label that arrives after the control renders**, which a framework
+ * does freely and which no attribute on the host reports: the platform adds the
+ * label to the host's `labels` and says nothing. `HelixFormElement` updates
+ * when this calls, so `AriaForwardController` names the control inside as the
+ * label appears, where it used to wait for focus.
+ *
+ * **One observer per tree, whatever the number of controls in it**, so a form
+ * of forty fields watches the page once, and a change that touches no label
+ * costs one check per record. The returned function stops the watch, and an
+ * observer whose controls have all gone stops at the next change it sees.
+ */
+export declare const watchLabels: (host: Node, heard: () => void) => (() => void);

package/dist/utils/watch-labels/watch-labels.js

@@ -0,0 +1,34 @@
+const trees = new Map();
+const touchesLabel = ({ addedNodes, removedNodes, target }) => [target, ...addedNodes, ...removedNodes].some((node) => (node instanceof Element ? node : node.parentElement)?.closest('label') != null ||
+    (node instanceof Element && node.querySelector('label') !== null));
+export const watchLabels = (host, heard) => {
+    const root = host.getRootNode();
+    let callbacks = trees.get(root);
+    if (!callbacks) {
+        const made = new Set();
+        const observer = new MutationObserver((records) => {
+            if (made.size === 0) {
+                observer.disconnect();
+                trees.delete(root);
+            }
+            else if (records.some(touchesLabel)) {
+                for (const callback of [...made]) {
+                    callback();
+                }
+            }
+        });
+        observer.observe(root, {
+            attributeFilter: ['for'],
+            characterData: true,
+            childList: true,
+            subtree: true,
+        });
+        callbacks = made;
+        trees.set(root, made);
+    }
+    callbacks.add(heard);
+    const watched = callbacks;
+    return () => {
+        watched.delete(heard);
+    };
+};

package/dist/utils/words-converter/words-converter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reads an attribute holding words keyed by name, written as a JSON object,
+ * such as Orb's `state-labels`, Sandbox Terminal's `level-words` or Color
+ * Picker's `color-words`. A property declares it as its `converter`.
+ *
+ * **Anything else is no words, never `null`.** JSON that does not parse, an
+ * array, a string or `null` gives an empty object, and a key whose value is
+ * not a string is dropped, so every key keeps its default words. Lit's own
+ * `Object` converter answers `null` for JSON that does not parse, and a render
+ * that reads a key off it throws and draws nothing, over a typo in markup.
+ */
+export declare const wordsConverter: {
+    fromAttribute: (value: string | null) => Record<string, string>;
+};

package/dist/utils/words-converter/words-converter.js

@@ -0,0 +1,15 @@
+export const wordsConverter = {
+    fromAttribute: (value) => {
+        let parsed;
+        try {
+            parsed = JSON.parse(value ?? '');
+        }
+        catch {
+            return {};
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+            return {};
+        }
+        return Object.fromEntries(Object.entries(parsed).filter((entry) => typeof entry[1] === 'string'));
+    },
+};