docs+example: package READMEs, vue/angular demo parity, source panels - #32
Merged
Conversation
Each React page duplicated its own <nav>, and none of the three apps offered a way back to the Pages landing page - once you were in /react you were stuck there. DemoNav centralises the links and adds an absolute 'Tất cả demo' link; absolute because the landing page only exists on the deployed site, one level above each app's base path.
Why: A demo you cannot read the code of only proves the library runs - it does not show how. Linking to GitHub means leaving the page, and a hand-written snippet drifts from the code that is actually running. What: Each route splits into a Server Component page and a client `demo.tsx`. The page reads its own demo's source with fs and passes it to DemoShell, which renders it in a toggleable side panel with a copy button. Because every route is statically exported, the read happens at build time and the text is baked into the HTML - no runtime fetch, and the snippet is by construction the code that rendered the form next to it. Tried `?raw` imports first: Turbopack compiles them inside a private folder but fails on a real route, so fs in a Server Component is the approach that works. How to test: cd example/react-app && npm run build # then open out/wizard/index.html
Why: Neither demo referenced a single v1.4 feature. Grepping both for useDynamicForm, createDynamicFormStore, createWizardState, DynamicFormDevTools, radio, range, switch or onBlurField returned zero hits, while the react app had three pages covering all of it. Anyone opening the Vue or Angular demo saw a library two releases out of date. Neither had a way back to the Pages landing page either. What: - Vue: EnterpriseDemo.vue (useDynamicForm, extended renderers, blur wiring, DevTools) and WizardDemo.vue, as two new tabs. - Angular: the same pair as standalone components, using createDynamicFormStore and its signals, plus the (onBlurField) output. - Both gain the '← Tất cả demo' link, absolute for the same reason as react. - Both show the demo's source beside it, matching the react panel. Vue uses Vite's native `?raw`; Angular's builder has no equivalent, so scripts/embed-demo-sources.js generates a module from the real files and is wired to prestart/prebuild, which keeps the panel from ever going stale. Label is '‹/› Xem code', not '</>': Angular's template parser reads the `</` inside an interpolated string as a closing tag and fails to compile. How to test: cd example/<app> && npm install && npm run build
Why: None of the four package READMEs mentioned the v1.4 surface. Grepping each for useDynamicForm, createDynamicFormStore, createWizardState, goNext, DynamicFormDevTools, zodValidator, onBlurField or defaultRenderersMap returned: core 0, react 2 (bare names in a list), vue 0, angular 0. Someone installing from npm and reading the package page saw a library two releases out of date. All four also linked a "Demo app" repo that is not where the demos live. What: - core: schema adapters (form vs field target, sync vs async), the wizard state machine with a table of every export, and the group array helpers. The "What this package provides" list now covers them too. - react / vue / angular: a form-state section with the full member table in each framework's idiom - props, refs, signals - plus default renderers and DevTools. Each notes how blur is wired, since that differs: a prop in react and vue, a focusout-driven @output in angular. - Point every "Live demo" link at the deployed Pages site. Every identifier written into these files was checked against the built dist. How to test: npm run format-check
.gitignore already excludes .superpowers/ as "scratch/planning docs, not subject to version control", but docs/superpowers/ held the same kind of content - eight internal plan and spec files - and was tracked, so it showed up on the repo page next to the real documentation. Untracked rather than deleted: the files stay on disk, and remain in history if they are ever needed.
README.md is in the published tarball - npm includes it regardless of the `files` field - so the v1.4 documentation only reaches the package pages through a release. Patch rather than --empty for that reason.
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
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.
What
Three gaps found after #31 merged, plus two follow-ups requested while reviewing the deployed demos.
Package READMEs documented none of the v1.4 surface. Grepping each for
useDynamicForm,createDynamicFormStore,createWizardState,goNext,DynamicFormDevTools,zodValidator,onBlurFieldordefaultRenderersMap:core(344 lines)react(256 lines)vue(242 lines)angular(235 lines)Anyone reading a package page on npm saw a library two releases out of date. All four also linked a "Demo app" repo that is not where the demos live.
The Vue and Angular demos referenced zero v1.4 features. React had three pages covering everything; the other two had one file each and not a single hit for any new API. Both now have Enterprise and Wizard tabs —
useDynamicForm/createDynamicFormStore, extended renderers, blur wiring, DevTools, and the wizard engine.No way back to the landing page. Once you were in
/reactyou were stuck. All three apps now carry an absolute "← Tất cả demo" link — absolute because the landing page only exists on the deployed site, one level above each app's base path.Code beside each demo. Every demo now shows its own source in a toggleable panel with a copy button, and it is guaranteed to be the running code rather than a snippet that can drift:
demo.tsxwithfsand a client demo. Static export means the read happens at build time and the text is baked into the HTML. (?rawwas tried first — Turbopack compiles it inside a private folder but fails on a real route.)?raw.scripts/embed-demo-sources.jsgenerates a module from the real files, wired toprestart/prebuild.docs/superpowers/untracked..gitignorealready excluded.superpowers/as scratch planning docs; the same content underdocs/was tracked and showed up next to the real documentation. Files stay on disk.Why
The features shipped in #31 were invisible to anyone who did not read the root README — which is most people arriving from npm or the demo site.
How to test