formstand 0.6.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,241 @@
 # Changelog
 
+## Unreleased
+
+## 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.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
+
+- `createFormHooks(form, name?)` — every hook pre-wired to one form, the
+  provider-free way to share a module-singleton form. The optional name is
+  baked into the hook names at the type level and at runtime
+  (`createFormHooks(form, "invoice")` → `useInvoiceField`,
+  `useInvoiceFieldArray`, `useInvoiceSelector`, `useInvoiceSelectorShallow`,
+  `useInvoiceError`, `useInvoiceIsDirty`, `useInvoiceIsValid`,
+  `useInvoiceIsSubmitting`, `useInvoiceSubmitCount`), so a typo'd
+  destructure is a compile error; omit the name for unprefixed keys. Every
+  bound hook keeps its unbound signature minus the `form` argument — typed
+  paths, array item inference, path-scoped flags. Documented alongside
+  `createFormContext` with the singleton/SSR caveat; new "Hooks factory"
+  playground tab.
+
+### Docs & examples (no package changes)
+
+- New "Onboarding" playground tab: a 26-field, five-section feature module
+  built on `createFormHooks` — `schema.ts` / `types.ts` / `hooks.ts`, one
+  file per field, one per section (section headers run the path-scoped
+  `useIsDirty`/`useIsValid` flags), with the whole folder shown in the
+  View code panel.
+- The playground's View code panel is syntax-highlighted (Prism, ~25KB —
+  read-only, so no editor bundle).
+
 ## 0.6.0 — 2026-07-09
 
 ### Added

package/dist/index.cjs

@@ -59,7 +59,7 @@ var valuesEqual = (a, b) => {
   if (isPlainObject(a) && isPlainObject(b)) {
     const aKeys = Object.keys(a);
     const bKeys = Object.keys(b);
-    return aKeys.length === bKeys.length && aKeys.every((k) => valuesEqual(a[k], b[k]));
+    return aKeys.length === bKeys.length && aKeys.every((k) => Object.hasOwn(b, k) && valuesEqual(a[k], b[k]));
   }
   return false;
 };
@@ -94,7 +94,7 @@ var readSegment = (obj, segment) => {
   if (Array.isArray(obj)) {
     return typeof segment === "number" ? obj[segment] : void 0;
   }
-  return isPlainRecord(obj) ? obj[String(segment)] : void 0;
+  return isPlainRecord(obj) && Object.hasOwn(obj, String(segment)) ? obj[String(segment)] : void 0;
 };
 var getAtPath = (obj, path) => parsePath(path).reduce(readSegment, obj);
 var slotAtPath = (obj, path) => {
@@ -137,6 +137,12 @@ var writeSegments = (obj, segments, value) => {
     return writeIntoArray(obj, head, rest, value);
   }
   if (isPlainRecord(obj)) {
+    if (!isPlainObject(obj)) {
+      console.warn(
+        `[formstand] cannot write key "${String(head)}" through a non-plain object (Date/Map/Set/class instance); value left unchanged.`
+      );
+      return obj;
+    }
     const key = String(head);
     return { ...obj, [key]: writeSegments(obj[key], rest, value) };
   }
@@ -670,7 +676,11 @@ var createForm = (schema, options) => {
           });
         }
         const merged = stale ? result.errors : store.getState().errors;
-        onInvalid?.(merged);
+        try {
+          onInvalid?.(merged);
+        } catch (error) {
+          return { kind: "error", error };
+        }
         return { kind: "invalid", errors: merged };
       }
       if (!stale) {
@@ -930,9 +940,13 @@ var createForm = (schema, options) => {
         // In-flight state is owned by live passes, never by snapshots: a
         // snapshotted flag has no pass left to clear it (the pass that set
         // it cleared its ORIGINAL entry when it settled), so restoring one
-        // would stick it forever.
+        // would stick it forever. isSubmitting follows the same rule — a
+        // mid-submit snapshot restored later must not disable submit
+        // buttons forever, so it reflects the LIVE submit count instead of
+        // the snapshotted flag (a live pass's finally still resets it).
         isValidating: emptyBools,
-        isValidatingForm: false
+        isValidatingForm: false,
+        isSubmitting: inFlight.count > 0
       };
     })
   });
@@ -960,15 +974,17 @@ var useForm = (schema, options) => {
     formRef.current = createForm(schema, options);
   }
   const form = formRef.current;
+  const mountInitialsRef = react.useRef(options.initialValues);
   const warnedRef = react.useRef(false);
   react.useEffect(() => {
-    if (!warnedRef.current && form.schema !== schema) {
+    const changedInitials = !Object.is(options.initialValues, mountInitialsRef.current) && !valuesEqual(options.initialValues, mountInitialsRef.current);
+    if (!warnedRef.current && (form.schema !== schema || changedInitials)) {
       warnedRef.current = true;
       console.warn(
-        "[formstand] useForm received a different schema reference after the first render; schema and options changes are ignored for the life of the component. If the schema is defined inline this is harmless (but consider hoisting it to module scope). For initial values that arrive later (e.g. from a fetch), call form.adoptValues(values) or form.reset(values) instead."
+        "[formstand] useForm received a different schema or initial values after the first render; schema and options changes are ignored for the life of the component. If the schema is defined inline this is harmless (but consider hoisting it to module scope). For initial values that arrive later (e.g. from a fetch), call form.adoptValues(values) or form.reset(values) instead."
       );
     }
-  }, [form, schema]);
+  }, [form, schema, options.initialValues]);
   return form;
 };
 var createFormContext = () => {
@@ -985,38 +1001,6 @@ var createFormContext = () => {
   };
   return { Provider, useFormContext };
 };
-function useFormSelector(form, selector) {
-  return react$1.useStore(form.store, selector);
-}
-function useFormSelectorShallow(form, selector) {
-  return react$1.useStore(form.store, shallow.useShallow(selector));
-}
-var useFormError = (form) => react$1.useStore(
-  form.store,
-  shallow.useShallow((state) => state.errors[""])
-);
-function useIsDirty(form, path) {
-  return react$1.useStore(
-    form.store,
-    (state) => path === void 0 || path === "" ? isFieldDirty(state.values, state.initialValues) : isFieldDirty(
-      getAtPath(state.values, path),
-      getAtPath(state.initialValues, path)
-    )
-  );
-}
-function useIsValid(form, path) {
-  return react$1.useStore(form.store, (state) => {
-    for (const k in state.errors) {
-      const errs = state.errors[k];
-      if (errs !== void 0 && errs.length > 0 && (path === void 0 || path === "" || isPathOrChild(k, path))) {
-        return false;
-      }
-    }
-    return true;
-  });
-}
-var useIsSubmitting = (form) => react$1.useStore(form.store, (state) => state.isSubmitting);
-var useSubmitCount = (form) => react$1.useStore(form.store, (state) => state.submitCount);
 function useField(form, pathArg, options) {
   const slice = react$1.useStore(
     form.store,
@@ -1146,6 +1130,168 @@ function useField(form, pathArg, options) {
     [slice, emptyValue, setValue, setTouched, setError, clearError, validate, validateAsync2, onBlur]
   );
 }
+var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
+var EMPTY_ITEMS = [];
+var reconcileIds = (prev, nextItems) => {
+  if (prev.items === nextItems) return prev;
+  if (prev.items.length === nextItems.length && prev.items.every((item, i) => Object.is(item, nextItems[i]))) {
+    return prev;
+  }
+  const buckets = prev.items.reduce((acc, item, i) => {
+    const bucket = acc.get(item);
+    if (bucket === void 0) {
+      acc.set(item, [i]);
+    } else {
+      bucket.push(i);
+    }
+    return acc;
+  }, /* @__PURE__ */ new Map());
+  const matchedIds = nextItems.map((item) => {
+    const prevIndex = buckets.get(item)?.shift();
+    return prevIndex === void 0 ? null : prev.ids[prevIndex] ?? null;
+  });
+  const leftoverAt = new Map(
+    [...buckets.values()].flat().flatMap((i) => {
+      const id = prev.ids[i];
+      return id === void 0 ? [] : [[i, id]];
+    })
+  );
+  const reused = matchedIds.map((id, i) => id ?? leftoverAt.get(i) ?? null);
+  const mintCounts = reused.reduce((acc, id) => {
+    const count = acc[acc.length - 1] ?? 0;
+    return [...acc, id === null ? count + 1 : count];
+  }, []);
+  const minted = mintCounts[mintCounts.length - 1] ?? 0;
+  const ids = reused.map(
+    (id, i) => id ?? `__zfa_${prev.counter + (mintCounts[i] ?? 0)}`
+  );
+  return { items: nextItems, ids, counter: prev.counter + minted };
+};
+function useFieldArray(form, pathArg) {
+  const path = react$1.useStore(
+    form.store,
+    (state) => typeof pathArg === "function" ? pathArg(state) : pathArg
+  );
+  const slice = react$1.useStore(
+    form.store,
+    shallow.useShallow((state) => {
+      const value = getAtPath(state.values, path);
+      return {
+        items: Array.isArray(value) ? value : EMPTY_ITEMS,
+        error: state.errors[path]
+      };
+    })
+  );
+  const items = slice.items;
+  const error = slice.error;
+  const [idEntry, setIdEntry] = react.useState({ form, path, state: EMPTY_ID_STATE });
+  const base = idEntry.form === form && idEntry.path === path ? idEntry.state : { ...EMPTY_ID_STATE, counter: idEntry.state.counter };
+  const nextIdState = reconcileIds(base, items);
+  if (idEntry.form !== form || idEntry.path !== path || idEntry.state !== nextIdState) {
+    setIdEntry({ form, path, state: nextIdState });
+  }
+  const ids = nextIdState.ids;
+  const push = react.useCallback(
+    (item) => form.arrayPush(path, item),
+    [form, path]
+  );
+  const remove = react.useCallback(
+    (index) => form.arrayRemove(path, index),
+    [form, path]
+  );
+  const insert = react.useCallback(
+    (index, item) => form.arrayInsert(path, index, item),
+    [form, path]
+  );
+  const move = react.useCallback(
+    (from, to) => form.arrayMove(path, from, to),
+    [form, path]
+  );
+  const swap = react.useCallback(
+    (a, b) => form.arraySwap(path, a, b),
+    [form, path]
+  );
+  const fields = react.useMemo(
+    () => items.map((value, index) => ({
+      id: ids[index] ?? `__zfa_fallback_${index}`,
+      value
+    })),
+    [items, ids]
+  );
+  return react.useMemo(
+    () => ({
+      fields,
+      items,
+      length: items.length,
+      error,
+      push,
+      remove,
+      insert,
+      move,
+      swap
+    }),
+    [fields, items, error, push, remove, insert, move, swap]
+  );
+}
+var useFormError = (form) => react$1.useStore(
+  form.store,
+  shallow.useShallow((state) => state.errors[""])
+);
+function useIsDirty(form, path) {
+  return react$1.useStore(
+    form.store,
+    (state) => path === void 0 || path === "" ? isFieldDirty(state.values, state.initialValues) : isFieldDirty(
+      getAtPath(state.values, path),
+      getAtPath(state.initialValues, path)
+    )
+  );
+}
+function useIsValid(form, path) {
+  return react$1.useStore(form.store, (state) => {
+    for (const k in state.errors) {
+      const errs = state.errors[k];
+      if (errs !== void 0 && errs.length > 0 && (path === void 0 || path === "" || isPathOrChild(k, path))) {
+        return false;
+      }
+    }
+    return true;
+  });
+}
+var useIsSubmitting = (form) => react$1.useStore(form.store, (state) => state.isSubmitting);
+var useSubmitCount = (form) => react$1.useStore(form.store, (state) => state.submitCount);
+function useFormSelector(form, selector) {
+  return react$1.useStore(form.store, selector);
+}
+function useFormSelectorShallow(form, selector) {
+  return react$1.useStore(form.store, shallow.useShallow(selector));
+}
+
+// src/react/createFormHooks.ts
+var capitalize = (name) => name.length === 0 ? name : name.charAt(0).toUpperCase() + name.slice(1);
+var createFormHooks = (form, name) => {
+  const structural = form;
+  const useBoundField = (path, options) => useField(structural, path, options);
+  const useBoundFieldArray = (path) => useFieldArray(structural, path);
+  const useBoundSelector = (selector) => useFormSelector(structural, selector);
+  const useBoundSelectorShallow = (selector) => useFormSelectorShallow(structural, selector);
+  const useBoundError = () => useFormError(structural);
+  const useBoundIsDirty = (path) => useIsDirty(structural, path);
+  const useBoundIsValid = (path) => useIsValid(structural, path);
+  const useBoundIsSubmitting = () => useIsSubmitting(structural);
+  const useBoundSubmitCount = () => useSubmitCount(structural);
+  const prefix = capitalize(name ?? "");
+  return {
+    [`use${prefix}Field`]: useBoundField,
+    [`use${prefix}FieldArray`]: useBoundFieldArray,
+    [`use${prefix}Selector`]: useBoundSelector,
+    [`use${prefix}SelectorShallow`]: useBoundSelectorShallow,
+    [`use${prefix}Error`]: useBoundError,
+    [`use${prefix}IsDirty`]: useBoundIsDirty,
+    [`use${prefix}IsValid`]: useBoundIsValid,
+    [`use${prefix}IsSubmitting`]: useBoundIsSubmitting,
+    [`use${prefix}SubmitCount`]: useBoundSubmitCount
+  };
+};
 
 // src/react/inputProps.ts
 var ariaInvalid = (field) => field.error !== void 0 && field.error.length > 0 ? true : void 0;
@@ -1336,7 +1482,8 @@ var SelectField = ({
   const id = react.useId();
   const errorId = `${id}-error`;
   const field = useField(form, path);
-  const showEmptyOption = field.value === void 0 || field.value === null || placeholder !== void 0;
+  const clearable = field.emptyValue === null;
+  const showEmptyOption = clearable || field.value === void 0 || field.value === null || placeholder !== void 0;
   return /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "zf-field", children: [
     label !== void 0 ? /* @__PURE__ */ jsxRuntime.jsx("label", { htmlFor: id, className: "zf-label", children: label }) : null,
     /* @__PURE__ */ jsxRuntime.jsxs(
@@ -1347,7 +1494,7 @@ var SelectField = ({
         ...selectProps(field),
         "aria-describedby": hasError(field.error) ? errorId : void 0,
         children: [
-          showEmptyOption ? /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: true, children: placeholder ?? "" }) : null,
+          showEmptyOption ? /* @__PURE__ */ jsxRuntime.jsx("option", { value: "", disabled: !clearable, children: placeholder ?? "" }) : null,
           options.map((opt, index) => (
             // Index-qualified: option lists may legitimately repeat a value
             // (e.g. differently-labelled aliases), and bare value keys would
@@ -1400,110 +1547,6 @@ var focusField = (path, root) => {
   const controls = focusableControls(root ?? document);
   return path === "" ? (root !== void 0 || document.querySelectorAll("form").length <= 1) && focusFirstOf(controls) : focusFirstOf(controls.filter((el) => nameMatchesAny(el, [path])));
 };
-var EMPTY_ID_STATE = { items: [], ids: [], counter: 0 };
-var EMPTY_ITEMS = [];
-var reconcileIds = (prev, nextItems) => {
-  if (prev.items === nextItems) return prev;
-  if (prev.items.length === nextItems.length && prev.items.every((item, i) => Object.is(item, nextItems[i]))) {
-    return prev;
-  }
-  const buckets = prev.items.reduce((acc, item, i) => {
-    const bucket = acc.get(item);
-    if (bucket === void 0) {
-      acc.set(item, [i]);
-    } else {
-      bucket.push(i);
-    }
-    return acc;
-  }, /* @__PURE__ */ new Map());
-  const matchedIds = nextItems.map((item) => {
-    const prevIndex = buckets.get(item)?.shift();
-    return prevIndex === void 0 ? null : prev.ids[prevIndex] ?? null;
-  });
-  const leftover = [...buckets.values()].flat().sort((a, b) => a - b).map((i) => prev.ids[i]).filter((id) => id !== void 0);
-  const ordinals = matchedIds.reduce((acc, id) => {
-    const count = acc.length === 0 ? 0 : acc[acc.length - 1] ?? 0;
-    acc.push(id === null ? count + 1 : count);
-    return acc;
-  }, []);
-  const unmatched = ordinals.length === 0 ? 0 : ordinals[ordinals.length - 1] ?? 0;
-  const ids = matchedIds.map((id, i) => {
-    if (id !== null) return id;
-    const ordinal = ordinals[i] ?? 0;
-    return leftover[ordinal - 1] ?? `__zfa_${prev.counter + (ordinal - leftover.length)}`;
-  });
-  return {
-    items: nextItems,
-    ids,
-    counter: prev.counter + Math.max(0, unmatched - leftover.length)
-  };
-};
-function useFieldArray(form, pathArg) {
-  const path = react$1.useStore(
-    form.store,
-    (state) => typeof pathArg === "function" ? pathArg(state) : pathArg
-  );
-  const slice = react$1.useStore(
-    form.store,
-    shallow.useShallow((state) => {
-      const value = getAtPath(state.values, path);
-      return {
-        items: Array.isArray(value) ? value : EMPTY_ITEMS,
-        error: state.errors[path]
-      };
-    })
-  );
-  const items = slice.items;
-  const error = slice.error;
-  const [idEntry, setIdEntry] = react.useState({ form, path, state: EMPTY_ID_STATE });
-  const base = idEntry.form === form && idEntry.path === path ? idEntry.state : { ...EMPTY_ID_STATE, counter: idEntry.state.counter };
-  const nextIdState = reconcileIds(base, items);
-  if (idEntry.form !== form || idEntry.path !== path || idEntry.state !== nextIdState) {
-    setIdEntry({ form, path, state: nextIdState });
-  }
-  const ids = nextIdState.ids;
-  const push = react.useCallback(
-    (item) => form.arrayPush(path, item),
-    [form, path]
-  );
-  const remove = react.useCallback(
-    (index) => form.arrayRemove(path, index),
-    [form, path]
-  );
-  const insert = react.useCallback(
-    (index, item) => form.arrayInsert(path, index, item),
-    [form, path]
-  );
-  const move = react.useCallback(
-    (from, to) => form.arrayMove(path, from, to),
-    [form, path]
-  );
-  const swap = react.useCallback(
-    (a, b) => form.arraySwap(path, a, b),
-    [form, path]
-  );
-  const fields = react.useMemo(
-    () => items.map((value, index) => ({
-      id: ids[index] ?? `__zfa_fallback_${index}`,
-      value
-    })),
-    [items, ids]
-  );
-  return react.useMemo(
-    () => ({
-      fields,
-      items,
-      length: items.length,
-      error,
-      push,
-      remove,
-      insert,
-      move,
-      swap
-    }),
-    [fields, items, error, push, remove, insert, move, swap]
-  );
-}
 
 exports.CheckboxField = CheckboxField;
 exports.NumberField = NumberField;
@@ -1512,6 +1555,7 @@ exports.TextField = TextField;
 exports.checkboxProps = checkboxProps;
 exports.createForm = createForm;
 exports.createFormContext = createFormContext;
+exports.createFormHooks = createFormHooks;
 exports.emptyValueForSchema = emptyValueForSchema;
 exports.flattenIssues = flattenIssues;
 exports.focusField = focusField;