@spunto/design-system 0.14.2 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.14.2",
+  "version": "0.15.0",
   "description": "Spunto's shared design system — warm/flame tokens, color constants, and UI primitives.",
   "type": "module",
   "license": "MIT",

package/src/components/projects/advanced-sections.tsx

@@ -4,7 +4,13 @@ import type { ReactNode } from "react"
 import { ChevronDownIcon, Settings2Icon } from "lucide-react"
 
 import { cn } from "../../utils"
-import type { ProjectFormSectionId, ProjectFormValue, ProjectSecretRef } from "./types"
+import {
+  isInternalSectionId,
+  type ProjectFormCustomSection,
+  type ProjectFormSectionId,
+  type ProjectFormValue,
+  type ProjectSecretRef,
+} from "./types"
 
 export interface AdvancedDisclosureProps {
   open: boolean
@@ -101,8 +107,8 @@ export function AdvancedDisclosure({
  * `lifecycle`, `3 secrets`. Pure, and exported, because a caller rendering its
  * own fold needs the same sentence.
  */
-export function advancedSummary(
-  value: ProjectFormValue,
+export function advancedSummary<TValue extends ProjectFormValue>(
+  value: TValue,
   sections: ProjectFormSectionId[],
   /**
    * Secrets already stored server-side. They count: a project whose only
@@ -110,10 +116,23 @@ export function advancedSummary(
    * keep the fold shut over them — exactly the "hides configuration you didn't
    * set yourself" failure this component exists to avoid.
    */
-  savedSecrets: ProjectSecretRef[] = []
+  savedSecrets: ProjectSecretRef[] = [],
+  /**
+   * App-provided sections. Theirs count too, for the very same reason: a fold
+   * that shuts over a field it doesn't happen to know about hides it just as
+   * well as one it does.
+   */
+  customSections: ProjectFormCustomSection<TValue>[] = []
 ): string[] {
+  const custom = new Map(customSections.filter((s) => !isInternalSectionId(s.id)).map((s) => [s.id, s]))
   const out: string[] = []
   for (const id of sections) {
+    const own = custom.get(id)
+    if (own) {
+      const label = own.summary?.(value)
+      if (label) out.push(label)
+      continue
+    }
     switch (id) {
       case "features":
         if (value.features.length) out.push(`${value.features.length} feature${value.features.length > 1 ? "s" : ""}`)

package/src/components/projects/index.ts

@@ -18,7 +18,10 @@
 // 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.
+// prop — creation and editing are one component with a different list, and an
+// app adds a section of its own to that list (`ProjectFormCustomSection`) for a
+// field the package doesn't model, rather than drawing a card beside the form
+// and losing its numbering, its fold and its manifest row.
 //
 // 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.
@@ -53,11 +56,15 @@ export type { ExtensionPickerProps } from "./extension-picker"
 export {
   CREATE_SECTIONS,
   EDIT_SECTIONS,
+  INTERNAL_SECTION_IDS,
   emptyProjectFormValue,
+  isInternalSectionId,
   toProjectFormValue,
 } from "./types"
 export type {
+  InternalSectionId,
   ProjectFeatureSelection,
+  ProjectFormCustomSection,
   ProjectFormSectionId,
   ProjectFormValue,
   ProjectRepo,

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

@@ -27,6 +27,9 @@ import { RepoList, type GithubConnection, type GithubRepoOption, type RepoFieldR
 import { SecretList } from "./secret-list"
 import {
   CREATE_SECTIONS,
+  isInternalSectionId,
+  type InternalSectionId,
+  type ProjectFormCustomSection,
   type ProjectFormSectionId,
   type ProjectFormValue,
   type ProjectSecretRef,
@@ -35,7 +38,7 @@ import type { DevcontainerFeatureEntry, DevcontainerImageEntry, VscodeExtensionE
 
 /** Chrome of each section: number, icon, accent, wording. */
 const SECTION_META: Record<
-  ProjectFormSectionId,
+  InternalSectionId,
   { 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" },
@@ -56,7 +59,7 @@ const SECTION_META: Record<
  * sections in front of someone creating their first project is how a form stops
  * being filled in at all.
  */
-const DEFAULT_ADVANCED: ProjectFormSectionId[] = [
+const DEFAULT_ADVANCED: InternalSectionId[] = [
   "features",
   "extensions",
   "lifecycle",
@@ -66,13 +69,22 @@ const DEFAULT_ADVANCED: ProjectFormSectionId[] = [
   "secrets",
 ]
 
-export interface ProjectFormProps {
-  value: ProjectFormValue
-  onChange: (value: ProjectFormValue) => void
+export interface ProjectFormProps<TValue extends ProjectFormValue = ProjectFormValue> {
+  /**
+   * The complete value. Generic: an app whose project has a field the package
+   * doesn't model declares an interface extending `ProjectFormValue` and every
+   * callback here — including a custom section's — speaks that type instead.
+   */
+  value: TValue
+  onChange: (value: TValue) => void
   /** Receives the current value. The app maps it to its own payload and calls its API. */
-  onSubmit?: (value: ProjectFormValue) => void
+  onSubmit?: (value: TValue) => void
 
-  /** Which sections to show, in order. Defaults to the seven creation ones. */
+  /**
+   * Which sections to show, in order. Defaults to the seven creation ones.
+   * A `customSections` id sits in here like any built-in — that's how an app's
+   * own card gets a place, a number and a fold.
+   */
   sections?: ProjectFormSectionId[]
   /**
    * Sections folded behind "Advanced options". Defaults to everything past
@@ -119,6 +131,19 @@ export interface ProjectFormProps {
   /** Extra content appended inside a section — the deploy key card, a warning… */
   extras?: Partial<Record<ProjectFormSectionId, ReactNode>>
 
+  /**
+   * Cards the app draws itself, for the fields the package doesn't model.
+   *
+   * Each one is a full section: put its id in `sections` to place it, in
+   * `advancedSections` to fold it, and it gets the same numbered card, the same
+   * summary line while the fold is closed, the same manifest row. Unlike
+   * `extras` — which appends *inside* an existing section — this is a section of
+   * its own, so it doesn't have to pretend to belong to one it has nothing to do
+   * with. An id that shadows a built-in is ignored: this extends the form, it
+   * doesn't override it.
+   */
+  customSections?: ProjectFormCustomSection<TValue>[]
+
   /** `false` drops the recap panel entirely and gives the form the full width. */
   manifest?: boolean
   submitLabel?: ReactNode
@@ -148,8 +173,15 @@ export interface ProjectFormProps {
  * 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.
+ *
+ * **And that list is open.** An app with a field the package doesn't model
+ * describes its own card in `customSections` and drops its id into `sections`:
+ * it then gets the numbering, the fold, the summary and the manifest row that a
+ * `FormSection` rendered next to the form can't have. Same for the value — the
+ * form is generic over it, so the app's extra fields are typed end to end
+ * instead of riding along behind a cast.
  */
-export function ProjectForm({
+export function ProjectForm<TValue extends ProjectFormValue = ProjectFormValue>({
   value,
   onChange,
   onSubmit,
@@ -170,6 +202,7 @@ export function ProjectForm({
   onSearchExtensions,
   savedSecrets,
   extras,
+  customSections,
   manifest = true,
   submitLabel = "Save",
   submittingLabel = "Saving…",
@@ -179,14 +212,31 @@ export function ProjectForm({
   manifestFooter,
   manifestTitle,
   className,
-}: ProjectFormProps) {
-  const patch = (next: Partial<ProjectFormValue>) => onChange({ ...value, ...next })
+}: ProjectFormProps<TValue>) {
+  // The one and only write: a spread. Which is *why* a value carrying fields the
+  // package doesn't model survives a form it never taught about them — a
+  // contract now, not a lucky implementation detail (see `ProjectFormValue`).
+  // The cast lives here, once, so no app has to write one at every boundary:
+  // `{ ...TValue, ...Partial<TValue> }` is a TValue, TypeScript just can't say so
+  // about a spread of a type parameter.
+  const applyPatch = (next: Partial<ProjectFormValue> | Partial<TValue>) =>
+    onChange({ ...value, ...next } as TValue)
+  const patch: (next: Partial<ProjectFormValue>) => void = applyPatch
+  const patchCustom: (next: Partial<TValue>) => void = applyPatch
+
+  // An id in `sections` that matches neither a built-in nor a custom section is
+  // dropped up front rather than skipped at render: numbering counts positions,
+  // so leaving the hole in would shift every section after it.
+  const custom = new Map<string, ProjectFormCustomSection<TValue>>(
+    (customSections ?? []).filter((s) => !isInternalSectionId(s.id)).map((s) => [s.id, s])
+  )
+  const shown = sections.filter((id) => isInternalSectionId(id) || custom.has(id))
 
-  const rows = manifestRows(value, sections, savedSecrets)
+  const rows = manifestRows(value, shown, savedSecrets, customSections)
 
-  const advanced = sections.filter((id) => advancedSections.includes(id))
-  const primary = sections.filter((id) => !advancedSections.includes(id))
-  const summary = advancedSummary(value, advanced, savedSecrets)
+  const advanced = shown.filter((id) => advancedSections.includes(id))
+  const primary = shown.filter((id) => !advancedSections.includes(id))
+  const summary = advancedSummary(value, advanced, savedSecrets, customSections)
   // 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.
@@ -251,7 +301,12 @@ export function ProjectForm({
 
   /** One section, numbered by its position in the whole form (folded or not). */
   function section(id: ProjectFormSectionId, index: number) {
-    const meta = SECTION_META[id]
+    const own = custom.get(id)
+    // A custom card is chrome-identical to a built-in one: same `FormSection`,
+    // same badge, same accent — only its body comes from the app.
+    const meta = own
+      ? { icon: own.icon, accent: own.accent, title: own.title, hint: own.hint }
+      : SECTION_META[id as InternalSectionId]
     return (
       <FormSection
         key={id}
@@ -265,13 +320,13 @@ export function ProjectForm({
         // you've already scrolled to it.
         style={{ animationDelay: `${Math.min(index, 8) * 40}ms` }}
       >
-        {renderSection(id)}
+        {own ? own.render(value, patchCustom) : renderSection(id as InternalSectionId)}
         {extras?.[id]}
       </FormSection>
     )
   }
 
-  function renderSection(id: ProjectFormSectionId): ReactNode {
+  function renderSection(id: InternalSectionId): ReactNode {
     switch (id) {
       case "identity":
         return (
@@ -450,11 +505,17 @@ function parsePorts(raw: string): number[] {
  * actually shown get a line: a creation form that hides ports shouldn't recap
  * an empty "ports" row.
  */
-export function manifestRows(
-  value: ProjectFormValue,
+export function manifestRows<TValue extends ProjectFormValue>(
+  value: TValue,
   sections: ProjectFormSectionId[],
   /** Counted alongside the drafts — an existing secret is still a secret. */
-  savedSecrets: ProjectSecretRef[] = []
+  savedSecrets: ProjectSecretRef[] = [],
+  /**
+   * App-provided sections. Their rows come after the built-in ones, in
+   * `sections` order — the built-in lines follow a fixed reading order rather
+   * than the form's, so there's no position to interleave them at.
+   */
+  customSections: ProjectFormCustomSection<TValue>[] = []
 ): ManifestRow[] {
   const shown = new Set(sections)
   const rows: ManifestRow[] = []
@@ -491,5 +552,13 @@ export function manifestRows(
     rows.push({ label: "secrets", value: `${n}`, done: n > 0 })
   }
 
+  if (customSections.length) {
+    const byId = new Map(customSections.filter((s) => !isInternalSectionId(s.id)).map((s) => [s.id, s]))
+    for (const id of sections) {
+      const row = byId.get(id)?.manifestRow?.(value)
+      if (row) rows.push(row)
+    }
+  }
+
   return rows
 }

package/src/components/projects/types.ts

@@ -8,6 +8,11 @@
 // payload on submit. A complete value is what makes the form controllable
 // without a single `?? ""` at every input.
 
+import type { ComponentType, ReactNode } from "react"
+
+import type { ManifestRow } from "./build-manifest"
+import type { SectionAccent } from "./form-section"
+
 /** One repository to clone into the workspace. */
 export interface ProjectRepo {
   /** Client-side identity, stable across re-renders. Not the API's id. */
@@ -58,7 +63,25 @@ export interface ProjectSecretRef {
   name: string
 }
 
-/** Everything the form edits. Every field is present — see the note at the top. */
+/**
+ * Everything the form edits. Every field is present — see the note at the top.
+ *
+ * **An app may carry more, and that is a supported contract, not a trick.** The
+ * form only ever patches at the spread (`onChange({ ...value, ...next })`), so
+ * any field it doesn't model travels through untouched. Declare an interface
+ * that extends this one and pass it to the form — `<ProjectForm<MyValue> …>`, or
+ * just let it infer from `value` — and every callback (`onChange`, `onSubmit`,
+ * and a custom section's `render` / `summary` / `manifestRow`) speaks *your*
+ * type, with no cast at the boundary:
+ *
+ * ```ts
+ * interface LiteFormValue extends ProjectFormValue { sharedVolumes: Volume[] }
+ * ```
+ *
+ * That's the whole extension story for the value, deliberately: a `custom`
+ * sub-bag would be a second place to put a field, and the fields apps actually
+ * add (a branch, a volume list) belong next to the others, not in a drawer.
+ */
 export interface ProjectFormValue {
   name: string
   description: string
@@ -77,7 +100,8 @@ export interface ProjectFormValue {
   dockerInDocker: boolean
 }
 
-export type ProjectFormSectionId =
+/** The ten sections the package models and draws itself. */
+export type InternalSectionId =
   | "identity"
   | "image"
   | "repositories"
@@ -89,6 +113,72 @@ export type ProjectFormSectionId =
   | "docker"
   | "secrets"
 
+/**
+ * A section of the form: one of the ten above, or the id of a card the app
+ * brings itself through `customSections`.
+ *
+ * Open on purpose, and `(string & {})` rather than plain `string` so the ten
+ * known ids keep their autocompletion — a closed union meant an app with a field
+ * of its own had to either hang it under an unrelated section via `extras` or
+ * draw its own card outside the form, losing the numbering, the fold and the
+ * manifest along the way.
+ */
+export type ProjectFormSectionId = InternalSectionId | (string & {})
+
+/**
+ * A card the app draws itself, numbered and folded like the package's own.
+ *
+ * Same contract as an internal section, no more: `render` gets the value and a
+ * patch, and that's it. Nothing here fetches, nothing here holds state — this is
+ * a render callback that happens to be recognised by the form's chrome, not a
+ * plugin. What it buys over a hand-rolled `FormSection` rendered after the form
+ * is everything the chrome owns: its place in `sections` (inside the "Advanced
+ * options" fold if the app puts its id in `advancedSections`), its number in the
+ * shared sequence, its line in the fold's summary, and its row in the manifest.
+ *
+ * Generic over the value so an app that extends `ProjectFormValue` reads and
+ * patches its own fields without a cast (see the note on `ProjectFormValue`).
+ */
+export interface ProjectFormCustomSection<TValue extends ProjectFormValue = ProjectFormValue> {
+  /** Used in `sections` / `advancedSections` / `extras`. Ignored if it shadows an internal id. */
+  id: string
+  title: string
+  hint?: string
+  icon?: ComponentType<{ className?: string }>
+  /** Defaults to `build`, like `FormSection` itself. */
+  accent?: SectionAccent
+  /** The card's body. `patch` merges into the value, exactly like an internal section. */
+  render: (value: TValue, patch: (next: Partial<TValue>) => void) => ReactNode
+  /**
+   * One short label — `2 volumes` — when this section holds something, `null`
+   * otherwise. Feeds the closed fold's summary, and with it the form's decision
+   * to start open. Skipping it means the fold can shut over a value the user
+   * typed, which is the failure the disclosure exists to prevent.
+   */
+  summary?: (value: TValue) => string | null
+  /** A line in the build manifest, or `null`. Appended after the built-in rows. */
+  manifestRow?: (value: TValue) => ManifestRow | null
+}
+
+/** Internal ids, as a runtime set — what tells a custom id from a built-in one. */
+export const INTERNAL_SECTION_IDS: readonly InternalSectionId[] = [
+  "identity",
+  "image",
+  "repositories",
+  "features",
+  "extensions",
+  "lifecycle",
+  "ports",
+  "prewarm",
+  "docker",
+  "secrets",
+]
+
+/** True for the ten sections the package draws itself. */
+export function isInternalSectionId(id: ProjectFormSectionId): id is InternalSectionId {
+  return (INTERNAL_SECTION_IDS as readonly string[]).includes(id)
+}
+
 /** Creation: the seven sections that matter before a project exists. */
 export const CREATE_SECTIONS: ProjectFormSectionId[] = [
   "identity",