@ogygie/ui 0.0.0-stage → 0.16.0

package/src/ScreenState.tsx

@@ -0,0 +1,102 @@
+/**
+ * @intent The ONE component that decides what a screen shows before its body
+ * (D39): access denied, then error, then loading, then empty — in that order,
+ * because a denial must never read as a failure to load, and a failure must
+ * never read as "still loading". It receives a `QueryLike` (the subset of a
+ * TanStack Query result), so a container passes its hook's result as it is
+ * and a test passes a fixture. The body is a render function that receives
+ * the data ONCE it is there: a body never branches on `undefined`.
+ *
+ * Every text is a prop (the product translates); the loading state has none
+ * — a skeleton, `aria-busy`, no sentence to translate.
+ */
+import type { ReactNode } from "react";
+import { EmptyState } from "./EmptyState.js";
+import { ErrorBanner } from "./ErrorBanner.js";
+import { isAccessDenied } from "./failures.js";
+import type { QueryLike } from "./query-like.js";
+
+/** What an explanatory state says: the same three slots as EmptyState. */
+export interface StateCopy {
+  title: ReactNode;
+  explanation: ReactNode;
+  action?: ReactNode;
+}
+
+export interface ScreenStateProps<TData> {
+  query: QueryLike<TData>;
+  /** The body, rendered once the data is served and not empty. */
+  children: (data: TData) => ReactNode;
+  /** The caller's own verdict (the viewer's permissions) — shown before any request is judged. */
+  denied?: boolean;
+  /** What a denied caller reads, also used when the read fails with 401 or 403. Absent, a 401/403 shows as an ErrorBanner. */
+  accessDenied?: StateCopy;
+  /** When the served data is an empty collection — the caller says what "empty" means for its shape. */
+  isEmpty?: (data: TData) => boolean;
+  /** What an empty screen says, with its one creation action. Absent, the body renders the empty data. */
+  emptyState?: StateCopy;
+  /** The loading surface. Absent: `Skeleton`. */
+  loading?: ReactNode;
+  /** The sentence above a failure, worded by the product. */
+  errorTitle?: ReactNode;
+  retry?: { label: ReactNode; onClick: () => void };
+}
+
+/** Pulsing bars, `role="status"`: the loading state has no sentence to translate. */
+export function Skeleton({ rows = 3 }: { rows?: number }) {
+  return (
+    <div role="status" aria-busy="true" data-pattern="Skeleton" className="animate-pulse space-y-3">
+      {Array.from({ length: rows }, (_, index) => (
+        <div key={index} className={index === 0 ? "h-6 w-1/3 rounded-sm bg-border" : "h-4 rounded-sm bg-border"} />
+      ))}
+    </div>
+  );
+}
+
+export function ScreenState<TData>(props: ScreenStateProps<TData>) {
+  const { query } = props;
+  const deniedCopy = props.accessDenied;
+
+  if (props.denied === true) {
+    return (
+      <div data-pattern="ScreenState" data-state="denied">
+        {deniedCopy === undefined ? null : <EmptyState {...deniedCopy} />}
+      </div>
+    );
+  }
+  if (query.error != null) {
+    if (deniedCopy !== undefined && isAccessDenied(query.error)) {
+      return (
+        <div data-pattern="ScreenState" data-state="denied">
+          <EmptyState {...deniedCopy} />
+        </div>
+      );
+    }
+    return (
+      <div data-pattern="ScreenState" data-state="error">
+        <ErrorBanner
+          error={query.error}
+          {...(props.errorTitle === undefined ? {} : { title: props.errorTitle })}
+          {...(props.retry === undefined ? {} : { retry: props.retry })}
+        />
+      </div>
+    );
+  }
+  if (query.data === undefined) {
+    return (
+      <div data-pattern="ScreenState" data-state="loading">
+        {props.loading ?? <Skeleton />}
+      </div>
+    );
+  }
+  if (props.emptyState !== undefined && props.isEmpty?.(query.data) === true) {
+    return (
+      <div data-pattern="ScreenState" data-state="empty">
+        <EmptyState {...props.emptyState} />
+      </div>
+    );
+  }
+  return <>{props.children(query.data)}</>;
+}
+
+ScreenState.Skeleton = Skeleton;

package/src/VarianceChart.test.tsx

@@ -0,0 +1,45 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the variance chart (spec ogygie-ui B8): two named series per
+ * label in an SVG whose colours are the product's tokens, the empty state
+ * delegated to the caller, a skeleton for the loading state.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, render, screen } from "@testing-library/react";
+import { VarianceChart, VarianceChartSkeleton } from "./VarianceChart.js";
+
+const ROWS = [
+  { label: "A1", measured: 3.2, reference: 2.8 },
+  { label: "A2", measured: 2.1, reference: 2.8 },
+  { label: "B1", measured: null, reference: 3 },
+];
+
+describe("VarianceChart", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ des lignes et une largeur fixe ALORS un SVG, une barre par série et la légende nommée par le produit", () => {
+    const { container } = render(
+      <VarianceChart rows={ROWS} measuredName="Measured" referenceName="Reference" varianceName="Variance" unit=" pts" width={640} height={240} ariaLabel="Variance by criterion" />,
+    );
+    const figure = container.querySelector("figure[data-pattern='VarianceChart']") as HTMLElement;
+    expect((figure).getAttribute("aria-label")).toBe("Variance by criterion");
+    expect(container.querySelector("svg")).not.toBeNull();
+    expect(container.textContent).toContain("Measured");
+    expect(container.textContent).toContain("Reference");
+    const fills = Array.from(container.querySelectorAll("path, rect")).map((node) => node.getAttribute("fill"));
+    expect(fills).toContain("var(--color-accent)");
+    expect(fills).toContain("var(--color-text-muted)");
+  });
+
+  it("ÉTANT DONNÉ aucune ligne et un emptyState ALORS lui seul se rend", () => {
+    const { container } = render(<VarianceChart rows={[]} measuredName="Measured" referenceName="Reference" varianceName="Variance" emptyState={<p>No target yet</p>} />);
+    expect(screen.getByText("No target yet")).toBeDefined();
+    expect(container.querySelector("svg")).toBeNull();
+  });
+
+  it("le squelette est un status occupé", () => {
+    render(<VarianceChartSkeleton />);
+    expect((screen.getByRole("status")).getAttribute("aria-busy")).toBe("true");
+    expect(VarianceChart.Skeleton).toBe(VarianceChartSkeleton);
+  });
+});

package/src/VarianceChart.tsx

@@ -0,0 +1,148 @@
+/**
+ * @intent The variance chart of the starter (D39): a measured value against
+ * its reference, per label, as two grouped bars — the variance (measured minus
+ * reference) read in the tooltip with its sign — and a zero line when the
+ * values cross it. Colours come from the product's tokens through CSS
+ * variables (`--color-accent`, `--color-text-muted`…), never from a palette of
+ * this file; units and series names are strings the product translates.
+ * Loading and error are the screen's business (ScreenState); the empty state
+ * is delegated to the caller. Recharts is an OPTIONAL peer carried by this
+ * entry point only (`@ogygie/ui/variance-chart`).
+ */
+import type { ReactNode } from "react";
+import { Bar, BarChart, CartesianGrid, Legend, ReferenceLine, ResponsiveContainer, Tooltip, XAxis, YAxis } from "recharts";
+
+export interface VarianceRow {
+  label: string;
+  measured: number | null;
+  reference: number | null;
+}
+
+export interface VarianceChartProps {
+  rows: ReadonlyArray<VarianceRow>;
+  /** Series names, as the legend and the tooltip show them — translated strings. */
+  measuredName: string;
+  referenceName: string;
+  varianceName: string;
+  /** Appended to every figure (`%`, ` pts`, ` €`). */
+  unit?: string;
+  /** How a figure reads. Default: up to two decimals, in the runtime's locale. */
+  format?: (value: number) => string;
+  /** The value axis bounds. Default: Recharts' automatic domain. */
+  domain?: [number, number];
+  height?: number;
+  /** A fixed width renders without a ResponsiveContainer — tests and print. Absent, the chart fills its container. */
+  width?: number;
+  /** The accessible name of the figure, translated. */
+  ariaLabel?: string;
+  /** Rendered INSTEAD of the chart when there is no row. */
+  emptyState?: ReactNode;
+}
+
+const defaultFormat = (value: number): string => value.toLocaleString(undefined, { maximumFractionDigits: 2 });
+
+interface TooltipEntry {
+  payload?: unknown;
+}
+
+function VarianceTooltip(props: {
+  active?: boolean | undefined;
+  payload?: ReadonlyArray<TooltipEntry> | undefined;
+  names: { measured: string; reference: string; variance: string };
+  unit: string;
+  format: (value: number) => string;
+}) {
+  const row = props.payload?.[0]?.payload as VarianceRow | undefined;
+  if (props.active !== true || row === undefined) return null;
+  const variance = row.measured !== null && row.reference !== null ? row.measured - row.reference : null;
+  const figure = (value: number | null): string => (value === null ? "—" : `${props.format(value)}${props.unit}`);
+  return (
+    <div className="rounded-sm border border-border bg-surface-raised px-3 py-2 text-xs text-text shadow-raised">
+      <p className="font-medium">{row.label}</p>
+      <p className="tabular-nums">
+        {props.names.measured}: {figure(row.measured)}
+      </p>
+      <p className="tabular-nums text-text-muted">
+        {props.names.reference}: {figure(row.reference)}
+      </p>
+      <p className={`tabular-nums ${variance === null ? "" : variance < 0 ? "text-danger" : "text-positive"}`}>
+        {props.names.variance}: {variance === null ? "—" : `${variance > 0 ? "+" : ""}${props.format(variance)}${props.unit}`}
+      </p>
+    </div>
+  );
+}
+
+export function VarianceChart(props: VarianceChartProps) {
+  const { rows, height = 240, unit = "", format = defaultFormat } = props;
+  if (rows.length === 0 && props.emptyState !== undefined) return <>{props.emptyState}</>;
+  const names = { measured: props.measuredName, reference: props.referenceName, variance: props.varianceName };
+  const crossesZero = rows.some((row) => (row.measured ?? 0) < 0 || (row.reference ?? 0) < 0);
+  const chart = (
+    <BarChart
+      data={rows.map((row) => ({ ...row }))}
+      margin={{ top: 8, right: 8, bottom: 8, left: 8 }}
+      {...(props.width === undefined ? {} : { width: props.width, height })}
+    >
+      <CartesianGrid vertical={false} stroke="var(--color-border)" />
+      <XAxis dataKey="label" tick={{ fill: "var(--color-text-muted)", fontSize: 12 }} stroke="var(--color-border)" />
+      <YAxis
+        tickFormatter={(value: number) => `${format(value)}${unit}`}
+        tick={{ fill: "var(--color-text-muted)", fontSize: 12 }}
+        stroke="var(--color-border)"
+        width={56}
+        {...(props.domain === undefined ? {} : { domain: props.domain })}
+      />
+      <Tooltip
+        cursor={{ fill: "var(--color-surface)" }}
+        content={(tooltipProps) => (
+          <VarianceTooltip
+            active={tooltipProps.active}
+            payload={tooltipProps.payload as ReadonlyArray<TooltipEntry> | undefined}
+            names={names}
+            unit={unit}
+            format={format}
+          />
+        )}
+      />
+      <Legend wrapperStyle={{ fontSize: 12, color: "var(--color-text-muted)" }} />
+      {crossesZero && <ReferenceLine y={0} stroke="var(--color-text-muted)" />}
+      <Bar dataKey="measured" name={props.measuredName} fill="var(--color-accent)" radius={2} isAnimationActive={false} />
+      <Bar dataKey="reference" name={props.referenceName} fill="var(--color-text-muted)" radius={2} isAnimationActive={false} />
+    </BarChart>
+  );
+  return (
+    <figure
+      data-pattern="VarianceChart"
+      {...(props.ariaLabel === undefined ? {} : { "aria-label": props.ariaLabel })}
+      className="m-0 text-sm text-text"
+      style={{ height }}
+    >
+      {props.width === undefined ? (
+        <ResponsiveContainer width="100%" height={height}>
+          {chart}
+        </ResponsiveContainer>
+      ) : (
+        chart
+      )}
+    </figure>
+  );
+}
+
+/** The loading state of a chart: pulsing bars of uneven height, `role="status"`. */
+export function VarianceChartSkeleton({ height = 240 }: { height?: number }) {
+  return (
+    <div
+      role="status"
+      aria-busy="true"
+      data-pattern="VarianceChart.Skeleton"
+      className="flex animate-pulse items-end gap-3 rounded-md border border-border bg-surface-raised px-6 pb-6 pt-10"
+      style={{ height }}
+    >
+      {[0.6, 0.9, 0.4, 0.75, 0.55].map((ratio, index) => (
+        <div key={index} className="w-full rounded-sm bg-border" style={{ height: `${Math.round(ratio * 100)}%` }} />
+      ))}
+    </div>
+  );
+}
+
+VarianceChart.Skeleton = VarianceChartSkeleton;

package/src/contract-fields.test.ts

@@ -0,0 +1,100 @@
+/**
+ * @intent Proves the field derivation of ContractForm (spec ogygie-ui B6):
+ * each Zod kind yields its control, bounds and options; optional, default and
+ * nullable wrappers are read through; a non-object schema is refused by name;
+ * the controls' raw values come back in the contract's types.
+ */
+import { describe, expect, it } from "vitest";
+import { z } from "zod";
+import { OgygieFailure } from "@ogygie/core/errors";
+import { coerceFormValues, formFieldsOf } from "./contract-fields.js";
+
+const Schema = z
+  .object({
+    label: z.string().trim().min(1).max(80),
+    note: z.string().max(2000).optional(),
+    code: z.string().regex(/^[a-z-]+$/).max(32).meta({ title: "Code", description: "A slug." }),
+    email: z.email(),
+    site: z.url().optional(),
+    effectiveDate: z.iso.date(),
+    recordedAt: z.iso.datetime().nullable(),
+    level: z.number().int().min(1).max(4).nullable(),
+    weight: z.number().positive().default(1),
+    active: z.boolean(),
+    tier: z.enum(["A", "B"]),
+    kind: z.literal("standard").optional(),
+    tags: z.array(z.string()).optional(),
+  })
+  .refine((body) => body.label !== "forbidden");
+
+describe("formFieldsOf", () => {
+  const fields = formFieldsOf(Schema);
+  const field = (name: string) => {
+    const found = fields.find((candidate) => candidate.name === name);
+    if (found === undefined) throw new Error(`no field ${name}`);
+    return found;
+  };
+
+  it("garde l'ordre de la forme et lit à travers le refine", () => {
+    expect(fields.map((candidate) => candidate.name)).toEqual([
+      "label", "note", "code", "email", "site", "effectiveDate", "recordedAt", "level", "weight", "active", "tier", "kind", "tags",
+    ]);
+  });
+
+  it("une chaîne bornée est un text avec ses bornes ; une longue est un textarea", () => {
+    expect(field("label")).toMatchObject({ kind: "text", required: true, minLength: 1, maxLength: 80, nullable: false });
+    expect(field("note")).toMatchObject({ kind: "textarea", required: false, maxLength: 2000 });
+  });
+
+  it("un regex donne le pattern, et le meta donne le titre et la description", () => {
+    expect(field("code")).toMatchObject({ kind: "text", pattern: "^[a-z-]+$", maxLength: 32, title: "Code", description: "A slug." });
+  });
+
+  it("les formats de chaîne choisissent leur contrôle", () => {
+    expect(field("email").kind).toBe("email");
+    expect(field("site")).toMatchObject({ kind: "url", required: false });
+    expect(field("effectiveDate").kind).toBe("date");
+    expect(field("recordedAt")).toMatchObject({ kind: "datetime", nullable: true, required: true });
+  });
+
+  it("un entier borné et nullable, un nombre avec défaut", () => {
+    expect(field("level")).toMatchObject({ kind: "integer", minimum: 1, maximum: 4, nullable: true });
+    expect(field("weight")).toMatchObject({ kind: "number", required: false, defaultValue: 1 });
+    expect(field("weight").minimum).toBeGreaterThan(0);
+  });
+
+  it("booléen, enum et littéral", () => {
+    expect(field("active").kind).toBe("checkbox");
+    expect(field("tier")).toMatchObject({ kind: "select", options: [{ value: "A" }, { value: "B" }] });
+    expect(field("kind")).toMatchObject({ kind: "select", required: false, options: [{ value: "standard" }] });
+  });
+
+  it("une forme que le formulaire ne sait pas rendre est nommée, jamais tue", () => {
+    expect(field("tags")).toMatchObject({ kind: "unsupported", typeName: "array" });
+  });
+
+  it("un schéma qui n'est pas un objet est refusé par son nom", () => {
+    expect(() => formFieldsOf(z.string())).toThrowError(OgygieFailure);
+    try {
+      formFieldsOf(z.array(z.string()));
+    } catch (thrown) {
+      expect((thrown as OgygieFailure).error.code).toBe("CONTRACT_FORM_NOT_AN_OBJECT");
+      expect((thrown as OgygieFailure).error.cause).toContain("array");
+    }
+  });
+});
+
+describe("coerceFormValues", () => {
+  const fields = formFieldsOf(Schema);
+
+  it("un contrôle vide devient undefined pour un optionnel, null pour un nullable, reste vide pour un requis", () => {
+    const values = coerceFormValues(fields, { label: "", note: "", site: "", recordedAt: "", level: Number.NaN, weight: Number.NaN, tier: "", kind: "", active: false });
+    expect(values).toEqual({ label: "", code: "", email: "", effectiveDate: "", recordedAt: null, level: null, active: false });
+  });
+
+  it("les nombres reviennent en nombres, les options gardent leur type, la case à cocher un booléen", () => {
+    const numeric = formFieldsOf(z.object({ level: z.number(), rank: z.enum({ one: 1, two: 2 }), flag: z.boolean() }));
+    expect(coerceFormValues(numeric, { level: "3", rank: "2", flag: "on" })).toEqual({ level: 3, rank: 2, flag: true });
+    expect(coerceFormValues(numeric, { level: 3, rank: "9", flag: true })).toEqual({ level: 3, rank: "9", flag: true });
+  });
+});

package/src/contract-fields.ts

@@ -0,0 +1,274 @@
+/**
+ * @intent What a FORM needs to know about each field of a Zod object contract
+ * (D39, pattern ContractForm): its control kind, whether it is required, its
+ * bounds and its options — read from the schema's public core definition
+ * (`schema._zod.def`, the `zod/v4/core` contract library authors build on),
+ * never redeclared by hand. The schema itself stays the validator: these
+ * descriptors only choose the control and its HTML constraints; `safeParse`
+ * decides. A field the structure cannot render (an object, an array, a union)
+ * is reported `unsupported` and named, never silently dropped.
+ */
+import * as core from "zod/v4/core";
+import { throwOgygieError } from "@ogygie/core/errors";
+
+export type FormFieldKind =
+  | "text"
+  | "textarea"
+  | "email"
+  | "url"
+  | "date"
+  | "datetime"
+  | "number"
+  | "integer"
+  | "checkbox"
+  | "select"
+  | "unsupported";
+
+export interface FormFieldOption {
+  value: string | number;
+}
+
+export interface FormField {
+  name: string;
+  kind: FormFieldKind;
+  /** False when the contract accepts `undefined` (optional) or carries a default. */
+  required: boolean;
+  /** True when the contract accepts `null` — an empty control then sends null, not undefined. */
+  nullable: boolean;
+  minLength: number | null;
+  maxLength: number | null;
+  /** The source of a `.regex()`, for the control's `pattern` attribute. */
+  pattern: string | null;
+  minimum: number | null;
+  maximum: number | null;
+  /** Options of a `select` (enum values, or the literal's values). */
+  options: FormFieldOption[];
+  defaultValue: unknown;
+  /** `.meta({ title, description })` of the field, when declared. */
+  title: string | null;
+  description: string | null;
+  /** The Zod type name — what an `unsupported` message names. */
+  typeName: string;
+}
+
+/** The parts of a core definition this module reads, structurally typed. */
+interface ReadableDef {
+  type: string;
+  innerType?: unknown;
+  in?: unknown;
+  shape?: Record<string, unknown>;
+  entries?: Record<string, string | number>;
+  values?: unknown[];
+  format?: unknown;
+  defaultValue?: unknown;
+  checks?: unknown[];
+}
+
+interface ReadableCheckDef {
+  check: string;
+  format?: unknown;
+  pattern?: unknown;
+  minimum?: unknown;
+  maximum?: unknown;
+  value?: unknown;
+  inclusive?: unknown;
+}
+
+function isZodSchema(candidate: unknown): candidate is core.$ZodType {
+  return typeof candidate === "object" && candidate !== null && "_zod" in candidate;
+}
+
+function defOf(schema: core.$ZodType): ReadableDef {
+  return schema._zod.def as ReadableDef;
+}
+
+function checkDefsOf(def: ReadableDef): ReadableCheckDef[] {
+  const defs: ReadableCheckDef[] = [];
+  for (const check of def.checks ?? []) {
+    if (typeof check === "object" && check !== null && "_zod" in check) {
+      const inner = (check as { _zod: { def: unknown } })._zod.def as ReadableCheckDef;
+      if (typeof inner.check === "string") defs.push(inner);
+    }
+  }
+  return defs;
+}
+
+function metaOf(schema: core.$ZodType): { title: string | null; description: string | null } {
+  const meta = core.globalRegistry.get(schema) as { title?: unknown; description?: unknown } | undefined;
+  return {
+    title: typeof meta?.title === "string" ? meta.title : null,
+    description: typeof meta?.description === "string" ? meta.description : null,
+  };
+}
+
+function asNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** Peels optional / nullable / default / pipe wrappers, collecting what they say. */
+function unwrap(schema: core.$ZodType): {
+  inner: core.$ZodType;
+  required: boolean;
+  nullable: boolean;
+  defaultValue: unknown;
+  title: string | null;
+  description: string | null;
+} {
+  let current = schema;
+  let required = true;
+  let nullable = false;
+  let defaultValue: unknown = undefined;
+  let { title, description } = metaOf(current);
+  for (;;) {
+    const def = defOf(current);
+    const next = def.type === "pipe" ? def.in : def.innerType;
+    if (def.type === "optional") required = false;
+    if (def.type === "nullable") nullable = true;
+    if (def.type === "default") {
+      required = false;
+      defaultValue = typeof def.defaultValue === "function" ? (def.defaultValue as () => unknown)() : def.defaultValue;
+    }
+    if (!["optional", "nullable", "default", "pipe", "nonoptional", "readonly"].includes(def.type) || !isZodSchema(next)) break;
+    current = next;
+    const meta = metaOf(current);
+    title ??= meta.title;
+    description ??= meta.description;
+  }
+  return { inner: current, required, nullable, defaultValue, title, description };
+}
+
+function fieldOf(name: string, schema: core.$ZodType): FormField {
+  const { inner, required, nullable, defaultValue, title, description } = unwrap(schema);
+  const def = defOf(inner);
+  const base: FormField = {
+    name,
+    kind: "unsupported",
+    required,
+    nullable,
+    minLength: null,
+    maxLength: null,
+    pattern: null,
+    minimum: null,
+    maximum: null,
+    options: [],
+    defaultValue,
+    title,
+    description,
+    typeName: def.type,
+  };
+  switch (def.type) {
+    case "string": {
+      const field: FormField = { ...base, kind: "text" };
+      const format = typeof def.format === "string" ? def.format : null;
+      if (format === "email") field.kind = "email";
+      else if (format === "url") field.kind = "url";
+      else if (format === "date") field.kind = "date";
+      else if (format === "datetime") field.kind = "datetime";
+      for (const check of checkDefsOf(def)) {
+        if (check.check === "min_length") field.minLength = asNumber(check.minimum);
+        if (check.check === "max_length") field.maxLength = asNumber(check.maximum);
+        if (check.check === "length_equals") {
+          field.minLength = asNumber(check.minimum) ?? field.minLength;
+          field.maxLength = asNumber(check.maximum) ?? field.maxLength;
+        }
+        if (check.check === "string_format" && check.format === "regex" && check.pattern instanceof RegExp) {
+          field.pattern = check.pattern.source;
+        }
+      }
+      // A long text reads in a textarea; a bounded short one in an input.
+      if (field.kind === "text" && field.maxLength !== null && field.maxLength > 160) field.kind = "textarea";
+      return field;
+    }
+    case "number": {
+      const field: FormField = { ...base, kind: "number" };
+      if (typeof def.format === "string" && def.format.includes("int")) field.kind = "integer";
+      for (const check of checkDefsOf(def)) {
+        if (check.check === "number_format" && typeof check.format === "string" && check.format.includes("int")) field.kind = "integer";
+        if (check.check === "greater_than") {
+          const bound = asNumber(check.value);
+          field.minimum = bound === null ? null : check.inclusive === true ? bound : bound + (field.kind === "integer" ? 1 : Number.EPSILON);
+        }
+        if (check.check === "less_than") {
+          const bound = asNumber(check.value);
+          field.maximum = bound === null ? null : check.inclusive === true ? bound : bound - (field.kind === "integer" ? 1 : Number.EPSILON);
+        }
+      }
+      return field;
+    }
+    case "boolean":
+      return { ...base, kind: "checkbox" };
+    case "enum":
+      return {
+        ...base,
+        kind: "select",
+        options: Object.values(def.entries ?? {}).map((value) => ({ value })),
+      };
+    case "literal":
+      return {
+        ...base,
+        kind: "select",
+        options: (def.values ?? [])
+          .filter((value): value is string | number => typeof value === "string" || typeof value === "number")
+          .map((value) => ({ value })),
+      };
+    default:
+      return base;
+  }
+}
+
+/** The fields of an object contract, in the order its shape declares them. Refused when the schema is not an object. */
+export function formFieldsOf(schema: core.$ZodType): FormField[] {
+  const { inner } = unwrap(schema);
+  const def = defOf(inner);
+  if (def.type !== "object" || def.shape === undefined) {
+    throwOgygieError(
+      {
+        code: "CONTRACT_FORM_NOT_AN_OBJECT",
+        message: "ContractForm derives its fields from an object schema.",
+        file: null,
+        cause: `the schema given is a "${def.type}"`,
+        suggestedFix: "Pass the z.object() input schema of the route (CreateXInputSchema), not a field or a union.",
+      },
+      500,
+    );
+  }
+  return Object.entries(def.shape)
+    .filter((entry): entry is [string, core.$ZodType] => isZodSchema(entry[1]))
+    .map(([name, fieldSchema]) => fieldOf(name, fieldSchema));
+}
+
+/**
+ * What the controls hand back, turned into what the contract expects: an
+ * empty control is `undefined` for an optional field, `null` for a nullable
+ * one, kept as is for a required one (the schema then says what is missing);
+ * numbers come back as numbers, select options keep their declared type.
+ */
+export function coerceFormValues(fields: ReadonlyArray<FormField>, raw: Record<string, unknown>): Record<string, unknown> {
+  const values: Record<string, unknown> = {};
+  for (const field of fields) {
+    const given = raw[field.name];
+    if (field.kind === "checkbox") {
+      values[field.name] = given === true || given === "on" || given === "true";
+      continue;
+    }
+    const isBlank = given === undefined || given === null || given === "" || (typeof given === "number" && Number.isNaN(given));
+    if (isBlank) {
+      if (field.nullable) values[field.name] = null;
+      else if (!field.required) continue;
+      else if (field.kind === "number" || field.kind === "integer" || field.kind === "select") continue;
+      else values[field.name] = "";
+      continue;
+    }
+    if ((field.kind === "number" || field.kind === "integer") && typeof given === "string") {
+      values[field.name] = Number(given);
+      continue;
+    }
+    if (field.kind === "select" && typeof given === "string") {
+      const option = field.options.find((candidate) => String(candidate.value) === given);
+      values[field.name] = option === undefined ? given : option.value;
+      continue;
+    }
+    values[field.name] = given;
+  }
+  return values;
+}