@fusion.dev/helix-headless 0.142.0 → 0.143.0

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

@@ -42,6 +42,21 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  *
  * To act on a single row, such as opening it, put a link or a button in a cell.
  *
+ * The grid is one tab stop, and the arrow keys move between its cells, the
+ * headings included:
+ *
+ * - The arrow keys move one cell, and Home and End to the ends of the row.
+ * - Control with Home or End moves to the first or the last cell of the grid.
+ * - Page Up and Page Down move by the rows that fit in view.
+ * - Enter or F2 moves into the cell's controls, and Escape moves back to the
+ *   cell. Tab moves between the controls of one cell.
+ * - Enter or Space on a sortable heading sorts by it, and Space on a row of a
+ *   `selectable` table selects it.
+ *
+ * The controls inside the cells leave the tab order, so Tab moves past the
+ * whole grid. A windowed table keeps the row holding focus drawn while the
+ * rest scroll away.
+ *
  * People can resize and reorder 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 new order
@@ -67,11 +82,16 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * @slot footer - Content below the grid. It replaces the built-in pagination.
  * @slot toolbar - Content above the grid, such as a search field or actions.
  *
+ * @event {HelixActivateEvent} helix-activate - Fired after the page changes, with the new page as a string in `detail.value`.
  * @event {HelixFilterEvent} helix-filter - The search query is about to change. Cancelable: cancel it to keep the current query.
+ * @event {HelixFilteredEvent} helix-filtered - Fired after the search query changes, with the new query.
  * @event {HelixNavigateEvent} helix-navigate - Another page was requested. Cancelable: cancel it to stay on the current page.
- * @event {HelixReorderEvent} helix-reorder - The columns were moved. The event carries every field in the new order. Cancelable: cancel it to keep the current order.
- * @event {HelixSelectEvent} helix-select - The selection changed. The event carries every selected key, separated by commas. Cancelable: cancel it to keep the current selection.
+ * @event {HelixReorderEvent} helix-reorder - The columns are about to move. The event carries every field in the new order. Cancelable: cancel it to keep the current order.
+ * @event {HelixReorderedEvent} helix-reordered - Fired after the columns move, with every field in the new order.
+ * @event {HelixSelectEvent} helix-select - The selection is about to change. The event carries every selected key, separated by commas. Cancelable: cancel it to keep the current selection.
+ * @event {HelixSelectedEvent} helix-selected - Fired after the selection changes, with every selected key, separated by commas.
  * @event {HelixSortEvent} helix-sort - A different sort order was requested. Cancelable: cancel it to keep the current order.
+ * @event {HelixSortedEvent} helix-sorted - Fired after the sort order changes, with the new order.
  *
  * @csspart after - The space that stands in for the rows below the window. Only while `windowed`.
  * @csspart before - The space that stands in for the rows above the window. Only while `windowed`.
@@ -176,6 +196,11 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     get filter(): string;
     set filter(next: string);
+    /**
+     * The built-in pagination's name for a gap in its run of pages. `{page}` is
+     * replaced with the page it jumps to.
+     */
+    gapLabel: string;
     /**
      * The grid's name, read by screen readers.
      */
@@ -192,6 +217,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * inverts the data flow.
      */
     mode: 'client' | 'server';
+    /** The built-in pagination's name for the button that moves forward a page. */
+    nextLabel: string;
     /**
      * The column order, as field names separated by spaces.
      *
@@ -212,6 +239,11 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     get page(): number;
     set page(next: number);
+    /**
+     * The built-in pagination's name for one page. `{page}` and `{pages}` are
+     * replaced with the page number and the page count.
+     */
+    pageLabel: string;
     /**
      * The number of rows on a page. `0` shows every row, with no paging.
      *
@@ -233,6 +265,10 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     get paginated(): boolean;
     set paginated(next: boolean);
+    /** The name of the built-in pagination's navigation landmark. */
+    paginationLabel: string;
+    /** The built-in pagination's name for the button that moves back a page. */
+    previousLabel: string;
     /**
      * Lets users reorder the columns.
      *
@@ -240,6 +276,13 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * place at a time with the arrow keys once it has focus.
      */
     reorderable: boolean;
+    /** What screen readers hear when a search leaves one row. `{count}` is the count. */
+    resultLabel: string;
+    /**
+     * What screen readers hear when a search leaves any other number of rows.
+     * `{count}` is the count.
+     */
+    resultsLabel: string;
     /**
      * The field that identifies each row.
      *
@@ -274,6 +317,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * are known by their place in the result, which a sort changes.
      */
     selectable: boolean;
+    /** The name of the checkbox in the heading that selects every row. */
+    selectAllLabel: string;
     /**
      * The keys of the selected rows, separated by commas.
      *
@@ -290,12 +335,18 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * rows are chosen.
      */
     selectedLabel: string;
+    /**
+     * The name of a row's checkbox. `{row}` is replaced with the row's value in
+     * the first column that has a field, or with its key.
+     */
+    selectRowLabel: string;
     /**
      * The sort 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.
+     * A reader's click on a sortable heading fires `helix-sort` first, and
+     * refusing it leaves the order as it was. To own the order yourself, refuse
+     * the event and set this to the order you chose. `default-sort` seeds an
+     * order this element then owns.
      */
     get sort(): string;
     set sort(next: string);
@@ -343,6 +394,25 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private paginatedState;
     private orderState;
     private selectedState;
+    /**
+     * The row holding the grid's tab stop: `-1` for the headings, otherwise a
+     * row of the page counted from 0. Unset until a reader moves, when the stop
+     * rests on the first row, or on the headings where there is none.
+     */
+    private activeRow;
+    /** The column holding the grid's tab stop, the checkbox column counted. */
+    private activeColumn;
+    /**
+     * The key of the row holding the tab stop, so a sort or a filter keeps the
+     * stop on the row a reader was on. Only kept while `row-key` is set.
+     */
+    private activeKey;
+    /** Whether the next render should move focus to the active cell. */
+    private focusWanted;
+    /** The page as last drawn, for the keys to count rows against between renders. */
+    private drawnPage;
+    /** The grid's size as the last render counted it, for the internals. */
+    private counts;
     /** 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. */
@@ -387,8 +457,30 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     private held;
     private arrange;
-    /** The part of a page the reader can see, which is every row when not windowed. */
+    /**
+     * The part of a page the reader can see, which is every row when not
+     * windowed, each with its place in the page.
+     *
+     * **The row holding the tab stop is drawn wherever the window is.** A row
+     * that scrolled out took the focus inside it to the body, and a grid whose
+     * one tab stop is not drawn has no tab stop at all. It is drawn beside the
+     * window, on the side it belongs, and the spacer on that side gives up its
+     * room, so every other row stays where it was.
+     */
     private windowOf;
+    /** The row drawn outside the window to keep the tab stop, if there is one. */
+    private keptRow;
+    /** What a row is known by between renders: its `row-key`, or its place in the page. */
+    private rowKeyOf;
+    /**
+     * The row holding the tab stop in this page: the row with the key it was
+     * on, where `row-key` says, and otherwise the same place, held to the page.
+     */
+    private currentRow;
+    /** How many cells a row has: the checkbox and every drawn column. */
+    private get width();
+    /** The column holding the tab stop, held to the row's width. */
+    private get currentColumn();
     /** The columns declared as children, in the order they are written. */
     get tableColumns(): HelixHeadlessTableColumn[];
     /**
@@ -545,8 +637,12 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private get everyKey();
     /** Ticks or clears one row, which the checkbox asked for and was refused. */
     private readonly toggleRow;
+    /** Asks for one row to be chosen or let go. */
+    private chooseRow;
     /** Selects every row, or clears them all where every one already was. */
     private readonly toggleAll;
+    /** Asks for every row, or for none where every one already was. */
+    private chooseAll;
     /**
      * Moves a column by some places among the ones that move and are drawn.
      *
@@ -603,6 +699,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private heardSort;
     /** The selection last heard, for the same reason. */
     private heardSelected;
+    /** The search last heard, for the same reason. */
+    private heardFilter;
     /**
      * What the table says after a sort or a change to the chosen rows.
      *
@@ -676,8 +774,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * 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.
      *
-     * A window is the second offset and stacks on the page: with both on, row one
-     * of the window is the page's start plus how far down the page it begins.
+     * `within` is the row's place in the page, which already counts the window.
      */
     private rowIndex;
     /**
@@ -690,8 +787,6 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private get placement();
     /** The signature the recorded heights were measured against. */
     private measuredAgainst;
-    /** Where the window begins in the page, which is the top when there is none. */
-    private get windowStart();
     /**
      * The room the rows outside the window would have taken.
      *
@@ -731,6 +826,59 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * makes of them, so a keyboard needs nothing of its own.
      */
     private readonly handleHeadClick;
+    /**
+     * The cell at a place in the grid. The headings are row `-1`, the rows of
+     * the page count from 0, and the checkbox column, where there is one, is
+     * column 0.
+     */
+    private cellAt;
+    /** The cell an event came from or through, and its place in the grid. */
+    private placeOf;
+    /**
+     * The controls inside a cell, in order: what Enter and F2 move into, and
+     * what Tab moves between while focus is in the cell.
+     */
+    private controlsIn;
+    /**
+     * Takes the controls a consumer's `cell` drew out of the tab order, so the
+     * grid stays one tab stop. They are reached with Enter or F2.
+     */
+    private quietControls;
+    /** Moves the tab stop to a cell, and focus with it on the next render. */
+    private moveTo;
+    /** How many rows Page Up and Page Down move: those that fit in view, less one. */
+    private pageStep;
+    /** How tall the headings are, which stick over the rows in a windowed table. */
+    private headHeight;
+    /** Whether focus is on a cell of the grid, or inside one. */
+    private gridHasFocus;
+    /** Whether focus was in the grid before this render, for `placeFocus` to keep it there. */
+    private hadFocus;
+    /**
+     * Focuses the cell holding the tab stop, where a key asked to move there or
+     * a render took focus away from the grid.
+     *
+     * **A render can take focus away**: a sort moves the row elements, and a
+     * moved element loses focus to the body. Put back on the cell the stop is on,
+     * which follows the row by its key.
+     */
+    private placeFocus;
+    /** A cell, or a control inside one, took focus: the tab stop moves there. */
+    private readonly handleFocusIn;
+    /**
+     * The grid's keys, on a cell and inside one.
+     *
+     * On a cell, the arrows, Home, End, Page Up and Page Down move between
+     * cells, and Enter, Space and F2 act on it. Inside a cell the control has the
+     * keys, apart from Escape and F2, which go back to the cell, and Tab, which
+     * moves between the cell's controls. A key a control already handled is left
+     * alone.
+     */
+    private readonly handleGridKey;
+    /** Enter, Space and F2 on a cell. */
+    private activate;
+    /** The keys the grid takes while focus is on a control inside a cell. */
+    private handleControlKey;
     /** 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. */
@@ -753,6 +901,12 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     private readonly handleResize;
     private columnFrom;
+    /**
+     * The composed pagination's notification, stopped for the reason its
+     * request is: this element sends its own `helix-activate` once its own page
+     * has moved, and one move is one event.
+     */
+    private readonly stopPageNotification;
     /**
      * The composed pagination's request, relayed as this element's own.
      *