fix(react,plugin-detail,plugin-grid,plugin-form,docs): one data-source resolution rule for the object-bound family, and a loud report when none resolves

[os-support-ai]

Fixes#5378
Fixes#5377

Two independent axes broke the same five snippets in content/docs/guide/building-crud-app.md, and a third turned up while measuring. Landing any one of them alone leaves the page rendering nothing while the PR reports success — which is exactly what #5378 was split out to prevent — so they are folded into one branch.

What was measured first (baseline, origin/main @ 32ef595f4)

Every snippet rendered through the real registry with a fake adapter. find / findOne call counts, and whether the row text appears:

snippet, as the guide publishes it	provider wiring	prop wiring
Step 5 / 6 / 7 object-grid	find0, nothing	find0, nothing
Step 6 object-form	findOne0, nothing	findOne0, nothing
Step 8 detail-view	findOne0, nothing	findOne0, nothing

All five dead in both directions. With the keys corrected, the split #5378 reports appears:

keys corrected, data dropped	provider wiring	prop wiring
object-grid	find1, row renders	find0
detail-view	findOne0	findOne1, row renders

Two mutually exclusive wirings. Neither reported anything: no error, no warning, no empty state that explained itself.

1. Converge the wiring (ruling item 1)

detail-view was registered as the raw DetailView, which reads a React dataSourceprop. Its siblings are registered through wrappers that read SchemaRendererContext. SchemaRenderer itself reads only context, so a prop never becomes context for anything below it.

All three blocks now resolve the adapter through one shared hook, useResolvedDataSource (new, @object-ui/react): an explicit dataSource prop first, the provider context second.

Precedence, stated and pinned: the explicit prop wins. It is the more specific signal — written on one placement, by someone who can see it — while the context adapter is ambient over every descendant. It is also the only precedence under which the ruling's "the prop form stays accepted" is true of the case that matters: a prop-form caller mounted inside an app that happens to have a provider would otherwise have its explicit choice silently overruled by an ancestor it never wrote.

Additive, as ruled — no prop removed this pass. Three wirings are asserted for detail-view: context alone (new), prop alone (must not break), and both at once (prop wins).

The compatibility surface, measured (the triage confidence gap)

Triage flagged that nobody had sized the existing detail-view prop-form caller population. Measured in this repo:

• packages/plugin-detail/src/renderers/record-details.tsx and packages/plugin-detail/src/RecordDetailDrawer.tsx both render the component directly, never through the registry. The published README documents the same direct form. The new wrapper does not sit between any of them and DetailView.
• Registry-routed detail-view nodes carrying a dataSource prop: zero, the getting-started guide being the one that tried.

So the additive wrapper changes no measured caller's behaviour and creates no ambiguous precedence. No fork to report — but the precedence is pinned by test rather than left to be discovered.

Two side effects of the convergence, both strictly widening:

• object-grid used to call useSchemaContext(), which throws without a provider — the || {} beside it could never catch it. So the exact case this card is about surfaced as the error boundary saying Component "object-grid" failed to render over a React hook message naming neither the data source nor the fix. It now reads the context.
• object-form gains a dataSource prop it did not have. It read context only, so nothing that worked before resolves differently.

2. The silence dies with it (ruling item 2)

A block in the family that resolves no adapter now renders a No data source resolved panel — role="alert", same shape as the existing unresolvable-view panel — naming the block, the object it was about to read, and the ancestor that injects the adapter. An address, not a symptom.

The check is opt-in per block (requiresDataSource on ElementDataSourceGate). The gate cannot compute "needs an adapter" and does not try: every block has different escape hatches, and a predicate guessed in the shared gate would paint a configuration error over a block that is working — a worse failure than the silence it replaces. Each call site states it, enumerating its own fallbacks:

• object-grid: inline rows (data array, provider: 'value', legacy staticData), bind, or a host that owns the fetch and passes the window as a data React prop (plugin-list's ListView). Tested with Array.isArray, which is the exact test ObjectGrid applies — a bare 'data' in props would also be true of the schema's own data object, because SchemaRenderer spreads every unstripped schema key as a prop.
• object-form: inline customFields, which is what hasInlineFields gates on inside the component.
• detail-view: an inline data record, or an api endpoint it fetches without an adapter.

The no-adapter answer comes before the unresolvable-view answer: with no adapter the view cannot resolve either, so the block would otherwise report "this data source cannot list the saved views" — true, and pointing at the view name instead of at the missing injection.

The other eight blocks using this gate are untouched; the flag defaults off.

3. The guide (ruling item 3, plus #5377's key axis)

• Wiring — one SchemaRendererProvider at the top of the App, per AGENTS.md commandment Implement visual designer for Object UI schemas #1. No SchemaRenderer in the page carries a dataSource prop any more; a test asserts that over the file's text.
• Keys — object becomes objectName in all five snippets.
• recordId becomes resourceId on detail-view ONLY.object-form genuinely reads recordId (ObjectForm.tsx calls findOne(schema.objectName, schema.recordId)), so the blanket rename that "fix the keys" reads like from a distance would have taken a working block to broken. Both directions are pinned: the form probe asserts the resourceId spelling loads no record there, the detail probe asserts recordId loads none there.
• data removed from the detail-view snippet only. Per-snippet triage, not a sweep: on detail-view, data means "here is the record already, do not fetch" — DetailView returns early on any schema.data, so the object's metadata was being installed as the record and findOne never ran (measured findOne0 with it, 1 without). On object-grid and object-form the same key is measured inert (find 1 either way), so it stays and is filed instead.

A third axis, found while measuring — and fixed here with evidence

The guide's setup.ts loaded @object-ui/components and @object-ui/fields only. initializeComponents() registers neither the plugins nor anything else beyond its own package, and Step 1 never installed @object-ui/plugin-detail at all. Measured by rendering the three keys against exactly the guide's registration set:

REG|object-grid|text="Unknown component type: object-grid…"
REG|object-form|text="Unknown component type: object-form…"
REG|detail-view|text="Unknown component type: detail-view…"

All five snippets resolved to the OBJUI-001 panel for anyone who followed the page literally, so no amount of wiring or key fixing could have made it render. Fixed in place rather than filed because the correct form is pinned by the page's own idiom — Step 2 already writes import '@object-ui/fields'; and explains why — and because a render probe over "the guide's snippets" that registered the plugins itself while the guide did not would have been measuring something the reader cannot reproduce.

Acceptance: a render probe, not a diff review

Three probe files (packages/plugin-{grid,form,detail}/src/__tests__/guideCrudAppRenders.test.tsx) evaluate the guide's own schema literals off disk — balanced-brace extraction plus Function, with the identifiers the page closes over bound — and render them through the real registry. A transcription kept in the tests would drift from the page silently, which is this defect's whole failure mode. Each file asserts its snippet count first, so a lost snippet cannot make the file vacuous.

Per snippet, after both axes: adapter call count 0 → 1 and the row text appears.

snippet	before	after
Step 5 object-grid	find 0	find 1, ["task", …], row painted
Step 6 object-grid	find 0	find 1, row painted
Step 7 object-grid	find 0	find 1, row painted
Step 6 object-form	getObjectSchema 0 / findOne 0	getObjectSchema('task'), findOne('task','42'), fields painted
Step 8 detail-view	findOne 0	findOne('task','42'), record painted

Each axis is also pinned as a standing contrast, so reintroducing one fails here rather than on a reader's screen: re-spell objectName back to object and the block fetches nothing; put recordId on the detail view and it loads nothing; hand the detail view a data and findOne never runs.

Reverse verification — predicted, then observed

No build artifact sits between any edit and the thing under test: the root vitest config aliases every @object-ui/* specifier to packages/*/src, and each probe imports its own plugin as ../index. Leg A proves it rather than asserting it — it edits a registration that a different file's assertions depend on, and a stale dist/ in the path would have left it green.

leg	predicted	observed
A — register the raw DetailView again	4 red	2 red: the provider-wiring test and the panel-presence test
B — drop requiresDataSource from the grid	1 red	1 red, exactly the panel test
C — put object: back in the guide's Step 5	1 red	2 red

Leg A is the interesting miss, and it is about my own tests rather than the code: two of the three no-adapter tests are absence assertions (a placement with inline rows must NOT get the panel), and a build with no wrapper satisfies those trivially. They are false-positive guards, not feature proofs, and only the presence assertion can fail when the feature is removed. Leg C under-counted for the same kind of reason — the both-wirings test reads the same snippet, so it dies with it.

A cross-package type check was reverse-verified too: requiresDataSource="yes-please" in packages/plugin-grid draws TS2322: Type 'string' is not assignable to type 'boolean | undefined', which proves the new prop reached packages/react/dist/index.d.ts and that plugin-grid's tsc is reading the rebuilt declarations, not a cached copy. (It first failed for the opposite reason — a stale dist gave TS2558: Expected 0 type arguments after useResolvedDataSource became generic.)

Out of scope, filed

Filed as #5446: Step 7 documents a view switcher and a search box that object-grid never reads — top-level view has zero read points, and data: { objectSchema, queryParams } is none of ViewData's four provider arms. Measured inert (identical find params with and without both keys). Left alone here because two legitimate correct forms exist — move it into the spec dataSource: { object, view } binding, or spell the view's declared filter / sort on the block — and choosing between them changes what the page teaches and, for the first option, what a reader sees when their backend has no such saved view. That is a decision, not a mechanical fix.

Verification

Gate union re-derived from the actual three-dot changed paths after the final commit, and run at 55c49cbb1:

• pnpm exec vitest run packages/plugin-detail/ packages/plugin-form/ packages/react/ — 193 files, 2074 passed
• pnpm exec vitest run packages/plugin-grid/ packages/plugin-list/ — 124 files, 1379 passed (plugin-list included deliberately: it is the host that passes the grid's rows as a React prop)
• pnpm exec vitest run packages/app-shell/ — 456 files, 4410 passed, 1 skipped (the heaviest in-repo consumer of all three blocks)
• turbo run type-check across the workspace — 81/81, the downstream-consumer direction for the new @object-ui/react exports
• turbo run lint on the four changed packages — 0 errors
• check:doc-types, check:doc-snippets (with the packages its --build-filter names built), check-doc-links, check:control-bytes, check:phantom-deps, check:self-import, check-lint-coverage, check-type-check-coverage, check:skills-paths, check:spec-symbols, check:action-forward-parity, check:i18n-keys, check:i18n-drift, check-changeset-no-major, check-changeset-fixed, check-changeset-presence — all green

Changeset: minor on the four packages (never major, per AGENTS.md §版本号策略).

Generated by Claude Code

---

Generated by Claude Code

[github-actions]

✅ Console Performance Budget

Metric	Value	Budget
Main entry (gzip)	25.3 KB	350 KB
Entry file	index-fsURae6P.js	—
Status	PASS	—

---

📦 Bundle Size Report

Package	Size	Gzipped
app-shell (index.js)	10.04KB	3.72KB
app-shell (runtime-config.js)	7.42KB	2.32KB
app-shell (types.js)	0.01KB	0.04KB
app-shell (urlParams.js)	10.06KB	3.86KB
auth (AuthContext.js)	0.31KB	0.24KB
auth (AuthGuard.js)	1.17KB	0.53KB
auth (AuthProvider.js)	29.34KB	7.05KB
auth (AuthShell.js)	3.49KB	1.40KB
auth (ForgotPasswordForm.js)	12.21KB	3.45KB
auth (LoginForm.js)	18.15KB	5.39KB
auth (PreviewBanner.js)	0.90KB	0.50KB
auth (RegisterForm.js)	6.65KB	2.22KB
auth (SocialSignInButtons.js)	9.61KB	3.89KB
auth (UserMenu.js)	3.41KB	1.23KB
auth (auth-gate-events.js)	1.29KB	0.66KB
auth (authStyles.js)	5.04KB	1.72KB
auth (createAuthClient.js)	40.21KB	10.80KB
auth (createAuthenticatedFetch.js)	6.35KB	2.43KB
auth (index.js)	2.77KB	1.22KB
auth (invitation-status.js)	1.22KB	0.70KB
auth (org-roles.js)	6.66KB	2.78KB
auth (phone-identifier.js)	1.11KB	0.66KB
auth (types.js)	0.59KB	0.35KB
auth (useAuth.js)	5.02KB	0.89KB
auth (useIsWorkspaceAdmin.js)	3.04KB	1.45KB
collaboration (CommentThread.js)	26.08KB	7.56KB
collaboration (LiveCursors.js)	3.17KB	1.27KB
collaboration (PresenceAvatars.js)	6.49KB	2.64KB
collaboration (PresenceProvider.js)	2.79KB	1.13KB
collaboration (index.js)	1.68KB	0.73KB
collaboration (useCollaborationTranslation.js)	6.05KB	2.52KB
collaboration (useCommentSearch.js)	1.98KB	0.88KB
collaboration (useConflictResolution.js)	7.75KB	1.86KB
collaboration (useMentionNotifications.js)	1.81KB	0.68KB
collaboration (usePresence.js)	6.33KB	1.84KB
collaboration (useRealtimeSubscription.js)	7.91KB	2.01KB
components (index.js)	506.94KB	113.61KB
core (index.js)	4.11KB	1.62KB
create-plugin (index.js)	10.08KB	3.26KB
data-objectstack (index.js)	159.80KB	44.34KB
fields (index.js)	237.21KB	59.50KB
i18n (LocalizationContext.js)	1.76KB	0.96KB
i18n (currency.js)	1.22KB	0.64KB
i18n (i18n.js)	4.28KB	1.75KB
i18n (index.js)	3.44KB	1.39KB
i18n (pickLocalized.js)	7.22KB	3.08KB
i18n (provider.js)	23.13KB	7.63KB
i18n (useDisplayLocale.js)	2.85KB	1.45KB
i18n (useObjectLabel.js)	30.51KB	7.57KB
i18n (useSafeTranslation.js)	7.77KB	3.13KB
layout (index.js)	38.95KB	10.97KB
mobile (MobileProvider.js)	0.92KB	0.49KB
mobile (ResponsiveContainer.js)	0.94KB	0.38KB
mobile (breakpoints.js)	1.51KB	0.70KB
mobile (createOfflineDataSource.js)	5.61KB	1.75KB
mobile (index.js)	1.55KB	0.62KB
mobile (offlineQueue.js)	3.91KB	1.35KB
mobile (pwa.js)	0.97KB	0.49KB
mobile (serviceWorker.js)	1.48KB	0.62KB
mobile (serviceWorkerSource.js)	3.41KB	1.48KB
mobile (useBreakpoint.js)	1.54KB	0.65KB
mobile (useGesture.js)	6.96KB	1.98KB
mobile (useOfflineSync.js)	1.99KB	0.72KB
mobile (usePullToRefresh.js)	2.53KB	0.85KB
mobile (useResponsive.js)	0.72KB	0.42KB
mobile (useResponsiveConfig.js)	1.37KB	0.63KB
mobile (useSpecGesture.js)	4.32KB	1.64KB
mobile (useTouchTarget.js)	1.01KB	0.54KB
permissions (MePermissionsProvider.js)	9.35KB	3.31KB
permissions (PermissionContext.js)	0.31KB	0.25KB
permissions (PermissionGuard.js)	0.89KB	0.45KB
permissions (PermissionProvider.js)	4.42KB	1.42KB
permissions (evaluator.js)	5.12KB	1.74KB
permissions (index.js)	0.93KB	0.41KB
permissions (store.js)	0.91KB	0.42KB
permissions (useFieldPermissions.js)	1.28KB	0.53KB
permissions (usePermissions.js)	1.81KB	0.83KB
plugin-ai (index.js)	15.75KB	3.80KB
plugin-calendar (index.js)	46.62KB	12.83KB
plugin-charts (index.js)	64.75KB	18.37KB
plugin-chatbot (index.js)	181.21KB	43.14KB
plugin-dashboard (index.js)	128.43KB	32.92KB
plugin-designer (index.js)	212.39KB	42.83KB
plugin-detail (index.js)	242.04KB	60.86KB
plugin-editor (index.js)	2.46KB	1.10KB
plugin-form (index.js)	124.40KB	30.26KB
plugin-gantt (index.js)	164.10KB	39.87KB
plugin-grid (index.js)	197.62KB	53.21KB
plugin-kanban (index.js)	52.93KB	14.60KB
plugin-list (index.js)	111.64KB	27.13KB
plugin-map (index.js)	20.08KB	6.62KB
plugin-markdown (index.js)	13.72KB	4.69KB
plugin-report (index.js)	43.49KB	11.93KB
plugin-timeline (index.js)	26.68KB	7.66KB
plugin-tree (index.js)	8.50KB	2.88KB
plugin-view (index.js)	84.52KB	20.67KB
providers (DataSourceProvider.js)	0.75KB	0.39KB
providers (MetadataProvider.js)	1.37KB	0.59KB
providers (ThemeProvider.js)	1.90KB	0.85KB
providers (UploadProvider.js)	11.66KB	3.50KB
providers (index.js)	0.45KB	0.23KB
providers (types.js)	0.01KB	0.04KB
react-runtime (index.js)	5.62KB	2.34KB
react (LazyPluginLoader.js)	3.77KB	1.33KB
react (SchemaRenderer.js)	36.10KB	12.26KB
react (data-invalidation.js)	5.05KB	2.08KB
react (index.js)	1.33KB	0.69KB
react (schema-input.js)	1.45KB	0.83KB
react (spec-input.js)	0.20KB	0.18KB
sdui-parser (codegen.js)	5.41KB	2.34KB
sdui-parser (index.js)	4.77KB	2.16KB
sdui-parser (input-type.js)	2.84KB	1.40KB
sdui-parser (parse.js)	10.76KB	3.17KB
sdui-parser (provenance.js)	3.66KB	1.82KB
sdui-parser (types.js)	0.29KB	0.24KB
sdui-parser (validate.js)	6.92KB	2.40KB
types (ai.js)	0.20KB	0.17KB
types (api-types.js)	0.20KB	0.18KB
types (app.js)	2.87KB	0.99KB
types (base.js)	0.20KB	0.18KB
types (blocks.js)	0.20KB	0.18KB
types (complex.js)	0.20KB	0.18KB
types (crud.js)	0.20KB	0.18KB
types (dashboard-filter-alias.js)	6.23KB	2.74KB
types (data-display.js)	0.20KB	0.18KB
types (data-protocol.js)	0.20KB	0.19KB
types (data.js)	0.20KB	0.18KB
types (designer.js)	1.87KB	0.85KB
types (disclosure.js)	0.20KB	0.18KB
types (error-code.js)	1.54KB	0.88KB
types (feedback.js)	0.20KB	0.18KB
types (field-types.js)	0.20KB	0.18KB
types (form.js)	0.20KB	0.18KB
types (http-retry.js)	4.32KB	2.02KB
types (index.js)	3.08KB	1.53KB
types (layout.js)	0.20KB	0.18KB
types (managed-by.js)	0.19KB	0.18KB
types (mobile.js)	2.59KB	1.31KB
types (navigation.js)	0.20KB	0.18KB
types (objectql.js)	0.20KB	0.18KB
types (overlay.js)	0.20KB	0.18KB
types (permissions.js)	0.20KB	0.18KB
types (plugin-scope.js)	0.20KB	0.18KB
types (record-components.js)	0.20KB	0.19KB
types (record-semantics.js)	1.28KB	0.67KB
types (registry.js)	0.20KB	0.18KB
types (reports.js)	0.20KB	0.18KB
types (spec-report.js)	5.05KB	1.93KB
types (system-fields.js)	3.33KB	1.54KB
types (theme.js)	0.20KB	0.18KB
types (ui-action.js)	3.40KB	1.71KB
types (views.js)	0.20KB	0.18KB
types (widget.js)	0.20KB	0.18KB

Size Limits

• ✅ Core packages should be < 50KB gzipped
• ✅ Component packages should be < 100KB gzipped
• ⚠️ Plugin packages should be < 150KB gzipped