formstand 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -1,6 +1,46 @@
 # Changelog
 
-## formstand-cli Unreleased
+## 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
+
+- `useIsDirty(form, path?)` and `useIsValid(form, path?)`: an optional
+  typed path scopes the flag to a subtree with the library's usual prefix
+  semantics (`"shipping"` covers `shipping.city`; for validity the path's
+  own key counts, so array-level errors match their array's path).
+  Subscriptions stay boolean-only — the component re-renders when the flag
+  flips, not on every keystroke like `useField(...).dirty`. Omitting the
+  path keeps the whole-form behavior; schema-less `FieldFormApi`-style
+  forms take plain string paths.
+
+## formstand-cli 0.2.2 — 2026-07-09
 
 - Generated array hooks drop the explicit item type
   (`useFieldArray(form, "items")`): formstand ≥ 0.5 infers it from the

package/dist/index.cjs

@@ -985,29 +985,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[""])
-);
-var useIsDirty = (form) => react$1.useStore(
-  form.store,
-  (state) => isFieldDirty(state.values, state.initialValues)
-);
-var useIsValid = (form) => react$1.useStore(form.store, (state) => {
-  for (const k in state.errors) {
-    const errs = state.errors[k];
-    if (errs !== void 0 && errs.length > 0) 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,
@@ -1137,6 +1114,169 @@ 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 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]
+  );
+}
+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;
@@ -1391,110 +1531,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;
@@ -1503,6 +1539,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;