docs(guide,readme): spell the grid child list children, the key grid reads (objectui#8912) - #8951
Merged
Merged
Conversation
…id` reads The `grid` renderer draws its child list from `schema.children` and from nothing else, and `GridSchema` declares only `children`. Three teaching surfaces authored that list as `items` anyway — including the flagship example on the npm/GitHub landing page — so a reader who copied any of them got a grid element with no children. Nothing refused the key: `BaseSchema` is `.passthrough()` with an `[key: string]: any` index signature, so `items` validated, type-checked, rode onto the node and drew nothing. Repairs the documentation, not the renderer: coding standard #0.1 (contract-first) forbids the alternatives — teaching `grid` to read `items` as an alias, or declaring `items` on `GridSchema` — as lenient fallbacks that would mint a second child-key dialect on one node. The objectui#8310 render pin transcribed the flagship verbatim, `items` and all, so the defect could not hide inside a green. It now transcribes the repaired flagship, asserts the three `statistic` labels are drawn, keeps the pre-repair spelling as a labelled negative-space leg (grid element drawn, children absent), and gains a README-scan leg so the transcription cannot become fiction. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MPaVWWMuWeT5LgB1qoXjVB
github-actions
Bot
added
documentation
Contributor
✅ Console Performance Budget
The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it. 📦 Bundle Size Report
Size Limits
|
The objectui#8310 arity pin transcribed the README's flagship grid with its child list spelled `items`, and said so in prose: a header paragraph describing that spelling as a live, unrepaired defect, a docblock calling the literal "the `grid` node the README's flagship example hands to `body`", and a brace-scanner comment naming a nested `items[]`. Repairing the three teaching surfaces made all four statements false, and nothing went red — `BaseSchema` carries `[key: string]: any`, and this file's subject is `body` arity, not the child key. Stale-truth repair only. Every one of the file's 28 assertion lines is byte-identical before and after; outside comments the diff is the single key. What the pin asserts, and the arity ruling it enforces, are untouched. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01MPaVWWMuWeT5LgB1qoXjVB
Contributor
✅ Console Performance Budget
The eager closure is every chunk the entry reaches through static imports — what the browser fetches and parses before the app renders. The entry chunk on its own is a small fraction of it. 📦 Bundle Size Report
Size Limits
|
os-steve
marked this pull request as ready for review
September 10, 2026 09:28
This was referenced Sep 10, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #8912
Session:
https://claude.ai/code/session_01MPaVWWMuWeT5LgB1qoXjVB— written into the prose as a codespan because a
PATCHof this body downgrades the session-URL footer to its bare form.The SDUI
gridrenderer draws its child list fromschema.childrenand from nothing else, andGridSchemadeclares onlychildren. Three teaching surfaces authored that list asitemsanyway —including the flagship example on the npm/GitHub landing page — so a reader who copied any of them
got a
gridelement with no children.Option 1 of the card, which the triage verdict had already established as the only surviving route:
the documentation is repaired, and the renderer is not. Options 2 (teach
gridto readitemsas analias) and 3 (declare
itemsonGridSchema) are the lenient-fallback shape coding standard #0.1(contract-first) forbids by name, and each would mint a second child-key dialect on one node. ⛔ The
gridrenderer andGridSchemaare untouched — both are correct today.What changed
README.md#### Basic Usagefence —items:becomeschildren:(tsx object literal, unquoted)content/docs/guide/schema-rendering.md"items"becomes"children"content/docs/guide/schema-playground.md"items"becomes"children"packages/components/src/__tests__/page-body-single-node-8310.test.tsxpackages/types/src/__tests__/page-body-arity-8310.test.ts.changeset/8912-grid-children-items.mdEach documentation edit is a one-key, one-line, line-count-preserving replacement (
1 +, 1 -perfile), so nothing that cites these files by line can rot.
Every hit was judged, never bulk-replaced
The bare word
itemsappears more often than the defect does. Counts re-derived on this branch's baseaeaa0f6, with the instrument proven on a known positive first — the quoted-JSON probe"items"returns 0 on the README, because that fence is a tsx object literal with unquoted keys. A probe
that spans only one of the two syntaxes produces a false zero on the single most important surface.
README.md:236items: [content/docs/guide/schema-rendering.md:131"items": [content/docs/guide/schema-playground.md:214"items": [content/docs/guide/schema-rendering.md:170Use arrays for multiple items:content/docs/guide/schema-rendering.md:444"${items.length === 0}"content/docs/guide/schema-rendering.md:445"No items found"A structural probe over every tracked file (a
gridtype literal in either syntax, with anitemskey within ten lines) finds no fourth authoring surface. Its two remaining hits are window artefacts,
inspected and dismissed: a designer palette group's member list in
PageDesigner.tsx, and atransport envelope
makeDS({ items: [VIEW] })in adata-objectstackpin whosetype: 'grid'is alist-view config. The only
itemsleft ingrid.tsxis the proseGap between items (0-12).This is the part worth reading before trusting any green below.
check:doc-typesasks only whether a fence'stypeliteral is a registered component.gridisregistered, so the fence passes; whether the snippet's other keys have a reader is that gate's
explicitly out-of-scope second dimension (objectui#4823).
check:doc-examplescompiles the fence againstBaseSchema, which is.passthrough()with an[key: string]: anyindex signature. That signature absorbs the undeclared key: exit 0, zerodiagnostics.
⇒ Both gates are green on the defect by design. Their greens appear in the table below because
they prove this change broke nothing, ⛔ never as evidence that the defect is repaired. The defect
validated, type-checked, rode onto the node and drew nothing — the only instrument that can see it is
what the renderer actually draws.
Discriminating power — proved in both directions
Both legs mutate a committed tree, prove the mutation reached disk by blob hash before any result
is read, restore under a
trapwith absolute paths, and verify the restore by state (git diff HEADempty plus a blob comparison against the
HEADblob), never by an exit code.Leg A — revert the README to the pre-repair spelling. The mutated blob comes out
d086dd5d0e8383b5bd5133acfa773d432bf8ac52, which is byte-identical to the README onorigin/main, sothe leg really does reconstruct the pre-repair file rather than something merely similar.
Leg B — revert the pin's own transcription to
items. This is the card's mechanism, and it showsexactly why a naive control passes on a broken build:
The two render-output assertions go red; the grid-element assertions in the same run stay
green — the
pagewrapper and thegridelement are drawn even in the broken state. The renderedcontainer's
textContentis the empty string. That is the whole defect in one line.What the objectui#8310 render pin now guards
That file deliberately transcribed the flagship with
itemspreserved, so this defect could nothide inside a green, and its own source comment said not to tidy it. Converted rather than deleted or
weakened:
statisticlabels are actually drawn — the render-output evidence;its children are not. This is the firing control, and it is also the floor set by standard #0.1 —
teaching
gridthe second spelling would redden it;#### Basic Usagefence and requireschildren: [with noitemskey, so the transcription cannot drift into fiction. Leg A above is the proof that this legcan fail.
not turn this pin red on its own: before this PR the file held only a local transcription and
never read
README.mdat all, so nothing tied it to the landing page's bytes. The types-side pin doesread the README, but its scan leg asserts
bodyarity and the page/grid/statistic shape — never thechild key. Measured, not assumed: both pins were green immediately after the documentation edit.
The README-scan leg added here is what makes that expectation true from now on.
Patch round — the arity pin's stale truths
Landing the repair above made four statements in
packages/types/src/__tests__/page-body-arity-8310.test.tsfalse, and nothing went red, which is exactly why it would have rotted quietly:
BaseSchemacarries[key: string]: any, and that file's subject isbodyarity, not the child key. Repaired in thesame PR that falsified them:
items: [at:92children: [gridnode the README's flagship example hands tobody"childrenspelling and the carditemsas a live, unrepaired defectitems[]children[]⛔ Stale-truth repair only — nothing this pin asserts moved. All 28 of the file's
it(/describe(/expect(lines are byte-identical before and after (compared as text, since theprose edits shifted line numbers). Outside comment lines the entire diff is two hunks: a docblock
opener reflowed from one line to a block, and
items: [becomingchildren: [. The arity ruling thispin enforces, and its README-scan leg's assertions about
body's arity, are untouched. The pin wasnot restructured and no leg was added to it — the README-scan leg belongs in the render pin,
where it is.
The compile-time leg is genuinely enforced rather than merely globbed:
tsc -p tsconfig.test.json --listFileslists this pin 1 time, withpackages/types/src/layout.tsas a positive control (1)and a components test as a negative control (0).
Gates
scripts/pm/dispatch-gates.mjsdoes not exist in this repository, so these families werederived by hand from the actual changed-file set and are declared as such. Every exit code was
captured before any pipe.
pnpm exec vitest run packages/types/+ the render pinpnpm --filter @object-ui/types run type-checktsc -p tsconfig.test.json, which compiles the arity pinpnpm exec vitest run packages/components/check:doc-typescheck:doc-examplescheck:doc-snippetscheck:doc-fencescheck:control-bytescheck-changeset-presencecheck-changeset-no-majorcheck-governed-queue-guard --testcheck:doc-snippetsandcheck:doc-examplesfirst returned exit 2 = PRECONDITION NOT MET, whichis neither a pass nor a red: the packages they resolve against were unbuilt, so the programs never
ran. The scoped build those gates name was run (35 of 35 tasks successful) and both were re-run to a
real exit 0. Heavy runs went through
scripts/pm/os-verify-lock.sh; each reportsVERDICT command-exit 0from the runner's own verdict line.patch round, and the reason is stated rather than implied: the patch round changed exactly one file, a
test under
packages/types/src/__tests__/, which is not a documentation surface and is not part of anypackage's build output — so neither gate's inputs moved.
origin/mainwas merged in first (a merge, norebase, no force-push) and touched only
apps/site, which those gates also do not read.Blast radius checked by content rather than by guess: of every test that reads a file this PR edits,
exactly two exist — the two objectui#8310 pins, both of which are in this diff and both green. The
three
packages/layouttests that mention "Basic Usage" readcontent/docs/layout/app-shell.mdxandcontent/docs/guide/layout.md, neither of which is touched here.Re-grading triggers — both measured, neither fires
create-*template or scaffold inlines theflagship. The nearest candidate, the VS Code extension's insert-schema command, authors a different
and correct shape — a
divcarrying Tailwind grid classes with its children onbody, a declaredand read channel.
content/docs/guide/meta.json, and the README is the repository and npm landing page.⇒
priority:p2stands.验收备注
repaired only after the file was added to this card's declared surface. Serial constraint re-derived
independently before editing: PR feat(types): declare
drillDown/title/compareToon both published copies of ObjectChartSchema (objectui#8885) #8895 touches three files underpackages/types/src/__tests__/—imported-defaults-8317.test.ts,object-chart-undeclared-keys-8885.test.tsandzod-mirror-parity.test.ts— andpage-body-arity-8310.test.tsis not among them.this card asked whether an authored child key has any reader at all.
as written with respect to its
bodyarity — one node, not a list — and thebodyvalue isstill the single
gridnode it was. Only the child key inside it moves.action — recorded above so the next seat running that probe does not re-investigate them.
.changesetuses the empty-frontmatter form: the only published-source files in the diff are tests,and no runtime surface moves.
🤖 Generated with Claude Code
https://claude.ai/code/session_01MPaVWWMuWeT5LgB1qoXjVB