@fusion.dev/helix-headless 0.176.1 → 0.177.1

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

@@ -2,6 +2,7 @@ import { AriaForwardController, type DataOptionItem, HelixFormElement, PopoverCo
 import { type PropertyValues, type TemplateResult } from 'lit';
 import { type HelixHeadlessOption } from '../../option/root/option-root.js';
 import '../../listbox/index.js';
+import '../../option/index.js';
 declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
  * @summary A control that opens a list of options to choose from.
@@ -13,7 +14,9 @@ declare const HelixHeadlessSelect_base: (new (...args: any[]) => import("@fusion
  * place for focus to return to when the list closes.
  *
  * Your options stay in your light DOM and are slotted through into the listbox,
- * so the listbox looks through slots to find them. For a list too long to draw
+ * so the listbox looks through slots to find them. Write them as `Option`,
+ * group them in `Option.Group`, and divide them with `Option.Separator`.
+ * Importing Select registers all three in the same tier. For a list too long to draw
  * whole, set `items` instead: the list draws only the options in sight, as
  * Listbox's `items` does, and the trigger, its keys and the form read the
  * whole set.

package/dist/select/root/select-root.js

@@ -12,6 +12,7 @@ import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { html } from 'lit/static-html.js';
 import { optionsAmong } from '../../option/root/option-root.js';
 import '../../listbox/index.js';
+import '../../option/index.js';
 import { over } from '../align.js';
 let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(MixinControllerValue(MixinField(HelixFormElement))) {
     constructor() {

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

@@ -24,6 +24,10 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * the lowest, in `overview-label`: "From 12 to 20, highest 30, lowest 8". An
  * `aria-label` on the element names it as `label` does.
  *
+ * `helix-reading-change` says each move of the reading, by pointer, tap or
+ * key, and `helix-reading-press` says a reading was clicked, tapped, or pressed
+ * with Enter or Space, as on every chart.
+ *
  * A pointer resting on the drawing shows the reading under it: the `cursor`
  * part marks it and the `readout` part writes it. `marks` adds a mark on the
  * highest and the lowest reading, and `range` draws a band between two values,
@@ -38,12 +42,26 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * the component computes and CSS cannot, so a stylesheet can draw the sparkline
  * without measuring anything.
  *
+ * **Keyboard.** A sparkline with a `label` is one tab stop.
+ *
+ * | Key | What it does |
+ * |---|---|
+ * | Tab | Moves focus to the drawing and shows the first reading, where there is a `label`. |
+ * | Any arrow | Right and Down move to the next reading, Left and Up to the previous. On a right-to-left page, Left moves to the next. |
+ * | Home, End | Moves to the first or the last reading. |
+ * | Page Down, Page Up | Moves a tenth of the readings on or back. |
+ * | Enter, Space | Presses the reading shown, which sends `helix-reading-press`. |
+ * | Escape | Puts the reading and its tooltip away. |
+ *
  * @since 0.1.0
  * @status stable
  * @category charts
  * @aliases Micro Chart, Trend Line, Inline Chart
  * @documentation https://fusion.dev/helix/components/sparkline
  *
+ * @event {HelixReadingChangeEvent} helix-reading-change - The reading shown moved, or was put away: `index` is the reading, or `-1` for none, with its row's `label` from a table and the `pointerType` that moved it.
+ * @event {HelixReadingPressEvent} helix-reading-press - A reading was clicked, tapped, or pressed with Enter or Space, with the same detail as `helix-reading-change`.
+ *
  * @csspart area - The region between the line and the bottom of its range.
  * @csspart bar - One column, drawn when `plot="bar"`.
  * @csspart cursor - The mark on the reading a pointer or a key rests on, rendered only while there is one. Placed with `inset-inline-start` and `inset-block-start`.
@@ -201,17 +219,24 @@ export declare class HelixHeadlessSparkline extends HelixElement {
     values: string | readonly number[];
     protected readonly source: SourceController;
     /**
-     * Finds the reading a pointer or a key rests on, as it does for every
-     * chart, so a sparkline is read the way they are.
+     * @internal Finds the reading a pointer or a key rests on, as it does for
+     * every chart, so a sparkline is read the way they are.
      */
     readonly pointer: ChartPointerController;
     /**
-     * Hears an `aria-label` written on the sparkline, which no property mirrors,
+     * @internal Hears an `aria-label` written on the sparkline, which no property mirrors,
      * because it names the drawing as `label` does, as on every chart.
      */
     static get observedAttributes(): string[];
-    /** Called by the browser when an observed attribute changes; a new `aria-label` renames the drawing. */
+    /** @internal Called by the browser when an observed attribute changes; a new `aria-label` renames the drawing. */
     attributeChangedCallback(name: string, old: string | null, value: string | null): void;
+    /**
+     * Sends the reading's moves and presses as `helix-reading-change` and
+     * `helix-reading-press`, named by the table's row where there is one. Here
+     * and not in a constructor, where the manifest's analyzer reads the
+     * assignment as a member of this class.
+     */
+    connectedCallback(): void;
     /** The drawing's name: an `aria-label` written on the sparkline, then `label`. */
     get named(): string;
     /** The two values of `range`, lower first, or none. */

package/dist/sparkline/root/sparkline-root.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 { CHART_PLOT, ChartPointerController, customElement, extent, extremesOf, formatNumbers, formatWords, HelixElement, linear, linePath, PLOT_WIDTH, SourceController, unbroken, words, wordsLocale, writtenList, writtenNumbers, } from '@fusion.dev/helix-core';
+import { CHART_PLOT, ChartPointerController, customElement, extent, extremesOf, formatNumbers, formatWords, HelixElement, HelixReadingChangeEvent, HelixReadingPressEvent, linear, linePath, PLOT_WIDTH, SourceController, unbroken, words, wordsLocale, writtenList, writtenNumbers, } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import { areaPath, overviewWords, readingWords, slotsOf } from '../readings.js';
@@ -33,6 +33,13 @@ let HelixHeadlessSparkline = class HelixHeadlessSparkline extends HelixElement {
             this.requestUpdate();
         }
     }
+    connectedCallback() {
+        super.connectedCallback();
+        this.pointer.onReading = (heard, detail) => {
+            const told = { ...detail, label: this.source.rows[detail.index]?.label ?? '' };
+            this.dispatchEvent(heard === 'press' ? new HelixReadingPressEvent(told) : new HelixReadingChangeEvent(told));
+        };
+    }
     get named() {
         return this.getAttribute?.('aria-label') || this.label;
     }

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

@@ -99,8 +99,9 @@ export declare class HelixHeadlessTagGroup extends HelixElement {
      */
     selectionMode?: TagSelectionMode;
     /**
-     * The selected tags' values, separated by commas, since a value may hold a
-     * space.
+     * The selected tags' values, separated by commas with no space, as Toggle
+     * Group and Table write theirs, since a value may hold a space. A value
+     * written with a space after each comma is read the same way.
      *
      * Set it to start with tags selected. A tag's value is its `value`, or its
      * words where it has none.
@@ -159,7 +160,7 @@ export declare class HelixHeadlessTagGroup extends HelixElement {
     /** Whether a press or a move selects the tag alone. */
     private get replaces();
     /**
-     * Asks for `value` to become `next`, where it changes and where it leaves a
+     * Asks for `value` to become `asked`, where it changes and where it leaves a
      * tag selected under `disallow-empty-selection`.
      */
     private ask;

package/dist/tag/group/tag-group.js

@@ -108,7 +108,7 @@ let HelixHeadlessTagGroup = class HelixHeadlessTagGroup extends HelixElement {
                 const left = this.tags.map((one) => this.valueFor(one));
                 const pruned = prunedValue(this.written, this.valueFor(tag), left);
                 if (pruned !== this.written) {
-                    this.value = pruned;
+                    this.value = commaList(pruned).join(',');
                     this.dispatchEvent(new Event('change', { bubbles: true, composed: true }));
                 }
                 const active = document.activeElement;
@@ -150,7 +150,7 @@ let HelixHeadlessTagGroup = class HelixHeadlessTagGroup extends HelixElement {
             : this.value
                 .map((one) => String(one).trim())
                 .filter((one) => one !== '')
-                .join(', ');
+                .join(',');
     }
     get tags() {
         return [...(this.children ?? [])].filter((child) => child instanceof HelixHeadlessTag);
@@ -212,8 +212,9 @@ let HelixHeadlessTagGroup = class HelixHeadlessTagGroup extends HelixElement {
     get replaces() {
         return this.selectionMode !== undefined && this.selectionBehavior === 'replace';
     }
-    ask(next) {
-        if (next === this.written) {
+    ask(asked) {
+        const next = commaList(asked).join(',');
+        if (next === commaList(this.written).join(',')) {
             return;
         }
         if (this.disallowEmptySelection && commaList(next).length === 0) {
@@ -239,7 +240,7 @@ let HelixHeadlessTagGroup = class HelixHeadlessTagGroup extends HelixElement {
         this.choose(this.tags.filter((tag) => chosen.includes(tag)));
     }
     choose(tags) {
-        this.ask([...new Set(tags.map((tag) => this.valueFor(tag)))].join(', '));
+        this.ask([...new Set(tags.map((tag) => this.valueFor(tag)))].join(','));
     }
     connectedCallback() {
         super.connectedCallback();

package/dist/tag/root/tag-root.js

@@ -70,12 +70,13 @@ let HelixHeadlessTag = class HelixHeadlessTag extends MixinDismissible(HelixElem
     }
     render() {
         const content = html `<slot name="start" part="start"></slot>${this.renderLabel()}${this.dismissible ? this.renderDismiss() : nothing}`;
+        const stop = this.focusable ? '0' : this.disabled ? nothing : '-1';
         return this.grouped
             ? html `<span
           aria-label=${this.words || nothing}
           part="cell"
           role="gridcell"
-          tabindex=${this.focusable ? '0' : '-1'}
+          tabindex=${stop}
           @focus=${this.handleCellFocus}
           @blur=${this.handleCellFocus}
           >${content}</span

package/dist/time-input/root/time-input-root.d.ts

@@ -277,7 +277,13 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
     unavailableMessage: string;
     /**
      * The message for text that is no time, where `bad-input-message` is not
-     * set. `{mode}` is `single`, `range`, or `multiple`, and `{shape}` is `HH:mm`, or `HH:mm:ss` with `seconds`.
+     * set. `{mode}` is `single`, `range`, or `multiple`, `{example}` is a time
+     * written as the field writes one, `2:30 PM` in `en-US` and `14:30` in
+     * `de-DE`, and `{shape}` is `HH:mm`, or `HH:mm:ss` with `seconds`.
+     *
+     * **The default names a time the field reads back.** It said "Enter a time
+     * as HH:mm." to a reader whose field showed `2:30 PM`, and a pattern token
+     * is words for a developer.
      */
     unreadableMessage: string;
     /** Every time in the value, which may hold more than one. */

package/dist/time-input/root/time-input-root.js

@@ -36,7 +36,7 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
         this.timeStyle = 'local';
         this.triggerLabel = 'Choose a time';
         this.unavailableMessage = 'Choose a time that is available.';
-        this.unreadableMessage = '{mode, select, single {Enter a time as {shape}.} other {Enter times as {shape}, separated by commas.}}';
+        this.unreadableMessage = '{mode, select, single {Enter a time such as {example}.} other {Enter times such as {example}, separated by commas.}}';
         this.draft = '';
         this.handleTextCommit = (event) => {
             if (this.mode !== 'multiple') {
@@ -182,10 +182,13 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
     }
     validate() {
         const held = this.held;
-        const shape = this.seconds ? 'HH:mm:ss' : 'HH:mm';
         if (held.length > 0 && !held.every((one) => this.isTime(one))) {
             return (this.badInputMessage ||
-                formatWords(this, 'unreadableMessage', { mode: this.mode ?? 'single', shape }));
+                formatWords(this, 'unreadableMessage', {
+                    example: this.written(this.seconds ? '14:30:15' : '14:30'),
+                    mode: this.mode ?? 'single',
+                    shape: this.seconds ? 'HH:mm:ss' : 'HH:mm',
+                }));
         }
         const rules = { disableTimes: this.disableTimes, max: this.max, min: this.min };
         const faults = held.map((one) => timeFault(one, rules));

package/dist/tree/item/tree-item.d.ts

@@ -14,9 +14,9 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * Each item is an element because it holds state: whether it is open, selected,
  * and focused.
  *
- * An item is a branch when something is slotted into `children`. This is
- * detected on the client, so server-rendered markup shows a leaf and the twisty
- * appears on hydration.
+ * An item is a branch when an item is slotted into `children`, with
+ * `slot="children"` on each nested item. This is detected on the client, so
+ * server-rendered markup shows a leaf and the twisty appears on hydration.
  *
  * **`href` makes the whole row a link**, rendered as an `<a>`. Enter, middle
  * click, and the status bar then work anywhere on the row.
@@ -43,7 +43,7 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * @aliases TreeNode, Branch, Leaf
  * @documentation https://fusion.dev/helix/components/tree
  *
- * @slot - The item's label.
+ * @slot - The item's label. A nested item does not go here: give it `slot="children"`. In a development build, an item nested here is reported.
  * @slot chevron - Replaces the expand and collapse mark of a branch, such as with your own icon.
  * @slot children - Nested items, which make this a branch.
  * @slot end - Content after the label, at the far side of the row, such as a count or a state.

package/dist/tree/item/tree-item.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, HelixLoadEvent, HelixSelectEvent, MixinControllerOpen, } from '@fusion.dev/helix-core';
+import { auditNesting, customElement, HelixElement, HelixLoadEvent, HelixSelectEvent, MixinControllerOpen, } from '@fusion.dev/helix-core';
 import { caretDown, check, dotsSixVertical, minus } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -68,6 +68,10 @@ let HelixHeadlessTreeItem = class HelixHeadlessTreeItem extends MixinControllerO
         slot?.addEventListener('slotchange', () => {
             this.branch = slot.assignedElements().length > 0;
         });
+        auditNesting(this, 'children');
+        this.renderRoot
+            .querySelector('[part="label"] > slot')
+            ?.addEventListener('slotchange', () => auditNesting(this, 'children'));
     }
     get choosable() {
         return this.value !== '' && !this.heads && !this.checkable && !this.disabled;