@fusion.dev/helix-headless 0.104.1 → 0.106.0

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

@@ -5,25 +5,23 @@ import '../../tag/index.js';
 import '../../time-picker/index.js';
 declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinPickerEditingInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinPickerFieldInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinTokensInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary A time, typed or picked from a list.
+ * @summary A field for a time, typed or picked from a list.
  *
  * @description
- * **The list is `TimePicker`, not a second one written here.** It is worth
- * having on its own, flat in a settings pane with nothing to open, and this
- * element is the field, the overlay and the form. Exactly the arrangement Input
- * Date has with `DatePicker` and Color Input with `ColorPicker`.
+ * The list is a `TimePicker`, which you can also use on its own, for example in
+ * a settings pane. This element adds the field, the overlay, and the form
+ * association, the same arrangement Date Input has with `DatePicker` and Color
+ * Input has with `ColorPicker`.
  *
- * **Typed as well as picked, and that is the division the list depends on.** A
- * list at a step offers the times a product actually has, and the field is how a
- * reader says `09:07`. Neither is a worse version of the other: without the
- * field a step is a cage, and without the list every common time is typed out.
+ * You can type a time or pick one. The list offers times at a step, and the
+ * field lets you enter any time, such as `09:07`.
  *
- * **The value is `HH:mm` on a twenty-four hour clock, always**, because that is
- * what a form submits, what `min` and `max` compare against, and what sorts as a
- * string. What the field *shows* is the reader's own convention while it is
- * idle, and the value itself once the caret is in it: the same separation Input
- * Date draws, and for the same reason, which is that `2:30 PM` cannot be typed
- * back and `Intl` has no parser to make it so.
+ * The value is always `HH:mm` on a 24-hour clock, because that is what the form
+ * submits, what `min` and `max` compare against, and what sorts correctly as a
+ * string. While idle, the field shows the time in the user's locale format.
+ * Once the caret is in the field, it shows the value itself, because a
+ * formatted time such as `2:30 PM` cannot be typed back and `Intl` has no
+ * parser for it.
  *
  * @since 0.1.0
  * @status stable
@@ -31,67 +29,67 @@ declare const HelixHeadlessTimeInput_base: (new (...args: any[]) => import("@fus
  * @aliases TimeField, InputTime
  * @documentation https://fusion.dev/helix/components/time-input
  *
- * @slot feedback - What is wrong with it.
+ * @slot feedback - The message that says what is wrong with the value.
  * @slot hint - Help under the field.
- * @slot trigger - The mark on the field saying a list opens.
+ * @slot trigger - The icon on the field that shows a list opens.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes. Cancelable: canceling it stops the change and leaves the decision to you.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the list closes. Cancelable: canceling it keeps the list open and leaves the decision to you.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the list opens. Cancelable: canceling it keeps the list closed and leaves the decision to you.
+ * @event {Event} input - Fired after the value changes.
+ * @event {Event} toggle - Fired after the list opens or closes, with `newState` and `oldState`.
  *
  * @csspart control - The text input.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding the text and the trigger.
+ * @csspart feedback - The message that says what is wrong with the value.
+ * @csspart field - The box that holds the text and the trigger.
  * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- * @csspart picker - The list inside it.
- * @csspart picker-column - One of them.
- * @csspart picker-column-empty - Shown when a filter has hidden everything.
- * @csspart picker-column-feedback - What is wrong with it.
- * @csspart picker-column-filter-icon - The mark beside that field.
- * @csspart picker-column-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart label - The label above the field.
+ * @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-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.
  * @csspart picker-column-hint - Help under the list.
- * @csspart picker-column-items - The list itself.
- * @csspart picker-column-label - The question, over the list.
- * @csspart picker-column-live - The inner column's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart picker-column-loading - Shown while the options are still on their way.
- * @csspart picker-column-search - The region holding the field that narrows the list.
- * @csspart picker-column-search-field - The field itself.
+ * @csspart picker-column-items - The list of options.
+ * @csspart picker-column-label - The label above the list.
+ * @csspart picker-column-live - The inner column's `live` part, the region screen readers announce its empty and loading text from.
+ * @csspart picker-column-loading - The text shown while the options load.
+ * @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-list - The listbox holding the times, in `list`.
- * @csspart picker-list-empty - Shown when a filter has hidden everything.
- * @csspart picker-list-feedback - What is wrong with it.
- * @csspart picker-list-filter-icon - The mark beside that field.
- * @csspart picker-list-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart picker-list-empty - The text shown when the filter hides every option.
+ * @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.
  * @csspart picker-list-hint - Help under the list.
- * @csspart picker-list-items - The list itself.
- * @csspart picker-list-label - The question, over the list.
- * @csspart picker-list-live - The inner list's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart picker-list-loading - Shown while the options are still on their way.
- * @csspart picker-list-search - The region holding the field that narrows the list.
- * @csspart picker-list-search-field - The field itself.
- * @csspart picker-option - One time in it. Carries `data-between` inside a range.
- * @csspart picker-option-between - A time inside a chosen range, short of either end, beside `picker-option`.
- * @csspart picker-option-description - The caption under the words, when there is one.
+ * @csspart picker-list-items - The list of options.
+ * @csspart picker-list-label - The label above the list.
+ * @csspart picker-list-live - The inner list's `live` part, the region screen readers announce its empty and loading text from.
+ * @csspart picker-list-loading - The text shown while the options load.
+ * @csspart picker-list-search - The region that holds the filter field.
+ * @csspart picker-list-search-field - The filter field.
+ * @csspart picker-option - One time in the picker. Carries `data-between` inside a range.
+ * @csspart picker-option-between - A time inside a chosen range, between its two ends. Set together with `picker-option`.
+ * @csspart picker-option-description - The caption under the label, when there is one.
  * @csspart picker-option-item - The row.
  * @csspart picker-option-item-active - The row the keyboard is on.
  * @csspart picker-option-item-selected - The row of a chosen time: the one time, or either end of a range.
- * @csspart picker-option-label - The words.
- * @csspart picker-option-text - The words and the caption, as one column.
- * @csspart rest - How many times are held beyond the ones shown. A `<button>` with `expandable`, a `<span>` without it.
+ * @csspart picker-option-label - The option's label.
+ * @csspart picker-option-text - The label and the caption, as one column.
+ * @csspart rest - The count of times held beyond the ones shown. A `<button>` with `expandable`, and a `<span>` without it.
  * @csspart surface - The floating panel.
  * @csspart tags - The row the times sit in.
  * @csspart time - One held time, as a tag, in `multiple`.
  * @csspart time-dismiss - The remove button, when `dismissible`.
- * @csspart time-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart time-dismiss-mark - The default icon on the remove button, shown when none is slotted.
  * @csspart time-start - The category before the label.
  * @csspart trigger - The control that opens the list.
- * @csspart trigger-icon - The mark on the button that opens the clock.
+ * @csspart trigger-icon - The icon on the button that opens the clock.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  * @cssstate open - While the clock is open.
  */
 export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base {
@@ -118,7 +116,7 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      */
     min: string;
     /**
-     * How many times can be held at once.
+     * How many times the field holds at once.
      *
      * Absent is one. `range` holds a start and an end, `multiple` holds any
      * number, and both are carried as one comma-separated value, which is what a
@@ -127,11 +125,11 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      */
     mode?: 'multiple' | 'range';
     /**
-     * What the field says before a time is in it.
+     * Placeholder text shown before a time is entered.
      */
     placeholder: string;
     /**
-     * What a reader is told when a range holds more than two times.
+     * The message shown when a range holds more than two times.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * so a form in another language speaks it. Absent is the control's own
@@ -139,17 +137,17 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      */
     rangeLengthMessage?: string;
     /**
-     * What a reader is told when a time is after `max`, with `{max}` filled in
-     * as the field writes it.
+     * The message shown when a time is after `max`, with `{max}` filled in as
+     * the field displays it.
      */
     rangeOverflowMessage?: string;
     /**
-     * What a reader is told when a time is before `min`, with `{min}` filled
-     * in as the field writes it.
+     * The message shown when a time is before `min`, with `{min}` filled in as
+     * the field displays it.
      */
     rangeUnderflowMessage?: string;
     /**
-     * What the control removing one time is called, with `{name}` filled in.
+     * The name of the button that removes one time, with `{name}` filled in.
      *
      * **The name goes in**, so a row of them is heard as which one each
      * removes rather than as "Remove" said once per time.
@@ -160,7 +158,8 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      */
     step: number;
     /**
-     * Whether the field writes the time out, or holds the value as it is.
+     * Whether the field shows the time in the local style or as the value
+     * itself.
      *
      * `local` is the reader's own convention from `Intl`, which is what a time is
      * for reading; `iso` is `HH:mm`, which is what it is for typing. The field
@@ -169,7 +168,7 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
      */
     timeStyle: 'iso' | 'local';
     /**
-     * Accessible name for the control that opens the list.
+     * The name of the button that opens the list, read by screen readers.
      */
     triggerLabel: string;
     /** Every time in the value, which may hold more than one. */
@@ -209,7 +208,8 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
     /** What is wrong with the times, which the text input cannot say. */
     protected validate(): string;
     /**
-     * Whether the panel is one list of times or a column each.
+     * Whether the panel shows one list of times or a column for each part of the
+     * time.
      *
      * `list` offers whole times, which is what a product with slots or opening
      * hours has. `wheels` splits them into an hour, a minute and a meridiem where
@@ -259,7 +259,8 @@ export declare class HelixHeadlessTimeInput extends HelixHeadlessTimeInput_base
     protected renderTrigger(): TemplateResult;
     protected render(): TemplateResult;
     /**
-     * The value as a `Date` on 1 January 1970 UTC, or `null` while there is no time.
+     * The value as a `Date` on January 1, 1970 UTC, or `null` while there is no
+     * time.
      *
      * The platform's own pair on `<input type="time">`, epoch day included: a time
      * is an offset into a day rather than an instant, and putting it on the epoch

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

@@ -4,40 +4,31 @@ import '../../listbox/index.js';
 import '../../option/index.js';
 declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
- * @summary Picks a time, from a list of them.
+ * @summary A control for choosing a time from a list or from wheels.
  *
  * @description
- * **A list rather than three wheels**, and the reason is what a list already
- * is. `Listbox` brings the keyboard, the typeahead, the scroll into view and
- * the announcement of a set of options, and a time at a step is a set of
- * options. Three little wheels for hours, minutes and a meridiem are three
- * controls to build, three to test, and a tab stop each for something a reader
- * answers once.
+ * Shows the times at each `step` as a `Listbox`, which provides the keyboard
+ * behavior, typeahead, scrolling into view, and announcements for a set of
+ * options. `variant="wheels"` shows a column each for the hour, the minute, and
+ * the meridiem.
  *
- * **A step is what makes it a list at all.** Fifteen minutes is ninety-six rows,
- * which a reader scrolls or types into; one minute is one thousand four hundred
- * and forty, which is a listbox in name only. So the list is for the times a
- * product actually offers, and arbitrary times are the field's job in Input
- * Time, the same division Date Input draws between typing a date and using the
- * calendar.
+ * The step keeps the list usable. At the default of 15 minutes a day is 96
+ * rows, which people can scroll or type into. At 1 minute it is 1,440. Use the
+ * list for the times your product offers, and Time Input for any time, the same
+ * way Date Input separates typing a date from picking one on the calendar.
  *
- * **The value is `HH:mm` on a twenty-four hour clock, always.** That is what a
- * form submits and what `min` and `max` compare against, and it sorts as a
- * string, which is the whole reason the shape is that one. What each row *says*
- * is the reader's own convention, from `Intl`.
+ * The value is always `HH:mm` on a 24-hour clock. A form submits that shape,
+ * `min` and `max` compare against it, and it sorts as a string. Each row's text
+ * follows the person's own conventions, from `Intl`.
  *
- * **The chosen row is marked in the markup, not worked out on upgrade.** The
- * listbox is handed the answer as `.value`, and lit-ssr serializes no property
- * binding, so a served `value="09:30"` shipped ninety-six rows with nothing on
- * any of them saying which one it was: the mark arrived when the listbox
- * upgraded and ran `place`. So each option is given `selected` as well, which
- * is an attribute binding and does serve, and which the listbox then agrees
- * with rather than fights, `place` writing the same answer from the same value.
- * `selected` is the declaration a consumer writes on `Option` anywhere else in
- * the library, and Date Picker expresses its own choice as markup for the same
- * reason: a picker whose answer is invisible until a script runs is a picker
- * whose answer is not served at all. Both readings do it, the list and the
- * wheels, a wheel being a listbox like the list is.
+ * The chosen row is marked in the served markup. The listbox gets the answer as
+ * `.value`, and Lit SSR serializes no property binding, so without more the 96
+ * served rows would carry no mark until the listbox upgrades and runs `place`.
+ * Each option also gets `selected`, an attribute binding that does serialize,
+ * and `place` then writes the same answer from the same value. This is the same
+ * `selected` you write on `Option` elsewhere in Helix, and Date Picker marks
+ * its choice in markup for the same reason. The list and the wheels both do
+ * this, because each wheel is also a listbox.
  *
  * @since 0.1.0
  * @status stable
@@ -45,47 +36,47 @@ declare const HelixHeadlessTimePicker_base: (new (...args: any[]) => import("@fu
  * @aliases Time, TimeList
  * @documentation https://fusion.dev/helix/components/time-picker
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the time changes, and cancelable. Canceling it keeps the current time.
+ * @event {Event} input - Fired after the value changes.
  *
- * @csspart column - One of them.
- * @csspart column-empty - Shown when a filter has hidden everything.
- * @csspart column-feedback - What is wrong with it.
- * @csspart column-filter-icon - The mark beside that field.
- * @csspart column-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart column - One column of the wheels.
+ * @csspart column-empty - The text shown when the filter hides every option.
+ * @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.
  * @csspart column-hint - Help under the list.
- * @csspart column-items - The list itself.
- * @csspart column-label - The question, over the list.
- * @csspart column-live - The inner list's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart column-loading - Shown while the options are still on their way.
- * @csspart column-search - The region holding the field that narrows the list.
- * @csspart column-search-field - The field itself.
+ * @csspart column-items - The list of options.
+ * @csspart column-label - The label above the list.
+ * @csspart column-live - A copy of the empty and loading text, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart column-loading - The text shown while the options load.
+ * @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 list - The listbox holding the times, in `list`.
- * @csspart list-empty - Shown when a filter has hidden everything.
- * @csspart list-feedback - What is wrong with it.
- * @csspart list-filter-icon - The mark beside that field.
- * @csspart list-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart list-empty - The text shown when the filter hides every option.
+ * @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.
  * @csspart list-hint - Help under the list.
- * @csspart list-items - The list itself.
- * @csspart list-label - The question, over the list.
- * @csspart list-live - The inner list's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart list-loading - Shown while the options are still on their way.
- * @csspart list-search - The region holding the field that narrows the list.
- * @csspart list-search-field - The field itself.
- * @csspart option - One time in it. Carries `data-between` inside a range.
- * @csspart option-between - A time inside a chosen range, short of either end, beside `option`.
- * @csspart option-description - The caption under the words, when there is one.
+ * @csspart list-items - The list of options.
+ * @csspart list-label - The label above the list.
+ * @csspart list-live - A copy of the empty and loading text, in a region that screen readers announce when it changes. Visually hidden in the styled tier.
+ * @csspart list-loading - The text shown while the options load.
+ * @csspart list-search - The region that holds the filter field.
+ * @csspart list-search-field - The filter field.
+ * @csspart option - One time in the list. It carries `data-between` inside a range.
+ * @csspart option-between - A time inside a chosen range, excluding its ends, beside `option`.
+ * @csspart option-description - The caption under the time's label, when there is one.
  * @csspart option-item - The row.
  * @csspart option-item-active - The row the keyboard is on.
  * @csspart option-item-selected - The row of a chosen time: the one time, or either end of a range.
- * @csspart option-label - The words.
- * @csspart option-text - The words and the caption, as one column.
+ * @csspart option-label - The time's label.
+ * @csspart option-text - The label and the caption, as one column.
  */
 export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_base {
     /**
-     * What a reader is told when the value holds something that is not a time.
+     * The validation message for a value that is not a time.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
@@ -154,7 +145,7 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
      */
     mode?: 'multiple' | 'range';
     /**
-     * Whether the control refuses changes while still submitting its value.
+     * Blocks changes to the time. The value is still submitted with the form.
      *
      * **Enforced by refusing every request in one place**, which is the seam this
      * component already has: `requestValue` is what every path here comes through,
@@ -168,7 +159,7 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
      */
     readOnly: boolean;
     /**
-     * Whether the form refuses to submit while nothing is chosen.
+     * Stops the form from submitting while no time is chosen.
      */
     required: boolean;
     /**
@@ -235,8 +226,8 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     /** Every minute offered within the hour currently shown. */
     private get minutes();
     /**
-     * Each wheel comes to rest on its own answer, and the list on the time it
-     * holds.
+     * Scrolls each wheel to its selected value, and the list to its selected
+     * time.
      *
      * A dial that opens at midnight when it holds ten in the evening is a dial
      * showing the wrong thing, and CSS cannot fix it: `scroll-snap-type` chooses a
@@ -272,11 +263,12 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     /** Refuses every change while read-only. See `readOnly`. */
     requestValue(next: string): boolean;
     /**
-     * What a reader is told when a time is required and none is chosen.
+     * The validation message for a required time picker with no time chosen.
      */
     valueMissingMessage?: string;
     /**
-     * Whether the times are one list or a column each.
+     * Shows the times as one `list`, or as `wheels` with a column for each part
+     * of the time.
      *
      * `list` is the default and offers whole times, which is what a product with
      * opening hours or slots actually has. `wheels` splits them into an hour, a
@@ -356,7 +348,7 @@ export declare class HelixHeadlessTimePicker extends HelixHeadlessTimePicker_bas
     private listRevealed;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    /** Puts the keyboard on the list, which is the only control here. */
+    /** Moves focus to the list, which is the only control in the picker. */
     focus(options?: FocusOptions): void;
     /**
      * One wheel, which is a listbox like the whole list is.

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

@@ -4,20 +4,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary One event on a timeline: when it happened, and what it was.
  *
  * @description
- * **The time is a `<time>`, and only when there is a time to put in it.** Given
- * `datetime`, the label a consumer wrote is wrapped in the element the platform
- * has for exactly this, so the machine-readable instant travels with the human
- * one: a crawler, a reader's own tooling and a copy-paste all get "2026-08-19",
- * where "yesterday" on its own is a word. Given no `datetime`, it stays a span,
- * because a `<time>` with nothing to be precise about is markup pretending.
+ * Given `datetime`, the label you write is wrapped in a `<time>` element, so a
+ * machine-readable value such as "2026-08-19" travels with a label such as
+ * "yesterday". Without `datetime`, the label is a `<span>`.
  *
- * **The connector is this element's, not the list's.** Each entry draws the line
- * that arrives at it and hides it when it is first, which `:host(:first-child)`
- * settles with no index, no counting parent and no script. `Steps` and
- * `Breadcrumbs` both do it this way and for the same reason.
+ * Each entry draws the connector line that arrives at it and hides it when it
+ * is the first entry, using `:host(:first-child)`. This needs no index, no
+ * counting parent, and no script. `Steps` and `Breadcrumbs` work the same way.
  *
- * `tone` says what kind of event it was, and it is the only thing that colors
- * the mark. It takes `Announcement`'s vocabulary rather than a second one.
+ * `tone` sets the kind of event and is the only thing that colors the mark. It
+ * uses the same values as `Announcement`.
  *
  * @since 0.1.0
  * @status stable
@@ -26,24 +22,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/timeline
  *
  * @slot - What happened.
- * @slot marker - The mark on the line. Falls back to a dot, which is the slot's
- * own fallback content: whether a consumer slotted a mark is a question only the
- * platform can answer, and it answers it at assignment time.
- * @slot time - When it happened, as a reader should see it written.
+ * @slot marker - The mark on the line. Defaults to a dot, which is the slot's fallback
+ * content.
+ * @slot time - When it happened, written the way you want it shown.
  *
  * @csspart content - What happened, and the time above it.
- * @csspart dot - The mark drawn where nothing was slotted for one.
+ * @csspart dot - The dot drawn when no marker is slotted.
  * @csspart marker - The mark on the line.
- * @csspart rail - The column holding the mark and the line. Both halves of the
- * line are drawn on the rail, which is `::part(rail)::before` and `::after` from
- * a consumer's sheet: this tier ships no CSS, so a box it renders for one to
- * paint is an empty child costing whatever the consumer's own layout charges for
- * a child. `ListItem` measured that.
+ * @csspart rail - The column that holds the mark and the line. Draw the two halves of the
+ * line with `::part(rail)::before` and `::part(rail)::after` in your stylesheet. This
+ * tier ships no CSS and renders no extra box for the line.
  * @csspart time - When it happened.
  */
 export declare class HelixHeadlessTimelineItem extends HelixElement {
     /**
-     * When it happened, machine-readable.
+     * When it happened, in machine-readable form. Setting it wraps the time in a
+     * `<time>` element.
      *
      * Whatever `<time>` accepts, which is a date, a time, both, a duration or a
      * week. Unset, the label is written as it was given and nothing claims to
@@ -51,7 +45,7 @@ export declare class HelixHeadlessTimelineItem extends HelixElement {
      */
     datetime: string;
     /**
-     * What kind of event it was, which decides the mark's color and nothing else.
+     * The kind of event. It sets the color of the mark and nothing else.
      */
     tone?: 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
     protected willUpdate(changed: PropertyValues): void;

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

@@ -1,31 +1,23 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A record of what happened, in the order it happened.
+ * @summary A list of events, in the order they happened.
  *
  * @description
- * **Not `Steps`, and the difference is what the thing is for.** A stepper is a
- * process a reader is moving through: it has a stage they are on, stages they
- * have finished, and stages ahead, so it carries `active` and `complete` and
- * numbers itself. A timeline is a record of events that already happened, or are
- * scheduled to. Nothing is current, nothing is complete, and what each entry
- * carries instead is a time. Building this as an appearance of `Steps` would
- * have meant a stepper with no step you are on.
+ * A timeline is a record of events that happened or are scheduled. Each entry
+ * carries a time, and no entry is current or complete. For a process you move
+ * through, with a current stage and `active` and `complete` states, use
+ * `Steps`.
  *
- * What it does take from `Steps` is the connector. Each entry draws the line
- * that arrives at it and hides it when it is first, which needs neither an index
- * nor a parent that counts: `:host(:first-child)` is the whole of it, resolved
- * at layout with no script, so a server's markup is right before anything runs.
+ * Each entry draws the connector line that arrives at it and hides it when it
+ * is first, using `:host(:first-child)`. This resolves at layout with no
+ * script, so the server markup is correct before anything runs.
  *
- * `role="list"` on the host rather than an `<ol>` in the shadow root, for the
- * reason `Steps` gives: the entries are the consumer's elements in the light
- * DOM, so a list element here would be a list whose items are somewhere else.
+ * The host has `role="list"`, because the entries are your elements in the
+ * light DOM. `Steps` does the same.
  *
- * **It runs down the page and has no horizontal form.** Laid along a line there
- * is no room for the time or the sentence that are the whole reason to reach for
- * a timeline, so what survives is a mark and a short label, and that is a
- * stepper. `Steps` is already horizontal by default and already draws it. A run
- * of stages along a page is `Steps`.
+ * A timeline runs down the page and has no horizontal layout. For stages laid
+ * out horizontally, use `Steps`, which is horizontal by default.
  *
  * @since 0.1.0
  * @status stable
@@ -37,7 +29,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessTimeline extends HelixElement {
     /**
-     * Names the record, for a reader arriving at it out of context.
+     * Accessible name for the timeline, for people who reach it out of context.
      */
     label: string;
     protected render(): TemplateResult;