Draft
Conversation
…s, selectors, and utilities Introduces a convention-based auto-discovery system that generates API reference documentation for non-component exports: React hooks, HTML controllers/mixins, factory functions, selectors, contexts, and utilities. The builder scans package entry points, classifies exports by naming convention (`use*`, `*Controller`, `create*`, `select*`) or `@public` JSDoc tag, extracts type information via typescript-api-extractor and raw TS AST, and outputs JSON consumed by new Astro components (`UtilReference`, `UtilParamsTable`, `UtilReturnTable`). Key design decisions: - Framework-agnostic entries (selectors, createSelector) omit the `frameworks` JSON field, meaning they apply to all frameworks - Framework-specific entries (hooks → react, controllers → html) get `frameworks: ['react']` or `frameworks: ['html']` - Slug collisions use the actual framework prefix (not hardcoded `html-`) - Discovery casts a wide net; only exports with both generated JSON AND a manually-created MDX page appear in the docs - Controller extraction handles both overload declarations and single constructors with a body Also renames ApiReference → ComponentReference to disambiguate from the new UtilReference, adds interactive demos for key utils, and updates the sidebar with Selectors, Hooks & Utilities, and Controllers & Mixins sections. Closes #466 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
✅ Deploy Preview for vjs10-site ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
Contributor
📦 Bundle Size Report
Total: 34.51 kB · 0 B · 0% Entry BreakdownSubpath sizes are the additional bytes on top of the root entry point, measured by bundling root + subpath together and subtracting the root-only size.
|
| Entry | Base | PR | Diff | % | |
|---|---|---|---|---|---|
. |
2.77 kB | 2.77 kB | 0 B | 0% | ✅ |
./dom |
2.60 kB | 2.60 kB | 0 B | 0% | ✅ |
| total | 5.37 kB | 5.37 kB | 0 B | 0% |
@videojs/element
| Entry | Base | PR | Diff | % | |
|---|---|---|---|---|---|
. |
817 B | 817 B | 0 B | 0% | ✅ |
./context |
823 B | 823 B | 0 B | 0% | ✅ |
| total | 1.60 kB | 1.60 kB | 0 B | 0% |
@videojs/icons
| Entry | Base | PR | Diff | % | |
|---|---|---|---|---|---|
./react |
4.77 kB | 4.77 kB | 0 B | 0% | ✅ |
./html |
1.64 kB | 1.64 kB | 0 B | 0% | ✅ |
| total | 6.40 kB | 6.40 kB | 0 B | 0% |
@videojs/react
| Entry | Base | PR | Diff | % | |
|---|---|---|---|---|---|
. |
7.67 kB | 7.67 kB | 0 B | 0% | ✅ |
./audio |
267 B | 267 B | 0 B | 0% | ✅ |
./background |
40 B | 40 B | 0 B | 0% | ✅ |
./video |
244 B | 244 B | 0 B | 0% | ✅ |
| total | 8.20 kB | 8.20 kB | 0 B | 0% |
@videojs/store
| Entry | Base | PR | Diff | % | |
|---|---|---|---|---|---|
. |
1.29 kB | 1.29 kB | 0 B | 0% | ✅ |
./html |
468 B | 468 B | 0 B | 0% | ✅ |
./react |
199 B | 199 B | 0 B | 0% | ✅ |
| total | 1.94 kB | 1.94 kB | 0 B | 0% |
@videojs/utils
| Entry | Base | PR | Diff | % | |
|---|---|---|---|---|---|
./array |
104 B | 104 B | 0 B | 0% | ✅ |
./dom |
684 B | 684 B | 0 B | 0% | ✅ |
./events |
227 B | 227 B | 0 B | 0% | ✅ |
./function |
197 B | 197 B | 0 B | 0% | ✅ |
./object |
119 B | 119 B | 0 B | 0% | ✅ |
./predicate |
265 B | 265 B | 0 B | 0% | ✅ |
./string |
110 B | 110 B | 0 B | 0% | ✅ |
./style |
63 B | 63 B | 0 B | 0% | ✅ |
./time |
478 B | 478 B | 0 B | 0% | ✅ |
./number |
158 B | 158 B | 0 B | 0% | ✅ |
| total | 2.35 kB | 2.35 kB | 0 B | 0% |
ℹ️ How to interpret
Sizes are minified + brotli, measured with esbuild.
Package totals are computed as root size + marginal subpath costs.
Subpath marginal cost = (root + subpath bundled together) − root alone.
| Icon | Meaning |
|---|---|
| ✅ | No change |
| 🔺 | Increased ≤ 10% |
| 🔴 | Increased > 10% |
| 🔽 | Decreased |
| 🆕 | New (no baseline) |
Run pnpm size locally to check current sizes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Note
Marked as draft while under human review. I'm mostly worried about the mdx. Did we document the right APIs? If so, how's the copy? How are the examples?
Summary
Adds a complete API reference documentation system for non-component exports — React hooks, HTML controllers/mixins, factory functions, selectors, contexts, and utilities. This complements the existing component reference pipeline and brings full API documentation coverage.
Util auto-discovery builder
site/scripts/api-docs-builder/src/util-handler.tsuse*→ hook,*Controller→ controller,create*→ factory,select*→ selector) or@publicJSDoc taggenerated-util-reference/consumed by new Astro componentsFramework metadata
react, controllers →html) serializeframeworks: ['react']orframeworks: ['html']in JSONcreateSelector) omit theframeworksfield entirely, meaning they apply to all frameworks${framework}-${slug}) instead of hardcodedhtml-Reference pages (29 util APIs documented)
usePlayer,useMedia,useStore,useButton,useSelector,useSnapshot,useMediaRegistration,usePlayerContext,createPlayer,mergeProps,renderElementPlayerController,StoreController,SnapshotController,playerContext,PlayerMixin,ContainerMixin,ProviderMixin,createPlayercreateSelector,selectBuffer,selectControls,selectFullscreen,selectPiP,selectPlayback,selectSource,selectTime,selectVolumeAstro components
UtilReference.astro— main component, handles single/multi-overload renderingUtilParamsTable.astro— parameter table (reusesPropRow)UtilReturnTable.astro— return value table with object field expansionApiReference.astro→ComponentReference.astroto disambiguateOther changes
remarkConditionalHeadingsupdated to inject<UtilReference>TOC headingsSubscriptionControllerwarning_sourceFileparameter fromgetJSDocParamDescriptiontoKebabwithkebabCasefrom es-toolkit (already a dependency)Preview
Selectors
Hooks & Utilities (React)
Controllers & Mixins (HTML)
Test plan
pnpm api-docsgenerates 29 util JSON files with correct framework metadatapnpm -F site test— all 270 tests pass (19 util-handler tests)create-selector.jsonhaskind: 'factory', noframeworksfieldframeworksfield (agnostic)frameworks: ['react']frameworks: ['html']biome checkCloses #466
🤖 Generated with Claude Code