@spunto/design-system 0.20.0 → 0.21.0

package/README.md

@@ -332,6 +332,29 @@ And the read-only twin of that form:
 - **Container queries** here too: the panel is 288 px in a sidebar on a 27" screen
   and full width on a phone — and the desktop case is the narrow one.
 
+And the build that configuration triggers, while it runs:
+
+- **`BuildSteps`** — an image build as the **list of blocks it is made of**
+  (base image, bootstrap, one per devcontainer feature, VS Code extensions,
+  finalize, DinD seed) rather than a wall of log. Each row lights up in turn and
+  carries its own duration, so "what is it doing, and for how long" reads at a
+  glance and a slow feature is visibly *the* slow one.
+- **The whole plan is drawn greyed out from the first frame**, instead of rows
+  appearing one by one: the list doubles as a table of contents for what the
+  image contains, the `done/total` counter has a denominator immediately, and
+  nothing shifts under the cursor for the four minutes of a build. A block
+  *absent* from the plan isn't `skipped` — `skipped` is a block that was reached
+  and had nothing to do.
+- **Presentational, so it isn't only about Docker**: it knows no WebSocket, no
+  marker, no daemon — hand it a snapshot of timestamped blocks and it draws.
+  Anything that can describe itself as ordered blocks (a CI pipeline, a
+  migration, a multi-phase command) can feed it.
+- **Timestamps in, durations out.** The running block counts from `startedAt`
+  itself, every second — a duration computed app-side freezes between two
+  snapshots and reads as a stuck build. Under a minute the package's
+  `formatDuration` is reused (one formatter, no drift); past it the format
+  switches to `2m 13s`.
+
 ## Marketing — `/marketing`
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.20.0",
+  "version": "0.21.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/projects/build-steps.tsx

@@ -0,0 +1,213 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import {
+  BoxIcon,
+  CheckIcon,
+  CircleIcon,
+  LayersIcon,
+  Loader2Icon,
+  MinusIcon,
+  PuzzleIcon,
+  TerminalIcon,
+  XIcon,
+} from "lucide-react"
+
+import { cn, formatDuration } from "../../utils"
+
+export type BuildStepState = "pending" | "running" | "done" | "error" | "skipped"
+
+/** The family a block belongs to — an icon, not a status. */
+export type BuildStepKind = "image" | "runtime" | "feature" | "extensions" | "finalize"
+
+export interface BuildStepItem {
+  id: string
+  label: string
+  kind: BuildStepKind
+  /** Second line: the base image ref, a feature's OCI ref, "3 extensions"… */
+  detail?: string
+  state: BuildStepState
+  /** ISO timestamps — the elapsed time of the running block ticks from `startedAt`. */
+  startedAt?: string
+  completedAt?: string
+}
+
+export interface BuildStepsProps {
+  steps: BuildStepItem[]
+  title?: string
+  /** Shown instead of the list when there is nothing to draw yet. */
+  emptyLabel?: string
+  className?: string
+}
+
+const KIND_ICON: Record<BuildStepKind, typeof BoxIcon> = {
+  image: LayersIcon,
+  runtime: TerminalIcon,
+  feature: PuzzleIcon,
+  extensions: PuzzleIcon,
+  finalize: BoxIcon,
+}
+
+/**
+ * `formatDuration` with a minutes tier on top.
+ *
+ * The package's formatter stops at seconds, which is right where it is used
+ * (a command, a request) and wrong here: pulling a base image or compiling a
+ * feature routinely passes the minute, and "127s" is a number one has to
+ * convert before reading it. Below a minute it delegates, so the two never
+ * drift on the part they share.
+ */
+function formatStepDuration(ms: number): string {
+  if (ms < 60_000) return formatDuration(ms)
+  const s = Math.round(ms / 1000)
+  const m = Math.floor(s / 60)
+  const rest = s % 60
+  return rest ? `${m}m ${rest}s` : `${m}m`
+}
+
+/** Elapsed for a block: fixed once it ended, ticking while it runs. */
+function useStepDuration(step: BuildStepItem): string | null {
+  const running = step.state === "running" && !!step.startedAt
+  const [now, setNow] = useState(() => Date.now())
+
+  useEffect(() => {
+    if (!running) return
+    const id = setInterval(() => setNow(Date.now()), 1000)
+    return () => clearInterval(id)
+  }, [running])
+
+  if (!step.startedAt) return null
+  const start = new Date(step.startedAt).getTime()
+  if (Number.isNaN(start)) return null
+  const end = step.completedAt ? new Date(step.completedAt).getTime() : running ? now : null
+  if (end == null || Number.isNaN(end)) return null
+  return formatStepDuration(end - start)
+}
+
+function StepBullet({ state }: { state: BuildStepState }) {
+  const base = "flex h-5 w-5 shrink-0 items-center justify-center rounded-full border"
+  if (state === "running")
+    return (
+      <span className={cn(base, "border-primary/40 bg-primary/10 text-primary")}>
+        <Loader2Icon className="h-3 w-3 animate-spin motion-reduce:animate-none" />
+      </span>
+    )
+  if (state === "done")
+    return (
+      <span className={cn(base, "border-green-500/40 bg-green-500/10 text-green-600 dark:text-green-400")}>
+        <CheckIcon className="h-3 w-3" />
+      </span>
+    )
+  if (state === "error")
+    return (
+      <span className={cn(base, "border-destructive/40 bg-destructive/10 text-destructive")}>
+        <XIcon className="h-3 w-3" />
+      </span>
+    )
+  if (state === "skipped")
+    return (
+      <span className={cn(base, "border-border bg-muted/40 text-muted-foreground/60")}>
+        <MinusIcon className="h-3 w-3" />
+      </span>
+    )
+  return (
+    <span className={cn(base, "border-border bg-background text-muted-foreground/40")}>
+      <CircleIcon className="h-1.5 w-1.5 fill-current" />
+    </span>
+  )
+}
+
+function StepRow({ step, last }: { step: BuildStepItem; last: boolean }) {
+  const duration = useStepDuration(step)
+  const KindIcon = KIND_ICON[step.kind] ?? BoxIcon
+  const dim = step.state === "pending" || step.state === "skipped"
+
+  return (
+    <li className="relative flex gap-2.5 pb-2.5 last:pb-0">
+      {/* The rail joining the bullets — drawn behind them, stopped on the last row. */}
+      {!last && <span aria-hidden className="absolute left-[9px] top-5 h-full w-px bg-border" />}
+      <StepBullet state={step.state} />
+
+      <div className="min-w-0 flex-1">
+        <div className="flex items-baseline gap-2">
+          <span
+            className={cn(
+              "min-w-0 flex-1 truncate text-[12px] leading-5",
+              step.state === "running" && "font-medium text-foreground",
+              step.state === "done" && "text-foreground",
+              step.state === "error" && "font-medium text-destructive",
+              dim && "text-muted-foreground/70",
+            )}
+            title={step.label}
+          >
+            {step.label}
+          </span>
+          {duration && (
+            <span className="shrink-0 font-mono text-[10px] tabular-nums text-muted-foreground">{duration}</span>
+          )}
+        </div>
+        {step.detail && (
+          <div className="flex items-center gap-1 text-[10px] text-muted-foreground/70">
+            <KindIcon className="h-2.5 w-2.5 shrink-0" />
+            <span className="min-w-0 truncate" title={step.detail}>
+              {step.detail}
+            </span>
+          </div>
+        )}
+      </div>
+    </li>
+  )
+}
+
+/**
+ * An image build, as the list of blocks it is actually made of, instead of a wall of log.
+ *
+ * A project image build pulls a base image, creates the user, installs the editor and the terminal
+ * tooling, every devcontainer feature and every VS Code extension, then bakes the DinD seed — all of
+ * it, until now, indistinguishable from the outside: one terminal scrolling. Here each of those is a
+ * row that lights up in turn, with its own duration, so "what is it doing, and for how long" is
+ * readable at a glance and a slow feature is visibly *the* slow one.
+ *
+ * Purely presentational — it draws the snapshot it's given (the app streams it from the build's log
+ * socket, and owns every byte of that transport). The whole plan is known upfront, so the blocks
+ * that haven't run yet are drawn greyed out rather than appearing one by one: it doubles as a table
+ * of contents for what the image is made of, which is what these blocks are on their way to becoming
+ * (a checklist of what to include).
+ *
+ * Sized by its container, scrolls inside it: give it a height (`className="h-full"` in a panel) and
+ * only the list scrolls — the header with its `done/total` counter stays put.
+ */
+export function BuildSteps({ steps, title = "Build steps", emptyLabel = "No step reported", className }: BuildStepsProps) {
+  const done = steps.filter((s) => s.state === "done").length
+  const failed = steps.some((s) => s.state === "error")
+
+  return (
+    <div data-slot="build-steps" className={cn("flex min-h-0 flex-col", className)}>
+      <div className="flex shrink-0 items-baseline justify-between gap-2 px-3 py-2">
+        <span className="text-[11px] font-medium text-muted-foreground">{title}</span>
+        {steps.length > 0 && (
+          <span
+            className={cn(
+              "font-mono text-[10px] tabular-nums",
+              failed ? "text-destructive" : "text-muted-foreground",
+            )}
+          >
+            {done}/{steps.length}
+          </span>
+        )}
+      </div>
+
+      <div className="min-h-0 flex-1 overflow-y-auto px-3 pb-3">
+        {steps.length === 0 ? (
+          <p className="text-[11px] text-muted-foreground/70">{emptyLabel}</p>
+        ) : (
+          <ol className="relative">
+            {steps.map((step, i) => (
+              <StepRow key={step.id} step={step} last={i === steps.length - 1} />
+            ))}
+          </ol>
+        )}
+      </div>
+    </div>
+  )
+}

package/src/components/projects/index.ts

@@ -92,6 +92,13 @@ export type { ChipListProps, ChipItem, ChipTone } from "./chip-list"
 export { BuildCacheList, BuildStateLabel, PrebuildButton } from "./build-cache-list"
 export type { BuildCacheListProps, PrebuildButtonProps } from "./build-cache-list"
 
+// The build itself, while it runs: the blocks an image is made of, each lighting
+// up in turn. Same domain as the cache list it sits next to (a project's image),
+// hence this entry rather than one of its own — and domain it is, since the
+// blocks are Spunto's (a devcontainer feature, a VS Code extension).
+export { BuildSteps } from "./build-steps"
+export type { BuildStepsProps, BuildStepItem, BuildStepKind, BuildStepState } from "./build-steps"
+
 export { LifecycleCommands, LifecycleCommand } from "./lifecycle-commands"
 export type { LifecycleCommandsProps, LifecycleCommandProps } from "./lifecycle-commands"