@spunto/design-system 0.9.3 → 0.11.0

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

@@ -0,0 +1,97 @@
+import type { ComponentType, ReactNode } from "react"
+
+import { cn } from "../../utils"
+import { Label } from "../label"
+
+/** The four warm accents; a section rotates through them down the form. */
+export type SectionAccent = "build" | "ship" | "run" | "flame"
+
+export interface FormSectionProps {
+  /** Step number in the badge. Omitted → no badge. */
+  n?: number
+  icon?: ComponentType<{ className?: string }>
+  accent?: SectionAccent
+  title: string
+  hint?: string
+  children: ReactNode
+  /** Mostly for the entrance `animationDelay` a stack of sections staggers with. */
+  style?: React.CSSProperties
+  className?: string
+}
+
+/**
+ * One numbered step of a long form: an accent bar, a number, a title, a hint.
+ *
+ * Exported on its own because a form this long is really a *stack of sections*,
+ * and an app that adds one of its own (a deploy key, a billing block) should get
+ * the same object rather than approximate it.
+ *
+ * The entrance animation the dashboard used to do with framer-motion is a plain
+ * CSS keyframe here — the package can't take a motion library as a dependency
+ * for one fade-in, and `motion-reduce:animate-none` covers the accessibility
+ * side that `useReducedMotion` covered before.
+ */
+export function FormSection({ n, icon: Icon, accent = "build", title, hint, children, style, className }: FormSectionProps) {
+  return (
+    <section
+      data-slot="form-section"
+      // `--a` set once here, then read by the bar, the badge and the icon: the
+      // accent is one custom property, not four Tailwind variants to keep in sync.
+      style={{ "--a": `var(--${accent})`, ...style } as React.CSSProperties}
+      className={cn(
+        // `p-4` on a phone: 20px of padding each side eats a tenth of a 390px
+        // screen twice over. The container is the form, so this follows the
+        // form's width and not the window's.
+        "relative overflow-hidden rounded-xl border border-border bg-card p-4 @min-[30rem]/form:p-5",
+        "motion-safe:animate-[form-section-in_0.5s_cubic-bezier(0.22,1,0.36,1)_both]",
+        className
+      )}
+    >
+      <span aria-hidden className="absolute inset-y-0 left-0 w-0.5 bg-[var(--a)]/40" />
+      <div className="mb-4 flex items-center gap-3">
+        {n != null && (
+          <span className="flex h-8 w-8 shrink-0 items-center justify-center rounded-lg bg-[var(--a)]/[0.12] font-display text-sm font-bold text-[var(--a)]">
+            {n}
+          </span>
+        )}
+        <div className="min-w-0">
+          <h3 className="flex items-center gap-2 font-display text-base font-bold tracking-tight">
+            {Icon && <Icon className="h-4 w-4 shrink-0 text-[var(--a)]" />}
+            {title}
+          </h3>
+          {hint && <p className="text-xs text-muted-foreground">{hint}</p>}
+        </div>
+      </div>
+      {children}
+    </section>
+  )
+}
+
+/** Label + control + help line — the unit every section is built out of. */
+export function Field({
+  label,
+  htmlFor,
+  hint,
+  error,
+  children,
+  className,
+}: {
+  label?: ReactNode
+  htmlFor?: string
+  hint?: ReactNode
+  error?: ReactNode
+  children: ReactNode
+  className?: string
+}) {
+  return (
+    <div className={cn("space-y-1.5", className)}>
+      {label && <Label htmlFor={htmlFor}>{label}</Label>}
+      {children}
+      {error ? (
+        <p className="text-xs text-destructive">{error}</p>
+      ) : hint ? (
+        <p className="text-xs text-muted-foreground">{hint}</p>
+      ) : null}
+    </div>
+  )
+}

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"