{ "$schema": "https://ui.shadcn.com/schema/registry-item.json", "name": "timeline", "type": "registry:ui", "title": "Timeline", "description": "The steps of a run in order, such as a deploy: when each started, a status icon on a hairline rail, the label and how long it took, grouped into phases. In a proportional timeline long steps draw their time as a bar in the phase's data hue, with the last run beside it. A strip shows the whole run at a glance.", "dependencies": [ "motion" ], "registryDependencies": [ "https://littmd.vercel.app/r/litt.json", "https://littmd.vercel.app/r/motion.json" ], "files": [ { "path": "registry/litt/ui/timeline.tsx", "type": "registry:ui", "content": "\"use client\";\n// @litt/timeline 2026.11.06. What changed: https://littmd.vercel.app/changelog.md\n\n/**\n * Timeline: the steps of a run in order (a deploy, a build, an import), with when each started, how long it\n * took and how it ended. Compose it from children: Timeline > TimelinePhase > TimelineStep, then a\n * TimelineResult. TimelineBar draws the whole run as one strip and sits beside it.\n *\n * - Layout (components.md, Timeline): an ordered list in four columns. The start (`at`) is the tabular caption in\n * fg-subtle with tabular numbers, then the rail, then the label in the small size and fg, then the duration at\n * the end in the tabular caption. A skipped or pending step's label is fg-subtle, and a skipped step's duration is\n * the word \"skipped\". Rows are airy, 32px at least. The list measures itself (a container query), not the\n * window: the start column shrinks on a narrow container and the labels wrap.\n * - Rail: a 1px line in line-strong that runs between the 16px status icons and stops at a phase's first and last\n * step. It is drawn in two short pieces around each icon, so the icon never needs a background of its own.\n * - Status icons (16px, currentColor, the icon set's marks): done is a filled disc with the check cut out, in\n * fg-muted; running is a ring half filled, in fg, and does not spin or pulse; pending is an empty ring in fg-subtle;\n * skipped is a dashed ring in fg-subtle; failed is a filled disc with the x cut out, in danger. No dots. Every\n * status is also said in hidden text, so color and shape are never the only signal.\n * - Phase: a heading row (the label small in fg-subtle, the total in the tabular caption) over a nested, labelled\n * list. Its `hue` says which phase (R7): it colors the phase's rail bars here and its segments in TimelineBar.\n * With no hue those marks are fg at 55%.\n * - Proportional: with `proportional`, a step with `seconds` gets a row at least `seconds * secondHeight` tall, and\n * the rail below its icon becomes a 4px bar at the control radius (the Meter's rail) of that length, in the\n * phase's mark tone. With `previousSeconds` a ghost bar at fg 12% shows the last run's length beside it, with\n * \"was 31s\" at its foot. A step whose bar would be shorter than a row keeps the thin line. A failed step's bar is\n * danger, the one status color a mark takes.\n * - Flat: done and now are ink marks (the tick cut from an ink disc, the half-filled ring), waiting and skipped take the line-control edge, and the result row has no rule.\n * - Result: the closing row under a hairline. The label is body size in success, danger or fg by `tone`, the total\n * is tabular in fg at the end, and the tone is said in hidden text.\n * - Bar: a strip of the whole run from data, not children. 32px tall at the control radius with overflow hidden,\n * segments sized by seconds, square, 2px apart. A skipped or zero-second step takes no width. Phase labels sit\n * above each phase's span and the times at the phase boundaries sit below, in the tabular caption. Hovering a\n * segment, or touching it, shows the Tooltip's look (solid surface-3, shadow-litt-tooltip: the label, then the tabular\n * duration), the way the Chart does. A touch pins it until the next touch elsewhere.\n * - Semantics: each step reads in order, \"00:02, Run build commands, done, 19 seconds\". The bar is role=\"img\" with a\n * summary, and its segments are not focusable: it always sits beside a Timeline or a table that lists the same\n * steps, so a keyboard user and a screen reader get every step there.\n * - Motion: none in the timeline. A running step does not move. The bar's tooltip uses the responsive tier like\n * every tooltip, and hover changes color only, at the instant tier.\n * - Fun mode (motion/fun.tsx, a trial, off unless a is on) moves the timeline only as a run changes: a step\n * whose status changes pops its icon in, a step that finishes draws its check as a pen would, a step that fails\n * shakes once sideways, a phase's total arrives with a small pop, and a result added after the timeline mounted rises\n * in on the expressive tier; a run that went live scatters a few dots in its phases' hues, once. A timeline that\n * loads finished stays still. Each change hands back to the static markup when it lands. Reduced motion turns it off.\n */\nimport { createContext, useCallback, useContext, useEffect, useId, useLayoutEffect, useMemo, useRef, useState, type ReactNode, type Ref } from \"react\";\nimport { animate, AnimatePresence, motion, type Transition } from \"motion/react\";\nimport { useExit, useFun, useTransition, useTravel } from \"../../lib/litt/motion\";\n\n/* ----------------------------------------------------------------- types */\n\n/** How a step stands. Running is a half-filled circle that stays still. */\nexport type TimelineStatus = \"done\" | \"running\" | \"pending\" | \"skipped\" | \"failed\";\n\n/** The five data hues, in their fixed order (R7). A phase takes one, and it means that phase everywhere in the view. */\nexport type TimelineHue = \"blue\" | \"amber\" | \"teal\" | \"violet\" | \"rose\";\n\n/** How a run ended: success, danger, or neither. It sets the result's color and a hidden word. */\nexport type TimelineTone = \"success\" | \"danger\" | \"neutral\";\n\n/* ----------------------------------------------------------------- lookups */\n\n/** Literal strings, so Tailwind sees every class. */\nconst MARK: Record = {\n blue: \"bg-litt-data-blue\",\n amber: \"bg-litt-data-amber\",\n teal: \"bg-litt-data-teal\",\n violet: \"bg-litt-data-violet\",\n rose: \"bg-litt-data-rose\",\n};\n/** With no hue, a mark is the foreground at 55%, as in the Chart. */\nconst MARK_FG = \"bg-[color-mix(in_oklab,var(--litt-fg)_55%,transparent)]\";\nconst GHOST = \"bg-[color-mix(in_oklab,var(--litt-fg)_12%,transparent)]\";\n\nconst ICON_TONE: Record = {\n done: \"text-litt-fg-muted in-[[data-material=flat]]:text-litt-fg\",\n running: \"text-litt-fg\",\n pending: \"text-litt-fg-subtle in-[[data-material=flat]]:text-litt-line-control\",\n skipped: \"text-litt-fg-subtle in-[[data-material=flat]]:text-litt-line-control\",\n failed: \"text-litt-danger\",\n};\nconst RESULT_TONE: Record = {\n success: \"text-litt-success\",\n danger: \"text-litt-danger\",\n neutral: \"text-litt-fg\",\n};\nconst RESULT_WORD: Record = { success: \", success\", danger: \", error\", neutral: \"\" };\n\n/* ----------------------------------------------------------------- numbers and words */\n\nconst ROW = 32; // the least height of a row\nconst RAIL_TOP = 24; // where the rail below an icon starts: the icon sits 8px down and is 16px tall\nconst BAR_MIN = 16; // a bar shorter than this is no better than the thin line\nconst CAPTION = 17; // a caption line at the caption size\n\nconst tidy = (n: number) => (Number.isInteger(n) ? String(n) : n < 10 ? n.toFixed(1) : String(Math.round(n)));\nconst isNum = (n: unknown): n is number => typeof n === \"number\" && Number.isFinite(n);\nconst clean = (n: unknown) => (isNum(n) ? Math.max(0, n) : 0);\n\n/** \"19s\", \"1m 12s\". */\nfunction formatSeconds(total: number): string {\n const s = Math.max(0, total);\n if ((s >= 10 ? Math.round(s) : s) < 60) return `${tidy(s)}s`;\n const whole = Math.round(s);\n const m = Math.floor(whole / 60);\n const r = whole - m * 60;\n return r ? `${m}m ${r}s` : `${m}m`;\n}\n\n/** \"19 seconds\", \"1 minute 12 seconds\": what a screen reader should say where the page shows \"19s\". */\nfunction speakSeconds(total: number): string {\n const s = Math.max(0, total);\n if ((s >= 10 ? Math.round(s) : s) < 60) {\n const t = tidy(s);\n return `${t} ${t === \"1\" ? \"second\" : \"seconds\"}`;\n }\n const whole = Math.round(s);\n const m = Math.floor(whole / 60);\n const r = whole - m * 60;\n const minutes = `${m} ${m === 1 ? \"minute\" : \"minutes\"}`;\n return r ? `${minutes} ${r} ${r === 1 ? \"second\" : \"seconds\"}` : minutes;\n}\n\n/** \"00:24\", or \"1:02:10\" past an hour: a time on the run's clock. */\nfunction clock(total: number): string {\n const s = Math.max(0, Math.round(total));\n const h = Math.floor(s / 3600);\n const m = Math.floor((s % 3600) / 60);\n const p = (n: number) => String(n).padStart(2, \"0\");\n return h ? `${h}:${p(m)}:${p(s % 60)}` : `${p(m)}:${p(s % 60)}`;\n}\n\n/** A number is seconds and is formatted and spoken. A string is shown and spoken as it is. */\nfunction readTime(value: number | string) {\n return typeof value === \"number\" ? { visual: formatSeconds(value), spoken: speakSeconds(value) } : { visual: value, spoken: value };\n}\n\n/* ----------------------------------------------------------------- context */\n\ntype TimelineContextValue = {\n proportional: boolean;\n secondHeight: number;\n /** True once the timeline has mounted: what arrives after that is a change, which fun mode may move. */\n mounted: { current: boolean };\n /** The phases' hues, for a run's celebration in fun mode. */\n hues: { current: Set };\n};\nconst TimelineContext = createContext({ proportional: false, secondHeight: 4, mounted: { current: true }, hues: { current: new Set() } });\nconst PhaseContext = createContext<{ hue?: TimelineHue }>({});\n\n/* ----------------------------------------------------------------- the icons */\n\n/* Done and failed are a filled disc with the mark cut out through a mask, the icon set's own drawing, so the cut shows\n whatever is behind it and the icon still needs no background. */\nconst CUT: Partial> = { done: \"m5.25 8.25 2 2 3.5-4.25\", failed: \"m6 6 4 4m0-4-4 4\" };\n\nfunction StatusIcon({ status, ref }: { status: TimelineStatus; ref?: Ref }) {\n const skipped = status === \"skipped\";\n const cut = CUT[status];\n const mask = useId().replace(/[^\\w-]/g, \"\");\n return (\n \n {cut ? (\n <>\n \n \n \n \n \n \n ) : (\n \n )}\n {status === \"running\" && }\n \n );\n}\n\n/* ----------------------------------------------------------------- Timeline */\n\nexport type TimelineProps = {\n /** What the run is, said once for screen readers: \"Update pricing page, deploy steps\". */\n label: string;\n /** Sizes each step's row by its seconds and draws long steps as a bar on the rail. A step needs `seconds` for that. */\n proportional?: boolean;\n /** Pixels of row height per second in a proportional timeline. A 19 second step at 4 is a 76px bar. */\n secondHeight?: number;\n /** Phases and steps, then a result. Put steps in a TimelinePhase so the rail breaks between phases. */\n children: ReactNode;\n /** Extra classes for the list, such as a width. */\n className?: string;\n};\n\n/** The steps of a run as an ordered list in four columns: start, rail, label, duration. Compose it from TimelinePhase, TimelineStep and TimelineResult. */\nexport function Timeline({ label, proportional = false, secondHeight = 4, children, className = \"\" }: TimelineProps) {\n const mounted = useRef(false);\n const hues = useRef(new Set());\n useEffect(() => {\n mounted.current = true;\n }, []);\n const value = useMemo(() => ({ proportional, secondHeight, mounted, hues }), [proportional, secondHeight]);\n return (\n \n
    \n {children}\n
\n \n );\n}\n\n/* ----------------------------------------------------------------- TimelinePhase */\n\nexport type TimelinePhaseProps = {\n /** The phase's name, in sentence case: \"Build\". It labels the nested list. */\n label: string;\n /** The phase's total at the end of its heading. A number is seconds (\"24s\", read as \"24 seconds\"); a string is shown as given. Leave it out while the phase has not run. */\n duration?: number | string;\n /** The phase's data hue (R7). It colors this phase's rail bars and its segments in a TimelineBar. Without one they are the foreground at 55%. */\n hue?: TimelineHue;\n /** The phase's TimelineSteps. */\n children: ReactNode;\n /** Extra classes for the phase. */\n className?: string;\n};\n\n/** A group of steps under a heading row (the label and the total), with a nested, labelled list. */\nexport function TimelinePhase({ label, duration, hue, children, className = \"\" }: TimelinePhaseProps) {\n const id = useId();\n const total = duration === undefined ? null : readTime(duration);\n const value = useMemo(() => ({ hue }), [hue]);\n const { hues } = useContext(TimelineContext);\n useEffect(() => {\n if (hue) hues.current.add(hue);\n }, [hue, hues]);\n /* Fun mode: a total that appears (the phase just finished) arrives with a small pop. */\n const fun = useFun();\n const totalRef = useRef(null);\n const hadTotal = useRef(total !== null);\n useLayoutEffect(() => {\n const el = totalRef.current;\n if (fun && el && total && !hadTotal.current) {\n animate(el, { opacity: [0, 1], y: [4, 0] }, fun.pop).then(() => Object.assign(el.style, { opacity: \"\", transform: \"\" }));\n }\n hadTotal.current = total !== null;\n }, [total !== null]); // eslint-disable-line react-hooks/exhaustive-deps -- only its arrival matters\n return (\n
  • \n
    \n \n {label}\n \n {total && (\n \n {total.visual}\n {total.spoken}\n \n )}\n
    \n \n
      \n {children}\n
    \n     \n
    • \n );\n}\n\n/* ----------------------------------------------------------------- TimelineStep */\n\nexport type TimelineStepProps = {\n /** The step's start on the run's clock, in the first column: \"00:02\". Leave it out for a step that has not started. */\n at?: string;\n /** What the step does, in sentence case: \"Run build commands\". It wraps on a narrow container. */\n label: string;\n /** How the step stands. The icon shows it and hidden text says it. */\n status: TimelineStatus;\n /** How long the step took, or has taken so far while it runs. Shown at the end of the row (\"19s\") and read as \"19 seconds\". A proportional timeline sizes the row by it. Leave it out for a step that has not run. */\n seconds?: number;\n /** How long the step took last run. A proportional timeline draws a ghost bar of this length beside the bar, with \"was 31s\" at its foot. Ignored when the timeline is not proportional. */\n previousSeconds?: number;\n /** Extra classes for the row. */\n className?: string;\n};\n\n/** One step: its start, a status icon on the rail, its label and its duration. In a proportional timeline a long step draws its time as a bar on the rail. */\nexport function TimelineStep({ at, label, status, seconds: took, previousSeconds, className = \"\" }: TimelineStepProps) {\n const { proportional, secondHeight } = useContext(TimelineContext);\n const { hue } = useContext(PhaseContext);\n\n /* Fun mode: a status that changes pops the icon in, a finished step draws its check, a failed one shakes once. */\n const fun = useFun();\n const icon = useRef(null);\n const was = useRef(status);\n useLayoutEffect(() => {\n const el = icon.current;\n const changed = was.current !== status;\n was.current = status;\n if (!fun || !el || !changed || status === \"pending\") return;\n const settle = () => Object.assign(el.style, { transform: \"\" });\n if (status === \"failed\") animate(el, { x: fun.shake.x }, fun.shake.transition).then(settle);\n else animate(el, { scale: [0.6, 1] }, fun.pop).then(settle);\n const check = status === \"done\" ? el.querySelector(\"path\") : null;\n if (check) {\n check.setAttribute(\"pathLength\", \"1\");\n check.style.strokeDasharray = \"1\";\n animate(check, { strokeDashoffset: [1, 0] }, fun.tick).then(() => {\n check.removeAttribute(\"pathLength\");\n Object.assign(check.style, { strokeDasharray: \"\", strokeDashoffset: \"\" });\n });\n }\n }, [status]); // eslint-disable-line react-hooks/exhaustive-deps -- a status change is what moves it\n\n const ran = isNum(took) && status !== \"skipped\" && status !== \"pending\";\n const bar = proportional && ran ? clean(took) * secondHeight : 0;\n const ghost = proportional && isNum(previousSeconds) && previousSeconds > 0 ? previousSeconds * secondHeight : 0;\n /* A bar shows once it is longer than a row would be anyway, or whenever there is a ghost to compare it with. */\n const showBar = bar >= BAR_MIN || (ghost > 0 && bar > 0);\n const longest = Math.max(showBar ? bar : 0, ghost);\n const captionTop = ghost > 0 ? Math.max(ROW, RAIL_TOP + ghost - CAPTION) : 0;\n const height = Math.max(ROW, longest > 0 ? longest + RAIL_TOP : 0, ghost > 0 ? captionTop + CAPTION : 0);\n\n const dim = status === \"skipped\" || status === \"pending\";\n const shown = status === \"skipped\" ? \"skipped\" : ran ? formatSeconds(clean(took)) : \"\";\n const spoken = ran ? speakSeconds(clean(took)) + (ghost > 0 ? `, was ${speakSeconds(previousSeconds!)} last run` : \"\") : \"\";\n const barTone = status === \"failed\" ? \"bg-litt-danger\" : hue ? MARK[hue] : MARK_FG;\n\n return (\n ROW ? { minHeight: height } : undefined}\n className={\n \"grid min-h-8 grid-cols-[2.5rem_1rem_minmax(0,1fr)_auto] items-start gap-x-3 @min-[28rem]:grid-cols-[3rem_1rem_minmax(0,1fr)_auto] @min-[28rem]:gap-x-4 \" +\n className\n }\n >\n \n {at}\n {at && ,}\n \n\n {/* The rail is decoration: the status and the time are said in the text. */}\n \n