@fusion.dev/helix-headless 0.23.0 → 0.24.1

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

@@ -1,6 +1,7 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
-import type { HelixHeadlessTableColumn } from '../../table/column/table-column.js';
+import { type HelixHeadlessTableColumn } from '../../table/column/table-column.js';
+import '../../checkbox/index.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;
@@ -32,6 +33,25 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * right shape with nothing in it. That is the cost of the first paragraph: use
  * `helix-table` where the served HTML has to carry the values.
  *
+ * **`selectable` adds a column of checkboxes, keyed on `row-key`.** A row is
+ * selected by its identity rather than its position, so a selection survives a
+ * sort, a filter and a page. `selected` is the chosen keys, comma separated, the
+ * shape Listbox uses for a multiple choice, and like `sort` it is controlled
+ * when set and seeded by `default-selected`. The box in the heading selects every
+ * row in the result, across pages, and shows a dash while only some are chosen.
+ * Choosing one of many, rather than several, is opening a row, and that is a
+ * link or a button in a cell rather than a selection.
+ *
+ * **A reader can size and order the columns.** `resizable` on a column puts a
+ * separator on its edge; `reorderable` on the table puts a grip on each heading
+ * that has a `field`, moved by dragging or with the arrow keys. The order lands
+ * in `order` as fields, and the consumer's own markup is never rewritten: the
+ * table assigns the headings to its header in that order instead.
+ *
+ * **`csv()` hands back the result as text**: every row the filter lets through,
+ * in the order on screen, in the columns on screen. Saving it is the page's
+ * business, the same as any other file.
+ *
  * @since 0.1.0
  * @status experimental
  * @category data
@@ -44,17 +64,29 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  *
  * @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 {HelixReorderEvent} helix-reorder - Fired when a reader asks for the columns in another order, with every field in the new one, and cancelable.
+ * @event {HelixSelectEvent} helix-select - Fired when a reader changes which rows are selected, with every selected key comma separated, and cancelable.
  * @event {HelixSortEvent} helix-sort - Fired when a reader asks for a different order, and cancelable.
  *
  * @csspart after - The room the rows below the window would have taken. Windowed only.
  * @csspart before - The room the rows above the window would have taken. Windowed only.
  * @csspart cell - One cell.
+ * @csspart checkbox - A row's checkbox, or the one in the heading that selects them all.
+ * @csspart checkbox-box - The frame the checkbox's input is painted as.
+ * @csspart checkbox-control - The checkbox's input.
+ * @csspart checkbox-feedback - Forwarded from the checkbox, and never drawn here.
+ * @csspart checkbox-field - The row the checkbox's box sits in.
+ * @csspart checkbox-hint - Forwarded from the checkbox, and never drawn here.
+ * @csspart checkbox-label - Forwarded from the checkbox; the label is spoken, not shown.
+ * @csspart checkbox-mark - The tick, or the dash while some rows are selected.
  * @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 select - The cell holding a row's checkbox.
+ * @csspart select-all - The heading holding the checkbox that selects every row.
  * @csspart table - The grid.
  * @csspart toolbar - The region above the grid.
  *
@@ -75,6 +107,10 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * Query to open with, where nothing declared one.
      */
     defaultFilter: string;
+    /**
+     * Column order to open with, where nothing declared one.
+     */
+    defaultOrder: string;
     /**
      * Page to open on, where nothing declared one.
      */
@@ -83,6 +119,10 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * Page size to open with, where nothing declared one.
      */
     defaultPageSize: number;
+    /**
+     * Keys to open with selected, comma separated, where nothing declared any.
+     */
+    defaultSelected: string;
     /**
      * Order to open on, where nothing declared one.
      */
@@ -107,16 +147,9 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get sort(): string;
     set sort(next: string);
     /**
-     * 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.
+     * Accessible name for the grid.
      */
-    key: string;
+    label: string;
     /**
      * What the rows are narrowed to, as one query across every column.
      *
@@ -127,9 +160,16 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get filter(): string;
     set filter(next: string);
     /**
-     * Accessible name for the grid.
+     * 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.
      */
-    label: string;
+    mode: 'client' | 'server';
     /**
      * The page on show, from 1.
      *
@@ -140,16 +180,38 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get page(): number;
     set page(next: number);
     /**
-     * Whether this element does the work or asks the consumer to.
+     * Whether a reader may move the columns.
      *
-     * `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.
+     * Each heading with a `field` gets a grip, dragged along the header or moved a
+     * place at a time with the arrow keys once it has focus.
      */
-    mode: 'client' | 'server';
+    reorderable: boolean;
+    /**
+     * The columns' order, as their fields separated by spaces.
+     *
+     * A reader's move fires `helix-reorder` first, and refusing it leaves the
+     * columns where they were, which is how a consumer who stores the order takes
+     * the decision. `default-order` seeds an order this element then owns. A field not named
+     * keeps its place after the named ones, and a column with no field never
+     * moves.
+     */
+    get order(): string;
+    set order(next: string);
+    /**
+     * 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.
+     *
+     * **`row-key` and not `key`**, which is what it was called until selection
+     * needed it from React: `key` is reserved there, and a JSX `key` never reaches
+     * the element, so a React page could not tell the table which field a row is.
+     */
+    rowKey: string;
     /**
      * The whole result, in the order it arrived.
      *
@@ -162,6 +224,24 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * holds and reordering it under them is a mutation they did not ask for.
      */
     rows: readonly DataRow[];
+    /**
+     * Whether a reader may select rows, with a column of checkboxes.
+     *
+     * Wants `row-key`: a selection is a set of identities, and without one the rows
+     * are known by their place in the result, which a sort changes.
+     */
+    selectable: boolean;
+    /**
+     * The keys of the selected rows, comma separated.
+     *
+     * A string rather than an array, so it is an attribute a server writes and a
+     * framework's hydration keeps, and the shape a multiple Listbox already uses.
+     * A key holding a comma cannot be told apart from two keys, which is the
+     * price of the shape. A reader's choice fires `helix-select` first, and
+     * refusing it leaves the selection as it was.
+     */
+    get selected(): string;
+    set selected(next: string);
     /**
      * How many rows a page holds. Zero is every row, which is what "no paging" means.
      *
@@ -217,6 +297,14 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private pageState;
     private pageSizeState;
     private paginatedState;
+    private orderState;
+    private selectedState;
+    /** The order while a grip is being dragged, before anybody has been asked. */
+    private dragOrder;
+    /** The column a grip is dragging, and the pointer doing it. */
+    private dragging;
+    /** Said once, so a table that re-renders does not repeat it. */
+    private warnedAboutKey;
     private readonly virtualize;
     /**
      * The rows in the shadow tree, each with the row of the page it drew.
@@ -259,6 +347,16 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private windowOf;
     /** The columns declared as children, in the order they are written. */
     get tableColumns(): HelixHeadlessTableColumn[];
+    /**
+     * The columns in the order a reader arranged them.
+     *
+     * The ones with a field are put in `order`'s order, those it does not name
+     * after them in the order they were written, and a column with no field stays
+     * where it was written: it has nothing to be named by.
+     */
+    get orderedColumns(): HelixHeadlessTableColumn[];
+    /** The fields in the order on screen. */
+    private get fields();
     /** The columns reduced to what the ordering needs. */
     private get axes();
     /** The track list, from the columns if there are any. */
@@ -337,6 +435,47 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * consumer refuses the local reorder, fetches, and hands back a new set.
      */
     private requestSort;
+    /** Asks for the columns in a different order, as every field in the new one. */
+    private requestOrder;
+    /** Asks for a different set of selected rows. */
+    private requestSelected;
+    /** The keys selected now. */
+    private get chosen();
+    /**
+     * A row's identity: its `row-key` field, or its place in the whole result.
+     *
+     * The place is a fallback that is right only while nothing reorders, and a
+     * selection outlives an order, so `selectable` without a `row-key` says so once.
+     */
+    private keyOf;
+    /**
+     * Every key the box in the heading answers for: the whole result in `client`
+     * mode, across every page, and the page it was handed in `server` mode, which
+     * is all it holds.
+     */
+    private get everyKey();
+    /** Ticks or clears one row, which the checkbox asked for and was refused. */
+    private readonly toggleRow;
+    /** Selects every row, or clears them all where every one already was. */
+    private readonly toggleAll;
+    /** Moves a column by some places among the ones that move. */
+    private moveColumn;
+    /**
+     * The result as CSV: every row the filter lets through, in the order on
+     * screen, in the columns on screen, headed by their headings.
+     *
+     * **Values, not cells.** A cell may be a template, a badge or a link, so each
+     * column gives its field's value, which is what a spreadsheet wants anyway.
+     * A column with no field has no value and is left out. In `server` mode this
+     * is the page it holds, which is all it can know.
+     *
+     * **A text value that a spreadsheet would run is quoted as text.** A cell
+     * opening with `=`, `+`, `-` or `@` is a formula to a spreadsheet, and a
+     * result is often something a reader did not write: those values gain a
+     * leading apostrophe, the mark spreadsheets read as "this is text". Numbers are
+     * left alone, so a negative one stays a number.
+     */
+    csv(): string;
     /** Asks for a different query. */
     private requestFilter;
     /** Asks for a different page. */
@@ -402,6 +541,13 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     /** Columns arrive from the light DOM, which changes no property here. */
     private readonly handleSlotChange;
     private renderCell;
+    /**
+     * A checkbox, named for what it chooses, whose change the table takes.
+     *
+     * Refused and re-asked rather than left to tick itself: the selection is the
+     * table's, so the box only ever shows what `selected` says.
+     */
+    private renderCheckbox;
     private renderRows;
     /**
      * A row's place in the whole result, counting the header as row 1.
@@ -439,6 +585,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private renderSpacer;
     /** The controller owns the geometry; this is only what tells it to look again. */
     private readonly handleScroll;
+    /** The heading of the checkbox column, which selects the whole result. */
+    private renderSelectAll;
     protected render(): TemplateResult;
     /**
      * Listens on the host, not on the slot the columns are assigned to.
@@ -457,10 +605,34 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     connectedCallback(): void;
     disconnectedCallback(): void;
-    /** A click on a sortable heading. */
+    /**
+     * A click on a sortable heading, anywhere but its grip or its edge.
+     *
+     * Enter and Space arrive here too, as the click the heading's sort button
+     * makes of them, so a keyboard needs nothing of its own.
+     */
     private readonly handleHeadClick;
-    /** The same on Enter and Space, since a heading that sorts is a control. */
-    private readonly handleHeadKey;
+    /** Whether the event passed through a part of that name on its way here. */
+    private partIn;
+    /** The arrow keys on a grip move its column a place, along the writing direction. */
+    private readonly handleGripKey;
+    /**
+     * A grip taken hold of: the headings follow the pointer and the order is asked
+     * for once it lets go.
+     *
+     * Previewed without an event, because a drag passes through a dozen orders on
+     * its way to the one the reader meant, and a consumer should hear the one.
+     */
+    private readonly handleGripDown;
+    private readonly handleGripMove;
+    private readonly handleGripUp;
+    private readonly handleGripCancel;
+    private stopDrag;
+    /**
+     * A column asked for a width. The column keeps its own, so all this does is
+     * draw the grid again once it has, a microtask on, when the width has landed.
+     */
+    private readonly handleResize;
     private columnFrom;
     /**
      * The composed pagination's request, relayed as this element's own.