@chelone/core 0.6.0 → 0.7.0

package/dist/form/filter-form-values.js

@@ -1,56 +1,70 @@
-const resolveFilterValue = (formValues, key, filter) => {
-  const formValue = formValues[key];
-  if (formValue === void 0 || formValue === null || Array.isArray(formValue) || formValue instanceof Date) {
-    return key in filter ? filter[key] : "";
-  }
-  if (typeof formValue === "object") {
-    const nestedFilter = typeof filter[key] === "object" && filter[key] !== null ? filter[key] : {};
-    const inner = formValue;
-    const rebuilt = {};
-    for (const innerKey of Object.keys(inner)) {
-      rebuilt[innerKey] = resolveFilterValue(inner, innerKey, nestedFilter);
-    }
-    if (Object.keys(rebuilt).length === 0) return "";
-    return rebuilt;
-  }
-  return key in filter ? filter[key] : "";
+import { isFilterBranch } from "../data/filter-branch.js";
+import { isRecord } from "../guards.js";
+// src/form/filter-form-values.ts
+/**
+* Pure helpers a live filter form uses to keep its values and the list filter
+* in sync. Shared by the React and Vue adapters so the merge and reflect rules
+* live once.
+*/
+var resolveFilterValue = (formValues, key, filter) => {
+	const formValue = formValues[key];
+	if (formValue === void 0 || formValue === null || Array.isArray(formValue) || formValue instanceof Date) return key in filter ? filter[key] : "";
+	if (isRecord(formValue)) {
+		const heldFilter = filter[key];
+		const nestedFilter = isRecord(heldFilter) ? heldFilter : {};
+		const rebuilt = {};
+		for (const innerKey of Object.keys(formValue)) rebuilt[innerKey] = resolveFilterValue(formValue, innerKey, nestedFilter);
+		if (Object.keys(rebuilt).length === 0) return "";
+		return rebuilt;
+	}
+	return key in filter ? filter[key] : "";
 };
+/**
+* Rebuild form values from the incoming filter so EVERY current form key is
+* present with a defined value (an empty string when the filter lacks it).
+*
+* form-core (like RHF) re-applies a field's CURRENT value when `reset(values)`
+* omits that key — which would silently ignore an external filter clear. So a
+* reset must carry a value for every mounted input. This never produces
+* `undefined`/`null` for a present form key.
+*/
 function getFilterFormValues(formValues, filter) {
-  const result = {};
-  for (const key of Object.keys(formValues)) {
-    result[key] = resolveFilterValue(formValues, key, filter);
-  }
-  return result;
+	const result = {};
+	for (const key of Object.keys(formValues)) result[key] = resolveFilterValue(formValues, key, filter);
+	return result;
 }
+/**
+* The form shape the external-reflect must cover: every key that is either a
+* current form value, a REGISTERED field (form-core tracks these in `fieldMeta`
+* even when unset), or present on the incoming filter. Existing values are
+* carried through; registered-but-unset / filter-only keys seed to `undefined`
+* so {@link getFilterFormValues} resolves them from the filter (fallback `''`).
+*/
 function filterFormReflectShape(values, fieldMeta, filter) {
-  const shape = { ...values };
-  for (const key of Object.keys(fieldMeta)) {
-    const top = key.split(/[.[]/, 1)[0];
-    if (top && !(top in shape)) shape[top] = void 0;
-  }
-  for (const key of Object.keys(filter)) {
-    if (!(key in shape)) shape[key] = void 0;
-  }
-  return shape;
+	const shape = { ...values };
+	for (const key of Object.keys(fieldMeta)) {
+		const top = key.split(/[.[]/, 1)[0];
+		if (top && !(top in shape)) shape[top] = void 0;
+	}
+	for (const key of Object.keys(filter)) if (!(key in shape)) shape[key] = void 0;
+	return shape;
 }
+/**
+* Merge form values OVER the existing filter, one level deep, with arrays
+* REPLACED (never element-merged) — matching ra's mergeObjNotArray. The result
+* is a fresh object (no mutation of the inputs).
+*/
 function mergeFilterValues(filter, values) {
-  const merged = { ...filter };
-  for (const key of Object.keys(values)) {
-    const next = values[key];
-    const prev = merged[key];
-    if (next !== null && typeof next === "object" && !Array.isArray(next) && !(next instanceof Date) && prev !== null && typeof prev === "object" && !Array.isArray(prev) && !(prev instanceof Date)) {
-      merged[key] = {
-        ...prev,
-        ...next
-      };
-    } else {
-      merged[key] = next;
-    }
-  }
-  return merged;
+	const merged = { ...filter };
+	for (const key of Object.keys(values)) {
+		const next = values[key];
+		const prev = merged[key];
+		if (isFilterBranch(next) && isFilterBranch(prev)) merged[key] = {
+			...prev,
+			...next
+		};
+		else merged[key] = next;
+	}
+	return merged;
 }
-export {
-  filterFormReflectShape,
-  getFilterFormValues,
-  mergeFilterValues
-};
+export { filterFormReflectShape, getFilterFormValues, mergeFilterValues };

package/dist/form/form-controller.d.ts

@@ -1,5 +1,7 @@
 import { FormApi, type FormAsyncValidateOrFn, type FormOptions, type FormValidateOrFn, type StandardSchemaV1 } from "@tanstack/form-core";
+import { type TranslateParamValues } from "../i18n/messages.js";
 import type { NotificationStore } from "../notification/notification-store.js";
+import { type FormHandle } from "./form-handle.js";
 /** A sync validator slot of the wrapped FormApi: fn, Standard Schema, or absent. */
 export type SyncValidator<TRecord> = FormValidateOrFn<TRecord> | undefined;
 /** An async validator slot of the wrapped FormApi. */
@@ -39,7 +41,7 @@ export type FieldErrors = Record<string, string | string[]>;
  */
 export interface TranslatableMessage {
     message: string;
-    args?: Record<string, unknown>;
+    args?: TranslateParamValues;
 }
 /**
  * Form-level validate fn (ra contract): receives ALL values, returns a map of
@@ -115,6 +117,12 @@ export interface FormController<TRecord> {
      * and advanced imperative use.
      */
     form: CheloneFormApi<TRecord>;
+    /**
+     * The same form as a {@link FormHandle}: `source` paths typed by `TRecord`,
+     * values typed at each path, and the record-erased `ambient` form a context
+     * can carry.
+     */
+    handle: FormHandle<TRecord>;
     /**
      * Refcounted subscription (uSES-compatible): registers `listener` with
      * `form.store` and mounts the form on the 0 -> 1 transition. Returns an

package/dist/form/form-controller.js

@@ -1,168 +1,173 @@
-import { revalidateLogic, FormApi } from "@tanstack/form-core";
-import { composeFormValidator, isThenable, toFormErrorMapValue, sanitizeEmptyValues } from "./save-pipeline.js";
+import { hasProperty, isThenable } from "../guards.js";
+import { pickTranslateParamValues } from "../i18n/messages.js";
+import { ERROR_MAP_PRIORITY } from "./field-error.js";
+import { createFormHandle } from "./form-handle.js";
+import { composeFormValidator, sanitizeEmptyValues, toFormErrorMapValue } from "./save-pipeline.js";
+import { FormApi, revalidateLogic } from "@tanstack/form-core";
+// src/form/form-controller.ts
 function createFormController(options) {
-  const userFormOptions = options.formOptions;
-  let serverErrorsApplied = false;
-  const notifyInvalid = (root) => {
-    const display = displayableRoot(root);
-    if (display === void 0) {
-      options.notifications?.notify("chelone.message.invalid_form", {
-        type: "error"
-      });
-    } else if (typeof display === "string") {
-      options.notifications?.notify(display, { type: "error" });
-    } else {
-      options.notifications?.notify(display.message, {
-        type: "error",
-        messageArgs: display.args
-      });
-    }
-  };
-  const dynamicValidator = composeFormValidator({
-    schema: options.schema,
-    validate: options.validate,
-    userValidator: userFormOptions?.validators?.onDynamic
-  });
-  const onSubmit = async ({ value }) => {
-    if (options.validate) {
-      const pending = options.validate(value);
-      const result = isThenable(pending) ? await pending : pending;
-      const mapped2 = toFormErrorMapValue(result);
-      if (mapped2) {
-        form.setErrorMap({ onSubmit: mapped2 });
-        serverErrorsApplied = true;
-        notifyInvalid(mapped2.form);
-        return;
-      }
-    }
-    const data = options.sanitizeEmptyValues ? sanitizeEmptyValues(value, options.getRecord?.()) : value;
-    const fieldErrors = await options.save(data);
-    const mapped = toFormErrorMapValue(fieldErrors);
-    if (mapped) {
-      form.setErrorMap({ onSubmit: mapped });
-      serverErrorsApplied = true;
-      notifyInvalid(mapped.form);
-      return;
-    }
-    if (options.resetOnSuccess !== false) form.reset(value);
-    await options.onSuccess?.(data);
-  };
-  const onSubmitInvalid = (props) => {
-    notifyInvalid(firstFormLevelError(form.store.state.errorMap));
-    userFormOptions?.onSubmitInvalid?.(props);
-  };
-  const formOptions = {
-    ...userFormOptions,
-    defaultValues: options.defaultValues,
-    validators: dynamicValidator ? { ...userFormOptions?.validators, onDynamic: dynamicValidator } : userFormOptions?.validators,
-    // revalidateLogic routes the onDynamic slots: run on submit, re-run on
-    // change once a submission failed. ALWAYS set (not only when the form
-    // has its own dynamic validator): FIELD bindings (T3) wire their
-    // validators into the field onDynamic slots, and those route through
-    // `form.options.validationLogic` — under form-core's default logic they
-    // would never run (probed on 1.33). A user-supplied validationLogic wins.
-    validationLogic: userFormOptions?.validationLogic ?? revalidateLogic(),
-    onSubmit,
-    onSubmitInvalid
-  };
-  const form = new FormApi(formOptions);
-  let destroyed = false;
-  let unmountForm;
-  const subscriptions = /* @__PURE__ */ new Set();
-  const detach = () => {
-    const unmount = unmountForm;
-    unmountForm = void 0;
-    unmount?.();
-  };
-  return {
-    form,
-    subscribe(listener) {
-      if (destroyed) return () => {
-      };
-      const storeSubscription = form.store.subscribe(listener);
-      const subscription = {
-        off: () => storeSubscription.unsubscribe()
-      };
-      const isFirst = subscriptions.size === 0;
-      subscriptions.add(subscription);
-      if (isFirst) {
-        unmountForm = form.mount();
-      }
-      return () => {
-        if (!subscriptions.delete(subscription)) return;
-        subscription.off();
-        if (subscriptions.size === 0 && !destroyed) detach();
-      };
-    },
-    getSnapshot: () => form.store.state,
-    async submit() {
-      if (destroyed) return;
-      if (serverErrorsApplied) {
-        form.setErrorMap({ onSubmit: { form: void 0, fields: {} } });
-        serverErrorsApplied = false;
-      }
-      try {
-        await form.handleSubmit();
-      } catch (error) {
-        options.notifications?.notify("chelone.notification.http_error", {
-          type: "error",
-          messageArgs: { _: String(error) }
-        });
-      }
-    },
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      detach();
-      for (const subscription of subscriptions) subscription.off();
-      subscriptions.clear();
-    }
-  };
+	const userFormOptions = options.formOptions;
+	/**
+	* True while the `onSubmit` error-map key holds errors WE wrote (server
+	* fieldErrors / async validate results). They make `canSubmit` false, and
+	* `handleSubmit` dead-ends on that gate BEFORE any validator could clear
+	* them (probed on form-core 1.33) — so `submit()` clears the channel first,
+	* letting an unchanged resubmit re-reach the server.
+	*/
+	let serverErrorsApplied = false;
+	/** Emits the invalid-form notification, preferring a displayable root message. */
+	const notifyInvalid = (root) => {
+		const display = displayableRoot(root);
+		if (display === void 0) options.notifications?.notify("chelone.message.invalid_form", { type: "error" });
+		else if (typeof display === "string") options.notifications?.notify(display, { type: "error" });
+		else options.notifications?.notify(display.message, {
+			type: "error",
+			messageArgs: display.args
+		});
+	};
+	const dynamicValidator = composeFormValidator({
+		schema: options.schema,
+		validate: options.validate,
+		userValidator: userFormOptions?.validators?.onDynamic
+	});
+	const onSubmit = async ({ value }) => {
+		if (options.validate) {
+			const pending = options.validate(value);
+			const result = isThenable(pending) ? await pending : pending;
+			const mapped = toFormErrorMapValue(result);
+			if (mapped) {
+				form.setErrorMap({ onSubmit: mapped });
+				serverErrorsApplied = true;
+				notifyInvalid(mapped.form);
+				return;
+			}
+		}
+		const data = options.sanitizeEmptyValues ? sanitizeEmptyValues(value, options.getRecord?.()) : value;
+		const fieldErrors = await options.save(data);
+		const mapped = toFormErrorMapValue(fieldErrors);
+		if (mapped) {
+			form.setErrorMap({ onSubmit: mapped });
+			serverErrorsApplied = true;
+			notifyInvalid(mapped.form);
+			return;
+		}
+		if (options.resetOnSuccess !== false) form.reset(value);
+		await options.onSuccess?.(data);
+	};
+	const onSubmitInvalid = (props) => {
+		notifyInvalid(firstFormLevelError(form.store.state.errorMap));
+		userFormOptions?.onSubmitInvalid?.(props);
+	};
+	const formOptions = {
+		...userFormOptions,
+		defaultValues: options.defaultValues,
+		validators: dynamicValidator ? {
+			...userFormOptions?.validators,
+			onDynamic: dynamicValidator
+		} : userFormOptions?.validators,
+		validationLogic: userFormOptions?.validationLogic ?? revalidateLogic(),
+		onSubmit,
+		onSubmitInvalid
+	};
+	const form = new FormApi(formOptions);
+	let destroyed = false;
+	/** Non-undefined exactly while attached (mount cleanup). */
+	let unmountForm;
+	const subscriptions = /* @__PURE__ */ new Set();
+	/** Runs the mount cleanup at most once per attach cycle. */
+	const detach = () => {
+		const unmount = unmountForm;
+		unmountForm = void 0;
+		unmount?.();
+	};
+	return {
+		form,
+		handle: createFormHandle(form),
+		subscribe(listener) {
+			if (destroyed) return () => {};
+			const storeSubscription = form.store.subscribe(listener);
+			const subscription = { off: () => storeSubscription.unsubscribe() };
+			const isFirst = subscriptions.size === 0;
+			subscriptions.add(subscription);
+			if (isFirst) unmountForm = form.mount();
+			return () => {
+				if (!subscriptions.delete(subscription)) return;
+				subscription.off();
+				if (subscriptions.size === 0 && !destroyed) detach();
+			};
+		},
+		getSnapshot: () => form.store.state,
+		async submit() {
+			if (destroyed || form.state.isSubmitting) return;
+			if (serverErrorsApplied) {
+				form.setErrorMap({ onSubmit: {
+					form: void 0,
+					fields: {}
+				} });
+				serverErrorsApplied = false;
+			}
+			try {
+				await form.handleSubmit();
+			} catch (error) {
+				options.notifications?.notify("chelone.notification.http_error", {
+					type: "error",
+					messageArgs: { _: String(error) }
+				});
+			}
+		},
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			detach();
+			for (const subscription of subscriptions) subscription.off();
+			subscriptions.clear();
+		}
+	};
 }
+/**
+* Filters an error down to something a NOTIFICATION can display: strings
+* (and the first entry of arrays) pass, objects with a string `message`
+* normalize to a translatable payload, everything else — schema path-record
+* objects, issue lists addressed at fields — yields `undefined` (those are
+* field concerns, the generic invalid_form key covers the notification).
+*/
 function displayableRoot(error) {
-  if (typeof error === "string") return error || void 0;
-  if (Array.isArray(error)) return displayableRoot(error[0]);
-  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
-    return normalizeFormError(error);
-  }
-  return void 0;
+	if (typeof error === "string") return error || void 0;
+	if (Array.isArray(error)) return displayableRoot(error[0]);
+	if (hasProperty(error, "message") && typeof error.message === "string") return normalizeFormError(error);
 }
+/** First displayable form-level error across the error-map keys, submit-first. */
 function firstFormLevelError(errorMap) {
-  const map = errorMap;
-  for (const key of [
-    "onSubmit",
-    "onDynamic",
-    "onChange",
-    "onBlur",
-    "onMount",
-    "onServer"
-  ]) {
-    const candidate = displayableRoot(map[key]);
-    if (candidate !== void 0) return candidate;
-  }
-  return void 0;
+	for (const key of ERROR_MAP_PRIORITY) {
+		const candidate = displayableRoot(errorMap[key]);
+		if (candidate !== void 0) return candidate;
+	}
 }
+/**
+* Boundary normalizer for form-core's `unknown`-typed errors: strings pass
+* through, ra translatable payloads (`{message, args}`) are preserved,
+* Standard Schema issues (and anything else with a string `message`,
+* including `Error`s) collapse to their message, arrays surface their first
+* entry (schema validators emit `StandardSchemaV1Issue[]`), nullish/empty
+* input yields `undefined`, and everything else is `String()`-ed.
+*/
 function normalizeFormError(error) {
-  if (error == null) return void 0;
-  if (typeof error === "string") return error;
-  if (Array.isArray(error)) {
-    return error.length > 0 ? normalizeFormError(error[0]) : void 0;
-  }
-  if (typeof error === "object" && "message" in error) {
-    const { message } = error;
-    if (typeof message === "string") {
-      if ("args" in error) {
-        const { args } = error;
-        if (typeof args === "object" && args !== null && !Array.isArray(args)) {
-          return { message, args };
-        }
-      }
-      return message;
-    }
-  }
-  return String(error);
+	if (error == null) return void 0;
+	if (typeof error === "string") return error;
+	if (Array.isArray(error)) return error.length > 0 ? normalizeFormError(error[0]) : void 0;
+	if (typeof error === "object" && "message" in error) {
+		const { message } = error;
+		if (typeof message === "string") {
+			if ("args" in error) {
+				const args = pickTranslateParamValues(error.args);
+				if (args) return {
+					message,
+					args
+				};
+			}
+			return message;
+		}
+	}
+	return String(error);
 }
-export {
-  createFormController,
-  normalizeFormError
-};
+export { createFormController, normalizeFormError };

package/dist/form/form-groups.d.ts

@@ -13,7 +13,8 @@
  * Vanilla + SSR-safe: no `window`, no React, no router/form library import at
  * runtime — mirrors the resource-registry / MicroStore notification pattern.
  */
-import { type TranslatableMessage } from "./form-controller.js";
+import type { ValidationErrorMap } from "@tanstack/form-core";
+import type { TranslatableMessage } from "./form-controller.js";
 /** Called on every membership mutation (a member added or removed). */
 export type FormGroupsListener = () => void;
 /** The vanilla form-group membership registry contract. */
@@ -47,8 +48,8 @@ export interface GroupFieldMeta {
     isDirty: boolean;
     isTouched: boolean;
     isValidating: boolean;
-    /** Cause-keyed validation errors (`onSubmit`/`onDynamic`/…) — `unknown` values. */
-    errorMap: Record<string, unknown>;
+    /** form-core's cause-keyed validation errors (`onSubmit`/`onDynamic`/…). */
+    errorMap: ValidationErrorMap;
 }
 /** The aggregated group state a badge/toolbar renders. */
 export interface GroupState {