From be690be131ae4ba43751187fbf242202fac27d43 Mon Sep 17 00:00:00 2001
From: Claude <pm@objectstack.ai>
Date: Sun, 23 Aug 2026 01:48:27 +0000
Subject: [PATCH 1/2] fix(components): declare the I18nLabel arm on
 element:text_input's label / placeholder / description (#5717)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The renderer has resolved all three keys through `pickLocalized` since it was
written, while the `ComponentMeta` entries still declared a single `'string'`
arm — so `validateTree` reported `type-mismatch` on a locale map the contract
admits and the screen renders correctly in the viewer's language.

The inverse of #5590 / #5637, where the declaration correctly stayed narrow
until the render site caught up. Here the render site was never behind.

Per-key, not blanket: `defaultValue` keeps `['string','number']` (no object arm
in its contract) and the console specimen control asserting that stays green.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EuPCi56cnGyykygi3z9w4m
---
 .changeset/text-input-i18n-label-arms-5717.md |  45 ++++
 .../component-input-union-specimens.test.ts   | 203 +++++++++++++++++-
 .../text-input-i18n-label-arms.test.tsx       | 185 ++++++++++++++++
 .../text-input-inputs-spec-parity.test.ts     | 108 ++++++++++
 .../src/renderers/basic/text-input.tsx        |  76 ++++++-
 5 files changed, 613 insertions(+), 4 deletions(-)
 create mode 100644 .changeset/text-input-i18n-label-arms-5717.md
 create mode 100644 packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx

diff --git a/.changeset/text-input-i18n-label-arms-5717.md b/.changeset/text-input-i18n-label-arms-5717.md
new file mode 100644
index 0000000000..f8cbd403a3
--- /dev/null
+++ b/.changeset/text-input-i18n-label-arms-5717.md
@@ -0,0 +1,45 @@
+---
+'@object-ui/components': patch
+---
+
+`element:text_input` now DECLARES the inline-translation arm on `label`,
+`placeholder` and `description`, so the manifest gate stops reporting
+`type-mismatch` on a locale map its own renderer has always resolved correctly
+(objectui#5717).
+
+`@objectstack/spec` types all three keys as the `I18nLabel` union
+(`string | Record<string, string>`) — measured on the installed 17.1.0 pin, per
+key, from the schema's own verdicts — and `text-input.tsx` has resolved all
+three through `pickLocalized` at their read sites since it was written. Only the
+`ComponentMeta` entries stayed at a single `'string'` arm. Driven through the
+same `manifestFromConfigs` + `validateTree` pair the JSX-page compiler and the
+save gate use, an author writing `{ en: 'Owner', 'zh-CN': '负责人' }` got three
+warnings on a write that renders correctly in the viewer's language:
+
+```
+<element:text_input> prop "label" expected a string
+<element:text_input> prop "placeholder" expected a string
+<element:text_input> prop "description" expected a string
+```
+
+That is the INVERSE of the direction the rest of this family moved in.
+`element:record_picker.emptyText` (objectui#5590) and that block's `label` /
+`placeholder` (objectui#5637) each held one arm for exactly as long as their
+render site dropped the map, and gained the object arm in the change that taught
+the render site to resolve it — never declare an arm the renderer drops. Here
+the render site was never behind, so the same rule's other half applies:
+withholding an arm the renderer resolves is the false declaration in the other
+direction, and noise on legal writes trains authors (AI authors included) to
+dismiss the `unknown-prop` and `type-mismatch` reports that are real.
+
+Per-key, not blanket. `defaultValue` on this same block keeps `['string',
+'number']` — its contract has no object arm, measured the same way — and the
+console specimen file keeps asserting that an `I18N_MAP` there still reports
+`type-mismatch`. That control is what makes this a widening of three keys rather
+than of a component.
+
+All three keys also gain a `description` written from what the renderer does
+rather than from restating the contract: where each one lands in the rendered
+output (a `<label>` above the field, the native `placeholder` attribute inside
+it, a `<p>` below it), when each is omitted, and the locale fallback chain the
+read site follows. No renderer behaviour changed.
diff --git a/apps/console/src/__tests__/component-input-union-specimens.test.ts b/apps/console/src/__tests__/component-input-union-specimens.test.ts
index ff202126c2..31fcb3448d 100644
--- a/apps/console/src/__tests__/component-input-union-specimens.test.ts
+++ b/apps/console/src/__tests__/component-input-union-specimens.test.ts
@@ -57,7 +57,11 @@ import { describe, it, expect } from 'vitest';
 import { ComponentRegistry } from '@object-ui/core';
 import { manifestFromConfigs, validateTree } from '@object-ui/sdui-parser';
 import type { Diagnostic, SchemaElement } from '@object-ui/sdui-parser';
-import { ElementButtonPropsSchema, ElementTextPropsSchema } from '@objectstack/spec/ui';
+import {
+  ElementButtonPropsSchema,
+  ElementTextInputPropsSchema,
+  ElementTextPropsSchema,
+} from '@objectstack/spec/ui';
 import '@object-ui/components';
 import '../register-plugins';
 
@@ -347,3 +351,200 @@ describe('objectui#4970 — element:text.content / element:button.label declare
     expect(codesFor({ type: 'element:button', label: ['Save'] })).toContain('type-mismatch');
   });
 });
+
+/**
+ * objectui#5717 — `element:text_input`'s `label` / `placeholder` / `description`,
+ * the trio whose declaration lagged a render site that was never behind.
+ *
+ * Every specimen above earned its object arm in the change that taught its
+ * RENDER SITE to resolve the map: `element:record_picker.emptyText`
+ * (objectui#5590) and that block's `label` / `placeholder` (objectui#5637) each
+ * held `['string']` for exactly as long as their renderer dropped the map. This
+ * block is the INVERSE and the reason it needed its own card:
+ * `text-input.tsx` has resolved all three keys through `pickLocalized` since it
+ * was written, so the map always reached the screen correctly in the viewer's
+ * language — and the declaration still said `'string'`, so `validateTree`
+ * reported `type-mismatch` on a legal write. Measured on `d8afbe519` before the
+ * fix, through this file's own `manifestFromConfigs` + `validateTree` pair:
+ *
+ *     label        declaredArms="string"  ["type-mismatch :: <element:text_input> prop \"label\" expected a string"]
+ *     placeholder  declaredArms="string"  ["type-mismatch :: <element:text_input> prop \"placeholder\" expected a string"]
+ *     description  declaredArms="string"  ["type-mismatch :: <element:text_input> prop \"description\" expected a string"]
+ *
+ * ## Why this file, and not only the block's spec-parity test
+ *
+ * `packages/components/src/__tests__/text-input-inputs-spec-parity.test.ts`
+ * asserts declared-arms == spec-accepted-arms per key, which is the DECLARATION
+ * half. It cannot see the defect: the defect is a DIAGNOSTIC emitted by
+ * `validateTree` over a manifest, and a type-level or declaration-level
+ * assertion never runs that path. This file drives the same pair the JSX-page
+ * compiler (`packages/components/src/renderers/layout/page.tsx:462`) and the
+ * save gate use, which is where the warning was actually reaching authors — so
+ * without a pin here the fix could regress with every parity assertion still
+ * green.
+ *
+ * ## Controls, and the one that is not local to this block
+ *
+ * Each specimen carries a value matching NEITHER arm, for the reason the #3832
+ * block states: "no diagnostic" is also what a silenced check looks like. This
+ * block has a second control that lives one `it` away rather than inside it —
+ * `element:text_input.defaultValue` above, whose spec type is `string | number`
+ * and whose `I18N_MAP` case must STILL report `type-mismatch`. That is the
+ * assertion which makes this widening per-key rather than blanket, and it is on
+ * the same component: had the object arm been applied to the block instead of
+ * to the three keys whose contract admits it, that case is what goes green.
+ */
+describe('objectui#5717 — element:text_input label / placeholder / description declare their real unions', () => {
+  it('the specimen block is registered (reachability before absence)', () => {
+    // Without this, an unregistered or renamed block satisfies every
+    // "no type-mismatch" assertion below by never being validated at all —
+    // an absent block reports `unknown-component`, a different code, and the
+    // filters here are per-code by design.
+    expect(manifest.components['element:text_input'], 'element:text_input is not registered').toBeDefined();
+  });
+
+  it('the installed spec accepts the string and inline-map arms on all three keys, and no others', () => {
+    // Guards the derivation before anything is compared against it: a schema
+    // that rejected every probe (a renamed key, a new sibling required key)
+    // would return `[]` and make the three comparisons below agree vacuously.
+    //
+    // Measured on the `@objectstack/spec` 17.1.0 pin — the same discipline the
+    // #4970 block adopted, and the reason these arms are honest rather than
+    // copied from the card that reported them.
+    expect(specAcceptedArms(ElementTextInputPropsSchema, 'label')).toEqual(['string', 'object']);
+    expect(specAcceptedArms(ElementTextInputPropsSchema, 'placeholder')).toEqual([
+      'string',
+      'object',
+    ]);
+    expect(specAcceptedArms(ElementTextInputPropsSchema, 'description')).toEqual([
+      'string',
+      'object',
+    ]);
+  });
+
+  it('the sibling key whose contract has NO object arm is measured the same way', () => {
+    // The separation asserted from the CONTRACT rather than from the
+    // declaration, so "why is defaultValue different" is answered by evidence
+    // in the same vocabulary. Without this line the per-key control below reads
+    // as a convention; with it, it reads as the contract.
+    expect(specAcceptedArms(ElementTextInputPropsSchema, 'defaultValue')).toEqual([
+      'string',
+      'number',
+    ]);
+  });
+
+  it('`element:text_input.label` accepts the inline translation map', () => {
+    expect([...declaredArms('element:text_input', 'label')].sort()).toEqual(
+      [...specAcceptedArms(ElementTextInputPropsSchema, 'label')].sort(),
+    );
+
+    expect(
+      diagnose({ type: 'element:text_input', label: I18N_MAP }).filter(
+        (d) => d.code === 'type-mismatch',
+      ),
+    ).toEqual([]);
+
+    // …and the plain-string arm keeps validating clean (that half must not move).
+    expect(
+      diagnose({ type: 'element:text_input', label: 'Workspace' }).filter(
+        (d) => d.code === 'type-mismatch',
+      ),
+    ).toEqual([]);
+
+    // CONTROL — values matching NEITHER arm are still reported. The spec refuses
+    // both (measured above), so the gate must too.
+    expect(codesFor({ type: 'element:text_input', label: 42 })).toContain('type-mismatch');
+    expect(codesFor({ type: 'element:text_input', label: ['Workspace'] })).toContain(
+      'type-mismatch',
+    );
+  });
+
+  it('`element:text_input.placeholder` accepts the inline translation map', () => {
+    expect([...declaredArms('element:text_input', 'placeholder')].sort()).toEqual(
+      [...specAcceptedArms(ElementTextInputPropsSchema, 'placeholder')].sort(),
+    );
+
+    expect(
+      diagnose({ type: 'element:text_input', placeholder: I18N_MAP }).filter(
+        (d) => d.code === 'type-mismatch',
+      ),
+    ).toEqual([]);
+    expect(
+      diagnose({ type: 'element:text_input', placeholder: 'acme' }).filter(
+        (d) => d.code === 'type-mismatch',
+      ),
+    ).toEqual([]);
+
+    // CONTROL
+    expect(codesFor({ type: 'element:text_input', placeholder: true })).toContain('type-mismatch');
+    expect(codesFor({ type: 'element:text_input', placeholder: ['acme'] })).toContain(
+      'type-mismatch',
+    );
+  });
+
+  it('`element:text_input.description` accepts the inline translation map', () => {
+    // Declared together with the two label-ish keys although its destination in
+    // the rendered output differs (a `<p>` below the field, not the `<label>`
+    // above it or the native attribute inside it). Destination is not what
+    // decides an arm: `ComponentInput.type`'s two conditions are that the
+    // contract accepts the shape and the renderer resolves it, and this key
+    // satisfies both identically — same `pickLocalized` call site, same
+    // `string | Record<string, string>` contract, both measured per key rather
+    // than inherited from its neighbours.
+    expect([...declaredArms('element:text_input', 'description')].sort()).toEqual(
+      [...specAcceptedArms(ElementTextInputPropsSchema, 'description')].sort(),
+    );
+
+    expect(
+      diagnose({ type: 'element:text_input', description: I18N_MAP }).filter(
+        (d) => d.code === 'type-mismatch',
+      ),
+    ).toEqual([]);
+    expect(
+      diagnose({ type: 'element:text_input', description: 'We use this to name your workspace.' }).filter(
+        (d) => d.code === 'type-mismatch',
+      ),
+    ).toEqual([]);
+
+    // CONTROL
+    expect(codesFor({ type: 'element:text_input', description: 42 })).toContain('type-mismatch');
+    expect(codesFor({ type: 'element:text_input', description: ['note'] })).toContain(
+      'type-mismatch',
+    );
+  });
+
+  it('all three on ONE node produce no type-mismatch — the authored shape the card reported', () => {
+    // The card's own reproduction: an author writes the map on every key of the
+    // trio at once, which is the write the gate used to answer with three
+    // warnings. Asserted as a whole node because that is the unit an author
+    // saves, and because three keys clean individually would not by itself
+    // prove the node is.
+    const authored = {
+      type: 'element:text_input',
+      id: 'ws_input',
+      label: I18N_MAP,
+      placeholder: I18N_MAP,
+      description: I18N_MAP,
+    };
+    expect(diagnose(authored).filter((d) => d.code === 'type-mismatch')).toEqual([]);
+
+    // CONTROL for the whole-node form: one bad key among three good ones is
+    // still reported, so the assertion above cannot be satisfied by a node that
+    // stopped being validated.
+    expect(
+      codesFor({ ...authored, description: ['note'] }),
+    ).toContain('type-mismatch');
+  });
+
+  it('the widening did NOT reach `defaultValue`, whose contract has no object arm', () => {
+    // The per-key control, restated at this block's own altitude. The `it` above
+    // for `defaultValue` owns the canonical assertion; this one fails for a
+    // DIFFERENT reason — a blanket widening applied to the component rather than
+    // to the three keys — and names #5717 so the next reader of a red here knows
+    // which change to look at.
+    expect(declaredArms('element:text_input', 'defaultValue')).not.toContain('object');
+    expect(codesFor({ type: 'element:text_input', defaultValue: I18N_MAP })).toContain(
+      'type-mismatch',
+    );
+  });
+});
diff --git a/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx b/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx
new file mode 100644
index 0000000000..afa096c5ff
--- /dev/null
+++ b/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx
@@ -0,0 +1,185 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ *
+ * `element:text_input` — `label` / `placeholder` / `description` resolve the
+ * inline locale map their declaration now advertises (objectui#5717).
+ *
+ * ## Why this file exists when the renderer was never the broken half
+ *
+ * #5717 is a DECLARATION fix: the three `ComponentMeta` arms said `'string'`
+ * while `text-input.tsx` had resolved all three through `pickLocalized` since it
+ * was written, so the manifest gate reported `type-mismatch` on a write the
+ * screen rendered correctly. Nothing in the renderer changed, and nothing here
+ * was red before the fix.
+ *
+ * That is precisely what makes this file load-bearing rather than ceremonial.
+ * `ComponentInput.type` permits an arm on two conditions — the contract accepts
+ * the shape AND the renderer resolves it — and after #5717 the second condition
+ * is what the declaration rests on while NOTHING pinned it for these three keys.
+ * `inline-locale-label-read-sites.test.tsx` next door covers `schema.label`
+ * (the BaseSchema key) on three other renderers; these are
+ * `schema.properties.*` on this one, a different read path in a different file.
+ * Delete the `pickLocalized` calls today and every #5717 assertion stays green:
+ * the declared arms still match the contract, the gate still emits nothing, and
+ * the map reaches the screen as a React child — which is the failure mode
+ * `inline-locale-label-read-sites.test.tsx` measured as a THROW, not a
+ * mis-render. This file is what turns that red, so the arms cannot outlive the
+ * behaviour that justifies them.
+ *
+ * ## Why the second locale is load-bearing, not decoration
+ *
+ * A case that only ever asserted the ENGLISH string would pass against any
+ * resolver that just reached for `.en` — including one that ignores the active
+ * language entirely. The `zh-CN` cases are what separate real locale resolution
+ * from an `.en` pick, which is the property `pickLocalized` has and the reason
+ * the descriptions promise it.
+ *
+ * The renderer is invoked DIRECTLY through the registry rather than through
+ * `SchemaRenderer`, for the reason `inline-locale-label-read-sites.test.tsx`
+ * states: `SchemaRenderer` injects its own props around a renderer, so a test
+ * driven through it can be green in both directions.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { I18nProvider } from '@object-ui/i18n';
+import { ComponentRegistry } from '@object-ui/core';
+// Registers `element:text_input` at module scope, not in a hook
+// (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+/** The inline locale map an author writes; `zh-CN` exists so a switch is observable. */
+const INLINE_MAP = { en: 'Owner', 'zh-CN': '负责人' } as const;
+
+function renderInput(properties: Record<string, unknown>, language = 'en') {
+  const C = ComponentRegistry.get('element:text_input') as React.ComponentType<any>;
+  if (!C) throw new Error('element:text_input is not registered');
+  return render(
+    <I18nProvider
+      persistLanguage={false}
+      config={{ defaultLanguage: language, detectBrowserLanguage: false }}
+    >
+      {/* eslint-disable-next-line react-hooks/static-components -- ComponentRegistry.get returns the registered component (stable), not one created during render */}
+      <C schema={{ type: 'element:text_input', id: 'ws_input', properties }} />
+    </I18nProvider>,
+  );
+}
+
+/** The `<p>` the renderer puts `description` in, below the field. */
+const descriptionNode = (container: HTMLElement) =>
+  container.querySelector('p.text-muted-foreground');
+
+describe('element:text_input — the I18nLabel trio resolves at the read site (objectui#5717)', () => {
+  it('renders all three destinations at all (reachability before absence)', () => {
+    // Without this, every "the text is X" assertion below would be satisfied
+    // just as well by a renderer that rendered none of the three — each is
+    // omitted entirely when its key is absent, so absence is silent here.
+    const { container } = renderInput({
+      label: 'Workspace',
+      placeholder: 'acme',
+      description: 'Used to name your workspace.',
+    });
+    expect(screen.getByTestId('text-input')).toBeInTheDocument();
+    expect(container.querySelector('label')?.textContent).toBe('Workspace');
+    expect(container.querySelector('input')?.getAttribute('placeholder')).toBe('acme');
+    expect(descriptionNode(container)?.textContent).toBe('Used to name your workspace.');
+  });
+
+  it('resolves the map to the active language on all three keys at once', () => {
+    // The authored node the card reported, and the case that separates real
+    // resolution from an `.en` pick.
+    const { container } = renderInput(
+      { label: INLINE_MAP, placeholder: INLINE_MAP, description: INLINE_MAP },
+      'zh-CN',
+    );
+    expect(container.querySelector('label')?.textContent).toBe('负责人');
+    expect(container.querySelector('input')?.getAttribute('placeholder')).toBe('负责人');
+    expect(descriptionNode(container)?.textContent).toBe('负责人');
+  });
+
+  it('resolves the SAME maps differently for a different language', () => {
+    const { container } = renderInput(
+      { label: INLINE_MAP, placeholder: INLINE_MAP, description: INLINE_MAP },
+      'en',
+    );
+    expect(container.querySelector('label')?.textContent).toBe('Owner');
+    expect(container.querySelector('input')?.getAttribute('placeholder')).toBe('Owner');
+    expect(descriptionNode(container)?.textContent).toBe('Owner');
+  });
+
+  it('keeps the three keys in their own destinations', () => {
+    // Distinct values per key, because the three-identical-maps case above
+    // cannot tell "each key reached its own destination" from "one value was
+    // rendered three times". This is also the evidence behind declaring the
+    // object arm on `description` alongside the two label-ish keys: the
+    // destinations genuinely differ — a `<label>` above, a native attribute
+    // inside, a `<p>` below — and the read path is identical for all three.
+    const { container } = renderInput(
+      {
+        label: { en: 'L', 'zh-CN': '标签' },
+        placeholder: { en: 'P', 'zh-CN': '提示' },
+        description: { en: 'D', 'zh-CN': '说明' },
+      },
+      'zh-CN',
+    );
+    expect(container.querySelector('label')?.textContent).toBe('标签');
+    expect(container.querySelector('input')?.getAttribute('placeholder')).toBe('提示');
+    expect(descriptionNode(container)?.textContent).toBe('说明');
+  });
+
+  it('falls back from a region tag to the base language the author wrote', () => {
+    // Author wrote `zh`; viewer is `zh-CN`. Pins a limb past "exact match", so
+    // a resolver that only ever hit the exact key could not satisfy this file.
+    const { container } = renderInput({ label: { en: 'Owner', zh: '负责人' } }, 'zh-CN');
+    expect(container.querySelector('label')?.textContent).toBe('负责人');
+  });
+
+  it('passes plain strings through unchanged, in any language', () => {
+    // CONTROL, same keys and same read sites as the probes: capable of failing —
+    // a resolution that mangled the string arm turns this red, and the string
+    // arm is the half that must not move.
+    const { container } = renderInput(
+      { label: 'Workspace', placeholder: 'acme', description: 'Used to name it.' },
+      'zh-CN',
+    );
+    expect(container.querySelector('label')?.textContent).toBe('Workspace');
+    expect(container.querySelector('input')?.getAttribute('placeholder')).toBe('acme');
+    expect(descriptionNode(container)?.textContent).toBe('Used to name it.');
+  });
+
+  it('omits label and description entirely when a map resolves to nothing', () => {
+    // The renderer guards all three reads with a truthiness test, and
+    // `pickLocalized` spells a total miss as `''`. Pinned because the
+    // descriptions published in #5717 promise exactly this — "OMITTED entirely
+    // when the key is absent or resolves to an empty string" — and because an
+    // author debugging a vanished label needs the behaviour to be stable.
+    const { container } = renderInput({ label: {}, placeholder: {}, description: {} }, 'zh-CN');
+    expect(screen.getByTestId('text-input')).toBeInTheDocument();
+    expect(container.querySelector('label')).toBeNull();
+    expect(descriptionNode(container)).toBeNull();
+    // `placeholder` is an ATTRIBUTE, so its miss is spelled by absence of the
+    // attribute rather than by an empty one (`placeholder || undefined`).
+    expect(container.querySelector('input')?.hasAttribute('placeholder')).toBe(false);
+  });
+
+  it('never renders a raw map into the DOM on any of the three keys', () => {
+    // The failure this whole file guards against, asserted as its own case
+    // rather than inferred: a read site that stopped resolving would put the
+    // object in a React child position — measured elsewhere in this package as a
+    // THROW, "Objects are not valid as a React child" — or stringify it into an
+    // attribute as `[object Object]`. Either way the arms declared in #5717
+    // would be advertising a shape that never reaches the screen.
+    const { container } = renderInput(
+      { label: INLINE_MAP, placeholder: INLINE_MAP, description: INLINE_MAP },
+      'zh-CN',
+    );
+    expect(container.textContent).not.toContain('[object Object]');
+    expect(container.querySelector('input')?.getAttribute('placeholder')).not.toBe(
+      '[object Object]',
+    );
+  });
+});
diff --git a/packages/components/src/__tests__/text-input-inputs-spec-parity.test.ts b/packages/components/src/__tests__/text-input-inputs-spec-parity.test.ts
index 3e541fa5bd..44c9fbce6d 100644
--- a/packages/components/src/__tests__/text-input-inputs-spec-parity.test.ts
+++ b/packages/components/src/__tests__/text-input-inputs-spec-parity.test.ts
@@ -202,3 +202,111 @@ describe('element:text_input — registry inputs vs @objectstack/spec', () => {
     expect(ElementTextInputPropsSchema.safeParse({}).data).not.toHaveProperty('defaultValue');
   });
 });
+
+/**
+ * The `I18nLabel` trio — `label` / `placeholder` / `description` (objectui#5717).
+ *
+ * Same discipline as the `defaultValue` case above and for the same reason: the
+ * arms are DERIVED from the spec's verdicts, never restated. Restating them
+ * would pin the declaration and leave the fact the declaration exists FOR — that
+ * the declared arms are the ones the contract accepts — unmeasured.
+ *
+ * ## Why these three needed a card of their own
+ *
+ * `element:record_picker.emptyText` (objectui#5590) and that block's `label` /
+ * `placeholder` (objectui#5637) each held a single `'string'` arm for exactly as
+ * long as their RENDER SITE dropped the map, and gained the object arm in the
+ * change that taught the render site to resolve it — the order
+ * `ComponentInput.type` prescribes. This block is the inverse: `text-input.tsx`
+ * has resolved all three keys through `pickLocalized` since it was written, so
+ * the map always reached the screen resolved, and only the declaration stayed
+ * narrow. `ComponentInput.type`'s rule is symmetric and condemns that half in
+ * its own words — withholding an arm the renderer resolves makes the manifest
+ * gate report `type-mismatch` on a legal write.
+ *
+ * ## What this file can and cannot see
+ *
+ * It sees the DECLARATION half — declared arms against the contract's own
+ * verdicts. It cannot see the defect itself, which is a `type-mismatch`
+ * diagnostic emitted by `validateTree` over a manifest; that path is driven in
+ * `apps/console/src/__tests__/component-input-union-specimens.test.ts`, where
+ * this block gained its pin in the same change. Neither file subsumes the other:
+ * this one goes red when the declaration and the contract disagree, that one
+ * when the gate and the declaration do.
+ */
+describe('element:text_input — the I18nLabel trio declares its real union (objectui#5717)', () => {
+  /**
+   * One representative value per coarse arm, in the vocabulary `checkType`'s
+   * `armAccepts` uses (`packages/sdui-parser/src/validate.ts`) — the same probe
+   * table `component-input-union-specimens.test.ts` derives with, so the two
+   * files cannot disagree about what "the object arm" means.
+   *
+   * `['Owner']` earns its place: the `'object'` arm accepts a non-null
+   * non-array object and nothing else, so an array is the value that tells
+   * "declares the object arm" apart from "stopped checking non-primitives".
+   */
+  const COARSE_ARM_PROBES: ReadonlyArray<readonly [string, unknown]> = [
+    ['string', 'Owner'],
+    ['object', { en: 'Owner', 'zh-CN': '负责人' }],
+    ['number', 42],
+    ['boolean', true],
+    ['array', ['Owner']],
+  ];
+
+  const specAcceptedArms = (key: string): string[] =>
+    COARSE_ARM_PROBES.filter(
+      ([, value]) => ElementTextInputPropsSchema.safeParse({ [key]: value } as never).success,
+    ).map(([arm]) => arm);
+
+  const TRIO = ['label', 'placeholder', 'description'] as const;
+
+  it('the spec accepts exactly the string and inline-map arms on all three keys', () => {
+    // Guards the derivation before anything is compared against it: a schema
+    // that refused every probe (a renamed key, a new sibling required key)
+    // returns `[]` and would make the per-key comparisons below agree
+    // vacuously. Measured on the installed 17.1.0 pin.
+    for (const key of TRIO) {
+      expect(specAcceptedArms(key), key).toEqual(['string', 'object']);
+    }
+  });
+
+  it.each(TRIO)('`%s` declares the arms the contract accepts, and only those', (key) => {
+    // Compared as a SET in both directions: every declared arm is a shape the
+    // spec accepts, and every shape the spec accepts has an arm. Either side
+    // moving turns this red — a spec release that drops the map arm, or a
+    // declaration that grows an arm the spec rejects.
+    expect(input(key)).toBeDefined();
+    const declared = input(key)?.type;
+    const arms = Array.isArray(declared) ? declared : [declared];
+    expect([...arms].sort()).toEqual([...specAcceptedArms(key)].sort());
+  });
+
+  it.each(TRIO)('`%s` carries a description written from what the renderer does', (key) => {
+    // The arms say WHICH shapes are legal; only the description says what the
+    // renderer then does with them, and `ComponentInput.type`'s ruling
+    // (maintainer, 2026-08-17) makes the description the expression ceiling for
+    // everything the coarse arm cannot carry. Each of these three has a
+    // different destination in the rendered output, which is exactly the kind of
+    // fact an author cannot get from `['string','object']`.
+    const description = input(key)?.description ?? '';
+    expect(description).not.toBe('');
+    // The map arm is only discoverable if the description teaches the shape.
+    expect(description).toMatch(/zh-CN/);
+    // …and the resolution is locale-aware, not an `en` pick — the property the
+    // trio's read site actually has and the half an author plans around.
+    expect(description).toMatch(/language/i);
+  });
+
+  it('`defaultValue` is NOT part of the trio — the contract is what separates it', () => {
+    // The control that keeps the widening per-key rather than blanket, asserted
+    // here from the CONTRACT so the separation has a reason and not just a
+    // convention. Its console-side twin is the `I18N_MAP` case on
+    // `element:text_input.defaultValue` in
+    // `component-input-union-specimens.test.ts`, which must keep REPORTING
+    // `type-mismatch`.
+    expect(specAcceptedArms('defaultValue')).toEqual(['string', 'number']);
+    const declared = input('defaultValue')?.type;
+    const arms = Array.isArray(declared) ? declared : [declared];
+    expect(arms).not.toContain('object');
+  });
+});
diff --git a/packages/components/src/renderers/basic/text-input.tsx b/packages/components/src/renderers/basic/text-input.tsx
index d75d8535b7..53551e539f 100644
--- a/packages/components/src/renderers/basic/text-input.tsx
+++ b/packages/components/src/renderers/basic/text-input.tsx
@@ -143,8 +143,61 @@ ComponentRegistry.register('text_input', ElementTextInputRenderer, {
   // reverse half of the parity gate in
   // `apps/console/src/__tests__/registry-inputs-spec-parity.test.ts`.
   inputs: [
-    { name: 'label', type: 'string', label: 'Label' },
-    { name: 'placeholder', type: 'string', label: 'Placeholder' },
+    // ── The `I18nLabel` trio — `label`, `placeholder` and `description` ──────
+    //
+    // TWO arms each, declared in the change that makes the gate agree with the
+    // contract (objectui#5717). The ORDER these were earned in is the inverse
+    // of the rest of the family, and that is the whole point of this block.
+    //
+    // `element:record_picker.emptyText` (objectui#5590) and that block's
+    // `label` / `placeholder` (objectui#5637) each held a single `'string'` arm
+    // while their render site passed the value straight into a text node, and
+    // gained the object arm in the very change that taught the render site to
+    // resolve it — the order `ComponentInput.type` prescribes: never declare an
+    // arm the renderer drops.
+    //
+    // Here the render site was NEVER behind. `pickLocalized(props.label,
+    // language)` and its two siblings above have resolved the inline locale map
+    // since this renderer was written, so the map has always reached the screen
+    // correctly in the viewer's language. Only the declaration stayed at one
+    // arm — which is the SAME rule's other half, and `ComponentInput.type`
+    // states it in those words: withholding an arm the renderer resolves makes
+    // the manifest gate report `type-mismatch` on a legal write, "one platform
+    // authority contradicting itself on the write it just recommended".
+    // Measured before this change, through the same `manifestFromConfigs` +
+    // `validateTree` pair the JSX-page compiler (`renderers/layout/page.tsx`)
+    // and the save gate use:
+    //
+    //     <element:text_input> prop "label" expected a string
+    //     <element:text_input> prop "placeholder" expected a string
+    //     <element:text_input> prop "description" expected a string
+    //
+    // …on `{ en: 'Owner', 'zh-CN': '负责人' }`, a value the contract accepts on
+    // all three keys.
+    //
+    // The arms are MEASURED, never copied from the card: the spec's own
+    // verdicts are what
+    // `packages/components/src/__tests__/text-input-inputs-spec-parity.test.ts`
+    // compares this declaration against, per key, so a spec release that drops
+    // an arm and a declaration that grows one the spec rejects are both red.
+    // `defaultValue` below deliberately does NOT join this trio — its contract
+    // is `string | number` with no object arm, and the console specimen file
+    // keeps that separation as the control that makes this widening per-key
+    // rather than blanket.
+    {
+      name: 'label',
+      type: ['string', 'object'],
+      label: 'Label',
+      description:
+        'Caption rendered ABOVE the input, in a `<label>` element — tied to the field by `htmlFor` when the node carries an `id`, so clicking it focuses the input. Display-only, and OMITTED entirely when the key is absent or resolves to an empty string; because the `required` asterisk is drawn on this element, a required input with no label shows no asterisk at all. Accepts either a plain string or an inline per-locale map (`{ en: "Owner", "zh-CN": "负责人" }`) — the `I18nLabel` union the contract admits on this key — and the renderer resolves the map against the active language at the read site, falling back through base language, a region-qualified sibling, `default`, then `en`, and finally to any remaining entry.',
+    },
+    {
+      name: 'placeholder',
+      type: ['string', 'object'],
+      label: 'Placeholder',
+      description:
+        'Prompt shown INSIDE the field while it is empty, as the native input\'s `placeholder` attribute — it disappears as the user types and never becomes the input\'s value, so it is never what a bound page variable receives. Display-only, with no renderer default: an absent key means no placeholder, and an authored empty string (or a map no locale limb resolves) drops the attribute altogether rather than setting an empty one. Accepts either a plain string or an inline per-locale map (`{ en: "Owner", "zh-CN": "负责人" }`), resolved against the active language with the same fallback chain as `label`.',
+    },
     {
       name: 'inputType',
       type: 'enum',
@@ -180,7 +233,24 @@ ComponentRegistry.register('text_input', ElementTextInputRenderer, {
     },
     { name: 'required', type: 'boolean', label: 'Required' },
     { name: 'disabled', type: 'boolean', label: 'Disabled' },
-    { name: 'description', type: 'string', label: 'Description' },
+    {
+      name: 'description',
+      // The third arm-widening of the trio commented above `label`, and the one
+      // worth saying explicitly travels WITH the other two: its destination in
+      // the rendered output differs (a `<p>` below the field, not the `<label>`
+      // above it or the native attribute inside it), but destination is not
+      // what decides an arm. The two conditions `ComponentInput.type` names are
+      // "the contract accepts it" and "the renderer resolves it", and this key
+      // satisfies both identically to `label` — same `pickLocalized` call, same
+      // `string | Record<string, string>` contract, measured per key. A
+      // destination-based split would have declared an arm on one key and
+      // withheld it on another for a difference neither the gate nor the
+      // contract can see.
+      type: ['string', 'object'],
+      label: 'Description',
+      description:
+        'Helper text rendered BELOW the input, in its own `<p>` — a different destination from `label` (above, in a `<label>`) and `placeholder` (inside the field), reached by the same read path. Display-only, and OMITTED entirely when the key is absent or resolves to an empty string. Accepts either a plain string or an inline per-locale map (`{ en: "Owner", "zh-CN": "负责人" }`), resolved against the active language with the same fallback chain as `label`. Presentational only: the renderer renders it as a sibling paragraph and does not tie it to the field with `aria-describedby`, so a screen reader does not announce it together with the input — instructions a user must not miss belong in `label`.',
+    },
   ],
 });
 

From 9711f5ca87410dc8a98cb8365fc245677bd910d9 Mon Sep 17 00:00:00 2001
From: Claude <pm@objectstack.ai>
Date: Sun, 23 Aug 2026 02:29:43 +0000
Subject: [PATCH 2/2] test(components): state the static-components reason as
 prose, not as an inert lint directive
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ESLint reports the copied `eslint-disable-next-line react-hooks/static-components`
as UNUSED under this repo's own config — the rule never fires at that site. The
reason the pattern is safe is worth keeping; the suppression that never
suppressed anything is not.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EuPCi56cnGyykygi3z9w4m
---
 .../src/__tests__/text-input-i18n-label-arms.test.tsx     | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx b/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx
index afa096c5ff..f33d25407e 100644
--- a/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx
+++ b/packages/components/src/__tests__/text-input-i18n-label-arms.test.tsx
@@ -63,7 +63,13 @@ function renderInput(properties: Record<string, unknown>, language = 'en') {
       persistLanguage={false}
       config={{ defaultLanguage: language, detectBrowserLanguage: false }}
     >
-      {/* eslint-disable-next-line react-hooks/static-components -- ComponentRegistry.get returns the registered component (stable), not one created during render */}
+      {/* `C` is the component the registry ALREADY holds — `ComponentRegistry.get`
+          returns a stable reference, not one created during this render — so the
+          static-components concern does not apply. Stated as prose rather than as
+          the `eslint-disable-next-line` its sibling
+          `record-picker-empty-text-i18n.test.tsx` carries: that directive is
+          reported UNUSED by this repo's own config (the rule never fires here),
+          and an inert suppression outlives the reason anyone wrote it. */}
       <C schema={{ type: 'element:text_input', id: 'ws_input', properties }} />
     </I18nProvider>,
   );