@spunto/design-system 0.9.2 → 0.10.0

package/src/components/kbd.tsx

@@ -0,0 +1,117 @@
+"use client"
+
+import { useEffect, useState, type ComponentProps } from "react"
+
+import { cn } from "../utils"
+
+// One key = one cap. Kept as a constant so `Kbd` and every caller (the command
+// palette footer, an item's `shortcut`) draw the exact same box.
+const capClass =
+  "inline-flex h-5 min-w-5 items-center justify-center rounded border border-border bg-muted px-1.5 font-sans text-[0.6875rem] leading-none font-medium text-muted-foreground"
+
+/**
+ * Symbol shown per modifier, per platform, plus the accessible name a screen
+ * reader gets instead of the glyph ("⌘" alone reads as nothing useful).
+ * `mod` is the portable modifier: ⌘ on Apple, Ctrl everywhere else — the one
+ * every "⌘K" shortcut actually means.
+ */
+const KEYS: Record<string, { mac: string; other: string; label: string }> = {
+  mod: { mac: "⌘", other: "Ctrl", label: "Ctrl" },
+  meta: { mac: "⌘", other: "Win", label: "Meta" },
+  cmd: { mac: "⌘", other: "Ctrl", label: "Commande" },
+  command: { mac: "⌘", other: "Ctrl", label: "Commande" },
+  ctrl: { mac: "⌃", other: "Ctrl", label: "Ctrl" },
+  control: { mac: "⌃", other: "Ctrl", label: "Ctrl" },
+  alt: { mac: "⌥", other: "Alt", label: "Alt" },
+  option: { mac: "⌥", other: "Alt", label: "Alt" },
+  shift: { mac: "⇧", other: "Maj", label: "Maj" },
+  enter: { mac: "↵", other: "↵", label: "Entrée" },
+  return: { mac: "↵", other: "↵", label: "Entrée" },
+  esc: { mac: "esc", other: "esc", label: "Échap" },
+  escape: { mac: "esc", other: "esc", label: "Échap" },
+  backspace: { mac: "⌫", other: "⌫", label: "Retour arrière" },
+  delete: { mac: "⌦", other: "Suppr", label: "Suppr" },
+  tab: { mac: "⇥", other: "⇥", label: "Tab" },
+  space: { mac: "␣", other: "␣", label: "Espace" },
+  up: { mac: "↑", other: "↑", label: "Flèche haut" },
+  down: { mac: "↓", other: "↓", label: "Flèche bas" },
+  left: { mac: "←", other: "←", label: "Flèche gauche" },
+  right: { mac: "→", other: "→", label: "Flèche droite" },
+}
+
+/**
+ * Apple platform detection, deferred to an effect on purpose: the package is
+ * consumed from a Next.js App Router, so the first render must be identical on
+ * the server and on the client. We render the portable label ("Ctrl") first and
+ * swap to "⌘" after mount rather than reading `navigator` during render.
+ */
+function useApplePlatform(): boolean {
+  const [isApple, setIsApple] = useState(false)
+  useEffect(() => {
+    const ua = navigator.userAgent
+    setIsApple(/Mac|iPhone|iPad|iPod/.test(ua))
+  }, [])
+  return isApple
+}
+
+function keyGlyph(part: string, isApple: boolean): string {
+  const known = KEYS[part.toLowerCase()]
+  if (known) return isApple ? known.mac : known.other
+  // Single letters read better upper-cased ("K"), longer names as written ("F5").
+  return part.length === 1 ? part.toUpperCase() : part
+}
+
+function keyLabel(part: string): string {
+  return KEYS[part.toLowerCase()]?.label ?? part.toUpperCase()
+}
+
+export interface KbdProps extends ComponentProps<"kbd"> {
+  /**
+   * Shortcut expressed as `"mod+shift+p"` — rendered as one cap per key, with
+   * `mod` resolved to ⌘ or Ctrl depending on the platform. Omit it and pass
+   * children instead to draw a single raw cap (`<Kbd>↵</Kbd>`).
+   */
+  keys?: string
+}
+
+/**
+ * A keyboard key, drawn as a cap. Either a raw one (`<Kbd>↵</Kbd>`) or a whole
+ * shortcut (`<Kbd keys="mod+k" />` → ⌘ K), which is the form the command palette
+ * uses for item shortcuts and footer hints.
+ *
+ * The accessible name is spelled out ("Commande + K"), because the glyphs alone
+ * announce as gibberish — or as nothing at all.
+ */
+function Kbd({ className, keys, children, ...props }: KbdProps) {
+  const isApple = useApplePlatform()
+
+  if (!keys) {
+    return (
+      <kbd data-slot="kbd" className={cn(capClass, className)} {...props}>
+        {children}
+      </kbd>
+    )
+  }
+
+  const parts = keys
+    .split("+")
+    .map((p) => p.trim())
+    .filter(Boolean)
+
+  return (
+    <kbd
+      data-slot="kbd"
+      aria-label={parts.map(keyLabel).join(" + ")}
+      className={cn("inline-flex items-center gap-1 border-0 bg-transparent p-0", className)}
+      {...props}
+    >
+      {parts.map((part, i) => (
+        <kbd key={`${part}-${i}`} aria-hidden className={capClass}>
+          {keyGlyph(part, isApple)}
+        </kbd>
+      ))}
+    </kbd>
+  )
+}
+
+export { Kbd }

package/src/components/workers/creator-avatar.tsx

@@ -0,0 +1,38 @@
+// Who spawned the worker, in 20 px.
+//
+// A plain <img>, deliberately: the design system is consumed by two Next apps
+// *and* by a Vite showcase, so it can't reach for `next/image`. Avatars come
+// from GitHub/Google CDNs already sized for this.
+
+import { cn } from "../../utils"
+import type { WorkerCreator } from "./types"
+
+export function CreatorAvatar({ creator, className }: { creator: WorkerCreator; className?: string }) {
+  if (creator.avatarUrl) {
+    return (
+      <img
+        src={creator.avatarUrl}
+        alt={creator.name}
+        className={cn("h-5 w-5 shrink-0 rounded-full object-cover ring-1 ring-border", className)}
+      />
+    )
+  }
+
+  const initials = creator.name
+    .split(" ")
+    .map((n) => n[0])
+    .join("")
+    .toUpperCase()
+    .slice(0, 2)
+
+  return (
+    <span
+      className={cn(
+        "flex h-5 w-5 shrink-0 items-center justify-center rounded-full bg-muted text-[9px] font-semibold text-muted-foreground ring-1 ring-border",
+        className
+      )}
+    >
+      {initials}
+    </span>
+  )
+}

package/src/components/workers/git-branch-chips.tsx

@@ -0,0 +1,128 @@
+// "repo · branch +3" chips — what a worker is actually working on.
+//
+// The dashboard's version shows the modified count; Lite's also shows ahead /
+// behind. This is the union: every counter is rendered only when the caller
+// supplies it, so neither app has to send a field it doesn't have.
+
+import { ArrowDownIcon, ArrowUpIcon, ExternalLinkIcon, GitBranchIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+
+export interface GitRepoStatus {
+  /** Absolute path of the checkout inside the worker — also the React key. */
+  path: string
+  branch?: string | null
+  /** Display name; defaults to the last segment of `path`. */
+  name?: string
+  /** Uncommitted files. */
+  modified?: number
+  /** Commits ahead of / behind the upstream branch. */
+  ahead?: number
+  behind?: number
+}
+
+export interface GitBranchChipsProps {
+  repos: GitRepoStatus[]
+  /**
+   * Chip → URL. A slot, not a link component: the design system knows nothing
+   * about code-server URLs, and returning `undefined` renders a plain span.
+   */
+  repoHref?: (repo: GitRepoStatus) => string | undefined
+  className?: string
+}
+
+export function repoName(repo: GitRepoStatus): string {
+  return repo.name ?? repo.path.split("/").filter(Boolean).pop() ?? repo.path
+}
+
+/** One chip per checked-out repository, wrapping onto as many lines as needed. */
+export function GitBranchChips({ repos, repoHref, className }: GitBranchChipsProps) {
+  if (!repos.length) return null
+
+  return (
+    // `@container` so the branch cap below reads *this row's* width: the same
+    // chips sit in a 600 px card on a desktop and in a 290 px one on a phone,
+    // and a viewport media query can't tell those apart.
+    <div data-slot="git-branch-chips" className={cn("@container flex flex-wrap gap-1.5", className)}>
+      {repos.map((repo) => {
+        const href = repoHref?.(repo)
+        const Tag = href ? "a" : "span"
+        return (
+          <Tag
+            key={repo.path}
+            {...(href ? { href, target: "_blank", rel: "noopener noreferrer" } : {})}
+            title={repo.path}
+            // `max-w-full` is what keeps a chip inside the card: without it a
+            // long "repo · branch" is a single unbreakable row that runs under
+            // the card's rounded edge and gets clipped.
+            className={cn(
+              "inline-flex min-w-0 max-w-full items-center gap-1 rounded-md border border-border bg-muted/40 px-2 py-0.5 font-mono text-[11px] text-muted-foreground",
+              href && "transition-colors hover:border-border/80 hover:bg-muted/70"
+            )}
+          >
+            <span className="shrink-0 font-medium text-foreground/70">{repoName(repo)}</span>
+            <span className="mx-0.5 shrink-0 text-muted-foreground/40">·</span>
+            <GitBranchIcon className="h-2.5 w-2.5 shrink-0" />
+            {/* The branch is the only part allowed to give up room — the repo
+                name and the counters are short and carry more meaning. */}
+            <span className="min-w-0 max-w-[6rem] truncate @min-[20rem]:max-w-[120px]">{repo.branch || "—"}</span>
+            <RepoCounters repo={repo} />
+            {href && <ExternalLinkIcon className="ml-0.5 h-2.5 w-2.5 shrink-0 opacity-40" />}
+          </Tag>
+        )
+      })}
+    </div>
+  )
+}
+
+/** Amber for local work not yet committed/pushed, muted for what's merely behind. */
+function RepoCounters({ repo }: { repo: GitRepoStatus }) {
+  return (
+    <>
+      {!!repo.modified && <span className="ml-0.5 shrink-0 text-amber-500 dark:text-amber-400">+{repo.modified}</span>}
+      {!!repo.ahead && (
+        <span className="ml-0.5 inline-flex shrink-0 items-center text-amber-500 dark:text-amber-400">
+          <ArrowUpIcon className="h-2.5 w-2.5" />
+          {repo.ahead}
+        </span>
+      )}
+      {!!repo.behind && (
+        <span className="ml-0.5 inline-flex shrink-0 items-center text-muted-foreground/70">
+          <ArrowDownIcon className="h-2.5 w-2.5" />
+          {repo.behind}
+        </span>
+      )}
+    </>
+  )
+}
+
+export interface GitStatusSummaryProps {
+  repos: GitRepoStatus[]
+  /** Heading above the list — e.g. "Open in VS Code" inside a tooltip. */
+  title?: string
+  className?: string
+}
+
+/**
+ * The same information as the chips, stacked one repo per line. Meant for the
+ * inside of a tooltip or a popover, where chips would wrap badly — the tooltip
+ * itself stays the app's business (the design system doesn't decide what opens
+ * it).
+ */
+export function GitStatusSummary({ repos, title, className }: GitStatusSummaryProps) {
+  if (!repos.length) return null
+
+  return (
+    <span data-slot="git-status-summary" className={cn("flex flex-col gap-1", className)}>
+      {title && <span className="text-[10px] uppercase tracking-wide opacity-60">{title}</span>}
+      {repos.map((repo) => (
+        <span key={repo.path} className="flex items-center gap-1.5">
+          <span className="font-medium">{repoName(repo)}</span>
+          <GitBranchIcon className="h-3 w-3 opacity-60" />
+          <span className="font-mono">{repo.branch || "—"}</span>
+          <RepoCounters repo={repo} />
+        </span>
+      ))}
+    </span>
+  )
+}

package/src/components/workers/index.ts

@@ -0,0 +1,35 @@
+// @spunto/design-system/workers — Spunto's *domain* components.
+//
+// Deliberately a sub-export rather than part of the main entry: the root of the
+// package stays "primitives with no domain" (a Button knows nothing about a
+// worker), and a third party consuming the design system never has to carry the
+// notion of a worker. New business components go here — see the README's
+// "Domain components" section for the rule.
+
+export { WorkerCard } from "./worker-card"
+export type { WorkerCardProps, LinkRender } from "./worker-card"
+
+export { WorkerStatusDot, WorkerStatusPill, resolveWorkerStatus, workerStatusConfig } from "./worker-status"
+export type { WorkerStatus, WorkerStatusConfig, WorkerStatusKey } from "./worker-status"
+
+export { SetupProgress, StepIndicator, phaseLabel, setupProgress, setupTotalMs } from "./setup-progress"
+export type { SetupProgressProps, StepState } from "./setup-progress"
+
+export { ResourceBars } from "./resource-bars"
+export type { ResourceBarsProps, WorkerStats } from "./resource-bars"
+
+export { GitBranchChips, GitStatusSummary, repoName } from "./git-branch-chips"
+export type { GitBranchChipsProps, GitRepoStatus, GitStatusSummaryProps } from "./git-branch-chips"
+
+export { TagChips } from "./tag-chips"
+export type { TagChipsProps } from "./tag-chips"
+export { tagColor } from "./tag-color"
+export type { TagPalette } from "./tag-color"
+
+export { CreatorAvatar } from "./creator-avatar"
+
+export type { WorkerCardWorker, WorkerCreator, WorkerSetupStatus } from "./types"
+
+// Re-exported here too so a consumer of the worker surface doesn't have to
+// import the root entry just to format the timestamps it feeds these components.
+export { cn, formatDuration, formatRelativeTime } from "../../utils"

package/src/components/workers/resource-bars.tsx

@@ -0,0 +1,104 @@
+// CPU + memory of a running container, as two thin bars.
+//
+// Written identically in the dashboard's card and its table row — the `compact`
+// flag is the only thing that ever differed between the two copies.
+
+import type { ReactNode } from "react"
+import { CpuIcon, MemoryStickIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+
+export interface WorkerStats {
+  cpuPercent: number
+  memUsageMb: number
+  memLimitMb?: number
+  memPercent?: number
+}
+
+export interface ResourceBarsProps {
+  stats: WorkerStats
+  /** Drops the framed panel — just the two bars, for a table cell or a tooltip. */
+  compact?: boolean
+  className?: string
+}
+
+/** Past this, the bar turns red: the container is about to be the problem. */
+const DANGER = 80
+
+export function ResourceBars({ stats, compact = false, className }: ResourceBarsProps) {
+  const cpu = stats.cpuPercent ?? 0
+  const mem = stats.memPercent ?? 0
+
+  return (
+    <div
+      data-slot="resource-bars"
+      className={cn(
+        // Side by side as soon as there's room for it, stacked below ~240 px —
+        // under that the label and its figure end up touching. Container query,
+        // not a media query: these bars live in a card, a table cell and a
+        // sidebar, and only their own width tells them what to do.
+        "@container grid grid-cols-1 gap-3 @min-[15rem]:grid-cols-2",
+        !compact && "rounded-lg border border-border/40 bg-muted/20 px-3 py-2.5",
+        className
+      )}
+    >
+      <Metric
+        icon={<CpuIcon className="h-3 w-3" />}
+        label="CPU"
+        value={`${cpu.toFixed(1)}%`}
+        valueClass={cpu > DANGER ? "text-orange-500 dark:text-orange-400" : "text-foreground/70"}
+        percent={cpu}
+        // Flame for CPU, Build amber for memory: two bars side by side need to be
+        // told apart at a glance, and both hues already mean "compute" here.
+        barClass={cpu > DANGER ? "bg-destructive" : "bg-primary"}
+      />
+      <Metric
+        icon={<MemoryStickIcon className="h-3 w-3" />}
+        label="Memory"
+        value={
+          <>
+            {(stats.memUsageMb ?? 0).toFixed(0)}
+            <span className="text-muted-foreground/50"> MB</span>
+          </>
+        }
+        valueClass="text-foreground/70"
+        percent={mem}
+        barClass={mem > DANGER ? "bg-destructive" : "bg-build"}
+      />
+    </div>
+  )
+}
+
+function Metric({
+  icon,
+  label,
+  value,
+  valueClass,
+  percent,
+  barClass,
+}: {
+  icon: ReactNode
+  label: string
+  value: ReactNode
+  valueClass: string
+  percent: number
+  barClass: string
+}) {
+  return (
+    <div>
+      <div className="mb-1.5 flex items-center justify-between gap-2">
+        <span className="flex min-w-0 items-center gap-1 truncate text-[11px] text-muted-foreground">
+          {icon}
+          {label}
+        </span>
+        <span className={cn("shrink-0 font-mono text-[11px] tabular-nums", valueClass)}>{value}</span>
+      </div>
+      <div className="h-1 overflow-hidden rounded-full bg-muted">
+        <div
+          className={cn("h-full rounded-full transition-all duration-500 motion-reduce:transition-none", barClass)}
+          style={{ width: `${Math.min(Math.max(percent, 0), 100)}%` }}
+        />
+      </div>
+    </div>
+  )
+}

package/src/components/workers/setup-progress.tsx

@@ -0,0 +1,130 @@
+// Worker setup, as a percentage and a sentence.
+//
+// The phase → percentage switch and the phase → label switch were written twice,
+// by hand, in two apps — and are the kind of thing that drifts silently (a phase
+// added on the agent side lands in one app's switch and not the other's). One
+// copy, here, plus the bar itself.
+//
+// Hookless, so it stays callable from a React Server Component.
+
+import { CheckIcon, CircleIcon, LoaderIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import type { WorkerSetupStatus } from "./types"
+
+/**
+ * Setup completion, 0-100.
+ *
+ * The numbers are deliberately uneven: they're calibrated on how long each phase
+ * actually takes, not on how many phases there are. Cloning gets a 30-point
+ * span sub-divided by repository, because it's the phase where a user watches
+ * the longest and the only one with real sub-progress to report.
+ */
+export function setupProgress(status: WorkerSetupStatus | null | undefined): number {
+  if (!status) return 5
+  switch (status.phase) {
+    case "initializing": return 10
+    case "credentials": return 25
+    case "dotfiles": return 35
+    case "cloning": {
+      const repos = status.repos ?? []
+      const done = repos.filter((r) => r.state === "done").length
+      const total = repos.length || 1
+      return 40 + Math.round((done / total) * 30)
+    }
+    case "lifecycle": {
+      if (status.postCreate === "running") return 75
+      if (status.postCreate === "done" && status.postStart === "running") return 88
+      return 80
+    }
+    case "ready": return 100
+    case "error": return 100
+    default: return 5
+  }
+}
+
+/** Human phase label — the line printed above the bar. */
+export function phaseLabel(status: WorkerSetupStatus | null | undefined): string {
+  if (!status) return "Starting up…"
+  switch (status.phase) {
+    case "initializing": return "Starting up…"
+    case "credentials": return "Configuring credentials…"
+    case "dotfiles": return "Installing dotfiles…"
+    case "cloning": return "Cloning repositories…"
+    case "lifecycle":
+      if (status.postCreate === "running") return "Running post-create command…"
+      if (status.postStart === "running") return "Running post-start command…"
+      return "Running setup commands…"
+    case "ready": return "Ready"
+    case "error": return "Setup failed"
+    default: return "Setting up…"
+  }
+}
+
+/**
+ * Total startup duration (ms) from the container-side phase timings, or null
+ * when we can't bracket it — old or crashed workers have no `ready` stamp, and
+ * an invented duration would be worse than no duration.
+ */
+export function setupTotalMs(status: WorkerSetupStatus | null | undefined): number | null {
+  const t = status?.timings
+  if (!t || t.initializing == null || t.ready == null) return null
+  const d = t.ready - t.initializing
+  return d > 0 ? d : null
+}
+
+export interface SetupProgressProps {
+  status?: WorkerSetupStatus | null
+  /** Hides the phase line + percentage, keeping only the bar (table rows). */
+  barOnly?: boolean
+  className?: string
+}
+
+/** Phase label + percentage + the bar itself. Red as soon as the setup failed. */
+export function SetupProgress({ status, barOnly = false, className }: SetupProgressProps) {
+  const pct = setupProgress(status)
+  const failed = status?.phase === "error"
+
+  return (
+    <div className={cn("w-full", className)}>
+      {!barOnly && (
+        <div className="mb-1.5 flex items-center justify-between gap-2">
+          <span
+            className={cn(
+              "min-w-0 truncate font-mono text-[11px]",
+              failed ? "text-destructive" : "text-yellow-500 dark:text-yellow-400"
+            )}
+          >
+            {phaseLabel(status)}
+          </span>
+          <span className="shrink-0 font-mono text-[11px] tabular-nums text-muted-foreground">{pct}%</span>
+        </div>
+      )}
+      <div className="h-1 overflow-hidden rounded-full bg-muted">
+        <div
+          className={cn(
+            "h-full rounded-full transition-all duration-700 motion-reduce:transition-none",
+            failed ? "bg-destructive" : "bg-yellow-400"
+          )}
+          style={{ width: `${pct}%` }}
+        />
+      </div>
+    </div>
+  )
+}
+
+export type StepState = "pending" | "running" | "done" | "error"
+
+/**
+ * The per-step bullet of a detailed setup view (one repository being cloned, a
+ * lifecycle command running). Same four states, same four colours, everywhere.
+ */
+export function StepIndicator({ state, className }: { state: StepState; className?: string }) {
+  const common = cn("h-3 w-3 shrink-0", className)
+
+  if (state === "running")
+    return <LoaderIcon className={cn(common, "animate-spin text-yellow-400 motion-reduce:animate-none")} />
+  if (state === "done") return <CheckIcon className={cn(common, "text-green-500")} />
+  if (state === "error") return <CircleIcon className={cn(common, "fill-destructive text-destructive")} />
+  return <CircleIcon className={cn(common, "text-muted-foreground/30")} />
+}