@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,392 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+import type { HelixHeadlessTableColumn } from '../../table/column/table-column.js';
+import '../../pagination/index.js';
+import { type DataRow } from './order.js';
+declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
+/**
+ * @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>
+ * ```
+ *
+ * This is the resolution of a deferral rather than a new idea. `helix-table`
+ * takes rows as markup and is the right component for a table of twelve things
+ * a person wrote out; the repeated `page`, `page-size` and `total` attributes on
+ * the three pagination elements are placeholders whose own comments name the fix
+ * as "a data table composing a pagination inside itself", and `helix-table`
+ * already carried `@aliases DataTable`: a name claimed and not kept.
+ *
+ * **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: this family has
+ * already shipped one source of truth for columns splitting into two, nothing
+ * checked that they agreed, 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.
+ */
+export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base {
+    /**
+     * 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 shadowRootOptions: ShadowRootInit;
+    /**
+     * 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.
+     */
+    rows: readonly DataRow[];
+    /**
+     * 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.
+     */
+    key: string;
+    /**
+     * 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.
+     */
+    mode: 'client' | 'server';
+    /**
+     * 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.
+     */
+    total: number;
+    /**
+     * Accessible name for the grid.
+     */
+    label: string;
+    /**
+     * 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(): string;
+    set sort(next: string);
+    /**
+     * Order to open on, where nothing declared one.
+     */
+    defaultSort: string;
+    /**
+     * 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(): string;
+    set filter(next: string);
+    /**
+     * Query to open with, where nothing declared one.
+     */
+    defaultFilter: string;
+    /**
+     * 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(): number;
+    set page(next: number);
+    /**
+     * Page to open on, where nothing declared one.
+     */
+    defaultPage: number;
+    /**
+     * 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(): number;
+    set pageSize(next: number);
+    /**
+     * Page size to open with, where nothing declared one.
+     */
+    defaultPageSize: number;
+    /**
+     * 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(): boolean;
+    set paginated(next: boolean);
+    private sortState;
+    private filterState;
+    private pageState;
+    private pageSizeState;
+    private paginatedState;
+    /** The columns declared as children, in the order they are written. */
+    get tableColumns(): HelixHeadlessTableColumn[];
+    /** The columns reduced to what the ordering needs. */
+    private get axes();
+    /** The track list, from the columns if there are any. */
+    private get template();
+    /**
+     * 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.
+     */
+    private static readonly COMFORTABLE;
+    /** Said once per element, so a table that re-renders does not repeat it. */
+    private warnedAboutSize;
+    /**
+     * 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 considered and refused**, which is worth recording because
+     * it is the obvious answer. This element already has two: `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
+     * mechanism 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. See #326.
+     *
+     * So the gap was never the capability, it was that nothing said which of the
+     * two to reach for. 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.
+     */
+    private warnIfCrowded;
+    /**
+     * 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.
+     */
+    private get view();
+    /** How many pages the result makes, which is at least one even when empty. */
+    private get pages();
+    /**
+     * 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`.
+     */
+    private get matched();
+    /** Emptiness is a fact about the data here, not about slotted children. */
+    protected get hasRows(): boolean;
+    /**
+     * 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.
+     */
+    private requestSort;
+    /** Asks for a different query. */
+    private requestFilter;
+    /** Asks for a different page. */
+    private requestPage;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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: string): boolean;
+    /**
+     * 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.
+     */
+    private assign;
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * Says on the toolbar and the footer whether anything is in them.
+     *
+     * **The stylesheet used to ask, and could not.** It read
+     * `[part="toolbar"]:has(> slot:not(:has(*)))`, which is two faults at once:
+     * `:has()` may not be nested inside `:has()`, so the selector failed to parse
+     * and the whole rule was 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. A table with no toolbar paid the gap
+     * above the grid for one that was not there.
+     */
+    private markEmpty;
+    /**
+     * 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.
+     */
+    private markRegion;
+    protected updated(changed: PropertyValues): void;
+    /** Columns arrive from the light DOM, which changes no property here. */
+    private readonly handleSlotChange;
+    private renderCell;
+    private renderRows;
+    /**
+     * 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.
+     */
+    private rowIndex;
+    protected render(): TemplateResult;
+    /**
+     * 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, and the same trust in the
+     * flattened tree could as easily have gone the other way.
+     *
+     * 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(): void;
+    disconnectedCallback(): void;
+    /** A click on a sortable heading. */
+    private readonly handleHeadClick;
+    /** The same on Enter and Space, since a heading that sorts is a control. */
+    private readonly handleHeadKey;
+    private columnFrom;
+    /**
+     * 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.
+     */
+    private readonly handleNavigate;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-data-table': HelixHeadlessDataTable;
+    }
+}
+export {};