@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,81 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+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.
+ *
+ * **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 colours
+ * 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 rather than anything this element works out: whether a
+ * consumer slotted a mark is a question only the platform can answer, and it
+ * answers it by rendering what is inside the slot when nothing replaced it.
+ * @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.
+ */
+export declare class HelixHeadlessTimelineItem extends HelixElement {
+    /**
+     * 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.
+     */
+    datetime: string;
+    /**
+     * What kind of event it was, which decides the mark's color and nothing else.
+     */
+    tone?: 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
+    protected willUpdate(changed: PropertyValues): void;
+    /**
+     * The mark for an entry that slotted none, which the tone decides.
+     *
+     * **A `protected render…()` and not a getter, which is what it was.** A slot's
+     * fallback answers a consumer and a seam answers the tier above, and a getter
+     * answers neither: `check:fallbacks` permits `${this.x}` because a property is
+     * not markup a tier would redraw, and it tests for parentheses, so a getter
+     * returning a template reads as a bare reference and was let through. That is
+     * the same hole the check's own comment records closing for a static helper,
+     * reopened by a different spelling of the same thing.
+     *
+     * 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.
+     */
+    protected renderMarker(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-timeline-item': HelixHeadlessTimelineItem;
+    }
+}

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

@@ -0,0 +1,128 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+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 colours
+ * 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 rather than anything this element works out: whether a
+ * consumer slotted a mark is a question only the platform can answer, and it
+ * answers it by rendering what is inside the slot when nothing replaced it.
+ * @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 `protected render…()` and not a getter, which is what it was.** A slot's
+     * fallback answers a consumer and a seam answers the tier above, and a getter
+     * answers neither: `check:fallbacks` permits `${this.x}` because a property is
+     * not markup a tier would redraw, and it tests for parentheses, so a getter
+     * returning a template reads as a bare reference and was let through. That is
+     * the same hole the check's own comment records closing for a static helper,
+     * reopened by a different spelling of the same thing.
+     *
+     * 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"
+      ><slot name="marker"
+        ><svg part="dot" fill="currentColor" viewBox=${icon.viewBox} aria-hidden="true">
+          ${unsafeSVG(icon.content)}
+        </svg></slot
+      ></span
+    >`;
+    }
+    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"
+          aria-hidden="true"
+        ></div>
+        ${this.renderMarker()}
+      </div>
+      ${this.datetime === ''
+            ? html `<span part="time">${when}</span>`
+            : html `<time
+              part="time"
+              datetime=${this.datetime}
+              >${when}</time
+            >`}
+      <div part="content"><slot></slot></div>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTimelineItem.prototype, "datetime", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessTimelineItem.prototype, "tone", void 0);
+HelixHeadlessTimelineItem = __decorate([
+    customElement('helix-headless-timeline-item')
+], HelixHeadlessTimelineItem);
+export { HelixHeadlessTimelineItem };

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

@@ -0,0 +1,52 @@
+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.
+ *
+ * @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.** There was one, and it
+ * was removed rather than tuned: 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, so the horizontal version
+ * of this was a second component rendering the same picture from thinner data.
+ * 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.
+ */
+export declare class HelixHeadlessTimeline extends HelixElement {
+    /**
+     * Names the record, for a reader arriving at it out of context.
+     */
+    label: string;
+    protected render(): TemplateResult;
+    protected willUpdate(changed: PropertyValues): void;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-timeline': HelixHeadlessTimeline;
+    }
+}

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

@@ -0,0 +1,72 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, 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.** There was one, and it
+ * was removed rather than tuned: 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, so the horizontal version
+ * of this was a second component rendering the same picture from thinner data.
+ * 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() {
+        return html `<slot></slot>`;
+    }
+    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' });
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessTimeline.prototype, "label", void 0);
+HelixHeadlessTimeline = __decorate([
+    customElement('helix-headless-timeline')
+], HelixHeadlessTimeline);
+export { HelixHeadlessTimeline };

package/dist/toast/index.d.ts

@@ -0,0 +1,2 @@
+export * from './item/toast-item.js';
+export * from './root/toast-root.js';

package/dist/toast/index.js

@@ -0,0 +1,2 @@
+export * from './item/toast-item.js';
+export * from './root/toast-root.js';

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

@@ -0,0 +1,183 @@
+import { HelixElement, type ToneMark } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+declare const HelixHeadlessToastItem_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
+/**
+ * @summary One message in the toast region.
+ *
+ * @description
+ * An element rather than a slot, because it carries a timeout, a tone, a
+ * dismiss control and a lifetime that pauses: behavior, state and API, which
+ * is the test for whether a region becomes an element in this library.
+ *
+ * **The timer is the item's own.** Held by the region, one message arriving
+ * would restart another's, so a stack of three would go from three seconds each
+ * to nine for the last one. Each message is on its own clock from the moment it
+ * is rendered.
+ *
+ * **A message is the opposite of the page it is over.** Inverted by default,
+ * because a thing arriving in a corner has to be told apart from the page in
+ * the moment before it is read, and inverting does that without spending a
+ * color that means something. It is a flip of `color-scheme` rather than a
+ * named inverse surface: every token in the subtree re-resolves, so a `Retry`
+ * a consumer slots in comes out right without knowing where it is. `Tooltip`
+ * can name the inverse surface directly because it holds no controls; this
+ * cannot. Set `data-color-mode` on the region to take the page's mode instead.
+ *
+ * **No duration means it stays.** That is the safe default rather than the
+ * common one: anything carrying an action has to still be there when the reader
+ * decides to take it, and a component cannot tell from the outside whether the
+ * message it was given is disposable.
+ *
+ * **The clock stops while it is being read.** Hover pauses it, and so does
+ * focus landing anywhere inside, which is the case that matters more: a
+ * keyboard reader tabbing towards the action in a toast is exactly the person a
+ * timer must not race. Both resume where they left off rather than starting
+ * again, so a message half-read does not get a full second life every time a
+ * pointer crosses it.
+ *
+ * **Going away is a request, never an act.** It dispatches a cancelable
+ * `helix-dismiss` and does nothing else: the consumer owns the list, so the
+ * item removing itself would leave the two disagreeing. Auto-dismiss and the
+ * dismiss control raise the same event, so a consumer handles one path and not
+ * two.
+ *
+ * The properties below are written by this component and read by whoever draws
+ * it. A consumer sets none of them: they carry a number this element computed
+ * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
+ * without measuring anything itself.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @documentation https://helix.fusion.dev/components/toast
+ *
+ * @slot - The message.
+ * @slot actions - What to do about it, usually a button or a link.
+ * @slot dismiss-icon - Replaces the glyph inside the dismiss control.
+ * @slot icon - Replaces the tone mark. Matches `Callout`, which is why the
+ *   dismiss control's own glyph is `dismiss-icon` rather than this: two slots
+ *   cannot share a name, assignment goes to whichever comes first in the tree,
+ *   and the tone mark is the one a consumer reaches for.
+ *
+ * @event {HelixDismissEvent} helix-dismiss - Fired when it asks to go, whether by the control or by its timer. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart actions - The region holding what to do about it.
+ * @csspart content - The message.
+ * @csspart dismiss - The control that asks to close.
+ * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @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.
+ * @csspart timer - The bar showing how long is left, where a duration was given.
+ *
+ * @cssproperty --toast-duration - How long this message stays, in milliseconds, for a progress hint.
+ */
+export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base {
+    /**
+     * How long it stays, in milliseconds. Absent means until it is dismissed.
+     *
+     * Read once when the item is first rendered. Changing it afterwards does not
+     * restart a message the reader is already partway through.
+     */
+    duration?: number;
+    /**
+     * What kind of message it is, which picks the mark and its name.
+     *
+     * `severity` was a sixth spelling of `tone`, and a subset of it: a toast
+     * reports a status and never a brand role.
+     */
+    tone?: 'danger' | 'info' | 'success' | 'warning';
+    /** When the current run of the timer began, or nothing while it is paused. */
+    private startedAt;
+    /** What is left of the duration, so resuming continues rather than restarts. */
+    private remaining;
+    private timer;
+    /**
+     * Whether the message is still showing.
+     *
+     * The same decide-once contract every other stateful thing here carries, and
+     * it was the one exception: this waited to be told in every case, so
+     * `duration` did nothing at all without consumer script and the dismiss
+     * control looked broken to anyone who pressed it. `Dialog` closes itself,
+     * `Accordion` closes itself, and there was no reason a message should not.
+     *
+     * Declared by the markup and it is the consumer's: the item announces and
+     * waits. Not declared and it is the item's: it goes when it is asked to, and
+     * the consumer still hears `helix-dismiss` and takes it out of their own
+     * list. Read once, at the first update.
+     *
+     * **No `default-open`, unlike the four mixins.** A `default-` seed exists so
+     * markup can choose a starting state without claiming ownership, and there is
+     * only one starting state that makes sense: a message that has been rendered
+     * is showing. An attribute whose only legal value is the default is an
+     * attribute nobody can use.
+     *
+     *
+     */
+    get open(): boolean;
+    set open(next: boolean);
+    /** Whether it is showing, whoever said so, and `undefined` until somebody has. */
+    private openState;
+    /**
+     * Asks to be taken away, and reports whether the request stood.
+     *
+     * Announced before anything happens, so `preventDefault()` is a refusal and
+     * the message stays. The event still carries the label, because a consumer
+     * removing this from their own state has to know which one went, and that is
+     * true whether or not the item hid itself first.
+     */
+    dismiss(): boolean;
+    /** Stops the clock, leaving whatever is left of it. */
+    pause(): void;
+    /** Starts it again from where it stopped. */
+    resume(): void;
+    /**
+     * How many reasons there are to hold the clock, rather than whether there is
+     * one.
+     *
+     * Hover and focus both stopped the same timer with nothing counting them, so
+     * a reader who tabbed into a message and then moved the pointer off it had
+     * the clock restarted underneath them while they were still reading it. That
+     * is the case the pause exists for, and it was the case that broke it.
+     *
+     * The two are genuinely independent: a pointer can leave while focus stays,
+     * and focus can leave while the pointer stays. Only the last one out starts
+     * it again.
+     */
+    private holds;
+    private readonly handlePause;
+    private readonly handleResume;
+    disconnectedCallback(): void;
+    protected willUpdate(changed: PropertyValues): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    /**
+     * The mark for the message's tone, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     *
+     * The mark is passed in rather than looked up again, since `render` has
+     * already resolved the tone and a second lookup is a second place for the
+     * fallback to disagree with the tone around it.
+     */
+    protected renderIcon(mark: ToneMark): TemplateResult;
+    /**
+     * The mark on the dismiss control, behind a seam.
+     *
+     * Slot fallback, so a consumer replaces it by slotting; and a method, so the
+     * tier above replaces it by overriding. Those answer different people: the
+     * slot is for the page and the method is for whoever is building the styled
+     * layer, and a fallback with only the first is one a tier can restyle and
+     * cannot change.
+     */
+    protected renderDismissIcon(): TemplateResult;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-toast-item': HelixHeadlessToastItem;
+    }
+}
+export {};