fix(spec): withdraw the offered-but-refused icon input from the object.form options repeater (#14326)

* fix(spec): withdraw the `icon` input from the object.form options repeater

The fields repeater's `options` sub-form offered an `icon` text input
("Lucide icon name") that `SelectOptionSchema` refuses at publish — the
shape is strict and has never declared `icon`, so an author who used the
input learned about it at the 422. Offer and door disagreed.

Resolved under ADR-0049 enforce-or-remove on the remove route: the offer
is withdrawn, the door is unchanged (`icon` was refused before this
change and is refused after it — no accept/reject behaviour moves).

The route rests on a premise measured for the FIELD-option surface
rather than inherited from #5016's ACTION-param reading: objectui
declares `icon` on `SelectOptionMetadata`, but no field-option render
path reads it. Measured on objectui 67dadd60 with a live positive
control — `packages/fields/src/index.tsx` reads `option?.label` and
`option?.color` off the same `SelectOptionMetadata[]` and never
`option?.icon`.

The #13669 pin moves in the same stroke instead of being deleted: its
`icon` control kept asserting only the door, which is how the offer-side
gap stayed green. It now asserts both halves, with the subject change
written out above the new section.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

* chore(spec): changeset for the withdrawn option `icon` input, and a truer pin title

The "leaves the OBJECT-level `icon` row alone" case asserts there is exactly
ONE `icon` input in the whole object form, so its title now says that: it is a
count, and it therefore also reds if the withdrawn row comes back.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

* docs(spec): anchor the objectui reader measurement to the pin, in the gate's spelling

`check:objectui-pin-citations` only sees a citation written as one of its two
spellings, and an unrecognised one is silent — so the read-point record now
uses the HISTORICAL form (`.objectui-sha` pin `<sha>`), which is what it is:
where the measurement was taken, not a claim about today's pin. Both citations
are now in the gate's population (13 historical -> 15).

The measurement was also repeated at the pin this repo actually ships
(d8ec8d6d4) as well as objectui `origin/main` (67dadd602) — same answer, same
positive control, both trees.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

* fix(i18n): regenerate platform-objects bundles after option icon row removal

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01GDA48PuRFrHyRfdkBz8m21

---------

Co-authored-by: os-zhuang <jack@objectstack.ai>
Co-authored-by: Claude Fable 5.1 <noreply@anthropic.com>

Author: 3 people

.changeset/object-form-option-icon-offer-withdrawn.md

@@ -0,0 +1,43 @@
+---
+"@objectstack/spec": patch
+---
+
+fix(spec): withdraw the `icon` input from the `object.form` options repeater (#13671)
+
+The field designer's `options` sub-form offered five inputs per select option,
+and one of them named a key the publish door refuses. `SelectOptionSchema` is
+strict and has never declared `icon`, so a Lucide name typed into that input
+came back as an `unrecognized_keys` refusal at publish — the author found out
+at the 422. Offer and door disagreed: the same class #11410 (a form offering a
+`deleteBehavior` the schema refuses) and #12868 (the form-face option
+narrowing) retired elsewhere, one key over.
+
+Resolved under **ADR-0049 enforce-or-remove on the remove route**: the offer is
+withdrawn so that declared = offered converges downward. ⚠️ **No accept/reject
+behaviour moves** — `icon` on a select option was refused before this change
+and is refused after it. Metadata that parses today parses identically; the
+only thing that changes is what the Studio object designer teaches an author to
+write. The repeater now offers `label`, `value`, `color` and `description` —
+exactly `SelectOptionSchema`'s authorable keys minus `visibleWhen`, which is a
+CEL predicate rather than a repeater text input.
+
+**Why remove rather than declare.** The route rests on a premise measured for
+the FIELD-option surface rather than inherited from #5016, which measured the
+ACTION-param path — objectui's `SelectOptionMetadata` does declare `icon`, so
+the two faces had to be measured apart. Measured twice with a live positive
+control, same answer both times: at the objectui pin this repo ships
+(`.objectui-sha` = `d8ec8d6d4f011b11c8eb1e6dbd364ef206711391`) and again at
+that repo's `origin/main` (`67dadd602a3a891666ea1513c5de677140784b6a`). The
+select/multiselect cell renderer (`packages/fields/src/index.tsx`) reads
+`option?.label` and `option?.color` off a `SelectOptionMetadata[]` and never
+`option?.icon`, and no field-option render path in either tree reads the key at
+all. Declaring `icon` instead would widen
+the accepted set, which needs a maintainer ruling and is deliberately not taken
+here.
+
+The #13669 pin (`field-rows-option-description.test.ts`) moves in the same
+stroke rather than being deleted: its `icon` case asserted only that the door
+refuses the key, which is how the offer-side half stayed green across a live
+disagreement. It now asserts both halves — the door still refuses `icon`, and
+the form no longer offers it — plus the general invariant that every input the
+repeater offers names a key the door accepts.

packages/platform-objects/src/apps/translations/en.metadata-forms.generated.ts

@@ -153,10 +153,6 @@ export const enMetadataForms: NonNullable<TranslationData['metadataForms']> = {
       "fields.options.color": {
         label: "Color"
       },
-      "fields.options.icon": {
-        label: "Icon",
-        helpText: "Lucide icon name"
-      },
       "fields.options.description": {
         label: "Description"
       },

packages/platform-objects/src/apps/translations/es-ES.metadata-forms.generated.ts

@@ -153,10 +153,6 @@ export const esESMetadataForms: NonNullable<TranslationData['metadataForms']> =
       "fields.options.color": {
         label: "Color de opción"
       },
-      "fields.options.icon": {
-        label: "Icono",
-        helpText: "Nombre de icono Lucide"
-      },
       "fields.options.description": {
         label: "Descripción"
       },

packages/platform-objects/src/apps/translations/ja-JP.metadata-forms.generated.ts

@@ -153,10 +153,6 @@ export const jaJPMetadataForms: NonNullable<TranslationData['metadataForms']> =
       "fields.options.color": {
         label: "色"
       },
-      "fields.options.icon": {
-        label: "アイコン",
-        helpText: "Lucide アイコン名"
-      },
       "fields.options.description": {
         label: "説明"
       },

packages/platform-objects/src/apps/translations/zh-CN.metadata-forms.generated.ts

@@ -153,10 +153,6 @@ export const zhCNMetadataForms: NonNullable<TranslationData['metadataForms']> =
       "fields.options.color": {
         label: "颜色"
       },
-      "fields.options.icon": {
-        label: "图标",
-        helpText: "Lucide 图标名称"
-      },
       "fields.options.description": {
         label: "描述"
       },

packages/spec/src/data/field-rows-option-description.test.ts

@@ -27,11 +27,20 @@
  * The ruling's capability expansion STOPS at these keys: the four inert
  * rich-text editor keys (`toolbar`/`preview`/`minHeight`/`maxHeight`) stay
  * undeclared — the control pins below hold that door shut.
+ *
+ * [#13671] Section 3 was added later and is about the OTHER half of the same
+ * offer-vs-door pair this file already documents. The `icon` control in
+ * section 2 used to assert one thing — the door refuses `icon` — while
+ * `object.form.ts` went on OFFERING an `icon` input, so the file was green
+ * across a live disagreement. Section 3 pins the offer side; the file keeps
+ * its name because the two subjects are one story (`options[]` keys the
+ * authoring form and the publish door must agree about).
  */
 
 import { describe, it, expect } from 'vitest';
 
 import { FieldSchema, SelectOptionSchema } from './field.zod';
+import { objectForm } from './object.form';
 import { FormSelectOptionSchema } from '../ui/view.zod';
 
 // =========================================================================
@@ -187,12 +196,14 @@ describe('SelectOptionSchema accepts `description` (objectui#6153, inherited rul
   });
 
   it('the neighbouring undeclared option keys are still refused — `icon` (control) and `dependsOn` (explicitly not licensed)', () => {
-    // `icon`: offered by the object.form options repeater and declared by
-    // objectui's SelectOptionMetadata, but #5016's option C left it out of
-    // this shape — it stays an unrecognized_keys refusal until someone rules
-    // otherwise. `dependsOn`: the inherited #6153 ruling resolves it
-    // objectui-side (the widget reads the canonical field-level `depends_on`);
-    // declaring a camelCase twin here is explicitly not licensed.
+    // `icon`: declared by objectui's `SelectOptionMetadata` but left out of
+    // this shape by #5016's option C, and #13671 re-measured that reading for
+    // the FIELD-option surface and kept it (section 3). It stays an
+    // unrecognized_keys refusal until someone rules otherwise — what #13671
+    // changed is the OFFER, not this door. `dependsOn`: the inherited #6153
+    // ruling resolves it objectui-side (the widget reads the canonical
+    // field-level `depends_on`); declaring a camelCase twin here is
+    // explicitly not licensed.
     for (const [key, value] of [['icon', 'circle-dot'], ['dependsOn', 'country']] as const) {
       const result = SelectOptionSchema.safeParse({ label: 'Open', value: 'open', [key]: value });
       expect(result.success, `\`${key}\` unexpectedly parsed — an unruled accepted-set expansion`).toBe(false);
@@ -203,3 +214,123 @@ describe('SelectOptionSchema accepts `description` (objectui#6153, inherited rul
     }
   });
 });
+
+// =========================================================================
+// 3. `options[].icon` — the OTHER half of the same offer-vs-door pair
+// =========================================================================
+
+/**
+ * ⚠️ THIS PIN CHANGED SUBJECT (#13671) — read this before "restoring" it.
+ *
+ * The `icon` case in section 2 used to stand alone and assert ONE thing: the
+ * publish door refuses `icon`. That was true and is still true — but while it
+ * held, `object.form.ts`'s options repeater went on OFFERING an `icon` text
+ * input labelled "Lucide icon name", so a Studio author was taught a key the
+ * door rejects and found out at the 422. The pin was green across a live
+ * disagreement because it only ever looked at one side of it.
+ *
+ * #13671 closed the disagreement under ADR-0049 enforce-or-remove, on the
+ * route triage ruled: **the offer was withdrawn, the door was NOT widened.**
+ * So the pin now has two halves and needs both — section 2's `it` for the
+ * door, this section for the offer. ⛔ Neither half alone is the pin: a green
+ * "the door refuses `icon`" says nothing about what the form offers, which is
+ * exactly how the gap survived.
+ *
+ * ## Why remove and not declare
+ *
+ * The premise was measured for THIS surface — a FIELD option — rather than
+ * inherited from #5016, which measured the ACTION-param path (objectui's
+ * `SelectOptionMetadata` does declare `icon`, so the two faces had to be
+ * measured apart). Measured at the `.objectui-sha` pin
+ * `d8ec8d6d4f011b11c8eb1e6dbd364ef206711391` — the console this repo ships —
+ * and again on that repo's `origin/main`, same answer both times, with a live
+ * positive control: the select/multiselect cell renderer
+ * (`packages/fields/src/index.tsx`, the `renderOne` badge/dot branch) reads
+ * `option?.label` and `option?.color` off a `SelectOptionMetadata[]` and never
+ * `option?.icon`, and no field-option render path in that tree reads the key at
+ * all — the single `opt.icon` read there belongs to the config-panel
+ * `ConfigField` vocabulary, whose `icon` is a `React.ReactNode` an authored
+ * field option cannot reach. Declaring `icon` would be an accepted-set
+ * expansion needing a maintainer ruling; if that ruling ever comes, this
+ * section INVERTS (offer restored, door widened, both halves moving together)
+ * rather than being deleted.
+ */
+describe('#13671 — the object.form options repeater offers only keys the door accepts', () => {
+  type FormSpec = Record<string, unknown>;
+
+  /**
+   * Every form-field spec matching `match`, at any depth. Same traversal as
+   * `form-delete-behavior-options.test.ts` (#11410) — sections and `fields`
+   * arrays, which is how a repeater's sub-form hangs off its parent.
+   */
+  function findSpecs(node: unknown, match: (s: FormSpec) => boolean, out: FormSpec[] = []): FormSpec[] {
+    if (!node || typeof node !== 'object') return out;
+    if (Array.isArray(node)) {
+      for (const n of node) findSpecs(n, match, out);
+      return out;
+    }
+    const rec = node as FormSpec;
+    if (match(rec)) out.push(rec);
+    for (const child of ['sections', 'fields'] as const) {
+      if (rec[child]) findSpecs(rec[child], match, out);
+    }
+    return out;
+  }
+
+  /** The one `options` repeater, asserted unique so a second one cannot hide. */
+  function optionsRepeater(): FormSpec {
+    const hits = findSpecs(objectForm, (s) => s.field === 'options' && s.type === 'repeater');
+    expect(hits, 'the object form no longer declares exactly one `options` repeater').toHaveLength(1);
+    return hits[0];
+  }
+
+  /** The input keys that repeater offers per option. */
+  function offeredOptionKeys(): string[] {
+    const sub = optionsRepeater().fields;
+    // An ABSENT list is not a narrower offer — it is the renderer's DERIVED
+    // source (the #11410 lesson): with no `fields` the metadata-admin form
+    // falls through to the JSON Schema, so "no list" would silently re-offer
+    // whatever the schema exposes. The list must be explicit.
+    expect(Array.isArray(sub) && sub.length > 0, 'the options repeater declares no explicit sub-form field list').toBe(true);
+    return (sub as FormSpec[]).map((f) => String(f.field));
+  }
+
+  it('does not offer `icon` — the withdrawn input (THE DEFECT)', () => {
+    expect(offeredOptionKeys()).not.toContain('icon');
+  });
+
+  it('still offers the four inputs that survived, in order', () => {
+    // The positive control for the assertion above: an empty or mangled list
+    // would satisfy `not.toContain('icon')` while having removed the whole
+    // repeater. `description` is here because PR #13669 declared it — ⛔ do
+    // not drop it while editing this list.
+    expect(offeredOptionKeys()).toEqual(['label', 'value', 'color', 'description']);
+  });
+
+  it('offers no input naming a key the publish door refuses — the general invariant', () => {
+    // The class, not the instance: whatever this repeater offers tomorrow, the
+    // door must accept it. Asserted through the door's own behaviour rather
+    // than a hand-copied key list, so it cannot drift from the schema.
+    for (const key of offeredOptionKeys()) {
+      const result = SelectOptionSchema.safeParse({ label: 'Open', value: 'open', [key]: 'probe' });
+      const unrecognized = result.success
+        ? undefined
+        : result.error.issues.find((i) => i.code === 'unrecognized_keys' && JSON.stringify(i).includes(key));
+      expect(
+        unrecognized,
+        `the options repeater offers an input for \`${key}\`, which \`SelectOptionSchema\` refuses at publish `
+          + '— offer and door disagree again (ADR-0049 enforce-or-remove)',
+      ).toBeUndefined();
+    }
+  });
+
+  it('declares exactly one `icon` input in total — the OBJECT-level row, a different subject', () => {
+    // The object form declares two `icon` inputs in total before #13671 and
+    // one after. The survivor is the object's own Lucide icon in Basics, which
+    // `ObjectSchema` declares and Studio renders; an over-broad deletion that
+    // took it out would otherwise look like a pass above.
+    const iconRows = findSpecs(objectForm, (s) => s.field === 'icon');
+    expect(iconRows).toHaveLength(1);
+    expect(String(iconRows[0].helpText ?? '')).toContain('Lucide icon name');
+  });
+});

packages/spec/src/data/object.form.ts

@@ -147,6 +147,33 @@ export const objectForm = defineForm({
             { field: 'scale', type: 'number', helpText: 'Decimal places', visibleWhen: "data.type in ['number','currency','percent']" },
 
             // Selection options
+            //
+            // The offered inputs are exactly `SelectOptionSchema`'s authorable
+            // keys, minus `visibleWhen` (a CEL predicate, not a repeater text
+            // input). An `icon` input used to sit between `color` and
+            // `description` and was withdrawn under ADR-0049 enforce-or-remove:
+            // the option shape is strict and has never declared `icon`, so a
+            // Lucide name typed there was an `unrecognized_keys` refusal at
+            // publish — the author found out at the 422, the same
+            // offer-vs-door class #11410 and #12868 retired elsewhere.
+            //
+            // Remove rather than declare, on a premise measured for THIS
+            // surface rather than inherited from #5016's action-param reading:
+            // objectui declares `icon` on `SelectOptionMetadata`, but no
+            // field-option render path READS it. Measured at the
+            // `.objectui-sha` pin `d8ec8d6d4f011b11c8eb1e6dbd364ef206711391`
+            // (the console this repo ships) and again on that repo's
+            // `origin/main`, same answer both times, with a live positive
+            // control: the select/multiselect cell renderer
+            // (`packages/fields/src/index.tsx`, the `renderOne` badge/dot
+            // branch) reads `option?.label` and `option?.color` off that very
+            // `SelectOptionMetadata[]` and never `option?.icon`. The only
+            // `opt.icon` read in that tree belongs to the config-panel
+            // `ConfigField` vocabulary, whose `icon` is a `React.ReactNode` an
+            // authored field option cannot reach. Declaring it instead would
+            // be an accepted-set expansion, which needs a maintainer ruling.
+            // `field-rows-option-description.test.ts` pins both halves — the
+            // schema still refuses `icon`, and this list no longer offers it.
             {
               field: 'options',
               type: 'repeater',
@@ -156,7 +183,6 @@ export const objectForm = defineForm({
                 { field: 'label', type: 'text', required: true },
                 { field: 'value', type: 'text', required: true },
                 { field: 'color', type: 'color' },
-                { field: 'icon', type: 'text', helpText: 'Lucide icon name' },
                 { field: 'description', type: 'text' },
               ],
             },