@ogygie/ui 0.0.0-stage → 0.16.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 x10sion LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,61 @@
-# Temporary Holding Version
+# @ogygie/ui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Le socle front du framework **Ogygie** (DECISIONS.md D39) : les briques
+d'écran que le starter prescrivait sans les livrer. Un produit les IMPORTE ;
+il ne les recopie plus dans `apps/web/src/patterns/`, qui ne garde que ses
+patterns propres. Le paquet livre ses sources TypeScript (comme `@ogygie/core`)
+et ne porte **aucune chaîne lue par un humain** : tout texte lui arrive en
+prop, traduit par la feature (Lingui).
+
+| Point d'entrée | Ce qu'il porte | Peer |
+|---|---|---|
+| `@ogygie/ui` | `ScreenState` (accès refusé → erreur → chargement → vide → corps), `EmptyState`, `ErrorBanner`, `EditableText`, `Skeleton`, `fetchContract` / `createContractFetcher`, `QueryLike` / `MutationLike` et leurs fixtures | `react`, `zod` (`@ogygie/core` est une DÉPENDANCE, à la version du lockstep) |
+| `@ogygie/ui/data-table` | `DataTable` (colonnes typées, tri, chiffres alignés) + `DataTable.Skeleton` | `@tanstack/react-table` (optionnel) |
+| `@ogygie/ui/contract-form` | `ContractForm` (formulaire dérivé d'un contrat Zod) + `formFieldsOf` | `react-hook-form` (optionnel) |
+| `@ogygie/ui/variance-chart` | `VarianceChart` (constaté contre référence) + `VarianceChart.Skeleton` | `recharts` (optionnel) |
+
+## Thème
+
+Les composants portent les utilitaires Tailwind des tokens du starter
+(`surface`, `surface-raised`, `border`, `text`, `text-muted`, `accent`,
+`accent-contrast`, `positive`, `warning`, `danger`, `focus`, les rayons
+`sm`/`md`/`lg`). La feuille Tailwind du produit déclare le paquet comme
+source, sinon ces classes ne sont pas générées :
+
+```css
+@import "tailwindcss";
+@source "../node_modules/@ogygie/ui/src";
+```
+
+Les couleurs du graphique passent par les variables CSS du thème
+(`--color-accent`, `--color-text-muted`, `--color-border`).
+
+## Un écran
+
+```tsx
+import { ScreenState } from "@ogygie/ui";
+import { DataTable } from "@ogygie/ui/data-table";
+
+export function OrdersList() {
+  return (
+    <ScreenState
+      query={useOrders()}
+      errorTitle={<Trans>This view could not be loaded</Trans>}
+      loading={<DataTable.Skeleton />}
+      isEmpty={(data) => data.orders.length === 0}
+      emptyState={{ title: <Trans>No order yet</Trans>, explanation: <Trans>Orders appear here once recorded.</Trans> }}
+    >
+      {(data) => <DataTable rows={data.orders} columns={orderColumns} rowKey={(order) => order.id} />}
+    </ScreenState>
+  );
+}
+```
+
+Le corps d'un écran reçoit des `QueryLike` et des `MutationLike`, jamais un
+hook : il se teste en rendu, sans client de requêtes ni réseau.
+
+## Tests
+
+Les tests du paquet tournent sous jsdom (`@testing-library/react`), un par
+état de chaque pattern : `pnpm vitest run packages/ogygie-ui` depuis le repo
+du framework.

package/package.json

@@ -1,6 +1,62 @@
 {
   "name": "@ogygie/ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.16.0",
+  "description": "Ogygie front socle: the five prescribed patterns (DataTable, EmptyState, ErrorBanner, ContractForm, VarianceChart), one screen-state component (ScreenState), fetchContract and EditableText. Ships TypeScript sources — Ogygie products run Vite/tsx/vitest by construction (D1); a product imports them, it no longer copies them (D39).",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./data-table": "./src/DataTable.tsx",
+    "./contract-form": "./src/ContractForm.tsx",
+    "./variance-chart": "./src/VarianceChart.tsx"
+  },
+  "dependencies": {
+    "@ogygie/core": "0.16.0"
+  },
+  "peerDependencies": {
+    "@tanstack/react-table": "^9.0.0",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-hook-form": "^7.60.0",
+    "recharts": "^2.15.0 || ^3.0.0",
+    "zod": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@tanstack/react-table": {
+      "optional": true
+    },
+    "react-hook-form": {
+      "optional": true
+    },
+    "recharts": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@tanstack/react-table": "9.2.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.2",
+    "@types/node": "^24.13.3",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "react-hook-form": "^7.90.0",
+    "recharts": "^3.10.1",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.7",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json"
+  }
 }

package/src/CharacterCount.tsx

@@ -0,0 +1,17 @@
+/**
+ * @intent How much of a bounded field is used, `12 / 80`, turning to the
+ * warning colour at the bound — figures only, nothing to translate. Rendered
+ * by EditableText and ContractForm next to a field whose contract declares a
+ * maximum length (D39).
+ */
+export function CharacterCount({ length, max }: { length: number; max: number }) {
+  return (
+    <span
+      role="status"
+      data-pattern="CharacterCount"
+      className={`ml-2 text-xs tabular-nums ${length >= max ? "text-warning" : "text-text-muted"}`}
+    >
+      {length} / {max}
+    </span>
+  );
+}

package/src/ContractForm.test.tsx

@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the contract-derived form (spec ogygie-ui B6): controls from
+ * the schema, labels and option labels from the product, a refused submission
+ * showing one sentence per faulty field and calling nothing, an accepted one
+ * handing the PARSED output over, the pending and server-refusal states, the
+ * form-level issue of a refine.
+ */
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { z } from "zod";
+import { OgygieFailure, ogygieError } from "@ogygie/core/errors";
+import { ContractForm } from "./ContractForm.js";
+
+const CreateInputSchema = z.object({
+  label: z.string().trim().min(1).max(80),
+  horizon: z.string().regex(/^2\d{3}-Q[1-4]$/, "expected a quarter such as 2027-Q2"),
+  level: z.number().int().min(1).max(4).nullable(),
+  tier: z.enum(["A", "B"]),
+  active: z.boolean(),
+  weight: z.number().positive().default(1),
+});
+
+const labels = { label: "Name", horizon: "Target quarter", level: "Level", tier: "Tier", active: "Active", weight: "Weight" };
+
+describe("ContractForm", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ le contrat ALORS un contrôle par champ, du bon type, avec son libellé et sa marque de requis", () => {
+    render(<ContractForm schema={CreateInputSchema} onSubmit={() => undefined} submitLabel="Create" labels={labels} optionLabels={{ tier: { A: "Tier A", B: "Tier B" } }} />);
+    expect((screen.getByLabelText(/Name/)).getAttribute("type")).toBe("text");
+    expect((screen.getByLabelText(/Name/)).getAttribute("maxlength")).toBe("80");
+    expect((screen.getByLabelText(/Target quarter/)).getAttribute("pattern")).toBe("^2\\d{3}-Q[1-4]$");
+    const level = screen.getByLabelText(/Level/);
+    expect((level).getAttribute("type")).toBe("number");
+    expect((level).getAttribute("min")).toBe("1");
+    expect((level).getAttribute("max")).toBe("4");
+    expect((level).getAttribute("step")).toBe("1");
+    expect(screen.getByLabelText(/Tier/).tagName).toBe("SELECT");
+    expect(screen.getByRole("option", { name: "Tier B" })).toBeDefined();
+    expect((screen.getByLabelText("Active")).getAttribute("type")).toBe("checkbox");
+    expect(screen.getByLabelText(/Name/).closest("[data-field]")?.textContent).toContain("*");
+    expect(screen.getByLabelText(/Weight/).closest("[data-field]")?.textContent).not.toContain("*");
+    expect(screen.getByRole("button", { name: "Create" })).toBeDefined();
+  });
+
+  it("QUAND la soumission viole le contrat ALORS une phrase par champ fautif, et rien n'est envoyé", async () => {
+    const onSubmit = vi.fn();
+    render(<ContractForm schema={CreateInputSchema} onSubmit={onSubmit} submitLabel="Create" labels={labels} />);
+    fireEvent.change(screen.getByLabelText(/Target quarter/), { target: { value: "soon" } });
+    fireEvent.submit(screen.getByRole("button", { name: "Create" }).closest("form") as HTMLFormElement);
+    const alerts = await screen.findAllByRole("alert");
+    expect(alerts.map((alert) => alert.textContent)).toContain("expected a quarter such as 2027-Q2");
+    expect((screen.getByLabelText(/Target quarter/)).getAttribute("aria-invalid")).toBe("true");
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("QUAND la soumission respecte le contrat ALORS onSubmit reçoit la sortie parsée (nombres, null, défauts)", async () => {
+    const onSubmit = vi.fn();
+    render(<ContractForm schema={CreateInputSchema} onSubmit={onSubmit} submitLabel="Create" labels={labels} />);
+    fireEvent.change(screen.getByLabelText(/Name/), { target: { value: "  First grade " } });
+    fireEvent.change(screen.getByLabelText(/Target quarter/), { target: { value: "2027-Q2" } });
+    fireEvent.change(screen.getByLabelText(/Tier/), { target: { value: "B" } });
+    fireEvent.click(screen.getByLabelText("Active"));
+    fireEvent.submit(screen.getByRole("button", { name: "Create" }).closest("form") as HTMLFormElement);
+    await waitFor(() => expect(onSubmit).toHaveBeenCalledTimes(1));
+    expect(onSubmit).toHaveBeenCalledWith({ label: "First grade", horizon: "2027-Q2", level: null, tier: "B", active: true, weight: 1 });
+  });
+
+  it("ÉTANT DONNÉ renderIssue ALORS le produit traduit la phrase d'un champ", async () => {
+    render(
+      <ContractForm
+        schema={CreateInputSchema}
+        onSubmit={() => undefined}
+        submitLabel="Create"
+        labels={labels}
+        renderIssue={(issue, field) => `${field?.name ?? "form"}: ${issue.code}`}
+      />,
+    );
+    fireEvent.submit(screen.getByRole("button", { name: "Create" }).closest("form") as HTMLFormElement);
+    const alerts = await screen.findAllByRole("alert");
+    expect(alerts.map((alert) => alert.textContent)).toContain("label: too_small");
+  });
+
+  it("ÉTANT DONNÉ un refine sur l'objet ALORS la phrase se lit au niveau du formulaire", async () => {
+    const UpdateSchema = z
+      .object({ label: z.string().optional(), horizon: z.string().optional() })
+      .refine((body) => Object.values(body).some((value) => value !== undefined), { message: "at least one field must be sent" });
+    const onSubmit = vi.fn();
+    render(<ContractForm schema={UpdateSchema} onSubmit={onSubmit} submitLabel="Save" />);
+    fireEvent.submit(screen.getByRole("button", { name: "Save" }).closest("form") as HTMLFormElement);
+    expect((await screen.findAllByRole("alert")).map((alert) => alert.textContent)).toContain("at least one field must be sent");
+    expect(onSubmit).not.toHaveBeenCalled();
+  });
+
+  it("ÉTANT DONNÉ pending ALORS le bouton est inactif ; ÉTANT DONNÉ error ALORS un bandeau save au-dessus des actions", () => {
+    const refusal = new OgygieFailure(ogygieError({ code: "GRADE_CODE_ALREADY_USED", message: "This code is already used.", file: null, cause: "first-grade", suggestedFix: "Pick another label." }), 409);
+    render(<ContractForm schema={CreateInputSchema} onSubmit={() => undefined} submitLabel="Create" labels={labels} pending error={refusal} errorTitle="This change could not be saved" />);
+    expect((screen.getByRole("button", { name: "Create" }) as HTMLButtonElement).disabled).toBe(true);
+    expect((screen.getByRole("alert")).getAttribute("data-code")).toBe("GRADE_CODE_ALREADY_USED");
+    expect((screen.getByRole("alert")).getAttribute("data-kind")).toBe("save");
+  });
+
+  it("ÉTANT DONNÉ fields ALORS seuls ces champs se montrent, dans cet ordre, et un cancel est un bouton", () => {
+    const onCancel = vi.fn();
+    render(<ContractForm schema={CreateInputSchema} onSubmit={() => undefined} submitLabel="Create" labels={labels} fields={["horizon", "label"]} cancel={{ label: "Cancel", onClick: onCancel }} />);
+    const shown = Array.from(document.querySelectorAll("[data-field]")).map((node) => node.getAttribute("data-field"));
+    expect(shown).toEqual(["horizon", "label"]);
+    fireEvent.click(screen.getByRole("button", { name: "Cancel" }));
+    expect(onCancel).toHaveBeenCalledTimes(1);
+  });
+
+  it("ÉTANT DONNÉ resetOnSubmit ALORS le formulaire se vide après une soumission acceptée", async () => {
+    const Simple = z.object({ label: z.string().min(1) });
+    render(<ContractForm schema={Simple} onSubmit={() => undefined} submitLabel="Create" resetOnSubmit />);
+    const input = screen.getByLabelText(/label/);
+    fireEvent.change(input, { target: { value: "Grade" } });
+    fireEvent.submit(screen.getByRole("button", { name: "Create" }).closest("form") as HTMLFormElement);
+    await waitFor(() => expect((input as HTMLInputElement).value).toBe(""));
+  });
+});

package/src/ContractForm.tsx

@@ -0,0 +1,269 @@
+/**
+ * @intent A form DERIVED from a Zod contract (D39): the fields come from the
+ * schema's shape, their controls from their kinds, their constraints from the
+ * schema's own bounds — nothing is redeclared by hand — and the schema itself
+ * validates every submission (`safeParse`, through a react-hook-form resolver
+ * written here, no extra dependency). States: typing, submitting (button
+ * inactive), field errors (one sentence under the field, from the Zod issue,
+ * translated by the product through `renderIssue`), server refusal (an
+ * ErrorBanner `kind: save` above the actions). Every text is a prop: labels,
+ * hints, option labels, the submit and cancel labels. react-hook-form is an
+ * OPTIONAL peer carried by this entry point only (`@ogygie/ui/contract-form`).
+ */
+import { useId, useMemo, useRef, type ReactNode } from "react";
+import { useForm, type FieldErrors, type Resolver } from "react-hook-form";
+import type { z } from "zod";
+import type { $ZodIssue } from "zod/v4/core";
+import { CharacterCount } from "./CharacterCount.js";
+import { ErrorBanner } from "./ErrorBanner.js";
+import { coerceFormValues, formFieldsOf, type FormField } from "./contract-fields.js";
+
+type FormValues = Record<string, unknown>;
+
+export interface ContractFormProps<TSchema extends z.ZodType<Record<string, unknown>, Record<string, unknown>>> {
+  schema: TSchema;
+  /** Receives the PARSED output of the contract — defaults applied, transforms run. */
+  onSubmit: (values: z.output<TSchema>) => void | Promise<void>;
+  submitLabel: ReactNode;
+  defaultValues?: Partial<z.input<TSchema>>;
+  /** The label of each field, translated. A field without one shows its name. */
+  labels?: Partial<Record<keyof z.input<TSchema> & string, ReactNode>>;
+  /** A sentence under a field. */
+  hints?: Partial<Record<keyof z.input<TSchema> & string, ReactNode>>;
+  /** The label of each option of a `select` field, by option value. */
+  optionLabels?: Partial<Record<keyof z.input<TSchema> & string, Record<string, ReactNode>>>;
+  /** Which fields to show, in which order. Default: every field of the shape, in its order. A hidden field still validates (its default value is sent). */
+  fields?: ReadonlyArray<keyof z.input<TSchema> & string>;
+  /** The write in flight outside the form (a mutation): the submit stays inactive. */
+  pending?: boolean;
+  /** The server's refusal, shown as a `save` banner above the actions. */
+  error?: unknown;
+  errorTitle?: ReactNode;
+  cancel?: { label: ReactNode; onClick: () => void };
+  /** The sentence for a Zod issue. Default: the issue's own message. */
+  renderIssue?: (issue: $ZodIssue, field: FormField | null) => ReactNode;
+  /** Empties the form after a submission the contract accepted. */
+  resetOnSubmit?: boolean;
+  /** Focus the first field when the form appears. */
+  autoFocus?: boolean;
+  id?: string;
+}
+
+const CONTROL_CLASS =
+  "w-full rounded-sm border bg-surface-raised px-2 py-1.5 text-sm text-text outline-none focus:border-focus";
+
+function controlClassOf(invalid: boolean): string {
+  return `${CONTROL_CLASS} ${invalid ? "border-danger" : "border-border"}`;
+}
+
+export function ContractForm<TSchema extends z.ZodType<Record<string, unknown>, Record<string, unknown>>>(
+  props: ContractFormProps<TSchema>,
+) {
+  const { schema, pending = false, resetOnSubmit = false, autoFocus = false } = props;
+  const generatedId = useId();
+  const formId = props.id ?? generatedId;
+  const allFields = useMemo(() => formFieldsOf(schema), [schema]);
+  const shownNames = props.fields;
+  const fields = useMemo(
+    () =>
+      shownNames === undefined
+        ? allFields
+        : shownNames.flatMap((name) => allFields.filter((field) => field.name === name)),
+    [allFields, shownNames],
+  );
+  // The issues of the last validation, by field — what the error sentences render from.
+  const issuesRef = useRef<Map<string, $ZodIssue>>(new Map());
+
+  const resolver: Resolver<FormValues, unknown, FormValues> = (raw) => {
+    const values = coerceFormValues(allFields, raw);
+    const parsed = schema.safeParse(values);
+    if (parsed.success) {
+      issuesRef.current = new Map();
+      return { values: parsed.data, errors: {} };
+    }
+    const errors: FieldErrors<FormValues> = {};
+    const issues = new Map<string, $ZodIssue>();
+    for (const issue of parsed.error.issues) {
+      const key = typeof issue.path[0] === "string" ? issue.path[0] : "root";
+      if (issues.has(key)) continue;
+      issues.set(key, issue);
+      errors[key] = { type: issue.code, message: issue.message };
+    }
+    issuesRef.current = issues;
+    return { values: {}, errors };
+  };
+
+  const initialValues: FormValues = {};
+  for (const field of allFields) {
+    const given = (props.defaultValues as Record<string, unknown> | undefined)?.[field.name];
+    initialValues[field.name] = given ?? field.defaultValue ?? (field.kind === "checkbox" ? false : "");
+  }
+
+  const form = useForm<FormValues, unknown, FormValues>({ resolver, defaultValues: initialValues, mode: "onTouched" });
+  const { register, handleSubmit, formState, reset, watch } = form;
+  const renderIssue = props.renderIssue ?? ((issue: $ZodIssue) => issue.message);
+  const rootIssue = issuesRef.current.get("root");
+  const busy = formState.isSubmitting || pending;
+
+  const submit = handleSubmit(async (values) => {
+    await props.onSubmit(values as z.output<TSchema>);
+    if (resetOnSubmit) reset(initialValues);
+  });
+
+  return (
+    <form
+      id={formId}
+      data-pattern="ContractForm"
+      noValidate
+      aria-busy={busy ? "true" : undefined}
+      onSubmit={(event) => {
+        void submit(event);
+      }}
+      className="flex flex-col gap-4"
+    >
+      {fields.map((field, index) => {
+        const inputId = `${formId}-${field.name}`;
+        const fieldError = formState.errors[field.name];
+        const issue = issuesRef.current.get(field.name);
+        const invalid = fieldError !== undefined;
+        const hint = props.hints?.[field.name as keyof z.input<TSchema> & string];
+        const describedBy = [hint === undefined ? null : `${inputId}-hint`, invalid ? `${inputId}-error` : null]
+          .filter((part): part is string => part !== null)
+          .join(" ");
+        const label = props.labels?.[field.name as keyof z.input<TSchema> & string] ?? field.title ?? field.name;
+        const shared = {
+          id: inputId,
+          "aria-invalid": invalid ? true : undefined,
+          "aria-describedby": describedBy === "" ? undefined : describedBy,
+          disabled: busy,
+          autoFocus: autoFocus && index === 0,
+        };
+        let control: ReactNode;
+        switch (field.kind) {
+          case "checkbox":
+            control = (
+              <input type="checkbox" {...shared} {...register(field.name)} className="h-4 w-4 rounded-sm border-border accent-accent" />
+            );
+            break;
+          case "select": {
+            const optionLabels = props.optionLabels?.[field.name as keyof z.input<TSchema> & string];
+            control = (
+              <select {...shared} {...register(field.name)} className={controlClassOf(invalid)}>
+                <option value="">{""}</option>
+                {field.options.map((option) => (
+                  <option key={String(option.value)} value={String(option.value)}>
+                    {optionLabels?.[String(option.value)] ?? String(option.value)}
+                  </option>
+                ))}
+              </select>
+            );
+            break;
+          }
+          case "textarea": {
+            const length = String(watch(field.name) ?? "").length;
+            control = (
+              <>
+                <textarea
+                  {...shared}
+                  {...register(field.name)}
+                  rows={4}
+                  {...(field.maxLength === null ? {} : { maxLength: field.maxLength })}
+                  className={controlClassOf(invalid)}
+                />
+                {field.maxLength !== null && <CharacterCount length={length} max={field.maxLength} />}
+              </>
+            );
+            break;
+          }
+          case "number":
+          case "integer":
+            control = (
+              <input
+                type="number"
+                {...shared}
+                {...register(field.name, { valueAsNumber: true })}
+                {...(field.minimum === null ? {} : { min: field.minimum })}
+                {...(field.maximum === null ? {} : { max: field.maximum })}
+                step={field.kind === "integer" ? 1 : "any"}
+                className={`${controlClassOf(invalid)} text-right tabular-nums`}
+              />
+            );
+            break;
+          case "unsupported":
+            control = (
+              <p className="text-xs text-warning" data-unsupported={field.typeName}>
+                {field.name}: {field.typeName}
+              </p>
+            );
+            break;
+          default: {
+            const type =
+              field.kind === "email" ? "email" : field.kind === "url" ? "url" : field.kind === "date" ? "date" : field.kind === "datetime" ? "datetime-local" : "text";
+            control = (
+              <input
+                type={type}
+                {...shared}
+                {...register(field.name)}
+                {...(field.maxLength === null ? {} : { maxLength: field.maxLength })}
+                {...(field.pattern === null ? {} : { pattern: field.pattern })}
+                className={controlClassOf(invalid)}
+              />
+            );
+          }
+        }
+        return (
+          <div key={field.name} data-field={field.name} className="flex flex-col gap-1">
+            <label htmlFor={inputId} className="text-sm font-medium text-text">
+              {label}
+              {field.required && field.kind !== "checkbox" && (
+                <span aria-hidden="true" className="text-danger">
+                  {" *"}
+                </span>
+              )}
+            </label>
+            {control}
+            {hint !== undefined && (
+              <p id={`${inputId}-hint`} className="text-xs text-text-muted">
+                {hint}
+              </p>
+            )}
+            {invalid && (
+              <p id={`${inputId}-error`} role="alert" className="text-xs text-danger">
+                {issue === undefined ? fieldError.message : renderIssue(issue, field)}
+              </p>
+            )}
+          </div>
+        );
+      })}
+      {rootIssue !== undefined && (
+        <p role="alert" className="text-xs text-danger">
+          {renderIssue(rootIssue, null)}
+        </p>
+      )}
+      {props.error != null && (
+        <ErrorBanner error={props.error} kind="save" {...(props.errorTitle === undefined ? {} : { title: props.errorTitle })} />
+      )}
+      <div className="flex items-center gap-3">
+        <button
+          type="submit"
+          disabled={busy}
+          className="rounded-sm bg-accent px-4 py-1.5 text-sm font-medium text-accent-contrast hover:opacity-90 disabled:opacity-60"
+        >
+          {props.submitLabel}
+        </button>
+        {props.cancel !== undefined && (
+          <button
+            type="button"
+            onClick={props.cancel.onClick}
+            disabled={formState.isSubmitting}
+            className="rounded-sm border border-border bg-surface px-4 py-1.5 text-sm font-medium text-text hover:bg-surface-raised"
+          >
+            {props.cancel.label}
+          </button>
+        )}
+      </div>
+    </form>
+  );
+}
+
+export { formFieldsOf, coerceFormValues, type FormField, type FormFieldKind, type FormFieldOption } from "./contract-fields.js";

package/src/DataTable.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+/**
+ * @intent Proves the data table (spec ogygie-ui B7): headers and cells from
+ * typed columns, sorting toggled on a header with its aria-sort, figures
+ * right-aligned, the empty state delegated to the caller, a skeleton for the
+ * loading state.
+ */
+import { afterEach, describe, expect, it } from "vitest";
+import { cleanup, fireEvent, render, screen, within } from "@testing-library/react";
+import { DataTable, DataTableSkeleton, type DataTableColumn } from "./DataTable.js";
+
+interface Row {
+  code: string;
+  label: string;
+  overall: number | null;
+}
+
+const ROWS: Row[] = [
+  { code: "second-grade", label: "Second grade", overall: 2.5 },
+  { code: "first-grade", label: "First grade", overall: 3.2 },
+  { code: "third-grade", label: "Third grade", overall: null },
+];
+
+const COLUMNS: DataTableColumn<Row>[] = [
+  { id: "label", header: "Label", cell: (row) => row.label, sortValue: (row) => row.label },
+  { id: "overall", header: "Overall", cell: (row) => (row.overall === null ? "—" : row.overall.toFixed(1)), sortValue: (row) => row.overall, align: "end" },
+  { id: "actions", header: "Actions", cell: (row) => <button type="button">{`Delete ${row.code}`}</button> },
+];
+
+const bodyLabels = (): string[] =>
+  within(screen.getByRole("table")).getAllByRole("row").slice(1).map((row) => within(row).getAllByRole("cell")[0]?.textContent ?? "");
+
+describe("DataTable", () => {
+  afterEach(cleanup);
+
+  it("ÉTANT DONNÉ des colonnes typées ALORS en-têtes et cellules, dans l'ordre servi", () => {
+    render(<DataTable rows={ROWS} columns={COLUMNS} rowKey={(row) => row.code} caption="Grades" />);
+    expect(screen.getAllByRole("columnheader").map((header) => header.textContent?.replace(/[▲▼⇅]/g, ""))).toEqual(["Label", "Overall", "Actions"]);
+    expect(bodyLabels()).toEqual(["Second grade", "First grade", "Third grade"]);
+    expect(screen.getByRole("button", { name: "Delete first-grade" })).toBeDefined();
+    expect(screen.getByRole("table").querySelector("caption")?.textContent).toBe("Grades");
+  });
+
+  it("QUAND un en-tête triable est cliqué ALORS les lignes se trient et aria-sort le dit ; un second clic inverse", () => {
+    render(<DataTable rows={ROWS} columns={COLUMNS} rowKey={(row) => row.code} />);
+    const labelHeader = screen.getAllByRole("columnheader")[0] as HTMLElement;
+    fireEvent.click(within(labelHeader).getByRole("button"));
+    expect((labelHeader).getAttribute("aria-sort")).toBe("ascending");
+    expect(bodyLabels()).toEqual(["First grade", "Second grade", "Third grade"]);
+    fireEvent.click(within(labelHeader).getByRole("button"));
+    expect((labelHeader).getAttribute("aria-sort")).toBe("descending");
+    expect(bodyLabels()).toEqual(["Third grade", "Second grade", "First grade"]);
+  });
+
+  it("ÉTANT DONNÉ un tri initial sur une colonne de chiffres ALORS les vides vont à la fin, et la colonne est alignée à droite", () => {
+    render(<DataTable rows={ROWS} columns={COLUMNS} rowKey={(row) => row.code} initialSort={{ id: "overall", desc: true }} />);
+    expect(bodyLabels()).toEqual(["First grade", "Second grade", "Third grade"]);
+    const overallCell = within(screen.getAllByRole("row")[1] as HTMLElement).getAllByRole("cell")[1];
+    expect(overallCell?.className).toContain("tabular-nums");
+    expect(overallCell?.className).toContain("text-right");
+  });
+
+  it("ÉTANT DONNÉ une colonne sans sortValue ALORS son en-tête n'est pas un bouton", () => {
+    render(<DataTable rows={ROWS} columns={COLUMNS} rowKey={(row) => row.code} />);
+    const actionsHeader = screen.getAllByRole("columnheader")[2] as HTMLElement;
+    expect(within(actionsHeader).queryByRole("button")).toBeNull();
+    expect((actionsHeader).hasAttribute("aria-sort")).toBe(false);
+  });
+
+  it("ÉTANT DONNÉ aucune ligne et un emptyState ALORS lui seul se rend ; sans lui, les en-têtes seuls", () => {
+    const { rerender } = render(<DataTable rows={[]} columns={COLUMNS} rowKey={(row) => row.code} emptyState={<p>No grade yet</p>} />);
+    expect(screen.getByText("No grade yet")).toBeDefined();
+    expect(screen.queryByRole("table")).toBeNull();
+    rerender(<DataTable rows={[]} columns={COLUMNS} rowKey={(row) => row.code} />);
+    expect(screen.getAllByRole("columnheader")).toHaveLength(3);
+    expect(screen.getAllByRole("row")).toHaveLength(1);
+  });
+
+  it("le squelette est un status occupé", () => {
+    render(<DataTableSkeleton rows={2} />);
+    expect((screen.getByRole("status")).getAttribute("aria-busy")).toBe("true");
+    expect(DataTable.Skeleton).toBe(DataTableSkeleton);
+  });
+});