@spunto/design-system 0.10.0 → 0.11.0

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

@@ -0,0 +1,488 @@
+"use client"
+
+import { useState, type ComponentType, type ReactNode } from "react"
+import {
+  BlocksIcon,
+  BoxIcon,
+  GitBranchIcon,
+  KeyRoundIcon,
+  LayersIcon,
+  NetworkIcon,
+  PuzzleIcon,
+  SquarePenIcon,
+  TerminalIcon,
+} from "lucide-react"
+
+import { cn } from "../../utils"
+import { Input } from "../input"
+import { Switch } from "../switch"
+import { Textarea } from "../textarea"
+import { ExtensionPicker } from "./extension-picker"
+import { FeaturePicker, type FeaturePickerProps } from "./feature-picker"
+import { ImagePicker, type ImagePickerProps } from "./image-picker"
+import { AdvancedDisclosure, advancedSummary } from "./advanced-sections"
+import { BuildManifest, type ManifestRow } from "./build-manifest"
+import { Field, FormSection, type SectionAccent } from "./form-section"
+import { RepoList, type GithubConnection, type GithubRepoOption, type RepoFieldRender } from "./repo-list"
+import { SecretList } from "./secret-list"
+import {
+  CREATE_SECTIONS,
+  type ProjectFormSectionId,
+  type ProjectFormValue,
+  type ProjectSecretRef,
+} from "./types"
+import type { DevcontainerFeatureEntry, DevcontainerImageEntry, VscodeExtensionEntry } from "../devcontainer/types"
+
+/** Chrome of each section: number, icon, accent, wording. */
+const SECTION_META: Record<
+  ProjectFormSectionId,
+  { icon: ComponentType<{ className?: string }>; accent: SectionAccent; title: string; hint?: string }
+> = {
+  identity: { icon: SquarePenIcon, accent: "build", title: "Identity", hint: "Name your project and what it's for" },
+  image: { icon: BoxIcon, accent: "ship", title: "Base image", hint: "The devcontainer your workers run on" },
+  repositories: { icon: GitBranchIcon, accent: "run", title: "Repositories", hint: "Cloned into /workspace at startup" },
+  features: { icon: PuzzleIcon, accent: "flame", title: "Features", hint: "Devcontainer features baked into the image" },
+  extensions: { icon: BlocksIcon, accent: "build", title: "Extensions", hint: "VS Code extensions, installed via code-server" },
+  lifecycle: { icon: TerminalIcon, accent: "ship", title: "Lifecycle", hint: "Commands run on create & on every start" },
+  ports: { icon: NetworkIcon, accent: "run", title: "Ports", hint: "Automatically forwarded for every worker" },
+  prewarm: { icon: LayersIcon, accent: "build", title: "Prewarm images", hint: "Docker images pre-loaded into the worker's docker-in-docker on first start" },
+  docker: { icon: BoxIcon, accent: "build", title: "Docker-in-Docker", hint: "Run workers privileged with a Docker daemon inside" },
+  secrets: { icon: KeyRoundIcon, accent: "flame", title: "Secrets", hint: "Env vars injected into every workspace" },
+}
+
+/**
+ * Folded by default: everything past identity / base image / repositories.
+ * Those three decide what a worker *is*; the rest is tuning, and putting ten
+ * sections in front of someone creating their first project is how a form stops
+ * being filled in at all.
+ */
+const DEFAULT_ADVANCED: ProjectFormSectionId[] = [
+  "features",
+  "extensions",
+  "lifecycle",
+  "ports",
+  "prewarm",
+  "docker",
+  "secrets",
+]
+
+export interface ProjectFormProps {
+  value: ProjectFormValue
+  onChange: (value: ProjectFormValue) => void
+  /** Receives the current value. The app maps it to its own payload and calls its API. */
+  onSubmit?: (value: ProjectFormValue) => void
+
+  /** Which sections to show, in order. Defaults to the seven creation ones. */
+  sections?: ProjectFormSectionId[]
+  /**
+   * Sections folded behind "Advanced options". Defaults to everything past
+   * identity / base image / repositories — the three that actually decide what
+   * a worker is. Pass `[]` to show the whole form flat.
+   *
+   * Safe to fold *because* the disclosure names what it holds while closed and
+   * the form opens it on its own when any of these already has a value: editing
+   * a project never hides settings you set earlier behind a shut drawer.
+   */
+  advancedSections?: ProjectFormSectionId[]
+  advancedLabel?: string
+  advancedHint?: string
+  /** Forces the initial state. Omitted → open iff an advanced section has a value. */
+  defaultAdvancedOpen?: boolean
+
+  /** Catalogs, already fetched by the app — the form never calls an API. */
+  images?: DevcontainerImageEntry[]
+  features?: DevcontainerFeatureEntry[]
+  /**
+   * How the image catalog is laid out. Passed straight through, because the
+   * right answer depends on the page around the form: a screen that already
+   * spends 360 px on the manifest leaves the picker too narrow for the detail
+   * card to sit beside the chips, and `auto` will stack it. Force `side` if you
+   * want the panel there regardless.
+   */
+  imagePicker?: Pick<ImagePickerProps, "layout" | "detail">
+  /** Same passthrough for the feature catalog. */
+  featurePicker?: Pick<FeaturePickerProps, "layout" | "detail">
+
+  githubRepos?: GithubRepoOption[]
+  github?: GithubConnection
+  connectUrl?: string
+  /** App-level combobox for the repo field; without it, a plain input + datalist. */
+  renderRepoField?: RepoFieldRender
+  githubIcon?: ReactNode
+
+  /** Searches Open VSX (or any marketplace). Absent → extensions are typed by hand. */
+  onSearchExtensions?: (query: string) => Promise<VscodeExtensionEntry[]>
+
+  /** Secrets that already exist server-side (edit mode). */
+  savedSecrets?: ProjectSecretRef[]
+
+  /** Extra content appended inside a section — the deploy key card, a warning… */
+  extras?: Partial<Record<ProjectFormSectionId, ReactNode>>
+
+  /** `false` drops the recap panel entirely and gives the form the full width. */
+  manifest?: boolean
+  submitLabel?: ReactNode
+  submittingLabel?: ReactNode
+  submitting?: boolean
+  error?: string | null
+  manifestCaption?: ReactNode
+  manifestFooter?: ReactNode
+  manifestTitle?: string
+
+  className?: string
+}
+
+/**
+ * The whole "compose a dev environment" form: identity, base image, repos,
+ * features, extensions, lifecycle, ports, prewarm, docker-in-docker, secrets —
+ * plus the live build manifest that recaps it and carries the submit button.
+ *
+ * **Controlled, single value.** One `ProjectFormValue` in, one `onChange` out.
+ * The dashboard used to spread this across seven pieces of local state, three
+ * hidden inputs carrying JSON, and a `FormData` read at submit — which meant the
+ * value was only knowable *at* submit, so no validation, no draft, no preview.
+ * Here the value is always readable, and the hidden-input trick disappears.
+ *
+ * **Nothing in here fetches.** Catalogs come in as data, the extension search is
+ * a callback, the GitHub combobox is a slot, and `onSubmit` hands the value back
+ * for the app to send. Which sections are shown is a prop, so creation and
+ * editing are the same component with a different list — not two screens that
+ * drift apart.
+ */
+export function ProjectForm({
+  value,
+  onChange,
+  onSubmit,
+  sections = CREATE_SECTIONS,
+  advancedSections = DEFAULT_ADVANCED,
+  advancedLabel,
+  advancedHint,
+  defaultAdvancedOpen,
+  images = [],
+  features = [],
+  imagePicker,
+  featurePicker,
+  githubRepos,
+  github,
+  connectUrl,
+  renderRepoField,
+  githubIcon,
+  onSearchExtensions,
+  savedSecrets,
+  extras,
+  manifest = true,
+  submitLabel = "Save",
+  submittingLabel = "Saving…",
+  submitting = false,
+  error,
+  manifestCaption,
+  manifestFooter,
+  manifestTitle,
+  className,
+}: ProjectFormProps) {
+  const patch = (next: Partial<ProjectFormValue>) => onChange({ ...value, ...next })
+
+  const rows = manifestRows(value, sections)
+
+  const advanced = sections.filter((id) => advancedSections.includes(id))
+  const primary = sections.filter((id) => !advancedSections.includes(id))
+  const summary = advancedSummary(value, advanced)
+  // Start open when there's already something in there — the initial value is
+  // read once, on mount, so a later edit can't yank the fold open under the
+  // user's cursor.
+  const [advancedOpen, setAdvancedOpen] = useState(() => defaultAdvancedOpen ?? summary.length > 0)
+
+  return (
+    // The container is this wrapper, not the form: a container query styles a
+    // container's DESCENDANTS, never the element that declares it — put both on
+    // one node and the query silently never matches.
+    //
+    // And it's a container query rather than `lg:` because the form is a full
+    // page in the dashboard and a ~700 px panel in the showcase. Keyed on the
+    // viewport, it split into two columns in both, squeezing the catalog cards
+    // to 130 px in the narrow one. Now it reads its own width.
+    <div className={cn("@container/form", className)}>
+      <form
+        data-slot="project-form"
+        onSubmit={(e) => {
+          e.preventDefault()
+          onSubmit?.(value)
+        }}
+        className={cn(
+          manifest
+            ? "grid gap-6 @min-[60rem]/form:grid-cols-[1fr_minmax(320px,360px)] @min-[60rem]/form:items-start"
+            : "block"
+        )}
+      >
+        <div className="space-y-4">
+          {primary.map((id, index) => section(id, index))}
+
+          {advanced.length > 0 && (
+            <AdvancedDisclosure
+              open={advancedOpen}
+              onOpenChange={setAdvancedOpen}
+              label={advancedLabel}
+              hint={advancedHint}
+              summary={summary}
+            >
+              {advanced.map((id, index) => section(id, primary.length + index))}
+            </AdvancedDisclosure>
+          )}
+        </div>
+
+        {manifest && (
+          <div className="@min-[60rem]/form:sticky @min-[60rem]/form:top-20">
+            <BuildManifest
+              rows={rows}
+              submitLabel={submitLabel}
+              submittingLabel={submittingLabel}
+              submitting={submitting}
+              disabled={!value.name.trim()}
+              error={error}
+              caption={manifestCaption}
+              footer={manifestFooter}
+              title={manifestTitle}
+            />
+          </div>
+        )}
+      </form>
+    </div>
+  )
+
+  /** One section, numbered by its position in the whole form (folded or not). */
+  function section(id: ProjectFormSectionId, index: number) {
+    const meta = SECTION_META[id]
+    return (
+      <FormSection
+        key={id}
+        n={index + 1}
+        icon={meta.icon}
+        accent={meta.accent}
+        title={meta.title}
+        hint={meta.hint}
+        // The stagger is an inline delay rather than ten Tailwind variants;
+        // capped, or a long form's last section would arrive noticeably after
+        // you've already scrolled to it.
+        style={{ animationDelay: `${Math.min(index, 8) * 40}ms` }}
+      >
+        {renderSection(id)}
+        {extras?.[id]}
+      </FormSection>
+    )
+  }
+
+  function renderSection(id: ProjectFormSectionId): ReactNode {
+    switch (id) {
+      case "identity":
+        return (
+          <div className="space-y-4">
+            <Field label="Name" htmlFor="project-name">
+              <Input
+                id="project-name"
+                name="name"
+                placeholder="my-project"
+                required
+                value={value.name}
+                onChange={(e) => patch({ name: e.target.value })}
+              />
+            </Field>
+            <Field label="Description" htmlFor="project-description">
+              <Textarea
+                id="project-description"
+                name="description"
+                rows={2}
+                placeholder="What is this project about?"
+                value={value.description}
+                onChange={(e) => patch({ description: e.target.value })}
+              />
+            </Field>
+          </div>
+        )
+
+      case "image":
+        return (
+          <ImagePicker
+            images={images}
+            value={value.image}
+            onChange={(image) => patch({ image })}
+            layout={imagePicker?.layout}
+            detail={imagePicker?.detail}
+          />
+        )
+
+      case "repositories":
+        return (
+          <RepoList
+            repos={value.repositories}
+            onChange={(repositories) => patch({ repositories })}
+            githubRepos={githubRepos}
+            github={github}
+            connectUrl={connectUrl}
+            renderRepoField={renderRepoField}
+            githubIcon={githubIcon}
+          />
+        )
+
+      case "features":
+        return (
+          <FeaturePicker
+            features={features}
+            value={value.features}
+            onChange={(next) => patch({ features: next })}
+            layout={featurePicker?.layout}
+            detail={featurePicker?.detail}
+          />
+        )
+
+      case "extensions":
+        return (
+          <ExtensionPicker
+            value={value.vscodeExtensions}
+            onChange={(vscodeExtensions) => patch({ vscodeExtensions })}
+            onSearch={onSearchExtensions}
+          />
+        )
+
+      case "lifecycle":
+        return (
+          <div className="space-y-4">
+            <Field label="Post-create command" htmlFor="post-create" hint="Runs once after container creation">
+              <Input
+                id="post-create"
+                name="postCreateCommand"
+                placeholder="npm install"
+                className="font-mono text-xs"
+                value={value.postCreateCommand}
+                onChange={(e) => patch({ postCreateCommand: e.target.value })}
+              />
+            </Field>
+            <Field label="Post-start command" htmlFor="post-start" hint="Runs on every container start">
+              <Input
+                id="post-start"
+                name="postStartCommand"
+                placeholder="npm run dev"
+                className="font-mono text-xs"
+                value={value.postStartCommand}
+                onChange={(e) => patch({ postStartCommand: e.target.value })}
+              />
+            </Field>
+          </div>
+        )
+
+      case "ports":
+        return (
+          <Field hint="Comma-separated port numbers">
+            <Input
+              name="forwardPorts"
+              placeholder="3000, 8080"
+              // Kept as text while typing: parsing on every keystroke would
+              // delete the comma the moment you type it.
+              value={value.forwardPorts.join(", ")}
+              onChange={(e) => patch({ forwardPorts: parsePorts(e.target.value) })}
+            />
+          </Field>
+        )
+
+      case "prewarm":
+        return (
+          <Field
+            hint={
+              <>
+                One image per line. Baked into the prebuilt image and <code>docker load</code>-ed at first
+                start — turns an internal <code>docker compose up</code> from minutes into seconds.
+              </>
+            }
+          >
+            <Textarea
+              name="prewarmImages"
+              rows={3}
+              className="font-mono text-xs"
+              placeholder={"traefik:v3\nnode:24\nghcr.io/org/image:tag"}
+              value={value.prewarmImages.join("\n")}
+              onChange={(e) => patch({ prewarmImages: e.target.value.split("\n").map((l) => l.trim()).filter(Boolean) })}
+            />
+          </Field>
+        )
+
+      case "docker":
+        return (
+          <label className="flex cursor-pointer items-start justify-between gap-4 rounded-md border bg-muted/30 px-3 py-2.5">
+            <span className="space-y-0.5">
+              <span className="block text-sm leading-none font-medium">Enable Docker-in-Docker</span>
+              <span className="block text-xs text-muted-foreground">
+                Runs each worker privileged with <code>dockerd</code> and dedicated{" "}
+                <code>/var/lib/docker</code> volumes. Use with a base image that bakes Docker — no{" "}
+                <code>docker-in-docker</code> feature needed.
+              </span>
+            </span>
+            <Switch
+              checked={value.dockerInDocker}
+              onCheckedChange={(checked) => patch({ dockerInDocker: checked })}
+            />
+          </label>
+        )
+
+      case "secrets":
+        return (
+          <SecretList
+            drafts={value.secrets}
+            onDraftsChange={(secrets) => patch({ secrets })}
+            saved={savedSecrets}
+            removedIds={value.removedSecretIds}
+            onRemovedIdsChange={(removedSecretIds) => patch({ removedSecretIds })}
+            hint="Shared across every member working on this project. Override at org or personal level anytime."
+          />
+        )
+    }
+  }
+}
+
+/** `"3000, 8080, "` → `[3000, 8080]`. Anything that isn't a number is dropped. */
+function parsePorts(raw: string): number[] {
+  return raw
+    .split(",")
+    .map((p) => Number.parseInt(p.trim(), 10))
+    .filter((p) => Number.isFinite(p) && p > 0)
+}
+
+/**
+ * The manifest lines, derived from the value — never stored. Only the sections
+ * actually shown get a line: a creation form that hides ports shouldn't recap
+ * an empty "ports" row.
+ */
+export function manifestRows(value: ProjectFormValue, sections: ProjectFormSectionId[]): ManifestRow[] {
+  const shown = new Set(sections)
+  const rows: ManifestRow[] = []
+
+  if (shown.has("identity")) rows.push({ label: "name", value: value.name || "untitled", done: !!value.name.trim() })
+  if (shown.has("image"))
+    rows.push({ label: "image", value: value.image ? (value.image.split("/").pop() ?? value.image) : "—", done: !!value.image })
+  if (shown.has("repositories")) {
+    const n = value.repositories.length
+    rows.push({ label: "sources", value: `${n} repo${n === 1 ? "" : "s"}`, done: n > 0 })
+  }
+  if (shown.has("features") || shown.has("extensions"))
+    rows.push({
+      label: "features",
+      value: `${value.features.length} · ${value.vscodeExtensions.length} ext`,
+      done: value.features.length > 0 || value.vscodeExtensions.length > 0,
+    })
+  if (shown.has("lifecycle"))
+    rows.push({
+      label: "lifecycle",
+      value:
+        [value.postCreateCommand && "create", value.postStartCommand && "start"].filter(Boolean).join(" + ") ||
+        "default",
+      done: !!(value.postCreateCommand || value.postStartCommand),
+    })
+  if (shown.has("ports"))
+    rows.push({ label: "ports", value: value.forwardPorts.join(", ") || "—", done: value.forwardPorts.length > 0 })
+  if (shown.has("prewarm"))
+    rows.push({ label: "prewarm", value: `${value.prewarmImages.length}`, done: value.prewarmImages.length > 0 })
+  if (shown.has("docker"))
+    rows.push({ label: "docker", value: value.dockerInDocker ? "in-docker" : "off", done: value.dockerInDocker })
+  if (shown.has("secrets"))
+    rows.push({ label: "secrets", value: `${value.secrets.length}`, done: value.secrets.length > 0 })
+
+  return rows
+}