@spunto/design-system 0.20.0 → 0.22.0

package/README.md

@@ -56,6 +56,20 @@ const nextConfig = { transpilePackages: ["@spunto/design-system"] }
     `Separator`, `Spinner`, `Skeleton`, `Avatar` (+`AvatarImage`/`AvatarFallback`),
     `Kbd` — one keyboard cap, or a whole shortcut (`keys="mod+k"` → ⌘ K, Ctrl K off Apple),
     spelled out for screen readers.
+  - _AvatarGroup_ — the stack of overlapping avatars. `size` (`xs`…`xl`) sizes the whole
+    stack at once — on `Avatar` it sets the circle **and** its initials, because a 64 px
+    avatar with 14 px initials looks broken. **Compositional**: the group never reads a
+    `{ name, src }` shape, it wraps whatever you hand it (an `Avatar`, one inside a
+    `Tooltip`, a round `Skeleton` while the list loads) in its own span, so a loading
+    stack has exactly the geometry of the loaded one. It owns only what a caller can't
+    get right by hand: the overlap (a ratio of the diameter, `spacing` = ~40/29/20%), the
+    `ringClassName` that separates two faces (match the surface *behind* the stack —
+    `ring-card` inside a `Card`), the paint order, and the `+N`. Counting has two rules:
+    the counter adds the children `max` cut **and** the people never rendered
+    (`total` − children), so a paginated list shows `+38` without fabricating 38 ghost
+    avatars; and a `+1` never appears — one hidden child takes exactly the room its
+    counter would, saying less, so the face is drawn instead. `onOverflowClick` makes
+    the counter a real button.
   - _Forms_ — `Input`, `Textarea`, `Label`, `Switch`, `Checkbox`,
     `RadioGroup` (+`RadioGroupItem`), `Select` (+`SelectTrigger`/`SelectValue`/
     `SelectContent`/`SelectItem`/`SelectGroup`/`SelectGroupLabel`/`SelectSeparator`).
@@ -332,6 +346,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.22.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/avatar.tsx

@@ -1,18 +1,54 @@
 "use client"
 
+import { Children, createContext, useContext, type ComponentProps, type ReactNode } from "react"
 import { Avatar as AvatarPrimitive } from "@base-ui/react/avatar"
+import { cva, type VariantProps } from "class-variance-authority"
 
 import { cn } from "../utils"
 
+const avatarVariants = cva("relative flex shrink-0 overflow-hidden rounded-full bg-muted select-none", {
+  variants: {
+    // The font-size of each step lives here rather than on the fallback: the
+    // initials then *inherit* it, so one `size` sets the circle and its text
+    // together (a 64 px avatar with 14 px initials looks broken).
+    size: {
+      xs: "size-5 text-[0.5625rem]",
+      sm: "size-7 text-[0.6875rem]",
+      default: "size-9 text-sm",
+      lg: "size-12 text-base",
+      xl: "size-16 text-xl",
+    },
+  },
+  defaultVariants: {
+    size: "default",
+  },
+})
+
+export type AvatarSize = NonNullable<VariantProps<typeof avatarVariants>["size"]>
+
+/**
+ * The size an `AvatarGroup` imposes on the avatars inside it, so a stack is
+ * sized once instead of on every child. `null` = no group above.
+ */
+const AvatarGroupSizeContext = createContext<AvatarSize | null>(null)
+
+export interface AvatarProps extends AvatarPrimitive.Root.Props {
+  /**
+   * Diameter of the circle (20 / 28 / 36 / 48 / 64 px) — and the size of the
+   * fallback initials with it. Inside an `AvatarGroup`, defaults to the group's.
+   * @default "default"
+   */
+  size?: AvatarSize
+}
+
 /** Circular avatar container. Compose `AvatarImage` + `AvatarFallback` inside. */
-function Avatar({ className, ...props }: AvatarPrimitive.Root.Props) {
+function Avatar({ className, size, ...props }: AvatarProps) {
+  const groupSize = useContext(AvatarGroupSizeContext)
+
   return (
     <AvatarPrimitive.Root
       data-slot="avatar"
-      className={cn(
-        "relative flex size-9 shrink-0 overflow-hidden rounded-full bg-muted select-none",
-        className
-      )}
+      className={cn(avatarVariants({ size: size ?? groupSize ?? undefined }), className)}
       {...props}
     />
   )
@@ -29,7 +65,8 @@ function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props)
     <AvatarPrimitive.Fallback
       data-slot="avatar-fallback"
       className={cn(
-        "flex size-full items-center justify-center bg-muted text-sm font-medium text-muted-foreground",
+        // No text-size here on purpose — it comes from the root's `size`.
+        "flex size-full items-center justify-center bg-muted font-medium text-muted-foreground",
         className
       )}
       {...props}
@@ -37,4 +74,169 @@ function AvatarFallback({ className, ...props }: AvatarPrimitive.Fallback.Props)
   )
 }
 
-export { Avatar, AvatarImage, AvatarFallback }
+export type AvatarGroupSpacing = "tight" | "default" | "loose"
+
+// How far each avatar slides under the previous one. Expressed per size because
+// an overlap is a *ratio* of the circle (~29% at default), and Tailwind needs
+// whole class names — hence a table rather than a computed `-ml-${n}`.
+const OVERLAP: Record<AvatarSize, Record<AvatarGroupSpacing, string>> = {
+  xs: { tight: "-ml-2", default: "-ml-1.5", loose: "-ml-1" },
+  sm: { tight: "-ml-3", default: "-ml-2", loose: "-ml-1.5" },
+  default: { tight: "-ml-3.5", default: "-ml-2.5", loose: "-ml-2" },
+  lg: { tight: "-ml-5", default: "-ml-3.5", loose: "-ml-2.5" },
+  xl: { tight: "-ml-6", default: "-ml-5", loose: "-ml-3.5" },
+}
+
+// The ring is what separates two overlapping circles — it has to grow with them.
+const RING: Record<AvatarSize, string> = {
+  xs: "ring-[1.5px]",
+  sm: "ring-2",
+  default: "ring-2",
+  lg: "ring-2",
+  xl: "ring-[3px]",
+}
+
+export interface AvatarGroupProps extends Omit<ComponentProps<"div">, "children"> {
+  /** The avatars, in reading order. Each one paints over its left neighbour. */
+  children?: ReactNode
+  /**
+   * Size applied to every avatar in the stack (a child's own `size` still wins).
+   * @default "default"
+   */
+  size?: AvatarSize
+  /**
+   * Show at most this many avatars; the rest collapse into a `+N` counter.
+   * Left unset, everything is drawn.
+   */
+  max?: number
+  /**
+   * Real number of people, when the caller only renders a sample of them (a
+   * members list that fetched 5 avatars out of 40 → `total={40}` counts the 35
+   * it never received). Defaults to the number of children.
+   */
+  total?: number
+  /**
+   * How much of each avatar the next one covers — ~40%, ~29%, ~20%.
+   * @default "default"
+   */
+  spacing?: AvatarGroupSpacing
+  /**
+   * Ring color punched between overlapping avatars: it must match the surface
+   * *behind* the stack, so inside a `Card` it's `ring-card`.
+   * @default "ring-background"
+   */
+  ringClassName?: string
+  /**
+   * Hovering an avatar brings it to the front (and lifts it a hair), which is
+   * how a covered face becomes readable without a click.
+   * @default true
+   */
+  revealOnHover?: boolean
+  /** Makes the `+N` counter a real button — "see all members". */
+  onOverflowClick?: () => void
+  /** Accessible name of that button. @default "Voir tout" */
+  overflowLabel?: string
+}
+
+/**
+ * A stack of overlapping avatars — the compact way to say "these people".
+ *
+ * ```tsx
+ * <AvatarGroup size="sm" max={4} total={members.length}>
+ *   {members.map((m) => (
+ *     <Avatar key={m.id}>
+ *       <AvatarImage src={m.avatarUrl} alt={m.name} />
+ *       <AvatarFallback>{initials(m.name)}</AvatarFallback>
+ *     </Avatar>
+ *   ))}
+ * </AvatarGroup>
+ * ```
+ *
+ * Purely presentational, and deliberately **compositional**: the group never
+ * reads a `{ name, src }` shape, it wraps whatever you put in it — an `Avatar`,
+ * one inside a `Tooltip`, a `Skeleton` while the list loads. It only owns what
+ * a caller can't get right by hand: the overlap, the ring that separates two
+ * faces, the paint order, and the `+N`.
+ */
+function AvatarGroup({
+  className,
+  children,
+  size = "default",
+  max,
+  total,
+  spacing = "default",
+  ringClassName = "ring-background",
+  revealOnHover = true,
+  onOverflowClick,
+  overflowLabel = "Voir tout",
+  ...props
+}: AvatarGroupProps) {
+  const items = Children.toArray(children)
+  const limit = max != null && max > 0 ? max : items.length
+
+  let shown = items.slice(0, limit)
+  // People the caller knows about but didn't render at all.
+  const unrendered = Math.max(0, (total ?? items.length) - items.length)
+  let overflow = items.length - shown.length + unrendered
+
+  // A single hidden child costs exactly the room a "+1" would take, and says
+  // strictly less. Draw the face instead.
+  if (overflow === 1 && unrendered === 0) {
+    shown = items
+    overflow = 0
+  }
+
+  const item = (node: ReactNode, index: number) => (
+    <span
+      key={index}
+      data-slot="avatar-group-item"
+      className={cn(
+        "relative inline-flex rounded-full",
+        RING[size],
+        ringClassName,
+        index > 0 && OVERLAP[size][spacing],
+        revealOnHover && "transition-transform duration-150 hover:z-10 hover:-translate-y-0.5"
+      )}
+    >
+      {node}
+    </span>
+  )
+
+  const counter = `+${overflow}`
+  const counterClass = cn(
+    avatarVariants({ size }),
+    "items-center justify-center font-medium text-muted-foreground"
+  )
+
+  return (
+    <AvatarGroupSizeContext.Provider value={size}>
+      <div data-slot="avatar-group" className={cn("flex items-center", className)} {...props}>
+        {shown.map(item)}
+        {overflow > 0 &&
+          item(
+            onOverflowClick ? (
+              <button
+                type="button"
+                data-slot="avatar-group-overflow"
+                aria-label={overflowLabel}
+                onClick={onOverflowClick}
+                className={cn(
+                  counterClass,
+                  "cursor-pointer transition-colors hover:bg-primary/15 hover:text-primary focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-ring"
+                )}
+              >
+                {counter}
+              </button>
+            ) : (
+              <span data-slot="avatar-group-overflow" className={counterClass}>
+                {counter}
+              </span>
+            ),
+            shown.length
+          )}
+      </div>
+    </AvatarGroupSizeContext.Provider>
+  )
+}
+
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup }

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"
 

package/src/index.ts

@@ -23,7 +23,11 @@ export { RadioGroup, RadioGroupItem } from "./components/radio-group"
 export { Separator } from "./components/separator"
 export { Skeleton } from "./components/skeleton"
 export { Spinner, spinnerVariants } from "./components/spinner"
-export { Avatar, AvatarImage, AvatarFallback } from "./components/avatar"
+// Avatar + the stack of overlapping avatars (`AvatarGroup`) — compositional:
+// the group wraps whatever you put in it and owns the overlap, the ring, the
+// paint order and the `+N`.
+export { Avatar, AvatarImage, AvatarFallback, AvatarGroup } from "./components/avatar"
+export type { AvatarProps, AvatarSize, AvatarGroupProps, AvatarGroupSpacing } from "./components/avatar"
 
 // xterm.js surface — theme + fit-on-resize, transport-agnostic (feed it via
 // the write/writeln ref handle).