@fusion.dev/helix-headless 0.147.0 → 0.149.0

package/dist/table/grid-controller.js

@@ -0,0 +1,299 @@
+import { deepActiveElement, deepContains, focusableElements, gridMove, inlineStep, pageRows, scrollingAncestor, scrollRoom, selectsAll, whenHydrated, } from '@fusion.dev/helix-core';
+const HEADS = { grip: 'grip-head', select: 'select-all' };
+const shown = (element) => {
+    const hidden = element.getAttribute('hidden');
+    return hidden === null || hidden === 'until-found';
+};
+export class TableGridController {
+    constructor(host, options) {
+        this.stopRow = undefined;
+        this.stopColumn = 0;
+        this.stopIndex = 0;
+        this.focusRow = undefined;
+        this.focusWanted = false;
+        this.pointing = false;
+        this.given = new Set();
+        this.handleKeydown = (event) => {
+            if (!this.options.on() || event.defaultPrevented || event.altKey) {
+                return;
+            }
+            const place = this.placeOf(event);
+            if (!place) {
+                return;
+            }
+            if (event.composedPath()[0] !== place.cell) {
+                this.handleControlKey(event, place);
+                return;
+            }
+            if (event.key === 'Tab') {
+                this.leave(event.shiftKey);
+                return;
+            }
+            if (selectsAll(event) && !event.shiftKey) {
+                if (this.options.selectAll()) {
+                    event.preventDefault();
+                }
+                return;
+            }
+            if (event.key === 'Enter' || event.key === ' ' || event.key === 'F2') {
+                if (event.key !== 'F2' && this.options.activate(place, event)) {
+                    event.preventDefault();
+                    return;
+                }
+                const first = event.key === ' ' ? undefined : this.controlsIn(place)[0];
+                if (first) {
+                    event.preventDefault();
+                    first.focus();
+                }
+                return;
+            }
+            const to = gridMove(event.key, place, { last: this.options.rows().length - 1, top: this.top, width: this.widthOf(place.row) }, {
+                control: event.ctrlKey || event.metaKey,
+                page: event.key.startsWith('Page') ? this.pageFrom(place.cell) : 1,
+                step: inlineStep(this.host, event.key),
+            });
+            if (!to) {
+                return;
+            }
+            event.preventDefault();
+            to.column = Math.max(0, Math.min(to.column, this.widthOf(to.row) - 1));
+            if (to.row !== place.row || to.column !== place.column) {
+                this.moveTo(to);
+            }
+        };
+        this.handleFocusIn = (event) => {
+            if (!this.options.on()) {
+                return;
+            }
+            const place = this.placeOf(event);
+            if (!place) {
+                return;
+            }
+            const from = event.relatedTarget;
+            const entering = !(from instanceof Node && deepContains(this.host, from));
+            if (entering && !this.pointing && event.composedPath()[0] !== place.cell) {
+                const stop = this.cellAt(this.current());
+                if (stop) {
+                    stop.focus();
+                    return;
+                }
+            }
+            this.focusRow = place.row === -1 ? undefined : this.options.rows()[place.row];
+            const at = this.current();
+            if (at.row !== place.row || at.column !== place.column) {
+                this.moveTo(place, false);
+            }
+        };
+        this.handleFocusOut = (event) => {
+            const to = event.relatedTarget;
+            if (to instanceof Node && !deepContains(this.host, to)) {
+                this.focusRow = undefined;
+            }
+        };
+        this.handlePointerDown = () => {
+            this.pointing = true;
+            setTimeout(() => {
+                this.pointing = false;
+            });
+        };
+        this.host = host;
+        this.options = options;
+        host.addController(this);
+    }
+    hostConnected() {
+        this.host.addEventListener('keydown', this.handleKeydown);
+        this.host.addEventListener('focusin', this.handleFocusIn);
+        this.host.addEventListener('focusout', this.handleFocusOut);
+        this.host.addEventListener('pointerdown', this.handlePointerDown);
+    }
+    hostDisconnected() {
+        this.host.removeEventListener('keydown', this.handleKeydown);
+        this.host.removeEventListener('focusin', this.handleFocusIn);
+        this.host.removeEventListener('focusout', this.handleFocusOut);
+        this.host.removeEventListener('pointerdown', this.handlePointerDown);
+    }
+    hostUpdate() {
+        const gone = this.stopRow;
+        const rows = this.options.rows();
+        if (!(gone instanceof Element) || rows.includes(gone)) {
+            return;
+        }
+        this.stopRow = rows[Math.min(this.stopIndex, rows.length - 1)];
+        const active = deepActiveElement();
+        if (this.focusRow === gone && (!active || active === document.body)) {
+            this.focusWanted = true;
+        }
+        this.focusRow = undefined;
+    }
+    get offset() {
+        return this.options.lead().length;
+    }
+    get top() {
+        return this.options.columns().length > 0 || this.offset > 0 ? -1 : 0;
+    }
+    cellsOf(row) {
+        return [...(row?.children ?? [])].filter(shown);
+    }
+    widthOf(row) {
+        const own = row === -1 ? this.options.columns().length : this.cellsOf(this.options.rows()[row]).length;
+        return this.offset + own;
+    }
+    cellAt({ column, row }) {
+        const lead = this.options.lead()[column];
+        if (row === -1) {
+            return lead
+                ? this.options.part(HEADS[lead])
+                : (this.options.columns()[column - this.offset]?.cellBox ?? null);
+        }
+        const line = this.options.rows()[row];
+        if (lead) {
+            return line?.shadowRoot?.querySelector(`[part~="${lead}"]`) ?? null;
+        }
+        return this.cellsOf(line)[column - this.offset] ?? null;
+    }
+    current() {
+        const found = this.stopRow === undefined || this.stopRow === 'head'
+            ? -1
+            : this.options.rows().indexOf(this.stopRow);
+        const row = this.stopRow === 'head' || found < 0 ? this.top : found;
+        const width = this.widthOf(row);
+        return { column: Math.max(0, Math.min(this.stopColumn, width - 1)), row };
+    }
+    isStop(place) {
+        const at = this.current();
+        return this.options.on() && at.row === place.row && at.column === place.column;
+    }
+    placeOf(event) {
+        const columns = this.options.columns();
+        const rows = this.options.rows();
+        for (const node of event.composedPath()) {
+            if (node === this.host) {
+                return undefined;
+            }
+            if (!(node instanceof HTMLElement)) {
+                continue;
+            }
+            const heading = columns.indexOf(node);
+            if (heading >= 0) {
+                const cell = node.cellBox;
+                return cell ? { cell, column: heading + this.offset, row: -1 } : undefined;
+            }
+            const part = node.getAttribute('part') ?? '';
+            const root = node.getRootNode();
+            for (const [column, lead] of this.options.lead().entries()) {
+                if (part === HEADS[lead] && root === this.host.shadowRoot) {
+                    return { cell: node, column, row: -1 };
+                }
+                if (part.split(' ').includes(lead) && rows.includes(root.host)) {
+                    return { cell: node, column, row: rows.indexOf(root.host) };
+                }
+            }
+            const parent = node.parentElement;
+            if (parent && rows.includes(parent) && shown(node)) {
+                const column = this.cellsOf(parent).indexOf(node);
+                return { cell: node, column: column + this.offset, row: rows.indexOf(parent) };
+            }
+        }
+        return undefined;
+    }
+    moveTo(place, focus = true) {
+        this.stopRow = place.row === -1 ? 'head' : this.options.rows()[place.row];
+        this.stopColumn = place.column;
+        this.focusWanted = focus;
+        this.host.requestUpdate();
+    }
+    mark() {
+        const on = this.options.on();
+        const at = this.current();
+        const lead = this.options.lead();
+        this.stopIndex = Math.max(0, at.row);
+        const columns = this.options.columns();
+        for (const [index, column] of columns.entries()) {
+            column.gridCell = on;
+            column.tabStop = on && at.row === -1 && at.column === index + this.offset;
+        }
+        for (const [index, line] of this.options.rows().entries()) {
+            const row = line;
+            if (row.isTableRow) {
+                const here = on && at.row === index;
+                whenHydrated(row, () => {
+                    row.gridCell = on;
+                    row.gripStop = here && lead[at.column] === 'grip';
+                    row.selectStop = here && lead[at.column] === 'select';
+                });
+            }
+            for (const [place, cell] of this.cellsOf(line).entries()) {
+                if ('isTableCell' in cell) {
+                    ;
+                    cell.gridCell = on;
+                }
+                if (!on) {
+                    continue;
+                }
+                const stop = at.row === index && at.column === place + this.offset ? 0 : -1;
+                if (cell.tabIndex !== stop || !cell.hasAttribute('tabindex')) {
+                    cell.tabIndex = stop;
+                }
+                this.given.add(cell);
+            }
+        }
+        for (const cell of this.given) {
+            if (!on || !cell.isConnected) {
+                if (!on) {
+                    cell.removeAttribute('tabindex');
+                }
+                this.given.delete(cell);
+            }
+        }
+    }
+    place() {
+        if (!this.focusWanted || !this.options.on()) {
+            return;
+        }
+        this.focusWanted = false;
+        this.cellAt(this.current())?.focus();
+    }
+    controlsIn(place) {
+        if (place.row === -1) {
+            return place.column < this.offset
+                ? []
+                : (this.options.columns()[place.column - this.offset]?.controls ?? []);
+        }
+        return place.column < this.offset ? [] : focusableElements(place.cell);
+    }
+    leave(back) {
+        const edge = this.options.part(back ? 'grid-start' : 'grid-end');
+        if (!edge) {
+            return;
+        }
+        edge.tabIndex = 0;
+        edge.addEventListener('focusout', () => {
+            edge.tabIndex = -1;
+        }, { once: true });
+        edge.focus({ preventScroll: true });
+    }
+    pageFrom(cell) {
+        const room = scrollRoom(scrollingAncestor(cell, { axis: 'y', overflowing: true }));
+        return pageRows(room, cell.getBoundingClientRect().height);
+    }
+    handleControlKey(event, place) {
+        if (event.key === 'Escape' || event.key === 'F2') {
+            event.preventDefault();
+            place.cell.focus();
+            return;
+        }
+        if (event.key !== 'Tab') {
+            return;
+        }
+        const origin = event.composedPath()[0];
+        const controls = this.controlsIn(place);
+        const at = controls.findIndex((one) => deepContains(one, origin));
+        const next = at >= 0 ? controls[at + (event.shiftKey ? -1 : 1)] : undefined;
+        if (next) {
+            event.preventDefault();
+            next.focus();
+            return;
+        }
+        this.leave(event.shiftKey);
+    }
+}

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

@@ -50,9 +50,48 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * 4. A chosen row takes `:state(selected)`, and a screen reader hears
  *    `selected-label` ("2 selected") from a polite region.
  *
- * Tab reaches each checkbox, and Space ticks it. For a grid a reader moves
- * through with the arrow keys, with typeahead and range selection, use
- * `DataTable`. To act on one row, put a link or a button in a cell.
+ * Tab reaches each checkbox, and Space ticks it. To act on one row, put a
+ * link or a button in a cell, or give the row an `href`.
+ *
+ * **Moving rows.** `reorderable` adds a column of grips before the checkboxes,
+ * under a heading named by `row-grips-label`.
+ *
+ * 1. Each row is known by its `value`, or by its place among the rows where it
+ *    has none, as for selecting. Give rows a `value` when they move, so a key
+ *    stays with its row.
+ * 2. A grip is a button named by `move-row-label` ("Move {row}") with the
+ *    words of the row's first cell. Drag it to move its row, and the page
+ *    scrolls near an edge. Or press it with Space, Enter, or a click to pick
+ *    the row up, move it with Up, Down, Home, and End, and press it again to
+ *    drop it. A click on another row drops it there, and Escape puts it back.
+ * 3. `helix-before-reorder` asks first, and `helix-reorder` follows with
+ *    `keys`, every row's key in the new order. **You move the rows**: the
+ *    table moves no element of yours, and focus goes back to the moved row's
+ *    grip once you have.
+ * 4. Each step is said in the table's live region, in words you can change:
+ *    `picked-up-label`, `moved-label`, `dropped-label`, and `canceled-label`.
+ *    The grips do nothing while a sort is set.
+ *
+ * **A grid.** `grid` makes the table one tab stop that the arrow keys move
+ * through cell by cell, the headings included, as React Aria's table is. The
+ * table is then a `grid` and each value a `gridcell`, and the table gives
+ * every cell a `tabindex` so focus can rest on it: set `grid` only where the
+ * cells may carry one. For typeahead and range selection, use `DataTable`.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Right, Left | Moves one cell along the row. Left moves on, on a right-to-left page. |
+ * | Down, Up | Moves one row, the headings included. |
+ * | Home, End | Moves to the first or the last cell of the row. |
+ * | Control with Home or End | Moves to the first or the last cell of the table. |
+ * | Page Down, Page Up | Moves by the rows that fit in view. |
+ * | Enter, F2 | Moves into the cell's links and controls. Escape or F2 moves back to the cell, and Tab moves between the controls of one cell. |
+ * | Enter on a cell of a row with `href` | Follows the row's link. |
+ * | Enter, Space on a sortable heading | Sorts by the column. |
+ * | Space on a row, Enter or Space on its checkbox cell | Selects the row, in a `selectable` table. |
+ * | Enter or Space on a grip cell | Picks the row up, or drops it, in a `reorderable` table. Up, Down, Home, and End move a row picked up, and Escape puts it back. |
+ * | Control or Command with A | Selects every row, in a `selectable` table. |
+ * | Tab | Leaves the table. |
  *
  * The CSS custom properties listed for this component are written by it and
  * read by the stylesheet that draws it. Do not set them. Each holds a number
@@ -68,6 +107,8 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * @slot - The table's rows.
  * @slot heading - Words that name the table, shown above it, such as a heading.
  *
+ * @event {HelixBeforeReorderEvent} helix-before-reorder - Fired when a row is dropped at a new place, in a `reorderable` table, with every row's key in the new order. Cancelable: cancel it to keep the row where it is.
+ * @event {HelixReorderEvent} helix-reorder - Fired after `helix-before-reorder` when nobody canceled it. Move your rows to the order in `keys`. Cancelable: cancel it to say the move did not happen.
  * @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, as `field:direction`, or empty for the order the rows were written in. Cancelable: cancel it to keep the current order.
@@ -84,9 +125,13 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * @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, in a `reorderable` table. Hidden from assistive technology.
  * @csspart empty - The text shown when there are no rows.
+ * @csspart grid-end - An empty box after the rows, in a `grid` table. Tab focuses it on its way out of the table, so the key leaves from the end.
+ * @csspart grid-start - An empty box before the rows, in a `grid` table. Shift with Tab focuses it on its way out of the table.
+ * @csspart grip-head - The heading over the row grips, in a `reorderable` table.
  * @csspart head - The row that holds the column headings. It has `display: contents`, so it takes no space of its own.
- * @csspart live - A live region that repeats the empty and loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
+ * @csspart live - A live region that repeats the empty and loading text, and says each step of a move, so screen readers announce it when it changes. Visually hidden in the styled tier.
  * @csspart loading - The text shown while the rows are loading.
  * @csspart select-all - The heading that holds the checkbox that selects every row.
  * @csspart table - The grid.
@@ -94,8 +139,24 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * @cssproperty --table-template - The column track list the table works out from its columns. The component writes it inline on the element that reads it, so setting it has no effect. Set `columns` to change the tracks.
  */
 export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
-    /** The word for an ascending sort, in `sorted-label`. */
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-table': { selectAllLabel: 'Alle Zeilen auswählen' } })`.
+     */
+    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, in a `reorderable` table.
+     */
+    canceledLabel: string;
     /**
      * The column widths as one track list, written once on the table.
      *
@@ -136,8 +197,31 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_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 held row is dropped, in a `reorderable` table. */
+    droppedLabel: string;
+    /**
+     * The table's name where neither `label` nor an `aria-label` or
+     * `aria-labelledby` on the host gives it one.
+     */
+    fallbackLabel: string;
+    /**
+     * Makes the table a grid: one tab stop, and the arrow keys, Home, End and the
+     * Page keys move focus between its cells, the headings included. Enter moves
+     * into a cell's controls, and Tab leaves the table.
+     *
+     * Off by default, where the table is a static `table` and Tab reaches each
+     * link and control in it. On, the table writes a `tabindex` onto each of its
+     * cells, which is the one way a cell of your markup can take focus.
+     */
+    grid: boolean;
     /**
      * Accessible name for the table.
      *
@@ -145,6 +229,29 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * wins over this.
      */
     label: string;
+    /**
+     * What screen readers hear each time a key moves a held row, in a
+     * `reorderable` table. `{name}` is the row's words, `{position}` the place it
+     * would go, counting from 1, and `{count}` the number of rows.
+     */
+    movedLabel: string;
+    /**
+     * The name of a row's grip, in a `reorderable` table. `{row}` is replaced
+     * with the words of the row's first cell.
+     */
+    moveRowLabel: string;
+    /**
+     * What screen readers hear when a key or a click picks up a row, in a
+     * `reorderable` table. `{name}` is the row's words.
+     */
+    pickedUpLabel: string;
+    /**
+     * Adds a column of grips that move rows, by dragging or with the keys. The
+     * table moves no row itself: you move your rows on `helix-reorder`.
+     */
+    reorderable: boolean;
+    /** The name of the heading over the row grips, in a `reorderable` table. */
+    rowGripsLabel: string;
     /**
      * Adds a column of checkboxes for selecting rows. Each row is known by its
      * `value`, and by its place among the rows as written where it has none.
@@ -163,7 +270,9 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_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;
     /**
@@ -184,7 +293,9 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_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;
     /** What screen readers hear when the table stops being sorted. */
@@ -202,6 +313,23 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * itself kept its default name.
      */
     protected readonly aria: AriaForwardController;
+    /** The keyboard of a `grid` table, in `grid-controller.ts`. */
+    private readonly gridKeys;
+    /**
+     * Moving rows by their grips, in a `reorderable` table. The rows are the
+     * page's, so a drop asks the page to move them, and the grips do nothing
+     * while a sort decides the order.
+     */
+    private readonly reorder;
+    /** The columns drawn before the consumer's cells: the grips, then the checkboxes. */
+    private get lead();
+    /** The row that stands for a key. */
+    private rowFor;
+    /**
+     * What takes focus for a row's grip, in a `reorderable` table: the cell in a
+     * grid, where every cell takes focus, and the button otherwise.
+     */
+    private gripOf;
     /**
      * Asks for a different order, and reports whether the request stood.
      */
@@ -231,6 +359,11 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * new order is said. Not on the first render, which is the table arriving.
      */
     private news;
+    /**
+     * 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;
     /** The sort as the last render had it, so a selection said beside a sort waits. */
     private heardSortBefore;
     /** The selection last heard, so a render that changed nothing says nothing. */
@@ -248,6 +381,17 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
      * left alone.
      */
     private readonly handleToggle;
+    /** Every row's key, in the order the rows are written. */
+    private get everyKey();
+    /** The checkbox in the heading: every row, or none where every row is chosen. */
+    private chooseAll;
+    /** One row's checkbox, ticked or not. */
+    private chooseRow;
+    /**
+     * Enter, Space or F2 on a cell of a `grid` table, and whether it did
+     * anything. Left alone, Enter and F2 move into the cell's controls.
+     */
+    private activate;
     /**
      * Tells each row whether it is selected and what its checkbox is called.
      *
@@ -398,6 +542,8 @@ export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
     private alignCells;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** The heading over the row grips, named by `row-grips-label`. */
+    private renderGripHead;
     /** The heading of the checkbox column, which selects every row. */
     private renderSelectAll;
     protected render(): TemplateResult;