Timeline

type Color = "neutral" | "primary" | "secondary" | "success" | "error" | "warning" | "info" | "pending";

type Variant = "default" | "card" | "compact";

type DateFormat = "date" | "datetime" | "time" | "relative";

interface TimelineTag {
    /**
     * The pill's text, e.g. 'Added', 'Breaking' or 'v2.4.0'.
     */
    label: string;

    /**
     * @defaultValue 'neutral'
     */
    color?: Color;

    /**
     * @defaultValue 'soft'
     */
    variant?: "solid" | "soft";

    /**
     * Name of the icon displayed before the label.
     */
    icon?: string;
}

interface TimelineItem {
    /**
     * The entry's heading — a version number, an action, a deploy name.
     */
    title?: string;

    /**
     * Secondary text under the title. `variant="compact"` keeps it on the title's row instead, and
     * truncates it, so a long audit-log line stays one row tall.
     */
    description?: string;

    /**
     * When the entry happened, shown at the end of the title row. A `Date` or a timestamp number is
     * formatted per the timeline's `dateFormat`; a string is displayed verbatim (so a pre-formatted
     * "3 days ago" passes straight through) unless it's ISO-8601 (`2026-03-04`,
     * `2026-03-04T09:30:00Z`), which is formatted like the other two.
     */
    date?: string | number | Date;

    /**
     * Name of the icon rendered inside this entry's marker, in place of the default dot.
     */
    icon?: string;

    /**
     * Renders an avatar as this entry's marker instead of a dot or icon — for an audit log, where
     * who did it is the first thing to read. Same fields as `Avatar`; takes precedence over `icon`.
     */
    avatar?: { src?: string; firstName?: string; lastName?: string };

    /**
     * Colors this entry's marker, overriding the timeline's `color` — for typing entries by
     * severity or kind (a failed deploy `error`, a release `success`). On an `avatar` marker, which
     * has no fill to tint, it becomes a ring around the avatar instead.
     */
    color?: Color;

    /**
     * Pills shown after the title, for change types ('Added', 'Fixed', 'Breaking') or labels.
     */
    tags?: TimelineTag[];

    /**
     * Turns the title into a link to this URL or route — the release notes, the audited record.
     */
    to?: string;

    /**
     * Marks the entry as the current one (the live version, the newest deploy), drawing a soft halo
     * around its marker.
     * @defaultValue false
     */
    active?: boolean;

    /**
     * Unique value identifying this entry. Falls back to `title`, then its index.
     */
    value?: string | number;

    /**
     * Name of the slot rendering this entry's body, instead of the shared `#content` slot.
     */
    slot?: string;
}