@fusion.dev/helix-headless 0.145.0 → 0.147.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.
@@ -71,8 +74,10 @@ declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fus
  * @csspart picker-column-search - The region that holds the filter field.
  * @csspart picker-column-search-field - The filter field.
  * @csspart picker-columns - The row of columns, in `wheels`.
+ * @csspart picker-feedback - The picker's own message, under the times, while the picker's `feedback` is set.
  * @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.
@@ -138,9 +143,12 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
     /**
      * Language tag the times are written in.
      *
-     * Absent uses the runtime's own.
+     * Absent is the page's: the `lang` of the nearest element with one, as
+     * Shoelace and Web Awesome read it, then the runtime's own.
      */
     locale: string;
+    /** The locale the words are written in: `locale`, or the page's `lang`. */
+    private get language();
     /**
      * Latest time that can be chosen, as `HH:mm`.
      */
@@ -272,7 +280,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

@@ -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 { AriaForwardController, valueAsTime as asTime, clockLocale, customElement, fillTemplate, timeAsValue as fromTime, HelixFormElement, isClockValue, MixinControllerOpen, MixinControllerValue, MixinField, MixinPickerEditing, MixinPickerField, MixinSegmentedField, MixinTokens, timeFault, writeClock, } from '@fusion.dev/helix-core';
+import { AriaForwardController, valueAsTime as asTime, clockLocale, customElement, fillTemplate, timeAsValue as fromTime, HelixFormElement, isClockValue, localeOf, MixinControllerOpen, MixinControllerValue, MixinField, MixinPickerEditing, MixinPickerField, MixinSegmentedField, MixinTokens, timeFault, writeClock, } from '@fusion.dev/helix-core';
 import { clock } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -88,6 +88,9 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
             }
         };
     }
+    get language() {
+        return localeOf(this, this.locale);
+    }
     get held() {
         return this.value
             .replace(/\s+[–-]\s+/g, ',')
@@ -102,7 +105,7 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
         return 'time';
     }
     get segmentLocale() {
-        return this.locale;
+        return this.language;
     }
     get segmentOptions() {
         return { hourCycle: this.hourCycle, seconds: this.seconds };
@@ -113,7 +116,7 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
     written(at) {
         return this.timeStyle === 'iso' || !this.isTime(at)
             ? at
-            : writeClock(at, clockLocale(this.locale, this.hourCycle), this.seconds);
+            : writeClock(at, clockLocale(this.language, this.hourCycle), this.seconds);
     }
     get display() {
         if (this.mode === 'multiple') {
@@ -152,14 +155,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.language, 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.language, this.hourCycle), this.seconds),
+                }),
+            ];
         }
         if (faults.includes('unavailable')) {
             return this.unavailableMessage || 'Choose a time that is available.';
@@ -178,13 +187,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,
+        column-search-field: picker-column-search-field, columns: picker-columns, feedback: picker-feedback, list: picker-list,
+        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,
@@ -200,7 +209,7 @@ let HelixHeadlessTimeInput = class HelixHeadlessTimeInput extends MixinSegmented
       manual
       label=${this.label || 'Time'}
       hour-cycle=${this.hourCycle ?? nothing}
-      locale=${this.locale || nothing}
+      locale=${this.language || nothing}
       max=${this.max}
       min=${this.min}
       ?seconds=${this.seconds}
@@ -285,7 +294,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

@@ -2,7 +2,7 @@ import { HelixFormElement, type HourCycle } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 import '../../listbox/index.js';
 import '../../option/index.js';
-declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
+declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinPickerFeedbackInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
  * @summary A control for choosing a time from a list or from wheels.
  *
@@ -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.
@@ -58,8 +59,10 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  * @csspart column-search - The region that holds the filter field.
  * @csspart column-search-field - The filter field.
  * @csspart columns - The row of columns, in `wheels`.
+ * @csspart feedback - The message under the times, while `feedback` is set.
  * @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.
@@ -78,6 +81,8 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  * @csspart option-item-selected - The row of a chosen time: the one time, or either end of a range.
  * @csspart option-label - The time's label.
  * @csspart option-text - The label and the caption, as one column.
+ *
+ * @cssstate invalid - While `invalid` is set or `feedback` says what is wrong.
  */
 export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_base {
     /**
@@ -112,18 +117,11 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     hourCycle?: HourCycle;
     /**
      * What the wheel of hours is called, read by screen readers.
-     */
-    hourLabel: string;
-    /**
-     * Whether the current selection fails validation.
      *
-     * A flag rather than a message, the same split Date Picker draws. A flat
-     * picker has no room of its own for a sentence: the field that wraps one owns
-     * the label, the hint and the feedback, and a second message inside the panel
-     * would be the same error said twice. What is left for the picker is the one
-     * thing the field cannot draw from outside, the mark on the answer itself.
+     * Absent is the locale's own word, from `Intl.DisplayNames`: "Hour" in
+     * English, "Stunde" in German.
      */
-    invalid: boolean;
+    hourLabel?: string;
     /**
      * Accessible name for the list, which has no visible one of its own.
      *
@@ -131,11 +129,14 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
      */
     label: string;
     /**
-     * Language tag the times are written in.
+     * Language tag the times and the wheels' names are written in.
      *
-     * Absent uses the runtime's own.
+     * Absent is the page's: the `lang` of the nearest element with one, as
+     * Shoelace and Web Awesome read it, then the runtime's own.
      */
     locale: string;
+    /** The locale the words are written in: `locale`, or the page's `lang`. */
+    private get language();
     /**
      * Stops the arrow keys in the list from choosing each time they move to.
      * Enter, Space or a click chooses.
@@ -151,16 +152,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 +329,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.
      *
@@ -446,7 +456,8 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     private listRevealed;
     /**
      * The list's name: the host's `aria-labelledby` read out, then its
-     * `aria-label`, then `label`.
+     * `aria-label`, then `label`, through core's `hostWords`, which Select reads
+     * its list's name through too.
      *
      * Read out as words, because the list is inside two shadow roots and an id on
      * the page reaches neither. Measured before this: `<helix-time-picker

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

@@ -4,25 +4,22 @@ 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 { clockLocale, commaList, customElement, dayPeriod, elementById, fillTemplate, HelixFormElement, inlineStep, isTwelveHour, MixinControllerValue, nearestTime, offeredTimes, reportValues, secondsAsValue, timeBarred, timeFault, valueAsSeconds, wheelParts, wholeHour, writeClock, } from '@fusion.dev/helix-core';
+import { clockLocale, commaList, customElement, dayPeriod, fillTemplate, HelixFormElement, hostWords, inlineStep, isTwelveHour, localeOf, MixinControllerValue, MixinPickerFeedback, nearestTime, offeredTimes, reportValues, secondsAsValue, timeBarred, timeFault, valueAsSeconds, wheelParts, wholeHour, writeClock, } from '@fusion.dev/helix-core';
 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) {
+let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinPickerFeedback(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 +74,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;
@@ -97,11 +93,14 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
             next.focus();
         };
     }
+    get language() {
+        return localeOf(this, this.locale);
+    }
     get times() {
         return offeredTimes(this.min, this.max, this.step, this.seconds);
     }
     get clock() {
-        return clockLocale(this.locale, this.hourCycle);
+        return clockLocale(this.language, this.hourCycle);
     }
     valueFor(at) {
         return secondsAsValue(at, this.seconds);
@@ -242,13 +241,7 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         this.reveal();
     }
     get listName() {
-        const named = (this.getAttribute('aria-labelledby') ?? '')
-            .split(/\s+/)
-            .filter(Boolean)
-            .map((id) => elementById(this, id)?.textContent?.trim() ?? '')
-            .filter(Boolean)
-            .join(' ');
-        return named || this.getAttribute('aria-label') || this.label;
+        return hostWords(this, this.label);
     }
     connectedCallback() {
         super.connectedCallback();
@@ -262,7 +255,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        this.internals.ariaInvalid = this.invalid ? 'true' : null;
         this.report();
     }
     updated(changed) {
@@ -285,8 +277,8 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         return html `<${this.tag('listbox')}
       part="column"
       data-column=${part}
-      aria-invalid=${this.invalid ? 'true' : nothing}
-      exportparts="empty: column-empty, feedback: column-feedback, filter-icon: column-filter-icon,
+      aria-invalid=${this.marked ? 'true' : nothing}
+      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,21 +315,21 @@ 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.language), 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.language), 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.language), 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.language), ['AM', 'PM'], (one) => dayPeriod(one, this.clock), meridiem, (one) => this.halfBarred(one))
             : nothing}
     </div>`;
     }
     renderList() {
         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,
+      aria-invalid=${this.marked ? 'true' : nothing}
+      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}
@@ -368,9 +360,9 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
     }
     render() {
         if (this.variant === 'wheels' && this.mode === undefined) {
-            return this.renderSpinner();
+            return html `${this.renderSpinner()}${this.renderPickerFeedback()}`;
         }
-        return html `${this.renderList()}`;
+        return html `${this.renderList()}${this.renderPickerFeedback()}`;
     }
     get valueAsDate() {
         const at = valueAsSeconds(this.value);
@@ -401,9 +393,6 @@ __decorate([
 __decorate([
     property({ attribute: 'hour-label' })
 ], HelixHeadlessTimePicker.prototype, "hourLabel", void 0);
-__decorate([
-    property({ reflect: true, type: Boolean })
-], HelixHeadlessTimePicker.prototype, "invalid", void 0);
 __decorate([
     property()
 ], HelixHeadlessTimePicker.prototype, "label", void 0);

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.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, hostAria } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, headingLevel, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 const HEADING_ID = 'heading';
@@ -18,7 +18,7 @@ let HelixHeadlessTimelineGroup = class HelixHeadlessTimelineGroup extends HelixE
         hostAria(this.internals, { role: 'listitem' });
     }
     render() {
-        const level = Math.min(6, Math.max(1, Math.trunc(this.headingLevel ?? 3)));
+        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>

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

@@ -13,9 +13,11 @@ 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
- * is its own assertive live region, so it is announced at once; every other one
- * is announced politely by the region.
+ * 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. The region
+ * says each message once as it arrives, a `danger` one assertively, so a
+ * message is never a live region of its own.
  *
  * A touch or a pen swipes a message toward the end of the line, and past
  * halfway, or quickly, dismisses it through the same `helix-dismiss` as its
@@ -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.
@@ -114,6 +120,13 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     connectedCallback(): 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.

package/dist/toast/item/toast-item.js

@@ -46,6 +46,17 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         this.handleResume = () => {
             this.countdown.release();
         };
+        this.name = () => {
+            const words = this.partNamed('content');
+            if (!words) {
+                return;
+            }
+            const heading = this.assigned('heading');
+            hostAria(this.internals, {
+                describedBy: this.assigned('description'),
+                labelledBy: heading.length > 0 ? heading : [words],
+            });
+        };
     }
     get open() {
         return this.openState ?? true;
@@ -93,14 +104,15 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         this.toggleAttribute('hidden', !this.open);
         hostAria(this.internals, { role: 'alertdialog' });
         this.internals.ariaModal = 'false';
-        this.internals.ariaLive = this.tone === 'danger' ? 'assertive' : null;
     }
     updated(changed) {
         super.updated(changed);
-        const words = this.partNamed('content');
-        if (words) {
-            hostAria(this.internals, { labelledBy: [words] });
-        }
+        this.name();
+    }
+    assigned(name) {
+        return (this.renderRoot
+            ?.querySelector(`slot[name="${name}"]`)
+            ?.assignedElements({ flatten: true }) ?? []);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
@@ -137,7 +149,11 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
               ${this.renderIcon(mark)}
             </span>`
             : nothing}
-      <div part="content"><slot></slot></div>
+      <div part="content">
+        <slot name="heading" part="heading" @slotchange=${this.name}></slot>
+        <slot name="description" part="description" @slotchange=${this.name}></slot>
+        <slot></slot>
+      </div>
       <div part="actions"><slot name="actions"></slot></div>
       ${this.dismissible
             ? drawDismiss({

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

@@ -9,10 +9,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * announce a region that arrives already holding its message. `Radio.Group` is
  * part of its family for the same reason.
  *
- * **The region is a landmark named by `label`, and a polite live region.** A
- * `danger` message is announced assertively, and every other one politely.
- * Each message is an `alertdialog` named by its words, so a reader who moves
- * into the stack hears which message they are on.
+ * **The region is a landmark named by `label`, and it says each message once
+ * as it arrives**: a `danger` message assertively, and every other one
+ * politely. It says the word for the tone, the heading, the description and
+ * the text, and not the actions, through two live regions of its own, the
+ * `live` parts, which it empties again a moment later. The stack itself is not
+ * a live region, so a message is never said twice, and changing the words of a
+ * message already showing says nothing. Each message is an `alertdialog` named
+ * by its words, so a reader who moves into the stack hears which message they
+ * are on.
  *
  * **`hotkey` takes focus to the stack and back**, F8 unless you set it, and
  * `label` says which key: `{hotkey}` in it is filled in, so the default name
@@ -54,6 +59,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @event {HelixDismissEvent} helix-dismiss - A message is being dismissed, by its control or by its timer. The message sends it, and you can listen for it on the region. Cancelable: canceling it keeps the message.
  *
+ * @csspart live - The two regions that say each message as it arrives, a polite `status` and an assertive `alert`, inside the stack. Empty at rest, and hide them with the standard clip, never `display: none`.
  * @csspart region - The stack the messages are in. It is in the top layer while a message shows, and takes focus from `hotkey` where no message holds a control.
  */
 export declare class HelixHeadlessToast extends HelixElement {
@@ -95,6 +101,24 @@ export declare class HelixHeadlessToast extends HelixElement {
      */
     placement?: 'bottom-center' | 'bottom-end' | 'bottom-start' | 'top-center' | 'top-end' | 'top-start';
     protected willUpdate(changed: PropertyValues): void;
+    /** What the polite region is saying. */
+    private said;
+    /** What the assertive region is saying. */
+    private urgent;
+    private readonly hush;
+    /**
+     * Says messages that have just arrived, each once, `danger` ones assertively.
+     *
+     * Emptied first and filled a frame later, so a message with the same words
+     * as the one before is still a change, and so a region the stack has just
+     * shown is in the accessibility tree before its words land.
+     */
+    private announce;
+    /**
+     * Says the messages that have just arrived: through the regions, or through
+     * `ariaNotify` where a modal dialog has made them inert.
+     */
+    private tell;
     /** The element focus came from when it entered the stack. */
     private focusOrigin;
     private readonly scope;
@@ -109,10 +133,16 @@ export declare class HelixHeadlessToast extends HelixElement {
      * stack, holding `message` as its text. The region removes it once it has
      * been dismissed and has finished leaving, which is the one case where it
      * removes anything: a message you render stays yours.
+     *
+     * `heading` gives the message a title, which names it, and `message` becomes
+     * the line of detail under it. `action` is an element for the message's
+     * `actions` slot, such as an Undo button you have wired up.
      */
     add(message: string, options?: {
+        action?: Element;
         dismissible?: boolean;
         duration?: number;
+        heading?: string;
         tone?: 'danger' | 'info' | 'success' | 'warning';
     }): HTMLElement;
     /** Removes a message `add()` made, once it has hidden and finished leaving. */