fix(components,app-shell): page elements bind data through the node-level dataSource only

element:repeater reads its query (object, filter, sort, limit) from the
dataSource binding, gate-wrapped like element:number; element:record_picker
and element:number drop their flat-key fallbacks and the number's AND with
properties.filter; the Studio designer writes dataSource.object (and the
repeater's dataSource.limit) at node level, and its field pickers read the
object from there. Docs and changeset follow.

Part of objectui#11880 (items 1-4).

Claude-Session: https://claude.ai/code/session_01MgfduSkFrfM3eorB3UGfAU
Co-authored-by: Claude <noreply@anthropic.com>

Author: claude

.changeset/11880-element-datasource-only.md

@@ -0,0 +1,12 @@
+---
+'@object-ui/components': patch
+'@object-ui/app-shell': patch
+---
+
+Page elements bind data through the node-level `dataSource` only (objectui#11880, the objectui half of objectstack#11509, ruled A-narrow).
+
+- `element:repeater` reads its query from the `dataSource` binding: `object`, `filter`, `sort` and `limit`, composed with the saved view its `view` names. A repeater bound only through `dataSource` used to render "No records". An unresolvable `view` now shows the configuration-error panel, and a resolving one the loading panel. Its registration declares the binding through the injected `dataSource` input and no longer publishes `object`, `filter`, `sort` or `limit`.
+- `element:record_picker` and `element:number` no longer read the flat `properties.object` / `filter` / `sort` / `limit` beside the binding, and no longer publish them as inputs. `element:number`'s filter is the binding's alone: the AND with `properties.filter` is gone. An element whose node names no `dataSource.object` issues no query.
+- The Studio page designer writes `dataSource.object` for `element:repeater` and `element:number`, and `dataSource.limit` for the repeater's row cap, at node level. Their field pickers read the object from `dataSource.object`. A stored `properties.object` stays visible in the inspector's Advanced section.
+
+Breaking for an author who wrote the flat keys on these three elements: move them into `dataSource`. `@objectstack/spec` retires the flat keys in v18.

content/docs/guide/data-source.md

@@ -256,6 +256,7 @@ ignores would be accepted and dropped, which is the defect this binding removes.
 | `object-grid` | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `element:record_picker` | ✅ | ✅ | ✅ | ✅ | ✅ |
 | `element:number` | ✅ | filter | ✅ | — single value | — single value |
+| `element:repeater` | ✅ | filter / sort / limit | ✅ | ✅ | ✅ |
 | `record:related_list` | ✅ | columns / filter / sort / limit | ✅ | ✅ | ✅ |
 | `object-calendar` | ✅ | filter / sort | ✅ | ✅ | — platform ceiling |
 | `object-kanban` | ✅ | filter / limit | ✅ | — no ordering | ✅ (`limit`) |
@@ -303,20 +304,37 @@ rows, a form's inline fields — `customFields`, or `sections` whose every field
 inline — a chart's `dataset`, a `bind` path, or a metric's `fallbackValue`) draws
 from that source and shows no hint.
 
-The two `element:*` rows keep their configuration in the node's `properties` bag,
-so the binding does not land on a schema key there: each reads it directly, and
-`dataSource.object` wins over `properties.object`. They differ on `filter`.
-`element:record_picker` takes the binding's (or its view's) filter in place of
-`properties.filter`, which applies only when neither supplies one.
-`element:number` AND-combines `properties.filter` with the binding's filter and
-its view's — the rule the gate-wrapped blocks above follow — so neither is
-dropped, and a filter refused while combining them shows the configuration-error
-panel instead of a count. On `element:number`,
+The three `element:*` rows keep their display configuration in the node's
+`properties` bag and take their query from the binding **only**: `object`,
+`filter`, `sort` and `limit` are read from `dataSource` and from nowhere else.
+There is no `properties.object`, `properties.filter`, `properties.sort` or
+`properties.limit` on these three elements — the renderers do not read them, and
+`@objectstack/spec` retires them in v18 (objectstack#11509). The binding's filter
+is AND-combined with its view's filter, as on every block above. A repeater is
+bound like this:
+
+```json
+{
+  "type": "element:repeater",
+  "dataSource": {
+    "object": "contact",
+    "sort": [{ "field": "name", "order": "asc" }],
+    "limit": 10
+  },
+  "properties": { "titleField": "name", "fields": ["email"] }
+}
+```
+
+On `element:number`,
 `{ "dataSource": { "object": "contact" }, "properties": { "aggregate": "count" } }`
 is a complete metric; its `sort` and `limit` are not read, because an aggregate
-has no ordering and a capped count would be a wrong number. An `element:number`
-that sets `aggregate` but names no object in either place (no `properties.object`,
-no `dataSource.object`) shows a short "no object named" notice instead of a count.
+has no ordering and a capped count would be a wrong number, and a filter the
+converter refuses shows the configuration-error panel instead of a count. An
+element whose node names no `dataSource.object` issues no query: an
+`element:number` that sets `aggregate` shows a short "no object named" notice
+instead of a count, an `element:record_picker` offers no records, and an
+`element:repeater` shows its empty-state text. The Studio page designer writes
+these elements' object (and the repeater's row cap) into `dataSource`.
 
 #### Scoping a filter to the record in view: `{record_id}`
 

packages/app-shell/src/views/metadata-admin/inspectors/PageBlockInspector.tsx

@@ -472,23 +472,40 @@ export function PageBlockInspector({ selection, draft, onPatch, onClearSelection
     block.type as string | undefined,
     (block.properties as Record<string, unknown>) || {},
   );
+  // The node-level `dataSource` binding (objectui#11880): a field marked
+  // `at: 'dataSource'` reads and writes its member, patched at node level the
+  // way `visibleWhen` is below, never under `properties`.
+  const binding: Record<string, unknown> =
+    block.dataSource && typeof block.dataSource === 'object' && !Array.isArray(block.dataSource)
+      ? (block.dataSource as Record<string, unknown>)
+      : {};
+  const readBinding = (name: string): unknown => binding[name];
+  const patchBinding = (name: string, value: unknown) =>
+    patch({ dataSource: { ...binding, [name]: value } } as Partial<Block>);
   // The record page's bound object — drives `field-picker`/`field-list` with
-  // objectFrom:'page'. (objectFrom:'self' reads a sibling block property.)
+  // objectFrom:'page'. (objectFrom:'self' reads a sibling block property, and
+  // objectFrom:'dataSource' the binding's object.)
   const pageObject = typeof (draft as any)?.object === 'string' ? ((draft as any).object as string) : undefined;
   const resolveObject = (src: BlockPropField & { objectFrom?: string; objectProp?: string }): string | undefined =>
     src.objectFrom === 'page'
       ? pageObject
-      : src.objectProp != null && blockProps[src.objectProp] != null
-        ? String(blockProps[src.objectProp])
-        : undefined;
+      : src.objectFrom === 'dataSource'
+        ? (typeof binding.object === 'string' ? binding.object : undefined)
+        : src.objectProp != null && blockProps[src.objectProp] != null
+          ? String(blockProps[src.objectProp])
+          : undefined;
   const readProp = (name: string): unknown => blockProps[name] ?? (block as any)[name];
   const patchProp = (name: string, value: unknown) =>
     patch({ properties: { ...blockProps, [name]: value } } as Partial<Block>);
 
   // Properties already handled by curated fields — excluded from the generic
-  // "Advanced" section so each property has exactly one editor.
+  // "Advanced" section so each property has exactly one editor. A field homed
+  // in the binding edits no `properties` key, so a stored `properties.<name>`
+  // of the same name stays visible there rather than hidden behind it.
   const curatedNames = new Set(
-    (blockHasConfig(block.type) ? BLOCK_CONFIG[block.type as string] : []).map((f) => f.name),
+    (blockHasConfig(block.type) ? BLOCK_CONFIG[block.type as string] : [])
+      .filter((f) => f.at !== 'dataSource')
+      .map((f) => f.name),
   );
   const advancedKeys = Object.keys(blockProps).filter(
     (key) => !curatedNames.has(key) && !STRUCTURAL_PROP_KEYS.has(key),
@@ -779,7 +796,9 @@ export function PageBlockInspector({ selection, draft, onPatch, onClearSelection
           <div className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
             {t('engine.inspector.pageBlock.properties', locale)}
           </div>
-          {BLOCK_CONFIG[block.type as string].map((f) => renderField(f, readProp, patchProp))}
+          {BLOCK_CONFIG[block.type as string].map((f) =>
+            f.at === 'dataSource' ? renderField(f, readBinding, patchBinding) : renderField(f, readProp, patchProp),
+          )}
         </div>
       )}
 

packages/app-shell/src/views/metadata-admin/previews/block-config.ts

@@ -5,8 +5,9 @@
  *
  * The page block inspector renders these as typed fields that edit the block's
  * `properties` (the spec convention; the renderer hoists `properties.*` to the
- * top level). Keep each field `name` aligned with the property name the
- * corresponding renderer reads. Add block types here as they are needed.
+ * top level), or — for a field marked `at: 'dataSource'` — the node-level
+ * `dataSource` binding. Keep each field `name` aligned with the property name
+ * the corresponding renderer reads. Add block types here as they are needed.
  *
  * Field kinds:
  *   text | number | boolean | select  — scalar props
@@ -76,8 +77,13 @@
 
 /** Where a field/field-list picker resolves its object from:
  *  - 'page' — the record page's bound object (draft.object)
- *  - 'self' — a sibling property on the same block (objectProp) */
-export type ObjectSource = { objectFrom: 'page' } | { objectFrom: 'self'; objectProp: string };
+ *  - 'self' — a sibling property on the same block (objectProp)
+ *  - 'dataSource' — the block's node-level `dataSource.object` binding, the
+ *    one place an `element:*` block reads its object from (objectui#11880) */
+export type ObjectSource =
+  | { objectFrom: 'page' }
+  | { objectFrom: 'self'; objectProp: string }
+  | { objectFrom: 'dataSource' };
 
 /**
  * A field's input hint — EXACTLY ONE of two shapes, chosen where the field is
@@ -105,8 +111,16 @@ export type PlaceholderSpec = { key: string; literal?: never } | { literal: stri
  * One curated property editor. Every `label` is a translation key, and every
  * `placeholder` declares whether it is one — see the file header for the five
  * key shapes and the tests that enforce them.
+ *
+ * `at` says where the value lives on the block node (objectui#11880). Absent,
+ * the default, is `properties.<name>`. `'dataSource'` is the node-level
+ * `dataSource.<name>`: a member of the spec's `ElementDataSourceSchema`
+ * binding, which `element:repeater`, `element:number` and
+ * `element:record_picker` read their query from and nowhere else
+ * (objectstack#11509, ruled A-narrow). Honoured on a block's top-level fields;
+ * an `array` field's item editors always write into the item.
  */
-export type BlockPropField =
+export type BlockPropField = (
   | { name: string; label: string; kind: 'text'; placeholder?: PlaceholderSpec }
   | { name: string; label: string; kind: 'number'; placeholder?: PlaceholderSpec }
   | { name: string; label: string; kind: 'boolean' }
@@ -123,7 +137,8 @@ export type BlockPropField =
   // Schema-driven pickers — dropdowns populated from the live metadata.
   | { name: string; label: string; kind: 'object-picker'; placeholder?: PlaceholderSpec }
   | ({ name: string; label: string; kind: 'field-picker'; placeholder?: PlaceholderSpec } & ObjectSource)
-  | ({ name: string; label: string; kind: 'field-list'; placeholder?: PlaceholderSpec } & ObjectSource);
+  | ({ name: string; label: string; kind: 'field-list'; placeholder?: PlaceholderSpec } & ObjectSource)
+) & { at?: 'dataSource' };
 
 /** Shared alignment options. The keys name the field (`align`), so reusing this
  *  const on a field called anything else turns the key-derivation pin red. */
@@ -320,17 +335,24 @@ export const BLOCK_CONFIG: Record<string, BlockPropField[]> = {
     { name: 'columns', label: 'engine.inspector.pageBlock.field.element:definition-list.columns', kind: 'number', placeholder: { literal: '1' } },
     { name: 'inline', label: 'engine.inspector.pageBlock.field.element:definition-list.inline', kind: 'boolean' },
   ],
+  // objectui#11880 — the list's query is the node-level `dataSource` binding,
+  // the only place `element:repeater` reads it from, so `object` and `limit`
+  // write `dataSource.object` / `dataSource.limit` and the field pickers read
+  // their object from there. They wrote `properties.object` / `.limit` before:
+  // keys the renderer no longer reads and the spec retires in v18.
   'element:repeater': [
-    { name: 'object', label: 'engine.inspector.pageBlock.field.element:repeater.object', kind: 'object-picker' },
-    { name: 'titleField', label: 'engine.inspector.pageBlock.field.element:repeater.titleField', kind: 'field-picker', objectFrom: 'self', objectProp: 'object' },
-    { name: 'fields', label: 'engine.inspector.pageBlock.field.element:repeater.fields', kind: 'field-list', objectFrom: 'self', objectProp: 'object' },
-    { name: 'limit', label: 'engine.inspector.pageBlock.field.element:repeater.limit', kind: 'number', placeholder: { literal: '10' } },
+    { name: 'object', label: 'engine.inspector.pageBlock.field.element:repeater.object', kind: 'object-picker', at: 'dataSource' },
+    { name: 'titleField', label: 'engine.inspector.pageBlock.field.element:repeater.titleField', kind: 'field-picker', objectFrom: 'dataSource' },
+    { name: 'fields', label: 'engine.inspector.pageBlock.field.element:repeater.fields', kind: 'field-list', objectFrom: 'dataSource' },
+    { name: 'limit', label: 'engine.inspector.pageBlock.field.element:repeater.limit', kind: 'number', placeholder: { literal: '10' }, at: 'dataSource' },
     { name: 'emptyText', label: 'engine.inspector.pageBlock.field.element:repeater.emptyText', kind: 'text' },
     { name: 'divided', label: 'engine.inspector.pageBlock.field.element:repeater.divided', kind: 'boolean' },
   ],
+  // objectui#11880 — the same move for the metric: its object is
+  // `dataSource.object`, and the measure picker reads its object from there.
   'element:number': [
-    { name: 'object', label: 'engine.inspector.pageBlock.field.element:number.object', kind: 'object-picker' },
-    { name: 'field', label: 'engine.inspector.pageBlock.field.element:number.field', kind: 'field-picker', objectFrom: 'self', objectProp: 'object' },
+    { name: 'object', label: 'engine.inspector.pageBlock.field.element:number.object', kind: 'object-picker', at: 'dataSource' },
+    { name: 'field', label: 'engine.inspector.pageBlock.field.element:number.field', kind: 'field-picker', objectFrom: 'dataSource' },
     {
       name: 'aggregate',
       label: 'engine.inspector.pageBlock.field.element:number.aggregate',