@fusion.dev/helix-headless 0.1.0 → 0.3.0

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

@@ -8,15 +8,9 @@ import { valueAsTime as asTime, customElement, timeAsValue as fromTime, HelixFor
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
-/* Side-effect imports, because this renders these in its own shadow root and a
-   custom element registers on import. The paths are relative, so this registers
-   the headless elements and the styled file's identical imports register the styled
-   ones; `tier` picks which names the template asks for. */
 import '../../listbox/index.js';
 import '../../option/index.js';
-/** Whether a string is a time the rest of this component can reason about. */
 export const isTime = (value) => /^([01]\d|2[0-3]):[0-5]\d$/.test(value);
-/** Minutes since midnight, or `null` where it is not a time. */
 export const toMinutes = (value) => {
     if (!isTime(value)) {
         return null;
@@ -24,195 +18,40 @@ export const toMinutes = (value) => {
     const [hours = '0', minutes = '0'] = value.split(':');
     return Number(hours) * 60 + Number(minutes);
 };
-/** Minutes since midnight back to `HH:mm`, which is the value shape throughout. */
 export const fromMinutes = (minutes) => {
     const whole = ((Math.round(minutes) % 1440) + 1440) % 1440;
     return `${String(Math.floor(whole / 60)).padStart(2, '0')}:${String(whole % 60).padStart(2, '0')}`;
 };
-/**
- * A time written the way the reader's locale writes one.
- *
- * `Intl` decides between a twelve and a twenty-four hour clock, because that is
- * a property of the locale rather than of this component: `en-US` gets
- * `2:30 PM` and `en-GB` gets `14:30` without either being configured. There is
- * no flag to force one, deliberately. A product that needs to override its
- * reader's own convention has a locale problem rather than a component one, and
- * the value is 24 hour regardless.
- */
 export const writeTime = (value, locale) => {
     const minutes = toMinutes(value);
     if (minutes === null) {
         return value;
     }
     const at = new Date(Date.UTC(2000, 0, 1, Math.floor(minutes / 60), minutes % 60));
-    /* `timeStyle` rather than `hour` and `minute` assembled by hand. Measured in
-       Chrome: `hour: 'numeric'` gives `9:00` for `en-GB`, unpadded, which is not
-       how a twenty-four hour clock is written, while `hour: '2-digit'` gives
-       `09:00 AM` for `en-US`, which is not how a twelve hour one is. `short` is
-       each locale's own answer: `09:00` and `9:00 AM`. */
     return new Intl.DateTimeFormat(locale || undefined, {
         timeStyle: 'short',
         timeZone: 'UTC',
     }).format(at);
 };
-/**
- * Whether the reader's locale writes times on a twelve hour clock.
- *
- * Asked of `Intl` rather than derived from a list of locales, because it is
- * exactly the question `resolvedOptions` answers and the list is long and
- * changes. `en-US` is true, `en-GB`, `fr-FR` and `ja-JP` are false, measured.
- */
 const isTwelveHour = (locale) => new Intl.DateTimeFormat(locale || undefined, { timeStyle: 'short' }).resolvedOptions().hour12 ===
     true;
-/**
- * @summary Picks a time, from a list of them.
- *
- * @description
- * **A list rather than three wheels**, and the reason is what a list already
- * is. `helix-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.
- *
- * **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 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`.
- *
- * @since 0.1.0
- * @status experimental
- * @category forms
- * @aliases Time, TimeList
- * @documentation https://helix.fusion.dev/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.
- *
- * @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-hint - Help under the list.
- * @csspart column-items - The list itself.
- * @csspart column-label - The question, over the list.
- * @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 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-hint - Help under the list.
- * @csspart list-items - The list itself.
- * @csspart list-label - The question, over the list.
- * @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-description - The caption under the words, when there is one.
- * @csspart option-item - The row.
- * @csspart option-label - The words.
- * @csspart option-text - The words and the caption, as one column.
- */
 let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControllerValue(HelixFormElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Times that cannot be chosen, comma separated, as `HH:mm`.
-         *
-         * The counterpart to Date Picker's `disable-dates`, and it exists for the same
-         * shape of problem: `min` and `max` take away a span, and what a booking
-         * usually has to take away is a scatter. A morning with 09:30 and 11:00
-         * already gone is not two bounds.
-         *
-         * A time not on the step is simply never offered, so it is not an error to
-         * name one, and naming every time in the list is how the empty state is
-         * reached honestly rather than by handing over an empty range.
-         */
         this.disableTimes = '';
-        /**
-         * 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.
-         */
         this.invalid = false;
-        /**
-         * Accessible name for the list, which has no visible one of its own.
-         */
         this.label = 'Time';
-        /**
-         * Language tag the times are written in.
-         *
-         * Absent uses the runtime's own.
-         */
         this.locale = '';
-        /**
-         * Latest time offered, as `HH:mm`.
-         */
         this.max = '23:59';
-        /**
-         * Earliest time offered, as `HH:mm`.
-         */
         this.min = '00:00';
-        /**
-         * Whether the control refuses changes while still submitting its value.
-         *
-         * **Enforced by refusing every request in one place**, which is the seam this
-         * component already has: `requestValue` is what every path here comes through,
-         * and gating it once is what stops the next call site from being written
-         * without the check.
-         *
-         * Not `disabled`, which is the confusion worth naming: a disabled control
-         * submits nothing and leaves the tab order, and a read-only one submits its
-         * value and stays reachable, which is what a form showing a value somebody
-         * else set needs.
-         */
         this.readOnly = false;
-        /**
-         * Whether the form refuses to submit while nothing is chosen.
-         */
         this.required = false;
-        /**
-         * Takes what the list announced and constrains it to what the mode allows.
-         *
-         * The listbox is put in `multiple` for both modes, because that is what marks
-         * more than one row and toggles on press. A range then differs only in what is
-         * kept: two, and a third pick starts again from that third one. Working out
-         * which is newest by difference rather than by position, since a toggle can
-         * remove as easily as add and the announced list is a set rather than a
-         * sequence.
-         */
         this.handleChange = (event) => {
             event.stopPropagation();
-            /* The listbox is told as well, which is what grays it and takes it out of
-               the tab order, and this refuses at the source so every path in is covered
-               by one check.
-               `isDisabled` rather than `disabled`, which is only the half a consumer
-               wrote: an ancestor `<fieldset disabled>` is the other half. */
             if (this.isDisabled) {
                 return;
             }
             const announced = event.detail.value;
-            /* The listbox already skips a disabled option, so this is the second lock
-               rather than the first: it covers a value arriving from a consumer's own
-               dispatch, and it is what makes the refusal a fact about the component
-               rather than about the listbox it happens to render. */
             if (announced.split(',').some((one) => this.barred(one.trim()))) {
                 return;
             }
@@ -232,7 +71,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
             const added = next.find((one) => !before.has(one));
             this.requestValue(added ?? '');
         };
-        /** Puts a changed column back together into a whole time. */
         this.moveColumn = (part, to) => {
             if (this.isDisabled) {
                 return;
@@ -243,10 +81,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
                 next = hour * 60 + Number(to);
             }
             else if (part === 'hour') {
-                /* On a twelve hour clock the column says 1 to 12 and the meridiem says
-                   which half, so the two have to be recombined rather than read straight:
-                   12 AM is midnight and 12 PM is noon, which is the one pair that does not
-                   follow the pattern. */
                 const shown = Number(to);
                 const whole = isTwelveHour(this.locale) ? (shown % 12) + (meridiem === 'PM' ? 12 : 0) : shown;
                 next = whole * 60 + minute;
@@ -255,35 +89,14 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
                 const half = hour % 12;
                 next = (half + (to === 'PM' ? 12 : 0)) * 60 + minute;
             }
-            /* The wheels build a value from three columns and never reach
-               `handleChange`, so the refusal has to be repeated here. Disabling the
-               options is not enough on its own: a reader on 09:00 who moves the hour to
-               10 lands on 10:00, and 10:00 can be barred while nothing in the hour
-               column was. */
             const whole = fromMinutes(next);
             if (this.barred(whole)) {
                 return;
             }
             this.requestValue(whole);
         };
-        /**
-         * How far apart the offered times are, in minutes.
-         *
-         * Fifteen, which is four rows an hour and ninety-six in a day: enough that a
-         * reader scrolls rather than hunts, and few enough that the list is a list.
-         * Anything under five is a thousand rows and wants a field instead.
-         */
         this.step = 15;
     }
-    /**
-     * Every time on offer, as minutes since midnight.
-     *
-     * Built from `min` upward rather than from midnight, so a list that starts at
-     * `09:00` steps from nine rather than offering `09:15` because that is where
-     * the quarter hours from midnight happen to land. A step that does not divide
-     * the hour is a real thing to want, twenty minutes being the obvious one, and
-     * this is the reading that makes it behave.
-     */
     get times() {
         const from = toMinutes(this.min) ?? 0;
         const to = toMinutes(this.max) ?? 1439;
@@ -294,17 +107,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         }
         return found;
     }
-    /**
-     * Whether a time is barred by name.
-     *
-     * `barred`, not `disabled`, for the reason Date Picker records: this is a form
-     * control and `HelixFormElement.disabled` is a boolean about the whole of it,
-     * so a method and a flag cannot share the name.
-     *
-     * Only the named list. `min` and `max` are not consulted here because they
-     * never produce a row to bar: `times` builds the list between them, so a time
-     * outside the bounds is absent rather than present and refused.
-     */
     barred(at) {
         return this.disableTimes
             .split(',')
@@ -312,30 +114,21 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
             .filter(Boolean)
             .includes(at);
     }
-    /**
-     * Whether every offered time in an hour is barred.
-     *
-     * `shown` is the meridiem the wheel is on, so `1` means 01:00 under AM and
-     * 13:00 under PM. Absent is a 24 hour clock, where the number is the hour.
-     */
     wholeHourBarred(shown, half) {
         const whole = half === undefined ? shown : (shown % 12) + (half === 'PM' ? 12 : 0);
         const within = this.times.filter((at) => Math.floor(at / 60) === whole);
         return within.length > 0 && within.every((at) => this.barred(fromMinutes(at)));
     }
-    /** Whether every offered time in a half of the clock is barred. */
     halfBarred(half) {
         const within = this.times.filter((at) => (half === 'PM') === at >= 720);
         return within.length > 0 && within.every((at) => this.barred(fromMinutes(at)));
     }
-    /** The times held, which is a list whether or not a mode is set. */
     get held() {
         return this.value
             .split(',')
             .map((one) => one.trim())
             .filter(Boolean);
     }
-    /** Whether a time falls inside a range, which is what gets banded. */
     between(at) {
         if (this.mode !== 'range') {
             return false;
@@ -343,41 +136,19 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         const [from, to] = this.held;
         return from !== undefined && to !== undefined && at > from && at < to;
     }
-    /** The three readings a wheel shows, from the value or from `min`. */
     get parts() {
         const at = toMinutes(this.value) ?? toMinutes(this.min) ?? 0;
         const hour = Math.floor(at / 60);
         return { hour, meridiem: hour < 12 ? 'AM' : 'PM', minute: at % 60 };
     }
-    /** Every whole hour that has at least one offered time in it. */
     get hours() {
         const found = new Set(this.times.map((at) => Math.floor(at / 60)));
         return [...found];
     }
-    /** Every minute offered within the hour currently shown. */
     get minutes() {
         const hour = this.parts.hour;
         return this.times.filter((at) => Math.floor(at / 60) === hour).map((at) => at % 60);
     }
-    /**
-     * Each wheel comes to rest on its own answer.
-     *
-     * 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
-     * snap point when something scrolls, and nothing has. Measured before this,
-     * with the value at 22:00, the hour wheel sat 288 pixels above its answer.
-     *
-     * On every update rather than on the first, because the columns re-render as
-     * the value moves and the minute column's contents change with the hour.
-     *
-     * **And it is public, because an update is not the only moment that matters.**
-     * Inside a panel this element renders while the panel is still
-     * `display: none`, so every box measures zero and there is nothing to center
-     * against: measured, the hour wheel stayed 288 pixels off its answer because
-     * the only call happened before anything had a size. Whatever shows the panel
-     * calls this again afterwards. The guard below makes the early call harmless
-     * rather than wrong, which is why it can be left in.
-     */
     reveal() {
         if (this.variant !== 'wheels' || this.mode !== undefined) {
             return;
@@ -386,34 +157,18 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
             column.reveal?.();
         }
     }
-    /** Refuses every change while read-only. See `readOnly`. */
     requestValue(next) {
         if (this.readOnly) {
             return false;
         }
         return super.requestValue(next);
     }
-    /**
-     * Reports "required and empty", or clears it.
-     *
-     * Written out rather than taken from `MixinField`, which is where the seven
-     * form controls get this. That mixin brings a label, a hint and a feedback
-     * region with it, and this is a grid rather than a field: it is composed
-     * *into* the field that has those, so taking the mixin would give one control
-     * two of each. What is shared is five lines, and the anchor is what the
-     * browser points its bubble at.
-     */
     reportRequired() {
         const anchor = this.renderRoot?.querySelector('[part="list"]') ?? undefined;
         if (this.required && this.value === '') {
             this.internals.setValidity({ valueMissing: true }, 'Choose a time.', anchor);
             return;
         }
-        /* A value the wheels cannot read is bad input, the same as on the calendar:
-           `value="not-a-time"` marks no row, and would otherwise report `:valid` and
-           be handed to the form. `asTime` rejects the hours and minutes that are
-           shaped right and out of range as well as the ones that are not shaped
-           right at all. */
         const held = this.held;
         if (held.length > 0 && held.some((one) => asTime(one) === null)) {
             this.internals.setValidity({ badInput: true }, this.mode === undefined
@@ -423,21 +178,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         }
         this.internals.setValidity({});
     }
-    /**
-     * Reports the times to the form, one entry each.
-     *
-     * `FormData` and one entry per time, which is `DatePicker.report` exactly.
-     * `mode="multiple"` is genuinely several answers, and a server reading
-     * `times=09:00,17:00` would have to split it on a convention this library
-     * invented; `range` sends its two in order, so start and end arrive as the
-     * pair they already are.
-     *
-     * **Nothing at all without a `name`.** A `FormData` carries its own names and
-     * its entries are appended whatever the element is called, so an unnamed
-     * picker would submit empty-named times rather than being skipped the way a
-     * control reporting a plain string is. That is the same guard, for the same
-     * reason, that the calendar's own note spells out.
-     */
     report() {
         const times = this.held;
         if (this.name === '' || this.disabled || times.length === 0) {
@@ -450,25 +190,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         }
         this.internals.setFormValue(data);
     }
-    /**
-     * Reveals once the wheels have rendered themselves.
-     *
-     * `updated` is this element's own moment, and each wheel is a `helix-listbox`
-     * that was created during this very render: its first update has been
-     * scheduled and has not run, so it has no rows and no height and `reveal`
-     * measures zero and gives up. Measured on a standalone picker, every column
-     * sat at `scrollTop: 0` with the answer nine rows down, which reads as a wheel
-     * showing the wrong time rather than as one that failed to scroll.
-     *
-     * Whatever opens a panel calls `reveal` again afterwards, for the separate
-     * reason that method documents. Flat on a page there is no panel and no
-     * second call.
-     *
-     * Safe to run on every update: the listbox stops as soon as the chosen row is
-     * within a pixel of center, so a call with nothing to do costs two rect reads
-     * and changes nothing. It cannot fight a reader mid-scroll either, since
-     * scrolling a wheel changes no property and so schedules no update.
-     */
     async revealWhenSettled() {
         const columns = [
             ...(this.renderRoot?.querySelectorAll('[part="column"]') ?? []),
@@ -476,16 +197,9 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         await Promise.all(columns.map((column) => column.updateComplete));
         this.reveal();
     }
-    /* `ariaInvalid` on the host through `ElementInternals`, the same route
-       Date Picker takes and for the reason the whole library records: a `role` or a
-       state written onto the host as an attribute is one a React consumer's
-       server markup never had. */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.internals.ariaInvalid = this.invalid ? 'true' : null;
-        /* Here rather than in `updated`, which is where `DatePicker` reports from
-           too: the value is known before the render and a form read between the two
-           should not see the previous one. */
         this.report();
     }
     updated(changed) {
@@ -494,23 +208,9 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         this.reveal();
         void this.revealWhenSettled();
     }
-    /** Puts the keyboard on the list, which is the only control here. */
     focus(options) {
         this.renderRoot?.querySelector('[part="list"]')?.focus(options);
     }
-    /**
-     * One wheel, which is a listbox like the whole list is.
-     *
-     * `protected` rather than `private`, which is the whole of what a seam is
-     * here: a tier above has to be able to reach it.
-     *
-     * `barred` is passed per column rather than read from `disableTimes` here,
-     * because a column holds a third of a time and only the caller knows the
-     * other two thirds. What that means differs by column and the difference is
-     * not a detail: a minute is barred when *this* hour plus it is, and an hour is
-     * barred only when every minute in it is, since one free minute is a reason to
-     * open the wheel rather than to close it.
-     */
     renderColumn(part, label, values, written, value, barred = () => false) {
         return html `<${this.tag('listbox')}
       part="column"
@@ -536,9 +236,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
         const twelve = isTwelveHour(this.locale);
         const { hour, meridiem, minute } = this.parts;
         const shownHour = twelve ? String(hour % 12 === 0 ? 12 : hour % 12) : String(hour);
-        /* The hour column reads 1 to 12 on a twelve hour clock, so the whole hours
-           on offer are mapped into that half and de-duplicated: 13:00 and 01:00 are
-           both "1", and offering it twice is offering a choice that is not one. */
         const hours = twelve
             ? [...new Set(this.hours.map((one) => (one % 12 === 0 ? 12 : one % 12)))].sort((a, b) => a - b)
             : this.hours;
@@ -550,16 +247,6 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
             : nothing}
     </div>`;
     }
-    /**
-     * The flat list of times, for the variant that is not wheels, behind a seam the styled tier can move.
-     *
-     * A method rather than a fragment inline, so a tier above can render its own,
-     * wrap this one, pass it a property the base does not know about, or leave it
-     * out, without reimplementing the whole template to do any of them. The tag is
-     * interpolated rather than written, so `tier` resolves it: this renders the
-     * headless element, and a styled subclass that sets `tier` renders the styled one
-     * from the same template.
-     */
     renderList() {
         return html `<${this.tag('listbox')}
       part="list"
@@ -587,30 +274,17 @@ let HelixHeadlessTimePicker = class HelixHeadlessTimePicker extends MixinControl
     </${this.tag('listbox')}>`;
     }
     render() {
-        /* A mode falls back to the list, for the reason the property records: a
-           range on wheels is two sets of wheels and a multiple is a set, which a
-           wheel cannot hold. */
         if (this.variant === 'wheels' && this.mode === undefined) {
             return this.renderSpinner();
         }
         return html `${this.renderList()}`;
     }
-    /**
-     * The value as a `Date` on 1 January 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
-     * is what makes `valueAsNumber` come out as milliseconds since midnight rather
-     * than as a moment nobody meant. Assigning any date reads the clock off it, so
-     * a consumer handing over `new Date()` gets the time of day they expected.
-     */
     get valueAsDate() {
         return asTime(this.value);
     }
     set valueAsDate(date) {
         this.value = fromTime(date);
     }
-    /** The value as milliseconds since midnight, or `NaN` while there is no time. */
     get valueAsNumber() {
         return asTime(this.value)?.getTime() ?? Number.NaN;
     }

package/dist/timeline/item/timeline-item.js

@@ -9,76 +9,15 @@ import { circle, record } from '@fusion.dev/helix-icons';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @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.
- *
- * **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.
- *
- * `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.
- *
- * @since 0.1.0
- * @status stable
- * @category data
- * @aliases Activity item, History entry, Event
- * @documentation https://helix.fusion.dev/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.
- *
- * @csspart connector - The line arriving at this entry.
- * @csspart content - What happened, and the time above it.
- * @csspart dot - The mark drawn where nothing was slotted for one.
- * @csspart marker - The mark on the line.
- * @csspart rail - The column holding the mark and the line.
- * @csspart time - When it happened.
- */
 let HelixHeadlessTimelineItem = class HelixHeadlessTimelineItem extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * When it happened, machine-readable.
-         *
-         * 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
-         * know what instant it names.
-         */
         this.datetime = '';
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'listitem' });
     }
-    /**
-     * The mark for an entry that slotted none, which the tone decides.
-     *
-     * **A seam is a `protected render…()` and never a getter.** A slot's fallback
-     * answers a consumer and a seam answers the tier above, and a getter answers
-     * neither. The check tests for parentheses, `${this.x}` being permitted
-     * because a property is not markup a tier would redraw, so a getter returning
-     * a template reads as a bare reference and is let through.
-     *
-     * Toned entries are reporting something, so they take the circle with a
-     * center, which is `Steps` drawing the stage a reader is standing on. Untoned
-     * ones are just things that happened and take the open circle, which is
-     * `Steps` drawing a stage nobody has reached. The same two glyphs in both
-     * components rather than two that resemble each other: a shape drawn twice
-     * drifts, and these are already the marks a reader has learned one page over.
-     */
     renderMarker() {
         const icon = this.tone === undefined ? circle : record;
         return html `<span part="marker"
@@ -91,11 +30,6 @@ let HelixHeadlessTimelineItem = class HelixHeadlessTimelineItem extends HelixEle
     }
     render() {
         const when = html `<slot name="time"></slot>`;
-        /* The time is a sibling of the content rather than the first thing inside
-           it, so the two are separate rows and the rail can align its mark to the
-           second of them. Nested, the mark could only ever be a fixed distance from
-           the top of the entry, which is the time's height on a good day and wrong
-           the moment a consumer writes two lines of it. */
         return html `<div part="rail">
         <div
           part="connector"

package/dist/timeline/root/timeline-root.js

@@ -7,47 +7,9 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A record of what happened, in the order it 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.
- *
- * 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.
- *
- * `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.
- *
- * **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`.
- *
- * @since 0.1.0
- * @status stable
- * @category data
- * @aliases Activity feed, History, Changelog, Audit trail
- * @documentation https://helix.fusion.dev/components/timeline
- *
- * @slot - The entries.
- */
 let HelixHeadlessTimeline = class HelixHeadlessTimeline extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Names the record, for a reader arriving at it out of context.
-         */
         this.label = '';
     }
     render() {
@@ -55,9 +17,6 @@ let HelixHeadlessTimeline = class HelixHeadlessTimeline extends HelixElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        /* On the host through internals rather than as an attribute, so the role is
-           there for a screen reader without being markup the server never wrote.
-           `Steps` says the same about its own list. */
         hostAria(this.internals, { label: this.label, role: 'list' });
     }
 };