fix(codegen-ts-react): the blank-optional list names only fields with a scalar control (#223)

Regenerating the advanced-modeling example put `syllabus` (an array-of-VO jsonb) and
`instructorProfile` (a single VO jsonb) into `BLANK_OPTIONAL_FIELDS`. Neither can
ever hold `""` — one renders as a `useFieldArray` list and the other as a nested
block, so what they submit is an array or an object, and the normalizer's `!== ""`
guard skips both. Harmless today, and wrong in the direction that invites a real
bug: the list is a statement about which controls can be BLANK, so naming a field
that has no scalar control at all is a claim about something that does not exist.

The predicate was "optional and not a checkbox/image", which is too coarse. It now
also excludes `field.object` and any array field. On the example that takes the list
from five entries to the three that actually have a blankable control: an enum
`<select>`, a textarea, and a currency input.

The example is what caught it — its committed `src/generated/**` is drift-gated, so
it regenerates whenever a generator changes and a reviewer sees the real field list
for a real model. A fixture would not have; the two VO shapes only exist there.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01DhpswkF1NvwxhFWMmdAT15

Author: dmealing

examples/advanced-modeling/src/generated/Program.form.tsx

@@ -10,6 +10,28 @@ import { useEntityForm } from "@metaobjectsdev/react";
 import type { ReactElement } from "react";
 import type { SubmitHandler } from "react-hook-form";
 
+const BLANK_OPTIONAL_FIELDS = ["status", "summary", "priceCents"] as const;
+
+/**
+ * Normalize blank optional inputs on the way out of the form (#223).
+ * On create a blank field is OMITTED (the column defaults); on edit it is sent as
+ * explicit `null` (present-null clears, per the FR-035 PATCH tristate).
+ */
+function normalizeBlankOptionals(values: Record<string, unknown>, isEdit: boolean): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...values };
+  for (const key of BLANK_OPTIONAL_FIELDS) {
+    if (out[key] !== "") {
+      continue;
+    }
+    if (isEdit) {
+      out[key] = null;
+    } else {
+      delete out[key];
+    }
+  }
+  return out;
+}
+
 export interface ProgramFormProps {
   onSubmit: SubmitHandler<Partial<ProgramRow>>;
   defaultValues?: Partial<ProgramRow>;
@@ -38,7 +60,13 @@ export function ProgramForm(props: ProgramFormProps): ReactElement {
     <form
       className={props.className ?? "metaobjects-form"}
       data-entity={Program.$entity}
-      onSubmit={form.handleSubmit(props.onSubmit as never)}
+      onSubmit={form.handleSubmit(
+        ((values: Record<string, unknown>, event?: unknown) =>
+          props.onSubmit(
+            normalizeBlankOptionals(values, props.defaultValues !== undefined) as never,
+            event as never,
+          )) as never,
+      )}
     >
       <div className="metaobjects-field" key="title">
         <label className="metaobjects-field-label" htmlFor={Program.title.name}>{Program.title.label}</label>

examples/advanced-modeling/src/generated/Purchase.form.tsx

@@ -7,6 +7,28 @@ import { useEntityForm } from "@metaobjectsdev/react";
 import type { ReactElement } from "react";
 import type { SubmitHandler } from "react-hook-form";
 
+const BLANK_OPTIONAL_FIELDS = ["amountCents", "status", "purchasedAt"] as const;
+
+/**
+ * Normalize blank optional inputs on the way out of the form (#223).
+ * On create a blank field is OMITTED (the column defaults); on edit it is sent as
+ * explicit `null` (present-null clears, per the FR-035 PATCH tristate).
+ */
+function normalizeBlankOptionals(values: Record<string, unknown>, isEdit: boolean): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...values };
+  for (const key of BLANK_OPTIONAL_FIELDS) {
+    if (out[key] !== "") {
+      continue;
+    }
+    if (isEdit) {
+      out[key] = null;
+    } else {
+      delete out[key];
+    }
+  }
+  return out;
+}
+
 export interface PurchaseFormProps {
   onSubmit: SubmitHandler<Partial<PurchaseRow>>;
   defaultValues?: Partial<PurchaseRow>;
@@ -34,7 +56,13 @@ export function PurchaseForm(props: PurchaseFormProps): ReactElement {
     <form
       className={props.className ?? "metaobjects-form"}
       data-entity={Purchase.$entity}
-      onSubmit={form.handleSubmit(props.onSubmit as never)}
+      onSubmit={form.handleSubmit(
+        ((values: Record<string, unknown>, event?: unknown) =>
+          props.onSubmit(
+            normalizeBlankOptionals(values, props.defaultValues !== undefined) as never,
+            event as never,
+          )) as never,
+      )}
     >
       <div className="metaobjects-field" key="programId">
         <label className="metaobjects-field-label" htmlFor={Purchase.programId.name}>{Purchase.programId.label}</label>

server/typescript/packages/codegen-ts-react/src/templates/form-file.ts

@@ -300,25 +300,30 @@ function enumValues(field: MetaField): string[] {
  * all (it fails the column's type), and for every other nullable column it makes a
  * `!= null` check read a blank field as SET.
  *
- * Excluded because they cannot produce `""`: a checkbox (always boolean) and a
- * `view.image` (Controller-managed, carries a storage key). A `@required` field is
- * excluded too — blank there is a validation error the schema already owns, and
- * rewriting it would convert a caught error into a silent null.
+ * Excluded because they cannot produce `""`, and naming one anyway would be a claim about
+ * a control that does not exist:
+ *   - a checkbox — always a boolean, and `false` is a real answer, never "blank";
+ *   - a `view.image` — Controller-managed, and its value is an opaque storage key;
+ *   - a nested `field.object` and any array field — rendered as a nested block or a
+ *     `useFieldArray` list, so what they submit is an object or an array.
+ * A `@required` field is excluded too: blank there is a validation error the schema
+ * already owns, and rewriting it would turn a caught error into a silent null.
  */
-/** Names of the two symbols the blank-normalizer emits, kept out of the template string. */
-const BLANK_FIELDS_CONST = "BLANK_OPTIONAL_FIELDS";
-const BLANK_NORMALIZER = "normalizeBlankOptionals";
-
 function blankableOptionalFields(fields: readonly MetaField[]): string[] {
   return fields
     .filter((f) => f.attr(FIELD_ATTR_REQUIRED) !== true)
+    .filter((f) => f.subType !== FIELD_SUBTYPE_OBJECT && !f.resolvedIsArray())
     .filter((f) => {
       const kind = viewKindFor(f, f.views()[0]); // resolving accessor (ADR-0039)
       return kind !== VIEW_SUBTYPE_CHECKBOX && kind !== VIEW_SUBTYPE_IMAGE;
     })
     .map((f) => f.name);
 }
 
+/** Names of the two symbols the blank-normalizer emits, kept out of the template string. */
+const BLANK_FIELDS_CONST = "BLANK_OPTIONAL_FIELDS";
+const BLANK_NORMALIZER = "normalizeBlankOptionals";
+
 export function renderFormFile(entity: MetaObject, ctx: RenderContext): string {
   const entityName = entity.name;
   // Import the entity's own file. Same target → relative "./Entity"; cross

server/typescript/packages/codegen-ts-react/test/form-blank-optional-tristate.test.ts

@@ -21,11 +21,16 @@ import { makeRenderContext, buildPkMap, buildRelationMap } from "@metaobjectsdev
 import type { GenContext } from "@metaobjectsdev/codegen-ts";
 import { MetaDataLoader, InMemoryStringSource } from "@metaobjectsdev/metadata";
 
-async function formFor(entityChildren: unknown[], name = "Booking"): Promise<string> {
+async function formFor(
+  entityChildren: unknown[],
+  name = "Booking",
+  extraRoots: unknown[] = [],
+): Promise<string> {
   const json = JSON.stringify({
     "metadata.root": {
       package: "acme",
       children: [
+        ...extraRoots,
         {
           "object.entity": {
             name,
@@ -145,6 +150,24 @@ describe("generated form — blank optional fields are tristate-aware (#223)", (
     });
   });
 
+  // Caught by regenerating the advanced-modeling example: a jsonb value-object field was
+  // being listed, because "optional and not a checkbox" was too coarse a test. It could
+  // never fire (its value is an object, never `""`), but the list is a statement about
+  // which controls can be blank, and naming one that has no scalar control at all is
+  // wrong in the direction that invites a real bug later.
+  test("a nested value object and an array field are excluded — neither has a scalar control", async () => {
+    const src = await formFor(
+      [
+        OPTIONAL_TEXT,
+        { "field.string": { name: "tags", isArray: true } },
+        { "field.object": { name: "profile", "@objectRef": "Profile", "@storage": "jsonb" } },
+      ],
+      "Listing",
+      [{ "object.value": { name: "Profile", children: [{ "field.string": { name: "bio" } }] } }],
+    );
+    expect(blankFieldList(src)).toEqual(["note"]);
+  });
+
   test("an all-required form emits no normalizer at all — output stays byte-identical", async () => {
     const src = await formFor([REQUIRED_TEXT]);
     expect(src).not.toContain("normalizeBlankOptionals");