docs(data-objectstack): document the real headless surface, not a phantom React API

[yinlianghui]

Fixes#4124

Docs-only. Rewrites content/docs/utilities/data-objectstack.mdx around the surface the package actually exports.

Ordering

PR #4127 (#3781) edits the same page and has merged — 1b6188d41, the tip of origin/main. This branches off main; no stacking was needed. Its dependency prose (install note at :16, the Dependencies list) is untouched — verified by grepping the diff for those lines: zero hits.

Premise re-verified on the branch tip

Both symbols are genuinely absent, so the card holds:

• grep -rn "ObjectStackProvider|useObjectStack" packages/data-objectstack/src/ -> exit 1, zero matches.
• The export list in packages/data-objectstack/src/index.ts is ObjectStackAdapter, createObjectStackAdapter, the error classes, MetadataClient, CloudOperations, SecurityManager, IntegrationManager, createObjectStackUserStateAdapter, the studio/contract helpers and types. No provider, no hook.

Reverse verification — the API the page used to teach, compiled against the built package:

error TS2724: '"@object-ui/data-objectstack"' has no exported member named
'ObjectStackProvider'. Did you mean 'ObjectStackError'?
error TS2305: Module '"@object-ui/data-objectstack"' has no exported member 'useObjectStack'.

That is the error a reader following the old Quick Start hit.

Two fabrication families, not one

1. The phantom React API (the card). Removed page-wide, not just at the three cited lines — it reached well beyond them: the Features bullet calling the package a "React context provider", Quick Start, both API Reference entries, the whole Configuration section, all three Advanced Usage examples, and Troubleshooting. Replaced with createObjectStackAdapter / ObjectStackAdapter injected via @object-ui/react's SchemaRendererProvider, which is what the README, content/docs/guide/data-source.md and seven plugin READMEs already teach.

The REACT_APP_OBJECTSTACK_* environment variables went with it: the package reads no environment variable of its own (grep for process.env in its src/ finds only a JSDoc example).

2. The JSON dataSource shape — found by the page-wide sweep the card asked for. Every JSON block used a type: "objectstack" discriminator with a query: { filters, sort, limit } body. That shape has zero occurrences repo-wide (grep over all .ts/.tsx/.json). The real per-element binding is the spec's ElementDataSource, validated by ElementDataSourceSchema in @objectstack/spec:

	documented before	actual
discriminator	"type": "objectstack"	none — the binding has no type tag
object	object	object (required)
filter	query.filters: [{field, operator, value}]	filter: FilterCondition (object form, e.g. { "total": { "$gt": 100 } })
sort	query.sort: [{field, direction}]	sort: [{ field, order }]
limit	query.limit	limit
saved view	—	view

The spec schema is z.strict, so the old type key would have been rejected, not ignored. Examples now use the block names from the guide's own support table (object-grid, object-form, object-kanban); kanban as written had no registration at all.

Corrected symbols

symbol	disposition
ObjectStackProvider	deleted — not exported
useObjectStack	deleted — not exported
ObjectStackDataSource (interface)	replaced by ElementDataSource
apiUrl / apiKey / organizationId props	replaced by baseUrl / token
REACT_APP_OBJECTSTACK_*	deleted — package reads no env vars
client.query / client.aggregate	replaced by find / findOne / create / update / delete
createObjectStackAdapter	added, real config incl. fetch, cache, reconnect options
ObjectStackAdapter	added, class form
SchemaRendererProvider	added, the real injection point

Three inaccuracies the type-check caught in my own draft

The mechanical check earned its keep — it went red on my first rewrite and each red was a real fact:

1. create() returns unknown unless the adapter is parameterised, so user.id did not compile. The docs now show the generic form.
2. bulk and batchTransaction are optional members of DataSource (bulk?(...), batchTransaction?(...)), so through a DataSource-typed value they need feature-detection. The page now says so and shows the class type for those calls.
3. getConnectionState / onConnectionStateChange are not on DataSource at all — they are ObjectStackAdapter class members. The method list is now split into "on the DataSource interface" and "adapter-only".

Without compiling the snippets all three would have shipped as new, confidently-worded errors.

Verification

No mdx snippet-check gate exists in this repo (scripts/extract-mdx-demos.mjs is an unwired one-off migration tool, not a gate), so per the card I extracted the snippets and ran tsc against the built workspace packages.

gate	result
snippet tsc (extracted, strict, against built dist/*.d.ts)	exit 0
snippet tsc on the OLD phantom imports (reverse)	exit 2 — TS2724 / TS2305 above
pnpm turbo run build --filter=@object-ui/site --force	29 successful, 29 total, 0 cached, 2m13s
node scripts/check-doc-links.mjs	Links are valid across 7 scan roots.
node scripts/check-control-bytes.mjs	OK (scanned 3829 tracked text file(s))
node scripts/check-changeset-presence.mjs	No source of a released package changed in this range, so no changeset is owed.

The build closure was built first (--filter '...^...') so tsc read real declarations rather than stale ones.

A note on the docs build: an unforced re-run reported 29 cached / FULL TURBO in 80ms after I had edited the mdx — turbo's input hash for @object-ui/site does not appear to track content/docs/**. The green above is therefore from a --force run. Worth knowing for anyone reading a cached Build Docs as validation of a content change.

Rendered-output check on apps/site/.next/server/app/docs/utilities/data-objectstack.html: ObjectStackProvider, useObjectStack, REACT_APP, apiKey, organizationId and "type": "objectstack" all render 0 times; createObjectStackAdapter 17, SchemaRendererProvider 6, ElementDataSource 4.

Changeset: none owed, per the presence script's own arbitration (docs-only). Labelled skip-changeset.

Out of scope, deliberately

• **Version:** 0.3.1 at :~380 is stale (the package is at 17.4.0) but is already filed as Two utilities docs pages hardcode "Version: 0.3.1" in their Package Information block while both packages are at 17.4.0 #4125 — left alone so this PR does not collide with that card.
• packages/data-objectstack/README.md:16 still says npm install @object-ui/data-objectstack @objectstack/client, the same claim docs(data-objectstack): describe the real dependency contract, not a peer one #4127 corrected on this docs page. Filed separately rather than fixed here.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
objectui	Ignored		Aug 10, 2026 11:54am