@fusion.dev/helix-core 0.145.0 → 0.146.0

package/dist/utils/calendar/calendar.js

@@ -1,4 +1,4 @@
-import { valueAsDate as asDate, dateAsValue as fromDate } from '../value-as/value-as.js';
+import { valueAsDate as asDate, dateAsValue as fromDate, utcDate } from '../value-as/value-as.js';
 import { writtenList } from '../written-list/written-list.js';
 export const localToday = (now = new Date()) => {
     const month = `${now.getMonth() + 1}`.padStart(2, '0');
@@ -15,13 +15,13 @@ export const weekStartOf = (locale) => {
         return 0;
     }
 };
-export const monthOf = (date) => `${date.getUTCFullYear()}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
-export const addDays = (date, days) => new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days));
+export const monthOf = (date) => `${String(date.getUTCFullYear()).padStart(4, '0')}-${String(date.getUTCMonth() + 1).padStart(2, '0')}`;
+export const addDays = (date, days) => utcDate(date.getUTCFullYear(), date.getUTCMonth(), date.getUTCDate() + days);
 export const sameMonth = (left, right) => left.getUTCFullYear() === right.getUTCFullYear() && left.getUTCMonth() === right.getUTCMonth();
 export const addMonths = (date, months) => {
-    const target = new Date(Date.UTC(date.getUTCFullYear(), date.getUTCMonth() + months, 1));
-    const last = new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth() + 1, 0)).getUTCDate();
-    return new Date(Date.UTC(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last)));
+    const target = utcDate(date.getUTCFullYear(), date.getUTCMonth() + months, 1);
+    const last = utcDate(target.getUTCFullYear(), target.getUTCMonth() + 1, 0).getUTCDate();
+    return utcDate(target.getUTCFullYear(), target.getUTCMonth(), Math.min(date.getUTCDate(), last));
 };
 export const barredBy = (date, rules) => {
     const iso = fromDate(date);
@@ -72,7 +72,7 @@ export const periodCells = ({ max, min, page, shown, today, view }) => {
     const start = years ? yearPageOf(page) : page;
     return Array.from({ length: 12 }, (_, index) => {
         const at = years ? start + index : index;
-        const first = new Date(Date.UTC(years ? at : start, years ? 0 : index, 1));
+        const first = utcDate(years ? at : start, years ? 0 : index, 1);
         return {
             at,
             chosen: years ? at === shown.getUTCFullYear() : monthOf(first) === monthOf(shown),

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

@@ -46,7 +46,7 @@ export interface TooltipAt {
  *
  * The chart's `pointer` is one, and is what every chart passes.
  */
-export type ReadingCursor = Pick<ChartPointerController, 'column' | 'keyed'>;
+export type ReadingCursor = Pick<ChartPointerController, 'column' | 'keyed'> & Partial<Pick<ChartPointerController, 'position' | 'shows'>>;
 /**
  * What a pointer resting on a reading shows, as `Tooltip` pointed at a mark.
  *

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

@@ -10,7 +10,9 @@ 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>`;
+        : html `<span aria-live="polite" part="live" role="status">${reading.keyed && row
+            ? spokenReading(row, reading.column, (cell) => reading.shows?.(cell) !== false, reading.position)
+            : ''}</span>`;
     if (!row || rows.length === 0) {
         return live;
     }

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

@@ -5,6 +5,10 @@ import type { Row } from '../read-series/read-series.js';
  *
  * 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.
+ * blank cell says nothing and is left out, and so is a cell `shows` answers
+ * false for, which is a series a legend hid.
+ *
+ * `position` follows in brackets, such as "2 of 12", where the chart gives
+ * one: last, so the reading is heard before where it stands.
  */
-export declare const spokenReading: (row: Row, column?: number) => string;
+export declare const spokenReading: (row: Row, column?: number, shows?: (cell: number) => boolean, position?: string) => string;

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

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

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

@@ -0,0 +1,8 @@
+/**
+ * A heading level a reader can be told: a whole number from 1 to 6, from
+ * the level asked for, or `fallback` where none was.
+ *
+ * `aria-level` takes a whole number, so a fraction is cut to the level below
+ * it, and a level past either end is held at it: `0` is 1 and `9` is 6.
+ */
+export declare const headingLevel: (level: number | undefined, fallback?: number) => number;

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

@@ -0,0 +1,4 @@
+export const headingLevel = (level, fallback = 3) => {
+    const asked = level === undefined || Number.isNaN(level) ? fallback : level;
+    return Math.min(6, Math.max(1, Math.trunc(asked)));
+};

package/dist/utils/implicit-submit/implicit-submit.d.ts

@@ -0,0 +1,25 @@
+/** Whether `element` is a submit button, native or Helix. */
+export declare const submits: (element: Element) => boolean;
+/** The form's default button, the first submit button in it, native or Helix. */
+export declare const defaultButton: (form: HTMLFormElement) => Element | undefined;
+/** Whether `target` is a native field of `form` that Enter submits it from. */
+export declare const submitsOnEnter: (target: EventTarget | undefined, form: HTMLFormElement) => boolean;
+/**
+ * Submits a control's form the way pressing Enter in a native text field does.
+ *
+ * A Helix control's own input is in a shadow root and has no form owner, so
+ * the platform never runs implicit submission for it. This runs it: the form's
+ * default button is activated, the first submit button in it, a Helix one
+ * included. With none, the form is submitted when it holds no more than one
+ * field that counts against implicit submission, and nothing happens
+ * otherwise.
+ *
+ * **A module of its own rather than a method on the base**, so its code ships
+ * only with the controls that submit on Enter (Input, Number Input, Pin Input,
+ * Combobox, the picker fields and Button) and not with Switch, Checkbox or
+ * Slider. `form` is the control's `form`, and a control with none submits
+ * nothing.
+ *
+ * @reference https://html.spec.whatwg.org/multipage/form-control-infrastructure.html#implicit-submission implicit submission
+ */
+export declare const submitImplicitly: (form: HTMLFormElement | null) => void;

package/dist/utils/implicit-submit/implicit-submit.js

@@ -0,0 +1,52 @@
+import { HelixFormElement } from '../../helix-form-element/helix-form-element.js';
+const BLOCKING_TYPES = new Set([
+    'date',
+    'datetime-local',
+    'email',
+    'month',
+    'number',
+    'password',
+    'search',
+    'tel',
+    'text',
+    'time',
+    'url',
+    'week',
+]);
+const hooks = (element) => element;
+export const submits = (element) => {
+    if (element instanceof HelixFormElement) {
+        return hooks(element).submitsForm;
+    }
+    if (element instanceof HTMLButtonElement) {
+        return element.type === 'submit';
+    }
+    return (element instanceof HTMLInputElement && (element.type === 'submit' || element.type === 'image'));
+};
+export const defaultButton = (form) => [...form.elements].find((element) => submits(element));
+export const submitsOnEnter = (target, form) => target instanceof HTMLInputElement && target.form === form && BLOCKING_TYPES.has(target.type);
+export const submitImplicitly = (form) => {
+    if (!form) {
+        return;
+    }
+    const button = defaultButton(form);
+    if (button) {
+        if (button.matches(':disabled')) {
+            return;
+        }
+        if (button instanceof HelixFormElement) {
+            hooks(button).activate();
+        }
+        else {
+            ;
+            button.click();
+        }
+        return;
+    }
+    const blocking = [...form.elements].filter((element) => element instanceof HelixFormElement
+        ? hooks(element).blocksImplicitSubmission
+        : element instanceof HTMLInputElement && BLOCKING_TYPES.has(element.type));
+    if (blocking.length <= 1) {
+        form.requestSubmit();
+    }
+};

package/dist/utils/name-text/name-text.d.ts

@@ -0,0 +1,12 @@
+/**
+ * The words a node gives a name computed from its content: its text, read
+ * through slots, and the `aria-label` or `alt` of a picture in it, such as an
+ * icon named by its own label. A node hidden from the reader gives none, and
+ * so does `shown`, the part where a control shows its value.
+ *
+ * **In every build.** `AriaForwardController` asks it whether a control's own
+ * label has words in it, which decides where the host's label goes, so it is
+ * kept apart from the missing-name warning, which only a development build
+ * carries.
+ */
+export declare const nameText: (node: Node, shown?: Element | null) => string;

package/dist/utils/name-text/name-text.js

@@ -0,0 +1,25 @@
+export const nameText = (node, shown) => {
+    if (node === shown) {
+        return '';
+    }
+    if (node instanceof HTMLSlotElement) {
+        return node
+            .assignedNodes({ flatten: true })
+            .map((one) => nameText(one, shown))
+            .join('');
+    }
+    if (node.nodeType === Node.TEXT_NODE) {
+        return node.textContent ?? '';
+    }
+    if (!(node instanceof Element)) {
+        return '';
+    }
+    if ((node instanceof HTMLElement && node.hidden) || node.getAttribute('aria-hidden') === 'true') {
+        return '';
+    }
+    const said = node.getAttribute('aria-label') ?? node.getAttribute('alt');
+    if (said?.trim()) {
+        return said;
+    }
+    return [...node.childNodes].map((one) => nameText(one, shown)).join('');
+};

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

@@ -15,7 +15,8 @@ export declare const formatNumber: (value: number, locale?: string, options?: In
  *
  * 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
+ * and a unit the options write are dropped too, in the plural and the
+ * singular, 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.

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

@@ -15,13 +15,21 @@ const grouped = (text, separator, decimal) => {
 };
 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 format = formatter(locale, options);
+    const parts = format.formatToParts(-12345.6);
+    const one = format.formatToParts(1);
+    const of = (type, from = parts) => from.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 named = (from) => [
+        ...of('currency', from),
+        ...of('percentSign', from),
+        ...of('unit', from),
+        ...of('literal', from),
+    ];
+    const dropped = [...new Set([...named(parts), ...named(one)].map((word) => word.trim()))]
+        .filter(Boolean)
+        .sort((a, b) => b.length - a.length);
     const percent = options?.style === 'percent' && /[%\u066a\u2030]/u.test(text);
     let read = text.replace(/[\s\u00a0\u202f]/gu, '');
     for (const one of dropped) {

package/dist/utils/plain-click/plain-click.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Whether a click is a plain press of the main button, with no Command,
+ * Control, Shift or Alt held.
+ *
+ * A link pressed any other way opens where the browser opens it, a new tab or
+ * a new window, so an element that acts on a link's click first (a tab
+ * choosing itself, a skip link moving focus, an outline scrolling) leaves
+ * every other click to the browser.
+ */
+export declare const plainClick: (event: MouseEvent) => boolean;

package/dist/utils/plain-click/plain-click.js

@@ -0,0 +1 @@
+export const plainClick = (event) => event.button === 0 && !event.metaKey && !event.ctrlKey && !event.shiftKey && !event.altKey;

package/dist/utils/press-type/press-type.d.ts

@@ -0,0 +1,20 @@
+import type { PressPointerType } from '../../events/details.js';
+/** What the control saw before the click, which the click does not carry everywhere. */
+export interface RecentPress {
+    /** Whether Enter or Space started this press. */
+    key?: boolean;
+    /** The `pointerType` of the last `pointerdown` on the control. */
+    pointer?: string;
+}
+/**
+ * What a `click` came from, for `HelixPressEvent`.
+ *
+ * **Read in order.** The click's own pointer kind first, which Chromium and
+ * Firefox put on it. Then a key, which the caller saw start the press, because
+ * a keyboard press and a script's `click()` arrive alike. Then, for a click
+ * with a press count (`detail` above zero), the last pointer's kind, or
+ * `mouse` where none was seen, which is how Safari's click arrives. A click
+ * with none of these is `virtual`, as React Aria reads one: a screen reader's
+ * press or a script's `click()`.
+ */
+export declare const pressType: (click: MouseEvent, recent?: RecentPress) => PressPointerType;

package/dist/utils/press-type/press-type.js

@@ -0,0 +1,15 @@
+const POINTERS = new Set(['mouse', 'pen', 'touch']);
+export const pressType = (click, recent = {}) => {
+    const own = click.pointerType ?? '';
+    if (POINTERS.has(own)) {
+        return own;
+    }
+    if (recent.key === true) {
+        return 'keyboard';
+    }
+    if (click.detail > 0) {
+        const last = recent.pointer ?? '';
+        return POINTERS.has(last) ? last : 'mouse';
+    }
+    return 'virtual';
+};

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

@@ -22,8 +22,6 @@ export type RuntimeKind =
 'duplicate-registration'
 /** The browser refused fullscreen, usually for a frame without the permission. */
  | 'fullscreen-refused'
-/** An Avatar Group's `max` is past the number the fold is written for. */
- | 'max-past-fold'
 /** A rating's `min` is no score between 0 and its `max`. */
  | 'min-out-of-range'
 /** A Stat was given one of Trend's directions, `up`, `down` or `neutral`, which lay nothing out. */
@@ -34,7 +32,10 @@ export type RuntimeKind =
  | 'missing-alt'
 /** The three.js driver could not load its layout, so the notes stay where they started. */
  | 'missing-layout'
-/** A control has no accessible name, so a screen reader announces it by its role alone. */
+/**
+ * A control has no accessible name, so a screen reader announces it by its role alone.
+ * Reported in development builds only (the `development` export condition).
+ */
  | 'missing-name'
 /** A selectable Data Table has no `row-key`, so it knows each row by its place. */
  | 'missing-row-key'
@@ -64,6 +65,8 @@ export type RuntimeKind =
  | 'too-many-rows'
 /** A filter field marks more than one operator as its default. */
  | 'two-default-operators'
+/** A Quote's text starts or ends with a quotation mark, so the browser's marks double it. */
+ | 'typed-marks'
 /** A React handler prop names an event nothing dispatches. */
  | 'unknown-event'
 /** An Icon's `name` is in no icon set it can read, so it draws nothing. */

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

@@ -0,0 +1,15 @@
+/**
+ * The value at `path` in a row of data, or `undefined` where the path leads
+ * nowhere: the field a Table or Data Table column, a Data Table's `row-key`
+ * or a Virtual List's template hole names.
+ *
+ * A dot separates keys, so `author.name` reads `row.author.name`. A key that
+ * holds a dot itself is read whole first, so a flat record with a key such as
+ * `"v1.2"` keeps working. An empty path reads nothing, and so does a row that
+ * is no record. `undefined` is drawn as an empty cell: a missing key is a hole
+ * in the data, and drawing "undefined" tells a reader the software is broken.
+ *
+ * Written here rather than taken from a library, because the whole of what is
+ * needed is "walk the keys and stop at the first thing that is not an object".
+ */
+export declare const valueAt: (row: unknown, path: string) => unknown;

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

@@ -0,0 +1,17 @@
+export const valueAt = (row, path) => {
+    if (path === '' || row === null || typeof row !== 'object') {
+        return undefined;
+    }
+    const record = row;
+    if (path in record) {
+        return record[path];
+    }
+    let value = record;
+    for (const key of path.split('.')) {
+        if (value === null || typeof value !== 'object') {
+            return undefined;
+        }
+        value = value[key];
+    }
+    return value;
+};

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

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

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

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

package/dist/utils/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';
+};