docs(layout): annotate the sidebar-nav grouped-navigation example as NavGroup[]

[yinlianghui-tw]

Fixes#6131

Two files: content/docs/layout/sidebar-nav.mdx (two lines) and a changeset.

The defect

The "Complete Example" block left navigationItems unannotated, so its
badgeVariant: 'destructive' widened to string. SidebarNav declares
badgeVariant?: 'default' | 'destructive' | 'outline', so the array stopped assigning to
items: NavItem[] | NavGroup[]. TypeScript then reports the union's other branch, which
is why the message reads "missing the following properties from type 'NavItem': title,
href" and looks at first like a wrong data shape. The data shape was always right — the
annotation was missing.

The fix

import{SidebarNav,typeNavGroup}from'@object-ui/layout';constnavigationItems: NavGroup[]=[

The type is imported in the same block, because every block compiles in isolation. An
annotation naming a type the block cannot see errors on the annotation itself, at which
point TypeScript stops checking the literal underneath and the TS2322 disappears — the
false-green shape already recorded for guide/theming in
scripts/check-doc-snippet-types.mjs. The import here resolves; the measurements below
are what prove it.

Measurement, re-derived on current origin/main (base d5b80c678, verified at 1803226b7)

The issue's numbers were taken before PR #6129 merged; the population has since grown from
211 to 224, so every number below is re-derived rather than inherited.

The block is still plaintext-fenced on main, so it is not in the compile population —
--build-filter does not even list @object-ui/layout. Re-fencing content/docs/layout
is #5867's lane, so the fence is left alone here and every measurement uses a throwaway
re-fence of that one fence under an EXIT trap.

run	blocks	declared fragments	failed	exit
baseline, branch as shipped (fence plaintext)	223	111	0	0
probe re-fenced, before the annotation	224	111	1	1
probe re-fenced, after the annotation	224	111	0	0

Reproduced diagnostic, before the fix:

content/docs/layout/sidebar-nav.mdx:235:7 TS2322: Type '{ label: string; items: (...)[] }[]'
is not assignable to type 'NavItem[] | NavGroup[]'.

Non-vacuity. The annotation is load-bearing, not decorative: removing it again (still
re-fenced) returns the identical TS2322 at the identical site 235:7, and
Semantic phase: 224 of 224 block(s) judged, 1 failed. Restoring it returns exit 0. Both
mutation legs were confirmed on disk by grepping for the specific text inserted and removed
before reading any result, and both restore legs ran from an EXIT trap against the
committed fix — git checkout HEAD -- followed by the path, never the bare form that
omits HEAD.

Declared fragment count is unmoved at 111, no FRAGMENT_MARKER is added, and
UNGATED_DOCS, the ledger and the gate itself are untouched.

Gates run, each quoting its own verdict line (all at 1803226b7, tree clean)

• check:doc-snippets exit 0 — Semantic phase: 223 of 223 block(s) judged, 0 failed. /
  Every covered documentation snippet compiles against the built types.
• check:doc-types exit 0 — Every documented component type is registered.
• check:control-bytes exit 0 — check-control-bytes: OK (scanned 5083 tracked text file(s); skipped 85 binary).
• docs:check-links exit 0 — Links are valid across 15 scan roots.
• vitest from the repo root, packages/layout/src/__tests__ plus
  scripts/__tests__/check-doc-snippet-types.test.ts — Test Files 20 passed (20),
  Tests 232 passed (232).
• Docs site build (@object-ui/site) exit 0, and the rendered
  apps/site/.next/server/app/docs/layout/sidebar-nav.html contains both the annotated
  navigationItems: NavGroup[] and the type NavGroup import, so the page still renders.

Lint, narrowing declared rather than skipped. The linted population was read from
eslint's own configuration, not guessed: eslint --no-inline-config --format json over the
two changed files reports 2 files, 0 errors, both with
File ignored because no matching configuration was supplied — content/docs/** and
.changeset/** are outside the lint population entirely. No TypeScript or JavaScript source
file changed, so no untouched file's lint verdict can move either.

One note on the environment, not on this diff: the site build fails with
Module not found: Can't resolve '@object-ui/plugin-gantt' until the workspace packages are
built, because the root build script excludes the site. After
turbo run build --filter='!@object-ui/site' it is green.

Scope

The type defect only. The fence stays plaintext and no other content/docs/layout
page is touched — #5867 remains open and its layout batch is not addressed here. With this
landed, the layout group has no remaining type defect of its own, so that batch should be a
pure re-fence.

Not marked ready and auto-merge is not enabled; the PM verifies CI and lands it.

Generated by Claude Code