@fusion.dev/helix-core 0.147.0 → 0.148.0

package/dist/utils/filter-marks/filter-marks.d.ts

@@ -0,0 +1,36 @@
+/** What the marks are called in `CSS.highlights`, and in `base.css`. */
+export declare const FILTER_MARK = "helix-filter-match";
+/**
+ * Where a needle sits inside an element, as a range over its text nodes, or
+ * nothing where it does not.
+ *
+ * Walked rather than measured off `textContent`, because the words may be split
+ * across several nodes and wrapped in elements of the consumer's, and a match
+ * can begin in one node and end in another. The offsets are mapped back onto
+ * the nodes they came from, so the range covers the real text either way.
+ * Matched without regard to case, as a filter matches.
+ */
+export declare const rangeOf: (root: Element, needle: string) => Range[];
+/**
+ * Marks where `needle` matches in each of `elements`, for `owner`, without
+ * touching the elements. An empty needle takes the owner's marks away, which
+ * is also what an owner leaving the page calls.
+ *
+ * **The Custom Highlight API paints a range, and nothing is inserted.** The
+ * words are usually the consumer's own light DOM, slotted through as many as
+ * two shadow roots, and wrapping the matched part in a `<mark>` would mean
+ * rewriting their content: markup they wrote would come back changed. So an
+ * option holding a link or an icon is marked as readily as one holding a bare
+ * word. Listbox marks what its filter matched this way, and so every family
+ * that filters through one: Select, Combobox, Command and Time Picker.
+ *
+ * **The rule that paints it lives in `base.css`**, as
+ * `::highlight(helix-filter-match)`, rather than in a component's styles. A
+ * highlight is styled from the tree its text lives in, and that text lives in
+ * the consumer's document.
+ *
+ * Nothing at all where the API is missing, as on a server, in a test
+ * environment or in an older browser: the text nodes are not walked for an
+ * answer nothing can paint.
+ */
+export declare const markMatches: (owner: Element, elements: Iterable<Element>, needle: string) => void;

package/dist/utils/filter-marks/filter-marks.js

@@ -0,0 +1,41 @@
+export const FILTER_MARK = 'helix-filter-match';
+const matched = new Map();
+export const rangeOf = (root, needle) => {
+    const walker = root.ownerDocument.createTreeWalker(root, NodeFilter.SHOW_TEXT);
+    const nodes = [];
+    let whole = '';
+    for (let node = walker.nextNode(); node !== null; node = walker.nextNode()) {
+        nodes.push([node, whole.length]);
+        whole += node.nodeValue;
+    }
+    const at = whole.toLowerCase().indexOf(needle.toLowerCase());
+    if (at < 0 || needle === '') {
+        return [];
+    }
+    const range = root.ownerDocument.createRange();
+    const [start, before] = nodes.findLast(([, from]) => from <= at);
+    range.setStart(start, at - before);
+    const end = at + needle.length;
+    const [last, under] = nodes.findLast(([, from]) => from < end);
+    range.setEnd(last, end - under);
+    return [range];
+};
+export const markMatches = (owner, elements, needle) => {
+    const registry = globalThis.CSS?.highlights;
+    if (registry === undefined) {
+        return;
+    }
+    if (needle === '') {
+        matched.delete(owner);
+    }
+    else {
+        matched.set(owner, [...elements].flatMap((element) => rangeOf(element, needle)));
+    }
+    const all = [...matched.values()].flat();
+    if (all.length === 0) {
+        registry.delete(FILTER_MARK);
+    }
+    else {
+        registry.set(FILTER_MARK, new Highlight(...all));
+    }
+};

package/dist/utils/focus-target/focus-target.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The element focus lands on when a trigger is focused: the trigger itself,
+ * or, for a component that delegates focus, the control inside its shadow root,
+ * followed down through any component nested there.
+ *
+ * **What a description or a name has to be written on**, since a reader hears
+ * the element that has focus: a tooltip describing a Helix button describes
+ * the `<button>` inside it, and a badge counting on an icon button counts on
+ * the same one. Read from outside through `shadowRoot`, so it works for any
+ * component with an open root and names none.
+ */
+export declare const focusTarget: (trigger: Element) => Element;

package/dist/utils/focus-target/focus-target.js

@@ -0,0 +1,9 @@
+const CONTROL = 'a[href], button, input, select, textarea, [contenteditable], [tabindex]:not([tabindex="-1"])';
+export const focusTarget = (trigger) => {
+    const root = trigger.shadowRoot;
+    if (!root?.delegatesFocus) {
+        return trigger;
+    }
+    const inner = root.querySelector(CONTROL);
+    return inner ? focusTarget(inner) : trigger;
+};

package/dist/utils/focusable-elements/focusable-elements.d.ts

@@ -1,3 +1,20 @@
+/**
+ * What takes a press of its own inside a row or an item that is pressable as a
+ * whole: a link, a control, a label, a disclosure's summary, or anything a page
+ * gave a `tabindex`.
+ */
+export declare const PRESSABLE = "a[href], button, input, label, select, summary, textarea, [tabindex]";
+/**
+ * Whether a press landed on a control of the item's own, before `boundary` in
+ * its path, so the item leaves the press to that control.
+ *
+ * **The composed path, so a control inside a component counts**: the `<button>`
+ * in a slotted Helix button's shadow root is on the path and matches, where the
+ * event's retargeted `target` is only the host. The boundary itself and
+ * everything past it is not asked, so a row that is a `[tabindex]` stop does
+ * not count as its own control.
+ */
+export declare const pressedOwnControl: (event: Event, boundary: EventTarget, pressable?: string) => boolean;
 /**
  * Everything inside `root` the reader can reach with Tab, in document order.
  *

package/dist/utils/focusable-elements/focusable-elements.js

@@ -7,6 +7,14 @@ const NATIVE_FOCUSABLE = [
     '[contenteditable]:not([contenteditable="false"])',
     '[tabindex]:not([tabindex="-1"])',
 ].join(',');
+export const PRESSABLE = 'a[href], button, input, label, select, summary, textarea, [tabindex]';
+export const pressedOwnControl = (event, boundary, pressable = PRESSABLE) => {
+    const path = event.composedPath();
+    const end = path.indexOf(boundary);
+    return path
+        .slice(0, end < 0 ? 0 : end)
+        .some((node) => node instanceof Element && node.matches(pressable));
+};
 export const focusableElements = (root) => [...root.querySelectorAll('*')].filter((node) => (node.matches(NATIVE_FOCUSABLE) || node.shadowRoot?.delegatesFocus === true) &&
     node.getClientRects().length > 0);
 export const deepActiveElement = () => {

package/dist/utils/grid-move/grid-move.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Where a key moves focus in a table read as a grid, as arithmetic over places.
+ *
+ * Pure, so a spec holds the keyboard map without a page, and in core because
+ * Table's `grid` and Data Table both read it: each finds its cells and focuses
+ * them, and this says which place a key reaches from which.
+ */
+/**
+ * A cell's place in the grid. The row of headings is row `-1`, the rows count
+ * from 0 in the order they are drawn, and a `selectable` table's checkbox
+ * column is column 0.
+ */
+export interface GridPlace {
+    column: number;
+    row: number;
+}
+/** The edges of the grid a key cannot move past. */
+export interface GridBounds {
+    /** The last row, counted as `GridPlace.row` counts. */
+    last: number;
+    /** The first row: `-1` where there is a row of headings, and `0` where there is not. */
+    top: number;
+    /** How many columns the grid has. */
+    width: number;
+}
+/** What a key reads besides itself. */
+export interface GridKeys {
+    /** Whether Control or Command was held, which takes Home and End to the corners. */
+    control: boolean;
+    /** How many rows Page Up and Page Down move. */
+    page: number;
+    /**
+     * Which way a horizontal arrow moves along the line: `1` forward, `-1` back,
+     * as core `inlineStep` answers, so a right-to-left page is already flipped.
+     */
+    step: -1 | 0 | 1;
+}
+/**
+ * The place a key reaches from `from`, or `undefined` for a key that does not
+ * move focus. A key at an edge answers the place it is on, so the caller still
+ * takes the key.
+ *
+ * | Key | Place |
+ * |---|---|
+ * | Up, Down | One row, the headings included. |
+ * | Left, Right | One column along the line, as `step` says. |
+ * | Home, End | The first or the last column of the row. |
+ * | Control with Home or End | The first column of the first row, or the last of the last. |
+ * | Page Up, Page Down | `page` rows. |
+ */
+export declare const gridMove: (key: string, from: GridPlace, bounds: GridBounds, keys: GridKeys) => GridPlace | undefined;
+/**
+ * How many rows Page Up and Page Down move: the rows of `tall` pixels that fit
+ * in `room`, less one, so the row focus left stays in view. At least one.
+ */
+export declare const pageRows: (room: number, tall: number) => number;

package/dist/utils/grid-move/grid-move.js

@@ -0,0 +1,28 @@
+const within = (value, low, high) => Math.max(low, Math.min(high, value));
+export const gridMove = (key, from, bounds, keys) => {
+    const { last, top, width } = bounds;
+    const edge = Math.max(0, width - 1);
+    const row = (to) => ({ column: from.column, row: within(to, top, last) });
+    switch (key) {
+        case 'ArrowUp':
+            return row(from.row - 1);
+        case 'ArrowDown':
+            return row(from.row + 1);
+        case 'ArrowLeft':
+        case 'ArrowRight':
+            return keys.step === 0
+                ? undefined
+                : { column: within(from.column + keys.step, 0, edge), row: from.row };
+        case 'Home':
+            return { column: 0, row: keys.control ? top : from.row };
+        case 'End':
+            return { column: edge, row: keys.control ? last : from.row };
+        case 'PageUp':
+            return row(from.row - keys.page);
+        case 'PageDown':
+            return row(from.row + keys.page);
+        default:
+            return undefined;
+    }
+};
+export const pageRows = (room, tall) => tall > 0 ? Math.max(1, Math.floor(room / tall) - 1) : 1;

package/dist/utils/number-format/number-format.d.ts

@@ -9,6 +9,13 @@
  */
 /** Writes a number in a locale with `Intl.NumberFormat` options. */
 export declare const formatNumber: (value: number, locale?: string, options?: Intl.NumberFormatOptions) => string;
+/**
+ * A share, from 0 to 1, as a locale writes a whole percentage: `40%`, or
+ * `40 %` in French. For `aria-valuetext`, since a bare `aria-valuenow` is read
+ * as a number with no unit. Splitter's position and Meter's and Progress's
+ * readings are written with it.
+ */
+export declare const formatPercent: (share: number, locale?: string) => string;
 /**
  * A reading in words: `value` written with `options` where they say another
  * style, and otherwise `share`, from 0 to 1, as a percentage, whole unless

package/dist/utils/number-format/number-format.js

@@ -10,6 +10,7 @@ const formatter = (locale, options) => {
 };
 export const formatNumber = (value, locale = '', options) => formatter(locale, options).format(value);
 const WHOLE_PERCENT = { maximumFractionDigits: 0, style: 'percent' };
+export const formatPercent = (share, locale = '') => formatNumber(share, locale, WHOLE_PERCENT);
 export const readingText = (value, share, locale = '', options) => options && options.style !== 'percent'
     ? formatNumber(value, locale, options)
     : formatNumber(share, locale, options ?? WHOLE_PERCENT);

package/dist/utils/report-runtime/report-runtime.d.ts

@@ -18,8 +18,10 @@
  */
 /** What went wrong, stable across versions, so it can be counted. */
 export type RuntimeKind = 
+/** A Blockquote's `cite` holds words, where it takes the source's URL. */
+'cite-not-url'
 /** A deprecated property, attribute or slot was used; the message names what replaces it. */
-'deprecated'
+ | 'deprecated'
 /** Another class asked for a tag that is already registered: two copies of Helix. */
  | 'duplicate-registration'
 /** The browser refused fullscreen, usually for a frame without the permission. */
@@ -79,8 +81,12 @@ export type RuntimeKind =
  | 'unlinked-trigger'
 /** A Text is rendered as a label, a deprecated value whose shadow root reaches no control. */
  | 'unreachable-label'
+/** A QR code holds a logo at a correction level below `H`, so it may not scan. */
+ | 'unscannable-logo'
 /** A virtualized list's box has no height of its own, so its window never settles. */
  | 'unsettled-window'
+/** A native button in a Button Group with `selection-mode`, which cannot be told it is pressed. */
+ | 'untold-toggle'
 /** A slotted trigger is a plain element, which cannot be told it opens something. */
  | 'untold-trigger'
 /** A tooltip wraps its trigger, so its text reaches no screen reader. */

package/dist/utils/report-values/report-values.d.ts

@@ -9,13 +9,25 @@
  * sent the first and Date Picker the second, so what a server received for the
  * same answer depended on which control asked for it.
  *
- * **The joined string is the state**, which is what the browser hands back to
- * `formStateRestoreCallback` and what `value` holds, so a restored control
- * reads the shape it wrote.
+ * **The joined string is the state by default**, which is what the browser
+ * hands back to `formStateRestoreCallback` and what `value` holds, so a
+ * restored control reads the shape it wrote. A control whose answers can hold
+ * a comma asks for `state: 'entries'`, and the browser hands back the form
+ * data itself, one entry per answer, so `b,1` comes back as one answer and not
+ * two.
  *
  * **Nothing without a `name`.** A plain string is skipped by the form when its
  * control has no name, but `FormData` carries its own names and its entries
  * are appended whatever the element is called, so an unnamed control would
  * submit empty-named values.
  */
-export declare const reportValues: (internals: ElementInternals, name: string, values: readonly string[]) => void;
+/** How `reportValues` saves the state the browser restores. */
+export interface ReportValuesOptions {
+    /**
+     * What the browser hands back to `formStateRestoreCallback`: `joined`, the
+     * answers joined with commas, or `entries`, the form data with one entry per
+     * answer. Defaults to `joined`.
+     */
+    state?: 'entries' | 'joined';
+}
+export declare const reportValues: (internals: ElementInternals, name: string, values: readonly string[], { state }?: ReportValuesOptions) => void;

package/dist/utils/report-values/report-values.js

@@ -1,4 +1,4 @@
-export const reportValues = (internals, name, values) => {
+export const reportValues = (internals, name, values, { state = 'joined' } = {}) => {
     if (name === '' || values.length === 0) {
         internals.setFormValue(null);
         return;
@@ -7,5 +7,5 @@ export const reportValues = (internals, name, values) => {
     for (const value of values) {
         data.append(name, value);
     }
-    internals.setFormValue(data, values.join(','));
+    internals.setFormValue(data, state === 'entries' ? data : values.join(','));
 };

package/dist/utils/request-change/request-change.d.ts

@@ -35,3 +35,14 @@ export interface ChangeRequestOptions<T> {
     next: T;
 }
 export declare const requestChange: <T>({ apply, event, host, next, }: ChangeRequestOptions<T>) => boolean;
+/**
+ * Asks before a reader's press moves a value, then applies it and says so:
+ * `helix-before-change` with the value it would leave, which a listener may
+ * cancel, and `change` once it has moved.
+ *
+ * **The order every selectable set in the library keeps**, so a page reads the
+ * same pair from a list, a tag group, a heatmap or a legend: the cancelable
+ * question first, the platform's `change` after, bubbling and composed as a
+ * native control's does. Returns whether the value moved.
+ */
+export declare const requestValue: (host: EventTarget, next: string, apply: (value: string) => void) => boolean;

package/dist/utils/request-change/request-change.js

@@ -1,3 +1,4 @@
+import { HelixBeforeChangeEvent } from '../../events/before-change.js';
 export const requestChange = ({ apply, event, host, next, }) => {
     if (!host.dispatchEvent(event(next))) {
         return false;
@@ -5,3 +6,12 @@ export const requestChange = ({ apply, event, host, next, }) => {
     apply(next);
     return true;
 };
+export const requestValue = (host, next, apply) => requestChange({
+    apply: (value) => {
+        apply(value);
+        host.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
+    },
+    event: (value) => new HelixBeforeChangeEvent({ value }),
+    host,
+    next,
+});

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

@@ -27,6 +27,23 @@ export interface ScrollItemOptions {
  * bar with it.
  */
 export declare const scrollingAncestor: (item: HTMLElement, options?: ScrollerOptions) => HTMLElement | null;
+/** What `scrollRoom` takes off a box that scrolls. */
+export interface ScrollRoomOptions {
+    /**
+     * How much of the box its own content covers while it scrolls, a sticky row
+     * of headings, in pixels. Defaults to `0`.
+     */
+    covered?: number;
+}
+/**
+ * How much of a list a reader sees at once, for Page Up and Page Down: the
+ * box's own height where it scrolls, less what covers it, and the window's
+ * where it does not and the page scrolls instead.
+ *
+ * **A pixel of slack**, since a box whose content rounds to one pixel more
+ * than its height does not scroll, and was paging by the window's height.
+ */
+export declare const scrollRoom: (box: Element | null | undefined, { covered }?: ScrollRoomOptions) => number;
 /** Where `scrollingAncestor` looks, and what it takes for a scroller. */
 export interface ScrollerOptions {
     /** The axis whose overflow counts, or either where absent. */

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

@@ -15,6 +15,7 @@ export const scrollingAncestor = (item, options = {}) => {
     }
     return null;
 };
+export const scrollRoom = (box, { covered = 0 } = {}) => box && box.scrollHeight > box.clientHeight + 1 ? box.clientHeight - covered : window.innerHeight;
 const overflows = (node, axis) => {
     const tall = node.scrollHeight > node.clientHeight;
     const wide = node.scrollWidth > node.clientWidth;

package/dist/utils/slot-filled/slot-filled.d.ts

@@ -22,3 +22,11 @@
  * anything", and a slot showing its fallback does render.
  */
 export declare const slotFilled: (slot: HTMLSlotElement | null | undefined) => boolean;
+/**
+ * The slot of a name in a shadow root, or its default slot for `''`.
+ *
+ * `slot[name=""]` matches nothing, since the default slot has no `name`
+ * attribute at all, which is the one thing every hand-written lookup had to
+ * remember.
+ */
+export declare const slotNamed: (root: ParentNode | null | undefined, name: string) => HTMLSlotElement | null;

package/dist/utils/slot-filled/slot-filled.js

@@ -1 +1,2 @@
 export const slotFilled = (slot) => (slot?.assignedNodes({ flatten: true }) ?? []).some((node) => node.nodeType === Node.ELEMENT_NODE || node.textContent?.trim() !== '');
+export const slotNamed = (root, name) => root?.querySelector?.(name === '' ? 'slot:not([name])' : `slot[name="${name}"]`) ?? null;

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

@@ -0,0 +1,18 @@
+/**
+ * The toolbar an element sits in, or `null`.
+ *
+ * Read from the parent up, so a toolbar is never its own. One answer for every
+ * family that changes inside a toolbar: Toolbar becomes a group of the outer
+ * one, a multiple Toggle Group becomes a group, and Divider turns across the
+ * toolbar's axis. By tag and by role, since a family other than Toolbar cannot
+ * 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.
+ */
+export declare const toolbarAround: (element: Element) => Element | null;
+/**
+ * The axis a toolbar runs along: its own `orientation`, else the page's
+ * `aria-orientation`, else horizontal, which is the role's default.
+ */
+export declare const toolbarAxis: (toolbar: Element) => 'horizontal' | 'vertical';

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

@@ -0,0 +1,5 @@
+const TOOLBAR = '[role="toolbar"], helix-toolbar, helix-headless-toolbar';
+export const toolbarAround = (element) => element.parentElement?.closest(TOOLBAR) ?? 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.147.0";
+export declare const VERSION = "0.148.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = '0.147.0';
+export const VERSION = '0.148.0';

package/package.json

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