@spunto/design-system 0.11.1 → 0.13.0

package/src/components/projects/panel-meta.tsx

@@ -0,0 +1,40 @@
+// The panel's footer: a few label → value lines, no border, no title.
+//
+// The two apps put different things here (the dashboard "Nodes online", Lite
+// "Runtime: Docker · local"), so this is a plain list of items rather than a
+// fixed set of fields — only "Created" is filled in by `ProjectPanel` itself.
+
+import { cn } from "../../utils"
+import type { ProjectPanelMetaItem } from "./panel-types"
+
+const TONES = {
+  default: "text-muted-foreground",
+  ok: "font-medium text-green-600 dark:text-green-400",
+  muted: "text-muted-foreground/60",
+} as const
+
+export interface PanelMetaProps {
+  items: ProjectPanelMetaItem[]
+  className?: string
+}
+
+/** One line per metadata item: icon + label on the left, value on the right. */
+export function PanelMeta({ items, className }: PanelMetaProps) {
+  if (!items.length) return null
+
+  return (
+    <div data-slot="panel-meta" className={cn("space-y-1.5", className)}>
+      {items.map((item) => (
+        <div key={item.id} className="flex items-center justify-between gap-2 text-[11px]">
+          <span className="flex min-w-0 items-center gap-1.5 text-muted-foreground/60">
+            {item.icon}
+            <span className="truncate">{item.label}</span>
+          </span>
+          <span className={cn("min-w-0 truncate text-right", TONES[item.tone ?? "default"])}>
+            {item.value}
+          </span>
+        </div>
+      ))}
+    </div>
+  )
+}

package/src/components/projects/panel-section.tsx

@@ -0,0 +1,68 @@
+// The panel's structural shell: one band per topic, with its uppercase label.
+//
+// This is the motif that was copy-pasted ~12 times per app (`px-4 py-3` +
+// `border-b border-border/60` + a `text-[10px] uppercase` paragraph). Lite had
+// already extracted the label as a local `Eyebrow`; the dashboard rewrote it by
+// hand in every section. Both are this.
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+
+export interface EyebrowProps {
+  /** Small glyph before the label — 3×3 (`h-3 w-3`) to sit on the cap height. */
+  icon?: ReactNode
+  children: ReactNode
+  className?: string
+}
+
+/** The uppercase label above a section's content. */
+export function Eyebrow({ icon, children, className }: EyebrowProps) {
+  return (
+    <p
+      data-slot="eyebrow"
+      className={cn(
+        "text-[10px] font-semibold tracking-wider text-muted-foreground/60 uppercase",
+        icon && "flex items-center gap-1.5",
+        className
+      )}
+    >
+      {icon}
+      {children}
+    </p>
+  )
+}
+
+export interface PanelSectionProps {
+  /** Rendered as an `Eyebrow`. Absent → the section is just a bordered band. */
+  title?: ReactNode
+  icon?: ReactNode
+  /**
+   * Right-hand affordance on the title row — a "Manage" link, a "Pre-build"
+   * button. Anything that calls an API stays the caller's business.
+   */
+  action?: ReactNode
+  /** Last section of a panel → no bottom border (the card's edge closes it). */
+  last?: boolean
+  children?: ReactNode
+  className?: string
+}
+
+/**
+ * One band of the project panel. Keeps the header row and the content spaced
+ * consistently whether or not there is an action on the right, so a section
+ * with a "Manage" link lines up with one without.
+ */
+export function PanelSection({ title, icon, action, last = false, children, className }: PanelSectionProps) {
+  return (
+    <div data-slot="panel-section" className={cn("px-4 py-3", !last && "border-b border-border/60", className)}>
+      {(title || action) && (
+        <div className={cn("mb-2 flex min-w-0 items-center justify-between gap-2", !title && "justify-end")}>
+          {title && <Eyebrow icon={icon}>{title}</Eyebrow>}
+          {action}
+        </div>
+      )}
+      {children}
+    </div>
+  )
+}

package/src/components/projects/panel-types.ts

@@ -0,0 +1,101 @@
+// Structural, deliberately laxist shapes for what the project PANEL reads.
+//
+// Separate from `types.ts`, which holds `ProjectFormValue` & co: the form owns a
+// *complete* value it edits (every field present, never undefined), the panel
+// reads a *partial* snapshot it merely displays. Same domain, opposite
+// invariants — merging them would force one of the two to lie.
+//
+// Same rule as the worker types: the design system must NOT import the
+// OpenAPI-generated types of the Spunto dashboard, nor Spunto Lite's
+// `lib/types.ts` — the two model a project differently. A repository carries a
+// `project` slug on the dashboard and a full `cloneUrl` on Lite;
+// `deployPublicKey` is a `(project as any)` cast on the dashboard and a real
+// field on Lite; `currentVersion` is optional on one side and guaranteed on the
+// other. So the shapes below describe the *minimum* these components read,
+// everything optional but `name` / `image` / `createdAt`, and an unknown value
+// (an unheard-of `state`, a missing repo slug) degrades instead of crashing.
+
+import type { ReactNode } from "react"
+
+/** One repository cloned into a worker's `/workspace`. */
+export interface ProjectPanelRepository {
+  id: string
+  /** `owner/repo` slug — how the dashboard names a GitHub repository. */
+  project?: string | null
+  /** Full clone URL (SSH or HTTPS) — how Lite names a generic "git" repository. */
+  cloneUrl?: string | null
+  /** Folder under `/workspace` the repo is checked out into. */
+  workspacePath: string
+}
+
+/** The project snapshot a `ProjectPanel` draws. */
+export interface ProjectPanelProject {
+  name: string
+  description?: string | null
+  /** `created` | `creating` | `ready` | `updating` | `error`… Absent → no badge. */
+  state?: string | null
+  /** Base image reference — only its last segment is displayed. */
+  image: string
+  /** Current config version → the `vN` of the stats row. */
+  currentVersion?: number
+  /** ISO date → the "Created" line of the footer. */
+  createdAt: string
+  repositories?: ProjectPanelRepository[]
+  /** devcontainer features, by full id (`ghcr.io/devcontainers/features/node:1`). */
+  features?: { id: string }[]
+  vscodeExtensions?: string[]
+  forwardPorts?: (number | string)[]
+  postCreateCommand?: string | null
+  postStartCommand?: string | null
+  /** Public half of the project's SSH deploy key (RFC 0013). */
+  deployPublicKey?: string | null
+}
+
+/** A secret, by NAME only — a value never reaches the design system. */
+export interface ProjectSecretMeta {
+  id: string
+  name: string
+}
+
+/**
+ * One target of the pre-build cache: a BYOC node on the dashboard, the single
+ * local Docker daemon on Lite.
+ */
+export interface ProjectBuildTarget {
+  id: string
+  label: string
+  /** `building` | `ready` | `error`. Absent/unknown → "not built". */
+  state?: "building" | "ready" | "error" | string | null
+  /** Absent → the row is inert (Lite has no build log to open). */
+  onSelect?: () => void
+}
+
+/** An external account the project can be connected to (GitHub, GCP…). */
+export interface ProjectIntegration {
+  id: string
+  label: string
+  /** The provider's logo/glyph — a slot, the design system ships no brand icons. */
+  icon?: ReactNode
+  connected?: boolean
+  /** Target of the "Connect" affordance when not connected. */
+  connectHref?: string
+}
+
+/** One entry of the version history. */
+export interface ProjectVersionEntry {
+  id: string
+  version: number
+  createdAt: string
+  /** Image of *that* version — shown under the date, last segment only. */
+  image?: string
+}
+
+/** One line of the panel's footer: icon, label, value. */
+export interface ProjectPanelMetaItem {
+  id: string
+  label: string
+  value: ReactNode
+  icon?: ReactNode
+  /** `ok` greens the value (a positive count), `muted` dims it. */
+  tone?: "default" | "ok" | "muted"
+}

package/src/components/projects/project-panel.tsx

@@ -0,0 +1,330 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { CalendarIcon, KeyRoundIcon, SquarePenIcon, ZapIcon } from "lucide-react"
+
+import { cn, formatShortDate } from "../../utils"
+// The catalog surface already turns a registry reference into a logo and a
+// readable ref — the panel shows the same image, so it reuses them instead of
+// re-deriving its own.
+import { RegistryRef } from "../devcontainer/registry-ref"
+import { resolveStackMark, StackMark } from "../devcontainer/stack-mark"
+import { buttonVariants } from "../button-variants"
+import type { LinkRender } from "../workers/worker-card"
+import { BuildCacheList, PrebuildButton } from "./build-cache-list"
+import { ExtensionChips, FeatureChips, PortChips, SecretChips } from "./chip-list"
+import { DeployKeySection } from "./deploy-key-section"
+import { IntegrationsList } from "./integrations-list"
+import { LifecycleCommands } from "./lifecycle-commands"
+import { PanelMeta } from "./panel-meta"
+import { PanelSection } from "./panel-section"
+import { ProjectStatePill } from "./project-state"
+import { RepositoryList } from "./repository-list"
+import type {
+  ProjectBuildTarget,
+  ProjectIntegration,
+  ProjectPanelMetaItem,
+  ProjectPanelProject,
+  ProjectSecretMeta,
+  ProjectVersionEntry,
+} from "./panel-types"
+import { VersionHistory } from "./version-history"
+
+export interface ProjectPanelProps {
+  project: ProjectPanelProject
+
+  /** Worker counts of the stats row. Absent → the row shows only `vN`, or nothing. */
+  stats?: { running: number; total: number }
+
+  /** Target of the header's "Edit" button. Absent → no button. */
+  editHref?: string
+  editLabel?: string
+  /** Target of the "Manage" link of the Secrets section. */
+  secretsHref?: string
+  manageLabel?: string
+  /**
+   * Escape hatch for links. `link` receives `{ href, className, children }` and
+   * must return an anchor-ish node (`next/link`, a router link…); without it the
+   * panel falls back to a plain `<a>`. Same slot as `WorkerCard` — the package
+   * never imports `next/link`, it is also consumed by a Vite app.
+   */
+  render?: { link?: LinkRender }
+
+  /** Secret NAMES. `[]` renders the empty state, `undefined` hides the section. */
+  secrets?: ProjectSecretMeta[]
+
+  /** Build cache targets: BYOC nodes on the dashboard, one local daemon on Lite. */
+  buildTargets?: ProjectBuildTarget[]
+  onPrebuild?: () => void
+  prebuilding?: boolean
+
+  integrations?: ProjectIntegration[]
+
+  versions?: ProjectVersionEntry[]
+  /** Restoring is a mutation → the app's. The callback gets the whole entry. */
+  onRestoreVersion?: (version: ProjectVersionEntry) => void
+  restoringVersionId?: string | null
+  versionsDefaultOpen?: boolean
+  /** Inline error of the version history (a failed restore). */
+  error?: string | null
+
+  /** Registration guidance under the deploy key — differs per app, hence a slot. */
+  deployKeyHelp?: ReactNode
+
+  /** Extra footer lines. "Created" is always first, from `project.createdAt`. */
+  meta?: ProjectPanelMetaItem[]
+
+  /** Sections an app has and the others don't, appended before the footer. */
+  children?: ReactNode
+  className?: string
+}
+
+/**
+ * The left-hand panel of a project page: identity, image, repositories, deploy
+ * key, features, extensions, build cache, ports, lifecycle, secrets,
+ * integrations, version history, footer.
+ *
+ * **Purely presentational.** Hand it a project plus slots and it draws — no
+ * query, no mutation, no router. Everything that would call an API is a
+ * callback (`onPrebuild`, `onRestoreVersion`) or a link the app renders
+ * (`editHref` + `render.link`). That is what makes the same panel renderable by
+ * the dashboard, by Spunto Lite and by the showcase with hand-written fixtures.
+ *
+ * The layout is a fixed sequence of optional bands, each disappearing when its
+ * data is absent: a project with no repository, no feature and no secret
+ * collapses to a header plus an image without a single caller-side conditional.
+ *
+ * The card is the panel's business; **its placement is not** — the
+ * `<aside className="w-full lg:w-72 lg:sticky …">` that pins it in the page grid
+ * stays in the app.
+ */
+export function ProjectPanel({
+  project,
+  stats,
+  editHref,
+  editLabel = "Edit",
+  secretsHref,
+  manageLabel = "Manage",
+  render,
+  secrets,
+  buildTargets,
+  onPrebuild,
+  prebuilding = false,
+  integrations,
+  versions,
+  onRestoreVersion,
+  restoringVersionId,
+  versionsDefaultOpen = false,
+  error,
+  deployKeyHelp,
+  meta,
+  children,
+  className,
+}: ProjectPanelProps) {
+  const Link: LinkRender =
+    render?.link ?? (({ href, className: cls, children: kids }) => <a href={href} className={cls}>{kids}</a>)
+
+  const imageMark = resolveStackMark(project.image)
+  const repositories = project.repositories ?? []
+  const features = project.features ?? []
+  const extensions = project.vscodeExtensions ?? []
+  const ports = project.forwardPorts ?? []
+  const showBuildCache = !!buildTargets?.length || (!!buildTargets && !!onPrebuild)
+  const showStats = !!stats || project.currentVersion != null
+
+  const metaItems: ProjectPanelMetaItem[] = [
+    {
+      id: "created",
+      label: "Created",
+      icon: <CalendarIcon className="h-3 w-3 shrink-0" />,
+      value: formatShortDate(project.createdAt),
+    },
+    ...(meta ?? []),
+  ]
+
+  return (
+    <div
+      data-slot="project-panel"
+      // `@container`: the few responsive rules below are container queries, never
+      // viewport ones. This panel is a 288 px sidebar column on a desktop and a
+      // full-width block on a phone — and the desktop case is the *narrow* one.
+      className={cn(
+        "@container overflow-hidden rounded-xl border border-border bg-card shadow-sm",
+        className
+      )}
+    >
+      {/* ── Header : identité, état, Edit, ligne de stats ── */}
+      <div className="border-b border-border/60 px-4 pt-4 pb-3">
+        <div className="flex items-start justify-between gap-2">
+          <div className="min-w-0">
+            {/* A project name is one unbreakable token more often than not. */}
+            <p className="truncate text-sm leading-tight font-semibold" title={project.name}>
+              {project.name}
+            </p>
+            {project.description && (
+              <p className="mt-1 text-xs leading-relaxed text-muted-foreground">{project.description}</p>
+            )}
+          </div>
+          <div className="flex shrink-0 items-center gap-1">
+            {project.state && <ProjectStatePill state={project.state} />}
+            {editHref && (
+              <Link
+                href={editHref}
+                className={cn(
+                  buttonVariants({ variant: "ghost", size: "sm" }),
+                  "h-7 gap-1.5 px-2 text-xs text-muted-foreground hover:text-foreground"
+                )}
+              >
+                <SquarePenIcon className="h-3 w-3" />
+                {/* Below ~256 px the state pill plus a labelled button push the
+                    name down to nothing — the pencil alone still reads. */}
+                <span className="@max-[16rem]:hidden">{editLabel}</span>
+              </Link>
+            )}
+          </div>
+        </div>
+
+        {showStats && (
+          <div className="mt-3 flex flex-wrap items-center gap-x-3 gap-y-1">
+            {stats && (
+              <>
+                <span className="flex items-center gap-1.5">
+                  <span className={cn("h-2 w-2 rounded-full", stats.running > 0 ? "bg-green-500" : "bg-muted-foreground/40")} />
+                  <span className="text-xs text-muted-foreground">
+                    <span className="font-medium text-foreground">{stats.running}</span> running
+                  </span>
+                </span>
+                <Separator />
+                <span className="text-xs text-muted-foreground">
+                  <span className="font-medium text-foreground">{stats.total}</span> total
+                </span>
+              </>
+            )}
+            {project.currentVersion != null && (
+              <>
+                {stats && <Separator />}
+                <span className="font-mono text-xs text-muted-foreground">v{project.currentVersion}</span>
+              </>
+            )}
+          </div>
+        )}
+      </div>
+
+      <PanelSection title="Image">
+        {/* The base image, drawn like the catalog draws it: the runtime's own
+            mark (derived from the ref, never fetched) and the reference with its
+            host dimmed — so the eye lands on `name:tag`, the part that actually
+            varies. Copyable, because pasting it into a devcontainer.json is the
+            one thing you want to do with it. */}
+        <div className="flex min-w-0 items-center gap-2 rounded-lg bg-muted/50 px-3 py-2">
+          <span className="flex h-4 w-4 shrink-0 items-center justify-center text-muted-foreground">
+            <StackMark name={imageMark} className="h-4 w-4" />
+          </span>
+          <RegistryRef value={project.image} copyable className="min-w-0 text-[11px]" />
+        </div>
+      </PanelSection>
+
+      {repositories.length > 0 && (
+        <PanelSection title="Repositories">
+          <RepositoryList repositories={repositories} />
+        </PanelSection>
+      )}
+
+      {project.deployPublicKey && (
+        <PanelSection title="Deploy key" icon={<KeyRoundIcon className="h-3 w-3" />}>
+          <DeployKeySection publicKey={project.deployPublicKey}>{deployKeyHelp}</DeployKeySection>
+        </PanelSection>
+      )}
+
+      {features.length > 0 && (
+        <PanelSection title="Features">
+          <FeatureChips features={features} />
+        </PanelSection>
+      )}
+
+      {extensions.length > 0 && (
+        <PanelSection title="Extensions">
+          <ExtensionChips extensions={extensions} />
+        </PanelSection>
+      )}
+
+      {showBuildCache && (
+        <PanelSection
+          title="Build cache"
+          icon={<ZapIcon className="h-3 w-3" />}
+          action={onPrebuild && <PrebuildButton onClick={onPrebuild} pending={prebuilding} />}
+        >
+          <BuildCacheList targets={buildTargets ?? []} />
+        </PanelSection>
+      )}
+
+      {ports.length > 0 && (
+        <PanelSection title="Forwarded ports">
+          <PortChips ports={ports} />
+        </PanelSection>
+      )}
+
+      {(project.postCreateCommand || project.postStartCommand) && (
+        <PanelSection title="Lifecycle">
+          <LifecycleCommands
+            postCreateCommand={project.postCreateCommand}
+            postStartCommand={project.postStartCommand}
+          />
+        </PanelSection>
+      )}
+
+      {secrets && (
+        <PanelSection
+          title="Secrets"
+          icon={<KeyRoundIcon className="h-3 w-3" />}
+          action={
+            secretsHref && (
+              <Link
+                href={secretsHref}
+                className="shrink-0 text-[10px] text-primary transition-colors hover:text-primary/80"
+              >
+                {manageLabel}
+              </Link>
+            )
+          }
+        >
+          <SecretChips secrets={secrets} />
+        </PanelSection>
+      )}
+
+      {!!integrations?.length && (
+        <PanelSection title="Integrations">
+          <IntegrationsList integrations={integrations} link={render?.link} />
+        </PanelSection>
+      )}
+
+      {!!versions?.length && (
+        <PanelSection>
+          <VersionHistory
+            versions={versions}
+            currentVersion={project.currentVersion}
+            onRestore={onRestoreVersion}
+            restoringVersionId={restoringVersionId}
+            error={error}
+            defaultOpen={versionsDefaultOpen}
+          />
+        </PanelSection>
+      )}
+
+      {children}
+
+      <PanelSection last>
+        <PanelMeta items={metaItems} />
+      </PanelSection>
+    </div>
+  )
+}
+
+/**
+ * The "·" between two stats. Hidden below ~272 px: the row is two lines deep by
+ * then, and a separator that ends up alone at the end of a line points at
+ * nothing (same reasoning as `WorkerCard`'s meta line).
+ */
+function Separator() {
+  return <span className="text-border @max-[17rem]:hidden">·</span>
+}

package/src/components/projects/project-state.tsx

@@ -0,0 +1,47 @@
+// The project's lifecycle state, as a pill.
+//
+// Replaces the `stateColors` map both apps kept inline, in raw Tailwind palette
+// classes with hand-written `dark:` variants. Same semantics as the worker
+// statuses (green = healthy, yellow = in flight, red = failure, neutral =
+// nothing happening), and errors go through the `destructive` token rather than
+// a raw red so they track the theme.
+//
+// No "use client": a pure table plus a hookless component.
+
+import { cn } from "../../utils"
+
+export type ProjectStateKey = "created" | "creating" | "ready" | "updating" | "error"
+
+const NEUTRAL = "bg-muted text-muted-foreground border-border"
+
+export const projectStateConfig: Record<ProjectStateKey, string> = {
+  created: NEUTRAL,
+  creating: "bg-yellow-500/10 text-yellow-700 border-yellow-500/20 dark:text-yellow-400",
+  ready: "bg-green-500/10 text-green-700 border-green-500/20 dark:text-green-400",
+  updating: "bg-primary/10 text-primary border-primary/20",
+  error: "bg-destructive/10 text-destructive border-destructive/20",
+}
+
+export interface ProjectStatePillProps {
+  /** Raw state string. Unknown values render neutral instead of throwing. */
+  state: string
+  label?: string
+  className?: string
+}
+
+/** The state chip next to the project name. */
+export function ProjectStatePill({ state, label, className }: ProjectStatePillProps) {
+  const tone = projectStateConfig[state as ProjectStateKey] ?? NEUTRAL
+  return (
+    <span
+      data-slot="project-state-pill"
+      className={cn(
+        "inline-flex h-5 shrink-0 items-center rounded-full border px-2 text-[10px] leading-none font-medium capitalize",
+        tone,
+        className
+      )}
+    >
+      {label ?? state}
+    </span>
+  )
+}