From 1803226b771c1ccc26104204fe11e9f3425b3772 Mon Sep 17 00:00:00 2001 From: Claude Date: Mon, 24 Aug 2026 20:23:57 +0000 Subject: [PATCH] docs(layout): annotate the sidebar-nav grouped-navigation example as NavGroup[] (#6131) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The "Complete Example" block left `navigationItems` unannotated, so its `badgeVariant: 'destructive'` widened to `string` and the array no longer assigned to `SidebarNav`'s `items: NavItem[] | NavGroup[]`. TypeScript reported the union's other branch, so the message read as a wrong data shape; the shape was right. Annotate the array as `NavGroup[]` and import the type in the same block, since every doc block compiles in isolation and an annotation that does not resolve silently switches off the check it was added to perform. The fence stays `plaintext` — re-fencing `content/docs/layout` belongs to #5867. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_019b5UBNMtTzKbVtZZGvFuxe --- .../6131-sidebar-nav-navgroup-annotation.md | 36 +++++++++++++++++++ content/docs/layout/sidebar-nav.mdx | 4 +-- 2 files changed, 38 insertions(+), 2 deletions(-) create mode 100644 .changeset/6131-sidebar-nav-navgroup-annotation.md diff --git a/.changeset/6131-sidebar-nav-navgroup-annotation.md b/.changeset/6131-sidebar-nav-navgroup-annotation.md new file mode 100644 index 0000000000..bb475295e3 --- /dev/null +++ b/.changeset/6131-sidebar-nav-navgroup-annotation.md @@ -0,0 +1,36 @@ +--- +--- + +Docs only, publishes nothing: the "Complete Example" block in +`content/docs/layout/sidebar-nav.mdx` now annotates its grouped-navigation array as +`NavGroup[]`, importing the type in the same block (objectui#6131). + +Without the annotation the array's `badgeVariant: 'destructive'` widens to `string`, +and `SidebarNav`'s declared `badgeVariant?: 'default' | 'destructive' | 'outline'` +does not accept it — so the whole array fails to assign 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. A reader who copies this block into an annotated +position, or assigns it anywhere typed under `strict`, hits the same TS2322. + +Measured on this branch against the built `dist/*.d.ts`, with the block temporarily +re-fenced as `ts` under an `EXIT` trap so it joins the compile population (the fence +itself belongs to objectui#5867's lane and is deliberately left as `plaintext` here): + +- before the annotation, `Semantic phase: 224 of 224 block(s) judged, 1 failed`, gate + exit 1, on `content/docs/layout/sidebar-nav.mdx:235:7 TS2322`; +- after it, `Semantic phase: 224 of 224 block(s) judged, 0 failed`, gate exit 0. + +Removing the annotation again reproduces the identical TS2322, so it is load-bearing +rather than decorative. Declared fragment count is unmoved at 111, no +`FRAGMENT_MARKER` is added, and the covered/ungated sets are untouched. + +The annotation is written so that it **resolves**: 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`. + +This clears the last `content/docs/layout` block that stays red for a reason of its +own, so the layout group is type-clean ahead of objectui#5867 re-fencing it. diff --git a/content/docs/layout/sidebar-nav.mdx b/content/docs/layout/sidebar-nav.mdx index 8cc7354225..0baf0ff840 100644 --- a/content/docs/layout/sidebar-nav.mdx +++ b/content/docs/layout/sidebar-nav.mdx @@ -189,7 +189,7 @@ Set a custom title for the sidebar: ## Complete Example ```plaintext -import { SidebarNav } from '@object-ui/layout'; +import { SidebarNav, type NavGroup } from '@object-ui/layout'; import { Home, Users, @@ -200,7 +200,7 @@ import { Mail } from 'lucide-react'; -const navigationItems = [ +const navigationItems: NavGroup[] = [ { label: 'Workspace', items: [