fix: centralize the nullable-union collapse in core and apply it in the TUI

Closes #2015, folded into #1928 rather than left as a follow-up.

The TUI's `schemaToForm` has the same defect the web `SchemaForm` had: its
local `JsonSchemaProperty` declares only `type?: string` — no `anyOf`, no
array-valued `type` — so a `.nullish()` argument has no top-level `type` or
`enum` for the dispatcher to read and falls to the `switch` default, losing
its select. Milder than the web bug (a plain text field, not a corrupting
JSON textarea), but the same class.

Fixing it in a second place is the argument for not having the logic in a
first place. So the collapse moves to `core/json/nullableUnion.ts` as
`normalizeNullableUnion`, generic over a minimal `NullableUnionSchema`
shape — the least a caller must expose to be *recognized* as a nullable
union — so neither client has to adopt the other's schema type. Both form
builders now share one copy and cannot drift on which schemas they render.

- `core/json/nullableUnion.ts` — the shared collapse, plus tests at
  `clients/web/src/test/core/nullableUnion.test.ts` (the web suite is what
  gates `core/`).
- `clients/web`: `schemaUtils.normalizeUnionType` is gone; `SchemaForm` and
  `resolveRefsInMessage` call the core function directly.
- `clients/tui`: `schemaToForm` normalizes each property before dispatch,
  and `JsonSchemaProperty` grows the `anyOf` / array-`type` fields the
  encoding uses.

Verified by driving the built TUI under a pty against the
`nullable-fields-http.json` showcase server. Before, every argument of
`record_shipment` rendered as a plain text field; after, `direction` is a
select ("No value"), `quantity` an integer, `express` a boolean
("[Not set]").

Signed-off-by: cliffhall <cliff@futurescale.com>

clients/web/src/test/core/nullableUnion.test.ts

@@ -0,0 +1,250 @@
+import { describe, it, expect } from "vitest";
+import { normalizeNullableUnion } from "@inspector/core/json/nullableUnion.js";
+
+// The two JSON Schema encodings of "this type, or null". Both form builders —
+// the web `SchemaForm` and the TUI's `schemaToForm` — dispatch on a single
+// `type` string, so this collapse is what keeps a nullable field renderable
+// (#1928 in the web client, #2015 in the TUI).
+describe("normalizeNullableUnion", () => {
+  it("normalizes anyOf string|null", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ type: "string" }, { type: "null" }],
+      }),
+    ).toEqual({
+      type: "string",
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("normalizes anyOf boolean|null", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ type: "boolean" }, { type: "null" }],
+      }),
+    ).toEqual({
+      type: "boolean",
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("normalizes anyOf number|null", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ type: "number" }, { type: "null" }],
+      }),
+    ).toEqual({
+      type: "number",
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("normalizes anyOf integer|null", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ type: "integer" }, { type: "null" }],
+      }),
+    ).toEqual({
+      type: "integer",
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("normalizes anyOf array|null", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ type: "array" }, { type: "null" }],
+      }),
+    ).toEqual({
+      type: "array",
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("normalizes type array string|null", () => {
+    expect(normalizeNullableUnion({ type: ["string", "null"] })).toEqual({
+      type: "string",
+      nullable: true,
+    });
+  });
+
+  it("normalizes type array boolean|null", () => {
+    expect(normalizeNullableUnion({ type: ["boolean", "null"] })).toEqual({
+      type: "boolean",
+      nullable: true,
+    });
+  });
+
+  it("normalizes type array number|null", () => {
+    expect(normalizeNullableUnion({ type: ["number", "null"] })).toEqual({
+      type: "number",
+      nullable: true,
+    });
+  });
+
+  it("normalizes type array integer|null", () => {
+    expect(normalizeNullableUnion({ type: ["integer", "null"] })).toEqual({
+      type: "integer",
+      nullable: true,
+    });
+  });
+
+  it("returns schema unchanged when no union pattern matches", () => {
+    const schema = { type: "string" as const };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  it("ignores anyOf with more than two members", () => {
+    const schema = {
+      anyOf: [
+        { type: "string" as const },
+        { type: "null" as const },
+        { type: "number" as const },
+      ],
+    };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  it("ignores a two-member anyOf with no null branch", () => {
+    const schema = {
+      anyOf: [{ type: "string" as const }, { type: "number" as const }],
+    };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  it("ignores an anyOf whose non-null branch has no renderable type (#1928)", () => {
+    const schema = {
+      anyOf: [{ const: "only" }, { type: "null" as const }],
+    };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  // #1928: the enum lives on the surviving branch, and hoisting it is what makes
+  // the field render as a Select instead of the raw-JSON fallback.
+  it("hoists enum out of an anyOf string-enum|null branch", () => {
+    expect(
+      normalizeNullableUnion({
+        description: "Direction",
+        anyOf: [
+          { type: "string", enum: ["envio", "recebimento"] },
+          { type: "null" },
+        ],
+      }),
+    ).toEqual({
+      type: "string",
+      description: "Direction",
+      enum: ["envio", "recebimento"],
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("infers string for a typeless enum branch", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ enum: ["a", "b"] }, { type: "null" }],
+      }),
+    ).toEqual({
+      type: "string",
+      enum: ["a", "b"],
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("hoists items out of an anyOf array|null branch", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [
+          { type: "array", items: { type: "string", enum: ["a", "b"] } },
+          { type: "null" },
+        ],
+      }),
+    ).toEqual({
+      type: "array",
+      items: { type: "string", enum: ["a", "b"] },
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("hoists properties out of an anyOf object|null branch", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [
+          { type: "object", properties: { a: { type: "string" } } },
+          { type: "null" },
+        ],
+      }),
+    ).toEqual({
+      type: "object",
+      properties: { a: { type: "string" } },
+      anyOf: undefined,
+      nullable: true,
+    });
+  });
+
+  it("normalizes anyOf object|null regardless of branch order", () => {
+    expect(
+      normalizeNullableUnion({
+        anyOf: [{ type: "null" }, { type: "object" }],
+      }),
+    ).toEqual({ type: "object", anyOf: undefined, nullable: true });
+  });
+
+  it("normalizes type array object|null", () => {
+    expect(
+      normalizeNullableUnion({
+        type: ["object", "null"],
+        properties: { a: { type: "string" } },
+      }),
+    ).toEqual({
+      type: "object",
+      properties: { a: { type: "string" } },
+      nullable: true,
+    });
+  });
+
+  it("normalizes type array array|null", () => {
+    expect(normalizeNullableUnion({ type: ["array", "null"] })).toEqual({
+      type: "array",
+      nullable: true,
+    });
+  });
+
+  it("keeps a type array of two non-null members unchanged", () => {
+    const schema = { type: ["string", "number"] as const };
+    expect(
+      normalizeNullableUnion({ ...schema, type: [...schema.type] }),
+    ).toEqual({
+      type: ["string", "number"],
+    });
+  });
+
+  // A server can put anything in `anyOf`; a non-object member must not be read
+  // as a branch (nor throw), it simply means no nullable union was recognized.
+  it("ignores an anyOf holding a non-object member", () => {
+    const schema = { anyOf: ["string", { type: "null" as const }] };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  it("ignores an anyOf holding an array member", () => {
+    const schema = { anyOf: [["string"], { type: "null" as const }] };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  it("ignores a type array whose non-null member has no widget", () => {
+    const schema = { type: ["null", "null"] };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+
+  it("ignores a schema with no union keywords at all", () => {
+    const schema = { type: "object" as const, properties: {} };
+    expect(normalizeNullableUnion(schema)).toBe(schema);
+  });
+});