@fusion.dev/helix-core 0.143.0 → 0.144.0

package/dist/utils/date-segments/date-segments.js

@@ -0,0 +1,206 @@
+const SAMPLE = new Date(Date.UTC(2006, 10, 22, 15, 4, 5));
+export const segmentLayout = (kind, locale, options = {}) => {
+    const format = kind === 'date'
+        ? new Intl.DateTimeFormat(locale || undefined, {
+            day: '2-digit',
+            month: '2-digit',
+            timeZone: 'UTC',
+            year: 'numeric',
+        })
+        : new Intl.DateTimeFormat(locale || undefined, {
+            hour: '2-digit',
+            minute: '2-digit',
+            timeZone: 'UTC',
+            ...(options.seconds ? { second: '2-digit' } : {}),
+            ...(options.hourCycle ? { hourCycle: options.hourCycle } : {}),
+        });
+    const known = new Set(['day', 'dayPeriod', 'hour', 'minute', 'month', 'second', 'year']);
+    const slots = [];
+    for (const part of format.formatToParts(SAMPLE)) {
+        if (known.has(part.type)) {
+            slots.push({ kind: part.type });
+        }
+        else if (part.type === 'literal' && slots.length > 0) {
+            slots.push({ literal: part.value });
+        }
+    }
+    while (slots.length > 0 && 'literal' in slots.at(-1)) {
+        slots.pop();
+    }
+    return slots;
+};
+export const isTwelveHourLayout = (layout) => layout.some((slot) => 'kind' in slot && slot.kind === 'dayPeriod');
+const daysIn = (month, year) => month === undefined ? 31 : new Date(Date.UTC(year ?? 2000, month, 0)).getUTCDate();
+export const segmentRange = (kind, segments, twelve) => {
+    switch (kind) {
+        case 'year':
+            return { max: 9999, min: 1 };
+        case 'month':
+            return { max: 12, min: 1 };
+        case 'day':
+            return { max: daysIn(segments.month, segments.year), min: 1 };
+        case 'hour':
+            return twelve ? { max: 12, min: 1 } : { max: 23, min: 0 };
+        case 'minute':
+        case 'second':
+            return { max: 59, min: 0 };
+        case 'dayPeriod':
+            return { max: 1, min: 0 };
+    }
+};
+export const shownValue = (kind, segments, twelve) => {
+    if (kind === 'dayPeriod') {
+        return segments.hour === undefined ? segments.dayPeriod : segments.hour >= 12 ? 1 : 0;
+    }
+    const value = segments[kind];
+    if (kind === 'hour' && twelve && value !== undefined) {
+        return value % 12 === 0 ? 12 : value % 12;
+    }
+    return value;
+};
+export const setSegment = (segments, kind, shown, twelve) => {
+    const next = { ...segments };
+    if (shown === undefined) {
+        delete next[kind];
+        return next;
+    }
+    if (kind === 'hour' && twelve) {
+        const half = segments.hour !== undefined ? (segments.hour >= 12 ? 1 : 0) : (segments.dayPeriod ?? 0);
+        next.hour = (shown % 12) + half * 12;
+    }
+    else if (kind === 'dayPeriod') {
+        next.dayPeriod = shown;
+        if (next.hour !== undefined) {
+            next.hour = (next.hour % 12) + shown * 12;
+        }
+    }
+    else {
+        next[kind] = shown;
+    }
+    if (next.day !== undefined) {
+        next.day = Math.min(next.day, daysIn(next.month, next.year));
+    }
+    return next;
+};
+export const stepSegment = (segments, kind, by, twelve, thisYear = new Date().getFullYear()) => {
+    const { max, min } = segmentRange(kind, segments, twelve);
+    const shown = shownValue(kind, segments, twelve);
+    let next;
+    if (shown === undefined) {
+        next = kind === 'year' ? thisYear : by > 0 ? min : max;
+    }
+    else if (kind === 'year') {
+        next = Math.min(max, Math.max(min, shown + by));
+    }
+    else {
+        const span = max - min + 1;
+        next = ((((shown - min + by) % span) + span) % span) + min;
+    }
+    return setSegment(segments, kind, next, twelve);
+};
+export const typeDigit = (segments, kind, typed, digit, twelve) => {
+    const { max, min } = segmentRange(kind, segments, twelve);
+    let text = `${typed}${digit}`;
+    if (Number(text) > max) {
+        text = digit;
+    }
+    const value = Number(text);
+    const full = text.length >= String(max).length || value * 10 > max;
+    const next = value >= min ? setSegment(segments, kind, value, twelve) : segments;
+    return { advance: full && value >= min, segments: next, typed: full ? '' : text };
+};
+export const segmentKey = (key, { kind, locale, segments, twelve, typed }) => {
+    const done = (next) => next === undefined ? null : { advance: false, segments: next, typed: '' };
+    if (key === 'ArrowUp' || key === 'ArrowDown') {
+        return done(stepSegment(segments, kind, key === 'ArrowUp' ? 1 : -1, twelve));
+    }
+    if (key === 'Home' || key === 'End') {
+        const { max, min } = segmentRange(kind, segments, twelve);
+        return done(setSegment(segments, kind, key === 'Home' ? min : max, twelve));
+    }
+    if (key === 'Backspace' || key === 'Delete') {
+        return done(setSegment(segments, kind, undefined, twelve));
+    }
+    if (/^\d$/.test(key) && kind !== 'dayPeriod') {
+        return typeDigit(segments, kind, typed, key, twelve);
+    }
+    if (kind === 'dayPeriod' && key.length === 1) {
+        const letter = key.toLowerCase();
+        const words = [0, 1].map((half) => segmentText('dayPeriod', { dayPeriod: half }, true, locale).toLowerCase());
+        const half = words.findIndex((word) => word.startsWith(letter));
+        return done(half >= 0 ? setSegment(segments, kind, half, twelve) : undefined);
+    }
+    return null;
+};
+export const segmentsOf = (kind, value) => {
+    if (kind === 'date') {
+        const parts = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+        return parts ? { day: Number(parts[3]), month: Number(parts[2]), year: Number(parts[1]) } : {};
+    }
+    const parts = /^(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(value);
+    if (!parts) {
+        return {};
+    }
+    const hour = Number(parts[1]);
+    return {
+        dayPeriod: hour >= 12 ? 1 : 0,
+        hour,
+        minute: Number(parts[2]),
+        ...(parts[3] === undefined ? {} : { second: Number(parts[3]) }),
+    };
+};
+export const segmentsValue = (kind, segments, layout) => {
+    const shown = layout.flatMap((slot) => ('kind' in slot ? [slot.kind] : []));
+    const needed = shown.filter((one) => one !== 'dayPeriod');
+    if (needed.some((one) => segments[one] === undefined)) {
+        return '';
+    }
+    const pad = (number, width = 2) => String(number ?? 0).padStart(width, '0');
+    if (kind === 'date') {
+        return `${pad(segments.year, 4)}-${pad(segments.month)}-${pad(segments.day)}`;
+    }
+    const clock = `${pad(segments.hour)}:${pad(segments.minute)}`;
+    return shown.includes('second') ? `${clock}:${pad(segments.second)}` : clock;
+};
+export const isPartial = (kind, segments, layout) => segmentsValue(kind, segments, layout) === '' &&
+    layout.some((slot) => 'kind' in slot && slot.kind !== 'dayPeriod' && segments[slot.kind] !== undefined);
+export const segmentText = (kind, segments, twelve, locale) => {
+    const shown = shownValue(kind, segments, twelve);
+    if (kind === 'dayPeriod') {
+        const at = new Date(Date.UTC(2000, 0, 1, (shown ?? 0) === 1 ? 15 : 3));
+        const word = new Intl.DateTimeFormat(locale || undefined, {
+            hour: 'numeric',
+            hour12: true,
+            timeZone: 'UTC',
+        })
+            .formatToParts(at)
+            .find((part) => part.type === 'dayPeriod')?.value ?? (shown === 1 ? 'PM' : 'AM');
+        return shown === undefined ? '–'.repeat(word.length) : word;
+    }
+    const width = kind === 'year' ? 4 : 2;
+    if (shown === undefined) {
+        return '–'.repeat(width);
+    }
+    return kind === 'hour' && twelve ? String(shown) : String(shown).padStart(width, '0');
+};
+export const segmentValueText = (kind, segments, twelve, locale) => {
+    const text = segmentText(kind, segments, twelve, locale);
+    const month = segments.month;
+    if (kind !== 'month' || month === undefined) {
+        return text;
+    }
+    const name = new Intl.DateTimeFormat(locale || undefined, {
+        month: 'long',
+        timeZone: 'UTC',
+    }).format(new Date(Date.UTC(2000, month - 1, 1)));
+    return `${month} – ${name}`;
+};
+export const segmentName = (kind, locale) => {
+    try {
+        const names = new Intl.DisplayNames(locale || undefined, { type: 'dateTimeField' });
+        return names.of(kind === 'dayPeriod' ? 'dayPeriod' : kind) ?? kind;
+    }
+    catch {
+        return kind;
+    }
+};

package/dist/utils/draw-dismiss/draw-dismiss.d.ts

@@ -0,0 +1,30 @@
+import { type TemplateResult } from 'lit';
+/** What a dismiss button says, does and holds. */
+export interface DrawDismissOptions {
+    /** Whether the button is disabled, as a disabled tag's is. */
+    disabled?: boolean | undefined;
+    /** The button's accessible name, such as "Dismiss" or "Remove Design". */
+    label: string;
+    /**
+     * What the button holds: the `dismiss-icon` slot around `drawDismissGlyph()`,
+     * written in the component's own `protected render…()` so a tier can move it.
+     */
+    mark: unknown;
+    /** What a press does. */
+    onDismiss: () => void;
+    /** The button's `tabindex`, where it is not in the page's own order. */
+    tabindex?: string | undefined;
+}
+/**
+ * A dismiss button, `<button part="dismiss" type="button">`, named by `label`
+ * and holding `mark`.
+ *
+ * **A plain `<button>` in the shadow root, never a nested component**, so the
+ * styled tier reaches the control itself through `[part="dismiss"]`. Toast,
+ * Callout, Dialog and Tag draw it, and each documents `dismiss` and
+ * `dismiss-mark` and the `dismiss-icon` slot. The slot stays in each
+ * component's own render seam, where its fallback is a tier's to replace.
+ */
+export declare const drawDismiss: ({ disabled, label, mark, onDismiss, tabindex, }: DrawDismissOptions) => TemplateResult;
+/** The cross a dismiss button shows where nothing is slotted: `<svg part="dismiss-mark">`. */
+export declare const drawDismissGlyph: () => TemplateResult;

package/dist/utils/draw-dismiss/draw-dismiss.js

@@ -0,0 +1,16 @@
+import { x } from '@fusion.dev/helix-icons';
+import { html, nothing } from 'lit';
+import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
+export const drawDismiss = ({ disabled = false, label, mark, onDismiss, tabindex, }) => html `<button
+  part="dismiss"
+  type="button"
+  aria-label=${label}
+  ?disabled=${disabled}
+  tabindex=${tabindex ?? nothing}
+  @click=${onDismiss}
+>
+  ${mark}
+</button>`;
+export const drawDismissGlyph = () => html `<svg part="dismiss-mark" viewBox=${x.viewBox} fill="currentColor" aria-hidden="true">
+    ${unsafeSVG(x.content)}
+  </svg>`;

package/dist/utils/draw-tooltip/draw-tooltip.d.ts

@@ -1,20 +1,8 @@
 import { nothing, type TemplateResult } from 'lit';
 import { type StaticValue } from 'lit/static-html.js';
+import { CHART_PLOT, type ChartPointerController } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
 import type { Row } from '../read-series/read-series.js';
-/**
- * The id every chart puts on its plot, and the boundary a bubble is kept inside.
- *
- * **A name six templates and this file have to agree on is a name that will
- * stop agreeing**, which is `PALETTE`'s argument and it holds harder here: the
- * failure is silent. `within` resolves by id, so a plot renamed on one side
- * returns null, the boundary falls back to the viewport,
- * and the bubble goes back to hanging past the drawing with nothing reported
- * anywhere.
- *
- * Fixed rather than generated, for the reason the mark's id below gives: it is
- * scoped to one chart's shadow root, where it is the only one.
- */
-export declare const CHART_PLOT = "helix-chart-plot";
+export { CHART_PLOT };
 /** Where a tooltip points, in the plot's own percentages, and which side it prefers. */
 export interface TooltipAt {
     /**
@@ -53,6 +41,12 @@ export interface TooltipAt {
      */
     y: string;
 }
+/**
+ * What the keyboard is reading, which `drawTooltip` says aloud and marks.
+ *
+ * The chart's `pointer` is one, and is what every chart passes.
+ */
+export type ReadingCursor = Pick<ChartPointerController, 'column' | 'keyed'>;
 /**
  * What a pointer resting on a reading shows, as `Tooltip` pointed at a mark.
  *
@@ -86,11 +80,11 @@ export interface TooltipAt {
  * here, including columns nothing was plotted from, because a note beside the
  * figures is most of the reason to want a tooltip.
  *
- * **Hidden from assistive technology, on purpose.** The table is the accessible
- * representation and the drawing is `aria-hidden`; a reader on a keyboard gets
- * the table, which they can reach, rather than a tooltip which they cannot.
- * The mark and the bubble carry `aria-hidden` themselves, so they stay hidden
- * in a chart whose plot also holds something a reader should hear, such as
- * the middle of a donut.
+ * **The bubble is hidden from assistive technology, and the readout is what is
+ * heard.** The bubble carries `aria-hidden`, and so does the mark, because a
+ * bubble of figures announced on every move is noise. Given `reading`, which
+ * is the chart's `pointer`, this also renders the `live` part: a polite region
+ * that says the reading in words when a key moves it, and is empty otherwise.
+ * The cell the series keys rest on is named `tooltip-cell-current` as well.
  */
-export declare const drawTooltip: (rows: Row[], at: number, tag: StaticValue, where?: TooltipAt, slotOf?: (cell: number) => number | undefined) => TemplateResult | typeof nothing;
+export declare const drawTooltip: (rows: Row[], at: number, tag: StaticValue, where?: TooltipAt, slotOf?: (cell: number) => number | undefined, reading?: ReadingCursor) => TemplateResult | typeof nothing;

package/dist/utils/draw-tooltip/draw-tooltip.js

@@ -1,13 +1,18 @@
 import { nothing } from 'lit';
 import { styleMap } from 'lit/directives/style-map.js';
 import { html } from 'lit/static-html.js';
+import { CHART_PLOT, } from '../../controllers/chart-pointer-controller/chart-pointer-controller.js';
 import { seriesIndex } from '../../mixins/mixin-chart-source/mixin-chart-source.js';
-export const CHART_PLOT = 'helix-chart-plot';
+import { spokenReading } from './spoken-reading.js';
+export { CHART_PLOT };
 const CHART_TOOLTIP = 'helix-chart-tooltip';
-export const drawTooltip = (rows, at, tag, where, slotOf) => {
+export const drawTooltip = (rows, at, tag, where, slotOf, reading) => {
     const row = rows[at];
+    const live = reading === undefined || rows.length === 0
+        ? nothing
+        : html `<span aria-live="polite" part="live" role="status">${reading.keyed && row ? spokenReading(row, reading.column) : ''}</span>`;
     if (!row || rows.length === 0) {
-        return nothing;
+        return live;
     }
     const slot = 100 / rows.length;
     const place = where ?? {
@@ -45,7 +50,7 @@ export const drawTooltip = (rows, at, tag, where, slotOf) => {
         const series = cell.value === undefined ? undefined : answer;
         return html `<span
               data-series=${series ?? nothing}
-              part="tooltip-cell"
+              part="tooltip-cell${index === reading?.column ? ' tooltip-cell-current' : ''}"
               style=${series === undefined ? nothing : `--chart-series: var(--chart-series-${series})`}
             >
               <span part="tooltip-name">${cell.name}</span>
@@ -53,5 +58,6 @@ export const drawTooltip = (rows, at, tag, where, slotOf) => {
             </span>`;
     })}
       </div>
-    </${tag}>`;
+    </${tag}>
+    ${live}`;
 };

package/dist/utils/draw-tooltip/spoken-reading.d.ts

@@ -0,0 +1,10 @@
+import type { Row } from '../read-series/read-series.js';
+/**
+ * A reading in words, for a chart's readout: the row's name and every cell
+ * that says something, or the one cell the series keys rest on.
+ *
+ * The table's own text, as the bubble shows it, so the words and the picture
+ * agree, and nothing in it is English: the names are the table's headings. A
+ * blank cell says nothing and is left out.
+ */
+export declare const spokenReading: (row: Row, column?: number) => string;

package/dist/utils/draw-tooltip/spoken-reading.js

@@ -0,0 +1,10 @@
+export const spokenReading = (row, column) => {
+    const cell = column === undefined ? undefined : row.cells[column];
+    if (cell) {
+        return `${row.label}, ${cell.name} ${cell.text}`.trim();
+    }
+    const said = row.cells
+        .filter((one) => one.text.trim() !== '')
+        .map((one) => `${one.name} ${one.text}`.trim());
+    return said.length === 0 ? row.label : `${row.label}: ${said.join(', ')}`;
+};

package/dist/utils/follow-link/follow-link.d.ts

@@ -0,0 +1,46 @@
+/** Where a row that is a link goes, in the words an `<a>` takes them. */
+export interface LinkTarget {
+    /** Whether following the link downloads what it names. */
+    download?: boolean | undefined;
+    /** The URL. */
+    href: string;
+    /** The link's `rel`. */
+    rel?: string | undefined;
+    /** Where the link opens, such as `_blank`. */
+    target?: string | undefined;
+}
+/** The keys held as a link is followed, which say where a browser opens it. */
+export interface LinkModifiers {
+    altKey?: boolean | undefined;
+    ctrlKey?: boolean | undefined;
+    metaKey?: boolean | undefined;
+    shiftKey?: boolean | undefined;
+}
+/**
+ * Follows a link from an element that is not an `<a>`, the way the browser
+ * follows one: in this tab, in the `target` named, or in a new tab or window
+ * where Command, Control or Shift is held.
+ *
+ * **An option cannot hold an anchor.** `role="option"` sits on the option's
+ * host, where `aria-activedescendant` can name it, and an `<a>` inside the
+ * host is exposed as a link inside the option, which loses the option its name
+ * (Menu Item's `href` records the measurement). So the option stays an option
+ * and the link is followed through an anchor made for the moment, which is
+ * React Aria's way for its own link items: the browser decides what the keys
+ * mean, a new tab or a download, and nothing here guesses.
+ *
+ * The anchor is in the document only while it is clicked, and its click does
+ * not bubble, so nothing on the page hears a click on something it never drew.
+ */
+export declare const followLink: (document: Document, link: LinkTarget, modifiers?: LinkModifiers) => void;
+/**
+ * Runs `then` once a link option has been followed, for an owner whose panel
+ * closes when a choice is made: Select and Combobox close on the listbox's
+ * change, and a link changes nothing, so they hear the option's own
+ * `helix-select` instead.
+ *
+ * After every listener has had the event, so a page that cancels it, to route
+ * there itself, keeps the panel as it was, the way the option keeps the
+ * browser from following.
+ */
+export declare const afterLinkFollowed: (event: Event, then: () => void) => void;

package/dist/utils/follow-link/follow-link.js

@@ -0,0 +1,37 @@
+export const followLink = (document, link, modifiers = {}) => {
+    const anchor = document.createElement('a');
+    anchor.href = link.href;
+    if (link.target) {
+        anchor.target = link.target;
+    }
+    if (link.rel) {
+        anchor.rel = link.rel;
+    }
+    if (link.download) {
+        anchor.download = '';
+    }
+    anchor.hidden = true;
+    document.body.append(anchor);
+    try {
+        anchor.dispatchEvent(new MouseEvent('click', {
+            altKey: Boolean(modifiers.altKey),
+            cancelable: true,
+            ctrlKey: Boolean(modifiers.ctrlKey),
+            metaKey: Boolean(modifiers.metaKey),
+            shiftKey: Boolean(modifiers.shiftKey),
+        }));
+    }
+    finally {
+        anchor.remove();
+    }
+};
+export const afterLinkFollowed = (event, then) => {
+    if (event.detail?.href === undefined) {
+        return;
+    }
+    queueMicrotask(() => {
+        if (!event.defaultPrevented) {
+            then();
+        }
+    });
+};

package/dist/utils/heading-in/heading-in.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The first heading among some elements or inside them, in order, or `null`.
+ *
+ * What names a panel when nothing else does: Popover's panel and a Tour stop
+ * by the first heading in their content. An element reference rather than an
+ * id, because the heading is in the light DOM and the panel in a shadow root,
+ * which an IDREF cannot cross.
+ */
+export declare const headingIn: (elements: readonly Element[]) => Element | null;
+/**
+ * The first heading among some elements or inside them, or the elements
+ * themselves where none is a heading or holds one.
+ *
+ * What names Dialog and Drawer by their `header` slot. A header can hold a
+ * close button beside its title, and a name that read "Delete project Close"
+ * would be worse than the title alone; a header with no heading in it is
+ * still all the name there is.
+ */
+export declare const headingsIn: (elements: readonly Element[]) => Element[];

package/dist/utils/heading-in/heading-in.js

@@ -0,0 +1,14 @@
+const HEADING = 'h1, h2, h3, h4, h5, h6, [role="heading"]';
+export const headingIn = (elements) => {
+    for (const one of elements) {
+        const found = one.matches(HEADING) ? one : one.querySelector(HEADING);
+        if (found) {
+            return found;
+        }
+    }
+    return null;
+};
+export const headingsIn = (elements) => {
+    const heading = headingIn(elements);
+    return heading ? [heading] : [...elements];
+};

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

@@ -0,0 +1,23 @@
+/**
+ * Writes and reads numbers in a locale with `Intl.NumberFormat` options, for a
+ * control that shows a number and takes one typed: a currency, a percent, a
+ * unit, or grouped thousands. React Aria's NumberField and Slider take the same
+ * `formatOptions`.
+ *
+ * **Formatters are kept**, by locale and options, since one is expensive to
+ * build and cheap to call, and a control formats on every update.
+ */
+/** Writes a number in a locale with `Intl.NumberFormat` options. */
+export declare const formatNumber: (value: 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.
+ *
+ * The locale's group separators are dropped and its decimal separator read as
+ * a point, so `1.234,5` in `de-DE` is 1234.5. A currency sign, a percent sign
+ * and a unit the options write are dropped too, and a percent is read back as
+ * the fraction it shows: `25 %` is 0.25. A point is read as a decimal point in
+ * a locale that groups with something else, which is what a decimal keypad
+ * types.
+ */
+export declare const parseNumber: (text: string, locale?: string, options?: Intl.NumberFormatOptions) => number | null;

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

@@ -0,0 +1,55 @@
+const held = new Map();
+const formatter = (locale, options) => {
+    const key = `${locale}|${JSON.stringify(options ?? {})}`;
+    let found = held.get(key);
+    if (!found) {
+        found = new Intl.NumberFormat(locale || undefined, options);
+        held.set(key, found);
+    }
+    return found;
+};
+export const formatNumber = (value, locale = '', options) => formatter(locale, options).format(value);
+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);
+};
+const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&');
+export const parseNumber = (text, locale = '', options) => {
+    const parts = formatter(locale, options).formatToParts(-12345.6);
+    const of = (type) => parts.filter((part) => part.type === type).map((part) => part.value);
+    const group = of('group')[0] ?? ',';
+    const decimal = of('decimal')[0] ?? '.';
+    const dropped = [...of('currency'), ...of('percentSign'), ...of('unit'), ...of('literal')]
+        .map((one) => one.trim())
+        .filter(Boolean);
+    const percent = options?.style === 'percent' && /[%\u066a\u2030]/u.test(text);
+    let read = text.replace(/[\s\u00a0\u202f]/gu, '');
+    for (const one of dropped) {
+        read = read.replace(new RegExp(literal(one), 'gu'), '');
+    }
+    read = read.replace(/[\u2212\u2012\u2013]/gu, '-');
+    const separator = group.trim() || group;
+    if (read.includes(separator) && !grouped(read, separator, decimal)) {
+        if (group !== '.' || read.includes(decimal)) {
+            return null;
+        }
+    }
+    if (group !== '.' || decimal === '.') {
+        read = read.replace(new RegExp(literal(separator), 'gu'), '');
+    }
+    else if (read.includes(decimal)) {
+        read = read.replaceAll(group, '');
+    }
+    else {
+        read = read.replaceAll(group, '.');
+    }
+    read = read.replace(decimal, '.');
+    if (!/^[+-]?(\d+\.?\d*|\.\d+)$/u.test(read)) {
+        return null;
+    }
+    const parsed = Number(read);
+    if (!Number.isFinite(parsed)) {
+        return null;
+    }
+    return percent ? parsed / 100 : parsed;
+};

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

@@ -0,0 +1,23 @@
+/** What `onApple` and `appleTouch` read of the browser: the parts of `navigator` they need. */
+export interface Platform {
+    readonly maxTouchPoints?: number;
+    readonly platform?: string;
+    readonly userAgent?: string;
+}
+/**
+ * Whether the browser is iOS or iPadOS, where VoiceOver reads a
+ * `role="spinbutton"` text field as a slider a reader cannot type in. React
+ * Aria's NumberField drops the role there for the same reason. An iPad asks
+ * for the desktop site and reports itself as a Mac, so a Mac with a touch
+ * screen counts too.
+ */
+export declare const appleTouch: (platform: Platform | undefined) => boolean;
+/**
+ * Whether the keyboard in front of the reader is an Apple one, which labels
+ * its modifiers with glyphs and whose platform modifier is Command.
+ *
+ * From the user agent, as every application asks it; `false` on a server,
+ * which has no keyboard to ask. Kbd draws `⌘K` or `Ctrl+K` from it and reads
+ * `mod` as the key it names.
+ */
+export declare const onApple: (platform?: Platform | undefined) => boolean;

package/dist/utils/platform/platform.js

@@ -0,0 +1,11 @@
+export const appleTouch = (platform) => {
+    if (!platform) {
+        return false;
+    }
+    const agent = platform.userAgent ?? '';
+    if (/iPhone|iPad|iPod/u.test(agent)) {
+        return true;
+    }
+    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 ?? '');

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

@@ -34,3 +34,17 @@ export type ColorBytes = [number, number, number];
  * @param value A resolved color, as `getComputedStyle` reports one.
  */
 export declare const readColor: (value: string) => ColorBytes | undefined;
+/**
+ * A computed color as `rgb()`, or `rgba()` where it is see-through, which
+ * every SVG reader can draw.
+ *
+ * A theme's colors compute to `oklch()` or `color()`, which a browser draws
+ * and an image editor opening a saved file may not, so the color is painted
+ * onto one fresh pixel and read back, its alpha with it. Unlike `readColor`,
+ * which refuses what it cannot tell apart from its ground, this keeps what the
+ * pixel says: a computed style is always a color the engine parsed. A page with
+ * no canvas keeps the color as it is.
+ *
+ * @param color A resolved color, as `getComputedStyle` reports one.
+ */
+export declare const rgbOf: (color: string) => string;

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

@@ -34,3 +34,16 @@ export const readColor = (value) => {
     known.set(value, read);
     return read ? [...read] : undefined;
 };
+export const rgbOf = (color) => {
+    const pixel = typeof document === 'undefined' ? null : document.createElement('canvas');
+    const context = pixel?.getContext?.('2d', { willReadFrequently: true });
+    if (!context) {
+        return color;
+    }
+    context.fillStyle = color;
+    context.fillRect(0, 0, 1, 1);
+    const [red, green, blue, alpha] = context.getImageData(0, 0, 1, 1).data;
+    return alpha === 255
+        ? `rgb(${red}, ${green}, ${blue})`
+        : `rgba(${red}, ${green}, ${blue}, ${(alpha ?? 0) / 255})`;
+};

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

@@ -130,3 +130,9 @@ export interface Row {
  * on render, rows only where a pointer has stopped.
  */
 export declare const readRows: (table: Element) => Row[];
+/**
+ * A series name as it is matched: trimmed and in lower case, since a column's
+ * heading is matched without regard to case or surrounding space everywhere a
+ * name is written, in `lines`, `hidden-series` and `hide()` alike.
+ */
+export declare const seriesKey: (name: string) => string;