@fusion.dev/helix-headless 0.144.0 → 0.146.0

package/dist/data-table/root/order.d.ts

@@ -1,141 +0,0 @@
-/**
- * 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/data-table/root/order.js

@@ -1,76 +0,0 @@
-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/listbox/range.d.ts

@@ -1,17 +0,0 @@
-/**
- * What Shift with Home or End adds to a listbox's selection, as arithmetic
- * over the options on show.
- *
- * Pure and beside the family's `index.ts`, because which options a range takes
- * in is a fact about a list, and a spec can hold it without a page.
- */
-/**
- * The selection after Shift with Home or End: every option shown from the
- * highlight to the end the key went to, added after what was selected, or
- * `null` where nothing new is taken in.
- *
- * `from` is where the highlight was, as an index into `shown`, or `-1` for no
- * highlight, which takes in the end alone. `to` is the end the key went to.
- * APG's multiple-selection listbox.
- */
-export declare const rangeAdd: (values: readonly string[], shown: readonly string[], from: number, to: number) => string[] | null;

package/dist/listbox/range.js

@@ -1,5 +0,0 @@
-export const rangeAdd = (values, shown, from, to) => {
-    const [start, end] = from < 0 ? [to, to] : [Math.min(from, to), Math.max(from, to)];
-    const added = shown.slice(start, end + 1).filter((value) => !values.includes(value));
-    return added.length > 0 ? [...values, ...added] : null;
-};

package/dist/tag/selection.d.ts

@@ -1,10 +0,0 @@
-/** How many tags a group lets a reader select. */
-export type TagSelectionMode = 'multiple' | 'none' | 'single';
-/**
- * The `value` a press on the tag carrying `pressed` leaves.
- *
- * `single` selects that tag alone, or none where it was the one selected.
- * `multiple` adds it, or takes it out. `none` selects nothing and leaves the
- * value as it was.
- */
-export declare const pressedValue: (mode: TagSelectionMode, value: string, pressed: string) => string;

package/dist/tag/selection.js

@@ -1,12 +0,0 @@
-import { commaList, toggleValue } from '@fusion.dev/helix-core';
-export const pressedValue = (mode, value, pressed) => {
-    const now = commaList(value);
-    const held = now.includes(pressed);
-    if (mode === 'single') {
-        return held ? '' : pressed;
-    }
-    if (mode === 'multiple') {
-        return toggleValue(now, pressed).join(', ');
-    }
-    return value;
-};