@chelone/core 0.6.0 → 0.9.0

package/dist/form/edit-create-form.js

@@ -1,201 +1,256 @@
 import { createCreateController, createEditController } from "../controller/record-controllers.js";
+import { isPlainObject } from "../guards.js";
+import { toFieldName } from "./field-name.js";
 import { createFormController } from "./form-controller.js";
+import { toResourceFormHandle } from "./form-handle.js";
+// src/form/edit-create-form.ts
+/** The registry schema for `resource`, widened to the form's Partial data type. */
 function registrySchema(ctx, resource) {
-  return ctx.resources?.[resource]?.schema;
-}
-function isPlainObject(value) {
-  if (typeof value !== "object" || value === null || Array.isArray(value)) {
-    return false;
-  }
-  const proto = Object.getPrototypeOf(value);
-  return proto === Object.prototype || proto === null;
+	return ctx.resources?.[resource]?.schema;
 }
+/**
+* Parity merge (§0b defaultValues precedence): `override` (the record) WINS,
+* including `null`; explicit `undefined` falls back to the base (an absent
+* server field never erases a default); arrays replace wholesale. Fresh
+* objects on every merged level.
+*/
 function deepMerge(base, override) {
-  if (override === void 0) return base;
-  if (!isPlainObject(base) || !isPlainObject(override)) return override;
-  const result = { ...base };
-  for (const [key, value] of Object.entries(override)) {
-    result[key] = key in base ? deepMerge(base[key], value) : value;
-  }
-  return result;
+	if (override === void 0) return base;
+	if (!isPlainObject(base) || !isPlainObject(override)) return override;
+	const result = { ...base };
+	for (const [key, value] of Object.entries(override)) result[key] = key in base ? deepMerge(base[key], value) : value;
+	return result;
 }
+/**
+* The record-hydration decision (§0b: record identity drives reset):
+* - a record with a DIFFERENT id (loose comparison) -> hard reset, dropping
+*   dirty values. Unreachable through `createEditFormController` today (the
+*   P4 fetch guard errors on id mismatches before a record lands), kept as
+*   the pinned semantic for any composition that can swap records.
+* - untouched form -> rebaseline (apply the merged record as new defaults —
+*   `form.update` auto-applies defaults to untouched forms without dirtying).
+* - FIRST record arrival into a touched form -> partial apply (§0b
+*   keepDirtyValues): the form has never seen the record, so clean fields
+*   still hold construction defaults — keeping them would make the next save
+*   send those defaults over the real record fields (a data wipe). The
+*   record hydrates every clean field; dirty values (and their dirty meta)
+*   survive.
+* - touched form, same record (refetch) -> keep ALL current values (soft):
+*   clean fields already hold the previous record's values — stale at worst,
+*   never destructive.
+*/
 function resolveHydrationAction(previousId, nextId, isTouched) {
-  if (previousId !== void 0 && String(nextId) !== String(previousId)) {
-    return "hard-reset";
-  }
-  if (!isTouched) return "rebaseline";
-  return previousId === void 0 ? "partial-apply" : "keep-dirty";
+	if (previousId !== void 0 && String(nextId) !== String(previousId)) return "hard-reset";
+	if (!isTouched) return "rebaseline";
+	return previousId === void 0 ? "partial-apply" : "keep-dirty";
+}
+/**
+* Wires the shared composed lifecycle. `onAttach` runs on the 0 -> 1
+* subscriber transition BEFORE the form mounts (the edit hydration listener
+* — so a cached record hydrates before mount validators see the form) and
+* its teardown runs on the last unsubscribe.
+*/
+function composeControllers(formController, recordStore, submit, onAttach) {
+	let destroyed = false;
+	let attachTeardown;
+	const active = /* @__PURE__ */ new Set();
+	let lastFormState;
+	let lastRecordState;
+	let cachedSnapshot;
+	return {
+		subscribe(listener) {
+			if (destroyed) return () => {};
+			const token = Symbol("composed-subscription");
+			const isFirst = active.size === 0;
+			active.add(token);
+			if (isFirst && onAttach) attachTeardown = onAttach();
+			const offForm = formController.subscribe(listener);
+			const offRecord = recordStore.subscribe(listener);
+			return () => {
+				if (!active.delete(token)) return;
+				offForm();
+				offRecord();
+				if (active.size === 0) {
+					const teardown = attachTeardown;
+					attachTeardown = void 0;
+					teardown?.();
+				}
+			};
+		},
+		getSnapshot() {
+			const formState = formController.getSnapshot();
+			const recordState = recordStore.getSnapshot();
+			if (cachedSnapshot === void 0 || lastFormState !== formState || lastRecordState !== recordState) {
+				lastFormState = formState;
+				lastRecordState = recordState;
+				cachedSnapshot = {
+					...recordState,
+					form: formState
+				};
+			}
+			return cachedSnapshot;
+		},
+		submit,
+		destroy() {
+			if (destroyed) return;
+			destroyed = true;
+			const teardown = attachTeardown;
+			attachTeardown = void 0;
+			teardown?.();
+			formController.destroy();
+			recordStore.destroy();
+			active.clear();
+		}
+	};
 }
-function composeControllers(formController, recordStore, onAttach) {
-  let destroyed = false;
-  let attachTeardown;
-  const active = /* @__PURE__ */ new Set();
-  let lastFormState;
-  let lastRecordState;
-  let cachedSnapshot;
-  return {
-    subscribe(listener) {
-      if (destroyed) return () => {
-      };
-      const token = /* @__PURE__ */ Symbol("composed-subscription");
-      const isFirst = active.size === 0;
-      active.add(token);
-      if (isFirst && onAttach) attachTeardown = onAttach();
-      const offForm = formController.subscribe(listener);
-      const offRecord = recordStore.subscribe(listener);
-      return () => {
-        if (!active.delete(token)) return;
-        offForm();
-        offRecord();
-        if (active.size === 0) {
-          const teardown = attachTeardown;
-          attachTeardown = void 0;
-          teardown?.();
-        }
-      };
-    },
-    getSnapshot() {
-      const formState = formController.getSnapshot();
-      const recordState = recordStore.getSnapshot();
-      if (cachedSnapshot === void 0 || lastFormState !== formState || lastRecordState !== recordState) {
-        lastFormState = formState;
-        lastRecordState = recordState;
-        cachedSnapshot = { ...recordState, form: formState };
-      }
-      return cachedSnapshot;
-    },
-    submit: () => formController.submit(),
-    destroy() {
-      if (destroyed) return;
-      destroyed = true;
-      const teardown = attachTeardown;
-      attachTeardown = void 0;
-      teardown?.();
-      formController.destroy();
-      recordStore.destroy();
-      active.clear();
-    }
-  };
+/**
+* The per-submit save options. The form's `onSubmit` takes no arguments, so
+* `submit(options)` parks `options` here for the length of that one submit and
+* the form's `save` reads them back through `saveOptions`. Two overlapping
+* submits share the slot.
+*/
+function createSubmitOptions() {
+	let current = {};
+	return {
+		/** The form's `save`: the call's options, with `reconcile` run before the caller's own `onSaved`. */
+		save(recordController, reconcile) {
+			return (data) => {
+				const call = current;
+				return recordController.save(data, {
+					...call,
+					onSaved: async (saved) => {
+						await reconcile(saved);
+						await call.onSaved?.(saved);
+					}
+				});
+			};
+		},
+		async submit(formController, options = {}) {
+			current = options;
+			try {
+				await formController.submit();
+			} finally {
+				current = {};
+			}
+		}
+	};
 }
+/**
+* The money path (D10): P4 `createEditController` + the form controller,
+* wired — record hydration into form defaults, `save` flowing server
+* `fieldErrors` onto the form, success reconciling with SERVER truth
+* (`form.reset(saved)` — D5), one subscription lifecycle spanning both.
+*/
 function createEditFormController(ctx, resource, options) {
-  const recordController = createEditController(
-    ctx,
-    resource,
-    {
-      id: options.id,
-      enabled: options.enabled,
-      mutationMode: options.mutationMode,
-      transform: options.transform,
-      onRedirect: options.onRedirect
-    }
-  );
-  const baseDefaults = options.defaultValues ?? {};
-  const resetOnSuccess = options.resetOnSuccess !== false;
-  const mergedWith = (record) => deepMerge(baseDefaults, record);
-  let lastHydrated;
-  const formController = createFormController({
-    defaultValues: baseDefaults,
-    schema: options.schema ?? registrySchema(ctx, resource),
-    validate: options.validate,
-    sanitizeEmptyValues: options.sanitizeEmptyValues,
-    getRecord: () => recordController.getSnapshot().record,
-    notifications: ctx.notifications,
-    translate: ctx.translate,
-    // The composed layer reconciles with SERVER truth in onSaved below — the
-    // standalone submitted-values reset must not fire first.
-    resetOnSuccess: false,
-    save: (data) => recordController.save(data, {
-      onSaved: async (saved) => {
-        if (resetOnSuccess) {
-          formController.form.reset(mergedWith(saved));
-          lastHydrated = saved;
-        }
-        await options.onSuccess?.(saved);
-      }
-    }),
-    formOptions: options.formOptions
-  });
-  const hydrate = () => {
-    const { record } = recordController.getSnapshot();
-    if (record === void 0 || record === lastHydrated) return;
-    const form = formController.form;
-    const action = resolveHydrationAction(
-      lastHydrated === void 0 ? void 0 : lastHydrated.id,
-      record.id,
-      form.state.isTouched
-    );
-    lastHydrated = record;
-    if (action === "keep-dirty") return;
-    const merged = mergedWith(record);
-    if (action === "hard-reset") {
-      form.reset(merged);
-      return;
-    }
-    if (action === "partial-apply") {
-      const dirtyValues = [];
-      for (const [path, meta] of Object.entries(
-        form.state.fieldMeta
-      )) {
-        if (!meta?.isDirty) continue;
-        const name = path;
-        dirtyValues.push([name, form.getFieldValue(name)]);
-      }
-      form.reset(merged);
-      for (const [path, value] of dirtyValues) {
-        form.setFieldValue(path, value, { dontRunListeners: true });
-      }
-      return;
-    }
-    form.update({ ...form.options, defaultValues: merged });
-  };
-  const lifecycle = composeControllers(formController, recordController, () => {
-    const off = recordController.subscribe(hydrate);
-    hydrate();
-    return off;
-  });
-  return { form: formController.form, recordController, ...lifecycle };
+	const recordController = createEditController(ctx, resource, {
+		id: options.id,
+		enabled: options.enabled,
+		mutationMode: options.mutationMode,
+		transform: options.transform,
+		onRedirect: options.onRedirect
+	});
+	const baseDefaults = options.defaultValues ?? {};
+	const resetOnSuccess = options.resetOnSuccess !== false;
+	const mergedWith = (record) => deepMerge(baseDefaults, record);
+	/** The last hydrated record REFERENCE — unrelated record-store writes (saving flips) skip hydration. */
+	let lastHydrated;
+	const submitOptions = createSubmitOptions();
+	const formController = createFormController({
+		defaultValues: baseDefaults,
+		schema: options.schema ?? registrySchema(ctx, resource),
+		validate: options.validate,
+		sanitizeEmptyValues: options.sanitizeEmptyValues,
+		getRecord: () => recordController.getSnapshot().record,
+		notifications: ctx.notifications,
+		translate: ctx.translate,
+		resetOnSuccess: false,
+		save: submitOptions.save(recordController, async (saved) => {
+			if (resetOnSuccess) {
+				formController.form.reset(mergedWith(saved));
+				lastHydrated = saved;
+			}
+			await options.onSuccess?.(saved);
+		}),
+		formOptions: options.formOptions
+	});
+	const hydrate = () => {
+		const { record } = recordController.getSnapshot();
+		if (record === void 0 || record === lastHydrated) return;
+		const form = formController.form;
+		const action = resolveHydrationAction(lastHydrated === void 0 ? void 0 : lastHydrated.id, record.id, form.state.isTouched);
+		lastHydrated = record;
+		if (action === "keep-dirty") return;
+		const merged = mergedWith(record);
+		if (action === "hard-reset") {
+			form.reset(merged);
+			return;
+		}
+		if (action === "partial-apply") {
+			const dirtyValues = [];
+			for (const [path, meta] of Object.entries(form.state.fieldMeta)) {
+				if (!meta?.isDirty) continue;
+				const name = toFieldName(path);
+				dirtyValues.push([name, form.getFieldValue(name)]);
+			}
+			form.reset(merged);
+			for (const [path, value] of dirtyValues) form.setFieldValue(path, value, { dontRunListeners: true });
+			return;
+		}
+		form.update({
+			...form.options,
+			defaultValues: merged
+		});
+	};
+	const lifecycle = composeControllers(formController, recordController, (saveOptions) => submitOptions.submit(formController, saveOptions), () => {
+		const off = recordController.subscribe(hydrate);
+		hydrate();
+		return off;
+	});
+	return {
+		form: formController.form,
+		handle: toResourceFormHandle(formController.handle, resource),
+		recordController,
+		...lifecycle
+	};
 }
+/**
+* D10's create arm: P4 `createCreateController` + the form controller. No
+* hydration machinery — the seed record and defaults are both known at
+* construction (seed wins, §0b precedence); success reconciles with the
+* CREATED record (server-assigned id included).
+*/
 function createCreateFormController(ctx, resource, options = {}) {
-  const recordController = createCreateController(
-    ctx,
-    resource,
-    {
-      record: options.record,
-      transform: options.transform,
-      onRedirect: options.onRedirect,
-      mutationMode: options.mutationMode
-    }
-  );
-  const seed = options.record ?? {};
-  const baseDefaults = options.defaultValues ?? {};
-  const resetOnSuccess = options.resetOnSuccess !== false;
-  const formController = createFormController({
-    defaultValues: deepMerge(baseDefaults, seed),
-    schema: options.schema ?? registrySchema(ctx, resource),
-    validate: options.validate,
-    sanitizeEmptyValues: options.sanitizeEmptyValues,
-    // ra parity: the create sanitize baseline is the seed record.
-    getRecord: () => seed,
-    notifications: ctx.notifications,
-    translate: ctx.translate,
-    resetOnSuccess: false,
-    save: (data) => recordController.save(data, {
-      onSaved: async (saved) => {
-        if (resetOnSuccess) {
-          formController.form.reset(
-            deepMerge(baseDefaults, saved)
-          );
-        }
-        await options.onSuccess?.(saved);
-      }
-    }),
-    formOptions: options.formOptions
-  });
-  const lifecycle = composeControllers(formController, recordController);
-  return { form: formController.form, recordController, ...lifecycle };
+	const recordController = createCreateController(ctx, resource, {
+		record: options.record,
+		transform: options.transform,
+		onRedirect: options.onRedirect,
+		mutationMode: options.mutationMode
+	});
+	const seed = options.record ?? {};
+	const baseDefaults = options.defaultValues ?? {};
+	const resetOnSuccess = options.resetOnSuccess !== false;
+	const submitOptions = createSubmitOptions();
+	const formController = createFormController({
+		defaultValues: deepMerge(baseDefaults, seed),
+		schema: options.schema ?? registrySchema(ctx, resource),
+		validate: options.validate,
+		sanitizeEmptyValues: options.sanitizeEmptyValues,
+		getRecord: () => seed,
+		notifications: ctx.notifications,
+		translate: ctx.translate,
+		resetOnSuccess: false,
+		save: submitOptions.save(recordController, async (saved) => {
+			if (resetOnSuccess) formController.form.reset(deepMerge(baseDefaults, saved));
+			await options.onSuccess?.(saved);
+		}),
+		formOptions: options.formOptions
+	});
+	const lifecycle = composeControllers(formController, recordController, (saveOptions) => submitOptions.submit(formController, saveOptions));
+	return {
+		form: formController.form,
+		handle: toResourceFormHandle(formController.handle, resource),
+		recordController,
+		...lifecycle
+	};
 }
-export {
-  createCreateFormController,
-  createEditFormController,
-  resolveHydrationAction
-};
+export { createCreateFormController, createEditFormController, resolveHydrationAction };

package/dist/form/event-value.d.ts

@@ -0,0 +1,6 @@
+/**
+ * RHF-compatible event extraction: DOM/synthetic change events yield
+ * `target.checked` for checkboxes and `target.value` otherwise; anything
+ * else (a raw value, a custom picker's payload) passes through untouched.
+ */
+export declare function extractEventValue(input: unknown): unknown;

package/dist/form/event-value.js

@@ -0,0 +1,17 @@
+import { hasProperty } from "../guards.js";
+// src/form/event-value.ts
+/**
+* RHF-compatible event extraction: DOM/synthetic change events yield
+* `target.checked` for checkboxes and `target.value` otherwise; anything
+* else (a raw value, a custom picker's payload) passes through untouched.
+*/
+function extractEventValue(input) {
+	if (!hasProperty(input, "target")) return input;
+	const { target } = input;
+	const hasValue = hasProperty(target, "value");
+	const hasChecked = hasProperty(target, "checked");
+	if (!hasValue && !hasChecked) return input;
+	if (hasProperty(target, "type") && target.type === "checkbox") return hasChecked ? target.checked : void 0;
+	return hasValue ? target.value : void 0;
+}
+export { extractEventValue };

package/dist/form/field-error.d.ts

@@ -0,0 +1,14 @@
+import { type TranslatableMessage } from "./form-controller.js";
+/**
+ * Error-map scan order: server/submit errors first, then validator causes.
+ * Internal to core — `firstFieldError` and the form-level scan both read it, so
+ * the order cannot drift between a field's error and a notification's.
+ */
+export declare const ERROR_MAP_PRIORITY: readonly ["onSubmit", "onDynamic", "onChange", "onBlur", "onMount", "onServer"];
+/**
+ * The first displayable error across a field's error-map causes, normalized.
+ * Takes any error-map shaped object (form-core's `ValidationErrorMap`, its
+ * form-level `FormValidationErrorMap`, a field meta's `errorMap`) and reads
+ * each cause through `Reflect.get`, so no call site needs a cast.
+ */
+export declare function firstFieldError(errorMap: object): string | TranslatableMessage | undefined;

package/dist/form/field-error.js

@@ -0,0 +1,28 @@
+import { normalizeFormError } from "./form-controller.js";
+// src/form/field-error.ts
+/**
+* Error-map scan order: server/submit errors first, then validator causes.
+* Internal to core — `firstFieldError` and the form-level scan both read it, so
+* the order cannot drift between a field's error and a notification's.
+*/
+var ERROR_MAP_PRIORITY = [
+	"onSubmit",
+	"onDynamic",
+	"onChange",
+	"onBlur",
+	"onMount",
+	"onServer"
+];
+/**
+* The first displayable error across a field's error-map causes, normalized.
+* Takes any error-map shaped object (form-core's `ValidationErrorMap`, its
+* form-level `FormValidationErrorMap`, a field meta's `errorMap`) and reads
+* each cause through `Reflect.get`, so no call site needs a cast.
+*/
+function firstFieldError(errorMap) {
+	for (const cause of ERROR_MAP_PRIORITY) {
+		const normalized = normalizeFormError(Reflect.get(errorMap, cause));
+		if (normalized !== void 0) return normalized;
+	}
+}
+export { ERROR_MAP_PRIORITY, firstFieldError };

package/dist/form/field-name.d.ts

@@ -0,0 +1,20 @@
+import type { DeepKeys, DeepValue } from "@tanstack/form-core";
+/**
+ * The one place chelone speaks form-core's path types. `FieldApi` and `FormApi`
+ * constrain their generics on `DeepKeys`/`DeepValue`, while chelone's own paths
+ * are dot.paths' `SourcePath`/`SourceValue`. The two agree on a concrete record
+ * (pinned in `field-name.test-d.ts`), but TS cannot relate them while the record
+ * is a type parameter, so a path crosses over through {@link toFieldName}.
+ *
+ * These are renames, not aliases: a new alias of a conditional type is a
+ * distinct type to TS, which form-core's own signatures then fail to match.
+ */
+export type { DeepKeys as FieldName, DeepValue as FieldValue };
+/**
+ * The widest value a runtime-composed path can address. An alias, so it is for
+ * chelone's own signatures: spell `FieldValue<T, FieldName<T>>` to meet a
+ * value form-core returned.
+ */
+export type FieldData<TRecord> = DeepValue<TRecord, DeepKeys<TRecord>>;
+/** A runtime-composed path, as form-core's name for it. */
+export declare function toFieldName<TRecord>(path: string): DeepKeys<TRecord>;

package/dist/form/field-name.js

@@ -0,0 +1,6 @@
+// src/form/field-name.ts
+/** A runtime-composed path, as form-core's name for it. */
+function toFieldName(path) {
+	return path;
+}
+export { toFieldName };