docs(ui): the react-pages live-data sample reads `result.records`, which is always undefined — and its Callout misstates what a dropped option does

[os-zhuang]

Found while fixing #10288 (the same two defects in examples/app-showcase). Filing
rather than fixing: content/docs/** pulls in a different gate family than that card's
diff (check:doc-anchors, check:docs-audit-scope, check:docs-redirects,
check:published-readme-links, check:role-word, plus the {/* os:check */} verified-
sample convention), and the Callout's second half needs a wording decision, not a
mechanical edit.

1. The sample renders an empty list

content/docs/ui/react-pages.mdx, the "Live data" sample (L143-148):

const result = await adapter.find('showcase_invoice', {
 $filter: ['status', '!=', 'paid'],
 $top: 200,
});
const records = Array.isArray(result) ? result : (result && result.records) || [];

The query options are right. The result read is not. useAdapter() returns
ObjectStackAdapter, whose find() resolves to a normalized QueryResult — objectui
packages/types/src/data.ts declares data / total / page / pageSize /
hasMore / cursor, and normalizeQueryResult (objectui
packages/data-objectstack/src/index.ts) returns exactly that shape. There is no
records key. result.records is undefined on every call, so records falls to []
and the documented sample renders an empty <ul> forever, with no error.

This is not theoretical: the identical read was fixed once already in
examples/app-showcase/src/ui/pages/crm-workbench.page.ts, whose comment records the
symptom verbatim — "Reading .records here always missed, so the KPI cards silently stuck
at 0 even though the ListView beside them showed the same rows" — and was still live in
renewals-pipeline.page.ts until #10288. The doc is the third instance, and it is the
one a customer copies from.

Fix: result.data, with the array arm kept. Every objectui consumer of this contract
spells it res?.data ?? res?.records ?? … (data-list.tsx, record-picker.tsx,
ObjectRefField.tsx, record-history.tsx, …) — canonical first, the legacy spelling as
a fallback, never alone.

2. The Callout names the wrong consequence

Directly below the sample:

An unprefixed top: or a filters: key is not a query option — it is silently
dropped, and the query comes back unfiltered or with the default page size. There
is no error.

The "unfiltered" half is right. The page-size half is backwards. The GET list route has
no default page size, so an absent top returns the ENTIRE match set — stated in
packages/client/src/index.ts ("The GET list route has no default page size, so an
absent top returns the ENTIRE match set"), pinned in packages/client/src/client.test.ts
(#6485), and measured by packages/objectql/src/protocol-unknown-query-param.test.ts's
baseline — no params returns every row (10 rows seeded, total: 10 with no params).

So the real failure mode of a dropped top is an unbounded read, not a truncated
one — the cap the author wrote never happens, and the page pulls every matching row over
the wire. That is a different thing to warn an author about, and the current wording
sends anyone debugging it looking for pagination that is not there.

Suggested wording: "…it is silently dropped. The query then runs as if you had not
written it: an unprefixed filter: comes back unfiltered, and an unprefixed top:
comes back with every matching row, because the list route has no default page size.
There is no error."

Acceptance

• The sample reads result.data (array arm preserved) and, run against a real adapter,
  renders rows.
• The Callout states the unbounded-read consequence, sourced from the client/protocol
  behaviour above rather than from the old wording.
• The named docs gates stay green.

[os-zhuang]

Triage: lands in content/docs/ui/react-pages.mdx → domain:devx (content/docs/**), type Bug (the published sample renders an empty list and the Callout states the inverse of the measured consequence). Queued. Both halves are docs-only edits with the correct wording already drafted in the body; the docs gate family named in the body is the verification surface. Size/model suggestion: S, sonnet.

---

Generated by Claude Code

[claude]

Claim — PM dispatch (devx seat)

• Session: c970724d-303c-5614-9d20-a3f92205cfad
• Branch: claude/issue-10469-react-pages-live-data

Premise re-verified on origin/main = 9185ff0213 (fetched 2026-08-21T10:04:48Z).
content/docs/ui/react-pages.mdx:147 still reads:

const records = Array.isArray(result) ? result : (result && result.records) || [];

⚠️ Worth stating precisely, because the line looks defensive: the Array.isArray(result) arm
does not rescue it. find() resolves to a normalized QueryResult object, so the array arm
never fires, result.records is undefined on every call, and records falls to []. The
published sample renders an empty <ul> forever, with no error.

This is the third instance of one read. It was fixed in
examples/app-showcase/src/ui/pages/crm-workbench.page.ts — whose comment records the symptom
verbatim, "the KPI cards silently stuck at 0 even though the ListView beside them showed the
same rows" — and again in renewals-pipeline.page.ts under #10288. The doc is the one a
customer copies from, which is why it is the worst of the three to leave.

⛔ content/docs/ui/react-pages.mdx only. It is not among the 19 files PR #10714 changed, so
it is free — but that PR merged recently, so re-derive at your own merge base.

⚠️ The second half is a wording decision, not a mechanical edit, and the card's drafted
wording must be verified against the route source, not adopted: the Callout claims a dropped
query option means the query comes back "with the default page size", and the card argues the
GET list route has no default page size at all. Confirm that in the route implementation before
rewriting the sentence — a Callout that states the inverse of the measured behaviour is exactly
the defect being fixed, and shipping a second wrong consequence would repeat it.

---

Generated by Claude Code