formstand 0.7.0 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,368 @@
 # Changelog
 
+## Unreleased
+
+## 0.9.0 — 2026-07-10
+
+### Fixed
+
+- `validateFields` no longer fabricates a "required" error for a field
+  whose required ancestor is `undefined` (the field-scoped fast path parsed
+  the leaf against undefined where the full-form parse keys the error at the
+  ancestor) — sync and async agreed again. `slotAtPath` now checks the
+  container at each step.
+- `useVariantField` keeps its type guard for **optional/nullable**
+  discriminated unions (a missing `NonNullable` let the nullish member
+  collapse `keyof` to `never` and leak every key, including the
+  discriminant).
+- `devtools` is active only in non-production builds
+  (`NODE_ENV !== "production"`), so opting in during development never
+  streams a shipped form's state to an end user with the extension.
+- `parseDateText` accepts calendar years under 100 (the Date constructor
+  maps 0–99 to 1900–1999; the literal year is forced back on).
+- `DateField` / `dateInputProps` preserve the existing value's time-of-day,
+  so re-picking the same day on a timestamped value is no longer spuriously
+  dirty (and changing the day keeps the time).
+- `parsePath`'s cached segment array is frozen — it is shared across callers
+  now, so external mutation throws instead of corrupting the cache.
+- `useVariantField` docs the write-gating contract (gate variant-field
+  writes on the discriminant, like rendering).
+
+### Added
+
+- `useVariantField(form, unionPath, field)`: typed access to the
+  variant-specific fields of a `z.discriminatedUnion` — the ones
+  `FieldPath` omits because they exist in only some union members (the
+  discriminant stays a common key, bound with plain `useField`). Typed as
+  the field's value across the variants that declare it, widened with
+  `| undefined`; a non-variant field or the discriminant itself is a
+  compile error. `createFormHooks` gains a bound `use{Name}VariantField`.
+- `persistForm(form, { key })`: the autosave recipe as a first-class
+  helper — debounced JSON drafts to any `{ getItem, setItem, removeItem }`
+  storage, draft auto-apply on start (`adopt` rebases clean, `restore`
+  loads dirty, `manual` waits for you), `clear()` that also cancels
+  pending writes, and guarded storage access throughout.
+- Redux DevTools: `createForm(schema, { devtools: "checkout" })` connects
+  the form's store to the extension via zustand's middleware — every write
+  named, inspectable, and time-travelable. Off by default and inert
+  without the extension.
+- Hot-path performance (the 2026-07 review's efficiency findings, no API
+  changes): `parsePath` is memoized (every field subscription re-parsed
+  its path per store notification); `validateFields` parses just the
+  requested subschemas when they're extractable — cross-field rules still
+  force the full parse, because extraction bails on refined levels — so a
+  wizard step stops paying for the whole schema per click; `diff()`/
+  `dirtyFields()` deep-compare each node once instead of once per ancestor
+  level; `focusFirstError` runs its focusability DOM walks only on
+  name-matched candidates instead of every named control in the document.
+- Dates are a first-class field kind: `DateField` (an `<input type="date">`
+  bound to Date-typed paths) joins the shipped components, with
+  `dateInputProps` / `dateToInputText` / `parseDateText` exported for
+  custom markup and UI-kit adapters. Local calendar-date semantics
+  throughout (never `toISOString()` — June 1 stays June 1 west of UTC),
+  the `emptyValue` round-trip on clear, and rollover rejection
+  (`2026-02-31` is invalid, not March 3).
+
+### CI (no package changes)
+
+- Dependabot triage: esbuild pinned to the patched 0.28.1 line via npm
+  overrides in the root and cli (dev-server advisories), scoped to spare
+  vitepress 1.x's nested vite-5 toolchain (esbuild 0.28 can't downlevel to
+  vite 5's browser targets). The remaining vitepress-nested alerts are
+  dismissed as tolerable risk — local docs dev/build only — with the
+  VitePress 2 migration tracked on the roadmap as the real fix.
+- Workflows declare least-privilege GITHUB_TOKEN permissions (CodeQL:
+  actions/missing-workflow-permissions).
+
+### Docs & examples (no package changes)
+
+- The Schema builder gains a **Paste a TypeScript type** mode: paste an
+  interface or type alias and the same in-browser emitters generate the
+  form — no TypeScript compiler in the bundle, a focused ~250-line parser
+  covers the CLI's type-mode subset (string/number/boolean/Date, arrays,
+  nested objects, string-literal unions, optional/nullable) and degrades
+  the rest to a text field with a TODO. Both input modes share one emit
+  path.
+- ROADMAP.md: a living plan for the library and the CLI — the 0.9/cli-0.6
+  cycle (dates as a first-class field kind, hot-path performance,
+  DevTools, CLI config + watch), the next tier, the parking lot, and the
+  review's deferred cleanup items.
+- The theme is one preference across the docs site and the playground:
+  the playground stores its light/dark choice under VitePress's own
+  localStorage key (same origin), so flipping either surface's toggle
+  follows you to the other.
+- The demo body caps at a readable 760px measure; legitimately wide demos
+  (Perf's grid, the Schema builder, the Invoice table) opt out via an
+  explicit WIDE_DEMOS set.
+- The demo card gets a real header: group eyebrow, title, a one-line
+  description of what each demo shows (exhaustive over the tab keys, like
+  the group map), and the View state / View code toggles plus a copy-link
+  button as a right-aligned action cluster — shell chrome separated from
+  demo content by a hairline. The nav groups show demo counts, and the
+  mobile bottom sheet gains its own Close button (the header toggles sit
+  behind it).
+
+- Mobile playground shell: a top app bar (menu / title / controls), the
+  demo list as an off-canvas drawer that closes on pick, and the View
+  state / View code panel as a bottom sheet — all CSS-driven, desktop
+  layout unchanged.
+- Light theme: a toggle in the app bar (and sidebar on desktop), defaulting
+  to the OS preference and persisted per browser. One variable palette in
+  styles.css drives the shell; the MUI bridge and the shadcn scope follow
+  the same html[data-theme] switch. Terminal/code surfaces deliberately
+  stay dark in both themes.
+- The GitHub link in the shell shows the repo's star count (best-effort,
+  cached per session, skipped under tests).
+
+## formstand-cli 0.6.0 — 2026-07-10
+
+- Discriminated unions (`z.discriminatedUnion`) at a field position: the
+  generator emits a discriminant select plus per-variant conditional
+  blocks, binding variant fields through the library's `useVariantField`
+  (single-file) or bound `use{Name}VariantField` (module layout) — fully
+  typed, no casts. All six emit paths (plain/mui/shadcn × single-file/
+  module) typecheck against the real helper. Initial values pick the
+  first variant; the schema round-trips. Nested-in-section unions,
+  unions in array rows, and non-scalar variant fields keep a TODO.
+- Nested-array row extraction (`--layout module`): an array inside a
+  section object, or an array inside an array row, now generates its own
+  Row/Rows component pair with a bound `useFieldArray` on the template
+  path (two numeric holes for arrays-in-rows,
+  `contacts.${parentIndex}.phones.${index}.number`) instead of a TODO
+  comment. One extraction level per array — deeper nesting keeps a TODO.
+- `formstand.config.ts` (also `.mts`/`.js`/`.mjs`, or `--config <file>`):
+  project defaults for `ui`/`layout`/`sections`/`columns`, written with the
+  typed `defineConfig` export. Precedence is flags > config > built-ins,
+  and config typos fail as loudly as flag typos.
+- `--watch`: regenerate whenever the input file changes (requires
+  `--out`; reruns overwrite their own output). Watches the parent
+  directory so editors that save via rename don't kill the watcher.
+- A kind × optional × nullable matrix test pins `emitInitialValues` and
+  `blankNeedsCast` agreement in both directions: the no-cast combos must
+  typecheck with the checked annotation, and every cast combo is proven
+  to genuinely need it.
+- Date fields emit real bindings instead of a text input with a cast and
+  a TODO: `DateField` (plain), `muiDateFieldProps` (MUI `type="date"`
+  TextField with a floated label), `shadcnDateInputProps` (shadcn Input).
+  `DATE_CAST` and the per-backend date TODOs are gone from generated
+  output — forms with dates submit successfully out of the box. Requires
+  formstand ≥ 0.9 for date fields.
+
+## 0.8.0 — 2026-07-10
+
+#### Fixed (2026-07 full-repo review)
+
+- `valuesEqual` compared only the first object's keys, so two objects with
+  equal key counts but different key sets (one holding `undefined`) read as
+  equal — dirty flags, `diff()`, and server-error release could all treat a
+  real change as clean. Key sets must now match (`Object.hasOwn`), and the
+  compare is symmetric.
+- `setAtPath` no longer spreads a `Date`/`Map`/`Set`/class instance at an
+  intermediate path into a plain object (silently destroying it); the write
+  is refused with a console warning, like other unwritable shapes.
+- Path reads return own properties only: `getAtPath(values,
+  "lookup.constructor")` on a `z.record` is `undefined` instead of leaking
+  `Object.prototype` members as field values.
+- A throwing `onInvalid` handler now resolves `submit()` with
+  `{ kind: "error" }` like a throwing `onValid`, instead of rejecting out of
+  a DOM event handler.
+- `restore()` no longer resurrects a snapshotted `isSubmitting` — the flag
+  reflects live submit passes, so a mid-submit snapshot restored later can't
+  disable submit buttons forever (same rule the validation flags already
+  followed).
+- `SelectField` on a nullable field keeps its empty option visible and
+  selectable after a choice, so the field can be cleared back to `null`
+  through the UI (the `emptyValue` round-trip `selectProps` always
+  supported). Non-nullable fields keep the disabled placeholder.
+- `useFieldArray` no longer hands a removed row's id to a row appended in
+  the same update (React treated it as a reorder and resurrected the dead
+  row's DOM state); the same-index fallback still keeps an edited row's id.
+- `useForm` now also warns when the CONTENT of `initialValues` changes after
+  mount (the async-fetch pattern with a module-hoisted schema — previously
+  silently ignored with no warning at all). Inline literals with identical
+  content stay silent.
+- Docs: `field-arrays.md` claimed array ops re-key `isValidating`; they
+  deliberately drop in-flight flags (the pass that set them is stale) — the
+  guide now says so. `components.md` documents the `checkboxProps`
+  unchecked-writes-`false` tradeoff for nullable booleans.
+
+### Docs & examples (no package changes)
+
+- The docs nav gains a "Built on" menu and the footer links to
+  [zod](https://zod.dev) and [zustand](https://zustand.docs.pmnd.rs).
+
+- A "Schema builder" tab: formstand-gen running in the browser. A formstand
+  form describes a schema (fields, sections, arrays, enum options — with
+  duplicate-name and enum-needs-options cross-field validation), its values
+  map straight onto the CLI's IR, and the REAL emitters (imported from
+  cli/src — pure string builders, no Node APIs) regenerate the output files
+  on every keystroke, shown in a file tree with copy-file / copy-all. All
+  the CLI axes are selects: --ui, --layout, --sections, --columns.
+- The Schema builder's "Copy all files" is now "Download .zip" — a
+  dependency-free STORE-only zip writer (~50 lines, in the demo's own
+  source) bundles the generated files under a folder named for the
+  component, exactly the tree `--out` would have written.
+- Every demo has a direct link: hash routes like
+  `examples/#/schema-builder` (kebab-cased tab keys), synced both ways so
+  back/forward and hand-edited URLs work. Hash routing because GitHub Pages
+  is static hosting.
+- The CLI command builder gains Sections and Field columns selects, and the
+  Generated Onboarding tab now showcases `--sections panel --columns 2`
+  (still CI-verified as the CLI's untouched output).
+
+- A "CLI command builder" tab: a formstand form (cross-field superRefine,
+  conditional fields) whose live-updating formstand-gen command line is
+  useFormSelector-derived state, with a copy button.
+- A "Generated" playground group whose Onboarding tab is formstand-gen's
+  untouched `--layout module --ui mui` output for the Onboarding schema —
+  CI regenerates it and fails on drift, so the demo is provably what the
+  current CLI emits (scripts/generate-cli-demos.mjs).
+
+- MUI and shadcn variants of the Onboarding feature module (31 demos now):
+  same shared schema, option lists, and blank draft as the plain module
+  (re-exported, so the three can't drift), each with its own form instance
+  and pre-wired hooks — MUI sections are Accordions with dirty/valid chips,
+  shadcn sections are collapsible with badges. The CLI generates the same
+  architecture from the same schema (`--layout module --ui mui|shadcn`).
+- The sidebar demo list is a tree view (x-tree-view): brass group folders,
+  form-check leaf icons, brass selection.
+
+- The playground gets a real app layout: grouped demo navigation in a
+  sidebar (Core / Patterns / Material UI / shadcn/ui — the group map is
+  exhaustive over the tab keys, so an unassigned demo is a compile error),
+  a sticky scrollable sidebar from tablet width up, and responsive tiers
+  through HD to 4K; on mobile the nav becomes wrapping chips above the
+  content. `/guide/` on the docs site now lands on a guide index instead
+  of a 404.
+- Fixed: clicking a checkbox's label made the field and everything below
+  it jump down for a frame and snap back (Chrome's label-forwarded
+  activation briefly rendered the checkbox as a padded text-input box —
+  reproduced and verified fixed in real Chromium via Playwright). The
+  playground's text-input chrome now excludes checkboxes, which also gain
+  a brass accent-color and a focus-visible ring.
+- View state / View code move to a panel on the demo's right (stacked
+  below on narrow screens), toggled by the same two buttons; multi-file
+  demos (Onboarding) get a file-tree navigator (@mui/x-tree-view with
+  folder/file icons) opening on hooks.ts; the sidebar brand links back to
+  the docs and stays pinned while the demo list scrolls.
+- The Perf demo registers its form like every other tab, so View state
+  works (the shell only mounts the panel while open, so a closed panel
+  costs the benchmark nothing — the copy says to close it while running).
+  The benchmark writes `field0` instead of the mid-grid field, so the
+  change is visible without scrolling.
+
+## formstand-cli 0.5.3 — 2026-07-10
+
+### Fixed
+
+- Emitted string literals escape U+2028/U+2029 (JSON.stringify leaves the
+  JS line separators raw — a syntax error for pre-ES2019 parsers of the
+  GENERATED file, and CodeQL's js/bad-code-sanitization).
+
+## formstand-cli 0.5.2 — 2026-07-10
+
+#### Fixed (2026-07 full-repo review)
+
+- Digit-leading schema keys ("2fa", "2ndOwners") emitted invalid
+  identifiers (`const 2ndOwnersArray`); pascalCase/camelCase results are
+  now underscore-prefixed when they'd start with a digit.
+- Array-row fields named JS reserved words ("new", "delete") emitted
+  reserved-word `const` declarations in module sections; row bindings now
+  use an identifier-safe variant (`new_`).
+- A field named after the module prefix (field "contact" in ContactForm)
+  collided with the bound `useContactField` hook from `hooks.ts` — a
+  duplicate declaration plus self-recursion; component names are now
+  deduped against the hook names too (`ContactField2`).
+- Boolean-only schemas with `--ui mui --layout module` emitted an
+  `adapter.ts` using `ChangeEvent` without importing it.
+- `--name` is validated as an identifier (reserved words rejected) instead
+  of interpolating verbatim into declarations and file names.
+- Cross-drive input/`--out` on Windows produced an unresolvable
+  `"./D:/..."` import specifier; the CLI now fails loudly at generation
+  time.
+- zod's `.nonoptional()` unwrapped transparently, letting an inner
+  `.optional()` win — the field's checked `initialValues` annotation then
+  failed to typecheck; `.nonoptional()` now re-requires the field.
+- A field literally named `__proto__` silently vanished from emitted object
+  literals (prototype-setter semantics); it's now emitted as a computed key.
+- `--sections panel` with `--ui mui` rendered different chrome per
+  `--layout` (single-file used `CardHeader`, module used `Typography` in
+  `CardContent`); both emitters now share the module shape, the grid
+  strings come from one set of helpers instead of six inline copies, and
+  `emitInitialValues`/`blankNeedsCast` read one shared blank-value table so
+  they can't drift.
+
+## formstand-cli 0.5.1 — 2026-07-09
+
+### Fixed
+
+- Generated `initialValues` (and array empty-item constants) only use the
+  `as unknown as` escape hatch when the blank draft genuinely can't
+  typecheck (a required number/date/enum starts `undefined`); every other
+  schema gets a checked type annotation, so typos in edited initial values
+  are compile errors again.
+- `--layout module`: the generated `index.ts` now re-exports `./schema` and
+  `./types` alongside `./hooks`, so consumers can type submit handlers and
+  server code (`ProfileValues`, `profileSchema`) off the module's public
+  API instead of deep-importing its files.
+
+## formstand-cli 0.5.0 — 2026-07-09
+
+### Added
+
+- `--sections flat|panel|collapsible` and `--columns 1|2|3`: minimal visual
+  layout options, working with both `--layout single` and `--layout module`
+  and all three uis. Sections render as flat headings (default, unchanged
+  output), bordered panels, or collapsible sections; fields inside each
+  section flow into 1–3 evenly spaced columns, with nested sections
+  spanning the full row. Each ui speaks its own dialect: inline styles for
+  `plain` (`<details>`/`<summary>` when collapsible), `Card`/`Accordion` +
+  `sx` grids for `mui`, Tailwind classes (`md:grid-cols-2`,
+  `bg-card … shadow-sm`, `<details>`) for `shadcn`. The defaults emit
+  byte-identical output to 0.4.0.
+
+## formstand-cli 0.4.0 — 2026-07-09
+
+### Added
+
+- `--layout module` works with `--ui mui` and `--ui shadcn`: kit modules
+  get a shared `adapter.ts` / `adapter.tsx` exporting the adapter the
+  single-file backends inline, and field/section files import it. The
+  emitted prop builders are now generic over the field's value type
+  (matching the documented example adapters), because the module layout's
+  typed hooks surfaced what the single-file layout's widened hooks masked —
+  `UseFieldReturn<string>` wasn't assignable to a monomorphic builder.
+  Emitted kit modules are typechecked in CI against the MUI stub and both
+  the shadcn stub and the repo's real Radix components.
+
+### Docs & examples (no package changes)
+
+- Brand pass on the docs site and playground: the formstand mark (a form
+  with its green check, resting on a music stand) as logo and favicon, a
+  brass/ink palette replacing the stock VitePress indigo, hand-drawn SVG
+  feature icons replacing the emoji, and restrained motion (hero float,
+  card lift, tab/button transitions, demo fade-in) — all disabled under
+  prefers-reduced-motion. The playground gains a branded header and
+  focus-visible states.
+
+## formstand-cli 0.3.0 — 2026-07-09
+
+### Added
+
+- `--layout module`: emits a feature-module folder instead of one file —
+  `schema.ts` (re-exported in zod mode, generated in type mode), `types.ts`,
+  `hooks.ts` (`createForm` + `createFormHooks`, so the whole module shares
+  one pre-wired hook API), one file per scalar field (props type + field
+  hook + component), one file per top-level object/array section (props
+  type + section hook built on the path-scoped dirty/valid flags +
+  component), the form body, and `index.ts` — the shape of the Onboarding
+  playground demo. `--out` names the folder with all destinations
+  pre-checked; without it the files stream to stdout with `// --- file:`
+  headers. Emitted modules are typechecked in CI against the library
+  source, including hostile-name, colliding-name, and leaf-free schemas.
+  Requires formstand ≥ 0.7; `--ui plain` only for now.
+- `emitModuleForm` / `joinModuleFiles` join the programmatic API.
+
 ## 0.7.0 — 2026-07-09
 
 ### Added

package/README.md

@@ -429,7 +429,8 @@ form.handleSubmit(async (data) => {
 
 See [CONTRIBUTING.md](./CONTRIBUTING.md) — note the repo has three
 independent npm roots (`.`, `examples/`, `cli/`), and the root test suite
-needs `examples/` installed.
+needs `examples/` installed. Where the project is headed lives in
+[ROADMAP.md](./ROADMAP.md).
 
 ## License