@spunto/design-system 0.10.0 → 0.11.0

package/src/components/projects/image-picker.tsx

@@ -0,0 +1,206 @@
+"use client"
+
+import { useState } from "react"
+
+import { cn } from "../../utils"
+import { ImageCard } from "../devcontainer/image-card"
+import { ImageTile } from "../devcontainer/image-tile"
+import type { DevcontainerImageEntry } from "../devcontainer/types"
+import { Input } from "../input"
+
+export interface ImagePickerProps {
+  images?: DevcontainerImageEntry[]
+  /** The image reference itself — not a catalog id. Empty = nothing picked yet. */
+  value: string
+  onChange: (image: string) => void
+  /**
+   * `chips` (default) — tag-sized entries flowing and wrapping on the left, the
+   * full card of the selected one on the right. `tiles` — a square-tile grid
+   * with the detail card underneath. `cards` — every entry as a full card, which
+   * only stays readable while the catalog is short.
+   */
+  layout?: "chips" | "tiles" | "cards"
+  /**
+   * Where the detail card goes in `chips` layout. `auto` (default) puts it on
+   * the right once the picker is wide enough for both, and underneath when it
+   * isn't — below roughly 52rem the chip column gets down to two chips a row,
+   * at which point the list is taller than it is scannable and stacking wins.
+   * `side` / `below` force it, for a layout that already knows its own width.
+   */
+  detail?: "auto" | "side" | "below"
+  className?: string
+}
+
+/**
+ * Pick the base image: the catalog, plus a "custom image" entry that swaps in a
+ * free-text field.
+ *
+ * **Why chips + a detail panel.** Full cards are the right object for six
+ * entries. Past a dozen they're a wall of near-identical blocks all repeating
+ * `mcr.microsoft.com/devcontainers/`, and picking a runtime is a *logo* task,
+ * not a reading one. Chips flow like tags — thirty images take the room six
+ * cards used to — and everything a chip has to drop (publisher, description, the
+ * full reference) comes back in one big card, for the single entry you actually
+ * chose. Scanning and reading stop competing for the same space.
+ *
+ * **The value is the reference, never the catalog id.** A ref that isn't in the
+ * catalog (typed by hand, or from a catalog that has since changed) is a
+ * first-class state, not a bug: it selects the custom entry and shows itself in
+ * the field.
+ */
+export function ImagePicker({
+  images = [],
+  value,
+  onChange,
+  layout = "chips",
+  detail: detailPosition = "auto",
+  className,
+}: ImagePickerProps) {
+  const matched = images.find((image) => image.image === value)
+  // An unrecognised ref means custom — but so does an empty value the user has
+  // just switched to, and the two are indistinguishable from `value` alone.
+  // Without this flag, clearing the field would bounce the selection back to a
+  // catalog entry mid-typing.
+  const [customPinned, setCustomPinned] = useState(false)
+  const isCustom = customPinned || (!!value && !matched)
+
+  const customEntry: DevcontainerImageEntry = {
+    label: "Custom image",
+    description: "Enter any devcontainer-compatible image",
+    image: isCustom ? value : undefined,
+  }
+
+  function selectCatalog(image: DevcontainerImageEntry) {
+    setCustomPinned(false)
+    onChange(image.image ?? "")
+  }
+
+  function selectCustom() {
+    setCustomPinned(true)
+    if (matched) onChange("")
+  }
+
+  const isSelected = (image: DevcontainerImageEntry) => !isCustom && image.image === value
+  // Only worth a card once there's something to detail: custom-but-empty has
+  // nothing to show yet, and an empty card reads as a broken one.
+  const detail = matched ?? (isCustom && value.trim() ? { label: "Custom image", image: value } : null)
+
+  const customInput = isCustom ? <CustomInput value={value} onChange={onChange} /> : null
+
+  if (layout === "cards") {
+    return (
+      <div className={cn("@container/picker space-y-3", className)}>
+        <div className="grid grid-cols-1 gap-2 @min-[34rem]/picker:grid-cols-2">
+          {images.map((image) => (
+            <ImageCard
+              key={image.id ?? image.image}
+              image={image}
+              copyable
+              selected={isSelected(image)}
+              onSelect={() => selectCatalog(image)}
+            />
+          ))}
+          <ImageCard image={customEntry} custom selected={isCustom} onSelect={selectCustom} />
+        </div>
+        {customInput}
+      </div>
+    )
+  }
+
+  if (layout === "tiles") {
+    return (
+      <div className={cn("space-y-3", className)}>
+        {/* `auto-fill` + a min track, not a fixed column count: the same grid is
+            four tiles wide in a form column and eight on a full-width page. */}
+        <div className="grid grid-cols-[repeat(auto-fill,minmax(84px,1fr))] gap-2">
+          {images.map((image) => (
+            <ImageTile
+              key={image.id ?? image.image}
+              image={image}
+              variant="tile"
+              selected={isSelected(image)}
+              onSelect={() => selectCatalog(image)}
+            />
+          ))}
+          <ImageTile image={customEntry} variant="tile" custom selected={isCustom} onSelect={selectCustom} />
+        </div>
+        {customInput}
+        {detail && <Detail image={detail} custom={isCustom} />}
+      </div>
+    )
+  }
+
+  // A CONTAINER query, so the split depends on the picker's own width and never
+  // on the window's. Stacked is the same reading order, just vertical.
+  const split = {
+    auto: "@min-[52rem]/picker:grid-cols-[1fr_minmax(18rem,22rem)] @min-[52rem]/picker:items-start",
+    // Even "forced" has a floor: below ~34rem two columns simply don't fit, and
+    // the panel would push the page into horizontal scrolling. `side` means "as
+    // soon as it fits", not "always".
+    side: "@min-[34rem]/picker:grid-cols-[1fr_minmax(15rem,22rem)] @min-[34rem]/picker:items-start",
+    below: "",
+  }[detailPosition]
+
+  return (
+    <div className={cn("@container/picker", className)}>
+      <div className={cn("grid gap-3", split)}>
+        <div className="space-y-3">
+          <div className="flex flex-wrap content-start gap-1.5">
+            {images.map((image) => (
+              <ImageTile
+                key={image.id ?? image.image}
+                image={image}
+                selected={isSelected(image)}
+                onSelect={() => selectCatalog(image)}
+              />
+            ))}
+            <ImageTile image={customEntry} custom selected={isCustom} onSelect={selectCustom} />
+          </div>
+          {customInput}
+        </div>
+
+        {detail ? (
+          <Detail image={detail} custom={isCustom} />
+        ) : (
+          // A placeholder rather than nothing: without it the chips reflow the
+          // moment you pick one, and the whole section jumps under the cursor.
+          <div
+            className={cn(
+              "min-h-[7.5rem] items-center justify-center rounded-lg border border-dashed border-border p-4 text-center text-xs text-muted-foreground",
+              detailPosition === "side" ? "hidden @min-[34rem]/picker:flex" : "hidden @min-[52rem]/picker:flex"
+            )}
+          >
+            Pick an image to see what it ships.
+          </div>
+        )}
+      </div>
+    </div>
+  )
+}
+
+function Detail({ image, custom }: { image: DevcontainerImageEntry; custom: boolean }) {
+  return (
+    <ImageCard
+      // Keyed on the reference so switching images replays the entrance — the
+      // panel is the answer to a click, and it should read as having changed.
+      key={image.image}
+      image={image}
+      custom={custom}
+      copyable
+      className="motion-safe:animate-[form-section-in_0.35s_cubic-bezier(0.22,1,0.36,1)_both]"
+    />
+  )
+}
+
+function CustomInput({ value, onChange }: { value: string; onChange: (value: string) => void }) {
+  return (
+    <Input
+      aria-label="Custom image reference"
+      placeholder="mcr.microsoft.com/devcontainers/typescript-node:20"
+      value={value}
+      required
+      className="font-mono text-xs"
+      onChange={(e) => onChange(e.target.value)}
+    />
+  )
+}

package/src/components/projects/index.ts

@@ -0,0 +1,58 @@
+// @spunto/design-system/projects — composing a project.
+//
+// Third domain sub-export, after `/workers` and `/devcontainer`. `ProjectForm`
+// is the whole "compose a dev environment" screen: 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.
+//
+// Controlled by a single `ProjectFormValue`, and nothing in here fetches:
+// catalogs come in as data, the extension search is a callback, the GitHub
+// combobox is a slot, `onSubmit` hands the value back. Which sections show is a
+// prop — creation and editing are one component with a different list.
+//
+// Every brick is exported on its own, because a screen that needs only the repo
+// rows or only the manifest shouldn't have to take the form with it.
+
+export { ProjectForm, manifestRows } from "./project-form"
+export type { ProjectFormProps } from "./project-form"
+
+export { FormSection, Field } from "./form-section"
+export type { FormSectionProps, SectionAccent } from "./form-section"
+
+export { AdvancedDisclosure, advancedSummary } from "./advanced-sections"
+export type { AdvancedDisclosureProps } from "./advanced-sections"
+
+export { BuildManifest } from "./build-manifest"
+export type { BuildManifestProps, ManifestRow } from "./build-manifest"
+
+export { RepoList, deriveFromGitUrl } from "./repo-list"
+export type { RepoListProps, GithubRepoOption, GithubConnection, RepoFieldRender } from "./repo-list"
+
+export { SecretList } from "./secret-list"
+export type { SecretListProps } from "./secret-list"
+
+export { ImagePicker } from "./image-picker"
+export type { ImagePickerProps } from "./image-picker"
+
+export { FeaturePicker } from "./feature-picker"
+export type { FeaturePickerProps } from "./feature-picker"
+
+export { ExtensionPicker } from "./extension-picker"
+export type { ExtensionPickerProps } from "./extension-picker"
+
+export {
+  CREATE_SECTIONS,
+  EDIT_SECTIONS,
+  emptyProjectFormValue,
+  toProjectFormValue,
+} from "./types"
+export type {
+  ProjectFeatureSelection,
+  ProjectFormSectionId,
+  ProjectFormValue,
+  ProjectRepo,
+  ProjectSecretDraft,
+  ProjectSecretRef,
+} from "./types"
+
+export { cn } from "../../utils"