docs: document 10 exported Navbar*/Sidebar* sub-components and 6 public composables; clarify `./utils` status

[IgorShevchik]

Background

Surfaced during the June 2026 multi-angle project audit (documentation review). Docs coverage is otherwise strong — every spot-checked "Defaults to" claim matched the source — these are the genuine gaps. (FormField #label slot = #48, not repeated here.)

Scope

1. 10 exported components have no docs page or mention

Navbar, NavbarSection, NavbarDivider, NavbarSpacer, SidebarHeader, SidebarBody, SidebarFooter, SidebarSection, SidebarHeading, SidebarSpacer are public API (exported in src/runtime/types/index.ts:104-115, registered via addComponentsDir, each with its own src/theme/*.ts) but have no page under docs/content/docs/2.components/ and are not even mentioned on sidebar.md/sidebar-layout.md. They're also absent from the skill's references/components.md.
Action: dedicated pages or a "Sub-components" section on the Sidebar/SidebarLayout (and a new Navbar) pages + rows in the skill component index.
(Other undocumented names — *Content, LinkBase, ModalDialogClose, OverlayProvider, Toaster — are internals per nuxt/ui convention; fine as is.)

2. 6 of 17 auto-imported composables undocumented

src/imports.ts (publicComposables) auto-imports 17; docs/content/docs/3.composables/ covers 11. Missing: useFileUpload, useScrollspy, useKbd, useResizable, useContentSearch, useLocale. (useFileUpload's only mention in all docs is a passing reference in use-speech-recognition.md — the FileUpload component page doesn't mention it either.)

3. ./utils export status

src/runtime/utils/ is exposed via package.json exports (./utils, ./utils/*) but is entirely undocumented. At minimum state whether it's public, stable API; ideally a short reference page for the genuinely useful helpers.

Priority: P2. Related: JSDoc-pass issue covers the in-code documentation side.

[IgorShevchik]

Done in #530 — 45eb1a8a. All three parts settled, two of them not the way this issue asked, because it was filed in June and the ground moved underneath it.

§1 — the ten components are all deprecated now ✅

Every one of Navbar, NavbarSection, NavbarDivider, NavbarSpacer, SidebarHeader, SidebarBody, SidebarFooter, SidebarSection, SidebarHeading and SidebarSpacer was tagged @deprecated ... removed in 3.0.0 on 10 August, two months after this was written, in 07481295. Eleven of the twelve Navbar*/Sidebar* components are tagged — only Sidebar survives, and it already had a page. None of the ten is used anywhere in docs/ or playgrounds/; checked by name, zero hits each.

Ten pages for ten components scheduled for removal would have been ten pages to delete. Saying nothing was not an option either — somebody with <B24SidebarSection> in their code has to be able to find out it is going away. So SidebarLayout, already the deprecated page for this same legacy kit, now carries a table naming all ten against their replacement, each one read off the source rather than recalled.

That page also had a migration pointer aimed at a playground source file at a pinned SHA. It points at the Dashboard pages now.

§2 — you were right that upstream is just as empty ✅

nuxt/ui@v4 ships all seven of these composables and documents none of them with a page — 8 composable pages there against our 11.

	upstream	ours, before
useResizable	0	0
useScrollspy	0	0
useFileUpload	0	0
useLocale	0	1, in passing, on an unrelated page
useKbd / useContentSearch / useFormField	1	1–2

That changed the shape of the fix rather than whether to do it. Upstream does have a convention here — a short note on the page of the component the composable powers, with the call shown inline, the way useFormField sits on form.md. Followed that instead of inventing dedicated pages:

• useFileUpload — right next to "make your own FileUpload component"
• useScrollspy
• useResizable — under "Resizable"
• useLocale — on both i18n pages. Its own JSDoc already linked to one of them, so the link had been one-way the whole time

Also: this issue lists six composables and there are seven. useFormField is missing from the list. It is already covered where upstream covers it, so it needed nothing.

§3 — ./utils is internal ✅

Now stated in the FAQ on the introduction page: the subpath resolves, it exists so the components and the module can reach their own helpers across build boundaries, it is undocumented, and it changes without a deprecation cycle or a major bump.

The part worth keeping

Both code snippets in the first commit were wrong, and /review caught all four points by running them:

useResizable has four defaults that are not what the prop names suggest — unit is 'px' so bare sizes are pixels, defaultSize is 0, storage is 'cookie' which is a no-op stub outside Nuxt, and collapsible is false, which made the collapse() I had cheerfully documented completely inert.

And that last one had a cause: UseResizableProps.collapsible was annotated @defaultValue true while the composable and DashboardSidebar both default it to false. I took the tag at face value and wrote a snippet around a call that could never fire. Every @defaultValue in that type is now checked against the opts object — collapsible was the only liar. The rendered props table had always been right, because withDefaults beats the tag; the thing telling fibs was the IDE hint.

The useFileUpload note was worse: it promised "the hidden <input type="file">", and the composable renders nothing at all. inputRef wants a component (inputRef.value.$el), so binding it to a plain <input> fails silently until someone submits a form. Both traps are now ::warning blocks rather than landmines.

---

Thanks from the maintainer for this one — three tidy documentation chores that turned into a stale premise, an upstream comparison, and a @defaultValue that had been quietly lying to every IDE. Closing.

---

Generated by Claude Code