Run timeline

Once per app, add the registry to components.json:

{
  "registries": {
    "@pixilui": "https://pixilui.com/r/{name}.json"
  }
}

Or install from the URL, no namespace needed: npx shadcn@latest add https://pixilui.com/r/run-timeline.json

1. 1

   Install the npm packages.

   TerminalCopy

   npm install motion clsx tailwind-merge

2. 2

   Add the items it depends on, the same way.

   • Foundation
3. 3

   Copy each file to the path shown.

   components/pixilui/run-timeline.tsxCopy

   "use client";
   
   import { forwardRef, useEffect, useState, useSyncExternalStore, type ComponentPropsWithoutRef, type KeyboardEvent, type ReactNode } from "react";
   import { AnimatePresence, motion, useReducedMotion } from "motion/react";
   import { cn } from "./lib/utils";
   import { instantTransition, motionTokens, reducedTransition } from "./motion-tokens";
   
   const noSubscription = () => () => {};
   
   /**
    * useReducedMotion, held at false until hydration finishes. The server cannot know the
    * preference, so reading it on the first client render would change the markup and break
    * hydration; the reduced branch takes over on the next render instead.
    */
   function useReducedMotionAfterHydration() {
     const hydrated = useSyncExternalStore(noSubscription, () => true, () => false);
     const reduced = useReducedMotion();
     return hydrated && (reduced ?? false);
   }
   
   export type RunTimelineStatus = "pending" | "active" | "done" | "error" | "waiting";
   
   export type RunTimelineStep = {
     /** Stable key for the step; onStepSelect receives it. */
     id: string;
     /** What the step does, in a few words: "Pull stuck refunds from Stripe". */
     title: ReactNode;
     /** Evidence once it ran ("9 refunds pending for more than 72 hours"), or why it failed. Hidden in compact mode. */
     detail?: ReactNode;
     /** Pending, active (live timer), done (drawn check), error, or waiting on a person. */
     status: RunTimelineStatus;
     /** When the step started (epoch ms). Drives the live timer and the duration. */
     startedAt?: number;
     /** When the step finished (epoch ms). With startedAt, shows how long it took. */
     endedAt?: number;
     /** Content under the step: an approval card on a waiting step, a tool call, a diff. Waiting steps show it in compact mode too. */
     children?: ReactNode;
   };
   
   export type RunTimelineLabels = Record<RunTimelineStatus, string>;
   
   const defaultLabels: RunTimelineLabels = {
     pending: "Up next",
     active: "In progress",
     done: "Done",
     error: "Failed",
     waiting: "Needs approval",
   };
   
   export type RunTimelineProps = Omit<ComponentPropsWithoutRef<"ol">, "children"> & {
     /** The run's steps, in order. Update a step's status and the timeline animates the change. */
     steps: RunTimelineStep[];
     /** Titles only, tighter rhythm. Waiting steps still show their children. */
     compact?: boolean;
     /** Makes each step a button. Called with the step's id. */
     onStepSelect?: (id: string) => void;
     /** The step shown elsewhere (a detail pane), marked with data-selected. */
     selectedId?: string;
     /** Status words, read by screen readers and shown for waiting and failed steps. */
     labels?: Partial<RunTimelineLabels>;
   };
   
   const TICK_MS = 250;
   
   /** "820ms", "1.4s", "1m 04s". */
   function formatDuration(ms: number) {
     if (ms < 1000) return `${Math.round(ms)}ms`;
     if (ms < 60_000) return `${(ms / 1000).toFixed(1)}s`;
     const s = Math.round(ms / 1000);
     return `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`;
   }
   
   function formatLive(ms: number) {
     const s = Math.floor(ms / 1000);
     return s < 60 ? `${s}s` : `${Math.floor(s / 60)}m ${String(s % 60).padStart(2, "0")}s`;
   }
   
   /** A live timer whose digits are keyed by place and roll up. Only this re-renders each tick. */
   function LiveTimer({ startedAt, reduced }: { startedAt: number; reduced: boolean }) {
     const [now, setNow] = useState<number | null>(null);
     useEffect(() => {
       const tick = () => setNow(Date.now());
       tick();
       const id = setInterval(tick, TICK_MS);
       return () => clearInterval(id);
     }, [startedAt]);
     if (now === null) return null;
     const value = formatLive(Math.max(0, now - startedAt));
     const chars = value.split("");
     return (
       <span role="timer" aria-label={value} className="numeric inline-flex">
         {chars.map((char, index) => {
           const place = chars.length - index;
           if (reduced || !/\d/.test(char)) {
             return (
               <span key={place} aria-hidden="true">
                 {char}
               </span>
             );
           }
           return (
             <span key={place} aria-hidden="true" className="relative inline-flex h-[1lh] overflow-hidden">
               <AnimatePresence initial={false} mode="popLayout">
                 <motion.span key={char} initial={{ y: "100%" }} animate={{ y: 0 }} exit={{ y: "-100%" }} transition={motionTokens.spring.snappy}>
                   {char}
                 </motion.span>
               </AnimatePresence>
             </span>
           );
         })}
       </span>
     );
   }
   
   /** Glyph rings sit between the 1px hairline and a 2px border. */
   const ring = { borderWidth: 1.5 };
   
   function Mark({ status, reduced }: { status: RunTimelineStatus; reduced: boolean }) {
     const draw = reduced
       ? { initial: { pathLength: 1 }, transition: reducedTransition }
       : { initial: { pathLength: 0 }, transition: { duration: motionTokens.duration.slow, ease: motionTokens.ease.enter, delay: motionTokens.stagger.item * 2 } };
     switch (status) {
       case "pending":
         return <span className="size-2.5 rounded-pill border-solid border-border-strong" style={ring} />;
       case "active":
         return (
           <span className="grid size-5 place-items-center rounded-pill border-solid border-accent-solid" style={ring}>
             <span className="size-2 rounded-pill bg-accent-solid" />
           </span>
         );
       case "done":
         return (
           <span className="grid size-5 place-items-center rounded-pill bg-accent-solid text-accent-contrast">
             <svg viewBox="0 0 12 12" fill="none" className="size-3">
               <motion.path d="M2.75 6.25l2.25 2.25 4.25-4.75" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" strokeLinejoin="round" initial={draw.initial} animate={{ pathLength: 1 }} transition={draw.transition} />
             </svg>
           </span>
         );
       case "error":
         return (
           <span className="grid size-5 place-items-center rounded-pill bg-danger-subtle text-danger">
             <svg viewBox="0 0 12 12" fill="none" className="size-3">
               <motion.path d="M3.75 3.75l4.5 4.5M8.25 3.75l-4.5 4.5" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" initial={draw.initial} animate={{ pathLength: 1 }} transition={draw.transition} />
             </svg>
           </span>
         );
       case "waiting":
         return (
           <span className="grid size-5 place-items-center rounded-pill bg-warning-subtle text-warning">
             <svg viewBox="0 0 12 12" fill="none" className="size-3">
               <path d="M4.5 3.5v5M7.5 3.5v5" stroke="currentColor" strokeWidth="1.6" strokeLinecap="round" />
             </svg>
           </span>
         );
     }
   }
   
   /**
    * Detail and children open their own height, so the steps below are pushed along in the flow
    * (no overlap while the content fades in). Growing uses morph, closing uses smooth. The clip is
    * lifted once it has opened, so an approval card's shadow and focus ring show in full.
    */
   function Reveal({ reduced, className, children, ...rest }: { reduced: boolean; className?: string; children: ReactNode; "data-slot"?: string }) {
     const [clip, setClip] = useState(true);
     const motionProps = reduced
       ? {
           initial: { opacity: 0 },
           animate: { opacity: 1 },
           exit: { opacity: 0, height: 0, transition: instantTransition },
           transition: reducedTransition,
         }
       : {
           initial: { opacity: 0, height: 0, filter: `blur(${motionTokens.blur.subtle}px)` },
           animate: {
             opacity: 1,
             height: "auto",
             filter: "blur(0px)",
             transition: {
               height: motionTokens.spring.morph,
               default: { duration: motionTokens.duration.fast, ease: motionTokens.ease.enter, delay: motionTokens.stagger.item * 2 },
             },
           },
           exit: {
             opacity: 0,
             height: 0,
             filter: `blur(${motionTokens.blur.subtle}px)`,
             transition: { height: motionTokens.spring.smooth, default: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } },
           },
         };
     return (
       <motion.div
         {...rest}
         {...motionProps}
         className={className}
         style={{ overflow: clip && !reduced ? "hidden" : "visible" }}
         onAnimationStart={() => setClip(true)}
         onAnimationComplete={() => setClip(false)}
       >
         {children}
       </motion.div>
     );
   }
   
   export const RunTimeline = forwardRef<HTMLOListElement, RunTimelineProps>(function RunTimeline(
     { steps, compact = false, onStepSelect, selectedId, labels: labelsProp, className, onKeyDown, ...rest },
     ref,
   ) {
     const labels = { ...defaultLabels, ...labelsProp };
     const reduced = useReducedMotionAfterHydration();
   
     // Up and Down walk the step buttons, Home and End jump to the ends.
     const handleKeyDown = (event: KeyboardEvent<HTMLOListElement>) => {
       onKeyDown?.(event);
       if (event.defaultPrevented || !onStepSelect || !["ArrowDown", "ArrowUp", "Home", "End"].includes(event.key)) return;
       const buttons = Array.from(event.currentTarget.querySelectorAll<HTMLElement>('[data-slot="run-timeline-trigger"]'));
       const current = buttons.indexOf(event.target as HTMLElement);
       if (current === -1) return;
       event.preventDefault();
       const next =
         event.key === "Home" ? 0 : event.key === "End" ? buttons.length - 1 : Math.min(buttons.length - 1, Math.max(0, current + (event.key === "ArrowDown" ? 1 : -1)));
       buttons[next]?.focus();
     };
   
     const swapIn = reduced
       ? { initial: { opacity: 0 }, animate: { opacity: 1 }, exit: { opacity: 0, transition: instantTransition }, transition: instantTransition }
       : {
           initial: { opacity: 0, scale: motionTokens.scale.enterFrom, filter: `blur(${motionTokens.blur.subtle}px)` },
           animate: { opacity: 1, scale: 1, filter: "blur(0px)" },
           exit: { opacity: 0, filter: `blur(${motionTokens.blur.subtle}px)`, transition: { duration: motionTokens.duration.instant, ease: motionTokens.ease.exit } },
           transition: { duration: motionTokens.duration.fast, ease: motionTokens.ease.swap },
         };
   
     return (
       <ol
         ref={ref}
         data-compact={compact || undefined}
         className={cn("flex w-full min-w-0 flex-col font-body text-14 text-foreground", className)}
         onKeyDown={handleKeyDown}
         {...rest}
       >
         {steps.map((step, index) => {
           const last = index === steps.length - 1;
           const duration = step.startedAt !== undefined && step.endedAt !== undefined ? step.endedAt - step.startedAt : null;
           const showDetail = !compact && step.detail;
           const showChildren = step.children && (!compact || step.status === "waiting");
           const flagged = step.status === "waiting" || step.status === "error";
   
           const titleRow = (
             <>
               <span className={cn("min-w-0 flex-1 text-pretty font-medium transition-colors duration-fast ease-swap", step.status === "pending" ? "text-muted" : "text-foreground")}>
                 {step.title}
               </span>
               <span className="flex shrink-0 items-center gap-2 pt-px text-12 text-muted">
                 {flagged ? <span className={step.status === "error" ? "text-danger" : "text-warning"}>{labels[step.status]}</span> : null}
                 {step.status === "active" && step.startedAt !== undefined ? <LiveTimer startedAt={step.startedAt} reduced={reduced} /> : null}
                 {step.status === "done" && duration !== null ? <span className="numeric">{formatDuration(duration)}</span> : null}
               </span>
             </>
           );
   
           return (
             <li
               key={step.id}
               data-status={step.status}
               data-selected={selectedId === step.id || undefined}
               aria-current={step.status === "active" ? "step" : undefined}
               className="relative grid min-w-0 grid-cols-[1.25rem_minmax(0,1fr)] gap-x-3"
             >
               {/* Rail: the glyph, then the connector to the next step, which fills when this one is done. */}
               <span aria-hidden="true" className="relative flex justify-center">
                 <span className="relative mt-0.5 grid size-5 place-items-center">
                   <AnimatePresence initial={false}>
                     <motion.span key={step.status} data-slot="run-timeline-glyph" className="absolute inset-0 grid place-items-center" {...swapIn}>
                       <Mark status={step.status} reduced={reduced} />
                     </motion.span>
                   </AnimatePresence>
                 </span>
                 {last ? null : (
                   <span className="absolute top-7 bottom-1 left-1/2 w-0.5 -translate-x-1/2 overflow-hidden rounded-pill bg-border">
                     <motion.span
                       data-slot="run-timeline-connector"
                       className="absolute inset-0 origin-top rounded-pill bg-accent-solid"
                       initial={false}
                       animate={{ scaleY: step.status === "done" ? 1 : 0 }}
                       transition={reduced ? instantTransition : { duration: motionTokens.duration.slow, ease: motionTokens.ease.linear }}
                     />
                   </span>
                 )}
               </span>
   
               <div className={cn("min-w-0", last ? "pb-0" : compact ? "pb-3" : "pb-6")}>
                 {onStepSelect ? (
                   <button
                     type="button"
                     data-slot="run-timeline-trigger"
                     aria-pressed={selectedId !== undefined ? selectedId === step.id : undefined}
                     onClick={() => onStepSelect(step.id)}
                     className={cn(
                       "-mx-2 -my-1 flex w-[calc(100%+1rem)] min-w-0 items-start gap-3 rounded-control px-2 py-1 text-left outline-none transition-colors duration-instant ease-swap hover-fine:bg-surface-muted focus-visible:focus-ring",
                       selectedId === step.id && "bg-surface-muted",
                     )}
                   >
                     {titleRow}
                   </button>
                 ) : (
                   <div className="flex min-w-0 items-start gap-3">{titleRow}</div>
                 )}
                 <span className="sr-only">{labels[step.status]}</span>
   
                 <AnimatePresence initial={false}>
                   {showDetail ? (
                     <Reveal key="detail" reduced={reduced}>
                       <div className={cn("pt-0.5 text-pretty", step.status === "error" ? "text-danger" : "text-secondary")}>{step.detail}</div>
                     </Reveal>
                   ) : null}
                 </AnimatePresence>
                 <AnimatePresence initial={false}>
                   {showChildren ? (
                     <Reveal key="children" data-slot="run-timeline-children" className="min-w-0" reduced={reduced}>
                       <div className="pt-3">{step.children}</div>
                     </Reveal>
                   ) : null}
                 </AnimatePresence>
               </div>
             </li>
           );
         })}
       </ol>
     );
   });

4. 4

   Check that your global stylesheet imports the foundation, after Tailwind.

   app/globals.cssCopy

   @import "tailwindcss";
   @import "../components/pixilui/foundation.css";