@fusion.dev/helix-headless 0.145.0 → 0.146.0

package/dist/steps/root/steps-root.js

@@ -7,7 +7,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria, MixinControllerActive, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-import { canReach } from '../reach.js';
+import { canReach, progressOf } from '../reach.js';
 let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
@@ -17,7 +17,8 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             if (event.defaultPrevented || !this.steps.includes(event.target)) {
                 return;
             }
-            if (!this.reachable(this.steps.indexOf(event.target))) {
+            const index = this.steps.indexOf(event.target);
+            if (!this.reachable(index) || !this.valid(index)) {
                 return;
             }
             this.requestActive(event.detail.value);
@@ -27,6 +28,9 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             this.lock();
         };
     }
+    get progress() {
+        return progressOf(this.steps);
+    }
     get steps() {
         return [...this.querySelectorAll(':scope > *')].filter((one) => 'current' in one);
     }
@@ -46,11 +50,20 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
             index += delta;
         }
         const target = steps[index];
-        if (!target || !this.reachable(index)) {
+        if (!target || !this.reachable(index) || !this.valid(index)) {
             return false;
         }
         return this.requestActive(target.value);
     }
+    valid(index) {
+        const from = this.steps[this.at];
+        if (!from || index <= this.at || !this.validate || from.optional) {
+            return true;
+        }
+        const valid = this.validate(from);
+        from.invalid = !valid;
+        return valid;
+    }
     reachable(index) {
         return !this.linear || canReach(this.steps, this.at, index);
     }
@@ -79,7 +92,10 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
-        this.watcher = new MutationObserver(() => this.lock());
+        this.watcher = new MutationObserver(() => {
+            this.lock();
+            this.requestUpdate();
+        });
         this.watcher.observe(this, {
             attributeFilter: ['complete', 'current', 'optional'],
             attributes: true,
@@ -92,9 +108,18 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         this.watcher?.disconnect();
         this.watcher = undefined;
     }
+    get known() {
+        return this.knownChildren.filter((one) => 'current' in one);
+    }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { label: this.label, role: 'list' });
+        const known = this.known;
+        this.toggleState('complete', known.length > 0 && known.every((step) => step.complete));
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.finishHydration();
     }
     updated(changed) {
         super.updated(changed);
@@ -106,7 +131,18 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         }
     }
     render() {
-        return html `<slot @slotchange=${this.handleSlotChange}></slot>`;
+        const progress = progressOf(this.known);
+        return html `<slot @slotchange=${this.handleSlotChange}></slot>
+      <div
+        part="progress"
+        role="progressbar"
+        aria-label=${this.label}
+        aria-valuemin="0"
+        aria-valuemax="100"
+        aria-valuenow=${progress}
+        style="--steps-progress: ${progress}%"
+        hidden
+      ></div>`;
     }
 };
 __decorate([
@@ -118,6 +154,9 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessSteps.prototype, "orientation", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessSteps.prototype, "validate", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessSteps.prototype, "variant", void 0);

package/dist/steps/step/step.d.ts

@@ -50,6 +50,8 @@ import '../../button/index.js';
  * @csspart mark - The glyph inside the marker: a tick, a dot, or an empty ring.
  * @csspart marker - The shape carrying the number or the check.
  * @csspart state - The words that describe a finished stage's button. Hidden.
+ *
+ * @cssstate invalid - The sequence's `validate` last answered that this stage is not valid.
  */
 export declare class HelixHeadlessStep extends HelixElement {
     /**
@@ -69,6 +71,11 @@ export declare class HelixHeadlessStep extends HelixElement {
      * Whether the stage is disabled, so the user cannot go to it.
      */
     disabled: boolean;
+    /**
+     * @internal Set by the sequence: whether its `validate` last answered that
+     * this stage is not valid. Recorded as `:state(invalid)`.
+     */
+    invalid: boolean;
     /**
      * @internal Set by a linear sequence: whether the stage is out of reach
      * until the ones before it are finished. A property, because the sequence

package/dist/steps/step/step.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, drawStatus, HelixElement, HelixSelectEvent, hostAria, StatusController, } from '@fusion.dev/helix-core';
+import { customElement, drawStatus, HelixElement, HelixSelectEvent, hostAria, StatusController, slottedWords, } from '@fusion.dev/helix-core';
 import { check, circle, record } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
@@ -18,6 +18,7 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
         this.completeLabel = 'Complete';
         this.current = false;
         this.disabled = false;
+        this.invalid = false;
         this.locked = false;
         this.optional = false;
         this.value = '';
@@ -40,11 +41,12 @@ let HelixHeadlessStep = class HelixHeadlessStep extends HelixElement {
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'listitem' });
+        this.toggleState('invalid', this.invalid);
     }
     updated(changed) {
         super.updated(changed);
         if (changed.get('complete') === false && this.complete) {
-            const name = (this.textContent ?? '').replace(/\s+/g, ' ').trim();
+            const name = slottedWords(this, ['']);
             this.status.say(name === '' ? this.completeLabel : `${name}, ${this.completeLabel}`);
         }
     }
@@ -84,6 +86,9 @@ __decorate([
 __decorate([
     property({ reflect: true, type: Boolean })
 ], HelixHeadlessStep.prototype, "disabled", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessStep.prototype, "invalid", void 0);
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessStep.prototype, "locked", void 0);

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

@@ -18,6 +18,16 @@ declare const HelixHeadlessSwitch_base: (new (...args: any[]) => import("@fusion
  * press, the same as a checkbox. The hint and the message go below the row,
  * because the switch and its label share one line.
  *
+ * **Keyboard.** The switch is one tab stop.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Space | Turns the switch on or off, as a native checkbox does. |
+ *
+ * The input carries `role="switch"`, so a screen reader says "on" or "off".
+ * `aria-readonly` is set under `readonly`, and `aria-invalid` and
+ * `aria-describedby` point at the message while one shows.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms

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

@@ -10,16 +10,6 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `undefined` falls back to the field.
  */
 export type CellReader = (row: Readonly<Record<string, unknown>>) => unknown;
-/**
- * A dot path resolved against a row.
- *
- * Written here rather than taken from a library, because the whole of what is
- * needed is "walk the keys and stop at the first thing that is not an object".
- * Returns `undefined` for a path that does not resolve, which the table renders
- * as an empty cell: a missing key is a hole in the data and drawing `undefined`
- * into a table tells a reader the software is broken rather than the row is.
- */
-export declare const at: (row: Readonly<Record<string, unknown>>, path: string) => unknown;
 /**
  * The edge a column names, where it names one of the three.
  *

package/dist/table/column/table-column.js

@@ -5,27 +5,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessTableColumn_1;
-import { customElement, fillTemplate, HelixBeforeResizeEvent, HelixElement, HelixResizedEvent, hostAria, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { customElement, fillTemplate, HelixBeforeResizeEvent, HelixElement, HelixResizedEvent, hostAria, inlineStep, isRtl, requestChange, valueAt, } from '@fusion.dev/helix-core';
 import { dotsThreeVertical } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-export const at = (row, path) => {
-    if (path === '') {
-        return undefined;
-    }
-    if (!path.includes('.')) {
-        return row[path];
-    }
-    let cursor = row;
-    for (const key of path.split('.')) {
-        if (cursor === null || typeof cursor !== 'object') {
-            return undefined;
-        }
-        cursor = cursor[key];
-    }
-    return cursor;
-};
 const EDGES = new Set(['center', 'end', 'start']);
 export const edgeOf = (align) => align && EDGES.has(align) ? align : undefined;
 let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixElement {
@@ -96,11 +80,11 @@ let HelixHeadlessTableColumn = class HelixHeadlessTableColumn extends HelixEleme
     }
     read(row) {
         const rendered = this.cell?.(row);
-        return rendered === undefined ? at(row, this.field) : rendered;
+        return rendered === undefined ? valueAt(row, this.field) : rendered;
     }
     order(row) {
         const compared = this.compare?.(row);
-        return compared === undefined ? at(row, this.field) : compared;
+        return compared === undefined ? valueAt(row, this.field) : compared;
     }
     willUpdate(changed) {
         super.willUpdate(changed);

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

@@ -17,21 +17,42 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  * `rowheader` for a `header` cell in a row of values. Rows are
  * `display: contents`, so their cells become items of the one grid.
  *
- * A column with `sortable` and a `field` sorts the rows by the text of its
- * cells, numbers by their value. Your markup is not reordered: the table draws
- * the rows in the sorted order. `helix-sort` asks first, so you can refuse it
- * and reorder the rows yourself.
+ * **Sorting.** A column with `sortable` and a `field` draws its heading as a
+ * button that sorts the rows by the text of its cells, numbers by their value.
+ * Your markup is not reordered: the table draws the rows in the sorted order.
+ *
+ * 1. Each press cycles the column through ascending, descending, and the
+ *    order the rows were written in, which keeps a server's own ranking
+ *    reachable.
+ * 2. `helix-sort` asks first, with `field:direction`, or empty for the written
+ *    order. Refuse it to keep the order, or to sort the rows yourself and set
+ *    `sort`.
+ * 3. `helix-sorted` follows once the order stands, and `sort` holds it.
+ * 4. The heading carries `aria-sort`, and a screen reader hears `sorted-label`
+ *    ("Sorted by Name, ascending") or `unsorted-label` from a polite region.
+ *
+ * Tab reaches each sort button, and Enter or Space presses it.
  *
  * The `heading` slot names the table: slot a heading or a line of text into
  * it, and the table is named by its words. An `aria-label` or `aria-labelledby` on the
  * host wins over it.
  *
- * `selectable` adds a column of checkboxes. Each row is known by its `value`,
- * and `selected` holds the chosen keys, comma separated, the same shape
- * `DataTable` uses. The checkbox in the heading selects every row. 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.
+ * **Selecting.** `selectable` adds a column of checkboxes.
+ *
+ * 1. Each row is known by its `value`, or by its place among the rows where it
+ *    has none, and `selected` holds the chosen keys, comma separated, the same
+ *    shape `DataTable` uses. `default-selected` is where it starts.
+ * 2. A row's checkbox is named by `select-row-label` ("Select {row}") with the
+ *    words of the row's first cell. The checkbox in the heading selects every
+ *    row, and shows a dash while only some are chosen.
+ * 3. `helix-select` asks first, with every key the change would leave.
+ *    Refuse it to keep the selection. `helix-selected` follows once it stands.
+ * 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.
  *
  * 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

package/dist/table/root/table-root.js

@@ -4,12 +4,11 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { AriaForwardController, commaList, customElement, fillTemplate, HelixElement, HelixSelectEvent, HelixSelectedEvent, HelixSortEvent, HelixSortedEvent, MixinCollection, reflectElements, requestChange, splitValues, whenHydrated, } from '@fusion.dev/helix-core';
+import { AriaForwardController, commaList, customElement, cycle, fillTemplate, format, HelixElement, HelixSelectEvent, HelixSelectedEvent, HelixSortEvent, HelixSortedEvent, MixinCollection, parse, reflectElements, requestChange, sort, splitValues, toggleEvery, whenHydrated, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../checkbox/index.js';
-import { cycle, format, parse, sort } from '../../data-table/root/order.js';
 import { edgeOf } from '../column/table-column.js';
 const tracksOf = (list, wanted) => {
     const words = splitValues(list, ' ');
@@ -78,17 +77,7 @@ let HelixHeadlessTable = class HelixHeadlessTable extends MixinCollection(HelixE
             const keys = this.chosen;
             if (root === this.renderRoot) {
                 event.preventDefault();
-                const every = this.keyed.map(({ key }) => key);
-                const all = every.length > 0 && every.every((key) => keys.has(key));
-                for (const key of every) {
-                    if (all) {
-                        keys.delete(key);
-                    }
-                    else {
-                        keys.add(key);
-                    }
-                }
-                this.requestSelected(keys);
+                this.requestSelected(new Set(toggleEvery(keys, this.keyed.map(({ key }) => key))));
                 return;
             }
             const found = this.keyed.find(({ row }) => row.shadowRoot === root);

package/dist/tabs/panel/tab-panel.d.ts

@@ -10,8 +10,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * The host is the `tabpanel` while its tab is selected, through
  * `ElementInternals`, so the tab's `aria-controls` can reach it from the tab's
- * shadow root. The box inside takes the focus, for a panel with nothing
- * focusable in it.
+ * shadow root. The box inside is a tab stop only while the panel holds nothing
+ * focusable, as the ARIA tabs pattern and React Aria's tab panel do: Tab from
+ * the tab list lands on the panel's first link or control where there is one,
+ * and on the panel itself where there is none.
  *
  * @since 0.1.0
  * @status stable
@@ -20,7 +22,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The panel's content.
  *
- * @csspart panel - The panel container, which takes the focus.
+ * @csspart panel - The panel container, which takes the focus while it holds nothing focusable.
  *
  * @cssstate selected - While its tab is the one selected.
  */
@@ -46,6 +48,17 @@ export declare class HelixHeadlessTabPanel extends HelixElement {
      * Pairs the panel with the tab of the same value.
      */
     value: string;
+    /**
+     * Whether the content holds a tab stop of its own, so the panel needs none.
+     * False on a server, which serves the panel as a stop: it cannot look.
+     */
+    private holdsStop;
+    /** Re-reads the content when it changes in a way that adds or removes a stop. */
+    private readonly watcher;
+    private readonly readStops;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(changed: PropertyValues): void;
     /**
      * Mirrors the chosen state where a stylesheet can select on it.
      *

package/dist/tabs/panel/tab-panel.js

@@ -4,15 +4,41 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
-import { html } from 'lit';
-import { property } from 'lit/decorators.js';
+import { customElement, focusableElements, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property, state } from 'lit/decorators.js';
 let HelixHeadlessTabPanel = class HelixHeadlessTabPanel extends HelixElement {
     constructor() {
         super(...arguments);
         this.label = '';
         this.selected = false;
         this.value = '';
+        this.holdsStop = false;
+        this.watcher = typeof MutationObserver === 'undefined'
+            ? undefined
+            : new MutationObserver(() => this.readStops());
+        this.readStops = () => {
+            this.holdsStop = this.selected && focusableElements(this).length > 0;
+        };
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.watcher?.observe(this, {
+            attributeFilter: ['contenteditable', 'disabled', 'hidden', 'href', 'tabindex'],
+            attributes: true,
+            childList: true,
+            subtree: true,
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.watcher?.disconnect();
+    }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('selected')) {
+            this.readStops();
+        }
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -23,9 +49,9 @@ let HelixHeadlessTabPanel = class HelixHeadlessTabPanel extends HelixElement {
         return html `<div
       part="panel"
       ?hidden=${!this.selected}
-      tabindex="0"
+      tabindex=${this.holdsStop ? nothing : '0'}
     >
-      <slot></slot>
+      <slot @slotchange=${this.readStops}></slot>
     </div>`;
     }
 };
@@ -38,6 +64,9 @@ __decorate([
 __decorate([
     property()
 ], HelixHeadlessTabPanel.prototype, "value", void 0);
+__decorate([
+    state()
+], HelixHeadlessTabPanel.prototype, "holdsStop", void 0);
 HelixHeadlessTabPanel = __decorate([
     customElement('helix-headless-tab-panel')
 ], HelixHeadlessTabPanel);

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

@@ -28,6 +28,17 @@ declare const HelixHeadlessTabs_base: (new (...args: any[]) => import("@fusion.d
  * Each tab says which panel it controls through `aria-controls`, set as an
  * element reference to the panel's host, where the engine has reflection.
  *
+ * Keys, on the tab list: Left and Right Arrow move between tabs, and so do Up
+ * and Down; Home and End go to the first and the last. The horizontal arrows
+ * follow the reading direction, so on a right-to-left page Left moves on.
+ * Disabled tabs are passed over. Tab leaves the list for the selected panel,
+ * which is a tab stop only while it holds nothing focusable.
+ *
+ * The `indicator` part moves to the selected tab and carries its place and
+ * size, so a mark of your own can be drawn there: style the part, or slot an
+ * element into `indicator`, which sits inside the part and reads the same
+ * properties.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -35,6 +46,7 @@ declare const HelixHeadlessTabs_base: (new (...args: any[]) => import("@fusion.d
  * @documentation https://fusion.dev/helix/components/tabs
  *
  * @slot - The tabs, as direct children of this element.
+ * @slot indicator - A mark of your own, drawn inside the `indicator` part, where `--indicator-x`, `--indicator-y`, `--indicator-inline-size` and `--indicator-block-size` reach it.
  * @slot panels - The panels, as direct children of this element. Panels inside a wrapper are not paired with tabs, because pairing reads only the direct children.
  *
  * @event {HelixActivateEvent} helix-activate - Fired after the active tab changes, so the element already holds the new value.

package/dist/tabs/root/tabs-root.js

@@ -105,7 +105,7 @@ let HelixHeadlessTabs = class HelixHeadlessTabs extends MixinControllerActive(He
         aria-orientation=${this.orientation === 'vertical' ? 'vertical' : nothing}
       >
         <slot @slotchange=${this.handleSlotChange}></slot>
-        <span part="indicator" aria-hidden="true"></span>
+        <span part="indicator" aria-hidden="true"><slot name="indicator"></slot></span>
       </div>
       <div part="panels"><slot name="panels" @slotchange=${this.handleSlotChange}></slot></div>`;
     }

package/dist/tabs/tab/tab.d.ts

@@ -47,6 +47,11 @@ export declare class HelixHeadlessTab extends HelixHeadlessTab_base {
      * Where the link opens, such as `_blank`, for a tab with an `href`.
      */
     target?: string;
+    /**
+     * Moves focus to the tab's control, the button or the link inside it, so a
+     * script can focus the tab the way it focuses a native one.
+     */
+    focus(options?: FocusOptions): void;
     /**
      * Chooses the tab before the browser follows its link, and keeps the browser
      * from following where the choice was refused. A press with a modifier, or

package/dist/tabs/tab/tab.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, MixinSelectableItem, reflectElements, } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, MixinSelectableItem, plainClick, reflectElements, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 let HelixHeadlessTab = class HelixHeadlessTab extends MixinSelectableItem(HelixElement) {
@@ -13,7 +13,7 @@ let HelixHeadlessTab = class HelixHeadlessTab extends MixinSelectableItem(HelixE
         this.itemPart = 'tab';
         this.controls = undefined;
         this.handleLinkClick = (event) => {
-            if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+            if (!plainClick(event)) {
                 return;
             }
             if (!this.select()) {
@@ -21,6 +21,9 @@ let HelixHeadlessTab = class HelixHeadlessTab extends MixinSelectableItem(HelixE
             }
         };
     }
+    focus(options) {
+        this.partNamed('tab')?.focus(options);
+    }
     updated(changed) {
         super.updated(changed);
         const control = this.renderRoot.querySelector('[part="tab"]');

package/dist/tag/group/tag-group.d.ts

@@ -1,7 +1,8 @@
-import { HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-core';
+import { HelixElement, KeyboardNavigationController, type SelectionMode } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { HelixHeadlessTag } from '../root/tag-root.js';
-import { type TagSelectionMode } from '../selection.js';
+/** How many tags a group lets a reader select: core's `SelectionMode`. */
+export type TagSelectionMode = SelectionMode;
 /**
  * @summary A set of tags that the arrow keys move through, and that can be removed and selected from the keyboard.
  *
@@ -17,9 +18,16 @@ import { type TagSelectionMode } from '../selection.js';
  * `single` selects one at a time and `multiple` any number. `value` holds the
  * selected tags' values, separated by commas, and a change asks with
  * `helix-before-change` and tells with `change`. Enter on a tag with an
- * `href` follows its link. A `disabled` tag is passed over.
+ * `href` follows its link. A `disabled` tag is passed over. A selected tag
+ * that is removed leaves `value`, which then sends `change`.
  *
- * Name the set with `label`.
+ * Name the set with `label`. Each tag is named by its words alone, without
+ * its remove button.
+ *
+ * **Removing the last tag keeps focus in the group.** With no tags left the
+ * set is a `group`, and focus moves to its `empty` part,
+ * which holds the `empty` slot: put words there such as "No filters" for a
+ * reader to hear.
  *
  * @since 0.1.0
  * @status stable
@@ -27,10 +35,13 @@ import { type TagSelectionMode } from '../selection.js';
  * @documentation https://fusion.dev/helix/components/tag
  *
  * @slot - The tags, in the order they are read.
+ * @slot empty - Shown in place of the tags while there are none, such as "No filters".
  *
  * @event {Event} change - Fired once a press has changed which tags are selected.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired before a press changes which tags are selected, with the `value` it would leave. Cancelable.
  * @event {HelixDismissEvent} helix-dismiss - A tag's remove button was pressed, or Delete or Backspace on the focused tag. Bubbles from that tag, which is its `target`; remove the tag in response. Cancelable.
+ *
+ * @csspart empty - Holds the `empty` slot while the group has no tags, rendered only then. Takes focus when the last tag is removed.
  */
 export declare class HelixHeadlessTagGroup extends HelixElement {
     /**
@@ -93,9 +104,25 @@ export declare class HelixHeadlessTagGroup extends HelixElement {
     protected press(tag: HelixHeadlessTag): void;
     private readonly handleKeydown;
     private readonly handleClick;
+    /**
+     * What happens once a tag has asked to be removed and the page has had its
+     * turn: a selected tag that left takes its value out of `value`, and focus
+     * that the last tag took with it comes to the group's `empty` part.
+     *
+     * Asked after the event and again a frame later, as `MixinDismissible`
+     * asks, because a framework removes the tag on its next render, after the
+     * handler. A canceled dismissal changes nothing.
+     */
+    private readonly handleDismiss;
+    private readonly handleSlotchange;
     private readonly handleFocusin;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /**
+     * Whether the group is known to hold no tags, which a server and a
+     * hydrating render cannot know: there it holds whatever it was given.
+     */
+    private get empty();
     protected willUpdate(changed: PropertyValues<this>): void;
     protected updated(changed: PropertyValues<this>): void;
     protected render(): TemplateResult;