@fusion.dev/helix-headless 0.148.0 → 0.149.1

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

@@ -94,6 +94,19 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * is written to `order` as a list of fields. Your markup is not rewritten: the
  * table assigns the headings to its header in that order.
  *
+ * **`reorderable-rows` lets people move rows.** A column of grips leads each
+ * row, named by `move-row-label`. Drag a grip to move its row, and the table
+ * scrolls near an edge. Or press Space or Enter on a grip, or click it, to pick
+ * up its row, move it with Down and Up, Home and End, and press Space or Enter
+ * again to drop it. A click on another row drops it there, and Escape puts it
+ * back. The table says each step in its `live` region. A drop sends
+ * `helix-before-reorder`, which you can refuse, and then `helix-reorder` with
+ * `kind` set to `row`, whose `keys` hold every key of `rows` in the new order.
+ * **You move the rows**: set `rows` to the new order, and the table draws it.
+ * Set `row-key`, so a row is known by its key once it has moved. The grips do
+ * nothing while a `sort` is set, since the sort decides the order, and a tree
+ * grid draws none.
+ *
  * `csv()` returns the result as text: every row that passes the filter, in the
  * order and the columns on screen. Saving the file is up to you.
  *
@@ -114,12 +127,13 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * @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 {HelixBeforeReorderEvent} helix-before-reorder - A row is about to move, with `reorderable-rows`. The event carries every row's key in the new order. Cancelable: cancel it to keep the row where it is.
  * @event {HelixExpandEvent} helix-expand - Fired after a row opens or closes, with every open row's key, separated by commas, which `expanded` also holds.
  * @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 {HelixLoadMoreEvent} helix-load-more - Fired when a reader asks for more rows, by the `load-more` row's button or by scrolling a `windowed` table near its end.
  * @event {HelixNavigateEvent} helix-navigate - Another page was requested. Cancelable: cancel it to stay on the current page.
- * @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 {HelixReorderEvent} helix-reorder - The columns are about to move, with `kind` set to `column` and every field in the new order. Cancelable: cancel it to keep the current order. For a row, with `kind` set to `row`, it follows `helix-before-reorder`, and you set `rows` to the order in `keys`.
  * @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.
@@ -142,8 +156,10 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * @csspart checkbox-mark-checked - Added to `checkbox-mark` while its box is checked.
  * @csspart checkbox-mark-dash - Added to `checkbox-mark` while it draws the dash, which it keeps until its box is checked.
  * @csspart checkbox-mark-indeterminate - Added to `checkbox-mark` while only some rows are selected.
+ * @csspart drag-preview - A copy of the row a pointer drags by its grip, which follows the pointer in the top layer until the row is let go, with `reorderable-rows`. A column's grip moves the column itself. Hidden from assistive technology.
  * @csspart empty - Shown when there are no rows, because none arrived or the filter matches none. While rows are loading, the `loading` part is shown in its place.
  * @csspart footer - The region below the grid.
+ * @csspart grip-head - The heading over the row grips, with `reorderable-rows`.
  * @csspart head - The row that holds the column headings. It is `display: contents`, so it takes no space.
  * @csspart live - A copy of the empty and loading messages, which screen readers announce when they change. Visually hidden in the styled tier.
  * @csspart loading - Shown while the rows are loading.
@@ -164,6 +180,12 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * @csspart pagination-previous - The pagination's button that goes back one page.
  * @csspart pagination-status - The pagination's text that says which page is shown, in `compact`.
  * @csspart row - One row of data.
+ * @csspart row-dragging - Added to `row` while it is being moved.
+ * @csspart row-drop-after - Added to `row` when the row being moved goes after it.
+ * @csspart row-drop-before - Added to `row` when the row being moved goes before it.
+ * @csspart row-grip - The cell that holds a row's grip, with `reorderable-rows`.
+ * @csspart row-grip-button - The button that moves a row.
+ * @csspart row-grip-mark - The icon on a row's grip.
  * @csspart select - The cell that holds a row's checkbox.
  * @csspart select-all - The heading that holds the checkbox that selects every row.
  * @csspart select-selected - Added to `select` in a selected row.
@@ -189,8 +211,24 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * same reason.
      */
     static shadowRootOptions: ShadowRootInit;
-    /** The word for an ascending sort, in `sorted-label`. */
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-data-table': { nextLabel: 'Nächste Seite' } })`.
+     */
+    static words: string;
+    /**
+     * The word for an ascending sort, in a `sorted-label` that writes `{order}`.
+     *
+     * @deprecated Write the whole sentence for each order in `sorted-label`, with
+     * `{direction, select, ascending {...} descending {...} other {...}}`.
+     * Removed in the next major version.
+     */
     ascendingLabel: string;
+    /**
+     * What screen readers hear when a held row is put back, or a move is
+     * refused, with `reorderable-rows`.
+     */
+    canceledLabel: string;
     /**
      * The field that holds a row's child rows, as an array. Set it, and `row-key`,
      * and the grid becomes a tree grid.
@@ -229,8 +267,16 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * The starting sort order, used until `sort` is set.
      */
     defaultSort: string;
-    /** The word for a descending sort, in `sorted-label`. */
+    /**
+     * The word for a descending sort, in a `sorted-label` that writes `{order}`.
+     *
+     * @deprecated Write the whole sentence for each order in `sorted-label`, with
+     * `{direction, select, ascending {...} descending {...} other {...}}`.
+     * Removed in the next major version.
+     */
     descendingLabel: string;
+    /** What screen readers hear when a row is dropped, with `reorderable-rows`. */
+    droppedLabel: string;
     /**
      * The estimated height of a row before it is drawn, in pixels.
      *
@@ -275,6 +321,12 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     loadMore: boolean;
     /** The words on the button in the `more` row. */
     loadMoreLabel: string;
+    /**
+     * The locale the words, plural forms, and numbers are in, as a BCP 47 tag
+     * such as `pl`. Empty reads the nearest `lang`, then the browser's
+     * language. The built-in pagination speaks it too.
+     */
+    locale: string;
     /**
      * Where filtering, sorting, and paging happen. `client` does them in the
      * table, and `server` leaves them to your code.
@@ -287,6 +339,17 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * inverts the data flow.
      */
     mode: 'client' | 'server';
+    /**
+     * What screen readers hear each time a key moves a held row, with
+     * `reorderable-rows`. `{name}` is the row's name, `{position}` the place it
+     * would go, counting from 1, and `{count}` the number of rows on the page.
+     */
+    movedLabel: string;
+    /**
+     * The name of a row's grip, with `reorderable-rows`. `{row}` is replaced with
+     * the row's name.
+     */
+    moveRowLabel: string;
     /** The built-in pagination's name for the button that moves forward a page. */
     nextLabel: string;
     /**
@@ -337,6 +400,11 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     set paginated(next: boolean);
     /** The name of the built-in pagination's navigation landmark. */
     paginationLabel: string;
+    /**
+     * What screen readers hear when a key or a click picks up a row, with
+     * `reorderable-rows`. `{name}` is the row's name.
+     */
+    pickedUpLabel: string;
     /** The built-in pagination's name for the button that moves back a page. */
     previousLabel: string;
     /**
@@ -346,13 +414,28 @@ 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.
+     * Lets people move rows, by a grip that leads each row. The table moves no
+     * row itself: set `rows` to the order `helix-reorder` carries.
+     */
+    reorderableRows: boolean;
+    /**
+     * What screen readers hear when a search leaves one row, where
+     * `results-label` should not say it. `{count}` is the count.
+     *
+     * @deprecated Write every form in `results-label`, as `{count, plural, one
+     * {# result} other {# results}}`. Removed in the next major version.
+     */
+    resultLabel?: string;
+    /**
+     * What screen readers hear when a search narrows the rows. `{count}` is how
+     * many rows are left, written in the locale, and each language writes the
+     * forms it has: `{count, plural, one {# wiersz} few {# wiersze} many
+     * {# wierszy} other {# wiersza}}`.
      */
     resultsLabel: string;
+    /** The name of the heading over the row grips, with `reorderable-rows`. */
+    rowGripsLabel: string;
     /**
      * The field that identifies each row.
      *
@@ -402,7 +485,9 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     set selected(next: string);
     /**
      * What screen readers hear when the chosen rows change. `{count}` is how many
-     * rows are chosen.
+     * rows are chosen, written in the locale, and a language that needs plural
+     * forms writes them: `{count, plural, one {# wybrany} few {# wybrane} many
+     * {# wybranych} other {# wybranego}}`.
      */
     selectedLabel: string;
     /**
@@ -422,7 +507,9 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     set sort(next: string);
     /**
      * What screen readers hear when the table is sorted. `{column}` is the
-     * column's heading and `{order}` is `ascending-label` or `descending-label`.
+     * column's heading and `{direction}` is `ascending` or `descending`, so each
+     * order has its whole sentence. `{order}` is the deprecated
+     * `ascending-label` or `descending-label`.
      */
     sortedLabel: string;
     /**
@@ -495,10 +582,24 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private shiftPressed;
     /** 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. */
-    private dragging;
+    /**
+     * A column dragged by its grip. The headings follow the pointer and the
+     * order is asked for once it lets go, so a consumer hears one order and not
+     * the dozen a drag passes through. The arrow keys on a grip move a column a
+     * place each, which `handleGripKey` does, so this only drags.
+     */
+    private readonly columnMoves;
+    /**
+     * A row moved by its grip, with `reorderable-rows`. The rows are the page's,
+     * so a drop asks the page to set them in the new order.
+     */
+    private readonly rowMoves;
+    /**
+     * The row drawn for a key on this page, or nothing for a row outside the
+     * window: the one kept drawn beside it for the tab stop is not where the
+     * row belongs.
+     */
+    private lineOf;
     /** Said once, so a table that re-renders does not repeat it. */
     private warnedAboutKey;
     private readonly virtualize;
@@ -577,8 +678,14 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * 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. */
+    /** How many cells a row has: the grip, the checkbox and every drawn column. */
     private get width();
+    /** Whether each row leads with a grip: `reorderable-rows`, in a table that is not a tree. */
+    private get rowGrips();
+    /** The column the checkboxes are in: the first, or the one after the grips. */
+    private get selectAt();
+    /** How many cells lead each row ahead of the columns: the grips and the checkboxes. */
+    private get lead();
     /** 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. */
@@ -591,6 +698,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * where it was written: it has nothing to be named by.
      */
     get orderedColumns(): HelixHeadlessTableColumn[];
+    /** The columns put in an order of fields, with the ones it does not name after them. */
+    private arrangeColumns;
     /**
      * The columns drawn: the arranged ones less any that are hidden.
      *
@@ -603,6 +712,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private get shownColumns();
     /** The fields in the order on screen. */
     private get fields();
+    /** The fields of the columns drawn, in the order on screen: what a grip moves among. */
+    private get shownFields();
     /** The columns reduced to what the ordering needs. */
     private get axes();
     /** The track list, from the columns if there are any. */
@@ -716,7 +827,10 @@ 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. */
+    /**
+     * Asks for the columns in a different order, as every field in the new one,
+     * with `field` the one that moved.
+     */
     private requestOrder;
     /** Asks for a different set of selected rows. */
     private requestSelected;
@@ -740,6 +854,33 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * Shift held it selects every row from the one last chosen.
      */
     private readonly toggleRow;
+    /**
+     * What a row is known by when it moves: its `row-key`, or its place in
+     * `rows`, which is the order `helix-reorder` gives back.
+     */
+    private moveKeyOf;
+    /** Each row's place in `rows`, kept while `rows` is the same array, for `moveKeyOf`. */
+    private rowPlaces;
+    /**
+     * Each drawn row's place in the page by its key, kept while the page is the
+     * same array, so a drag asks for a row's box without a search per row.
+     */
+    private pagePlaces;
+    /** What `pagePlaces` keeps. */
+    private pageKeyed;
+    /** A row's name: its row header's value, or its key where it has none. */
+    private rowName;
+    /**
+     * Asks the page to move a row: `helix-before-reorder`, which can refuse it,
+     * then `helix-reorder`, with every key of `rows` in the new order. A row a
+     * search hides keeps its place among the rest. Reports whether it stood.
+     */
+    private requestRowMove;
+    /**
+     * Says a step of a move in the live region. Emptied first, so the same
+     * words twice are heard twice, and filled a frame later.
+     */
+    private say;
     /** The keys of the rows on the page, in the order they are drawn. */
     private get pageKeys();
     /**
@@ -776,8 +917,6 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      * order and nothing on screen. A hidden column keeps its place among the rest.
      */
     private moveColumn;
-    /** Every field in order, with one taken out and put back beside another. */
-    private placed;
     /**
      * Returns the result as CSV: every row that matches the filter, in the order
      * and columns shown, under a line of the column headings.
@@ -826,6 +965,11 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     private heardSelected;
     /** The search last heard, for the same reason. */
     private heardFilter;
+    /**
+     * The sentence a sort is said in: `sorted-label` with the column, and the
+     * order both as `{direction}` and as the deprecated `{order}` word.
+     */
+    private sortSaid;
     /**
      * What the table says after a sort or a change to the chosen rows.
      *
@@ -938,6 +1082,16 @@ 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 cell that leads a row with its grip, with `reorderable-rows`.
+     *
+     * The cell takes focus, as every cell of the grid does, and Space or Enter
+     * on it picks up the row. The button inside is what a pointer and a screen
+     * reader press. `aria-disabled` while a sort decides the order.
+     */
+    private renderGrip;
+    /** The heading over the row grips, named by `row-grips-label`. */
+    private renderGripHead;
     /** The heading of the checkbox column, which selects the whole result. */
     private renderSelectAll;
     /**
@@ -1040,18 +1194,6 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     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.