docs(v4): ship the v4 documentation site - #867
Merged
Merged
Conversation
123 pages on the packages/docs theme, written against DESIGN.md and RATIONALE.md with every signature verified against src/ or the built declarations: the guide, the full Base API, one page per service, decorator, registry helper and context function, and the utils reference by category. The site lives inside the v4 package rather than beside packages/docs: its VitePress, Tailwind and twoslash dependencies are v4 devDependencies and its scripts hang off @studiometa/js-toolkit-v4, so packages/* in the workspaces glob needs no change. Samples are twoslash-checked, which caught four claims that were wrong: on<Child><Event> methods get no automatic parameter typing; @on checks an annotation rather than replacing it; only @on's class form carries the payload type, since a string is just a string to the type system; and an intermediate class must annotate `static config: BaseConfig` or its inferred literal type breaks every subclass that adds an option. packages/v4/docs/** joins the relaxed oxlint override beside test/ and scripts/, since the strict type-aware block for packages/v4/**/*.ts flags the copied VitePress theme. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012ioM9dGKVhexCv4NLUcbA7
A second Cloudflare Pages job rather than two builds in one, so a v4 docs failure cannot hold back the v3 deploy. It builds the v4 package first. The committed @twoslash-cache comments mean twoslash normally does not run in CI at all, but the v4 exports map has no `typescript` condition — so on a cache miss twoslash resolves the package types out of dist, and without that step the miss would fail the build instead of type-checking against a stale or absent tree. The custom domain still has to be attached to the js-toolkit-v4 Pages project in the Cloudflare dashboard; `pages deploy` does not create one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_012ioM9dGKVhexCv4NLUcbA7
Export sizeBundled per export with peer dependencies left external, dynamic imports excluded and the output minified; sizes are gzipped. ✅ No export size changes. Unchanged (399)@studiometa/js-toolkit
@studiometa/js-toolkit-v4
|
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## main #867 +/- ##
=======================================
Coverage 97.06% 97.06%
=======================================
Files 176 176
Lines 4561 4561
Branches 1330 1331 +1
=======================================
Hits 4427 4427
Misses 122 122
Partials 12 12
Flags with carried forward coverage won't be shown. Click here to find out more. ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
Code ReviewRisk: Low — No concrete defects were identified in the files opened for review; the documentation site is safe to merge aside from the unreviewed files noted below. Adds the v4 VitePress documentation content and documents services, decorators, configuration, events, registry APIs, context helpers, and utilities. The reviewed pages consistently describe the v4 API and include the intended typing corrections for delegated events, scroll progress, and component configuration. Notes:
Review usage: 423,569 in (327,824 cached) / 2,200 out tokens — $0.0828 (openrouter/openai/gpt-5.6-luna, thinking: low) Reviewed by @weareikko/code-review v0.9.5 for commit a14a62c. |
v4 mount benchmarksBase and head measured on this runner, alternating over 3 rounds each; every value is the median of the round medians. Running both sides on one machine is what removes cross-machine noise — a cached baseline from another runner would put it back. A move under 25%, or on a benchmark under 5 ms, is not reported as a change: it is inside the measured noise of a shared runner.
Within noise (17)
|
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.
Adds the v4 documentation site and deploys it to
js-toolkit-v4.studiometa.dev.The site
123 pages at
packages/v4/docs, on the same theme aspackages/docs—.vitepress/theme/is copied verbatim (DefaultTheme + Tailwind 4 +@studiometa/tailwind-config+ twoslash client +PreviewIframe.vue).api/— Base, HTML, registry, shared state, services, decorators, scheduler, DOM, storage, diagnostics, testingutils/— 14 category pages + overviewContent is written against
DESIGN.mdandRATIONALE.md, with every signature verified againstsrc/or the built declarations rather than taken from the spec on trust.It lives inside the v4 package
Not beside
packages/docs. The VitePress, Tailwind and twoslash dependencies are devDependencies of@studiometa/js-toolkit-v4, the scripts aredocs:dev/docs:build/docs:previewon that package, and the root exposesdocs:v4:dev/docs:v4:build/docs:v4:preview. There is nopackages/v4/docs/package.json, so thepackages/*workspaces glob is unchanged.Twoslash caught four wrong claims
Type-checked samples paid for themselves — each of these was a statement that would otherwise have shipped as documentation:
on<Child><Event>methods get no automatic parameter typing. The name is resolved at runtime, so the payload needsDelegatedEvent/RefEvent/GlobalEvent.@ondoes not remove that annotation — it checks it. A decorator cannot infer the method's own parameters. The specs confirmed the correction.@on's class form carries the payload type.@on('Child', 'open')leavespayloadasunknown, because a string is just a string to the type system. Now a table on the@onpage, since a lazy child has no choice but the string form.static config: BaseConfig. Left inferred it becomes a literal type, and every subclass that adds an option fails withClass static side … incorrectly extends.Two claims taken from the design doc that the shipped code does not match were also corrected:
ScrollProgressPropscarries nodelta, and theoffsetoption is"<target> <viewport> / <target> <viewport>"with the default'start end / end start'— documented fromscroll-progress-offset.ts.Deployment
A second job in
.github/workflows/docs.yml, rather than two builds in one, so a v4 docs failure cannot hold back the v3 deploy. It runsnpm run build:v4first: the committed@twoslash-cachecomments mean twoslash normally does not run in CI, but the v4 exports map has notypescriptcondition, so on a cache miss twoslash resolves the package types out ofdist.Important
Two things are needed on the Cloudflare side before the job can succeed:
js-toolkit-v4;js-toolkit-v4.studiometa.devattached to it.wrangler pages deploycreates neither. The existingCLOUDFLARE_API_TOKENandCLOUDFLARE_ACCOUNT_IDsecrets are reused as-is.Checks
The full CI sequence was also run from a clean tree (
rm -rf packages/v4/dist→build:v4→docs:v4:build) with no twoslash cache drift.Notes for review
packages/v4/docs/**joins the relaxed.oxlintrc.jsonoverride besidetest/**andscripts/**— the strict type-aware block forpackages/v4/**/*.tsflags the copied VitePress theme.@studiometa/js-toolkit-v4so their types resolve against the package that exists today; the installation page states plainly that readers should read it as@studiometa/js-toolkit.utils/*subpaths should each get their own page.🤖 Generated with Claude Code
https://claude.ai/code/session_012ioM9dGKVhexCv4NLUcbA7