@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/data-table/root/data-table-root.js

@@ -9,176 +9,36 @@ import { customElement, HelixElement, HelixFilterEvent, HelixNavigateEvent, Heli
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
-/* `static-html`'s `html`, because the pagination's tag is interpolated: a
-   template naming a literal `helix-pagination` renders the styled element from
-   the headless tier, and `lit`'s own `html` treats `${tag}` in tag position as
-   text, which renders an element called `lit$…$` that lays out as nothing.
-   Measured: the styled spec read `localName` as `lit$640177303$`. */
 import { html } from 'lit/static-html.js';
 import '../../pagination/index.js';
 import { cycle, format, ordered, parse } from './order.js';
-/**
- * @summary A table that owns a result: rows as data, with sort, filter and paging.
- *
- * @description
- * **The schema is markup and the data is a property.** Columns are declared as
- * `helix-table-column` children, because a schema is small, declarative, and
- * something a reader should be able to see in the HTML; rows are handed over as
- * an array, because data is large and a table that draws ten thousand elements
- * cannot window them.
- *
- * ```html
- * <helix-data-table .rows=${rows} sort="name:asc" page-size="20">
- *   <helix-table-column field="name" sortable>Name</helix-table-column>
- *   <helix-table-column field="size" align="end" sortable .cell=${bytes}>Size</helix-table-column>
- * </helix-data-table>
- * ```
- *
- * `helix-table` takes rows as markup and is the right component for a table of
- * twelve things a person wrote out.
- *
- * **Sort and filter apply to the whole set, never the page.** Sorting the drawn
- * window is correct on the first screen and wrong on every other one, which is
- * how it survives being looked at. The arithmetic lives in `order.ts` where
- * nothing can see a window, and its spec asserts the composition rather than the
- * three steps, because each step alone passes either way.
- *
- * **What it does not do, stated where a consumer will read it: the cell values
- * do not server-render.** The headings do, because a column renders its own, and
- * the row elements do, because their count comes from `rows`. Reading a cell
- * needs the columns, and the columns are markup children that Lit SSR does not
- * hand this element: `children` is undefined there. So a crawler and a reader on
- * a slow connection see a table of the right shape with nothing in it, which is
- * strictly less than `helix-table` serves for a table whose rows are markup.
- *
- * That is the cost of "the schema is markup and the data is a property". Use
- * `helix-table` where the content has to be in the served HTML and the result is
- * small enough to write out; use this where the result is large, and accept that
- * the first paint is a shell. The obvious workaround, a `columns` property
- * beside the markup columns, is deliberately not offered: it splits one source
- * of truth for the columns into two that nothing checks against each other, and
- * a table rendering one way on the server and another in the browser is that
- * failure with a hydration mismatch on top.
- *
- * **Every axis is controlled or uncontrolled, and that is what makes a server
- * mode fall out rather than be bolted on.** `sort`, `filter`, `page` and
- * `page-size` each defer to the consumer when set and seed themselves from a
- * `default-*` when not. A consumer who answers all four holds the data flow:
- * they hear the reader's request, fetch, and hand back a new `rows` with a
- * `total`. Retrofitting that inverts the flow and is a rewrite, so it is here
- * from the start.
- *
- * @since 0.1.0
- * @status experimental
- * @category data
- * @aliases Grid, Result table, Data grid
- * @documentation https://helix.fusion.dev/components/data-table
- *
- * @slot - The columns, declared as `helix-table-column` children.
- * @slot footer - Below the grid, replacing the pagination this would otherwise draw.
- * @slot toolbar - Above the grid, for a search field or actions.
- *
- * @event {HelixFilterEvent} helix-filter - Fired when the query changes, and cancelable.
- * @event {HelixNavigateEvent} helix-navigate - Fired when a reader asks for another page, and cancelable.
- * @event {HelixSortEvent} helix-sort - Fired when a reader asks for a different order, and cancelable.
- *
- * @csspart cell - One cell.
- * @csspart empty - Shown when no rows match.
- * @csspart footer - The region below the grid.
- * @csspart head - The row the column headings sit in. `display: contents`, so it takes no space.
- * @csspart loading - Shown while the rows are still on their way.
- * @csspart pagination - The pagination, where this draws one.
- * @csspart row - One row of data.
- * @csspart table - The grid.
- * @csspart toolbar - The region above the grid.
- *
- * @cssproperty --data-table-template - The column track list this element worked out from the columns declared in it. Written by the component, read by the sheet that paints: a stylesheet takes it to lay the grid out, and setting it does nothing, because the component writes it inline on the very element that reads it and an inline declaration beats any sheet. `--data-table-columns` is the one to set.
- */
 let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollection(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Query to open with, where nothing declared one.
-         */
         this.defaultFilter = '';
-        /**
-         * Page to open on, where nothing declared one.
-         */
         this.defaultPage = 1;
-        /**
-         * Page size to open with, where nothing declared one.
-         */
         this.defaultPageSize = 0;
-        /**
-         * Order to open on, where nothing declared one.
-         */
         this.defaultSort = '';
-        /**
-         * The field naming a row's stable identity.
-         *
-         * **Needed before selection exists, not after.** Lit keys the rendered rows by
-         * it, so a sort moves a row's element rather than rewriting every cell in
-         * place, which is what keeps focus inside a cell and keeps a CSS transition
-         * attached to the row it belongs to. Left unset the index is the key, which is
-         * correct only while nothing reorders: it is why this defaults to something
-         * that works and is worth setting anyway.
-         */
         this.key = '';
-        /**
-         * Accessible name for the grid.
-         */
         this.label = '';
-        /**
-         * Whether this element does the work or asks the consumer to.
-         *
-         * `client` filters, sorts and pages `rows` itself. `server` applies none of
-         * them: `rows` is the page, `total` is the size of the whole result, and the
-         * three events are requests the consumer answers by fetching. Past some size
-         * the client cannot hold the data, so this is not an optimization, it is the
-         * only mode that works, and it is here from the start because adding it later
-         * inverts the data flow.
-         */
         this.mode = 'client';
-        /**
-         * The whole result, in the order it arrived.
-         *
-         * A property and not an attribute: it is an array. Left alone this element
-         * filters, sorts and pages it; in `server` mode it is the page the consumer
-         * already fetched and none of the three is applied.
-         *
-         * **Read, never written.** Sorting produces a new array rather than reordering
-         * this one, because a consumer's array may be the same object their own state
-         * holds and reordering it under them is a mutation they did not ask for.
-         */
         this.rows = [];
-        /**
-         * How many rows the whole result has, where this element cannot count them.
-         *
-         * Only read in `server` mode, where `rows` is one page and its length says
-         * nothing about the result. Ignored in `client` mode rather than trusted,
-         * because two sources for one count is the mistake, and here the array is the
-         * one that cannot be stale.
-         */
         this.total = 0;
         this.sortState = undefined;
         this.filterState = undefined;
         this.pageState = undefined;
         this.pageSizeState = undefined;
         this.paginatedState = undefined;
-        /** Said once per element, so a table that re-renders does not repeat it. */
         this.warnedAboutSize = false;
-        /** Columns arrive from the light DOM, which changes no property here. */
         this.handleSlotChange = () => {
             this.requestUpdate();
         };
-        /** A click on a sortable heading. */
         this.handleHeadClick = (event) => {
             const column = this.columnFrom(event);
             if (column?.canSort) {
                 this.toggleSort(column.field);
             }
         };
-        /** The same on Enter and Space, since a heading that sorts is a control. */
         this.handleHeadKey = (event) => {
             if (event.key !== 'Enter' && event.key !== ' ') {
                 return;
@@ -189,14 +49,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
                 this.toggleSort(column.field);
             }
         };
-        /**
-         * The composed pagination's request, relayed as this element's own.
-         *
-         * Stopped rather than allowed to bubble, because two `helix-navigate` events
-         * for one click would reach a consumer's handler twice: the pagination's, and
-         * this element's after it. The one that leaves carries this element's page
-         * bounds rather than the inner component's.
-         */
         this.handleNavigate = (event) => {
             event.stopPropagation();
             const wanted = Number(event.detail.value);
@@ -206,26 +58,10 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         };
     }
     static { HelixHeadlessDataTable_1 = this; }
-    /**
-     * Nothing is assigned by name, so the columns can be put in a header row.
-     *
-     * `role="columnheader"` under `role="grid"` with no owning row is invalid, and
-     * the columns are ordinary children a consumer writes with no `slot`. Manual
-     * assignment is the only way to wrap them without editing the consumer's
-     * markup, which is a change a React consumer's hydration reports and does not
-     * patch up. The same arrangement `helix-table` arrived at, for the same reason.
-     */
     static { this.shadowRootOptions = {
         ...HelixElement.shadowRootOptions,
         slotAssignment: 'manual',
     }; }
-    /**
-     * The order, as `field:direction`.
-     *
-     * Set it and this element defers: a reader's click fires `helix-sort` and
-     * changes nothing until a new value arrives. `default-sort` seeds an order this
-     * element then owns.
-     */
     get sort() {
         return this.sortState ?? this.defaultSort;
     }
@@ -234,13 +70,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.sortState = next;
         this.requestUpdate('sort', previous);
     }
-    /**
-     * What the rows are narrowed to, as one query across every column.
-     *
-     * One query rather than a predicate per column, which is what a reader means
-     * by a search box above a table. It matches on each column's ordering value,
-     * so search and sort cannot disagree about what a column holds.
-     */
     get filter() {
         return this.filterState ?? this.defaultFilter;
     }
@@ -249,13 +78,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.filterState = next;
         this.requestUpdate('filter', previous);
     }
-    /**
-     * The page on show, from 1.
-     *
-     * Clamped on the way out, so what this reports is the page it drew: a
-     * bookmarked link to page 99 of a result that has since shrunk reads back as
-     * the last page rather than as 99.
-     */
     get page() {
         const asked = this.pageState ?? this.defaultPage;
         return Math.min(this.pages, Math.max(1, Math.floor(asked) || 1));
@@ -265,15 +87,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.pageState = next;
         this.requestUpdate('page', previous);
     }
-    /**
-     * How many rows a page holds. Zero is every row, which is what "no paging" means.
-     *
-     * **It announces nothing, and that is not an omission.** Nothing in this
-     * element ever asks for a different page size: a size selector is
-     * `helix-pagination-size`, which a consumer puts in the `footer` slot and
-     * answers themselves. Routing this through `requestChange` would announce an
-     * event the element never has cause to fire.
-     */
     get pageSize() {
         return Math.max(0, Math.floor(this.pageSizeState ?? this.defaultPageSize) || 0);
     }
@@ -282,14 +95,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.pageSizeState = next;
         this.requestUpdate('pageSize', previous);
     }
-    /**
-     * Whether to draw a pagination under the grid.
-     *
-     * On by default once a page size is set, because a paged table with no way to
-     * change pages shows a reader the first twenty rows and no way to know there
-     * are more. Off for a consumer supplying their own through the `footer` slot,
-     * which is why the slot replaces this rather than sitting beside it.
-     */
     get paginated() {
         return this.paginatedState ?? this.pageSize > 0;
     }
@@ -298,56 +103,19 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.paginatedState = next;
         this.requestUpdate('paginated', previous);
     }
-    /** The columns declared as children, in the order they are written. */
     get tableColumns() {
-        /* `?? []` is the server. Lit's element shim carries attributes and not a
-           tree, so `children` is undefined there, and this getter is read during
-           `render`: spreading it throws and takes the whole SSR suite with it. */
         return [...(this.children ?? [])].filter((child) => 'isTableColumn' in child && child.isTableColumn === true);
     }
-    /** The columns reduced to what the ordering needs. */
     get axes() {
         return this.tableColumns
             .filter((column) => column.field !== '')
             .map((column) => ({ field: column.field, order: (row) => column.order(row) }));
     }
-    /** The track list, from the columns if there are any. */
     get template() {
         const declared = this.tableColumns;
         return declared.length > 0 ? declared.map((column) => column.track).join(' ') : '';
     }
-    /**
-     * How many rows this draws before it is worth saying something, and why 2,000.
-     *
-     * Measured 28 Aug 2026 on a four-column grid, mounting and painting: 100 rows
-     * in 10.9ms, 500 in 30.2ms, 2,000 in 83.2ms and **5,000 rows as 20,000 cells
-     * in 186ms**. It is linear at roughly 37 microseconds a row, so the 100ms an
-     * interaction has to stay inside lands near 2,700 and this sits under it.
-     * Sorting stays cheap throughout, 23.7ms at five thousand, so the cost is the
-     * cells rather than the work over them.
-     */
     static { this.COMFORTABLE = 2_000; }
-    /**
-     * Says so when a table is asked to draw more than it comfortably can.
-     *
-     * **The component renders every row it is given and defaults to doing so.**
-     * `defaultPageSize` is `0`, so `paginated` is false unless a consumer asks,
-     * which means the out-of-the-box arrangement is the unbounded one and nothing
-     * about it says that a result of any size will simply be drawn.
-     *
-     * **Windowing was refused**, which is worth recording because it is the
-     * obvious answer. This element already has two mechanisms: `paginated` with a
-     * `page-size`, and `mode="server"` where `rows` is one page, `total` is the
-     * whole result and `aria-rowcount` already reports the result rather than the
-     * window, which is the hard half of virtualization done correctly. A third
-     * would fight the first two, and virtualizing a grid means variable row
-     * heights, a sticky header and keeping `aria-rowindex` honest against a result
-     * the element is no longer holding. `VirtualizeController` exists for the case
-     * where the rows are a flat list and this is not that.
-     *
-     * Warned once per element, in a browser only: a warning during a server render
-     * is one nobody can act on and one that would print per request.
-     */
     warnIfCrowded(drawn) {
         if (this.warnedAboutSize ||
             drawn <= HelixHeadlessDataTable_1.COMFORTABLE ||
@@ -360,14 +128,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
             'crosses an interaction budget around 2,700. Set `page-size` to paginate, or `mode="server"` ' +
             'to hand it one page at a time with `total` describing the whole result.');
     }
-    /**
-     * The rows to draw, and the counts around them.
-     *
-     * In `server` mode this element applies nothing: `rows` is already the page,
-     * `total` is the result, and both counts come from the consumer. Anything else
-     * would be this element filtering a page it was handed, which narrows one
-     * screen and calls it a search.
-     */
     get view() {
         if (this.mode === 'server') {
             const total = Math.max(this.total, this.rows.length);
@@ -382,7 +142,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.warnIfCrowded(view.rows.length);
         return view;
     }
-    /** How many pages the result makes, which is at least one even when empty. */
     get pages() {
         const size = this.pageSize;
         if (size <= 0) {
@@ -391,12 +150,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         const count = this.mode === 'server' ? Math.max(this.total, this.rows.length) : this.matched;
         return Math.max(1, Math.ceil(count / size));
     }
-    /**
-     * Rows after filtering, computed without paging.
-     *
-     * Separate from `view` because `pages` needs it and `page` needs `pages`:
-     * asking `view` for it would recurse through the clamp in `page`.
-     */
     get matched() {
         const query = this.filter.trim();
         if (query === '') {
@@ -411,17 +164,9 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
                 : String(value).toLocaleLowerCase().includes(needle);
         })).length;
     }
-    /** Emptiness is a fact about the data here, not about slotted children. */
     get hasRows() {
         return this.view.rows.length > 0;
     }
-    /**
-     * Asks for a different order, and reports whether the request stood.
-     *
-     * Announced before it is applied, so `preventDefault()` is a refusal and the
-     * order does not move, which is what makes a server-side sort expressible: the
-     * consumer refuses the local reorder, fetches, and hands back a new set.
-     */
     requestSort(next) {
         return requestChange({
             apply: (value) => {
@@ -434,7 +179,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
             next,
         });
     }
-    /** Asks for a different query. */
     requestFilter(next) {
         return requestChange({
             apply: (value) => {
@@ -447,7 +191,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
             next,
         });
     }
-    /** Asks for a different page. */
     requestPage(next) {
         if (next === this.page || next < 1 || next > this.pages) {
             return false;
@@ -463,30 +206,12 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
             next,
         });
     }
-    /**
-     * Narrows the rows, from a consumer's own search field.
-     *
-     * Public because the query lives above the table in every design that has one,
-     * and a consumer wiring their own input needs somewhere to send it. Returns
-     * whether the change stood, the same as every other request here.
-     */
     search(query) {
         return this.requestFilter(query);
     }
-    /**
-     * Cycles the order by one column, which is what a click on its heading means.
-     *
-     * Ascending, descending, then the order the rows arrived in. Public for the
-     * same reason `search` is: a consumer's own heading UI needs a way to ask.
-     */
     toggleSort(field) {
         return this.requestSort(format(cycle(parse(this.sort), field)));
     }
-    /**
-     * The columns into the header row, everything else into the toolbar and footer.
-     *
-     * Manual assignment, so a consumer's own markup is never written to.
-     */
     assign() {
         const root = this.renderRoot;
         if (!root?.querySelector) {
@@ -513,30 +238,10 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label || 'Table', role: 'grid' });
     }
-    /**
-     * Says on the toolbar and the footer whether anything is in them.
-     *
-     * **A stylesheet cannot ask.** `[part="toolbar"]:has(> slot:not(:has(*)))` is
-     * two faults at once: `:has()` may not be nested inside `:has()`, so the
-     * selector fails to parse and the whole rule is discarded; and
-     * `slot:not(:has(*))` is as true of a filled slot as of an empty one, because
-     * assigned nodes are not a slot's DOM children. Both verified in a browser.
-     */
     markEmpty() {
         this.markRegion('toolbar', ['toolbar']);
-        /* The footer is not empty while this element is drawing its own pagination
-           into it. */
         this.markRegion('footer', ['footer'], '[part="pagination"]');
     }
-    /**
-     * One region, hidden when its slot holds nothing and nothing of ours fills it.
-     *
-     * `hidden` beside the `data-empty` mirror: `data-empty` is the hook the styled
-     * sheet reads, and this tier ships no sheet, so an empty region left in the box
-     * tree would be a gap a headless consumer cannot close without knowing to look
-     * for it. The styled rule stays too, because that sheet sets `display` on these
-     * parts and therefore outranks the UA's `[hidden]` one.
-     */
     markRegion(part, slots, occupied) {
         const region = this.renderRoot?.querySelector(`[part="${part}"]`);
         const empty = !slots.some((name) => slotFilled(this.renderRoot?.querySelector(`slot[name="${name}"]`))) && !(occupied && this.renderRoot?.querySelector(occupied));
@@ -549,20 +254,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         this.assign();
         this.announceSort();
     }
-    /**
-     * Tells each column which way it is ordered, if it is the one.
-     *
-     * **The table owns the sort and the column carries the semantics**, which is
-     * the only arrangement that can be right: `role="columnheader"` is on the
-     * column, so `aria-sort` has to be there too, and the value is a fact about
-     * the table's `sort` rather than about any column. Pushed down here rather
-     * than pulled up there, because a column asking its parent would have to know
-     * what kind of parent it has, and it is slotted into two.
-     *
-     * In `updated` and after `assign`, so the order announced is the order the
-     * rows are already in. Announced before the rows moved is the sort a reader is
-     * told about being one they cannot see yet.
-     */
     announceSort() {
         const current = parse(this.sort);
         for (const column of this.tableColumns) {
@@ -585,10 +276,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
     renderRows(rows) {
         const columns = this.tableColumns;
         const field = this.key;
-        /* Keyed, so a sort moves a row's element rather than rewriting every cell
-           in place: focus inside a cell survives and a transition stays attached to
-           the row it belongs to. The index is the fallback and is correct only
-           while nothing reorders, which is why `key` is worth setting. */
         return html `${repeat(rows, (row, index) => (field ? String(row[field] ?? index) : index), (row, index) => html `<div
         part="row"
         role="row"
@@ -597,14 +284,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
         ${columns.map((column) => this.renderCell(column, row))}
       </div>`)}`;
     }
-    /**
-     * A row's place in the whole result, counting the header as row 1.
-     *
-     * **The number describes the result and not the window**, which is the whole
-     * reason a virtualized or paged grid needs `aria-rowindex` at all: a screen
-     * reader on page three should hear row 41, and a grid whose indices restart at
-     * every page tells a reader the result is twenty rows long however many it has.
-     */
     rowIndex(within) {
         const size = this.pageSize;
         const offset = size > 0 ? (this.page - 1) * size : 0;
@@ -642,21 +321,6 @@ let HelixHeadlessDataTable = class HelixHeadlessDataTable extends MixinCollectio
             : nothing}
       </div>`;
     }
-    /**
-     * Listens on the host, not on the slot the columns are assigned to.
-     *
-     * The columns are light-DOM children of this element, so their events bubble
-     * to it directly and the shadow tree is not involved at all. Bound on the
-     * `<slot>` instead, this works in a browser, because an event from a slotted
-     * node passes through the slot in the flattened tree, and does not work in
-     * happy-dom, which does not implement that propagation: measured, the host
-     * hears the click and the slot does not. A spec written against the slot fails
-     * in the suite while the component is correct.
-     *
-     * Added here rather than in the template because there is nothing in the
-     * shadow tree to attach it to, and removed on disconnect because this element
-     * is the listener's owner rather than its subject.
-     */
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('click', this.handleHeadClick);

package/dist/data-table/root/order.js

@@ -1,29 +1,3 @@
-/**
- * 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.
- */
-/**
- * `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 const parse = (spec) => {
     const trimmed = spec.trim();
     if (trimmed === '') {
@@ -35,36 +9,13 @@ export const parse = (spec) => {
     }
     return { direction, field };
 };
-/** A `Sort` written back out, so the property and the attribute agree. */
 export const format = (sort) => sort ? `${sort.field}:${sort.direction}` : '';
-/**
- * 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 const cycle = (current, field) => {
     if (current?.field !== field) {
         return { direction: 'asc', field };
     }
     return current.direction === 'asc' ? { direction: 'desc', field } : 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 const filter = (rows, query, axes) => {
     const needle = query.trim().toLocaleLowerCase();
     if (needle === '') {
@@ -72,16 +23,6 @@ export const filter = (rows, query, axes) => {
     }
     return rows.filter((row) => axes.some((axis) => text(axis.order(row)).toLocaleLowerCase().includes(needle)));
 };
-/**
- * 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 const sort = (rows, spec, axes) => {
     const axis = spec ? axes.find((one) => one.field === spec.field) : undefined;
     if (!spec || !axis) {
@@ -90,14 +31,6 @@ export const sort = (rows, spec, axes) => {
     const sign = spec.direction === 'asc' ? 1 : -1;
     return [...rows].sort((left, right) => compare(axis.order(left), axis.order(right), sign));
 };
-/**
- * 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 `helix-pagination` already applies to what it reports.
- */
 export const window_ = (rows, page, size) => {
     if (size <= 0) {
         return [...rows];
@@ -107,12 +40,6 @@ export const window_ = (rows, page, size) => {
     const from = (wanted - 1) * size;
     return rows.slice(from, from + size);
 };
-/**
- * A value as text, for matching.
- *
- * `null` and `undefined` become empty rather than their own names, so a search
- * for "null" does not match every hole in the data.
- */
 const text = (value) => {
     if (value === null || value === undefined) {
         return '';
@@ -122,26 +49,6 @@ const text = (value) => {
     }
     return String(value);
 };
-/**
- * Two cell values ordered, with the types a table actually holds.
- *
- * **Numbers compare as numbers and strings collate.** `String(a) < String(b)`
- * puts 10 before 9 and puts every accented word after every unaccented one, and
- * both look like the sort is broken while every value in the column is correct.
- * `localeCompare` handles the second, and the numeric branch handles the first.
- *
- * **Holes sort last in both directions**, which is deliberate and is the one
- * choice here a reader could disagree with. A missing value is not smaller than
- * a present one, it is absent, and burying the holes at the end is what a reader
- * scanning for the largest or smallest actual value wants. Reversing them with
- * the direction puts every hole first on a descending sort, which is the least
- * useful screen the data can produce.
- *
- * **`sign` is applied in here rather than to the result**, and that is why it is
- * a parameter rather than the caller's multiplication. Written the obvious way,
- * as `sign * compare(a, b)`, the constant this returns for a hole flips with the
- * direction and the holes lead a descending sort.
- */
 const compare = (left, right, sign) => {
     const leftMissing = left === null || left === undefined || left === '';
     const rightMissing = right === null || right === undefined || right === '';
@@ -159,13 +66,6 @@ const compare = (left, right, sign) => {
     }
     return (sign * text(left).localeCompare(text(right), undefined, { numeric: true, sensitivity: 'base' }));
 };
-/**
- * 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 const ordered = (rows, axes, { page, query, size, spec }) => {
     const matched = filter(rows, query, axes);
     const arranged = sort(matched, parse(spec), axes);