@wow-two-beta/ui-vue 0.0.2

package/dist/forms-engine/tanstack/index.d.ts

@@ -0,0 +1,8 @@
+import { useAppForm } from './UseAppForm';
+export { useAppForm };
+export type { TanstackFormEngine } from './UseAppForm';
+export type { TanstackFormOverlay, TanstackOverlayState } from './TanstackFormOverlay';
+/** The tanstack adapter as a `FormEngine` — compile-time proof it satisfies the module contract. */
+export declare const tanstackFormEngine: {
+    useAppForm: typeof useAppForm;
+};

package/dist/forms-engine/tanstack/index.js

@@ -0,0 +1,407 @@
+import { shallowRef, onMounted, toValue, onScopeDispose } from "vue";
+import { useForm, revalidateLogic } from "@tanstack/vue-form";
+import { f as fieldIssues } from "../../chunks/FieldErrors-2zjhia4U.js";
+import { d as deepEqual } from "../../chunks/DeepEqual-7lBKnkNS.js";
+import { n as remapPathSet, o as remapPathMap, b as createFormStateView, a as createFieldComponent, l as runStandardSchema, d as createOptionsMessageResolver, g as getPath, c as createFieldApi, e as createUseFormState, r as resolveSubmitFailure, i as hasPath, f as defaultMapFieldPath } from "../../chunks/SubmitErrors-K8nmmj0P.js";
+const EMPTY_MAP = Object.freeze({});
+function normalizeErrorMap(errors) {
+  const normalized = {};
+  for (const [path, messages] of Object.entries(errors)) normalized[path] = [...messages];
+  return normalized;
+}
+function createTanstackFormOverlay(initialBaseline) {
+  const store = shallowRef({
+    baseline: initialBaseline,
+    serverErrors: EMPTY_MAP,
+    touched: /* @__PURE__ */ new Set(),
+    submitCount: 0,
+    isSubmitting: false,
+    submitError: null,
+    isSubmitSuccessful: null
+  });
+  function commit(next) {
+    store.value = next;
+  }
+  function patch(partial) {
+    commit({ ...store.value, ...partial });
+  }
+  return {
+    state: store,
+    getState: () => store.value,
+    markBlurred: (path) => {
+      if (store.value.touched.has(path)) return;
+      const touched = new Set(store.value.touched);
+      touched.add(path);
+      patch({ touched });
+    },
+    clearServerErrorsAt: (path) => {
+      if (!Object.prototype.hasOwnProperty.call(store.value.serverErrors, path)) return;
+      patch({
+        serverErrors: Object.fromEntries(
+          Object.entries(store.value.serverErrors).filter(([key]) => key !== path)
+        )
+      });
+    },
+    remapForArrayOperation: (arrayPath, operation) => {
+      patch({
+        serverErrors: remapPathMap(store.value.serverErrors, arrayPath, operation),
+        touched: remapPathSet(store.value.touched, arrayPath, operation)
+      });
+    },
+    beginSubmitAttempt: () => {
+      patch({
+        submitCount: store.value.submitCount + 1,
+        serverErrors: EMPTY_MAP,
+        submitError: null,
+        isSubmitSuccessful: null
+      });
+    },
+    touchAll: () => {
+      if (store.value.submitCount === 0) patch({ submitCount: 1 });
+    },
+    setSubmitting: (isSubmitting) => {
+      if (store.value.isSubmitting !== isSubmitting) patch({ isSubmitting });
+    },
+    setSubmitSuccessful: (value) => {
+      if (store.value.isSubmitSuccessful !== value) patch({ isSubmitSuccessful: value });
+    },
+    applySubmitFailure: (resolution) => {
+      patch({
+        serverErrors: normalizeErrorMap(resolution.fieldErrors),
+        submitError: resolution.submitError
+      });
+    },
+    replaceServerErrors: (errors) => {
+      patch({ serverErrors: normalizeErrorMap(errors) });
+    },
+    clearSubmitError: () => {
+      if (store.value.submitError !== null) patch({ submitError: null });
+    },
+    reset: (baseline) => {
+      commit({
+        baseline,
+        serverErrors: EMPTY_MAP,
+        touched: /* @__PURE__ */ new Set(),
+        submitCount: 0,
+        isSubmitting: store.value.isSubmitting,
+        // an in-flight submit still owns its flag (its finally clears it)
+        submitError: null,
+        isSubmitSuccessful: null
+      });
+    }
+  };
+}
+const EMPTY_MESSAGES = Object.freeze([]);
+function toEngineValidationError(errors) {
+  const paths = Object.keys(errors);
+  if (paths.length === 0) return void 0;
+  const fields = {};
+  let form;
+  for (const path of paths) {
+    if (path === "") form = errors[path];
+    else fields[path] = errors[path] ?? [];
+  }
+  return form ? { form, fields } : { fields };
+}
+function toMessages(errors) {
+  if (!errors || errors.length === 0) return EMPTY_MESSAGES;
+  const messages = [];
+  const visit = (error) => {
+    if (error === null || error === void 0) return;
+    if (typeof error === "string") {
+      messages.push(error);
+      return;
+    }
+    if (Array.isArray(error)) {
+      for (const entry of error) visit(entry);
+      return;
+    }
+    if (typeof error === "object" && typeof error.message === "string") {
+      messages.push(error.message);
+    }
+  };
+  for (const error of errors) visit(error);
+  return messages.length > 0 ? messages : EMPTY_MESSAGES;
+}
+function sameMessages(a, b) {
+  return a === b || a.length === b.length && a.every((message, index) => message === b[index]);
+}
+function fieldStatesEqual(a, b) {
+  return Object.is(a.value, b.value) && a.isDirty === b.isDirty && a.isTouched === b.isTouched && sameMessages(a.errors, b.errors);
+}
+function bridgeStore(engine) {
+  const snapshot = shallowRef(engine.store.state);
+  const subscription = engine.store.subscribe((next) => {
+    snapshot.value = next;
+  });
+  onScopeDispose(() => subscription.unsubscribe(), true);
+  return snapshot;
+}
+function createCombinedReader(snapshot, overlay) {
+  let generation = null;
+  let formState = null;
+  let fieldCache = /* @__PURE__ */ new Map();
+  let previousFieldCache = /* @__PURE__ */ new Map();
+  function currentGeneration() {
+    const tan = snapshot.value;
+    const ov = overlay.state.value;
+    if (generation && generation.tan === tan && generation.ov === ov) return generation;
+    generation = { tan, ov };
+    formState = null;
+    previousFieldCache = fieldCache;
+    fieldCache = /* @__PURE__ */ new Map();
+    return generation;
+  }
+  return {
+    getFormState: () => {
+      const { tan, ov } = currentGeneration();
+      formState ??= {
+        values: tan.values,
+        isDirty: !deepEqual(tan.values, ov.baseline),
+        // Client validity is engine-native; the server-error overlay holds it false too.
+        isValid: tan.isValid && Object.keys(ov.serverErrors).length === 0,
+        isSubmitting: ov.isSubmitting,
+        // Whole-schema validation is a FORM-level validator — TanStack's derived
+        // `isValidating` counts field-level validators only, so merge both flags.
+        isValidating: tan.isFormValidating || tan.isValidating,
+        submitError: ov.submitError,
+        isSubmitSuccessful: ov.isSubmitSuccessful
+      };
+      return formState;
+    },
+    getFieldState: (path) => {
+      const { tan, ov } = currentGeneration();
+      const cached = fieldCache.get(path);
+      if (cached) return cached;
+      const value = getPath(tan.values, path);
+      const clientMessages = toMessages(tan.fieldMeta[path]?.errors);
+      const serverMessages = ov.serverErrors[path] ?? EMPTY_MESSAGES;
+      const computed = {
+        value,
+        // Client + server messages merged, client first (contract JSDoc).
+        errors: serverMessages.length === 0 ? clientMessages : clientMessages.length === 0 ? serverMessages : [...clientMessages, ...serverMessages],
+        isDirty: !deepEqual(value, getPath(ov.baseline, path)),
+        // A submit attempt counts as touching everything — error-display gating works post-attempt.
+        isTouched: ov.touched.has(path) || ov.submitCount > 0
+      };
+      const previous = previousFieldCache.get(path);
+      const stable = previous && fieldStatesEqual(previous, computed) ? previous : computed;
+      fieldCache.set(path, stable);
+      return stable;
+    }
+  };
+}
+function createAdapterPrelude(getOptions) {
+  const initialOptions = getOptions();
+  const overlay = createTanstackFormOverlay(initialOptions.defaultValues);
+  const messageResolver = createOptionsMessageResolver(getOptions);
+  const tanstackOptions = {
+    defaultValues: initialOptions.defaultValues,
+    onSubmit: async ({ value }) => {
+      overlay.setSubmitting(true);
+      try {
+        await getOptions().onSubmit(value);
+        overlay.setSubmitSuccessful(true);
+      } finally {
+        overlay.setSubmitting(false);
+      }
+    }
+  };
+  if (initialOptions.schema) {
+    const validateWithSchema = async ({ value }) => {
+      const schema = getOptions().schema;
+      if (!schema) return void 0;
+      return toEngineValidationError(await runStandardSchema(schema, value, messageResolver()));
+    };
+    tanstackOptions.validators = { onDynamicAsync: validateWithSchema };
+    tanstackOptions.validationLogic = revalidateLogic({
+      // `validateOn` maps 1:1 onto the pre-submission mode; after the first attempt
+      // every mode re-validates on change so errors clear as the user fixes them.
+      mode: initialOptions.validateOn ?? "submit",
+      modeAfterSubmission: "change"
+    });
+  }
+  return { getOptions, overlay, tanstackOptions, messageResolver };
+}
+function buildAppForm(engine, prelude) {
+  const { getOptions, overlay, tanstackOptions, messageResolver } = prelude;
+  const reader = createCombinedReader(bridgeStore(engine), overlay);
+  function applySubmitFailure(error) {
+    const options = getOptions();
+    const values = engine.store.state.values;
+    overlay.applySubmitFailure(
+      resolveSubmitFailure(
+        error,
+        options.mapSubmitError ?? fieldIssues,
+        options.mapFieldPath ?? defaultMapFieldPath,
+        (path) => hasPath(values, path),
+        options.fallbackErrorMessage,
+        messageResolver()
+      )
+    );
+  }
+  async function runOnSubmit() {
+    overlay.setSubmitting(true);
+    try {
+      await getOptions().onSubmit(engine.store.state.values);
+      overlay.setSubmitSuccessful(true);
+      return true;
+    } catch (error) {
+      applySubmitFailure(error);
+      overlay.setSubmitSuccessful(false);
+      return false;
+    } finally {
+      overlay.setSubmitting(false);
+    }
+  }
+  async function performSubmit() {
+    if (getOptions().isDisabled) return false;
+    overlay.beginSubmitAttempt();
+    if (getOptions().submitInvalid) {
+      await engine.validate("submit");
+      return runOnSubmit();
+    }
+    let succeeded = false;
+    try {
+      await engine.handleSubmit();
+      succeeded = overlay.getState().isSubmitSuccessful === true;
+    } catch (error) {
+      applySubmitFailure(error);
+      succeeded = false;
+    }
+    overlay.setSubmitSuccessful(succeeded);
+    return succeeded;
+  }
+  let inFlight = null;
+  async function guardedSubmit() {
+    if (inFlight) return inFlight;
+    const run = performSubmit();
+    inFlight = run;
+    try {
+      return await run;
+    } finally {
+      inFlight = null;
+    }
+  }
+  async function validate() {
+    overlay.touchAll();
+    await engine.validate("submit");
+    return engine.store.state.isValid;
+  }
+  let autoSubmitTimer = null;
+  const clearAutoSubmitTimer = () => {
+    if (autoSubmitTimer !== null) {
+      clearTimeout(autoSubmitTimer);
+      autoSubmitTimer = null;
+    }
+  };
+  const scheduleAutoSubmit = () => {
+    if ((getOptions().submitOn ?? "manual") !== "change") return;
+    clearAutoSubmitTimer();
+    const delay = getOptions().submitDebounceMs ?? 0;
+    autoSubmitTimer = setTimeout(() => {
+      autoSubmitTimer = null;
+      void guardedSubmit();
+    }, delay);
+  };
+  const autoSubmitOnBlur = () => {
+    if ((getOptions().submitOn ?? "manual") === "blur") void guardedSubmit();
+  };
+  const fieldApis = /* @__PURE__ */ new Map();
+  const fieldOps = {
+    getState: (path) => reader.getFieldState(path),
+    setValue: (path, value) => {
+      overlay.clearServerErrorsAt(path);
+      engine.setFieldValue(path, value);
+      scheduleAutoSubmit();
+    },
+    blur: (path) => {
+      overlay.markBlurred(path);
+      void engine.validateField(path, "blur");
+      autoSubmitOnBlur();
+    }
+  };
+  const getFieldApi = (path) => {
+    const existing = fieldApis.get(path);
+    if (existing) return existing;
+    const api = createFieldApi(path, fieldOps);
+    fieldApis.set(path, api);
+    return api;
+  };
+  const arrayOperation = (path, operation) => {
+    const field = path;
+    switch (operation.kind) {
+      case "push":
+        engine.pushFieldValue(field, operation.value);
+        break;
+      case "insert":
+        void engine.insertFieldValue(field, operation.index, operation.value);
+        break;
+      case "remove":
+        void engine.removeFieldValue(field, operation.index);
+        break;
+      case "swap":
+        engine.swapFieldValues(field, operation.indexA, operation.indexB);
+        break;
+      case "move":
+        engine.moveFieldValues(field, operation.fromIndex, operation.toIndex);
+        break;
+    }
+    overlay.remapForArrayOperation(path, operation);
+    scheduleAutoSubmit();
+  };
+  const state = createFormStateView(reader.getFormState);
+  const form = {
+    Field: createFieldComponent(getFieldApi, () => getOptions().isDisabled ?? false),
+    state,
+    // The same computed `state.values` reads — `form.values` is a shorthand, never a second source.
+    get values() {
+      return state.values;
+    },
+    useFormState: createUseFormState(reader.getFormState),
+    handleSubmit: async (event) => {
+      event?.preventDefault();
+      return guardedSubmit();
+    },
+    validate,
+    setValue: (path, value) => {
+      overlay.clearServerErrorsAt(path);
+      engine.setFieldValue(path, value);
+      scheduleAutoSubmit();
+    },
+    array: (path) => ({
+      push: (value) => arrayOperation(path, { kind: "push", value }),
+      insert: (index, value) => arrayOperation(path, { kind: "insert", index, value }),
+      remove: (index) => arrayOperation(path, { kind: "remove", index }),
+      swap: (indexA, indexB) => arrayOperation(path, { kind: "swap", indexA, indexB }),
+      move: (fromIndex, toIndex) => arrayOperation(path, { kind: "move", fromIndex, toIndex })
+    }),
+    reset: (next) => {
+      const values = next ?? getOptions().defaultValues;
+      tanstackOptions.defaultValues = values;
+      overlay.reset(values);
+      engine.reset(values);
+      clearAutoSubmitTimer();
+    },
+    setFieldErrors: (errors) => overlay.replaceServerErrors(errors),
+    clearSubmitError: () => overlay.clearSubmitError(),
+    engine
+  };
+  return { form, dispose: clearAutoSubmitTimer };
+}
+function useAppForm(options) {
+  const prelude = createAdapterPrelude(() => toValue(options));
+  const engine = useForm(prelude.tanstackOptions);
+  const built = buildAppForm(engine, prelude);
+  onMounted(() => {
+    if (toValue(options).validateOnMount) void engine.validate("submit");
+  });
+  onScopeDispose(built.dispose, true);
+  return built.form;
+}
+const tanstackFormEngine = { useAppForm };
+export {
+  tanstackFormEngine,
+  useAppForm
+};
+//# sourceMappingURL=index.js.map

package/dist/forms-engine/tanstack/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/forms-engine/tanstack/TanstackFormOverlay.ts","../../../src/forms-engine/tanstack/UseAppForm.ts","../../../src/forms-engine/tanstack/index.ts"],"sourcesContent":["import { shallowRef, type ShallowRef } from 'vue';\n\nimport type { ApiError } from '../../foundation/http';\n\nimport { remapPathMap, remapPathSet, type ArrayOperation } from '../Paths';\nimport type { SubmitFailureResolution } from '../SubmitErrors';\n\n/*\n * The adapter-owned overlay store — the contract state TanStack Form does not model\n * (docs/analysis/forms-engine.md §4/§5). TanStack has no client/server error merge, its\n * touched marks on change (contract: blur OR submit attempt), its dirty is sticky\n * per-field (contract: deep-compared against a resettable baseline), and its array\n * reindexing of field meta differs from the contract's remap rules. All four live here,\n * outside TanStack state, exactly like the house engine keeps them:\n *   - `serverErrors` — the server-error overlay, cleared per-path on the next change,\n *     replaced wholesale by `setFieldErrors`, remapped through array ops.\n *   - `baseline` — the dirty baseline `reset(next)` re-seeds.\n *   - `touched` — blur marks; `submitCount > 0` touches everything.\n *   - `isSubmitting` / `submitError` — the contract submit pipeline flags: `isSubmitting`\n *     wraps only the app's `onSubmit` call (not TanStack's validation window), and\n *     `submitError` holds the failure remainder no field could represent.\n *\n * The React version was a hand-rolled listener store read through `useSyncExternalStore`; here\n * it is one immutable object in a `shallowRef`, so a read of `state.value` is the subscription.\n * TanStack's own store stays a `@tanstack/store` `Store` — the adapter bridges it separately.\n */\n\ntype ErrorMap = Readonly<Record<string, readonly string[]>>;\n\nconst EMPTY_MAP: ErrorMap = Object.freeze({});\n\n/** The adapter-owned slice merged with TanStack state into the contract's form/field state. */\nexport interface TanstackOverlayState<TValues extends object> {\n  /** The dirty baseline — `reset(next)` re-seeds it. */\n  readonly baseline: TValues;\n  /** The server-error overlay, keyed by form path (`rules[0].destination`). */\n  readonly serverErrors: ErrorMap;\n  readonly touched: ReadonlySet<string>;\n  readonly submitCount: number;\n  readonly isSubmitting: boolean;\n  readonly submitError: ApiError | null;\n  /** The last completed submit's verdict — `null` until the first attempt completes and after `reset()`. */\n  readonly isSubmitSuccessful: boolean | null;\n}\n\n/** The overlay store the tanstack adapter combines with the TanStack form store. */\nexport interface TanstackFormOverlay<TValues extends object> {\n  /** The reactive seam — reading `state.value` subscribes, the way `subscribe` + `useSyncExternalStore` did in React. */\n  readonly state: Readonly<ShallowRef<TanstackOverlayState<TValues>>>;\n  readonly getState: () => TanstackOverlayState<TValues>;\n  /** Marks a field touched (wired onto the control's blur). */\n  readonly markBlurred: (path: string) => void;\n  /** Server messages clear on the next change to the field (contract JSDoc). */\n  readonly clearServerErrorsAt: (path: string) => void;\n  /** Row-scoped server errors + touched marks follow their rows through array ops. */\n  readonly remapForArrayOperation: (arrayPath: string, operation: ArrayOperation) => void;\n  /** A new attempt clears the previous server errors + submitError, re-arms the verdict, and counts as touching everything. */\n  readonly beginSubmitAttempt: () => void;\n  /** Marks every field touched (`submitCount > 0`) WITHOUT clearing errors or the verdict — `validate()`'s display gate. */\n  readonly touchAll: () => void;\n  /** Brackets the app's `onSubmit` call — the contract's `isSubmitting` window. */\n  readonly setSubmitting: (isSubmitting: boolean) => void;\n  /** Settles the last completed submit's verdict (`handleSubmit` mirrors it into `isSubmitSuccessful`). */\n  readonly setSubmitSuccessful: (value: boolean | null) => void;\n  /** Lands a resolved submit failure: matches as the server overlay, remainder as `submitError`. */\n  readonly applySubmitFailure: (resolution: SubmitFailureResolution) => void;\n  /** Replaces the server-error overlay (`setFieldErrors`). */\n  readonly replaceServerErrors: (errors: Record<string, string[]>) => void;\n  /** Clears the form-level `submitError` without touching field errors (`clearSubmitError`). */\n  readonly clearSubmitError: () => void;\n  /** Clears everything and re-seeds the dirty baseline. */\n  readonly reset: (baseline: TValues) => void;\n}\n\nfunction normalizeErrorMap(errors: Record<string, string[]>): ErrorMap {\n  const normalized: Record<string, readonly string[]> = {};\n  for (const [path, messages] of Object.entries(errors)) normalized[path] = [...messages];\n  return normalized;\n}\n\n/** Creates the adapter-owned overlay store seeded with the initial dirty baseline. */\nexport function createTanstackFormOverlay<TValues extends object>(\n  initialBaseline: TValues,\n): TanstackFormOverlay<TValues> {\n  const store = shallowRef<TanstackOverlayState<TValues>>({\n    baseline: initialBaseline,\n    serverErrors: EMPTY_MAP,\n    touched: new Set<string>(),\n    submitCount: 0,\n    isSubmitting: false,\n    submitError: null,\n    isSubmitSuccessful: null,\n  });\n\n  function commit(next: TanstackOverlayState<TValues>): void {\n    store.value = next;\n  }\n\n  function patch(partial: Partial<TanstackOverlayState<TValues>>): void {\n    commit({ ...store.value, ...partial });\n  }\n\n  return {\n    state: store,\n    getState: () => store.value,\n    markBlurred: (path) => {\n      if (store.value.touched.has(path)) return;\n      const touched = new Set(store.value.touched);\n      touched.add(path);\n      patch({ touched });\n    },\n    clearServerErrorsAt: (path) => {\n      if (!Object.prototype.hasOwnProperty.call(store.value.serverErrors, path)) return;\n      patch({\n        serverErrors: Object.fromEntries(\n          Object.entries(store.value.serverErrors).filter(([key]) => key !== path),\n        ),\n      });\n    },\n    remapForArrayOperation: (arrayPath, operation) => {\n      patch({\n        serverErrors: remapPathMap(store.value.serverErrors, arrayPath, operation),\n        touched: remapPathSet(store.value.touched, arrayPath, operation),\n      });\n    },\n    beginSubmitAttempt: () => {\n      patch({\n        submitCount: store.value.submitCount + 1,\n        serverErrors: EMPTY_MAP,\n        submitError: null,\n        isSubmitSuccessful: null,\n      });\n    },\n    touchAll: () => {\n      if (store.value.submitCount === 0) patch({ submitCount: 1 });\n    },\n    setSubmitting: (isSubmitting) => {\n      if (store.value.isSubmitting !== isSubmitting) patch({ isSubmitting });\n    },\n    setSubmitSuccessful: (value) => {\n      if (store.value.isSubmitSuccessful !== value) patch({ isSubmitSuccessful: value });\n    },\n    applySubmitFailure: (resolution) => {\n      patch({\n        serverErrors: normalizeErrorMap(resolution.fieldErrors),\n        submitError: resolution.submitError,\n      });\n    },\n    replaceServerErrors: (errors) => {\n      patch({ serverErrors: normalizeErrorMap(errors) });\n    },\n    clearSubmitError: () => {\n      if (store.value.submitError !== null) patch({ submitError: null });\n    },\n    reset: (baseline) => {\n      commit({\n        baseline,\n        serverErrors: EMPTY_MAP,\n        touched: new Set<string>(),\n        submitCount: 0,\n        isSubmitting: store.value.isSubmitting, // an in-flight submit still owns its flag (its finally clears it)\n        submitError: null,\n        isSubmitSuccessful: null,\n      });\n    },\n  };\n}\n","import { onMounted, onScopeDispose, shallowRef, toValue, type ShallowRef } from 'vue';\n\nimport {\n  revalidateLogic,\n  useForm,\n  type DeepKeys,\n  type FormApi,\n  type FormAsyncValidateOrFn,\n  type FormOptions,\n  type FormValidateAsyncFn,\n  type VueFormApi,\n} from '@tanstack/vue-form';\n\nimport { fieldIssues } from '../../foundation/http';\nimport type { ResolveValidationMessage } from '../../foundation/validation';\n\nimport type { AppFieldApi, AppForm, AppFormOptions, AppFormOptionsSource, AppFormState } from '../AppForm';\nimport { deepEqual } from '../DeepEqual';\nimport {\n  createFieldApi,\n  createFieldComponent,\n  createFormStateView,\n  createUseFormState,\n} from '../FormGlue';\nimport { getPath, hasPath } from '../Paths';\nimport { createOptionsMessageResolver, runStandardSchema } from '../SchemaValidation';\nimport { defaultMapFieldPath, resolveSubmitFailure } from '../SubmitErrors';\n\nimport {\n  createTanstackFormOverlay,\n  type TanstackFormOverlay,\n  type TanstackOverlayState,\n} from './TanstackFormOverlay';\n\n/*\n * The tanstack adapter — the facade contract over `@tanstack/vue-form` (optional peer).\n * TanStack owns values, validation scheduling, and the submit lifecycle; the overlay\n * (`TanstackFormOverlay`) owns everything the contract pins that TanStack models\n * differently — server-error merge/clearing, baseline-compared dirty, blur-or-submit\n * touched, contract array reindexing, `submitError` (see the overlay's module doc).\n *\n * Validation wiring: the whole-form Standard Schema runs as a TanStack form-level\n * `onDynamicAsync` validator under `revalidateLogic` — `validateOn` maps 1:1 onto its\n * pre-submission `mode` ('submit' default / 'blur' / 'change'), and `modeAfterSubmission:\n * 'change'` gives the pinned post-attempt change-revalidation. The validator returns\n * TanStack's global `{ form?, fields }` error shape, so client errors land in TanStack\n * field meta (created on demand — no TanStack `Field` mounts needed) and `state.isValid`\n * stays engine-native. Adapter notes (both mirror the contract's static options intent):\n *   - `validateOn` and schema PRESENCE are creation-pinned; the schema VALUE is read\n *     per run, so swapping schema instances through a getter source is honored.\n *   - Escape-hatch writes (`engine.setFieldValue`) bypass the overlay — server-error\n *     clearing and touched semantics then follow TanStack, not the contract.\n *\n * WHAT THE VUE PACKAGE CHANGED. `@tanstack/vue-form` is the same `form-core` under a different\n * host binding, so every call in here is unchanged; what moved is how state is READ.\n *   - `ReactFormExtendedApi` has no Vue twin — the returned instance is `FormApi & VueFormApi`.\n *   - TanStack's store is a `@tanstack/store` `Store`, invisible to Vue's tracker. It is bridged\n *     ONCE, here, into a `shallowRef` (`bridgeStore`); every contract read then flows through\n *     Vue reactivity. `form.useSelector` would do the same per slice, but it wraps its ref in\n *     `readonly()`, which would hand values back through a proxy and break the identity compares\n *     the reader and `deepEqual` rely on.\n *   - `useForm` applies its options ONCE (Vue's `setup` runs once), where React re-applied them\n *     every render. The stable-options dance survives anyway because `reset()` still has to keep\n *     `tanstackOptions.defaultValues` in step with TanStack's own copy.\n */\n\n/** The native TanStack form instance the adapter builds — what `form.engine` exposes. */\nexport type TanstackFormEngine<TValues extends object> = FormApi<\n  TValues,\n  undefined, // onMount\n  undefined, // onChange\n  undefined, // onChangeAsync\n  undefined, // onBlur\n  undefined, // onBlurAsync\n  undefined, // onSubmit\n  undefined, // onSubmitAsync\n  undefined, // onDynamic\n  FormAsyncValidateOrFn<TValues>, // onDynamicAsync — the adapter's schema bridge\n  undefined, // onServer\n  never // submitMeta\n> &\n  VueFormApi<\n    TValues,\n    undefined,\n    undefined,\n    undefined,\n    undefined,\n    undefined,\n    undefined,\n    undefined,\n    undefined,\n    FormAsyncValidateOrFn<TValues>,\n    undefined,\n    never\n  >;\n\ntype TanstackFormOptions<TValues extends object> = FormOptions<\n  TValues,\n  undefined,\n  undefined,\n  undefined,\n  undefined,\n  undefined,\n  undefined,\n  undefined,\n  undefined,\n  FormAsyncValidateOrFn<TValues>,\n  undefined,\n  never\n>;\n\nconst EMPTY_MESSAGES: readonly string[] = Object.freeze([]);\n\n/**\n * Folds the shared schema-error map into TanStack's global form error shape:\n * root-path (`''`) issues become the form-level error, the rest per-field errors.\n */\nfunction toEngineValidationError(errors: Record<string, string[]>): unknown {\n  const paths = Object.keys(errors);\n  if (paths.length === 0) return undefined;\n  const fields: Record<string, string[]> = {};\n  let form: string[] | undefined;\n  for (const path of paths) {\n    if (path === '') form = errors[path];\n    else fields[path] = errors[path] ?? [];\n  }\n  return form ? { form, fields } : { fields };\n}\n\n/**\n * Normalizes TanStack field-meta errors to plain messages. The adapter's own validator\n * yields `string[]`, but escape-hatch validators may add strings, nested arrays, or\n * Standard Schema issue objects — all are accepted.\n */\nfunction toMessages(errors: ReadonlyArray<unknown> | undefined): readonly string[] {\n  if (!errors || errors.length === 0) return EMPTY_MESSAGES;\n  const messages: string[] = [];\n  const visit = (error: unknown): void => {\n    if (error === null || error === undefined) return;\n    if (typeof error === 'string') {\n      messages.push(error);\n      return;\n    }\n    if (Array.isArray(error)) {\n      for (const entry of error) visit(entry);\n      return;\n    }\n    if (typeof error === 'object' && typeof (error as { message?: unknown }).message === 'string') {\n      messages.push((error as { message: string }).message);\n    }\n  };\n  for (const error of errors) visit(error);\n  return messages.length > 0 ? messages : EMPTY_MESSAGES;\n}\n\n/** The per-field slice the `Field` glue reads — identity-stable while its members are unchanged. */\ninterface TanstackFieldState {\n  readonly value: unknown;\n  readonly errors: readonly string[];\n  readonly isDirty: boolean;\n  readonly isTouched: boolean;\n}\n\n/** The minimal structural view of TanStack form state the reader consumes (loose string paths). */\ninterface EngineStateView {\n  readonly values: unknown;\n  readonly isValid: boolean;\n  readonly isValidating: boolean;\n  readonly isFormValidating: boolean;\n  readonly fieldMeta: Partial<Record<string, { readonly errors: ReadonlyArray<unknown> }>>;\n}\n\nfunction sameMessages(a: readonly string[], b: readonly string[]): boolean {\n  return a === b || (a.length === b.length && a.every((message, index) => message === b[index]));\n}\n\nfunction fieldStatesEqual(a: TanstackFieldState, b: TanstackFieldState): boolean {\n  return (\n    Object.is(a.value, b.value) &&\n    a.isDirty === b.isDirty &&\n    a.isTouched === b.isTouched &&\n    sameMessages(a.errors, b.errors)\n  );\n}\n\n/**\n * Mirrors the `@tanstack/store` store into a `shallowRef` — the ONE seam that puts TanStack\n * state inside Vue's tracker. Deliberately not `useSelector`/`useStore` from\n * `@tanstack/vue-store`: those wrap the ref in `readonly()`, which would hand every read back\n * through a deep proxy and defeat the `Object.is` identity compares the reader, `deepEqual`, and\n * TanStack's own writes all depend on.\n */\nfunction bridgeStore<TValues extends object>(engine: TanstackFormEngine<TValues>): ShallowRef<EngineStateView> {\n  const snapshot = shallowRef(engine.store.state as unknown as EngineStateView);\n  const subscription = engine.store.subscribe((next) => {\n    snapshot.value = next as unknown as EngineStateView;\n  });\n  onScopeDispose(() => subscription.unsubscribe(), true);\n  return snapshot;\n}\n\ninterface CombinedReader<TValues extends object> {\n  readonly getFormState: () => AppFormState<TValues>;\n  readonly getFieldState: (path: string) => TanstackFieldState;\n}\n\n/**\n * Derives the contract state from the (TanStack store state, overlay state) pair with\n * generation caching: snapshots are rebuilt only when either source commits, and per-path\n * field slices reuse the previous generation's identity when unchanged — so a read stays\n * referentially stable between commits. Both sources are `shallowRef`s, so every read below\n * is also the subscription.\n */\nfunction createCombinedReader<TValues extends object>(\n  snapshot: ShallowRef<EngineStateView>,\n  overlay: TanstackFormOverlay<TValues>,\n): CombinedReader<TValues> {\n  let generation: { tan: EngineStateView; ov: TanstackOverlayState<TValues> } | null = null;\n  let formState: AppFormState<TValues> | null = null;\n  let fieldCache = new Map<string, TanstackFieldState>();\n  let previousFieldCache = new Map<string, TanstackFieldState>();\n\n  function currentGeneration(): { tan: EngineStateView; ov: TanstackOverlayState<TValues> } {\n    const tan = snapshot.value;\n    const ov = overlay.state.value;\n    if (generation && generation.tan === tan && generation.ov === ov) return generation;\n    generation = { tan, ov };\n    formState = null;\n    previousFieldCache = fieldCache;\n    fieldCache = new Map();\n    return generation;\n  }\n\n  return {\n    getFormState: () => {\n      const { tan, ov } = currentGeneration();\n      formState ??= {\n        values: tan.values as TValues,\n        isDirty: !deepEqual(tan.values, ov.baseline),\n        // Client validity is engine-native; the server-error overlay holds it false too.\n        isValid: tan.isValid && Object.keys(ov.serverErrors).length === 0,\n        isSubmitting: ov.isSubmitting,\n        // Whole-schema validation is a FORM-level validator — TanStack's derived\n        // `isValidating` counts field-level validators only, so merge both flags.\n        isValidating: tan.isFormValidating || tan.isValidating,\n        submitError: ov.submitError,\n        isSubmitSuccessful: ov.isSubmitSuccessful,\n      };\n      return formState;\n    },\n    getFieldState: (path) => {\n      const { tan, ov } = currentGeneration();\n      const cached = fieldCache.get(path);\n      if (cached) return cached;\n      const value = getPath(tan.values, path);\n      const clientMessages = toMessages(tan.fieldMeta[path]?.errors);\n      const serverMessages = ov.serverErrors[path] ?? EMPTY_MESSAGES;\n      const computed: TanstackFieldState = {\n        value,\n        // Client + server messages merged, client first (contract JSDoc).\n        errors:\n          serverMessages.length === 0\n            ? clientMessages\n            : clientMessages.length === 0\n              ? serverMessages\n              : [...clientMessages, ...serverMessages],\n        isDirty: !deepEqual(value, getPath(ov.baseline, path)),\n        // A submit attempt counts as touching everything — error-display gating works post-attempt.\n        isTouched: ov.touched.has(path) || ov.submitCount > 0,\n      };\n      const previous = previousFieldCache.get(path);\n      const stable = previous && fieldStatesEqual(previous, computed) ? previous : computed;\n      fieldCache.set(path, stable);\n      return stable;\n    },\n  };\n}\n\ninterface AdapterPrelude<TValues extends object> {\n  readonly getOptions: () => AppFormOptions<TValues>;\n  readonly overlay: TanstackFormOverlay<TValues>;\n  readonly tanstackOptions: TanstackFormOptions<TValues>;\n  /** The form's message resolver, memoized against the `messages` / `labels` option identities. */\n  readonly messageResolver: () => ResolveValidationMessage;\n}\n\n/** Builds the overlay + the stable TanStack options (all callbacks read the latest options through `getOptions`). */\nfunction createAdapterPrelude<TValues extends object>(\n  getOptions: () => AppFormOptions<TValues>,\n): AdapterPrelude<TValues> {\n  const initialOptions = getOptions();\n  const overlay = createTanstackFormOverlay<TValues>(initialOptions.defaultValues);\n  const messageResolver = createOptionsMessageResolver(getOptions);\n\n  const tanstackOptions: TanstackFormOptions<TValues> = {\n    defaultValues: initialOptions.defaultValues,\n    onSubmit: async ({ value }) => {\n      // The contract's `isSubmitting` brackets ONLY the app submit call (house-identical),\n      // not TanStack's validation window. Failures propagate to the adapter's\n      // `handleSubmit` catch, so TanStack's own submit lifecycle stays truthful.\n      overlay.setSubmitting(true);\n      try {\n        await getOptions().onSubmit(value);\n        // Reached only when validation passed AND the app submit resolved — the verdict's\n        // sole success signal (the invalid path never runs this; a throw skips it).\n        overlay.setSubmitSuccessful(true);\n      } finally {\n        overlay.setSubmitting(false);\n      }\n    },\n  };\n\n  if (initialOptions.schema) {\n    const validateWithSchema: FormValidateAsyncFn<TValues> = async ({ value }) => {\n      const schema = getOptions().schema;\n      if (!schema) return undefined;\n      return toEngineValidationError(await runStandardSchema(schema, value, messageResolver()));\n    };\n    tanstackOptions.validators = { onDynamicAsync: validateWithSchema };\n    tanstackOptions.validationLogic = revalidateLogic({\n      // `validateOn` maps 1:1 onto the pre-submission mode; after the first attempt\n      // every mode re-validates on change so errors clear as the user fixes them.\n      mode: initialOptions.validateOn ?? 'submit',\n      modeAfterSubmission: 'change',\n    });\n  }\n\n  return { getOptions, overlay, tanstackOptions, messageResolver };\n}\n\n/** What `buildAppForm` returns — the contract surface plus the teardown the adapter's own timer needs. */\ninterface BuiltForm<TValues extends object> {\n  readonly form: AppForm<TValues, TanstackFormEngine<TValues>>;\n  /** Releases the pending `submitOn: 'change'` debounce timer on scope teardown. */\n  readonly dispose: () => void;\n}\n\n/** Builds the stable contract surface over the TanStack engine + overlay pair. */\nfunction buildAppForm<TValues extends object>(\n  engine: TanstackFormEngine<TValues>,\n  prelude: AdapterPrelude<TValues>,\n): BuiltForm<TValues> {\n  const { getOptions, overlay, tanstackOptions, messageResolver } = prelude;\n  const reader = createCombinedReader(bridgeStore(engine), overlay);\n\n  // ── Submit path shared by `handleSubmit` + auto-submit (validate → onSubmit → map failure) ─────\n  /** Resolves a thrown submit failure onto the overlay (matched paths → fields, remainder → banner). */\n  function applySubmitFailure(error: unknown): void {\n    const options = getOptions();\n    const values = engine.store.state.values;\n    overlay.applySubmitFailure(\n      resolveSubmitFailure(\n        error,\n        options.mapSubmitError ?? fieldIssues,\n        options.mapFieldPath ?? defaultMapFieldPath,\n        (path) => hasPath(values, path),\n        options.fallbackErrorMessage,\n        messageResolver(),\n      ),\n    );\n  }\n\n  /** Runs the app `onSubmit` inside the contract's `isSubmitting` bracket (the `submitInvalid` path). */\n  async function runOnSubmit(): Promise<boolean> {\n    overlay.setSubmitting(true);\n    try {\n      await getOptions().onSubmit(engine.store.state.values);\n      overlay.setSubmitSuccessful(true);\n      return true;\n    } catch (error) {\n      applySubmitFailure(error);\n      overlay.setSubmitSuccessful(false);\n      return false;\n    } finally {\n      overlay.setSubmitting(false);\n    }\n  }\n\n  async function performSubmit(): Promise<boolean> {\n    // A whole-form disabled form is inert — no attempt, no onSubmit (read-only / role-locked / frozen).\n    if (getOptions().isDisabled) return false;\n    // A new attempt clears the previous server errors/submitError, re-arms the verdict, touches all.\n    overlay.beginSubmitAttempt();\n\n    if (getOptions().submitInvalid) {\n      // Backend-as-source-of-truth: always validate (advisory errors populate + render), then run\n      // `onSubmit` regardless of validity — the verdict reflects `onSubmit`, not the client gate.\n      await engine.validate('submit');\n      return runOnSubmit();\n    }\n\n    // Default — TanStack gates `onSubmit` on validity; a valid pass runs the wrapper `onSubmit`.\n    let succeeded = false;\n    try {\n      await engine.handleSubmit();\n      // The wrapper `onSubmit` flips the verdict true only on a valid + resolved submit;\n      // an invalid attempt leaves it `null` (no throw, `onSubmit` never ran).\n      succeeded = overlay.getState().isSubmitSuccessful === true;\n    } catch (error) {\n      // TanStack rethrows `onSubmit` failures — resolve them here so the contract's\n      // `handleSubmit` never rejects and no server message silently disappears.\n      applySubmitFailure(error);\n      succeeded = false;\n    }\n    // Settle the verdict — the invalid path's `null` becomes `false`; success is idempotent.\n    overlay.setSubmitSuccessful(succeeded);\n    return succeeded;\n  }\n\n  /**\n   * Single-flight submit — while a run is in flight a re-entrant trigger (double-click / Enter-spam /\n   * a `submitOn: 'change'` burst) coalesces onto it instead of starting a second `onSubmit`.\n   */\n  let inFlight: Promise<boolean> | null = null;\n  async function guardedSubmit(): Promise<boolean> {\n    if (inFlight) return inFlight;\n    const run = performSubmit();\n    inFlight = run;\n    try {\n      return await run;\n    } finally {\n      inFlight = null;\n    }\n  }\n\n  /** Validate without submitting — marks touched, runs the whole-form schema, resolves client validity. */\n  async function validate(): Promise<boolean> {\n    overlay.touchAll();\n    await engine.validate('submit');\n    return engine.store.state.isValid;\n  }\n\n  // ── Auto-submit (`submitOn`) — routes through the SAME `guardedSubmit` as manual submit ────────\n  let autoSubmitTimer: ReturnType<typeof setTimeout> | null = null;\n  const clearAutoSubmitTimer = (): void => {\n    if (autoSubmitTimer !== null) {\n      clearTimeout(autoSubmitTimer);\n      autoSubmitTimer = null;\n    }\n  };\n  const scheduleAutoSubmit = (): void => {\n    if ((getOptions().submitOn ?? 'manual') !== 'change') return;\n    clearAutoSubmitTimer();\n    const delay = getOptions().submitDebounceMs ?? 0;\n    autoSubmitTimer = setTimeout(() => {\n      autoSubmitTimer = null;\n      void guardedSubmit();\n    }, delay);\n  };\n  const autoSubmitOnBlur = (): void => {\n    if ((getOptions().submitOn ?? 'manual') === 'blur') void guardedSubmit();\n  };\n\n  // One API object per path (React memoized the same thing inside its per-field hook).\n  const fieldApis = new Map<string, AppFieldApi<unknown>>();\n  const fieldOps = {\n    getState: (path: string) => reader.getFieldState(path),\n    setValue: (path: string, value: unknown) => {\n      // Server messages clear on the next change to the field (contract JSDoc).\n      overlay.clearServerErrorsAt(path);\n      // Triggers TanStack 'change'-cause validation, gated by `revalidateLogic`.\n      engine.setFieldValue(path as DeepKeys<TValues>, value as never);\n      // `submitOn: 'change'` — a user-origin write schedules the debounced auto-submit.\n      scheduleAutoSubmit();\n    },\n    blur: (path: string) => {\n      overlay.markBlurred(path);\n      // 'blur'-cause validation — runs the schema only in `validateOn: 'blur'` mode.\n      void engine.validateField(path as DeepKeys<TValues>, 'blur');\n      // `submitOn: 'blur'` — save-on-blur.\n      autoSubmitOnBlur();\n    },\n  };\n  const getFieldApi = (path: string): AppFieldApi<unknown> => {\n    const existing = fieldApis.get(path);\n    if (existing) return existing;\n    const api = createFieldApi(path, fieldOps);\n    fieldApis.set(path, api);\n    return api;\n  };\n\n  const arrayOperation = (path: string, operation: Parameters<typeof overlay.remapForArrayOperation>[1]): void => {\n    // TanStack's array ops are constrained to its typed array paths (`DeepKeysOfType`); the\n    // contract's paths are loose strings, so the vendor's path algebra is opted out of with\n    // `never` rather than reimplemented here.\n    const field = path as never;\n    switch (operation.kind) {\n      case 'push':\n        engine.pushFieldValue(field, operation.value as never);\n        break;\n      case 'insert':\n        void engine.insertFieldValue(field, operation.index, operation.value as never);\n        break;\n      case 'remove':\n        void engine.removeFieldValue(field, operation.index);\n        break;\n      case 'swap':\n        engine.swapFieldValues(field, operation.indexA, operation.indexB);\n        break;\n      case 'move':\n        engine.moveFieldValues(field, operation.fromIndex, operation.toIndex);\n        break;\n    }\n    // Contract reindexing for the overlay: row-scoped server errors + touched marks\n    // follow their rows. TanStack shifts its OWN field meta by its rules; where they\n    // differ, the contract wins because errors/touched surface from the overlay and\n    // client errors are recomputed by the op's change-revalidation.\n    overlay.remapForArrayOperation(path, operation);\n    scheduleAutoSubmit();\n  };\n\n  const state = createFormStateView<TValues>(reader.getFormState);\n\n  const form: AppForm<TValues, TanstackFormEngine<TValues>> = {\n    Field: createFieldComponent<TValues>(getFieldApi, () => getOptions().isDisabled ?? false),\n    state,\n    // The same computed `state.values` reads — `form.values` is a shorthand, never a second source.\n    get values() {\n      return state.values;\n    },\n    useFormState: createUseFormState<TValues>(reader.getFormState),\n    handleSubmit: async (event?: Event) => {\n      event?.preventDefault();\n      return guardedSubmit();\n    },\n    validate,\n    setValue: (path, value) => {\n      // Server messages clear on the next change to the field (contract JSDoc) — mirror the\n      // in-field `setValue`; TanStack's 'change'-cause validation runs under `revalidateLogic`.\n      overlay.clearServerErrorsAt(path);\n      engine.setFieldValue(path as DeepKeys<TValues>, value as never);\n      scheduleAutoSubmit();\n    },\n    array: (path: string) => ({\n      push: (value: unknown) => arrayOperation(path, { kind: 'push', value }),\n      insert: (index: number, value: unknown) => arrayOperation(path, { kind: 'insert', index, value }),\n      remove: (index: number) => arrayOperation(path, { kind: 'remove', index }),\n      swap: (indexA: number, indexB: number) => arrayOperation(path, { kind: 'swap', indexA, indexB }),\n      move: (fromIndex: number, toIndex: number) => arrayOperation(path, { kind: 'move', fromIndex, toIndex }),\n    }),\n    reset: (next?: TValues) => {\n      const values = next ?? getOptions().defaultValues;\n      // Keep the options object TanStack was created with in sync: its own `reset(values)`\n      // rewrites `options.defaultValues`, and any later `update()` would otherwise clobber the\n      // re-seeded values back from the stale copy.\n      tanstackOptions.defaultValues = values;\n      overlay.reset(values);\n      engine.reset(values);\n      clearAutoSubmitTimer(); // a reset/prefill never auto-submits — drop any pending trailing submit\n    },\n    setFieldErrors: (errors: Record<string, string[]>) => overlay.replaceServerErrors(errors),\n    clearSubmitError: () => overlay.clearSubmitError(),\n    engine,\n  };\n\n  return { form, dispose: clearAutoSubmitTimer };\n}\n\n/**\n * The tanstack adapter's `useAppForm` — the facade contract over `@tanstack/vue-form`.\n * The returned form object is stable for the owning scope's lifetime and every state member on\n * it is a live getter, so `form.values.title` / `form.state.isSubmitting` read in a template ARE\n * the subscription; `form.engine` exposes the native {@link TanstackFormEngine} (the 90/10\n * escape hatch — typed here, `unknown` on the shared contract), including TanStack's typed\n * deep-path `Field`/`Subscribe` and per-field validator graph.\n *\n * Call it in `setup()`: `useForm` registers an `onMounted` of its own, and the store bridge +\n * the pending `submitOn: 'change'` timer release on scope teardown.\n */\nexport function useAppForm<TValues extends object>(\n  options: AppFormOptionsSource<TValues>,\n): AppForm<TValues, TanstackFormEngine<TValues>> {\n  const prelude = createAdapterPrelude<TValues>(() => toValue(options));\n  const engine = useForm(prelude.tanstackOptions) as TanstackFormEngine<TValues>;\n  const built = buildAppForm<TValues>(engine, prelude);\n\n  // Validate once on mount when flagged — seeds `isValid` / field errors WITHOUT marking touched\n  // (the mount pass shows validity without asserting the user interacted).\n  onMounted(() => {\n    if (toValue(options).validateOnMount) void engine.validate('submit');\n  });\n  onScopeDispose(built.dispose, true);\n\n  return built.form;\n}\n","// @wow-two-beta/ui-vue/forms-engine/tanstack — the DEFAULT engine adapter over\n// `@tanstack/vue-form` (optional peer; installed only by apps that pin this adapter).\n// Implements the full facade contract with TanStack owning values, validation scheduling\n// (`revalidateLogic` + a form-level Standard Schema bridge), and the submit lifecycle,\n// while the adapter-owned overlay keeps the contract semantics TanStack models\n// differently: client/server error merge with per-field clear-on-change, baseline-\n// compared dirty (`reset(next)` re-seeds), blur-or-submit touched, contract array\n// reindexing of row-scoped errors, and the `submitError` remainder.\n//\n// Past the contract, `form.engine` exposes the native TanStack instance — typed deep-path\n// `engine.Field`/`engine.Subscribe`, per-field validators, listeners — per the 90/10\n// escape-hatch rule (docs/analysis/forms-engine.md §4). Overlay-backed semantics apply\n// only through the contract surface; native writes follow TanStack's own rules.\n//\n// `@tanstack/vue-form` shares `form-core` with the React package, so every engine call the\n// React adapter made survives verbatim; what changed is the READ side — TanStack's store is\n// bridged once into a `shallowRef` so the contract's reactive surface is plain Vue.\n\nimport type { FormEngine } from '../AppForm';\n\nimport { useAppForm } from './UseAppForm';\n\nexport { useAppForm };\nexport type { TanstackFormEngine } from './UseAppForm';\nexport type { TanstackFormOverlay, TanstackOverlayState } from './TanstackFormOverlay';\n\n/** The tanstack adapter as a `FormEngine` — compile-time proof it satisfies the module contract. */\nexport const tanstackFormEngine = { useAppForm } satisfies FormEngine;\n"],"names":[],"mappings":"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"}

package/dist/foundation/animation/Animate.d.ts

@@ -0,0 +1,73 @@
+/** A keyframe list (`[{ opacity: '0' }, { opacity: '1' }]`) or a property-indexed map (`{ opacity: ['0', '1'] }`). */
+export type AnimationKeyframes = Keyframe[] | PropertyIndexedKeyframes;
+/** Tunes a single `animate()` call. Mirrors the subset of `KeyframeAnimationOptions` this slice commits to. */
+export interface AnimateOptions {
+    /** Run length in milliseconds. `0` (or less) commits the final keyframe instantly. Defaults to `200`. */
+    readonly duration?: number;
+    /** CSS easing function (`'ease-out'`, a `cubic-bezier(…)`). Defaults to the house ease-out curve. */
+    readonly easing?: string;
+    /** Milliseconds to wait before the first frame. Defaults to `0`. */
+    readonly delay?: number;
+    /** Whether the animated values persist outside the active window. Defaults to `'none'` — no style residue. */
+    readonly fill?: FillMode;
+    /** How many times the keyframes run. Defaults to `1`. */
+    readonly iterations?: number;
+    /** When `true`, skip the tween and commit the final keyframe immediately. Defaults to `false`. */
+    readonly reducedMotion?: boolean;
+}
+/** The control surface returned by every entry point in this slice. Always safe to call, even on a no-op handle. */
+export interface AnimationHandle {
+    /**
+     * Settles when the animation stops running — finished, cancelled, or removed by the browser.
+     * Never rejects, so it is safe to `await` without a try/catch and safe to ignore entirely.
+     */
+    readonly finished: Promise<void>;
+    /** Stops the animation and reverts to the element's own styles. Settles `finished`. */
+    cancel(): void;
+    /** Jumps to the end of the animation. No-op on an infinite-iteration animation, which cannot finish. */
+    finish(): void;
+    /** Suspends playback at the current time. */
+    pause(): void;
+    /** Resumes playback (or restarts a finished animation). */
+    play(): void;
+}
+/**
+ * Motion defaults for the slice. `duration` reuses `TransitionExtensions.duration.default` (200ms) — the
+ * single existing motion constant in this codebase — so a WAAPI tween and a CSS presence transition agree.
+ * `easing` mirrors Tailwind's `ease-out` (the curve `ScrollViewport` already animates with); there is no
+ * easing token in `foundation/themes` to consume, so this is the slice's declaration of one.
+ */
+export declare const ANIMATION_DEFAULTS: {
+    /** Default run length in milliseconds. */
+    readonly duration: 200;
+    /** Default easing curve — Tailwind `ease-out`. */
+    readonly easing: "cubic-bezier(0, 0, 0.2, 1)";
+};
+/**
+ * An already-settled handle for the paths that never start an animation (no element, no WAAPI, reduced motion,
+ * a no-op FLIP). Callers branch on nothing — `await handle.finished` resolves and `cancel()` is harmless.
+ */
+export declare function noopAnimationHandle(): AnimationHandle;
+/**
+ * The element's inline style declaration, or `null` for a node that has none (a bare `Element`, a text node
+ * reached through a loose cast). `HTMLElement` and `SVGElement` both qualify; nothing else is assumed.
+ */
+export declare function inlineStyleOf(element: Element): CSSStyleDeclaration | null;
+/**
+ * Commits the final frame of `keyframes` as inline styles — the instant-jump branch shared by reduced motion,
+ * `duration: 0`, and hosts without WAAPI. Frame-config keys (`offset`/`easing`/`composite`) and `null` values
+ * are skipped; a `null` in a keyframe means "use the underlying value", which is what NOT writing achieves.
+ */
+export declare function applyFinalKeyframe(element: Element, keyframes: AnimationKeyframes): void;
+/**
+ * Animates `element` through `keyframes` and returns a handle to control it.
+ *
+ * Falls back to committing the final keyframe instantly — with a settled handle, never a throw — when the
+ * element is missing, the host has no `element.animate`, `reducedMotion` is set, or `duration` is `0`.
+ *
+ * @param element The target node. `null`/`undefined` (SSR, an unattached ref) yields a no-op handle.
+ * @param keyframes The frames to run, in either WAAPI shape.
+ * @param options Timing and the reduced-motion switch.
+ * @returns A handle whose `finished` promise settles when the animation stops running.
+ */
+export declare function animate(element: Element | null | undefined, keyframes: AnimationKeyframes, options?: AnimateOptions): AnimationHandle;

package/dist/foundation/animation/AnimatedLayout.d.ts

@@ -0,0 +1,72 @@
+import { PropType, SlotsType, StyleValue, VNode, DefineComponent, ExtractPropTypes, RendererNode, RendererElement, ComponentOptionsMixin, PublicProps, ComponentProvideOptions } from 'vue';
+import { FlipOptions } from './Flip';
+/** Props for `AnimatedLayout`. */
+export interface AnimatedLayoutProps extends FlipOptions {
+    /** Whether layout animation is active. Defaults to `true`. */
+    readonly enabled?: boolean;
+    /** Class for the container element. */
+    readonly class?: unknown;
+    /** Inline styles for the container element. */
+    readonly style?: StyleValue;
+}
+/**
+ * FLIP-animates its children to their new positions when the list reorders, filters, or resizes.
+ *
+ * Renders one plain `<div>` wrapper and clones each slot child with a `data-flip-key`; all layout (flex, grid,
+ * list) stays with the consumer via `class` / `style`, which fall through as ordinary attributes.
+ *
+ * Under `prefers-reduced-motion` — or `:enabled="false"`, or an explicit `reducedMotion` — children jump
+ * straight to their new positions with no transform applied and no residue left behind.
+ */
+export declare const AnimatedLayout: DefineComponent<ExtractPropTypes<{
+    /** Whether layout animation is active. Defaults to `true`. */
+    enabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Animation duration in milliseconds. Falls through to `playFlip`. */
+    duration: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** Timing function. Falls through to `playFlip`. */
+    easing: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** Forces the reduced-motion branch either way, overriding the media query. */
+    reducedMotion: {
+        type: PropType<boolean | undefined>;
+        default: undefined;
+    };
+}>, () => VNode< RendererNode, RendererElement, {
+    [key: string]: any;
+}>, {}, {}, {}, ComponentOptionsMixin, ComponentOptionsMixin, {}, string, PublicProps, Readonly< ExtractPropTypes<{
+    /** Whether layout animation is active. Defaults to `true`. */
+    enabled: {
+        type: BooleanConstructor;
+        default: boolean;
+    };
+    /** Animation duration in milliseconds. Falls through to `playFlip`. */
+    duration: {
+        type: NumberConstructor;
+        default: undefined;
+    };
+    /** Timing function. Falls through to `playFlip`. */
+    easing: {
+        type: StringConstructor;
+        default: undefined;
+    };
+    /** Forces the reduced-motion branch either way, overriding the media query. */
+    reducedMotion: {
+        type: PropType<boolean | undefined>;
+        default: undefined;
+    };
+}>> & Readonly<{}>, {
+    enabled: boolean;
+    duration: number;
+    easing: string;
+    reducedMotion: boolean | undefined;
+}, SlotsType<{
+    default?: () => VNode[];
+}>, {}, {}, string, ComponentProvideOptions, true, {}, any>;