@cosmicdrift/kumiko-headless 0.327.0 → 0.328.1

package/src/form/types.ts

@@ -1,297 +0,0 @@
-import type { ZodType } from "zod";
-import type { Dispatcher, FieldIssue, WriteResult } from "../dispatcher";
-
-// Form-Controller contract.
-//
-// One controller per edit/create screen. Wraps a mutable "values" record
-// plus derived state (changes vs initial, per-field errors) and exposes a
-// subscribe API shaped for React's `useSyncExternalStore`. The framework's
-// renderer-react wraps this in a thin `useForm` hook; the mobile renderer
-// will do the same with the same controller.
-//
-// Why not just Zustand / a state library?
-// Form state has a small, well-defined shape — values, initial, changes,
-// errors, per-field meta. Building it on raw subscribe/emit keeps the
-// runtime deps at zero (this package imports nothing but types from
-// @cosmicdrift/kumiko-framework and zod), and leaves renderer-specific decisions
-// (batching, suspense) to the host framework.
-//
-// Snapshot identity: `getSnapshot()` returns the SAME reference until a
-// mutator (setField / setValues / reset / ...) runs. React compares by
-// identity when deciding whether to re-render — recomputing the snapshot
-// on every call would re-render on every tick. Mutators rebuild the
-// snapshot once, then notify listeners.
-
-export type FormValues = Record<string, unknown>;
-
-// Per-field conditional rules (Kumiko's "visible/readonly/required as
-// functions" decision, 2026-03-30). A rule is either a static boolean or a
-// predicate `(values, ctx) => boolean`. The controller evaluates them on
-// every snapshot rebuild and exposes the resolved booleans as
-// FieldState — renderers read `snapshot.fields[key].visible` and never
-// re-evaluate the predicate themselves.
-//
-// Why here and not on the framework's FieldDefinition: conditions are
-// UI-layer concerns (visibility depends on form state, not entity state)
-// and shouldn't couple the server-side schema. The App wires them up per
-// screen via the screen-def / form-controller options. The framework's
-// own `field.required` is mirrored here when present, so feature authors
-// can still declare "always required" once at the entity level.
-export type FieldConditionPredicate<TValues extends FormValues, TCtx> = (
-  values: TValues,
-  ctx: TCtx,
-) => boolean;
-
-export type FieldConditionValue<TValues extends FormValues, TCtx> =
-  | boolean
-  | FieldConditionPredicate<TValues, TCtx>;
-
-export type FieldConditions<TValues extends FormValues, TCtx = unknown> = {
-  readonly visible?: FieldConditionValue<TValues, TCtx>;
-  readonly readonly?: FieldConditionValue<TValues, TCtx>;
-  readonly required?: FieldConditionValue<TValues, TCtx>;
-};
-
-// Resolved per-field state, keyed by field name, surfaced on the snapshot.
-// Defaults (when no condition is declared): visible=true, readonly=false,
-// required=false — renderer treats a field with no rules as a normal
-// always-shown-always-editable field.
-export type FieldState = {
-  readonly visible: boolean;
-  readonly readonly: boolean;
-  readonly required: boolean;
-};
-
-// Immutable view handed to renderers. Every mutator call produces a fresh
-// snapshot; previous snapshot references stay valid for `useSyncExternalStore`'s
-// identity compare.
-export type FormSnapshot<TValues extends FormValues> = {
-  // Current values — the user's in-progress edit.
-  readonly values: TValues;
-  // Pristine values at mount / last `reset()`. Needed for:
-  //   - diffing `changes` (see below)
-  //   - the "discard changes?" prompt when the user navigates away dirty
-  //   - re-hydrating the form after an optimistic-update rollback
-  readonly initial: TValues;
-  // Changes-only: keys whose current value differs from initial, with the
-  // NEW value. The server uses this directly as the `payload` of an
-  // entity-level update command (Kumiko writes carry changes, not full
-  // objects) — see `docs/plans/architecture/event-sourcing-pivot.md`.
-  readonly changes: Partial<TValues>;
-  // True iff `changes` is non-empty. Convenience for the submit-button's
-  // disabled state and the unsaved-changes guard.
-  readonly isDirty: boolean;
-  // True iff no field was touched, kept separate from `isDirty` so UI code
-  // reads the right one without negation (= `!isDirty`). Form consumers
-  // will reach for both — they're not symmetric in intent (one is "can I
-  // submit?" and the other is "can I safely close?").
-  readonly isUnchanged: boolean;
-  // Per-field errors keyed by dotted path (`title`, `address.city`,
-  // `tasks.2.title`). Empty when the form is valid, populated after
-  // `validate()` or a failed submit. The dotted convention matches the
-  // server's ValidationError.fields[].path — a failed dispatcher call
-  // pushes its field issues here without any translation.
-  readonly errors: Readonly<Record<string, readonly FieldIssue[]>>;
-  // Resolved per-field state from FieldConditions. Renderers read this to
-  // decide whether to show the field, whether the input is disabled, and
-  // whether to show the required-marker. Fields without declared
-  // conditions default to `{ visible: true, readonly: false, required: false }`.
-  readonly fields: Readonly<Record<string, FieldState>>;
-};
-
-export type FormController<TValues extends FormValues> = {
-  // --- Subscribe surface (for useSyncExternalStore) ---
-
-  // Returns the current snapshot. SAME reference across calls until a
-  // mutator runs — callers rely on identity compare.
-  getSnapshot(): FormSnapshot<TValues>;
-
-  // Registers a listener that fires whenever the snapshot changes. Returns
-  // an unsubscribe function. Matches the `subscribe(listener) => unsubscribe`
-  // shape required by `useSyncExternalStore`.
-  subscribe(listener: () => void): () => void;
-
-  // --- Value mutators ---
-
-  // Sets one field. For scalar fields, `value` is the new value; for
-  // nested paths (lines/sub-forms) you'd use a sub-controller (Block 2b.4)
-  // instead of poking this with a dotted path.
-  setField<K extends keyof TValues>(key: K, value: TValues[K]): void;
-
-  // Bulk-update multiple fields at once. One snapshot rebuild + one
-  // notify, so a 5-field form-reset from a remote fetch doesn't cascade 5
-  // re-renders.
-  setValues(partial: Partial<TValues>): void;
-
-  // Clears field-level errors, keyed by dotted path. Used when the user
-  // starts typing again in a field that had a server-side failure —
-  // the UX hint should go away immediately, before the next validate()
-  // run. Pass no arguments to clear ALL errors.
-  clearErrors(path?: string): void;
-
-  // Replaces all errors (overwrite, not merge). Used by submit() to
-  // surface server-side validation failures and by external callers
-  // that want to project custom error state (e.g. a parent controller
-  // pushing down cross-field errors onto its children).
-  setErrors(errors: Readonly<Record<string, readonly FieldIssue[]>>): void;
-
-  // --- Validation ---
-
-  // Runs the controller's zod schema (if configured) against current
-  // values. Populates errors and returns true iff valid. Noop-returns
-  // `true` when no schema was wired — a controller without a schema
-  // relies entirely on server-side validation via the submit() path.
-  //
-  // `scope` restricts reported issues to those field names; root-level
-  // `.refine()` issues (path `(root)`) are dropped on scoped `validate()`
-  // calls (wizard steps, #1885). `submit()` always re-includes them even
-  // when `validateScope` is set so RenderEdit `fields={…}` cannot skip
-  // cross-field rules (#1907).
-  validate(scope?: readonly string[]): boolean;
-
-  // Reverts values to `initial`, clears errors. Doesn't fire a new
-  // "initial" baseline — to adopt the current values as the new baseline
-  // (e.g. after a successful submit), use `rebase()`.
-  reset(): void;
-
-  // Promotes the current values to the new `initial`, clears errors.
-  // After a successful submit the user should no longer see "unsaved
-  // changes" — rebase() is what the submit path calls internally to
-  // achieve that.
-  rebase(): void;
-
-  // Swap the external context threaded into field-condition predicates.
-  // Rare — most conditionals depend on values, not ctx — but needed when
-  // e.g. the user switches tenant mid-form and visibility rules key off
-  // tenant-scoped config.
-  setCtx(ctx: unknown): void;
-
-  // --- Submit ---
-  //
-  // Runs validate() first; if it fails, returns `{ validationBlocked: true,
-  // isSuccess: false }` WITHOUT a network call (the caller knows it's a
-  // user-level failure — show the errors, let them retry).
-  //
-  // If validation passes, dispatches to the configured submit.type with
-  // values or changes per submit.payloadMode. On server-side
-  // ValidationError, the error's field issues are pushed onto the form
-  // via setErrors so the UI reacts identically to local and remote
-  // validation failures. On success, rebase() — the form becomes "clean"
-  // and the data returned by the handler flows back via the result.
-  //
-  // Throws (not returns a failure) if `submit` config wasn't provided —
-  // a controller without submit-wiring has no destination, and guessing
-  // one would hide an integration bug.
-  submit<TData = unknown>(): Promise<SubmitResult<TData>>;
-};
-
-export type FormControllerOptions<TValues extends FormValues, TCtx = unknown> = {
-  readonly initial: TValues;
-  // Optional zod schema used by `validate()`. When present, validate()
-  // runs schema.safeParse(values) and populates the snapshot's errors
-  // map. When absent, validate() is a no-op that returns true — the
-  // controller defers entirely to server-side validation on submit.
-  //
-  // Typed as `ZodType` (not `ZodType<TValues>`) because a feature's
-  // input schema often narrows a subset of the form's surface (e.g.
-  // "changes-only" update-schemas) and re-exporting that precise type
-  // all the way through would chain generics across every layer. The
-  // runtime contract is that schema accepts the form's `values` shape.
-  readonly schema?: ZodType;
-  // Per-field conditional rules. Keyed by field name; unlisted fields
-  // get the default {visible:true, readonly:false, required:false}.
-  // See FieldConditions for the predicate signature.
-  readonly fields?: Readonly<Record<string, FieldConditions<TValues, TCtx>>>;
-  // External context passed to every field-condition predicate. Host app
-  // picks the shape — typically `{ user, tenant, config, featureToggles }`.
-  // Captured once; a ctx change without a corresponding setField/validate
-  // won't re-evaluate predicates. Use setCtx() to trigger re-evaluation
-  // when the ctx itself changes (rare in practice — most conditionals
-  // depend on values, not ctx).
-  readonly ctx?: TCtx;
-  // Optional submit wiring. When configured, `controller.submit()` runs
-  // local validate() then dispatches to the configured type with the
-  // selected payload, maps server-side field errors back onto the form,
-  // and — on success — rebases so "unsaved changes" goes quiet.
-  //
-  // Omitted when the caller drives dispatching manually (custom-screen
-  // cases, or when a multi-step wizard needs finer control). In that
-  // case submit() throws rather than guessing a destination.
-  readonly submit?: SubmitConfig<TValues>;
-};
-
-// How the form's payload is derived when submit() runs. Kumiko's write
-// convention says commands carry CHANGES (delta since initial), not full
-// objects — but that assumes an update flow. For creates, `changes ===
-// values` in practice because initial is empty.
-//
-//   - "values"  — send the current `values` object. Right for create
-//                 handlers whose schema expects a full entity payload.
-//                 Untouched fields that are still "" (the seed
-//                 buildInitialValues gives controlled optional inputs)
-//                 are stripped from the payload before it's sent, because
-//                 `.optional()` server schemas accept `undefined` but not
-//                 `""`. Set `stripEmptySeeds: false` on SubmitConfig to
-//                 opt out and send those fields as `""` unchanged.
-//   - "changes" — send only the `changes` delta. Right for update
-//                 handlers; noop when the form is un-dirty (submit
-//                 short-circuits into a no-network success).
-//
-// Default is "values" — the common M1 case is a create-screen wiring
-// straight through. Update-screens opt in with "changes".
-export type SubmitPayloadMode = "values" | "changes";
-
-export type SubmitConfig<TValues extends FormValues = FormValues> = {
-  // Optional so callers can default it from an ambient DispatcherProvider
-  // (see kumiko-renderer's useForm) instead of requiring it at every call
-  // site — submit() throws at write-time if it's still missing then.
-  readonly dispatcher?: Dispatcher;
-  // Qualified write-handler name (e.g. "orders:write:order:create").
-  readonly type: string;
-  readonly payloadMode?: SubmitPayloadMode;
-  /** Only applies to payloadMode "values". Controls whether untouched
-   *  empty-string fields (still equal to their initial "" seed) are
-   *  stripped from the payload before dispatch — see SubmitPayloadMode's
-   *  "values" doc for why the stripping exists. Default `true` (current
-   *  behavior). Set `false` to send those fields as `""` unchanged. */
-  readonly stripEmptySeeds?: boolean;
-  // Optional payload transformer — overrides payloadMode. Used for
-  // nested-writes: the submit path calls buildPayload(snapshot) once at
-  // submit-time and sends the result. The snapshot is the one captured
-  // before the network call, so in-flight edits during the await don't
-  // leak into the payload.
-  //
-  // Typical shape for a parent form with hasMany child controllers:
-  //
-  //   buildPayload: (snap) => ({
-  //     ...snap.values,
-  //     lines: lineControllers.map(c => c.getSnapshot().values),
-  //   })
-  //
-  // When both buildPayload and payloadMode are set, buildPayload wins.
-  // That's intentional: a caller choosing to write a transformer is
-  // making an explicit statement about payload shape.
-  readonly buildPayload?: (snapshot: FormSnapshot<TValues>) => unknown;
-  // When buildPayload nests values under a key, server issue paths carry it
-  // ("changes.vin"); submit() strips this prefix so errors map onto form fields.
-  readonly serverFieldPathPrefix?: string;
-  /** Restricts submit()'s internal validate() call to these field names —
-   *  same contract as validate()'s `scope` param. Set by RenderEdit when the
-   *  caller's `fields` prop narrows which fields are rendered, so an
-   *  unrendered required field can't block a submit the user can't fix.
-   *  Omitted = unscoped (existing behavior, validates everything). */
-  readonly validateScope?: readonly string[];
-};
-
-// What submit() returns. Mirrors WriteResult so a failed submit can
-// carry the structured DispatcherError unchanged — callers log or toast
-// based on error.code without the form-controller guessing UX intent.
-// `validationBlocked: true` signals a LOCAL (pre-dispatch) validate()
-// failure — no network call happened; caller doesn't need to retry the
-// network, the user needs to fix fields.
-// `isNoOp: true` signals a successful submit that skipped dispatcher.write
-// entirely because payloadMode "changes" found nothing changed — callers
-// must not treat this like a normal write (e.g. don't discard a draft).
-export type SubmitResult<TData = unknown> =
-  | ({ readonly validationBlocked: false; readonly isNoOp?: boolean } & WriteResult<TData>)
-  | { readonly validationBlocked: true; readonly isSuccess: false };

package/src/format/__tests__/escape.test.ts

@@ -1,79 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { escapeHtml, escapeHtmlAttr, escapeXml } from "../escape";
-
-describe("escapeHtml", () => {
-  test('escapes & < > "', () => {
-    expect(escapeHtml(`& < > "`)).toBe("&amp; &lt; &gt; &quot;");
-  });
-
-  test("does not escape '", () => {
-    expect(escapeHtml("it's")).toBe("it's");
-  });
-
-  test("plain text passes through", () => {
-    expect(escapeHtml("Hello, World!")).toBe("Hello, World!");
-  });
-
-  test("empty string", () => {
-    expect(escapeHtml("")).toBe("");
-  });
-
-  test("multiple occurrences", () => {
-    expect(escapeHtml(`<div class="foo">&bar</div>`)).toBe(
-      "&lt;div class=&quot;foo&quot;&gt;&amp;bar&lt;/div&gt;",
-    );
-  });
-
-  test("no double-escape", () => {
-    const escaped = escapeHtml(`& < > "`);
-    expect(escapeHtml(escaped)).toBe("&amp;amp; &amp;lt; &amp;gt; &amp;quot;");
-  });
-});
-
-describe("escapeHtmlAttr", () => {
-  test('escapes & " < > with priority on & and "', () => {
-    expect(escapeHtmlAttr(`& " < >`)).toBe("&amp; &quot; &lt; &gt;");
-  });
-
-  test("escapes ' so single-quoted attributes cannot break out", () => {
-    expect(escapeHtmlAttr("it's")).toBe("it&#39;s");
-  });
-
-  test("plain attribute value passes through", () => {
-    expect(escapeHtmlAttr("https://example.com?a=1&b=2")).toBe("https://example.com?a=1&amp;b=2");
-  });
-
-  test("empty string", () => {
-    expect(escapeHtmlAttr("")).toBe("");
-  });
-
-  test("no double-escape", () => {
-    const escaped = escapeHtmlAttr(`& " < >`);
-    expect(escapeHtmlAttr(escaped)).toBe("&amp;amp; &amp;quot; &amp;lt; &amp;gt;");
-  });
-});
-
-describe("escapeXml", () => {
-  test("escapes & < > \" '", () => {
-    expect(escapeXml(`& < > " '`)).toBe("&amp; &lt; &gt; &quot; &apos;");
-  });
-
-  test("plain text passes through", () => {
-    expect(escapeXml("Hello, World!")).toBe("Hello, World!");
-  });
-
-  test("empty string", () => {
-    expect(escapeXml("")).toBe("");
-  });
-
-  test("multiple occurrences", () => {
-    expect(escapeXml(`<element attr="value">it's & stuff</element>`)).toBe(
-      "&lt;element attr=&quot;value&quot;&gt;it&apos;s &amp; stuff&lt;/element&gt;",
-    );
-  });
-
-  test("no double-escape", () => {
-    const escaped = escapeXml(`& < > " '`);
-    expect(escapeXml(escaped)).toBe("&amp;amp; &amp;lt; &amp;gt; &amp;quot; &amp;apos;");
-  });
-});

package/src/format/__tests__/format.test.ts

@@ -1,281 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { applyFormatSpec, UNIT_FORMAT_KEYS } from "../index";
-
-describe("applyFormatSpec — priority", () => {
-  test("rendert emptyLabel für undefined/null/leer/0 (nicht den globalen ''-Collapse)", () => {
-    expect(applyFormatSpec({ format: "priority" }, undefined)).toBe("—");
-    expect(applyFormatSpec({ format: "priority" }, null)).toBe("—");
-    expect(applyFormatSpec({ format: "priority" }, "")).toBe("—");
-    expect(applyFormatSpec({ format: "priority" }, 0)).toBe("—");
-  });
-
-  test("custom emptyLabel + prefix", () => {
-    expect(applyFormatSpec({ format: "priority", emptyLabel: "none" }, null)).toBe("none");
-    expect(applyFormatSpec({ format: "priority", prefix: "P" }, 2)).toBe("P2");
-  });
-});
-
-describe("applyFormatSpec — leere Werte anderer Formate", () => {
-  test("collapsen zu ''", () => {
-    expect(applyFormatSpec({ format: "boolean" }, undefined)).toBe("");
-    expect(applyFormatSpec({ format: "currency", symbol: "€" }, null)).toBe("");
-    expect(applyFormatSpec({ format: "timestamp" }, "")).toBe("");
-  });
-});
-
-describe("applyFormatSpec — boolean/currency", () => {
-  test("boolean mit Default- und Custom-Labels", () => {
-    expect(applyFormatSpec({ format: "boolean" }, true)).toBe("✓");
-    expect(applyFormatSpec({ format: "boolean" }, false)).toBe("");
-    expect(applyFormatSpec({ format: "boolean", trueLabel: "ja", falseLabel: "nein" }, false)).toBe(
-      "nein",
-    );
-  });
-
-  test("currency hängt Symbol an", () => {
-    expect(applyFormatSpec({ format: "currency", symbol: "€" }, 12)).toBe("12 €");
-    expect(applyFormatSpec({ format: "currency" }, 12)).toBe("12");
-  });
-});
-
-describe("applyFormatSpec — number grouping (fw#3234)", () => {
-  test("groups thousands by default", () => {
-    expect(applyFormatSpec({ format: "number" }, 2021)).toBe("2,021");
-    expect(applyFormatSpec({ format: "number", locale: "de-DE" }, 2021)).toBe("2.021");
-  });
-
-  test("grouping: false renders no thousands separator", () => {
-    expect(applyFormatSpec({ format: "number", grouping: false }, 2021)).toBe("2021");
-    expect(applyFormatSpec({ format: "number", locale: "de-DE", grouping: false }, 2021)).toBe(
-      "2021",
-    );
-  });
-
-  test("decimal/bigInt share the same grouping path", () => {
-    expect(applyFormatSpec({ format: "decimal", locale: "de-DE" }, 2021)).toBe("2.021");
-    expect(applyFormatSpec({ format: "bigInt", locale: "de-DE", grouping: false }, 2021)).toBe(
-      "2021",
-    );
-  });
-});
-
-describe("applyFormatSpec — timestamp/date (formatDateCell-Pfad)", () => {
-  // Mittag UTC: das Datum kippt in keiner Zeitzone UTC-11..UTC+11 —
-  // deterministisch auf CI (UTC) und lokal (CET).
-  const instant = "2026-01-15T12:00:00Z";
-
-  test("timestamp mit locale+dateStyle+timeStyle rendert lokalisiert", () => {
-    const out = applyFormatSpec(
-      { format: "timestamp", locale: "en-US", dateStyle: "long", timeStyle: "short" },
-      instant,
-    );
-    expect(out).toContain("January");
-    expect(out).toContain("2026");
-  });
-
-  test("date mit locale de-DE rendert deutschen Monatsnamen", () => {
-    const out = applyFormatSpec({ format: "date", locale: "de-DE", dateStyle: "long" }, instant);
-    expect(out).toContain("Januar");
-    expect(out).toContain("2026");
-  });
-
-  test("timestamp ohne Optionen nutzt das kompakte Default-Format", () => {
-    const out = applyFormatSpec({ format: "timestamp", locale: "en-US" }, instant);
-    expect(out).toContain("2026");
-    expect(out).not.toBe(instant);
-  });
-
-  test("unparsebarer Wert fällt auf den Rohstring zurück", () => {
-    expect(applyFormatSpec({ format: "timestamp" }, "kein-datum")).toBe("kein-datum");
-    expect(applyFormatSpec({ format: "date" }, "kein-datum")).toBe("kein-datum");
-  });
-
-  test("offset-lose Timestamps (kein Z/Offset) fallen NICHT auf den Rohstring zurück", () => {
-    // Temporal.Instant.from is stricter than the old `new Date(raw)` —
-    // without a UTC designator/offset it throws. Both forms must still
-    // format instead of passing through raw (see toInstant fallback in
-    // index.ts).
-    const withoutOffset = "2026-01-15T12:00:00";
-    const withoutTime = "2026-01-15 12:00:00";
-    for (const raw of [withoutOffset, withoutTime]) {
-      const out = applyFormatSpec({ format: "timestamp", locale: "en-US" }, raw);
-      expect(out).not.toBe(raw);
-      expect(out).toContain("2026");
-    }
-  });
-
-  test("offset-loser Timestamp im date-Format fällt NICHT auf den Rohstring zurück", () => {
-    const withoutOffset = "2026-01-15T12:00:00";
-    const out = applyFormatSpec({ format: "date", locale: "en-US" }, withoutOffset);
-    expect(out).not.toBe(withoutOffset);
-    expect(out).toContain("2026");
-  });
-});
-
-describe("applyFormatSpec — unit (fw#2187)", () => {
-  test("km/m/kg/percent gehen über Intl.NumberFormat(style:'unit'), locale-korrekt", () => {
-    expect(applyFormatSpec({ format: "unit", unit: "km" }, 58)).toBe(
-      new Intl.NumberFormat(undefined, {
-        style: "unit",
-        unit: "kilometer",
-        unitDisplay: "short",
-      }).format(58),
-    );
-    expect(applyFormatSpec({ format: "unit", unit: "km", locale: "de-DE" }, 58)).toBe("58 km");
-    expect(applyFormatSpec({ format: "unit", unit: "kg", locale: "de-DE" }, 2.5)).toBe("2,5 kg");
-    // de-DE percent uses a narrow no-break space (U+202F) before "%", not a
-    // plain space — assert against Intl's own output rather than guessing.
-    expect(applyFormatSpec({ format: "unit", unit: "percent", locale: "de-DE" }, 12)).toBe(
-      new Intl.NumberFormat("de-DE", {
-        style: "unit",
-        unit: "percent",
-        unitDisplay: "short",
-      }).format(12),
-    );
-    // Ratio 0.15 must NOT become 15 % — unit:"percent" is percent-points.
-    expect(applyFormatSpec({ format: "unit", unit: "percent", locale: "de-DE" }, 0.15)).toBe(
-      new Intl.NumberFormat("de-DE", {
-        style: "unit",
-        unit: "percent",
-        unitDisplay: "short",
-      }).format(0.15),
-    );
-  });
-
-  test("mi (Meilen) geht über Intl.NumberFormat(style:'unit') genau wie km", () => {
-    expect(applyFormatSpec({ format: "unit", unit: "mi" }, 58)).toBe(
-      new Intl.NumberFormat(undefined, {
-        style: "unit",
-        unit: "mile",
-        unitDisplay: "short",
-      }).format(58),
-    );
-    expect(applyFormatSpec({ format: "unit", unit: "mi", locale: "en-US" }, 12)).toBe("12 mi");
-  });
-
-  test("m2 hat kein ECMA-402-sanktioniertes Intl-Unit (RangeError für 'square-meter') — Zahl + literales Suffix", () => {
-    expect(applyFormatSpec({ format: "unit", unit: "m2", locale: "de-DE" }, 58)).toBe("58 m²");
-    expect(applyFormatSpec({ format: "unit", unit: "m2", locale: "de-DE" }, 1234.5)).toBe(
-      "1.234,5 m²",
-    );
-  });
-
-  test("unitDisplay steuert long", () => {
-    expect(
-      applyFormatSpec({ format: "unit", unit: "km", locale: "en-US", unitDisplay: "long" }, 3),
-    ).toBe("3 kilometers");
-    expect(
-      applyFormatSpec({ format: "unit", unit: "km", locale: "en-US", unitDisplay: "narrow" }, 3),
-    ).toBe(
-      new Intl.NumberFormat("en-US", {
-        style: "unit",
-        unit: "kilometer",
-        unitDisplay: "narrow",
-      }).format(3),
-    );
-  });
-
-  test("nicht-numerischer Wert fällt auf String zurück", () => {
-    expect(applyFormatSpec({ format: "unit", unit: "km" }, "not-a-number")).toBe("not-a-number");
-  });
-
-  test("fehlende/unbekannte unit fällt auf String zurück, statt zu werfen", () => {
-    expect(applyFormatSpec({ format: "unit" }, 58)).toBe("58");
-    expect(applyFormatSpec({ format: "unit", unit: "does-not-exist" }, 58)).toBe("58");
-  });
-
-  test("Prototype-Chain-Keys (toString, constructor) zählen NICHT als unit — Object.hasOwn statt `in`", () => {
-    expect(applyFormatSpec({ format: "unit", unit: "toString" }, 58)).toBe("58");
-    expect(applyFormatSpec({ format: "unit", unit: "constructor" }, 58)).toBe("58");
-  });
-
-  test("leerer Wert collapst zu '' wie jedes andere Nicht-priority-Format", () => {
-    expect(applyFormatSpec({ format: "unit", unit: "km" }, null)).toBe("");
-    expect(applyFormatSpec({ format: "unit", unit: "km" }, "")).toBe("");
-  });
-});
-
-describe("applyFormatSpec — enumOption (fw#2315)", () => {
-  const spec = { format: "enumOption", keyPrefix: "contact:entity:contact:field:status:option:" };
-
-  test("übersetzter Key gewinnt gegen den Rohwert", () => {
-    const translate = (key: string) =>
-      key === "contact:entity:contact:field:status:option:active" ? "Aktiv" : key;
-    expect(applyFormatSpec(spec, "active", translate)).toBe("Aktiv");
-  });
-
-  test("unbekannter Key fällt auf den Rohwert zurück (translate gibt den Key unverändert zurück)", () => {
-    const translate = (key: string) => key;
-    expect(applyFormatSpec(spec, "active", translate)).toBe("active");
-  });
-
-  test("ohne translate-Parameter fällt auf den Rohwert zurück", () => {
-    expect(applyFormatSpec(spec, "active")).toBe("active");
-  });
-
-  test("ohne keyPrefix fällt auf den Rohwert zurück, auch mit translate", () => {
-    const translate = (key: string) => `translated:${key}`;
-    expect(applyFormatSpec({ format: "enumOption" }, "active", translate)).toBe("active");
-  });
-
-  test("nicht-string-Wert wird vor der Key-Bildung stringifiziert", () => {
-    const translate = (key: string) =>
-      key === "contact:entity:contact:field:status:option:1" ? "Eins" : key;
-    expect(applyFormatSpec(spec, 1, translate)).toBe("Eins");
-  });
-
-  test("leerer Wert collapst zu '' wie jedes andere Nicht-priority-Format", () => {
-    expect(applyFormatSpec(spec, null, (k) => k)).toBe("");
-    expect(applyFormatSpec(spec, "", (k) => k)).toBe("");
-  });
-});
-
-describe("applyFormatSpec — boolean labels through translate (fw#2683)", () => {
-  const TRUE_KEY = "managed-pages:entity:page:field:published:option:true";
-  const FALSE_KEY = "managed-pages:entity:page:field:published:option:false";
-  const spec = { format: "boolean", trueLabel: TRUE_KEY, falseLabel: FALSE_KEY };
-  const translate = (key: string): string => {
-    if (key === TRUE_KEY) return "Published";
-    if (key === FALSE_KEY) return "Draft";
-    return key;
-  };
-
-  test("an i18n key as trueLabel renders translated", () => {
-    expect(applyFormatSpec(spec, true, translate)).toBe("Published");
-  });
-
-  test("an i18n key as falseLabel renders translated", () => {
-    expect(applyFormatSpec(spec, false, translate)).toBe("Draft");
-  });
-
-  test("without translate the declared labels stay verbatim", () => {
-    expect(applyFormatSpec(spec, true)).toBe(TRUE_KEY);
-    expect(applyFormatSpec(spec, false)).toBe(FALSE_KEY);
-  });
-
-  test("a plain-text label is not mangled by a pass-through translate", () => {
-    const plain = { format: "boolean", trueLabel: "Yes", falseLabel: "No" };
-    expect(applyFormatSpec(plain, true, (k) => k)).toBe("Yes");
-    expect(applyFormatSpec(plain, false, (k) => k)).toBe("No");
-  });
-
-  test("undeclared labels keep the ✓ / empty defaults even with translate", () => {
-    expect(applyFormatSpec({ format: "boolean" }, true, translate)).toBe("✓");
-    expect(applyFormatSpec({ format: "boolean" }, false, translate)).toBe("");
-  });
-});
-
-describe("unit format keys stay in lockstep with UnitKey", () => {
-  // Mirror of packages/types/src/screen.ts UnitKey — keep lists equal without
-  // adding a kumiko-types dependency to headless.
-  const TYPE_UNIT_KEYS = ["m2", "km", "m", "kg", "percent", "mi"] as const;
-  test("every UnitKey formats with a non-bare number", () => {
-    for (const k of TYPE_UNIT_KEYS) {
-      expect(UNIT_FORMAT_KEYS.includes(k)).toBe(true);
-      expect(applyFormatSpec({ format: "unit", unit: k }, 1)).not.toBe("1");
-    }
-  });
-  test("no extra runtime keys beyond UnitKey", () => {
-    expect([...UNIT_FORMAT_KEYS].sort()).toEqual([...TYPE_UNIT_KEYS].sort());
-  });
-});