@fusion.dev/helix-core 0.144.0 → 0.146.0

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/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,67 @@
+/**
+ * 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>;

package/dist/utils/typeahead/typeahead.js

@@ -0,0 +1,36 @@
+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,
+});

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/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'));
+    },
+};

package/dist/utils/write-time/write-time.d.ts

@@ -3,10 +3,10 @@
  *
  * `Intl` decides between a twelve and a twenty-four hour clock, because that is
  * a property of the locale rather than of any component: `en-US` gets `2:30 PM`
- * and `en-GB` gets `14:30` without either being configured. There is no flag to
- * force one, deliberately. A product that needs to override its reader's own
- * convention has a locale problem rather than a component one, and the value is
- * 24 hour regardless.
+ * and `en-GB` gets `14:30` without either being configured. This function takes
+ * no flag to force one. A family that offers the choice, such as Time Picker
+ * and Time Input with `hour-cycle`, passes it in the locale, as its `-u-hc-`
+ * extension (`en-US-u-hc-h23`). The value is 24 hour regardless.
  *
  * A value this cannot read is handed back unchanged, so a field showing what is
  * being typed shows the letters rather than blanking under the reader. Minute

package/dist/utils/written-list/written-list.d.ts

@@ -61,3 +61,32 @@ export declare const commaList: (value: string) => string[];
  * holds, so a set of pressed items reads the same whichever was pressed first.
  */
 export declare const toggleValue: (list: readonly string[], value: string, order?: readonly string[]) => string[];
+/**
+ * `chosen` with every one of `values` added, or with every one taken out
+ * where each was already in it: a select-all box, or a branch of a checkbox
+ * tree pressed. `values` empty changes nothing.
+ *
+ * With `order`, the result is put in that order and holds only what `order`
+ * holds. Without it, what was chosen keeps its place and what is added
+ * follows.
+ */
+export declare const toggleEvery: (chosen: Iterable<string>, values: readonly string[], order?: readonly string[]) => string[];
+/** How many items a set lets a reader select: Tag Group's and List's `selection-mode`. */
+export type SelectionMode = 'multiple' | 'none' | 'single';
+/**
+ * The comma-separated `value` a press on the item carrying `pressed` leaves.
+ *
+ * `single` selects that item alone, or none where it was the one selected.
+ * `multiple` adds it, or takes it out. `none` selects nothing and leaves the
+ * value as it was. Tag Group and List answer the same question for their
+ * tags and rows.
+ */
+export declare const pressedValue: (mode: SelectionMode, value: string, pressed: string) => string;
+/**
+ * The comma-separated `value` once an item carrying `removed` has left, where
+ * `left` is what the items still there stand for.
+ *
+ * Taken out only where no item left still stands for it, so two items with
+ * one value keep it while either remains. The rest is written back as it was.
+ */
+export declare const prunedValue: (value: string, removed: string, left: readonly string[]) => string;

package/dist/utils/written-list/written-list.js

@@ -12,3 +12,33 @@ export const toggleValue = (list, value, order) => {
     const next = list.includes(value) ? list.filter((one) => one !== value) : [...list, value];
     return order ? order.filter((one) => next.includes(one)) : next;
 };
+export const toggleEvery = (chosen, values, order) => {
+    const next = new Set(chosen);
+    const every = values.length > 0 && values.every((value) => next.has(value));
+    for (const value of values) {
+        if (every) {
+            next.delete(value);
+        }
+        else {
+            next.add(value);
+        }
+    }
+    return order ? order.filter((value) => next.has(value)) : [...next];
+};
+export const pressedValue = (mode, value, pressed) => {
+    const now = commaList(value);
+    if (mode === 'single') {
+        return now.includes(pressed) ? '' : pressed;
+    }
+    if (mode === 'multiple') {
+        return toggleValue(now, pressed).join(', ');
+    }
+    return value;
+};
+export const prunedValue = (value, removed, left) => {
+    const now = commaList(value);
+    if (!now.includes(removed) || left.includes(removed)) {
+        return value;
+    }
+    return now.filter((one) => one !== removed).join(', ');
+};

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.144.0";
+export declare const VERSION = "0.146.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.144.0';
+export const VERSION = '0.146.0';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-core",
   "description": "Helix element primitives: base classes, mixins, decorators, utilities.",
-  "version": "0.144.0",
+  "version": "0.146.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -28,21 +28,34 @@
   "scripts": {
     "analyze": "bun --bun helix-cem",
     "build": "tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
-    "test": "bun test src",
+    "test": "bun test src --conditions helix-source --conditions helix-development",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
     "@floating-ui/dom": "^1.8.0",
-    "@fusion.dev/helix-icons": "0.144.0"
+    "@fusion.dev/helix-icons": "0.146.0"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.144.0",
-    "@fusion.dev/helix-testing": "0.144.0",
+    "@fusion.dev/helix-cem": "0.146.0",
+    "@fusion.dev/helix-testing": "0.146.0",
     "@lit-labs/ssr": "^4.1.0",
     "lit": "^3.2.1"
   },
   "homepage": "https://fusion.dev",
+  "imports": {
+    "#audit-name": {
+      "helix-source": {
+        "development": "./src/utils/audit-name/audit-name.ts",
+        "helix-development": "./src/utils/audit-name/audit-name.ts",
+        "default": "./src/utils/audit-name/audit-name-off.ts"
+      },
+      "types": "./dist/utils/audit-name/audit-name.d.ts",
+      "development": "./dist/utils/audit-name/audit-name.js",
+      "helix-development": "./dist/utils/audit-name/audit-name.js",
+      "default": "./dist/utils/audit-name/audit-name-off.js"
+    }
+  },
   "keywords": [
     "web-components",
     "custom-elements",