minka-ds 0.4.2 → 0.4.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minka-ds",
-  "version": "0.4.2",
+  "version": "0.4.4",
   "description": "Minka product design system — tokenized component library",
   "license": "MIT",
   "files": [

package/src/components/ui/diagram-node.tsx

@@ -0,0 +1,118 @@
+"use client"
+
+import * as React from "react"
+import { cn } from "../../lib/utils"
+
+export type DiagramNodeVariant = "wallet" | "anchor"
+
+/** Brand pair for state nodes (issue/destroy). */
+export type DiagramAccent =
+  | "yellow-darkforest"
+  | "rose-coral"
+  | "blue-navy"
+  | "beige-bronze"
+  | "gray-black"
+
+export interface DiagramNodeProps {
+  /** Node type — drives default colors. wallet = white/raised, anchor = inverted slate. */
+  variant?: DiagramNodeVariant
+  /** When false, renders a dashed empty slot. */
+  filled?: boolean
+  /** Pair-colored "state" node (issue/destroy). Overrides variant colors. */
+  accent?: DiagramAccent
+  /** Invert the accent fill (light bg + dark text). */
+  accentInverted?: boolean
+  /** Compact sizing (used by anchor/alias nodes). */
+  compact?: boolean
+  className?: string
+  children?: React.ReactNode
+}
+
+// exact-dash rounded border for the empty state
+function DashedBorder({ radius = 10 }: { radius?: number }) {
+  return (
+    <svg className="pointer-events-none absolute inset-0 size-full" aria-hidden>
+      <rect
+        x="0.75" y="0.75"
+        rx={radius} ry={radius}
+        fill="none"
+        stroke="var(--color-border-default)"
+        strokeWidth="1.5"
+        strokeDasharray="6 6"
+        style={{ width: "calc(100% - 1.5px)", height: "calc(100% - 1.5px)" }}
+      />
+    </svg>
+  )
+}
+
+/**
+ * A node card for the diagram family (FlowDiagram, alias resolve, …). Raised
+ * two-layer treatment: a 4px stroke ring underneath + a surface on top whose
+ * lift shadow falls OVER the stroke (button-like). The stroke grows 0→4px as
+ * the node fills (smooth, no layout shift). Empty nodes render a dashed slot.
+ *
+ * Node type is encoded by color: wallet = white/raised, anchor = inverted slate,
+ * accent = pair-colored state (issue/destroy).
+ */
+function DiagramNode({
+  variant = "wallet",
+  filled = true,
+  accent,
+  accentInverted = false,
+  compact = false,
+  className,
+  children,
+}: DiagramNodeProps) {
+  const sizeClass = compact ? "px-4 py-2 min-h-[48px] min-w-[140px]" : "px-5 py-3 min-h-[64px] min-w-[180px]"
+
+  // resolve fill / stroke / text per type
+  let fill = "var(--color-bg-raised)"
+  let stroke = "var(--color-border-default)"
+  let ink: string | undefined
+
+  if (accent) {
+    fill = accentInverted ? `var(--color-pair-${accent}-light)` : `var(--color-pair-${accent}-dark)`
+    stroke = accentInverted ? `var(--color-pair-${accent}-dark)` : `var(--color-pair-${accent}-light)`
+    ink = accentInverted ? "var(--color-text-default)" : "var(--color-text-inverse)"
+  } else if (variant === "anchor") {
+    fill = "var(--color-pair-blue-navy-dark)"
+    stroke = "var(--color-pair-blue-navy-light)"
+    ink = "var(--color-text-inverse)"
+  }
+
+  return (
+    <div
+      data-slot="diagram-node"
+      className={cn("relative inline-flex [border-radius:var(--radius-card)]", className)}
+      style={filled ? { animation: "diagram-node-pop .18s cubic-bezier(0.16,1,0.3,1) both" } : undefined}
+    >
+      <style>{`@keyframes diagram-node-pop { from { opacity:0; transform: scale(.96) } to { opacity:1; transform: scale(1) } }`}</style>
+
+      {/* bottom: stroke ring that grows 0→4px on fill */}
+      <div
+        className="absolute inset-0 [border-radius:var(--radius-card)] transition-[box-shadow] duration-300 ease-out"
+        style={{ boxShadow: filled ? `inset 0 0 0 4px ${stroke}` : "inset 0 0 0 0px transparent" }}
+      />
+
+      {/* top: surface — inset so the ring shows; bg + lift fade in on fill.
+          flex-1 so it fills the wrapper when an explicit width is imposed
+          (e.g. w-full), while still shrink-wrapping content otherwise. */}
+      <div
+        className={cn(
+          "relative m-1 flex flex-1 items-center justify-center [border-radius:calc(var(--radius-card)-4px)] text-center transition-[background-color,box-shadow] duration-300 ease-out",
+          sizeClass,
+        )}
+        style={{
+          backgroundColor: filled ? fill : "var(--color-bg-base)",
+          color: filled ? ink : undefined,
+          boxShadow: filled ? "var(--shadow-raised)" : "none",
+        }}
+      >
+        {!filled && <DashedBorder radius={6} />}
+        {children}
+      </div>
+    </div>
+  )
+}
+
+export { DiagramNode }

package/src/components/ui/expandable-panel.tsx

@@ -0,0 +1,130 @@
+"use client"
+
+import * as React from "react"
+import { ChevronDown } from "lucide-react"
+import { Collapsible, CollapsibleContent } from "./collapsible"
+import { Button } from "./button"
+import { cn } from "../../lib/utils"
+
+// A composed expand/collapse panel: a header row (title + optional subtitle on
+// the left, optional meta + chevron on the right) over a styled body that
+// expands. Built on the DS Collapsible primitive. Domain-agnostic — pass any
+// content as children.
+//
+// When rendered inside an <ExpandablePanelGroup>, panels drop their own border +
+// rounding (the Group owns the frame + shared dividers).
+
+const GroupContext = React.createContext(false)
+
+export interface ExpandablePanelProps {
+  title: React.ReactNode
+  /** Secondary line under the title (e.g. a timestamp). */
+  subtitle?: React.ReactNode
+  /** Right-aligned meta beside the chevron (e.g. "1 proof"). */
+  meta?: React.ReactNode
+  /** Uncontrolled initial open state. */
+  defaultOpen?: boolean
+  /** Controlled open state (pair with onOpenChange). */
+  open?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Body content, revealed when expanded. */
+  children?: React.ReactNode
+  className?: string
+  /** Extra classes for the body region. */
+  contentClassName?: string
+}
+
+function ExpandablePanel({
+  title, subtitle, meta, defaultOpen = false, open, onOpenChange, children, className, contentClassName,
+}: ExpandablePanelProps) {
+  // Controlled or uncontrolled open state. The whole header row toggles it; the
+  // chevron is the DS ghost icon Button (carries the hover), wired to the same state.
+  const [internal, setInternal] = React.useState(defaultOpen)
+  const isOpen = open ?? internal
+  const setOpen = (next: boolean) => {
+    if (open === undefined) setInternal(next)
+    onOpenChange?.(next)
+  }
+  const toggle = () => setOpen(!isOpen)
+  const inGroup = React.useContext(GroupContext)
+
+  return (
+    <Collapsible
+      open={isOpen}
+      onOpenChange={setOpen}
+      data-slot="expandable-panel"
+      className={cn(
+        "overflow-hidden bg-[var(--color-bg-raised)]",
+        // standalone: own border + rounded frame. In a group, the Group owns the
+        // frame and the shared dividers, so the panel is borderless/square.
+        !inGroup && "[border-radius:var(--radius-card)] border border-[var(--color-border-default)]",
+        className,
+      )}
+    >
+      <style>{`
+        @keyframes expandable-down { from { height: 0 } to { height: var(--radix-collapsible-content-height) } }
+        @keyframes expandable-up   { from { height: var(--radix-collapsible-content-height) } to { height: 0 } }
+        [data-slot="expandable-panel-content"][data-state="open"]  { animation: expandable-down .22s ease-out }
+        [data-slot="expandable-panel-content"][data-state="closed"]{ animation: expandable-up .2s ease-in }
+      `}</style>
+
+      {/* Header — the whole row is clickable; only the chevron Button shows hover. */}
+      <div
+        data-slot="expandable-panel-header"
+        onClick={toggle}
+        className="flex w-full cursor-pointer items-center gap-4 px-5 py-3.5 text-left select-none"
+      >
+        <div className="flex min-w-0 flex-1 items-baseline gap-2">
+          <span className="text-label text-[var(--color-text-default)]">{title}</span>
+          {subtitle && <span className="truncate text-caption-light text-[var(--color-text-muted)]">{subtitle}</span>}
+        </div>
+        {meta && <span className="shrink-0 text-overline text-[var(--color-text-muted)]">{meta}</span>}
+        <Button
+          variant="ghost"
+          size="icon-sm"
+          aria-label={isOpen ? "Collapse" : "Expand"}
+          aria-expanded={isOpen}
+          onClick={(e) => { e.stopPropagation(); toggle() }}
+        >
+          <ChevronDown className={cn("size-4 transition-transform duration-200", isOpen && "rotate-180")} />
+        </Button>
+      </div>
+
+      {/* Body — white like the header, no divider */}
+      <CollapsibleContent data-slot="expandable-panel-content" className="overflow-hidden">
+        <div className={cn("bg-[var(--color-bg-raised)] px-5 pb-4", contentClassName)}>
+          {children}
+        </div>
+      </CollapsibleContent>
+    </Collapsible>
+  )
+}
+
+// A stacked group of ExpandablePanels that read as one connected unit: the
+// group owns the outer border + rounded corners (top of first / bottom of last),
+// inner edges are square, and adjacent panels share a single divider. Children
+// drop their own border/rounding via context. `overflow-hidden` clips the inner
+// panels' square corners to the group's rounded frame.
+export interface ExpandablePanelGroupProps {
+  children: React.ReactNode
+  className?: string
+}
+
+function ExpandablePanelGroup({ children, className }: ExpandablePanelGroupProps) {
+  return (
+    <GroupContext.Provider value={true}>
+      <div
+        data-slot="expandable-panel-group"
+        className={cn(
+          "overflow-hidden [border-radius:var(--radius-card)] border border-[var(--color-border-default)]",
+          "divide-y divide-[var(--color-border-default)]",
+          className,
+        )}
+      >
+        {children}
+      </div>
+    </GroupContext.Provider>
+  )
+}
+
+export { ExpandablePanel, ExpandablePanelGroup }

package/src/components/ui/flow-diagram.tsx

@@ -1,6 +1,7 @@
 "use client"
 
 import * as React from "react"
+import { DiagramNode } from "./diagram-node"
 
 /** Brand pair used to give a node / the flow a semantic accent. */
 export type FlowAccent =
@@ -185,72 +186,66 @@ function Connector({
   )
 }
 
-function FlowNodeCard({ node, active, format, pop }: { node: FlowNode; active: boolean; format: FormatFn; pop?: boolean }) {
+function FlowNodeCard({ node, active, format }: { node: FlowNode; active: boolean; format: FormatFn; pop?: boolean }) {
   const showAfter = active && node.after !== null
   const overdrawn = node.after !== null && node.after < 0
 
+  // Empty slot
   if (node.empty) {
     return (
-      <div className="relative flex flex-col items-center justify-center gap-1 [border-radius:var(--radius-card)] bg-[var(--color-bg-base)] px-5 py-3 text-center min-w-[180px] min-h-[64px]">
-        <DashedBorder radius={10} />
+      <DiagramNode filled={false}>
         <span className="text-body-sm text-[var(--color-text-hint)]">{node.name}</span>
-      </div>
+      </DiagramNode>
     )
   }
 
-  // State node (issue/destroy abstract end): pair-colored, no balance. Icon sits
-  // inline next to the main label; subtext below.
+  // State node (issue/destroy): pair-colored, no balance. Icon + label, subtext below.
   if (node.accent) {
-    // default: dark fill + light text; inverted: light fill + dark text.
-    const fill = node.accentInverted ? `var(--color-pair-${node.accent}-light)` : `var(--color-pair-${node.accent}-dark)`
-    const ink  = node.accentInverted ? `var(--color-pair-${node.accent}-dark)` : `var(--color-pair-${node.accent}-light)`
-    const ring = node.accentInverted ? `var(--color-pair-${node.accent}-dark)` : `var(--color-pair-${node.accent}-light)`
     const subInk = node.accentInverted ? "var(--color-text-default)" : "var(--color-text-inverse)"
     return (
-      <div
-        className="flex flex-col items-center gap-1 [border-radius:var(--radius-card)] border px-5 py-3 text-center min-w-[180px]"
-        style={{ backgroundColor: fill, color: ink, borderColor: ring }}
-      >
-        <span className="flex items-center gap-1.5 text-body-sm">
-          {node.icon && <span className="flex items-center [&_svg]:size-4">{node.icon}</span>}
-          {node.name}
-        </span>
-        {node.subtitle && <span className="text-caption" style={{ color: subInk }}>{node.subtitle}</span>}
-      </div>
+      <DiagramNode accent={node.accent} accentInverted={node.accentInverted}>
+        <div className="flex flex-col items-center gap-1">
+          <span className="flex items-center gap-1.5 text-body-sm">
+            {node.icon && <span className="flex items-center [&_svg]:size-4">{node.icon}</span>}
+            {node.name}
+          </span>
+          {node.subtitle && <span className="text-caption" style={{ color: subInk }}>{node.subtitle}</span>}
+        </div>
+      </DiagramNode>
     )
   }
 
+  // Wallet / balance node
   return (
-    <div
-      className="flex flex-col items-center gap-1 [border-radius:var(--radius-card)] border border-[var(--color-border-default)] bg-[var(--color-bg-raised)] px-5 py-3 text-center min-w-[180px]"
-      style={pop ? { animation: "flow-pop .18s cubic-bezier(0.16,1,0.3,1) both" } : undefined}
-    >
-      <span className="text-body-sm text-[var(--color-text-default)]">{node.name}</span>
-
-      {node.current === null ? (
-        node.subtitle ? <span className="text-caption text-[var(--color-text-muted)]">{node.subtitle}</span> : null
-      ) : (
-        <div className="flex flex-col items-center leading-none">
-          <span
-            className={`origin-bottom transition-all duration-300 ${
-              showAfter
-                ? "scale-[0.78] text-caption text-[var(--color-text-muted)] mb-0.5"
-                : "text-label-mono text-[var(--color-text-default)]"
-            }`}
-          >
-            {showAfter ? `was ${format(node.current)}` : format(node.current)}
-          </span>
-          {showAfter && (
+    <DiagramNode variant="wallet">
+      <div className="flex flex-col items-center gap-1">
+        <span className="text-body-sm text-[var(--color-text-default)]">{node.name}</span>
+
+        {node.current === null ? (
+          node.subtitle ? <span className="text-caption text-[var(--color-text-muted)]">{node.subtitle}</span> : null
+        ) : (
+          <div className="flex flex-col items-center leading-none">
             <span
-              className={`text-label-mono ${overdrawn ? "text-[var(--color-feedback-error)]" : "text-[var(--color-text-default)]"}`}
-              style={{ animation: "flow-slide-in .3s ease both" }}
+              className={`origin-bottom transition-all duration-300 ${
+                showAfter
+                  ? "scale-[0.78] text-caption text-[var(--color-text-muted)] mb-0.5"
+                  : "text-label-mono text-[var(--color-text-default)]"
+              }`}
             >
-              {format(node.after!)}
+              {showAfter ? `was ${format(node.current)}` : format(node.current)}
             </span>
-          )}
-        </div>
-      )}
-    </div>
+            {showAfter && (
+              <span
+                className={`text-label-mono ${overdrawn ? "text-[var(--color-feedback-error)]" : "text-[var(--color-text-default)]"}`}
+                style={{ animation: "flow-slide-in .3s ease both" }}
+              >
+                {format(node.after!)}
+              </span>
+            )}
+          </div>
+        )}
+      </div>
+    </DiagramNode>
   )
 }
 

package/src/components/ui/timeline.tsx

@@ -0,0 +1,316 @@
+"use client"
+
+import * as React from "react"
+import { Info } from "lucide-react"
+import { Badge } from "./badge"
+import { Alert, AlertTitle, AlertDescription } from "./alert"
+import { cn } from "../../lib/utils"
+
+// A vertical process timeline: ordered sections, each anchored by a milestone
+// badge, with items (steps) connected by a two-layer rail — a 4px muted "route"
+// always drawn, and a 2px dark "progress" line riding on it from the top down to
+// the step in progress. Sections connect via rounded CSS elbows. Optional
+// annotation rows (a DS Alert) mark boundaries. On failure the timeline can
+// truncate at the failed item.
+//
+// Status vocabulary (fixed): done = success(green), current = warning(amber,
+// pulsing), failed = error(red), upcoming = border-strong(grey).
+
+export type TimelineItemStatus = "done" | "current" | "upcoming" | "failed"
+
+export interface TimelineItem {
+  label: string
+  status: TimelineItemStatus
+  /** Secondary tag shown before the label (e.g. an actor: "Ledger · …"). */
+  meta?: string
+  /** Preformatted timestamp shown first in the row (mono, hint). */
+  timestamp?: string
+  /** Optional "+N" multi-day suffix on the timestamp. */
+  dayOffset?: number
+  /** Failure reason, shown red inline when status is "failed". */
+  detail?: string
+}
+
+export interface TimelineMilestone {
+  label: string
+  variant: "warning" | "info" | "success" | "error"
+  /** Heading shown left of the badge (e.g. a ledger phase term). */
+  lead?: string
+  /** Full-color when true; dimmed when false (not yet reached). */
+  active?: boolean
+}
+
+export interface TimelineAnnotation {
+  title: string
+  description: React.ReactNode
+  /** DS Alert variant; defaults to "info". */
+  variant?: "info" | "success" | "warning" | "error"
+}
+
+export interface TimelineSection {
+  milestone: TimelineMilestone
+  /** Elbow direction: "top" leads into the items below, "end" closes them. */
+  position: "top" | "end"
+  items: TimelineItem[]
+  /** Optional Alert row rendered before this section's items. */
+  annotationBefore?: TimelineAnnotation
+  /** Open a stub gap above the first item (separates from the section above). */
+  gapBefore?: boolean
+}
+
+export interface TimelineProps {
+  sections: TimelineSection[]
+  /** When true, render stops after the first failed item (and its section). */
+  truncateAtFailure?: boolean
+  className?: string
+}
+
+// ── Geometry (shared so dots, lines, and elbows align on one axis) ────────────
+const RAIL_W = 20
+const RAIL_X = RAIL_W / 2
+const RAIL_MUTED = "var(--color-border-default)"
+const RAIL_DARK = "var(--color-text-default)"
+// Dot center aligns to the vertical center of the first text line (text-body-sm
+// = 14px × 1.5 = 21px line box → center at 10.5px). Connectors/elbows derive
+// from DOT_TOP so they shift with it.
+const DOT_TOP = 10.5
+const STROKE = 4       // muted base stroke width — the structural rail
+const STROKE_DARK = 2  // dark progress stroke — thinner, rides over the base
+const STUB_LEN = 12    // partial stub length across a section gap
+const MILESTONE_H = 30 // fixed milestone row height; title-center = H/2
+const ELBOW_RADIUS = 8
+const ELBOW_REACH = RAIL_W / 2 + 2
+const ROW_PB = 12      // pb-3 below a milestone; the top elbow's arm spans it
+const ANNOTATION_ANCHOR = 18 // px to the alert's title line (elbow lands here)
+const ANNOTATION_PB = 16     // pb-4 below the annotation; arm spans it to next dot
+
+type LineBelow = "none" | "muted" | "dark"
+type Stub = "muted" | "dark" | null
+
+// Proof-dot color reads status alone: green done, amber current (pulse), red
+// failed, grey upcoming.
+const DOT_CLASS: Record<TimelineItemStatus, string> = {
+  done:     "bg-[var(--color-feedback-success)]",
+  current:  "bg-[var(--color-feedback-warning)] [animation:tl-pulse_1.6s_ease-in-out_infinite]",
+  failed:   "bg-[var(--color-feedback-error)]",
+  upcoming: "bg-[var(--color-border-strong)]",
+}
+
+// ── Rail segment ──────────────────────────────────────────────────────────────
+// The 4px muted base (the route) is ALWAYS drawn; a 2px dark line overlays it,
+// centered, when `dark` (progress reached here). `bottom` xor `height` sets the
+// lower end.
+function RailSeg({ top, bottom, height, dark }: { top: number; bottom?: number; height?: number; dark: boolean }) {
+  const span: React.CSSProperties = { top, ...(height != null ? { height } : { bottom }) }
+  return (
+    <>
+      <span className="absolute rounded-full" style={{ left: RAIL_X, width: STROKE, backgroundColor: RAIL_MUTED, transform: `translateX(-${STROKE / 2}px)`, ...span }} />
+      {dark && <span className="absolute rounded-full" style={{ left: RAIL_X, width: STROKE_DARK, backgroundColor: RAIL_DARK, transform: `translateX(-${STROKE_DARK / 2}px)`, ...span }} />}
+    </>
+  )
+}
+
+// ── Item row ──────────────────────────────────────────────────────────────────
+// The dot sits at a fixed offset from the row top; the connector runs from this
+// dot's center to the NEXT dot's center. Since every dot shares the same offset,
+// `top: DOT_TOP` → `bottom: -DOT_TOP` lands exactly on the next dot regardless of
+// row height. The dot is painted last, over the connector's start.
+function ItemRow({ item, lineBelow, stubAbove = null, stubBelow = null }: { item: TimelineItem; lineBelow: LineBelow; stubAbove?: Stub; stubBelow?: Stub }) {
+  const upcoming = item.status === "upcoming"
+  const failed = item.status === "failed"
+  return (
+    <div className="flex gap-2">
+      <div className="relative shrink-0" style={{ width: RAIL_W }}>
+        {lineBelow !== "none" && <RailSeg top={DOT_TOP} bottom={-DOT_TOP} dark={lineBelow === "dark"} />}
+        {stubAbove && <RailSeg top={DOT_TOP - STUB_LEN} height={STUB_LEN} dark={stubAbove === "dark"} />}
+        {stubBelow && <RailSeg top={DOT_TOP} height={STUB_LEN} dark={stubBelow === "dark"} />}
+        <span className={`absolute size-2.5 rounded-full ${DOT_CLASS[item.status]}`} style={{ left: RAIL_X, top: DOT_TOP, transform: "translate(-50%, -50%)" }} />
+      </div>
+
+      {/* single line: timestamp (mono, hint) · meta · label */}
+      <div className={`flex flex-1 items-baseline gap-2 pb-4 text-body-sm ${upcoming ? "opacity-45" : ""}`}>
+        {item.timestamp && (
+          <span className="shrink-0 text-caption text-[var(--color-text-hint)] [font-family:var(--font-mono)]">
+            {item.timestamp}
+            {item.dayOffset != null && item.dayOffset > 0 && <span className="ml-0.5 align-super text-[0.7em]">+{item.dayOffset}</span>}
+          </span>
+        )}
+        {item.meta && <span className="text-[var(--color-text-muted)]">{item.meta} ·</span>}
+        <span className="text-[var(--color-text-default)]">{item.label}</span>
+        {failed && item.detail && <span className="text-[var(--color-feedback-error)]">· {item.detail}</span>}
+      </div>
+    </div>
+  )
+}
+
+// ── Milestone elbow ───────────────────────────────────────────────────────────
+// CSS elbow (bordered box, no SVG): a vertical arm + a horizontal arm into the
+// badge, with a rounded corner. Two layers so the 2px dark rides centered on the
+// 4px muted base. Both endpoints anchor to centers (badge-center = MILESTONE_H/2;
+// the adjacent dot is DOT_TOP into the flush neighbour row).
+function Elbow({ position, reached }: { position: "top" | "end"; reached: boolean }) {
+  const TITLE_C = MILESTONE_H / 2
+  const layer = (w: number, c: string): React.CSSProperties => {
+    const d = (STROKE - w) / 2
+    return {
+      position: "absolute",
+      left: RAIL_X,
+      width: ELBOW_REACH,
+      transform: `translateX(-${w / 2}px)`,
+      borderStyle: "solid",
+      borderColor: "transparent",
+      borderLeftWidth: w,
+      borderLeftColor: c,
+      ...(position === "end"
+        ? { top: -DOT_TOP, height: TITLE_C + DOT_TOP - d, borderBottomWidth: w, borderBottomColor: c, borderBottomLeftRadius: ELBOW_RADIUS - d }
+        : { top: TITLE_C + d, height: MILESTONE_H - TITLE_C + ROW_PB + DOT_TOP - d, borderTopWidth: w, borderTopColor: c, borderTopLeftRadius: ELBOW_RADIUS - d }),
+    }
+  }
+  return (
+    <>
+      <span style={layer(STROKE, RAIL_MUTED)} />
+      {reached && <span style={layer(STROKE_DARK, RAIL_DARK)} />}
+    </>
+  )
+}
+
+function MilestoneRow({ milestone, position, reached }: { milestone: TimelineMilestone; position: "top" | "end"; reached: boolean }) {
+  const active = milestone.active ?? true
+  return (
+    <div className="pb-3">
+      <div className="flex items-center gap-2" style={{ height: MILESTONE_H }}>
+        <div className="relative shrink-0 self-stretch" style={{ width: RAIL_W }}>
+          <Elbow position={position} reached={reached} />
+        </div>
+        <div className={`flex items-center gap-2.5 ${active ? "" : "opacity-55"}`}>
+          {milestone.lead && (
+            <span className="text-body-lg font-semibold text-[var(--color-text-default)]">{milestone.lead}</span>
+          )}
+          <Badge variant={milestone.variant} className="text-label px-2.5 py-1">{milestone.label}</Badge>
+        </div>
+      </div>
+    </div>
+  )
+}
+
+// ── Annotation row ────────────────────────────────────────────────────────────
+// A label (not an item — no dot): a DS Alert whose elbow corner sits beside it
+// and whose arm runs DOWN into the next item's dot. Two-layer like the rail.
+function AnnotationRow({ annotation, dark }: { annotation: TimelineAnnotation; dark: boolean }) {
+  const elbowLayer = (w: number, c: string): React.CSSProperties => {
+    const d = (STROKE - w) / 2
+    return {
+      position: "absolute",
+      left: RAIL_X,
+      width: ELBOW_REACH,
+      top: ANNOTATION_ANCHOR + d,
+      bottom: -(DOT_TOP + ANNOTATION_PB),
+      transform: `translateX(-${w / 2}px)`,
+      borderStyle: "solid",
+      borderColor: "transparent",
+      borderLeftWidth: w,
+      borderLeftColor: c,
+      borderTopWidth: w,
+      borderTopColor: c,
+      borderTopLeftRadius: ELBOW_RADIUS - d,
+    }
+  }
+  return (
+    <div className="flex items-start gap-2 pb-4">
+      <div className="relative shrink-0 self-stretch" style={{ width: RAIL_W }}>
+        <span style={elbowLayer(STROKE, RAIL_MUTED)} />
+        {dark && <span style={elbowLayer(STROKE_DARK, RAIL_DARK)} />}
+      </div>
+      <Alert variant={annotation.variant ?? "info"}>
+        <Info />
+        <AlertTitle>{annotation.title}</AlertTitle>
+        <AlertDescription>{annotation.description}</AlertDescription>
+      </Alert>
+    </div>
+  )
+}
+
+// ── Helpers ───────────────────────────────────────────────────────────────────
+const isDone = (i?: TimelineItem) => i?.status === "done"
+const reachedDot = (i?: TimelineItem) => i?.status === "done" || i?.status === "current"
+
+// Connector below an item: none if nothing follows it in-section (gap/elbow
+// joins); dark once flow passed it (done); muted otherwise.
+const lineBelowFor = (i: TimelineItem, nextJoins: boolean): LineBelow =>
+  !nextJoins ? "none" : i.status === "done" ? "dark" : "muted"
+const stubColor = (i?: TimelineItem): Stub => (reachedDot(i) ? "dark" : "muted")
+
+/**
+ * Generic vertical process timeline. See the file header for the model. The
+ * component owns all layout (rail, connectors, elbows, stubs, truncation); the
+ * consumer supplies the data and wraps it (e.g. in a Card) as needed.
+ */
+function Timeline({ sections, truncateAtFailure = false, className }: TimelineProps) {
+  // Find the failing item (across sections) to optionally truncate there.
+  let failedSectionIdx = -1
+  let failedItemIdx = -1
+  if (truncateAtFailure) {
+    for (let s = 0; s < sections.length && failedSectionIdx === -1; s++) {
+      const fi = sections[s].items.findIndex(i => i.status === "failed")
+      if (fi !== -1) { failedSectionIdx = s; failedItemIdx = fi }
+    }
+  }
+  const truncated = failedSectionIdx !== -1
+
+  return (
+    <div className={cn("flex flex-col", className)}>
+      <style>{`@keyframes tl-pulse {
+        0%, 100% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--color-feedback-warning) 45%, transparent); }
+        50%      { box-shadow: 0 0 0 4px color-mix(in srgb, var(--color-feedback-warning) 0%, transparent); }
+      }`}</style>
+
+      {sections.map((section, s) => {
+        if (truncated && s > failedSectionIdx) return null
+        const items = truncated && s === failedSectionIdx
+          ? section.items.slice(0, failedItemIdx + 1)
+          : section.items
+        const sectionFailed = truncated && s === failedSectionIdx
+        const lastItem = items[items.length - 1]
+        // A gap sits between two sections when the FOLLOWING section opts in via
+        // gapBefore: this section's last item gets a stub below, the next
+        // section's first item a stub above — together forming the broken gap.
+        const next = sections[s + 1]
+        const closeWithGap = section.position === "top" && !sectionFailed && !!next?.gapBefore
+
+        return (
+          <React.Fragment key={s}>
+            {section.position === "top" && (
+              <MilestoneRow milestone={section.milestone} position="top" reached={isDone(items[0])} />
+            )}
+
+            {section.annotationBefore && (
+              <AnnotationRow annotation={section.annotationBefore} dark={stubColor(items[0]) === "dark"} />
+            )}
+
+            {items.map((item, i) => {
+              const isLast = i === items.length - 1
+              return (
+                <ItemRow
+                  key={i}
+                  item={item}
+                  lineBelow={lineBelowFor(item, !isLast)}
+                  stubBelow={isLast && closeWithGap ? stubColor(item) : null}
+                  // a stub above the first item only when this section opts into a
+                  // gap AND it isn't introduced by an annotation (the annotation's
+                  // elbow already connects down into the first item).
+                  stubAbove={i === 0 && section.gapBefore && !section.annotationBefore ? stubColor(item) : null}
+                />
+              )
+            })}
+
+            {section.position === "end" && !sectionFailed && (
+              <MilestoneRow milestone={section.milestone} position="end" reached={isDone(lastItem)} />
+            )}
+          </React.Fragment>
+        )
+      })}
+    </div>
+  )
+}
+
+export { Timeline }

package/src/index.ts

@@ -44,7 +44,10 @@ export * from "./components/ui/tabs"
 export * from "./components/ui/textarea"
 export * from "./components/ui/tooltip"
 export * from "./components/ui/flow-diagram"
+export * from "./components/ui/diagram-node"
 export * from "./components/ui/help-expander"
+export * from "./components/ui/timeline"
+export * from "./components/ui/expandable-panel"
 
 // Brand textures + logo
 export * from "./textures"

package/tokens/primitives.css

@@ -240,6 +240,7 @@
   --primitive-shadow-md: 0 4px 6px oklch(0 0 0 / 0.07), 0 2px 4px oklch(0 0 0 / 0.06);
   --primitive-shadow-lg: 0 10px 15px oklch(0 0 0 / 0.10), 0 4px 6px oklch(0 0 0 / 0.05);
   --primitive-shadow-xl: 0 20px 25px oklch(0 0 0 / 0.10), 0 8px 10px oklch(0 0 0 / 0.04);
+  --primitive-shadow-raised: 0 4px 12px -1px oklch(0 0 0 / 0.18), 0 2px 5px -1px oklch(0 0 0 / 0.12);
 
   /* --- Z-index scale --- */
   --primitive-z-base:      0;

package/tokens/semantic.css

@@ -192,6 +192,7 @@
   --shadow-card:    var(--primitive-shadow-xs);
   --shadow-popover: var(--primitive-shadow-md);
   --shadow-modal:   var(--primitive-shadow-lg);
+  --shadow-raised:  var(--primitive-shadow-raised);
 }
 
 /* ── Dark mode ───────────────────────────────────────────────────── */
@@ -321,4 +322,5 @@
   --shadow-card:    none;
   --shadow-popover: var(--primitive-shadow-lg);
   --shadow-modal:   var(--primitive-shadow-xl);
+  --shadow-raised:  var(--primitive-shadow-raised);
 }