@fusion.dev/helix-headless 0.142.1 → 0.144.0

package/dist/copy-button/from.js

@@ -0,0 +1,28 @@
+import { elementById } from '@fusion.dev/helix-core';
+export const parseFrom = (reference) => {
+    const written = reference.trim();
+    const bracket = /^([^[\].\s]+)\[([^\]\s]+)\]$/u.exec(written);
+    if (bracket) {
+        return { attribute: bracket[2], id: bracket[1] };
+    }
+    const dot = /^([^[\].\s]+)\.([^[\].\s]+)$/u.exec(written);
+    if (dot) {
+        return { id: dot[1], property: dot[2] };
+    }
+    return /^[^[\].\s]+$/u.test(written) ? { id: written } : null;
+};
+export const readFrom = (reference, scope) => {
+    const parsed = parseFrom(reference);
+    const element = parsed ? elementById(scope, parsed.id) : null;
+    if (!(parsed && element)) {
+        return null;
+    }
+    if (parsed.attribute !== undefined) {
+        return element.getAttribute(parsed.attribute);
+    }
+    if (parsed.property !== undefined) {
+        const read = element[parsed.property];
+        return read === undefined || read === null ? null : String(read);
+    }
+    return element.textContent;
+};

package/dist/copy-button/root/copy-button-root.d.ts

@@ -12,7 +12,19 @@ import '../../tooltip/index.js';
  * The confirmation and the event wait for the write to finish. The browser can
  * refuse a clipboard write, for example on an insecure origin, in a document
  * that is not focused, or after a gesture that does not qualify. A refused
- * write leaves the button unchanged.
+ * write, or nothing to copy, names the button with `error-label` for the same
+ * moment a copy shows `copied-label`, draws a cross, and sends
+ * `helix-copy-error`.
+ *
+ * `from` copies from another element on the page: its text, an attribute
+ * written `id[attribute]`, or a property written `id.property`, read at the
+ * press. It takes the place of `value`.
+ *
+ * It replaces Button's render and its press, so it never submits a form or
+ * sends a command: `type`, `command`, `commandfor` and the `form*` overrides
+ * have no effect, and the `start` and `end` slots and the `text` part are not
+ * rendered. An `aria-label` on the element names it before a copy, in place of
+ * `label`.
  *
  * @since 0.1.0
  * @status stable
@@ -22,10 +34,13 @@ import '../../tooltip/index.js';
  *
  * @slot - The icon shown before a copy. Defaults to a clipboard.
  * @slot copied - The icon shown after a successful copy. Defaults to a check mark.
+ * @slot failed - The icon shown after a copy that put nothing on the clipboard. Defaults to a cross.
  *
  * @event {HelixCopyEvent} helix-copy - Fired after the clipboard write succeeds.
+ * @event {Event} helix-copy-error - Fired when a press put nothing on the clipboard: the browser refused the write, or there was nothing to copy.
  *
  * @csspart button - The inner button.
+ * @csspart live - The live region that says `pending-label` when the button becomes pending under focus. It is rendered from the first time the button is pending.
  * @csspart mark - The clipboard icon, and the confirmation icon that replaces it.
  * @csspart tooltip - The tooltip bubble, forwarded from the tooltip inside the button.
  * @csspart tooltip-arrow - The tooltip's arrow, which points at the button.
@@ -46,6 +61,18 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
      * dash-casing it, and `copiedlabel` is not what anyone would type.
      */
     copiedLabel: string;
+    /**
+     * The button's name and tooltip text after a press that put nothing on the
+     * clipboard.
+     */
+    errorLabel: string;
+    /**
+     * The element to copy from, by its id: `key` for its text, `key[value]` for
+     * an attribute, and `key.value` for a property. Read at the press, and used
+     * in place of `value`. An element that is not there copies nothing, which is
+     * a failed copy.
+     */
+    from: string;
     /**
      * The button's name and tooltip text before a copy.
      *
@@ -57,12 +84,8 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
     /**
      * The text copied to the clipboard.
      *
-     * **Narrows `Button.value`, which is the submit value, and the two agree.**
-     * A copy button is `type="button"` and never submits, so the inherited
-     * meaning has nothing to act on; where a consumer changes the type, what it
-     * submits is what it copies, which is the reading anybody would expect of one
-     * property called `value`. Declared here rather than inherited because the
-     * clipboard is what this component is about and its own page should say so.
+     * It replaces `Button.value`, the submit value: a copy button never submits,
+     * whatever its `type`. Declared here so its own page says what it holds.
      */
     value: string;
     /**
@@ -76,6 +99,19 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
      * makes the announcement happen at all.
      */
     private get says();
+    /**
+     * @internal The host's `aria-label`, observed so a new one renders, as
+     * `MixinField` observes it. Not reflected: the attribute is the consumer's.
+     */
+    protected namedBy: string | null;
+    /**
+     * @internal The name is written here, from `aria-label` too, so it can
+     * change to `copiedLabel`: carried down as well, a host `aria-label` would
+     * cover the confirmation.
+     */
+    protected get forwardsLabel(): boolean;
+    /** @internal A copy button never submits, so it is no form's default button. */
+    protected get submitsForm(): boolean;
     /**
      * The write, the confirmation, the timer and the event, all of them shared.
      *
@@ -92,6 +128,9 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
      */
     private readonly clipboard;
     private get copied();
+    private get failed();
+    /** What a press copies: the text `from` names, or `value`. */
+    private get text();
     private readonly handleCopy;
     /**
      * Both faces, drawn rather than demanded.
@@ -124,6 +163,8 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
      * the focused element mid-press.
      */
     protected renderCopiedIcon(): TemplateResult;
+    /** The mark for a press that put nothing on the clipboard, behind a seam of its own. */
+    protected renderFailedIcon(): TemplateResult;
     /**
      * The bubble the control sits inside, behind a seam.
      *

package/dist/copy-button/root/copy-button-root.js

@@ -6,60 +6,97 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 };
 var HelixHeadlessCopyButton_1;
 import { CopyController, customElement } from '@fusion.dev/helix-core';
-import { check, copy } from '@fusion.dev/helix-icons';
+import { check, copy, x } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
 import { HelixHeadlessIconButton } from '../../icon-button/root/icon-button-root.js';
+import { readFrom } from '../from.js';
 import '../../tooltip/index.js';
 const CONFIRM = 1600;
 let HelixHeadlessCopyButton = HelixHeadlessCopyButton_1 = class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
     constructor() {
         super(...arguments);
         this.copiedLabel = 'Copied';
+        this.errorLabel = 'Could not copy';
+        this.from = '';
         this.label = 'Copy';
         this.value = '';
+        this.namedBy = null;
         this.clipboard = new CopyController(this, { after: CONFIRM });
-        this.handleCopy = async () => {
+        this.handleCopy = async (event) => {
+            if (this.pending) {
+                event.preventDefault();
+                event.stopImmediatePropagation();
+                return;
+            }
             if (this.isDisabled) {
                 return;
             }
-            await this.clipboard.copy(this.value);
+            const wrote = await this.clipboard.copy(this.text);
+            if (!wrote && this.isConnected) {
+                this.dispatchEvent(new Event('helix-copy-error', { bubbles: true, composed: true }));
+            }
         };
     }
     get says() {
-        return this.copied ? this.copiedLabel : this.label;
+        if (this.failed) {
+            return this.errorLabel;
+        }
+        return this.copied ? this.copiedLabel : this.namedBy || this.label;
+    }
+    get forwardsLabel() {
+        return false;
+    }
+    get submitsForm() {
+        return false;
     }
     get copied() {
         return this.clipboard.copied;
     }
+    get failed() {
+        return this.clipboard.failed;
+    }
+    get text() {
+        return this.from === '' ? this.value : (readFrom(this.from, this) ?? '');
+    }
     static icon(glyph) {
         return html `<svg part="mark" fill="currentColor" viewBox=${glyph.viewBox} aria-hidden="true">
       ${unsafeSVG(glyph.content)}
     </svg>`;
     }
     render() {
-        return this.renderTooltip(html `<button
+        return html `${this.renderTooltip(html `<button
       part="button"
       type="button"
+      aria-busy=${this.pending ? 'true' : nothing}
+      aria-disabled=${this.pending ? 'true' : nothing}
       aria-label=${this.says}
       data-copied=${this.copied ? '' : nothing}
+      data-failed=${this.failed ? '' : nothing}
       tabindex=${this.focusable ? nothing : '-1'}
       ?disabled=${this.isDisabled}
       @click=${this.handleCopy}
     >
-      ${this.renderCopiedIcon()} ${this.renderCopyIcon()}
-      </button>`);
+      ${this.renderCopiedIcon()} ${this.renderFailedIcon()} ${this.renderCopyIcon()}
+      </button>`)}${this.renderLive()}`;
     }
     renderCopyIcon() {
-        return html `<slot ?hidden=${this.copied}>${HelixHeadlessCopyButton_1.icon(copy)}</slot>`;
+        return html `<slot ?hidden=${this.copied || this.failed}
+      >${HelixHeadlessCopyButton_1.icon(copy)}</slot
+    >`;
     }
     renderCopiedIcon() {
         return html `<slot name="copied" ?hidden=${!this.copied}
       >${HelixHeadlessCopyButton_1.icon(check)}</slot
     >`;
     }
+    renderFailedIcon() {
+        return html `<slot name="failed" ?hidden=${!this.failed}
+      >${HelixHeadlessCopyButton_1.icon(x)}</slot
+    >`;
+    }
     renderTooltip(control) {
         return html `<${this.tag('tooltip')} content=${this.says} persist
     exportparts="arrow: tooltip-arrow, arrow-bottom: tooltip-arrow-bottom,
@@ -73,12 +110,21 @@ let HelixHeadlessCopyButton = HelixHeadlessCopyButton_1 = class HelixHeadlessCop
 __decorate([
     property({ attribute: 'copied-label' })
 ], HelixHeadlessCopyButton.prototype, "copiedLabel", void 0);
+__decorate([
+    property({ attribute: 'error-label' })
+], HelixHeadlessCopyButton.prototype, "errorLabel", void 0);
+__decorate([
+    property()
+], HelixHeadlessCopyButton.prototype, "from", void 0);
 __decorate([
     property()
 ], HelixHeadlessCopyButton.prototype, "label", void 0);
 __decorate([
     property()
 ], HelixHeadlessCopyButton.prototype, "value", void 0);
+__decorate([
+    property({ attribute: 'aria-label' })
+], HelixHeadlessCopyButton.prototype, "namedBy", void 0);
 HelixHeadlessCopyButton = HelixHeadlessCopyButton_1 = __decorate([
     customElement('helix-headless-copy-button')
 ], HelixHeadlessCopyButton);

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.
      *