@spunto/design-system 0.14.1 → 0.15.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spunto/design-system",
-  "version": "0.14.1",
+  "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",

package/src/components/workers/tag-chips.tsx

@@ -24,6 +24,7 @@ export interface TagChipsProps {
   onRemove?: (tag: string, next: string[]) => void
   /** Longest accepted tag; anything past it is truncated on commit. */
   maxLength?: number
+  /** Posée sur le GROUPE (les chips et leur bouton « + »), pas sur chaque chip. */
   className?: string
 }
 
@@ -66,7 +67,11 @@ export function TagChips({ tags, onAdd, onRemove, maxLength = 32, className }: T
   if (!shown.length && !editable) return null
 
   return (
-    <>
+    // Les chips ET le bouton « + » forment UNE unité de retour à la ligne. Sur
+    // une carte étroite (grille à trois colonnes, téléphone), l'en-tête wrappe —
+    // et laissé libre, c'est le « + » qui atterrit seul sur la ligne suivante
+    // sous une première ligne pleine. Groupé, il emmène les tags avec lui.
+    <span data-slot="tag-chips" className={cn("inline-flex flex-wrap items-center gap-2", className)}>
       {shown.map((tag) => {
         const c = tagColor(tag)
         return (
@@ -76,8 +81,7 @@ export function TagChips({ tags, onAdd, onRemove, maxLength = 32, className }: T
               "inline-flex items-center gap-1 rounded-full border px-2 py-0.5 text-[10px] font-medium leading-none",
               c.bg,
               c.text,
-              c.border,
-              className
+              c.border
             )}
           >
             {tag}
@@ -134,6 +138,6 @@ export function TagChips({ tags, onAdd, onRemove, maxLength = 32, className }: T
             <PlusIcon className="h-2.5 w-2.5" />
           </button>
         ))}
-    </>
+    </span>
   )
 }

package/src/components/workers/worker-card.tsx

@@ -178,27 +178,28 @@ export function WorkerCard({
               <TagChips tags={worker.tags ?? []} onAdd={onAddTag} onRemove={onRemoveTag} />
             </div>
 
-            {/* Meta line. Each item carries its own leading separator instead of
-                the separators being siblings: this row wraps onto two lines as
-                soon as the card is narrow, and a sibling "·" then ends up
-                stranded at the end of a line, pointing at nothing. Attached to
-                the item, the worst case is a line that *starts* with "·", which
-                reads as a continuation. */}
-            <div className="mt-1.5 flex flex-wrap items-center gap-x-2 gap-y-1">
+            {/* Meta line, sans « · » entre les items : cette ligne wrappe dès que
+                la carte est étroite (grilles à deux ou trois colonnes,
+                téléphone), et un séparateur est un enfant flex comme un autre —
+                il wrappe comme un autre, donc la ligne du dessus se termine sur
+                un point suspendu dans le vide. Chaque item après l'auteur porte
+                sa propre icône, qui les sépare bien assez ; l'espacement fait le
+                reste. */}
+            <div className="mt-1.5 flex flex-wrap items-center gap-x-3 gap-y-1">
               {creator && (
-                <MetaItem first>
+                <MetaItem>
                   <CreatorAvatar creator={creator} />
                   <span className="text-muted-foreground">{creator.name}</span>
                 </MetaItem>
               )}
               {nodeName && (
-                <MetaItem first={!creator}>
+                <MetaItem>
                   <ServerIcon className="h-3 w-3 shrink-0" />
                   <span className="truncate">{nodeName}</span>
                 </MetaItem>
               )}
               {worker.createdAt && (
-                <MetaItem first={!creator && !nodeName} title={new Date(worker.createdAt).toLocaleString()}>
+                <MetaItem title={new Date(worker.createdAt).toLocaleString()}>
                   <ClockIcon className="h-3 w-3 shrink-0" />
                   {formatRelativeTime(worker.createdAt)}
                 </MetaItem>
@@ -307,24 +308,9 @@ export function WorkerCard({
  * entirely: under ~26 rem the row is two lines deep anyway and the icons already tell
  * the items apart, so the dots are pure noise there.
  */
-function MetaItem({
-  first = false,
-  title,
-  children,
-}: {
-  first?: boolean
-  title?: string
-  children: ReactNode
-}) {
+function MetaItem({ title, children }: { title?: string; children: ReactNode }) {
   return (
-    <span
-      title={title}
-      className={cn(
-        "flex min-w-0 items-center gap-1 text-[11px] text-muted-foreground/60",
-        !first &&
-          "before:hidden before:text-muted-foreground/30 before:content-['·'] @min-[26rem]:before:mr-1 @min-[26rem]:before:inline"
-      )}
-    >
+    <span title={title} className="flex min-w-0 items-center gap-1 text-[11px] text-muted-foreground/60">
       {children}
     </span>
   )