torch-glare 2.5.1 → 2.5.3

package/apps/lib/components/FormRenderer/FormDrawer.tsx

@@ -12,7 +12,7 @@ import {
   DrawerNotchDivider,
   DrawerNotchPill,
 } from "../Drawer";
-import { FormHeaderBar, type HeaderVariant } from "../FormBuilder/header";
+import { FormHeaderBar, type HeaderVariant } from "./header";
 
 export interface FormDrawerProps {
   open: boolean;
@@ -108,7 +108,7 @@ export function FormDrawer({
 
             {/* pt-[72px] clears the 44px header pill (inset 4px) — same as the page shell. The
                 48px bottom breathing-room goes on an inner wrapper, not the scroll container:
-                FormBuilder's outer element is `h-full`, which would pin it to the content box and
+                FormRenderer's outer element is `h-full`, which would pin it to the content box and
                 swallow the container's own `pb`. On a plain wrapper that `h-full` resolves to the
                 content height, so the padding actually lengthens the scroll. The conclusion panel
                 is a separate sibling, so it keeps its own spacing. */}

package/apps/lib/components/FormRenderer/detail.tsx

@@ -5,11 +5,11 @@ import * as TabsPrimitive from "@radix-ui/react-tabs";
 
 import { cn } from "../../utils/cn";
 import { formBarItemStyles } from "../TabFormItem";
-import { FormHeaderBar, type HeaderVariant } from "../FormBuilder/header";
+import { FormHeaderBar, type HeaderVariant } from "./header";
 
 /**
  * Detail-tabs — a display-only view where a left **sidebar** switches the main area between
- * **`FormBuilder.Section` panels** (a detail page, not a form). It lives on `FormRenderer`
+ * **`FormRenderer.Section` panels** (a detail page, not a form). It lives on `FormRenderer`
  * (`FormRenderer.Sidebar` / `.Sidebar.Item` / `.Tab`) so `FormBuilder` stays form-only. Built on
  * the same Radix Tabs primitive shadcn uses: the sidebar is the `Tabs.List`, each `Sidebar.Item` a
  * `Tabs.Trigger`, each `Tab` a `Tabs.Content` — so the fixed rail and the panels share tab state.
@@ -20,7 +20,7 @@ export interface DetailSidebarProps {
 }
 
 /**
- * `FormRenderer.Sidebar` — the tab rail, sitting where a `FormBuilder.Stepper`'s nav would.
+ * `FormRenderer.Sidebar` — the tab rail, sitting where a `FormRenderer.Stepper`'s nav would.
  * Renders **nothing itself**: the FormRenderer root detects it and places its `Sidebar.Item`
  * children (the tab triggers) into the fixed rail.
  */
@@ -80,7 +80,7 @@ export interface DetailRowProps {
 
 /**
  * `FormRenderer.Row` — a read-only label/value cell for detail content (the display counterpart of a
- * form field). Drop several inside a `FormRenderer.Grid` within a `FormBuilder.Section`.
+ * form field). Drop several inside a `FormRenderer.Grid` within a `FormRenderer.Section`.
  */
 export function DetailRow({ label, value }: DetailRowProps) {
   return (
@@ -110,7 +110,7 @@ const GRID_COLS: Record<NonNullable<DetailGridProps["columns"]>, string> = {
 /**
  * `FormRenderer.Grid` — arranges `FormRenderer.Row`s in an equal-column grid spanning the **full
  * section width** (default 2 columns, so cells split in half). Padded so the rows breathe inside a
- * `FormBuilder.Section` (clear of the title badge, roomy row + column spacing).
+ * `FormRenderer.Section` (clear of the title badge, roomy row + column spacing).
  */
 export function DetailGrid({ columns = 2, children }: DetailGridProps) {
   return (
@@ -121,7 +121,7 @@ export function DetailGrid({ columns = 2, children }: DetailGridProps) {
 export interface DetailTabProps {
   /** Ties this panel to the `Sidebar.Item` of the same `value`. */
   value: string;
-  /** The panel body — typically `FormBuilder.Section` display blocks. */
+  /** The panel body — typically `FormRenderer.Section` display blocks. */
   children: React.ReactNode;
 }
 

package/apps/lib/components/FormRenderer/form-renderer.tsx

@@ -1,11 +1,11 @@
 "use client";
 
-import { Children, useId } from "react";
-import { FieldValues } from "react-hook-form";
+import { Children, useId, type ReactElement, type ReactNode } from "react";
+import { useForm, type Control, type FieldValues } from "react-hook-form";
 
+import { cn } from "../../utils/cn";
 import { FormBuilder } from "../FormBuilder";
 import { FormIdContext, LoadingContext } from "../FormBuilder/context";
-import { StepperActions } from "../FormBuilder/stepper";
 import {
   DetailSidebar,
   DetailTab,
@@ -16,20 +16,39 @@ import {
   isDetailTabElement,
 } from "./detail";
 import { FormDrawer } from "./FormDrawer";
+import { FormHeaderBar } from "./header";
+import { Section } from "./section";
+import {
+  Back,
+  Next,
+  Step,
+  StepSlot,
+  Stepper,
+  StepperActions,
+  StepperContext,
+  StepperNav,
+  isStepElement,
+  isStepperElement,
+  useStepperState,
+  type StepProps,
+} from "./stepper";
 import type { FormRendererProps } from "./types";
 
 /**
- * FormRenderer — a thin wrapper around the compound `FormBuilder`. Author the
- * fields as JSX children; FormRenderer owns page-vs-drawer display, the absolute
- * title header, and drawer field direction.
+ * FormRenderer — the chrome around a `FormBuilder`.
+ *
+ * `FormBuilder` is the fields and nothing else: a `<form>`, its react-hook-form context, and the
+ * field components. Every pixel drawn *around* those fields is here — page-vs-drawer display, the
+ * absolute title header, the `actions` bar, titled `FormRenderer.Section` cards, the page gutters,
+ * the scroll shell, the wizard rail (`FormRenderer.Stepper`), and the `summary` column.
  *
  * FormRenderer never manufactures a Submit — you compose it and hand it to `actions`
- * (`actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}`). It renders in the form's
- * header action pill (page) or the drawer header (drawer), and auto-targets this form.
+ * (`actions={<FormBuilder.Submit>Save</FormBuilder.Submit>}`). It renders in the form's header
+ * action pill (page) or the drawer header (drawer), and auto-targets this form.
  *
  * Give it `FormRenderer.Sidebar` + `FormRenderer.Tab` children instead of fields and it switches to
- * a **detail-tabs** view: a display-only page (no `<form>`) whose sidebar swaps `FormBuilder.Section`
- * panels — the sidebar sits where a stepper's rail would.
+ * a **detail-tabs** view: a display-only page (no `<form>`) whose sidebar swaps
+ * `FormRenderer.Section` panels — the sidebar sits where a stepper's rail would.
  */
 function FormRendererRoot<T extends FieldValues = FieldValues>({
   children,
@@ -65,12 +84,35 @@ function FormRendererRoot<T extends FieldValues = FieldValues>({
   const autoId = useId();
   const formId = id ?? autoId;
 
+  // The form instance is created HERE, not in FormBuilder, because the stepper needs `trigger` to
+  // validate a step before advancing — and the rail that calls it renders outside the `<form>`.
+  // Same pattern FormBuilder uses: one is always created (hooks can't be conditional), the
+  // caller's hoisted instance wins when given.
+  const ownForm = useForm<T>({ resolver, defaultValues, values });
+  const formInstance = form ?? ownForm;
+
+  const childArray = Children.toArray(children);
+
   // Detail-tabs mode: a `FormRenderer.Sidebar` + `FormRenderer.Tab` children mean a display-only
   // detail page (no `<form>`) — the sidebar swaps Section panels via Radix Tabs. Detected here so
   // the form props below are simply unused.
-  const childArray = Children.toArray(children);
   const detailSidebar = childArray.find(isDetailSidebarElement);
   const detailTabs = childArray.filter(isDetailTabElement);
+
+  // Split out a `FormRenderer.Stepper`: its Steps become the visibility-toggled slots inside the
+  // `<form>`, its non-Step children a footer, and its state drives the rail beside them.
+  const stepperEl = childArray.find(isStepperElement);
+  const stepChildren = stepperEl ? Children.toArray(stepperEl.props.children) : [];
+  const steps = stepChildren.filter(isStepElement) as ReactElement<StepProps>[];
+  const stepExtras = stepChildren.filter((n) => !isStepElement(n));
+  const isStepper = !!stepperEl;
+
+  // Called unconditionally (inert when there are no steps) to keep hooks order stable.
+  const stepper = useStepperState(
+    steps,
+    formInstance.trigger as Parameters<typeof useStepperState>[1],
+  );
+
   if (detailSidebar && detailTabs.length > 0) {
     return (
       <DetailTabsView
@@ -83,35 +125,118 @@ function FormRendererRoot<T extends FieldValues = FieldValues>({
     );
   }
 
-  const inner = (
+  // The fields the `<form>` wraps: the stepper's steps (+ any custom footer extras), or the
+  // children as authored. Every step stays mounted so the whole form is registered at all times.
+  const fields: ReactNode = isStepper ? (
+    <>
+      {steps.map((step, i) => (
+        <StepSlot key={i} index={i} active={i === stepper.currentStep}>
+          {step.props.children}
+        </StepSlot>
+      ))}
+      {stepExtras}
+    </>
+  ) : (
+    children
+  );
+
+  const formEl = (
     <FormBuilder
       id={formId}
-      form={form}
+      form={formInstance}
       onSubmit={onSubmit ?? (() => {})}
       onInvalid={onInvalid}
-      resolver={resolver}
-      defaultValues={defaultValues}
-      values={values}
       loading={loading}
       fieldDirection={effectiveDirection}
       resetOnSuccess={resetOnSuccess}
-      // Page display only — in a drawer the panel owns the sizing.
-      className={!isDrawer ? className : undefined}
-      // Page display: FormBuilder lays the conclusion as the grid's right column (a stepper adds
-      // the left nav column too). In a drawer the summary goes to FormDrawer's tray instead.
-      conclusion={!isDrawer ? summary : undefined}
     >
-      {useHeader && (
-        <FormBuilder.Header title={header!.title} label={header!.label} variant={header!.variant}>
-          {/* A stepper form prepends chevron Back/Next + a divider before the Submit. */}
-          {actions && <StepperActions>{actions}</StepperActions>}
-        </FormBuilder.Header>
-      )}
-
-      {children}
+      {fields}
     </FormBuilder>
   );
 
+  // The fields column caps at 1100px and centres — standalone, and as the middle column of the
+  // stepper grid. This is page framing, which is why it wraps FormBuilder rather than living
+  // inside it: a form embedded in a 260px rail has no room to give up 96px to gutters.
+  const fieldsColumn = <div className="mx-auto w-full max-w-[1100px] px-[48px]">{formEl}</div>;
+
+  // Inside the form surface: the stepper rail beside the fields. Columns never wrap — the layout
+  // stays side-by-side at every screen size; when space runs short the fields column shrinks and
+  // the rail's labels truncate.
+  //
+  // `minmax(180px,1fr)` and not a bare `1fr` on the side tracks. `1fr` means `minmax(auto,1fr)`,
+  // whose *auto* minimum stops a track shrinking below its content — so a long step label made the
+  // rail's track wider than the empty track opposite it, and the two side tracks being equal is the
+  // only thing centring the middle column. Hovering a step made it visibly worse: the label's
+  // padding grows 6px→9px on hover (FormStepper), so the centre jumped 3px every time.
+  //
+  // The minimum is a fixed 180px rather than `auto` precisely so it cannot depend on the labels:
+  // both side tracks size identically whatever the rail holds, so the middle column stays centred,
+  // and the rail still has room to be legible (a plain `minmax(0,…)` let it collapse to 0 in a
+  // narrow preview frame). Past that floor the labels truncate instead of pushing.
+  const bodyInner = isStepper ? (
+    <div className="grid w-full grid-cols-[minmax(180px,1fr)_minmax(0,1100px)_minmax(180px,1fr)] gap-8">
+      <StepperNav control={formInstance.control as Control<FieldValues>} />
+      {fieldsColumn}
+      {/* Empty third column — balances the rail's gutter so the middle column is centred. */}
+      <div />
+    </div>
+  ) : (
+    fieldsColumn
+  );
+
+  const surface = useHeader ? (
+    // Scroll shell: the absolute header floats over the scrollable body. No fixed height — it
+    // fills whatever the parent gives it (like the drawer's panel fills its tray) and the body
+    // scrolls internally.
+    <div className="relative isolate flex h-full w-full flex-col overflow-hidden rounded-2xl bg-background-presentation-body-primary">
+      <FormHeaderBar title={header!.title} label={header!.label} variant={header!.variant}>
+        {/* A stepper form prepends chevron Back/Next + a divider before the Submit. */}
+        {actions && <StepperActions>{actions}</StepperActions>}
+      </FormHeaderBar>
+      <div className="relative z-[1] flex min-h-0 w-full flex-1 flex-col overflow-y-auto px-6 py-6 pt-[72px] scrollbar-hide">
+        {bodyInner}
+      </div>
+    </div>
+  ) : (
+    bodyInner
+  );
+
+  // The summary (right) lives OUTSIDE the scroll surface — its own panel beside it (mirroring the
+  // drawer's tray, a 6px gutter). Only the surface's body scrolls; the summary stays put. In a
+  // drawer it goes to FormDrawer's tray instead.
+  const pageBody =
+    summary && !isDrawer ? (
+      <div className="flex h-full flex-row items-stretch">
+        <div className="min-h-0 min-w-0 flex-1">{surface}</div>
+        <div className="ml-[6px] flex min-h-0">{summary}</div>
+      </div>
+    ) : (
+      surface
+    );
+
+  // `className` lands on the OUTERMOST element — the one a parent lays out (e.g. `flex-1 min-h-0`
+  // to fill a flex column). `h-full` fills a parent that has a definite height.
+  //
+  // The form-id and loading contexts are supplied HERE as well as inside FormBuilder, because the
+  // header's action pill renders outside the `<FormBuilder>` subtree: a bare `FormBuilder.Submit`
+  // in `actions` reads the id from context to target the `<form>` by native form-association.
+  // Same reason the drawer branch below re-provides them around its own header.
+  const inner = (
+    <LoadingContext.Provider value={!!loading}>
+      <FormIdContext.Provider value={formId}>
+        <div className={cn("h-full w-full", !isDrawer && className)}>{pageBody}</div>
+      </FormIdContext.Provider>
+    </LoadingContext.Provider>
+  );
+
+  // One provider around the whole tree: the rail renders outside the `<form>`, the step slots
+  // inside it, and both read the same state.
+  const tree = isStepper ? (
+    <StepperContext.Provider value={stepper}>{inner}</StepperContext.Provider>
+  ) : (
+    inner
+  );
+
   if (isDrawer) {
     return (
       <FormDrawer
@@ -132,21 +257,28 @@ function FormRendererRoot<T extends FieldValues = FieldValues>({
         }
         onOpenInNewTab={onOpenInNewTab}
       >
-        {inner}
+        {tree}
       </FormDrawer>
     );
   }
 
-  // Page display: FormBuilder already placed `summary` as the grid's conclusion column.
-  return inner;
+  return tree;
 }
 
 /**
- * FormRenderer — see {@link FormRendererRoot}. The compound statics drive the display-only
- * **detail-tabs** view: `FormRenderer.Sidebar` (the rail) + `FormRenderer.Sidebar.Item` (a tab) +
- * `FormRenderer.Tab` (a `FormBuilder.Section` panel).
+ * FormRenderer — see {@link FormRendererRoot}. The compound statics are the form's chrome:
+ *
+ * - `FormRenderer.Section` — a titled card grouping fields (or display rows).
+ * - `FormRenderer.Stepper` / `.Step` — the wizard; `.Back` / `.Next` are the chevron controls,
+ *   which the header's action bar already prepends for you.
+ * - `FormRenderer.Sidebar` / `.Tab` / `.Grid` / `.Row` — the display-only **detail-tabs** view.
  */
 export const FormRenderer = Object.assign(FormRendererRoot, {
+  Section,
+  Stepper,
+  Step,
+  Back,
+  Next,
   Sidebar: DetailSidebar,
   Tab: DetailTab,
   Grid: DetailGrid,

package/apps/lib/components/{FormBuilder → FormRenderer}/header.tsx

@@ -29,8 +29,10 @@ export interface FormHeaderBarProps {
  * The floating form header: a `HeaderBar` title pill on the left and a dark action
  * pill on the right, absolutely positioned over the scrollable body.
  *
- * Shared by **both** form surfaces — `FormBuilder.Header` (page) and `FormDrawer`
- * (drawer) — so a form's title looks identical wherever it is rendered.
+ * Shared by all three FormRenderer surfaces — the page form, `FormDrawer` and the
+ * detail view — so a form's title looks identical wherever it is rendered. This is
+ * chrome, so it lives here rather than in `FormBuilder`: a bare `<FormBuilder>` is
+ * fields and nothing else.
  *
  * Per the design both pills are 44px tall, reached differently: the title pill is
  * 6px padding + 32px content, the action pill 8px + 28px.
@@ -70,32 +72,17 @@ export function FormHeaderBar({
   );
 }
 
-export interface HeaderProps {
+/**
+ * The `header` prop's shape — `header={{ title, label, variant }}` on `FormRenderer`.
+ * There is no `FormRenderer.Header` component: the header is a prop, not a child, so a
+ * child element can never reconfigure the surrounding layout the way the old
+ * `FormBuilder.Header` did.
+ */
+export interface HeaderConfig {
   /** Plain title text (uppercased), e.g. the entity label or SKU. */
   title: string;
   /** Badge text — defaults from `variant` (New / Edit / View). */
   label?: string;
-  /** Colored badge variant. Defaults from the form `mode` (view → detail). */
+  /** Colored badge variant. */
   variant?: HeaderVariant;
-  /** Action buttons shown in the right-hand action pill (e.g. FormBuilder.Submit). */
-  children?: ReactNode;
-}
-
-/**
- * `FormBuilder.Header` — the page form's title + action bar. A thin, mode-aware
- * wrapper over `FormHeaderBar`: it defaults the badge variant from the form `mode`
- * (view → detail).
- *
- * Place it as a direct child of `<FormBuilder>`; the root then switches to the
- * scroll-shell layout that reserves space beneath the floating header.
- */
-export function Header({ title, label, variant = "new", children }: HeaderProps) {
-  return (
-    <FormHeaderBar title={title} label={label} variant={variant}>
-      {children}
-    </FormHeaderBar>
-  );
 }
-
-// Marker so the FormBuilder root can detect the header among its children.
-(Header as unknown as { __isFormHeader: boolean }).__isFormHeader = true;

package/apps/lib/components/FormRenderer/index.ts

@@ -1,6 +1,10 @@
 export { FormRenderer } from "./form-renderer";
 export { FormDrawer } from "./FormDrawer";
 export type { FormDrawerProps } from "./FormDrawer";
+export { FormHeaderBar } from "./header";
+export type { HeaderConfig, HeaderVariant, FormHeaderBarProps } from "./header";
+export type { SectionProps } from "./section";
+export type { StepProps, StepperProps } from "./stepper";
 export type { FormRendererProps, FormRendererDisplay, FieldDirection } from "./types";
 export type {
   DetailSidebarProps,

package/apps/lib/components/FormRenderer/section.tsx

@@ -0,0 +1,39 @@
+"use client";
+
+import { ReactNode } from "react";
+
+import { SectionBlock, type SectionColor, type SectionVariant } from "../SectionBlock";
+
+export interface SectionProps {
+  title?: ReactNode;
+  color?: SectionColor;
+  icon?: ReactNode;
+  /**
+   * `"Table"` switches to the full-bleed table shell — no body padding, a rule under
+   * the header, and the card clipped to its radius. `FormBuilder.Table` uses it; pass
+   * it here only when hand-composing a table inside a section.
+   */
+  variant?: SectionVariant;
+  /** Right-aligned content on the title row — e.g. action buttons. */
+  action?: ReactNode;
+  children: ReactNode;
+}
+
+/**
+ * `FormRenderer.Section` — a titled Glare `SectionBlock` grouping fields.
+ *
+ * It lives here, not on `FormBuilder`, because it is presentation: a coloured card with a title
+ * row and an action slot. It holds no form state and reads no form context, so it works just as
+ * well around the read-only `FormRenderer.Grid` rows of a detail page as it does around fields.
+ *
+ * The per-field row layout — label, required marker, hint, the two-column split — is a different
+ * thing entirely: that is `FieldSection`, applied by every field itself, and it stays inside
+ * FormBuilder where the fields are.
+ */
+export function Section({ title, color, icon, variant, action, children }: SectionProps) {
+  return (
+    <SectionBlock title={title} color={color} icon={icon} variant={variant} action={action}>
+      {children}
+    </SectionBlock>
+  );
+}

package/apps/lib/components/{FormBuilder → FormRenderer}/stepper.tsx

@@ -1,18 +1,42 @@
 "use client";
 
 import * as React from "react";
-import { useFormState, type FieldPath, type FieldValues } from "react-hook-form";
+import { useFormState, type Control, type FieldPath, type FieldValues } from "react-hook-form";
 
 import { cn } from "../../utils/cn";
 import { Button } from "../Button";
+// The step *registry* stays with the fields: `FieldShell` registers each field name into it, so
+// it must ship with FormBuilder (which is installable on its own). Everything else about the
+// stepper — the rail, the state, Back/Next — is chrome and lives here. The dependency only ever
+// points this way: FormRenderer → FormBuilder, never back.
+import { StepContext, type StepRegistry } from "../FormBuilder/context";
 import { FormStepper, FormStep, FormStepIndicator, FormStepLabel } from "../FormStepper";
-import {
-  StepContext,
-  StepperContext,
-  useStepper,
-  type StepperContextValue,
-  type StepRegistry,
-} from "./context";
+
+// ─── Stepper state context ───────────────────────────────────────────────────
+
+/** Stepper state shared by the nav, the step slots and the Back/Next buttons. */
+export interface StepperContextValue {
+  currentStep: number;
+  totalSteps: number;
+  titles: string[];
+  isFirstStep: boolean;
+  isLastStep: boolean;
+  goToNext: () => void | Promise<void>;
+  goToPrevious: () => void;
+  goToStep: (index: number) => void;
+  /** Field names registered per step, for per-step validation. */
+  stepFields: Record<number, Set<string>>;
+  /** Steps that have passed validation — stay checked even after navigating back. */
+  completedSteps: Set<number>;
+}
+
+export const StepperContext = React.createContext<StepperContextValue | null>(null);
+
+export const useStepper = () => {
+  const ctx = React.useContext(StepperContext);
+  if (!ctx) throw new Error("FormRenderer.Step/Back/Next must be used within FormRenderer.Stepper");
+  return ctx;
+};
 
 // ─── Step (declaration only — the Stepper reads its props) ───────────────────
 
@@ -23,7 +47,7 @@ export interface StepProps {
 }
 
 /**
- * Declares a wizard step. It renders nothing itself — `FormBuilder.Stepper`
+ * Declares a wizard step. It renders nothing itself — `FormRenderer.Stepper`
  * collects Step elements as an array and renders every step's fields (so the
  * **whole form is registered**), toggling visibility per the active step.
  */
@@ -76,16 +100,23 @@ function StepSlot({
 /**
  * Vertical step rail (matches `Tabs.svg`): the numbered state badges stacked top
  * to bottom, joined by a short vertical connector between consecutive steps.
+ *
+ * `control` is passed in rather than read from context: the rail renders in its own grid column
+ * **outside** the `<form>`, so there is no `FormProvider` above it to read. Same reason
+ * `useStepperState` takes `trigger` as an argument.
  */
-function StepperNav() {
+function StepperNav({ control }: { control: Control<FieldValues> }) {
   const { titles, currentStep, goToStep, stepFields, completedSteps } = useStepper();
-  const { errors } = useFormState();
+  const { errors } = useFormState({ control });
 
   const stepHasError = (index: number) =>
     [...(stepFields[index] ?? [])].some((name) => name in errors);
 
   return (
-    <FormStepper activeStep={currentStep} className="shrink-0 flex-col items-start gap-[4px]">
+    // `min-w-0` so the rail can be squeezed: its grid track no longer grows to fit a long label
+    // (see form-renderer.tsx), so the column has to be allowed to shrink and let the labels
+    // truncate instead of spilling over the fields column.
+    <FormStepper activeStep={currentStep} className="min-w-0 shrink-0 flex-col items-start gap-[4px]">
       {titles.map((title, index) => {
         // The step buttons ARE the navigation: click to move. Backward is free;
         // clicking forward validates the steps in between (goToStep) and stops at
@@ -98,9 +129,21 @@ function StepperNav() {
             : "default";
         return (
           <React.Fragment key={title}>
-            <FormStep index={index} type={type} onClick={() => void goToStep(index)}>
+            {/* The shrink/truncate pair is passed in rather than changed in `FormStepper`, so its
+                other consumers keep sizing to their labels. `shrink` beats the pill's own
+                `shrink-0` and `truncate` beats the label's `whitespace-nowrap` — both via
+                tailwind-merge, which `FormStepper` runs the caller's className through. */}
+            <FormStep
+              index={index}
+              type={type}
+              onClick={() => void goToStep(index)}
+              // `max-w-full` is what actually makes the label truncate: the rail is
+              // `items-start`, so without a cap the pill shrink-wraps its label and grows straight
+              // past the track instead of clipping inside it.
+              className="min-w-0 max-w-full shrink"
+            >
               <FormStepIndicator />
-              <FormStepLabel>{title}</FormStepLabel>
+              <FormStepLabel className="truncate">{title}</FormStepLabel>
             </FormStep>
             {/* Connector between steps — a 3×16 rounded bar centred under the badge. */}
             {index < titles.length - 1 && (
@@ -150,13 +193,13 @@ function StepNavButton({
   );
 }
 
-/** `FormBuilder.Back` — chevron to the previous step; disabled on the first. */
+/** `FormRenderer.Back` — chevron to the previous step; disabled on the first. */
 export function Back() {
   const { goToPrevious, isFirstStep } = useStepper();
   return <StepNavButton dir="left" onClick={goToPrevious} disabled={isFirstStep} />;
 }
 
-/** `FormBuilder.Next` — chevron to the next step (validates first); disabled on the last. */
+/** `FormRenderer.Next` — chevron to the next step (validates first); disabled on the last. */
 export function Next() {
   const { goToNext, isLastStep } = useStepper();
   return <StepNavButton dir="right" onClick={() => void goToNext()} disabled={isLastStep} />;
@@ -165,7 +208,7 @@ export function Next() {
 // ─── Stepper action bar (Back/Next + divider, then the Submit) ────────────────
 
 /**
- * `FormRenderer` wraps its `actions` in this. When the form is a stepper it prepends the
+ * The FormRenderer root wraps its `actions` in this. When the form is a stepper it prepends the
  * chevron `Back`/`Next` controls + a divider before the (user-provided) Submit — the Figma
  * `Body-HeaderBar-1.0` layout. Outside a stepper there's no `StepperContext`, so it renders
  * the actions untouched.
@@ -191,10 +234,10 @@ export interface StepperProps {
 }
 
 /**
- * `FormBuilder.Stepper` — declares a wizard. It renders **nothing itself**: the
- * FormBuilder root detects it, lifts its state (so the nav can live in its own
+ * `FormRenderer.Stepper` — declares a wizard. It renders **nothing itself**: the
+ * FormRenderer root detects it, lifts its state (so the nav can live in its own
  * grid column *outside* the `<form>`), and renders `[nav | active step's fields]`.
- * Children are `FormBuilder.Step`s (plus an optional custom footer).
+ * Children are `FormRenderer.Step`s (plus an optional custom footer).
  *
  * Every step's fields stay registered with react-hook-form at all times — the
  * stepper only controls which step is *visible*. **Navigation is the step buttons
@@ -202,7 +245,7 @@ export interface StepperProps {
  * validates every step in between and stops at the first with errors (which shows a
  * red indicator). Only the last step shows the Submit button.
  */
-// eslint-disable-next-line @typescript-eslint/no-unused-vars -- children are read by the FormBuilder root
+// eslint-disable-next-line @typescript-eslint/no-unused-vars -- children are read by the FormRenderer root
 export function Stepper(_props: StepperProps) {
   return null;
 }
@@ -218,7 +261,7 @@ export function isStepperElement(node: React.ReactNode): node is React.ReactElem
 type TriggerFn = (names?: FieldPath<FieldValues>[]) => Promise<boolean>;
 
 /**
- * Stepper state — lifted to the FormBuilder root so the nav (rail) and the step
+ * Stepper state — lifted to the FormRenderer root so the nav (rail) and the step
  * fields can render in separate grid columns while sharing one state. `trigger` is
  * the form's `trigger` (passed in — no `useFormContext` needed). Inert when
  * `steps` is empty (a form without a stepper still calls this, for hooks order).

package/apps/lib/components/FormRenderer/types.ts

@@ -8,18 +8,18 @@ import type {
 } from "react-hook-form";
 
 /**
- * FormRenderer — a thin wrapper around the compound `FormBuilder`. You author the
- * fields as **JSX children** (`FormBuilder.Section`, `FormBuilder.Text`, …); the
- * renderer owns the surrounding concerns: page-vs-drawer display, the absolute
- * title header, vertical field layout inside a drawer, and an `actions` slot (the
- * form's header / drawer action bar) where you place the Save.
+ * FormRenderer — the chrome around a `FormBuilder`. You author the fields as **JSX children**
+ * (`FormRenderer.Section`, `FormBuilder.Text`, …); the renderer owns everything drawn around
+ * them: page-vs-drawer display, the absolute title header, the `actions` bar, the titled section
+ * cards, the page gutters and scroll shell, the wizard rail, the `summary` column, and vertical
+ * field layout inside a drawer.
  */
 
 export type FormRendererDisplay = "page" | "drawer";
-export type FieldDirection = "horizontal" | "vertical";
+export type FieldDirection = "horizontal" | "vertical" | "flexible";
 
 export interface FormRendererProps<T extends FieldValues = FieldValues> {
-  /** The form body — `FormBuilder.Section` / field / `FormBuilder.Stepper` JSX. */
+  /** The form body — `FormRenderer.Section` / field / `FormRenderer.Stepper` JSX. */
   children: ReactNode;
 
   // --- react-hook-form root (forwarded to FormBuilder) ---

package/apps/lib/components/SectionBlock.tsx

@@ -14,7 +14,17 @@ const titleBadge = cva(
         Orange: "bg-red-orange-900",
         Purple: "bg-violet-900",
         Pink: "bg-medium-violet-red-900",
-        Gray: "bg-background-presentation-badge-gray",
+        // Per Figma (`FormHeader10`, Color=Gray), which pairs two *variables*: the pill is
+        // `background/presentation/button/primary` and its label `content/presentation/global/
+        // primary-inverse`. They invert together — a light pill with dark text in the dark theme,
+        // dark pill with white text in the light one — so the text token has to ride along on the
+        // variant. It overrides the base `text-[#F4F4F4]` because `titleBadge` goes through `cn`
+        // (tailwind-merge) below; the other seven are dark palette chips that still want that base.
+        //
+        // This previously read `bg-background-presentation-badge-gray`, which is not a token at all:
+        // every badge colour has `-solid`/`-subtle` and none has a bare name, so the utility was
+        // never generated and a Gray badge painted no background whatsoever.
+        Gray: "bg-background-presentation-button-primary text-content-presentation-global-primary-inverse",
       },
     },
     defaultVariants: { color: "Blue" },