@spunto/design-system 0.10.0 → 0.11.1

package/src/components/devcontainer/feature-card.tsx

@@ -0,0 +1,157 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { FileCode2Icon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { CatalogCard, CatalogChip, CatalogMark, type CatalogTone } from "./catalog-card"
+import { PublisherBadge } from "./publisher-badge"
+import { derivePublisher, parseRegistryRef } from "./registry"
+import { RegistryRef } from "./registry-ref"
+import { resolveStackMark } from "./stack-mark"
+import type { DevcontainerFeatureEntry } from "./types"
+
+/**
+ * The options the feature will actually be installed with: the catalog's
+ * declared defaults, overridden by the platform's forced ones, overridden by
+ * whatever the user picked. Exported because a picker needs the same merge to
+ * decide what to send.
+ */
+export function resolveFeatureOptions(
+  feature: DevcontainerFeatureEntry,
+  selected?: Record<string, string> | null
+): Record<string, string> {
+  const merged: Record<string, string> = {}
+  for (const option of feature.options ?? []) {
+    if (option?.name && option.default != null) merged[option.name] = option.default
+  }
+  Object.assign(merged, feature.defaultOptions ?? {}, selected ?? {})
+  return merged
+}
+
+export interface FeatureCardProps {
+  feature: DevcontainerFeatureEntry
+  selected?: boolean
+  onSelect?: () => void
+  disabled?: boolean
+  compact?: boolean
+  /** An OCI ref the user pasted: dashed border, no invented author. */
+  custom?: boolean
+  /** Options actually in effect — merged over the catalog defaults. */
+  options?: Record<string, string> | null
+  /**
+   * Replaces the derived option chips entirely. That's the seam for an editable
+   * version=lts / moby=false row: the chips are drawn here, the state and the
+   * persistence stay in the app.
+   */
+  optionsSlot?: ReactNode
+  action?: ReactNode
+  copyable?: boolean
+  onCopyRef?: (value: string) => void
+  tone?: CatalogTone
+  className?: string
+}
+
+/**
+ * A devcontainer feature, as a card: the author behind its `ghcr.io/<owner>/…`
+ * ref (avatar included), the label, what it installs, the options it will be
+ * installed with, and the OCI reference itself.
+ *
+ * The author isn't stored anywhere — it *is* the ref. `ghcr.io/coderhammer/…`
+ * is `coderhammer` on GitHub and `github.com/coderhammer.png` is their avatar,
+ * which means the whole catalog gets faces without a single API change. A
+ * feature installed from a local script has no registry and says so.
+ */
+export function FeatureCard({
+  feature,
+  selected = false,
+  onSelect,
+  disabled = false,
+  compact = false,
+  custom = false,
+  options,
+  optionsSlot,
+  action,
+  copyable = false,
+  onCopyRef,
+  tone = "build",
+  className,
+}: FeatureCardProps) {
+  const ref = feature.ociRef
+  const parsed = parseRegistryRef(ref)
+  const title = feature.label || parsed.name || feature.id || ref || "Feature"
+  const mark = custom ? undefined : resolveStackMark(feature.mark, feature.id, parsed.name)
+  const publisher = custom ? feature.publisher : (feature.publisher ?? derivePublisher(ref))
+
+  const effective = optionsSlot ? {} : resolveFeatureOptions(feature, options)
+  const chips = Object.entries(effective)
+
+  return (
+    <CatalogCard
+      className={className}
+      compact={compact}
+      custom={custom}
+      selected={selected}
+      onSelect={onSelect}
+      disabled={disabled}
+      action={action}
+      tone={tone}
+      watermark={mark}
+      selectLabel={typeof title === "string" ? title : undefined}
+      mark={
+        <CatalogMark
+          iconUrl={feature.iconUrl}
+          mark={mark}
+          publisher={publisher}
+          label={title}
+          tone={tone}
+          compact={compact}
+        />
+      }
+      title={title}
+      meta={
+        !compact ? (
+          publisher ? (
+            <PublisherBadge publisher={publisher} />
+          ) : feature.localScript ? (
+            // No registry at all: worth saying, since "no author" here means
+            // "shipped by Spunto", not "unknown".
+            <span className="inline-flex items-center gap-1.5 text-[11px] text-muted-foreground">
+              <FileCode2Icon className="h-3 w-3 shrink-0" />
+              Local install script
+            </span>
+          ) : undefined
+        ) : undefined
+      }
+      description={feature.description}
+    >
+      {!compact && (optionsSlot ?? (chips.length > 0 && (
+        <div className="flex flex-wrap items-center gap-1 pt-0.5">
+          {chips.map(([name, value]) => (
+            <CatalogChip key={name} title={optionDescription(feature, name)}>
+              <span className="text-muted-foreground/60">{name}=</span>
+              <span className="text-foreground/80">{value}</span>
+            </CatalogChip>
+          ))}
+        </div>
+      )))}
+
+      {ref ? (
+        <RegistryRef
+          value={ref}
+          copyable={copyable && !compact}
+          onCopy={onCopyRef}
+          className={cn(compact ? "mt-0.5" : "mt-1.5")}
+        />
+      ) : feature.localScript ? (
+        <span className={cn("block truncate font-mono text-[10px] text-muted-foreground/50", compact ? "mt-0.5" : "mt-1.5")}>
+          {feature.localScript}
+        </span>
+      ) : null}
+    </CatalogCard>
+  )
+}
+
+function optionDescription(feature: DevcontainerFeatureEntry, name: string): string | undefined {
+  return feature.options?.find((option) => option?.name === name)?.description
+}

package/src/components/devcontainer/feature-tile.tsx

@@ -0,0 +1,63 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { PlusIcon } from "lucide-react"
+
+import { CatalogTile, type CatalogTileProps } from "./catalog-tile"
+import { PublisherAvatar } from "./publisher-badge"
+import { derivePublisher, parseRegistryRef } from "./registry"
+import { StackMark, resolveStackMark } from "./stack-mark"
+import type { DevcontainerFeatureEntry } from "./types"
+
+export interface FeatureTileProps extends Omit<CatalogTileProps, "mark" | "label" | "meta" | "title"> {
+  feature: DevcontainerFeatureEntry
+  icon?: ReactNode
+}
+
+/**
+ * A devcontainer feature, small: a mark, its name. Same object as `ImageTile`,
+ * same shell — the catalogs are picked the same way, so they look the same.
+ *
+ * The one difference is the fallback. An image without a recognised runtime is
+ * just a box; a feature without one still has an **author** — the GitHub org
+ * behind its `ghcr.io` ref — and that avatar says more than a generic glyph
+ * would. So the cascade is brand mark → author avatar, mirroring `CatalogMark`
+ * on the full cards.
+ */
+export function FeatureTile({
+  feature,
+  icon,
+  custom = false,
+  variant = "chip",
+  tone = "build",
+  ...rest
+}: FeatureTileProps) {
+  const parsed = parseRegistryRef(feature.ociRef)
+  const mark = custom ? undefined : resolveStackMark(feature.mark, feature.id, parsed.name)
+  const publisher = custom ? feature.publisher : (feature.publisher ?? derivePublisher(feature.ociRef))
+  const label = feature.label || parsed.name || feature.id || "Feature"
+  const glyph = variant === "chip" ? "h-4 w-4" : "h-7 w-7"
+
+  return (
+    <CatalogTile
+      {...rest}
+      custom={custom}
+      variant={variant}
+      tone={tone}
+      label={label}
+      title={feature.ociRef ?? feature.localScript ?? label}
+      mark={
+        icon ??
+        (custom ? (
+          <PlusIcon className={variant === "chip" ? "h-4 w-4" : "h-6 w-6"} />
+        ) : mark ? (
+          <StackMark name={mark} className={glyph} />
+        ) : publisher?.avatarUrl ? (
+          <PublisherAvatar publisher={publisher} fallbackLabel={label} className={glyph} />
+        ) : (
+          <StackMark className={glyph} />
+        ))
+      }
+    />
+  )
+}

package/src/components/devcontainer/image-card.tsx

@@ -0,0 +1,107 @@
+"use client"
+
+import type { ReactNode } from "react"
+
+import { cn } from "../../utils"
+import { CatalogCard, CatalogMark, type CatalogTone } from "./catalog-card"
+import { PublisherBadge } from "./publisher-badge"
+import { derivePublisher, parseRegistryRef } from "./registry"
+import { RegistryRef } from "./registry-ref"
+import { resolveStackMark } from "./stack-mark"
+import type { DevcontainerImageEntry } from "./types"
+
+export interface ImageCardProps {
+  image: DevcontainerImageEntry
+  selected?: boolean
+  /** Absent → read-only card (no overlay, no check). */
+  onSelect?: () => void
+  disabled?: boolean
+  /** One-line rendering for a project sheet or a summary. */
+  compact?: boolean
+  /**
+   * A ref the user typed rather than a catalog entry. Dashed border, generic
+   * tile, and no invented publisher — an unknown registry stays unknown.
+   */
+  custom?: boolean
+  /** Trailing control (a remove ✕). */
+  action?: ReactNode
+  /** Copy button next to the reference. */
+  copyable?: boolean
+  onCopyRef?: (value: string) => void
+  tone?: CatalogTone
+  className?: string
+}
+
+/**
+ * A devcontainer base image, as a card: the runtime's mark, its label, who
+ * publishes it, the image reference, and what it ships.
+ *
+ * **Everything but the label is derived from the reference** —
+ * `mcr.microsoft.com/devcontainers/python:3.12` is the Dev Containers team's
+ * Python image — because the catalog carries no author today. `image.publisher`
+ * and `image.mark` are the overrides for the day the API knows better; nothing
+ * else has to change here when it does.
+ */
+export function ImageCard({
+  image,
+  selected = false,
+  onSelect,
+  disabled = false,
+  compact = false,
+  custom = false,
+  action,
+  copyable = false,
+  onCopyRef,
+  tone = "ship",
+  className,
+}: ImageCardProps) {
+  const ref = image.image
+  const parsed = parseRegistryRef(ref)
+  const title = image.label || parsed.name || ref || "Image"
+  const mark = custom ? undefined : resolveStackMark(image.mark, image.id, parsed.name)
+  const publisher = custom ? image.publisher : (image.publisher ?? derivePublisher(ref))
+
+  return (
+    <CatalogCard
+      className={className}
+      compact={compact}
+      custom={custom}
+      selected={selected}
+      onSelect={onSelect}
+      disabled={disabled}
+      action={action}
+      tone={tone}
+      watermark={mark}
+      selectLabel={typeof title === "string" ? title : undefined}
+      mark={
+        <CatalogMark
+          iconUrl={image.iconUrl}
+          mark={mark}
+          publisher={publisher}
+          label={title}
+          tone={tone}
+          compact={compact}
+        />
+      }
+      title={title}
+      titleMeta={
+        parsed.tag && !compact ? (
+          <span className="shrink-0 rounded border border-border bg-muted px-1.5 py-0.5 font-mono text-[10px] leading-none text-muted-foreground">
+            {parsed.tag}
+          </span>
+        ) : undefined
+      }
+      meta={!compact && publisher ? <PublisherBadge publisher={publisher} /> : undefined}
+      description={image.description}
+    >
+      {ref && (
+        <RegistryRef
+          value={ref}
+          copyable={copyable && !compact}
+          onCopy={onCopyRef}
+          className={cn(compact ? "mt-0.5" : "mt-1.5")}
+        />
+      )}
+    </CatalogCard>
+  )
+}

package/src/components/devcontainer/image-tile.tsx

@@ -0,0 +1,56 @@
+"use client"
+
+import type { ReactNode } from "react"
+import { PlusIcon } from "lucide-react"
+
+import { CatalogTile, type CatalogTileProps } from "./catalog-tile"
+import { parseRegistryRef } from "./registry"
+import { StackMark, resolveStackMark } from "./stack-mark"
+import type { DevcontainerImageEntry } from "./types"
+
+export interface ImageTileProps extends Omit<CatalogTileProps, "mark" | "label" | "meta" | "title"> {
+  image: DevcontainerImageEntry
+  /** Replaces the derived mark — for the "custom image" entry, mostly. */
+  icon?: ReactNode
+}
+
+/**
+ * A base image, small: the runtime's mark, its name, its tag. That's it.
+ *
+ * The full `ImageCard` is the right object when the catalog is six entries and
+ * the publisher, the reference and the description each deserve a line. Past a
+ * dozen it's a wall of near-identical blocks all repeating the same
+ * `mcr.microsoft.com/devcontainers/` prefix — and picking a runtime is a *logo*
+ * task, not a reading one.
+ *
+ * So the default is `chip`: tag-sized, flowing and wrapping like tags rather
+ * than sitting in a rigid grid, which lets thirty images fit in the space six
+ * cards used to. What the chip drops comes back in the detail card
+ * `ImagePicker` shows for whichever one is selected.
+ */
+export function ImageTile({ image, icon, custom = false, variant = "chip", tone = "ship", ...rest }: ImageTileProps) {
+  const parsed = parseRegistryRef(image.image)
+  const mark = custom ? undefined : resolveStackMark(image.mark, image.id, parsed.name)
+  const label = image.label || parsed.name || image.image || "Image"
+  const glyph = variant === "chip" ? "h-4 w-4" : "h-7 w-7"
+
+  return (
+    <CatalogTile
+      {...rest}
+      custom={custom}
+      variant={variant}
+      tone={tone}
+      label={label}
+      title={image.image ?? label}
+      meta={custom ? undefined : parsed.tag}
+      mark={
+        icon ??
+        (custom ? (
+          <PlusIcon className={variant === "chip" ? "h-4 w-4" : "h-6 w-6"} />
+        ) : (
+          <StackMark name={mark} className={glyph} />
+        ))
+      }
+    />
+  )
+}

package/src/components/devcontainer/index.ts

@@ -0,0 +1,68 @@
+// @spunto/design-system/devcontainer — the three catalogs you compose an
+// environment from: base images, devcontainer features, VS Code extensions.
+//
+// A second *domain* sub-export, next to `/workers`: the root entry stays
+// "primitives with no domain" (a Button knows nothing about an OCI reference).
+// These cards are the screens where a user builds their environment, they exist
+// identically in the dashboard and in Spunto Lite, and they were hand-drawn as
+// raw `<button>`s in both — which is exactly the duplication this package is for.
+//
+// Presentational only: no fetch, no useQuery, no next/link. What talks to an API
+// is a callback (`onSelect`) or a slot (`action`, `optionsSlot`); what draws is
+// in here. The author and the logo are *derived* from the registry reference by
+// pure functions (`derivePublisher`, `resolveStackMark`) — see registry.ts.
+
+export { ImageCard } from "./image-card"
+export type { ImageCardProps } from "./image-card"
+
+export { ImageTile } from "./image-tile"
+export type { ImageTileProps } from "./image-tile"
+
+export { FeatureTile } from "./feature-tile"
+export type { FeatureTileProps } from "./feature-tile"
+
+export { CatalogTile } from "./catalog-tile"
+export type { CatalogTileProps } from "./catalog-tile"
+
+export { FeatureCard, resolveFeatureOptions } from "./feature-card"
+export type { FeatureCardProps } from "./feature-card"
+
+export { ExtensionCard, ExtensionCardSkeleton } from "./extension-card"
+export type { ExtensionCardProps } from "./extension-card"
+
+// The bricks, on their own — a picker's custom-ref row or a summary line needs
+// the shell without any of the three cards.
+export { CatalogCard, CatalogChip, CatalogMark } from "./catalog-card"
+export type { CatalogCardProps, CatalogMarkProps, CatalogTone } from "./catalog-card"
+
+export { PublisherAvatar, PublisherBadge, monogram } from "./publisher-badge"
+export type { PublisherAvatarProps, PublisherBadgeProps } from "./publisher-badge"
+
+export { RegistryRef } from "./registry-ref"
+export type { RegistryRefProps } from "./registry-ref"
+
+export { StackMark, resolveStackMark, STACK_MARK_PATHS } from "./stack-mark"
+export type { StackMarkName, StackMarkProps } from "./stack-mark"
+
+export {
+  derivePublisher,
+  extensionId,
+  formatCount,
+  githubAvatarUrl,
+  githubOwner,
+  parseExtensionId,
+  parseRegistryRef,
+} from "./registry"
+export type { ParsedRegistryRef } from "./registry"
+
+export type {
+  CatalogPublisher,
+  DevcontainerFeatureEntry,
+  DevcontainerFeatureOption,
+  DevcontainerImageEntry,
+  VscodeExtensionEntry,
+} from "./types"
+
+// Re-exported here too, so a consumer of this surface doesn't have to reach for
+// the root entry just to merge a class name.
+export { cn } from "../../utils"

package/src/components/devcontainer/publisher-badge.tsx

@@ -0,0 +1,91 @@
+"use client"
+
+import { useState } from "react"
+import { BadgeCheckIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import type { CatalogPublisher } from "./types"
+
+/** Initials for a monogram — "Dev Containers" → "DC", "dbaeumer" → "DB". */
+export function monogram(label?: string | null): string {
+  const value = (label ?? "").trim()
+  if (!value) return "?"
+  const words = value.split(/[\s._/-]+/).filter(Boolean)
+  if (words.length > 1) return (words[0][0] + words[1][0]).toUpperCase()
+  return value.slice(0, 2).toUpperCase()
+}
+
+export interface PublisherAvatarProps {
+  publisher?: CatalogPublisher
+  /** Label the monogram falls back to when the publisher has no name. */
+  fallbackLabel?: string
+  className?: string
+}
+
+/**
+ * The publisher's avatar — a plain `<img>`, deliberately: the package is
+ * consumed by two Next apps *and* a Vite showcase, so it can't reach for
+ * `next/image`. A dead URL (GitHub org renamed, extension icon 404) falls back
+ * to the monogram instead of leaving a broken-image glyph in the grid.
+ */
+export function PublisherAvatar({ publisher, fallbackLabel, className }: PublisherAvatarProps) {
+  const [broken, setBroken] = useState(false)
+  const label = publisher?.name || publisher?.login || fallbackLabel || ""
+  const url = publisher?.avatarUrl
+
+  if (url && !broken) {
+    return (
+      <img
+        src={url}
+        alt=""
+        loading="lazy"
+        onError={() => setBroken(true)}
+        className={cn("h-4 w-4 shrink-0 rounded-full object-cover ring-1 ring-border", className)}
+      />
+    )
+  }
+
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        "flex h-4 w-4 shrink-0 items-center justify-center rounded-full bg-muted text-[8px] font-semibold text-muted-foreground ring-1 ring-border",
+        className
+      )}
+    >
+      {monogram(label)}
+    </span>
+  )
+}
+
+export interface PublisherBadgeProps {
+  publisher?: CatalogPublisher
+  /** Drawn when the publisher itself has no name (a hand-typed ref). */
+  fallbackLabel?: string
+  /** `false` → the name alone, for rows already carrying a logo of their own. */
+  showAvatar?: boolean
+  className?: string
+}
+
+/**
+ * Who published this — avatar, name, and a flame check when the registry vouches
+ * for the namespace. Nothing derivable → renders nothing at all rather than an
+ * "Unknown publisher" line that says less than the empty space it takes.
+ */
+export function PublisherBadge({ publisher, fallbackLabel, showAvatar = true, className }: PublisherBadgeProps) {
+  const name = publisher?.name || publisher?.login || fallbackLabel
+  if (!name) return null
+
+  return (
+    <span className={cn("inline-flex min-w-0 items-center gap-1.5 text-[11px] text-muted-foreground", className)}>
+      {showAvatar && <PublisherAvatar publisher={publisher} fallbackLabel={fallbackLabel} />}
+      <span className="truncate">{name}</span>
+      {publisher?.verified && (
+        <BadgeCheckIcon
+          className="h-3 w-3 shrink-0 text-primary"
+          aria-label="Verified publisher"
+        />
+      )}
+    </span>
+  )
+}

package/src/components/devcontainer/registry-ref.tsx

@@ -0,0 +1,89 @@
+"use client"
+
+import { useEffect, useState } from "react"
+import { CheckIcon, CopyIcon } from "lucide-react"
+
+import { cn } from "../../utils"
+import { parseRegistryRef } from "./registry"
+
+export interface RegistryRefProps {
+  /** The full reference — `mcr.microsoft.com/devcontainers/python:3.12`. */
+  value?: string | null
+  /**
+   * Adds a copy button. The ref is the one thing on these cards you actually
+   * want in your clipboard (to paste into a devcontainer.json), and it was
+   * already printed in mono — this just makes it useful.
+   */
+  copyable?: boolean
+  /** Called instead of `navigator.clipboard` when the app wants to own the copy. */
+  onCopy?: (value: string) => void
+  className?: string
+}
+
+/**
+ * A registry reference, mono, with its host dimmed so the eye lands on the
+ * name+tag — the part that differs between two entries of the same catalog.
+ * Always carries the full ref as a `title`, because it truncates.
+ */
+export function RegistryRef({ value, copyable = false, onCopy, className }: RegistryRefProps) {
+  const [copied, setCopied] = useState(false)
+
+  useEffect(() => {
+    if (!copied) return
+    const id = setTimeout(() => setCopied(false), 1400)
+    return () => clearTimeout(id)
+  }, [copied])
+
+  const ref = value?.trim()
+  if (!ref) return null
+
+  const parsed = parseRegistryRef(ref)
+  // Prefix = everything up to the name; it's the boilerplate part
+  // ("ghcr.io/devcontainers/features/") that's identical across a whole catalog.
+  const prefix = [parsed.registry, parsed.owner, ...parsed.path].filter(Boolean).join("/")
+  const tail = [parsed.name, parsed.tag && `:${parsed.tag}`].filter(Boolean).join("")
+
+  function copy(event: React.MouseEvent) {
+    event.stopPropagation()
+    event.preventDefault()
+    if (onCopy) {
+      onCopy(ref!)
+    } else {
+      void navigator?.clipboard?.writeText(ref!).catch(() => {})
+    }
+    setCopied(true)
+  }
+
+  return (
+    // `relative z-10 w-fit`: on a selectable card the selection overlay covers
+    // everything, so the ref has to be raised above it — otherwise neither its
+    // `title` tooltip nor the copy button below would ever be reachable.
+    <span
+      title={ref}
+      className={cn(
+        "relative z-10 inline-flex w-fit min-w-0 max-w-full items-center gap-1 font-mono text-[10px] leading-none",
+        className
+      )}
+    >
+      {/* The prefix truncates, the name+tag never does. Truncating the whole ref
+          as one string eats the only part that differs between two entries of
+          the same catalog ("mcr.microsoft.com/devcontai…" says nothing), and in
+          this grid the prefix is identical on every card anyway. */}
+      {prefix && <span className="min-w-0 truncate text-muted-foreground/50">{prefix}/</span>}
+      <span className="shrink-0 text-muted-foreground">{tail || ref}</span>
+      {copyable && (
+        // `relative z-10`: the card's selection hit-area is an overlay button
+        // stretched across the whole card, so anything clickable inside has to
+        // sit above it — otherwise copying would select the card instead.
+        <button
+          type="button"
+          onClick={copy}
+          aria-label={copied ? "Copied" : `Copy ${ref}`}
+          className="relative z-10 shrink-0 cursor-pointer rounded p-0.5 text-muted-foreground/40 transition-colors hover:bg-accent hover:text-foreground"
+        >
+          {copied ? <CheckIcon className="h-3 w-3 text-primary" /> : <CopyIcon className="h-3 w-3" />}
+        </button>
+      )}
+    </span>
+  )
+}