feat(react): evaluate the spec-declared expression-bindable text keys

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare

.changeset/4795-bindable-text-keys.md

@@ -0,0 +1,50 @@
+---
+'@object-ui/react': minor
+---
+
+Expression-bindable text keys: `statistic.value`, `card.title`, `button.label`
+and their siblings now evaluate `${...}` on the node (objectui#4795 Direction 1,
+maintainer ruling 2026-08-25).
+
+**What changes for you.** Four text keys — `title`, `label`, `value`,
+`description` — can now carry an expression written directly on the component
+node, on the component types that declare them:
+
+| Component | Bindable node keys |
+|---|---|
+| `statistic` | `label`, `value`, `description` |
+| `card` | `title`, `description` |
+| `button` | `label` |
+
+```json
+{ "type": "statistic", "label": "Active users", "value": "${data.metrics.active}" }
+```
+
+That node used to render the literal text `${data.metrics.active}`. A dashboard
+`statistic` previously had no way at all to bind a dynamic number — the
+documented workaround (moving the key under `props`) evaluated the value and
+then discarded it, painting a blank card instead. Both shapes are fixed by the
+same change: the value is evaluated once, at the single place that produces
+evaluated schema, and lands where the renderers already read.
+
+**No component behaviour changed.** `statistic.tsx`, `card.tsx` and `button.tsx`
+are untouched — they always read these keys off the node; nothing was writing an
+evaluated value there.
+
+**Scope, and how it grows.** The list is closed and lives in
+`@objectstack/spec` (`EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT`); the renderer
+reads that declaration rather than keeping a copy. On any other component type
+these four keys are still read raw, so an expression reaches the screen as
+literal text — notably `text`, whose `value` is read but has no declaration.
+Adding a type or a key is a change to the spec, never something the renderer
+infers.
+
+**Nothing is newly rejected.** This release only widens what evaluates; no
+metadata that used to render now fails to. The build-time rejection of `${...}`
+in undeclared keys — the second half of the same ruling — is not in this release
+and is still open.
+
+Published authoring guidance updated to match: `skills/objectui/rules/protocol.md`
+(new "Bindable Text Keys" rule), plus the `page-builder`, `schema-expressions`
+and `data-integration` guides, which taught the now-retired "never evaluated"
+statement and its host-pre-resolution workaround.

packages/components/src/__tests__/bindable-text-keys-4795.test.tsx

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+
+/**
+ * objectui#4795 Direction 1 — the same contract as
+ * `packages/react/src/__tests__/SchemaRenderer.bindableTextKeys.test.tsx`, but
+ * driven through the REAL production renderers with no stand-in for the
+ * read-back half.
+ *
+ * That companion file pins the memo against probes, because `@object-ui/react`
+ * by design does not depend on `@object-ui/components`. It can therefore prove
+ * the value was EVALUATED, and only assert the read-back against a mirror of
+ * the real read points. This file closes that gap: `statistic`, `card` and
+ * `button` here are the shipped renderers, so a passing assertion below means
+ * the evaluated value actually reached the DOM — which is the whole of what
+ * objectui#4795 measured as missing ("evaluated AND read back").
+ *
+ * ## Why this file contains no renderer-specific fix to guard
+ *
+ * It guards the OPPOSITE. The ruling's implementation caution was that these
+ * read-back sites must be "converged on evaluated values, not patched per
+ * component" — and none of `data-display/statistic.tsx`, `layout/card.tsx` or
+ * `form/button.tsx` is touched by this card. They already read the right place;
+ * the single memo leg upstream now writes an evaluated value there. So these
+ * assertions passing while those three files are untouched IS the convergence
+ * claim, stated as a measurement rather than as a promise.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { SchemaRenderer, SchemaRendererProvider } from '@object-ui/react';
+// Module scope, not a hook — the cold transform would otherwise be billed to
+// `hookTimeout` (object-ui/no-dynamic-import-in-test-hook, objectui#3010).
+import '../renderers';
+
+const DATA = { total: 99, caption: 'Active users', note: '+20.1% from last month' };
+
+const renderNode = (schema: any) =>
+ render(
+ <SchemaRendererProvider dataSource={DATA}>
+ <SchemaRenderer schema={schema} />
+ </SchemaRendererProvider>,
+ );
+
+describe('objectui#4795 — declared text keys are evaluated AND read back, through real renderers', () => {
+ it('`statistic` binds label / value / description', () => {
+ renderNode({
+ type: 'statistic',
+ label: '${data.caption}',
+ value: '${data.total}',
+ description: '${data.note}',
+ });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('99')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ // The defect, stated in the negative: the literal source must be gone.
+ expect(screen.queryByText('${data.total}')).toBeNull();
+ });
+
+ it('`statistic` interpolates inside surrounding text', () => {
+ renderNode({ type: 'statistic', value: 'Total: ${data.total}' });
+ expect(screen.getByText('Total: 99')).toBeTruthy();
+ });
+
+ it('`card` binds title / description', () => {
+ renderNode({ type: 'card', title: '${data.caption}', description: '${data.note}' });
+ expect(screen.getByText('Active users')).toBeTruthy();
+ expect(screen.getByText('+20.1% from last month')).toBeTruthy();
+ });
+
+ it('`button` binds label', () => {
+ renderNode({ type: 'button', label: 'Refresh ${data.total}' });
+ expect(screen.getByText('Refresh 99')).toBeTruthy();
+ });
+});
+
+describe('objectui#4795 — the undeclared half stays inert, through real renderers', () => {
+ /**
+ * `basic/text.tsx` renders `schema.content || schema.value`, so `text.value`
+ * IS a top-level read-back site — and `text` has no row in the spec's
+ * carriage map, so the memo must not evaluate it. This assertion therefore
+ * pins a KNOWN, reported gap rather than a desired behaviour: the literal on
+ * screen is what an author writing the form the expressions guide teaches
+ * gets today, and closing it is a spec-side row (objectstack), not a
+ * renderer-side inference here. If a row is ever added upstream, this is the
+ * test that will go red and say so.
+ */
+ it('`text.value` is still not evaluated — no spec row (reported upstream)', () => {
+ renderNode({ type: 'text', value: '${data.total}' });
+ expect(screen.getByText('${data.total}')).toBeTruthy();
+ });
+
+ it('a key outside the component\'s declared row stays inert (`card.value`)', () => {
+ const { container } = renderNode({ type: 'card', title: 'Fixed', value: '${data.total}' });
+ // `card` declares title/description only; `value` is neither evaluated nor
+ // read back, so nothing from it reaches the DOM text.
+ expect(container.textContent).toContain('Fixed');
+ expect(container.textContent).not.toContain('99');
+ });
+});

packages/components/src/__tests__/skill-guide-provider-envelope.test.tsx

@@ -20,7 +20,20 @@
  * - `properties.*` — evaluated, then HOISTED onto the node by the COMPAT
  * hoist (`type` / `id` excepted). It therefore lands
  * exactly where every renderer reads, in every namespace.
- * - a node key — read, but never expression-evaluated.
+ * - a node key — read, and expression-evaluated only if
+ * `@objectstack/spec` DECLARES it bindable for that
+ * component type (objectui#4795 Direction 1, ruled
+ * 2026-08-25). Every other node key is read raw.
+ *
+ * ⚠️ That third line said a flat "read, but never expression-evaluated" when
+ * this file was written, and the reading below said so too. objectui#4795
+ * closed the gap for the closed set `title` / `label` / `value` /
+ * `description`, per the carriage map in
+ * `EXPRESSION_BINDABLE_TEXT_KEYS_BY_COMPONENT` — `card` carries `title` and
+ * `description`. The rest of this file's measurement is untouched: the two
+ * envelope fates above are exactly what #5372 measured, and the card's
+ * question ② (whether `properties` is an official `ui:*` authoring channel)
+ * is still open and still not answered here.
  *
  * So the one spelling the rules told an author not to reach for was the only
  * one that reaches a provider's data, and the two the rules endorsed both fail
@@ -158,9 +171,19 @@ describe('#5372 behaviour — the hoist is not `element:*`-only', () => {
  expect(header()).toBe('Customer Summary');
  });
 
- it('a node-level `title` is read but never evaluated', () => {
+ // objectui#4795 Direction 1 flipped this reading. It used to assert the
+ // literal `${data.label}` on screen — a node key was read but never
+ // evaluated — and that is the defect the 2026-08-25 ruling retired for the
+ // spec-DECLARED keys. Kept as a pair so the file still states both halves:
+ // a declared key now evaluates, an undeclared one on the same node does not.
+ it('a node-level `title` is read AND evaluated — `card` declares it', () => {
  renderNode({ type: 'card', title: '${data.label}' });
- expect(header()).toBe('${data.label}');
+ expect(header()).toBe('Evaluated Title');
+ });
+
+ it('a node key `card` does NOT declare is still read raw (`value`)', () => {
+ renderNode({ type: 'card', title: 'Fixed', value: '${data.label}' });
+ expect(header()).toBe('Fixed');
  });
 
  it('the same expression under `properties` is evaluated AND read', () => {

packages/react/package.json

@@ -34,7 +34,7 @@
  "@object-ui/data-objectstack": "workspace:*",
  "@object-ui/i18n": "workspace:*",
  "@object-ui/types": "workspace:*",
- "@objectstack/spec": "^17.0.0",
+ "@objectstack/spec": "^17.1.0",
  "react-hook-form": "^7.85.0"
  },
  "peerDependencies": {

packages/react/src/SchemaRenderer.tsx

@@ -32,6 +32,7 @@ import { resolveKeyedI18nLabel } from './utils/i18n.js';
 import { isConfigBag } from './utils/configBag.js';
 import { reportUnevaluatedExpressions } from './utils/unevaluatedExpression.js';
 import { reportDroppedPropsBag } from './utils/propsBagDiagnostic.js';
+import { expressionBindableTextKeysFor } from '@objectstack/spec/ui';
 import {
  reportUnresolvableVisibilityPredicate,
  reportAdapterOnlyDataPredicate,
@@ -1070,7 +1071,79 @@ export const SchemaRenderer: ForwardRefExoticComponent<
  if (typeof newSchema.content === 'string') {
  newSchema.content = evaluator.evaluate(newSchema.content);
  }
-
+
+ /**
+ * Evaluate the SPEC-DECLARED, expression-bindable TOP-LEVEL text keys
+ * (objectui#4795 Direction 1, maintainer ruling 2026-08-25).
+ *
+ * ## The hole this closes
+ *
+ * A value reaches the screen only if it is BOTH evaluated here AND read
+ * back by the renderer off the node. `content` above satisfies both; the
+ * other text keys satisfied neither at once, so
+ * `{ type: 'statistic', value: '${data.total}' }` — whose renderer reads
+ * `schema.value` (`data-display/statistic.tsx`) — put the literal
+ * `${data.total}` on screen, and the `props`-envelope workaround the
+ * objectui#4786 teaching rewrite retired rendered BLANK instead (evaluated,
+ * then spread as a React prop nobody reads). `statistic` is the dashboard
+ * workhorse and had no way at all to bind a dynamic value.
+ *
+ * ## Why this is ONE leg here and not a patch in each renderer
+ *
+ * The ruling's own implementation caution: the read-back sites must be
+ * "converged on evaluated values, not patched per component". They already
+ * agree on WHERE to read (the node's top level) — what they lacked was
+ * anything writing an evaluated value there. Writing it at the single
+ * producer of evaluated schema means `statistic.tsx`, `card.tsx` and
+ * `button.tsx` are UNCHANGED by this card and every future top-level reader
+ * is covered by construction. Four fixed components and no contract was the
+ * failure mode named at dispatch.
+ *
+ * ## The vocabulary is the spec's, and is consumed rather than copied
+ *
+ * `@objectstack/spec` declares it (objectstack#9599): the closed set
+ * `title` / `label` / `value` / `description`, plus the per-component
+ * carriage map saying which of them each component type actually reads
+ * back. The 2026-08-18 ruling is explicit that this memo CONSUMES the
+ * declaration "rather than hard-coding a twin list" — so the only thing
+ * this file knows is the name of the lookup. A row added upstream starts
+ * working here with no edit; a row this file invented would be the second
+ * dialect the declaration exists to prevent.
+ *
+ * ## The type string is passed VERBATIM
+ *
+ * `expressionBindableTextKeysFor` keys on the bare registry name, and the
+ * spec states the answer for an unlisted type is the empty set — "closed
+ * and mechanically answerable in both directions, never inferred from what
+ * a renderer happens to read". So no prefix-stripping normalization: it
+ * would look harmless (`ui:statistic` → `statistic`) and would in the same
+ * motion grant rows to `element:button` and `page:card`, whose renderers
+ * read their config out of the bag via `readProps()` and never touch these
+ * keys on the node — re-manufacturing the evaluated-but-not-read-back half
+ * of the very table this card exists to close. Measured on this tree: the
+ * authored corpus spells these types bare (`statistic` 42, `card` 135,
+ * `button` 158 nodes) and `ui:*` zero times, so verbatim is also the
+ * spelling authors actually use. `action:button` (5 nodes) has no row and
+ * is reported upstream rather than inferred here.
+ *
+ * ## Ordering and idempotence
+ *
+ * After the `properties` hoist deliberately, exactly like `content`: a
+ * value arriving through that channel was already evaluated by the
+ * `properties` leg, so it no longer carries a `${…}` and
+ * `evaluator.evaluate` returns it unchanged. The `typeof === 'string'`
+ * guard is doing real work rather than mirroring the line above — it stops
+ * this loop CREATING an absent key as `undefined`, which would change what
+ * `{ ...schema }` spreads and what `key in schema` answers downstream.
+ */
+ for (const key of expressionBindableTextKeysFor(
+ typeof newSchema.type === 'string' ? newSchema.type : '',
+ )) {
+ if (typeof newSchema[key] === 'string') {
+ newSchema[key] = evaluator.evaluate(newSchema[key]);
+ }
+ }
+
  // Evaluate 'props' — the legacy alias of the config bag.
  //
  // The guard MIRRORS the `properties` branch above rather than testing bare