Repository navigation
docs: six public hooks still have no hook doc or live example #11207
Description
The docs-coverage sweep filed a "docs(useX): add hook docs and a minimal live example" issue for 14 hooks (#9480, #9484, #9486, #9490, #9491, #9559–#9566, #9572). All 14 are now closed. Per architecture:knowledge-contracts INV28 and DEC-16, a public hook without a hook doc and a conforming example is a docs gap that belongs in the issue queue.
I ran the example-coverage report (apps/docsite/src/__tests__/example-coverage.test.ts) on current main, against an API surface built with node scripts/api-report/cli.mjs --surface <dir>. For @astryxdesign/core it reports 110 public hooks: 31 have no hook doc, and 37 have no block that names them in exampleFor or alsoExampleFor. Most of the 31 are context hooks that components use internally. These six have no hook doc and no example block, and app code is meant to call them:
| Hook | Entry point | Why app code calls it |
|---|---|---|
useOutlineFromDOM |
Outline |
Outline.doc.mjs tells callers to use it for generated headings. Its sibling useOutlineFromMarkdown got a page in #9572. |
useThemeName |
theme |
Its JSDoc names consumers that need only the theme identity. useTheme already has a page. |
useSyntaxTheme |
theme, theme/syntax |
Its JSDoc example reads syntax colors in app code (a canvas code view). SyntaxTheme.doc.mjs does not cover the hook. |
useChatDictation |
Chat |
Its file header calls it the one hook consumers call for voice input. The ChatDictationButton blocks use it, but their exampleFor is the button, so the hook has no page. |
useSpeechRecognition |
Chat |
A headless SpeechRecognition wrapper. ChatDictationButton.doc.mjs accepts its return value. |
useChatPasteAsToken |
Chat |
ChatComposerInput.doc.mjs tells callers to pass its result to customize paste-as-token. |
The report also lists these hooks. I am not sure whether they are meant for app code. Each one is exported and has a documented use outside its component, but each could also be internal plumbing:
useChatComposerContext: a context hook, butChatComposer.doc.mjsnames it as the contract for a custom input.useChatStreamScrollanduseChatNewMessages: their headers say "also usable standalone", but they are wired to ChatLayout's context.useSideNavCollapse: reads the collapse state, for example for a custom collapse control.useStepperContext: its JSDoc calls the return value the Stepper's public context.useIndicator: resolves a theme's indicator, likeuseIcon(docs(useIcon): add hook docs and a minimal live example #9563), but its header says controls use it.useSize: resolves a size prop against the inherited size, for authors of custom components.useBaseTablePlugins: turns a plugin record into a stable array forBaseTable.
Six hooks already have a hook doc but no example block: useAnimatedLayout, useDevWarning, useEntryAnimation, useIndicatorFocusRing, useLongPress and useMenuPress. Under INV28 each one needs only an example.
I left out the remaining context hooks the report lists (useTabListContext, useLayerContext, useButtonGroup, and similar) and the layer internals (useLayerDismissal, useTouchTrigger, useSelectedItemOffset).
Questions:
- Should the six hooks in the table get the same kind of issue as the closed series?
- For the "not sure" list: which of these are public API that should get a page, and which should stay undocumented?
- Should the six hooks that have a doc but no example get example-only issues?
I can take the docs and examples for whichever hooks you confirm, one pull request per hook, in the same format as the closed series.
Activity