finding(docs): sidebar-nav.mdx's grouped-navigation example leaves `navigationItems` unannotated, so `badgeVariant` widens to `string` and `SidebarNav` rejects the whole array (TS2322)

[yinlianghui-tw]

Measured by the #6120 dev while probing that card's fix (session session_019b5UBNMtTzKbVtZZGvFuxe, on origin/main 133e2ea1e, with lucide-react resolution in place from PR #6129). Filed rather than fixed: re-fencing the content/docs/layout blocks is #5867's lane, and #6120 was scoped to the resolution defect only.

The measurement

With PR #6129's third-party resolution in place, four of the five content/docs/layout blocks that were red on lucide-react compile clean. The fifth — content/docs/layout/sidebar-nav.mdx, the "complete example" block whose fence sits at line 191 — is red for its own, unrelated reason:

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

The cause

The block writes:

const navigationItems = [
 {
 label: 'Workspace',
 items: [
 { title: 'Inbox', href: '/inbox', icon: Mail, badge: 8, badgeVariant: 'destructive' },
 ...

with no type annotation. So badgeVariant's string literal widens to string, and the declared shape (packages/layout/dist/SidebarNav.d.ts) is a union of literals:

export interface NavItem {
 title: string;
 href: string;
 badgeVariant?: 'default' | 'destructive' | 'outline';
 ...
}
export interface NavGroup { label: string; items: NavItem[] }
export interface SidebarNavProps { items: NavItem[] | NavGroup[]; ... }

string is not assignable to that union, so the NavGroup[] branch fails; TypeScript then reports the other branch of the union, 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 is right. The annotation is missing.

A reader who copies this block verbatim into an annotated position, or who has strict on and assigns it anywhere typed, gets the same error.

Measured fix

Annotating the array — importing the type in the same block, since every block is compiled in isolation — takes it to zero:

import { SidebarNav, type NavGroup } from '@object-ui/layout';
const navigationItems: NavGroup[] = [

Probed under an EXIT trap with the five layout blocks temporarily re-fenced: Semantic phase: 211 of 211 block(s) judged, 0 failed, gate exit 0. Without the annotation, that same run is 1 failed.

⚠️ Note for whoever takes this: the annotation must resolve, not merely be written. A first probe added : NavGroup[] while the import landed in a different block, producing TS2304: Cannot find name 'NavGroup' — and with the annotation itself erroring, TypeScript stopped checking the literal underneath and the TS2322 disappeared. That is the same false-green shape guide/theming hit (recorded in scripts/check-doc-snippet-types.mjs's ledger): an annotation that errors silently switches off the check it was added to perform.

Scope

Belongs with the content/docs/layout re-fence under #5867 — this block cannot be brought under the gate without it. Filed unassigned.

Refs: #5867 (parent lane) · #6120 / PR #6129 (where this was measured).

Generated by Claude Code

[yinlianghui-tw]

os-dev-report

{
 "issue": 6131,
 "status": "done",
 "branch": "claude/issue-6131-sidebar-nav-badgevariant",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6139",
 "premise_still_valid": true,
 "summary": "Annotated the 'Complete Example' block in content/docs/layout/sidebar-nav.mdx as `const navigationItems: NavGroup[]`, importing `type NavGroup` in the same block from '@object-ui/layout' (every doc block compiles in isolation, so the annotation must resolve or it silently switches off the check it was added to perform). Two lines of MDX plus an empty-frontmatter changeset -- objectui has no skip-changeset label, so a docs-only changeset is the declaration here. The fence stays `plaintext`: re-fencing content/docs/layout is #5867's lane and was deliberately not taken as a rider. The issue's premise held on current origin/main, but its NUMBERS did not -- the compile population grew from 211 to 224 since PR #6129 merged, so everything below was re-derived rather than inherited.",
 "tests": "All at commit 1803226b7, tree clean (base d5b80c678). REPRODUCTION, throwaway re-fence of the one fence at line 191 under an EXIT trap: gate exit 1, 'Semantic phase: 224 of 224 block(s) judged, 1 failed', on 'content/docs/layout/sidebar-nav.mdx:235:7 TS2322: Type ... is not assignable to type NavItem[] | NavGroup[]'. AFTER the annotation, same probe: exit 0, 'Semantic phase: 224 of 224 block(s) judged, 0 failed'. NON-VACUITY ablation (fix committed FIRST, restore leg was `git checkout HEAD -- ` plus the path, never the bare form): with the annotation removed and the block still re-fenced, the identical TS2322 returns at the identical site 235:7, 'Semantic phase: 224 of 224 block(s) judged, 1 failed', exit 1; restoring returns exit 0. Both mutation legs were confirmed ON DISK by grepping for the exact text inserted and removed (annotated-const count, bare-const count, 'type NavGroup' occurrence count, ts-fence count) BEFORE any result was read -- the first fix attempt was in fact a zero-hit no-op that exited 0, and only the anchored grep caught it. Gate counts: diagnostics 0, declared fragments UNMOVED at 111 across all four runs, no FRAGMENT_MARKER added, UNGATED_DOCS / ledger / gate untouched. GATES, each quoting its own verdict line: 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 (never package-scoped) over packages/layout/src/__tests__ and scripts/__tests__/check-doc-snippet-types.test.ts: 'Test Files 20 passed (20)', 'Tests 232 passed (232)'. DOCS BUILD: @object-ui/site build exit 0, and the rendered apps/site/.next/server/app/docs/layout/sidebar-nav.html carries both the annotated `navigationItems: NavGroup[]` and the `type NavGroup` import, so the page still renders. Compiled against FRESHLY BUILT dist -- packages/layout/dist/SidebarNav.d.ts confirms the declared union `badgeVariant?: 'default' | 'destructive' | 'outline'` the issue quoted. LINT, narrowing declared not skipped: population read from eslint's OWN config rather than guessed -- `eslint --no-inline-config --format json` over the two changed files reports 2 files, 0 errors, both 'File ignored because no matching configuration was supplied', so content/docs/** and .changeset/** are outside the lint population entirely; no TS/JS source changed, so no untouched file's verdict can move. Exit codes were captured before any pipe throughout.",
 "open_questions": [],
 "out_of_scope_findings": []
}

Layout group status for #5867: unblocked. This was the one content/docs/layout block
that stayed red for a cause of its own after PR #6129 fixed the resolution half. With the
annotation landed, a re-fence of all five layout blocks is a pure fence change: measured
here at Semantic phase: 224 of 224 block(s) judged, 0 failed, gate exit 0, with the
complete-example block re-fenced as ts.

One environment note, not a defect in this diff: the site build fails with
Module not found: Can't resolve '@object-ui/plugin-gantt' (and plugin-map) until the
workspace packages are built, because the root build script excludes the site. It is
green after turbo run build --filter='!@object-ui/site'. Not filed as an issue -- it is a
local build-order property, and CI builds before it renders.

Generated by Claude Code

---

Generated by Claude Code

[yinlianghui-tw]

PM review — ACCEPT, landed

Reviewed by the domain:devx @ objectui execution seat (#5748), PM session session_019b5UBNMtTzKbVtZZGvFuxe. PR #6139 verified against GitHub: 20 checks, 20 success/skipped, zero failures. Marked ready and auto-merge armed (SQUASH) in the same turn.

What made this report trustworthy

⭐ The on-disk grep caught a no-op fix. "the first fix attempt was in fact a zero-hit no-op that exited 0, and only the anchored grep caught it." That is the discipline earning its keep in real time, not as ceremony — an editor exit code is not evidence a mutation reached disk, and this run has the counterexample to prove it. Both mutation legs confirmed by grepping the exact inserted and removed text before any result was read.

⭐ Numbers re-derived rather than inherited. The card's compile population was 211; #6129 merged in between and it is now 224. The report says so explicitly and re-derives every figure. A report that had quietly reused 211 would have been wrong in a way nothing downstream would have caught.

⭐ The annotation was shown to be load-bearing. Removing it returns the identical TS2322 at the identical site 235:7; restoring it returns exit 0. And the reasoning for importing type NavGroup in the same block is the right one and worth restating: 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 original diagnostic disappears — the false-green shape already recorded for guide/theming. A fix that silently switches off the check it was added to perform is worse than no fix.

The declared-fragment count is unmoved at 111 across all four runs, no FRAGMENT_MARKER was added, and UNGATED_DOCS / the ledger / the gate are untouched.

Scope discipline: correct

Leaving the fence plaintext was right. Re-fencing content/docs/layout is #5867's lane, and taking it as a rider here would have merged a type fix into a fence batch — two different verification surfaces in one diff.

The handback this seat is taking forward

⭐ The layout group is unblocked for #5867. This was the one content/docs/layout block still red for a cause of its own after PR #6129 landed the resolution half. Measured here at Semantic phase: 224 of 224 block(s) judged, 0 failed with the complete-example block re-fenced, so that batch is now a pure fence change. Recorded for the next #5867 dispatch, along with your note that a batch is in flight in objectui-5867-b3 and may want a rebase onto this.

The site-build note (@object-ui/plugin-gantt / plugin-map unresolvable until the workspace is built, because the root build script excludes the site) is the fourth independent sighting of the same local build-order property today. Correctly judged environmental and correctly not filed — but four sightings is itself a signal, and this seat is tracking it rather than letting each dev rediscover it.

---

Generated by Claude Code