@fusion.dev/helix-headless 0.144.0 → 0.146.0

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

@@ -17,6 +17,11 @@ declare const HelixHeadlessTextarea_base: (new (...args: any[]) => import("@fusi
  * `max-rows` stops the growth at that many lines, and the field scrolls past
  * them.
  *
+ * `clearable` draws a button that empties the field while it holds text, and
+ * sends `helix-clear`, as `Input` does. `validate` adds your own rule, run on
+ * every change once the browser finds nothing wrong, as React Aria's
+ * TextField `validate` does.
+ *
  * @since 0.1.0
  * @status stable
  * @category forms
@@ -31,15 +36,18 @@ declare const HelixHeadlessTextarea_base: (new (...args: any[]) => import("@fusi
  *
  * @event {Event} change - Sent from the textarea when the user finishes an edit.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
+ * @event {HelixClearEvent} helix-clear - Fired after the clear button has emptied the field, after `input` and `change`.
  * @event {Event} input - Fired after the value changes.
  *
+ * @csspart clear - The button that empties the field, under `clearable`.
  * @csspart control - The textarea itself.
  * @csspart feedback - The message that says what is wrong.
  * @csspart field - The box that holds the textarea.
  * @csspart hint - Help under the field, while nothing is wrong.
  * @csspart label - The label above the field.
  *
- * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
+ * @cssstate blank - The field holds no text.
+ * @cssstate invalid - The control has an error to show, from the browser's validation, `validate`, or your `feedback`.
  */
 export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
     protected readonly aria: AriaForwardController;
@@ -57,6 +65,14 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      * Grows the box to fit its content, so it does not scroll.
      */
     autoGrow: boolean;
+    /**
+     * Draws a button that empties the field while it holds text.
+     */
+    clearable: boolean;
+    /**
+     * The accessible name of the clear button, which shows only an icon.
+     */
+    clearLabel: string;
     /**
      * How many characters wide the box is, when the layout does not set its
      * width.
@@ -194,6 +210,11 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
     focus(options?: FocusOptions): void;
     /** Reports the value and the validity the host stands behind. */
     private sync;
+    /**
+     * Empties the field and puts the caret back in it, through `requestValue`,
+     * so a consumer who owns the value can refuse. `Input` clears the same way.
+     */
+    private readonly handleClear;
     connectedCallback(): void;
     disconnectedCallback(): void;
     protected firstUpdated(changed: PropertyValues): void;
@@ -212,6 +233,12 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      * How many lines the box is before anything is typed.
      */
     rows: number;
+    /**
+     * Your own rule for the value, run on every change once the browser finds
+     * nothing wrong. Return a message, or a list of them, to mark the field
+     * invalid, and `true`, `null`, or nothing to accept the value.
+     */
+    validate?: (value: string) => string | string[] | true | null | undefined;
     /**
      * How the browser wraps the text, and whether the breaks are submitted with
      * it.

package/dist/textarea/root/textarea-root.js

@@ -4,7 +4,8 @@ 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, customElement, HelixFormElement, holdCaret, isRtl, MixinControllerValue, MixinField, restoreValue, } from '@fusion.dev/helix-core';
+import { AriaForwardController, customElement, drawIcon, HelixClearEvent, HelixFormElement, holdCaret, isRtl, MixinControllerValue, MixinField, restoreValue, } from '@fusion.dev/helix-core';
+import { x } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { grownHeight, lineMetrics } from '../grow.js';
@@ -17,6 +18,8 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
         this.announcesInput = true;
         this.autocomplete = '';
         this.autoGrow = false;
+        this.clearable = false;
+        this.clearLabel = 'Clear';
         this.dirName = '';
         this.placeholder = '';
         this.readOnly = false;
@@ -32,6 +35,17 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
             event.stopPropagation();
             this.announceChange();
         };
+        this.handleClear = () => {
+            if (this.value !== '' && this.requestValue('')) {
+                this.announceChange();
+                this.dispatchEvent(new HelixClearEvent());
+            }
+            const control = this.control;
+            if (control) {
+                restoreValue(control, this.value);
+                control.focus();
+            }
+        };
         this.rows = 3;
         this.wrap = 'soft';
     }
@@ -112,6 +126,11 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
             return;
         }
         this.copyValidity(control);
+        const own = control.validity.valid ? this.validate?.(this.value) : undefined;
+        const message = Array.isArray(own) ? own.join(' ') : typeof own === 'string' ? own : '';
+        if (message !== '') {
+            this.internals.setValidity({ customError: true }, message, control);
+        }
         this.refreshFeedback();
     }
     connectedCallback() {
@@ -140,6 +159,7 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
     }
     willUpdate(changed) {
         super.willUpdate(changed);
+        this.toggleState('blank', this.value === '');
         if (!this.hasUpdated) {
             return;
         }
@@ -180,6 +200,16 @@ let HelixHeadlessTextarea = class HelixHeadlessTextarea extends MixinControllerV
         @change=${this.handleChange}
       ></textarea>
       <slot name="end"></slot>
+      ${this.clearable && this.value !== '' && !this.isDisabled && !this.readOnly
+            ? html `<button
+              part="clear"
+              type="button"
+              aria-label=${this.clearLabel}
+              @click=${this.handleClear}
+            >
+              ${drawIcon(x)}
+            </button>`
+            : nothing}
     </div>
     ${this.renderHint()}${this.renderFeedback()}`;
     }
@@ -190,6 +220,12 @@ __decorate([
 __decorate([
     property({ attribute: 'auto-grow', reflect: true, type: Boolean })
 ], HelixHeadlessTextarea.prototype, "autoGrow", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessTextarea.prototype, "clearable", void 0);
+__decorate([
+    property({ attribute: 'clear-label' })
+], HelixHeadlessTextarea.prototype, "clearLabel", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessTextarea.prototype, "cols", void 0);
@@ -214,6 +250,9 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessTextarea.prototype, "rows", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessTextarea.prototype, "validate", void 0);
 __decorate([
     property()
 ], HelixHeadlessTextarea.prototype, "wrap", void 0);

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

@@ -42,6 +42,8 @@ declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fus
  *
  * @slot feedback - The message that says what is wrong with the value.
  * @slot hint - Help under the field.
+ * @slot panel-footer - Content in the panel under the times, such as a note or an action.
+ * @slot panel-header - Content in the panel above the times, such as a heading or a shortcut.
  * @slot trigger - The icon on the field that shows a list opens.
  *
  * @event {Event} change - Fired after the value changes.
@@ -60,6 +62,7 @@ declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fus
  * @csspart picker - The time picker inside the panel.
  * @csspart picker-column - One column of the picker.
  * @csspart picker-column-empty - The text shown when the filter hides every option.
+ * @csspart picker-column-error - A wheel's `error` part, which the list never sets: its times do not load.
  * @csspart picker-column-feedback - The column's message that says what is wrong with the value.
  * @csspart picker-column-filter-icon - The icon beside the filter field.
  * @csspart picker-column-filter-mark - The default icon beside the filter field, shown when none is slotted.
@@ -73,6 +76,7 @@ declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fus
  * @csspart picker-columns - The row of columns, in `wheels`.
  * @csspart picker-list - The listbox holding the times, in `list`.
  * @csspart picker-list-empty - The text shown when the filter hides every option.
+ * @csspart picker-list-error - The list's `error` part, which the list never sets: its times do not load.
  * @csspart picker-list-feedback - The inner list's message that says what is wrong with the value.
  * @csspart picker-list-filter-icon - The icon beside the filter field.
  * @csspart picker-list-filter-mark - The default icon beside the filter field, shown when none is slotted.
@@ -272,7 +276,7 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
     /** Each time, where `mode` holds several, sent one entry each. */
     protected get answers(): readonly string[] | undefined;
     /** What is wrong with the times, which the text input cannot say. */
-    protected validate(): string;
+    protected validate(): string | readonly [keyof ValidityStateFlags, string];
     /**
      * Whether the panel shows one list of times or a column for each part of the
      * time.

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

@@ -152,14 +152,20 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
         const rules = { disableTimes: this.disableTimes, max: this.max, min: this.min };
         const faults = held.map((one) => timeFault(one, rules));
         if (faults.includes('rangeUnderflow')) {
-            return fillTemplate(this.rangeUnderflowMessage || 'Choose a time at or after {min}.', {
-                min: writeClock(this.min, clockLocale(this.locale, this.hourCycle), this.seconds),
-            });
+            return [
+                'rangeUnderflow',
+                fillTemplate(this.rangeUnderflowMessage || 'Choose a time at or after {min}.', {
+                    min: writeClock(this.min, clockLocale(this.locale, this.hourCycle), this.seconds),
+                }),
+            ];
         }
         if (faults.includes('rangeOverflow')) {
-            return fillTemplate(this.rangeOverflowMessage || 'Choose a time at or before {max}.', {
-                max: writeClock(this.max, clockLocale(this.locale, this.hourCycle), this.seconds),
-            });
+            return [
+                'rangeOverflow',
+                fillTemplate(this.rangeOverflowMessage || 'Choose a time at or before {max}.', {
+                    max: writeClock(this.max, clockLocale(this.locale, this.hourCycle), this.seconds),
+                }),
+            ];
         }
         if (faults.includes('unavailable')) {
             return this.unavailableMessage || 'Choose a time that is available.';
@@ -178,13 +184,13 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
     renderPicker() {
         return html `<${this.tag('time-picker')}
       part="picker"
-      exportparts="column: picker-column, column-empty: picker-column-empty,
+      exportparts="column: picker-column, column-empty: picker-column-empty, column-error: picker-column-error,
         column-feedback: picker-column-feedback, column-filter-icon: picker-column-filter-icon,
         column-filter-mark: picker-column-filter-mark, column-hint: picker-column-hint,
         column-items: picker-column-items, column-label: picker-column-label,
         column-live: picker-column-live, column-loading: picker-column-loading, column-search: picker-column-search,
         column-search-field: picker-column-search-field, columns: picker-columns, list: picker-list,
-        list-empty: picker-list-empty, list-feedback: picker-list-feedback,
+        list-empty: picker-list-empty, list-error: picker-list-error, list-feedback: picker-list-feedback,
         list-filter-icon: picker-list-filter-icon, list-filter-mark: picker-list-filter-mark,
         list-hint: picker-list-hint, list-items: picker-list-items, list-label: picker-list-label,
         list-live: picker-list-live, list-loading: picker-list-loading, list-search: picker-list-search,
@@ -285,7 +291,9 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
         ?hidden=${!this.open}
         @keydown=${this.handleWheelEnter}
       >
+        <slot name="panel-header"></slot>
         ${this.renderPicker()}
+        <slot name="panel-footer"></slot>
       </div>
       ${this.renderHint()}${this.renderFeedback()}`;
     }

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

@@ -47,6 +47,7 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  *
  * @csspart column - One column of the wheels.
  * @csspart column-empty - The text shown when the filter hides every option.
+ * @csspart column-error - A wheel's `error` part, which Time Picker never sets: its times do not load.
  * @csspart column-feedback - The message that says what is wrong with the value.
  * @csspart column-filter-icon - The icon beside the filter field.
  * @csspart column-filter-mark - The default icon beside the filter field, shown when none is slotted.
@@ -60,6 +61,7 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  * @csspart columns - The row of columns, in `wheels`.
  * @csspart list - The listbox holding the times, in `list`.
  * @csspart list-empty - The text shown when the filter hides every option.
+ * @csspart list-error - The list's `error` part, which Time Picker never sets: its times do not load.
  * @csspart list-feedback - The message that says what is wrong with the value.
  * @csspart list-filter-icon - The icon beside the filter field.
  * @csspart list-filter-mark - The default icon beside the filter field, shown when none is slotted.
@@ -112,8 +114,11 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     hourCycle?: HourCycle;
     /**
      * What the wheel of hours is called, read by screen readers.
+     *
+     * Absent is the locale's own word, from `Intl.DisplayNames`: "Hour" in
+     * English, "Stunde" in German.
      */
-    hourLabel: string;
+    hourLabel?: string;
     /**
      * Whether the current selection fails validation.
      *
@@ -151,16 +156,22 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     /**
      * What the wheel of the half of the day is called, read by screen readers.
      * Its two options are written as the locale writes them, such as AM and PM.
+     *
+     * Absent is the locale's own word, from `Intl.DisplayNames`: "AM/PM" in
+     * English, "Tageshälfte" in German.
      */
-    meridiemLabel: string;
+    meridiemLabel?: string;
     /**
      * Earliest time offered, as `HH:mm`.
      */
     min: string;
     /**
      * What the wheel of minutes is called, read by screen readers.
+     *
+     * Absent is the locale's own word, from `Intl.DisplayNames`: "Minute" in
+     * English and German, "分" in Japanese.
      */
-    minuteLabel: string;
+    minuteLabel?: string;
     /**
      * How many times can be held at once.
      *
@@ -322,8 +333,11 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     required: boolean;
     /**
      * What the wheel of seconds is called, read by screen readers.
+     *
+     * Absent is the locale's own word, from `Intl.DisplayNames`: "Second" in
+     * English, "Sekunde" in German.
      */
-    secondLabel: string;
+    secondLabel?: string;
     /**
      * Whether times carry their seconds.
      *

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

@@ -8,21 +8,19 @@ import { clockLocale, commaList, customElement, dayPeriod, elementById, fillTemp
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
+import { wheelName } from '../wheel-name.js';
 import '../../listbox/index.js';
 import '../../option/index.js';
 let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControllerValue(HelixFormElement) {
     constructor() {
         super(...arguments);
         this.disableTimes = '';
-        this.hourLabel = 'Hour';
         this.invalid = false;
         this.label = 'Time';
         this.locale = '';
         this.manual = false;
         this.max = '23:59';
-        this.meridiemLabel = 'Before or after noon';
         this.min = '00:00';
-        this.minuteLabel = 'Minute';
         this.handleListInput = (event) => {
             event.stopPropagation();
         };
@@ -77,7 +75,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         };
         this.readOnly = false;
         this.required = false;
-        this.secondLabel = 'Second';
         this.seconds = false;
         this.step = 15;
         this.listRevealed = false;
@@ -286,7 +283,7 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
       part="column"
       data-column=${part}
       aria-invalid=${this.invalid ? 'true' : nothing}
-      exportparts="empty: column-empty, feedback: column-feedback, filter-icon: column-filter-icon,
+      exportparts="empty: column-empty, error: column-error, feedback: column-feedback, filter-icon: column-filter-icon,
         filter-mark: column-filter-mark, hint: column-hint, items: column-items, label: column-label,
         live: column-live, loading: column-loading, search: column-search, search-field: column-search-field"
       aria-label=${label}
@@ -323,13 +320,13 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
       data-unset=${this.value === '' ? '' : nothing}
       @keydown=${this.handleColumnsKeydown}
     >
-      ${this.renderColumn('hour', this.hourLabel, hours.map(String), (one) => (twelve ? one : one.padStart(2, '0')), String(shown), (one) => this.wholeHourBarred(Number(one), twelve ? meridiem : undefined))}
-      ${this.renderColumn('minute', this.minuteLabel, this.minutes.map(String), (one) => one.padStart(2, '0'), String(minute), (one) => this.barredAt(hour * 3600 + Number(one) * 60))}
+      ${this.renderColumn('hour', this.hourLabel ?? wheelName('hour', this.locale), hours.map(String), (one) => (twelve ? one : one.padStart(2, '0')), String(shown), (one) => this.wholeHourBarred(Number(one), twelve ? meridiem : undefined))}
+      ${this.renderColumn('minute', this.minuteLabel ?? wheelName('minute', this.locale), this.minutes.map(String), (one) => one.padStart(2, '0'), String(minute), (one) => this.barredAt(hour * 3600 + Number(one) * 60))}
       ${this.seconds
-            ? this.renderColumn('second', this.secondLabel, this.secondsShown.map(String), (one) => one.padStart(2, '0'), String(second), (one) => this.barredAt(hour * 3600 + minute * 60 + Number(one)))
+            ? this.renderColumn('second', this.secondLabel ?? wheelName('second', this.locale), this.secondsShown.map(String), (one) => one.padStart(2, '0'), String(second), (one) => this.barredAt(hour * 3600 + minute * 60 + Number(one)))
             : nothing}
       ${twelve
-            ? this.renderColumn('meridiem', this.meridiemLabel, ['AM', 'PM'], (one) => dayPeriod(one, this.clock), meridiem, (one) => this.halfBarred(one))
+            ? this.renderColumn('meridiem', this.meridiemLabel ?? wheelName('dayPeriod', this.locale), ['AM', 'PM'], (one) => dayPeriod(one, this.clock), meridiem, (one) => this.halfBarred(one))
             : nothing}
     </div>`;
     }
@@ -337,7 +334,7 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         return html `<${this.tag('listbox')}
       part="list"
       aria-invalid=${this.invalid ? 'true' : nothing}
-      exportparts="empty: list-empty, feedback: list-feedback, filter-icon: list-filter-icon,
+      exportparts="empty: list-empty, error: list-error, feedback: list-feedback, filter-icon: list-filter-icon,
         filter-mark: list-filter-mark, hint: list-hint, items: list-items, label: list-label,
         live: list-live, loading: list-loading, search: list-search, search-field: list-search-field"
       aria-label=${this.listName}

package/dist/time-picker/wheel-name.d.ts

@@ -0,0 +1,9 @@
+/** A part of the time a Time Picker wheel sets. */
+export type WheelField = 'dayPeriod' | 'hour' | 'minute' | 'second';
+/**
+ * What a locale calls a wheel, core's `segmentName`, with its first letter in
+ * capitals as a name standing on its own: "Hour" in English, "Stunde" in
+ * German, "時" in Japanese, and "AM/PM" for the half of the day, React Aria's
+ * name for it.
+ */
+export declare const wheelName: (field: WheelField, locale: string) => string;

package/dist/time-picker/wheel-name.js

@@ -0,0 +1,15 @@
+import { segmentName } from '@fusion.dev/helix-core';
+const ENGLISH = {
+    dayPeriod: 'AM/PM',
+    hour: 'Hour',
+    minute: 'Minute',
+    second: 'Second',
+};
+export const wheelName = (field, locale) => {
+    const name = segmentName(field, locale);
+    if (name === field || name === '') {
+        return ENGLISH[field];
+    }
+    const lead = String.fromCodePoint(name.codePointAt(0));
+    return `${lead.toLocaleUpperCase(locale || undefined)}${name.slice(lead.length)}`;
+};

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

@@ -0,0 +1,46 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A run of timeline entries under a heading, such as a day.
+ *
+ * @description
+ * Groups entries by date, such as "Today" and "Yesterday", in a timeline that
+ * holds many. The group is an entry of the timeline, and its entries are a
+ * list of their own, named by the heading. A screen reader lists the heading
+ * with the page's headings and hears how many entries each day holds.
+ *
+ * The heading's level is `heading-level`, and 3 where it is not set.
+ *
+ * Each group draws its own line, so the line stops at the last entry of one
+ * day and starts again at the first entry of the next.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Day, Section, Date group
+ * @documentation https://fusion.dev/helix/components/timeline
+ *
+ * @slot - The entries.
+ * @slot heading - The heading, when it is more than text. Falls back to `label`.
+ *
+ * @csspart entries - The list that holds the entries.
+ * @csspart heading - The heading.
+ */
+export declare class HelixHeadlessTimelineGroup extends HelixElement {
+    /**
+     * The level of the group's heading, from 1 to 6.
+     */
+    headingLevel?: number;
+    /**
+     * The heading, when it is plain text, such as "Today".
+     *
+     * The fallback of the `heading` slot, so slotted content replaces it.
+     */
+    label: string;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-timeline-group': HelixHeadlessTimelineGroup;
+    }
+}

package/dist/timeline/group/timeline-group.js

@@ -0,0 +1,37 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    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, headingLevel, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+const HEADING_ID = 'heading';
+let HelixHeadlessTimelineGroup = class HelixHeadlessTimelineGroup extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { role: 'listitem' });
+    }
+    render() {
+        const level = headingLevel(this.headingLevel);
+        return html `<div part="heading" id=${HEADING_ID} role="heading" aria-level=${level}>
+        <slot name="heading">${this.label}</slot>
+      </div>
+      <div part="entries" role="list" aria-labelledby=${HEADING_ID}><slot></slot></div>`;
+    }
+};
+__decorate([
+    property({ attribute: 'heading-level', type: Number })
+], HelixHeadlessTimelineGroup.prototype, "headingLevel", void 0);
+__decorate([
+    property()
+], HelixHeadlessTimelineGroup.prototype, "label", void 0);
+HelixHeadlessTimelineGroup = __decorate([
+    customElement('helix-headless-timeline-group')
+], HelixHeadlessTimelineGroup);
+export { HelixHeadlessTimelineGroup };

package/dist/timeline/index.d.ts

@@ -1,2 +1,3 @@
+export * from './group/timeline-group.js';
 export * from './item/timeline-item.js';
 export * from './root/timeline-root.js';

package/dist/timeline/index.js

@@ -1,2 +1,3 @@
+export * from './group/timeline-group.js';
 export * from './item/timeline-item.js';
 export * from './root/timeline-root.js';

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

@@ -16,8 +16,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * The host has `role="list"`, because the entries are your elements in the
  * light DOM. `Steps` does the same.
  *
- * A timeline runs down the page and has no horizontal layout. For stages laid
- * out horizontally, use `Steps`, which is horizontal by default.
+ * **Group entries by date with `Timeline.Group`**, which puts a heading such as
+ * "Today" over its entries. The group is an entry of the timeline, and its
+ * entries are a list of their own named by the heading.
+ *
+ * **The reading order is the order you write the entries in**, in every layout
+ * the styled tier draws: down the page, either side of a line down the middle,
+ * or across the page. Inside each entry the time is read before what happened.
+ * Write the entries in the order the events happened, oldest or newest first,
+ * and the layout only moves where they are drawn.
  *
  * @since 0.1.0
  * @status stable
@@ -25,7 +32,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Activity feed, History, Changelog, Audit trail
  * @documentation https://fusion.dev/helix/components/timeline
  *
- * @slot - The entries.
+ * @slot - The entries, and any groups of them.
  */
 export declare class HelixHeadlessTimeline extends HelixElement {
     /**

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

@@ -13,7 +13,9 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  * seconds.
  *
  * **Each message is an `alertdialog` named by its words**, which is how a reader
- * who moves into the stack hears which message they are on. A `danger` message
+ * who moves into the stack hears which message they are on. Give it a
+ * `heading` and a `description`, and the heading names it and the description
+ * describes it, for a message with a title and a line of detail. A `danger` message
  * is its own assertive live region, so it is announced at once; every other one
  * is announced politely by the region.
  *
@@ -31,7 +33,9 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  *
  * @slot - The message.
  * @slot actions - Actions for the message, usually a button or a link.
+ * @slot description - A line of detail under the heading, which describes the message.
  * @slot dismiss-icon - Replaces the glyph inside the dismiss control.
+ * @slot heading - The message's title, which names it.
  * @slot icon - Replaces the tone mark. The name matches `Callout`. The dismiss
  *   control's glyph uses `dismiss-icon`, because two slots cannot share a name:
  *   content goes to whichever slot comes first in the tree, and the tone mark is
@@ -41,8 +45,10 @@ declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fus
  *
  * @csspart actions - The region that holds the actions.
  * @csspart content - The message.
+ * @csspart description - The slot the description is in. It draws no box until you give it one.
  * @csspart dismiss - The control that dismisses the message.
  * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart heading - The slot the heading is in. It draws no box until you give it one.
  * @csspart icon - The tone mark, where the message has one.
  * @csspart icon-mark - The tone glyph, where none is slotted.
  * @csspart item - The message's own surface.
@@ -78,11 +84,16 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     protected readonly swipes: SwipeController;
     /** Writes how far a swipe has moved the message toward the end of the line. */
     private slide;
-    /** When the current run of the timer began, or nothing while it is paused. */
-    private startedAt;
-    /** What is left of the duration, so resuming continues rather than restarts. */
-    private remaining;
-    private timer;
+    /**
+     * The dismiss timer, which pauses while a reader is on the message and
+     * continues from what was left.
+     *
+     * Paused is said on the host so the indicator can freeze with the clock. A
+     * `data-` attribute rather than a property, because it is written after
+     * upgrade from a pointer moving: nothing declares it and no server rendered
+     * it, which is the same reason `Carousel` names its slides from here.
+     */
+    private readonly countdown;
     /**
      * The kind of message, which sets its mark and the mark's accessible name.
      *
@@ -104,23 +115,18 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     pause(): void;
     /** Restarts the dismiss timer from where it paused. */
     resume(): void;
-    /**
-     * How many reasons there are to hold the clock, rather than whether there is
-     * one.
-     *
-     * Hover and focus stop the same timer, and the two are genuinely independent:
-     * a pointer can leave while focus stays, and focus can leave while the
-     * pointer stays. Uncounted, a reader who tabs into a message and then moves
-     * the pointer off it has the clock restarted underneath them, which is the
-     * case the pause exists for. Only the last one out starts it again.
-     */
-    private holds;
     private readonly handlePause;
     private readonly handleResume;
     connectedCallback(): void;
-    disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
+    /** The elements assigned to one of the message's named slots. */
+    private assigned;
+    /**
+     * Names the message by its heading and describes it by its description,
+     * where it has them, and otherwise names it by all its words.
+     */
+    private readonly name;
     protected firstUpdated(changed: PropertyValues): void;
     /**
      * The mark for the message's tone, behind a seam.