@fusion.dev/helix-core 0.146.0 → 0.148.0

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/host-words/host-words.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The words that name a host, for a part inside its shadow root that must
+ * carry the same name: the list a Select or a Time Picker opens.
+ *
+ * **Words rather than a reference**, because the part is inside the host's
+ * shadow root, and neither an IDREF on the page nor the host's labels reach
+ * it. Read in the order a browser names the host: its `aria-labelledby`, its
+ * `aria-label`, then `own`, the name the component draws itself (its `label`),
+ * then a `<label>` for it. Each element's words are read as a name reads
+ * them, so hidden text is left out and runs of white space are one space.
+ *
+ * Empty where nothing names the host, which leaves the fallback to the caller.
+ */
+export declare const hostWords: (host: HTMLElement & {
+    labels?: NodeList | null;
+}, own?: string) => string;

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

@@ -0,0 +1,13 @@
+import { elementById } from '../element-by-id/element-by-id.js';
+import { nameText } from '../name-text/name-text.js';
+const wordsOf = (named) => named
+    .map((one) => (one ? nameText(one).replace(/\s+/g, ' ').trim() : ''))
+    .filter(Boolean)
+    .join(' ');
+export const hostWords = (host, own = '') => {
+    const ids = (host.getAttribute('aria-labelledby') ?? '').split(/\s+/).filter(Boolean);
+    return (wordsOf(ids.map((id) => elementById(host, id))) ||
+        host.getAttribute('aria-label')?.trim() ||
+        own ||
+        wordsOf([...(host.labels ?? [])]));
+};

package/dist/utils/load-more/load-more.d.ts

@@ -0,0 +1,25 @@
+/** Where a scrolling set stands, for the question of whether to ask for more. */
+export interface EndInSight {
+    /** The length the set last asked for more at, or `-1` where it never has. */
+    askedAt: number;
+    /** The set's length now, which the answer is kept for. */
+    count: number;
+    /** How far below the bottom of the box the set goes, in pixels. */
+    remaining: number;
+    /** The box's own height, in pixels: one screen. */
+    screen: number;
+}
+/**
+ * Whether a reader has come within one screen of the end of a set, and the
+ * set has not already asked for more at this length: React Aria's
+ * `onLoadMore` rule.
+ *
+ * **Once for each length**, so a scroll that goes on asks again only after the
+ * next page arrived and the length moved. False while the box has no height or
+ * the set no items, so a list that has not been laid out asks for nothing.
+ * The caller keeps `askedAt`, setting it to `count` when this answers true.
+ *
+ * Listbox asks this of its own scroll, and `VirtualizeController.endInSight`
+ * of the rows it lays out, so the two lists ask on the same terms.
+ */
+export declare const endInSight: ({ askedAt, count, remaining, screen }: EndInSight) => boolean;

package/dist/utils/load-more/load-more.js

@@ -0,0 +1 @@
+export const endInSight = ({ askedAt, count, remaining, screen }) => count > 0 && screen > 0 && askedAt !== count && remaining <= screen;

package/dist/utils/locale-of/locale-of.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The locale an element speaks: `own`, the element's own `locale` property,
+ * where one is set, and otherwise the `lang` of the nearest element with one,
+ * read out through any shadow root the element is drawn in.
+ *
+ * **The page's language is the default a reader expects.** A date picker on a
+ * page written `lang="de"` that names its months in English and starts its
+ * weeks on Sunday is a widget that ignored the one place the page said what
+ * language it is in; Shoelace and Web Awesome read the same attribute.
+ * `lang=""` is the page saying it does not know, and answers empty.
+ *
+ * Empty where nothing says, which every `Intl` call here takes as the
+ * runtime's own locale, and empty for a bare language the runtime already
+ * speaks (see `usable`). Read when asked rather than watched, so a page that
+ * changes its `lang` is answered in the new one on the element's next render.
+ * A server shim with no `closest` answers `own`, or empty.
+ */
+export declare const localeOf: (element: Element, own?: string) => string;

package/dist/utils/locale-of/locale-of.js

@@ -0,0 +1,26 @@
+let runtime;
+const usable = (lang) => {
+    try {
+        const asked = new Intl.Locale(lang);
+        runtime ??= new Intl.Locale(new Intl.DateTimeFormat().resolvedOptions().locale);
+        return asked.region === undefined && asked.language === runtime.language ? '' : asked.toString();
+    }
+    catch {
+        return '';
+    }
+};
+export const localeOf = (element, own = '') => {
+    if (own) {
+        return own;
+    }
+    let from = element;
+    while (from && typeof from.closest === 'function') {
+        const found = from.closest('[lang]');
+        if (found) {
+            return usable(found.getAttribute('lang') ?? '');
+        }
+        const root = from.getRootNode?.();
+        from = root?.host ?? null;
+    }
+    return '';
+};

package/dist/utils/nearest/nearest.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The value in `values` nearest `target`, the first of two at the same
+ * distance, or `undefined` for none.
+ *
+ * Drawer's `snapTo` and Rating's reading of a score between its steps each
+ * wrote this loop. Given in ascending order, a target halfway between two
+ * goes to the lower, which is the rule both kept.
+ */
+export declare const nearest: (values: Iterable<number>, target: number) => number | undefined;

package/dist/utils/nearest/nearest.js

@@ -0,0 +1,9 @@
+export const nearest = (values, target) => {
+    let found;
+    for (const one of values) {
+        if (found === undefined || Math.abs(one - target) < Math.abs(found - target)) {
+            found = one;
+        }
+    }
+    return found;
+};

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

@@ -9,6 +9,22 @@
  */
 /** 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
+ * `options` say more.
+ *
+ * Meter and Progress each wrote this, with the value each holds to its range
+ * and the share of it that is filled.
+ */
+export declare const readingText: (value: number, share: number, locale?: string, options?: Intl.NumberFormatOptions) => string;
 /**
  * Reads a number written in a locale with the same options it is shown with,
  * or `null` where the text is no number.

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

@@ -9,6 +9,11 @@ const formatter = (locale, options) => {
     return found;
 };
 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);
 const grouped = (text, separator, decimal) => {
     const whole = (text.split(decimal)[0] ?? '').replace(/^[+-]/u, '');
     return new RegExp(`^\\d{1,3}(${literal(separator)}\\d{3})+$`, 'u').test(whole);

package/dist/utils/own-rule/own-rule.d.ts

@@ -0,0 +1,16 @@
+/**
+ * A page's own rule for a field's value: a message, a list of them, or `true`,
+ * `null` or nothing to accept the value. Input's and Textarea's `validate`.
+ */
+export type OwnRule = (value: string) => string | string[] | true | null | undefined;
+/**
+ * Applies a page's own rule after the native verdict was copied, as React
+ * Aria's TextField `validate` does: only while the browser finds nothing
+ * wrong, so a required empty field says the browser's sentence first. A list
+ * of messages is joined with spaces, and the message is a `customError`
+ * anchored at the control, so the bubble points at the text.
+ *
+ * A function rather than a member of `MixinField`, so only the fields that
+ * take `validate` carry it.
+ */
+export declare const applyOwnRule: (internals: ElementInternals, control: HTMLInputElement | HTMLTextAreaElement, rule: OwnRule | undefined, value: string) => void;

package/dist/utils/own-rule/own-rule.js

@@ -0,0 +1,7 @@
+export const applyOwnRule = (internals, control, rule, value) => {
+    const own = control.validity.valid ? rule?.(value) : undefined;
+    const message = Array.isArray(own) ? own.join(' ') : typeof own === 'string' ? own : '';
+    if (message !== '') {
+        internals.setValidity({ customError: true }, message, control);
+    }
+};

package/dist/utils/platform/platform.d.ts

@@ -21,3 +21,11 @@ export declare const appleTouch: (platform: Platform | undefined) => boolean;
  * `mod` as the key it names.
  */
 export declare const onApple: (platform?: Platform | undefined) => boolean;
+/**
+ * Whether the browser runs on Android, where TalkBack reads no `aria-sort`.
+ *
+ * React Aria's table header describes its sort order in words there for the
+ * same reason, so a reader who cannot hear the state still hears which way a
+ * column is sorted. From the user agent; `false` on a server.
+ */
+export declare const onAndroid: (platform?: Platform | undefined) => boolean;

package/dist/utils/platform/platform.js

@@ -9,3 +9,4 @@ export const appleTouch = (platform) => {
     return platform.platform === 'MacIntel' && (platform.maxTouchPoints ?? 0) > 1;
 };
 export const onApple = (platform = typeof navigator === 'undefined' ? undefined : navigator) => platform !== undefined && /mac|iphone|ipad|ipod/i.test(platform.userAgent ?? '');
+export const onAndroid = (platform = typeof navigator === 'undefined' ? undefined : navigator) => platform !== undefined && /android/i.test(platform.userAgent ?? '');

package/dist/utils/read-series/read-series.d.ts

@@ -136,3 +136,17 @@ export declare const readRows: (table: Element) => Row[];
  * name is written, in `lines`, `hidden-series` and `hide()` alike.
  */
 export declare const seriesKey: (name: string) => string;
+/** Where the highest and the lowest readings are, by place, or none. */
+export interface Extremes {
+    /** The place of the highest reading, the first where several tie. */
+    high?: number;
+    /** The place of the lowest reading, the first where several tie. */
+    low?: number;
+}
+/**
+ * Where the highest and the lowest readings stand. A blank slot is passed
+ * over, and a list with nothing in it has neither.
+ *
+ * Sparkline's overview and Heatmap's busiest place each looked for these.
+ */
+export declare const extremesOf: (slots: readonly (number | undefined)[]) => Extremes;

package/dist/utils/read-series/read-series.js

@@ -139,3 +139,18 @@ export const readRows = (table) => {
     return [...(element.tBodies[0]?.rows ?? [])].map((one) => row(one.cells[0], [...one.cells].slice(1), names));
 };
 export const seriesKey = (name) => name.trim().toLowerCase();
+export const extremesOf = (slots) => {
+    const found = {};
+    slots.forEach((value, at) => {
+        if (value === undefined) {
+            return;
+        }
+        if (found.high === undefined || value > slots[found.high]) {
+            found.high = at;
+        }
+        if (found.low === undefined || value < slots[found.low]) {
+            found.low = at;
+        }
+    });
+    return found;
+};

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

@@ -1,3 +1,11 @@
+/**
+ * How long each unit lasts, in milliseconds, largest last. `elapsedTime`
+ * reads its minute, hour and day from here.
+ */
+export declare const UNITS: Array<{
+    ms: number;
+    unit: Intl.RelativeTimeFormatUnit;
+}>;
 /** What one timestamp reads as, and when that stops being true. */
 export interface Relative {
     /**

package/dist/utils/relative-time/relative-time.js

@@ -1,5 +1,5 @@
 const held = new Map();
-const UNITS = [
+export const UNITS = [
     { ms: 1000, unit: 'second' },
     { ms: 60_000, unit: 'minute' },
     { ms: 3_600_000, unit: 'hour' },
@@ -25,7 +25,10 @@ export const relativeTime = (locale, options = {}) => {
         }
         const size = Math.abs(elapsed);
         if (size < 60_000) {
-            return { next: Math.max(1000, 60_000 - size), text: found.format(0, 'second') };
+            return {
+                next: Math.max(1000, 60_000 - size),
+                text: found.format(elapsed > 0 ? 0 : -0, 'second'),
+            };
         }
         let chosen = UNITS[1];
         for (const unit of UNITS) {

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

@@ -1,18 +1,6 @@
+import { callListener } from '../call-listener/call-listener.js';
 export const RENDER_SLOT = Symbol.for('fusion.dev/helix/render');
 export const measuring = () => typeof globalThis[RENDER_SLOT] === 'function';
-let told = false;
 export const reportRender = (element, start, duration) => {
-    const listener = globalThis[RENDER_SLOT];
-    if (typeof listener !== 'function') {
-        return;
-    }
-    try {
-        listener(element, { duration, start });
-    }
-    catch (error) {
-        if (!told) {
-            told = true;
-            console.error('helix: a render listener threw, and the element rendered as usual. Later failures are not printed.', error);
-        }
-    }
+    callListener(RENDER_SLOT, 'render', 'the element rendered as usual', element, { duration, start });
 };

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

@@ -18,8 +18,12 @@
  */
 /** 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'
 /** Another class asked for a tag that is already registered: two copies of Helix. */
-'duplicate-registration'
+ | 'duplicate-registration'
 /** The browser refused fullscreen, usually for a frame without the permission. */
  | 'fullscreen-refused'
 /** A rating's `min` is no score between 0 and its `max`. */
@@ -41,6 +45,8 @@ export type RuntimeKind =
  | 'missing-row-key'
 /** A stencil names parts the shape does not have. */
  | 'missing-stencil-parts'
+/** A chart, a legend or a sparkline names no table with `for`. Development builds only. */
+ | 'missing-table'
 /** A Skip Link's `href` names no element in its tree, so a press moves focus nowhere. */
  | 'missing-target'
 /** A tooltip's `for` names no element in its own tree. */
@@ -75,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-runtime/report-runtime.js

@@ -1,7 +1,7 @@
+import { callListener } from '../call-listener/call-listener.js';
 export const RUNTIME_SLOT = Symbol.for('fusion.dev/helix/runtime');
 export const RUNTIME_LOG = Symbol.for('fusion.dev/helix/runtime-log');
 const KEPT = 200;
-let told = false;
 export const reportRuntime = (event) => {
     const store = globalThis;
     const log = Array.isArray(store[RUNTIME_LOG]) ? store[RUNTIME_LOG] : [];
@@ -9,19 +9,7 @@ export const reportRuntime = (event) => {
         log.push(event);
     }
     store[RUNTIME_LOG] = log;
-    let quiet = false;
-    const listener = store[RUNTIME_SLOT];
-    if (typeof listener === 'function') {
-        try {
-            quiet = listener(event) === true;
-        }
-        catch (error) {
-            if (!told) {
-                told = true;
-                console.error('helix: a runtime listener threw, and the warning is printed here. Later failures are not printed.', error);
-            }
-        }
-    }
+    const quiet = callListener(RUNTIME_SLOT, 'runtime', 'the warning is printed here', event) === true;
     if (quiet) {
         return;
     }

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

@@ -1,4 +1,5 @@
 import { VERSION } from '../../version.js';
+import { callListener } from '../call-listener/call-listener.js';
 export const USAGE_SLOT = Symbol.for('fusion.dev/helix/usage');
 export const VERSIONS_SLOT = Symbol.for('fusion.dev/helix/versions');
 export const noteVersion = () => {
@@ -9,19 +10,6 @@ export const noteVersion = () => {
     }
     store[VERSIONS_SLOT] = listed;
 };
-let told = false;
 export const reportUsage = (element) => {
-    const listener = globalThis[USAGE_SLOT];
-    if (typeof listener !== 'function') {
-        return;
-    }
-    try {
-        listener(element);
-    }
-    catch (error) {
-        if (!told) {
-            told = true;
-            console.error('helix: a usage listener threw, and the element rendered as usual. Later failures are not printed.', error);
-        }
-    }
+    callListener(USAGE_SLOT, 'usage', 'the element rendered as usual', element);
 };

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