Skip to content

docs+example: package READMEs, vue/angular demo parity, source panels - #32

Merged
vannt-dev merged 6 commits into
developfrom
feature/docs-and-example-parity
Aug 5, 2026
Merged

docs+example: package READMEs, vue/angular demo parity, source panels#32
vannt-dev merged 6 commits into
developfrom
feature/docs-and-example-parity

Conversation

@vannt-dev

Copy link
Copy Markdown
Owner

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, onBlurField or defaultRenderersMap:

before after
core (344 lines) 0 12
react (256 lines) 2 (bare names in a list) 12
vue (242 lines) 0 9
angular (235 lines) 0 9

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 /react you 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:

  • React: each route splits into a Server Component that reads demo.tsx with fs and a client demo. Static export means the read happens at build time and the text is baked into the HTML. (?raw was tried first — Turbopack compiles it inside a private folder but fails on a real route.)
  • Vue: Vite's native ?raw.
  • Angular: no equivalent in its builder, so scripts/embed-demo-sources.js generates a module from the real files, wired to prestart/prebuild.

docs/superpowers/ untracked. .gitignore already excluded .superpowers/ as scratch planning docs; the same content under docs/ 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

npm run lint && npm run format-check && npm run typecheck
for p in core react vue angular; do npm run test --workspace=@dynamic-field-kit/$p -- --coverage; done
cd example/vue-app && npm install && npm run build      # then the Enterprise / Wizard tabs
cd example/angular-app && npm install && npm run build

  • Tests unchanged and passing — core 117, react 116, vue 115, angular 74
  • Every identifier written into a README was checked against the built dist
  • All three example apps build
  • No changeset: docs and examples only, no package source changed

One thing worth knowing: '</> Xem code' had to become '‹/› Xem code'. Angular's template parser reads the </ inside an interpolated string as a closing tag and refuses to compile.

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.
@vannt-dev
vannt-dev merged commit c3faa51 into develop Aug 5, 2026
10 checks passed
@vannt-dev
vannt-dev deleted the feature/docs-and-example-parity branch August 5, 2026 17:18
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant