@chelone/core 0.6.0 → 0.9.0

package/dist/form/form-groups.js

@@ -1,83 +1,83 @@
-import { normalizeFormError } from "./form-controller.js";
-const EMPTY_MEMBERS = Object.freeze([]);
+import { firstFieldError } from "./field-error.js";
+// src/form/form-groups.ts
+/** Shared empty snapshot so unknown/empty groups return a stable reference. */
+var EMPTY_MEMBERS = Object.freeze([]);
 function createFormGroups() {
-  const groups = /* @__PURE__ */ new Map();
-  const listeners = /* @__PURE__ */ new Set();
-  const snapshots = /* @__PURE__ */ new Map();
-  const notify = (group) => {
-    snapshots.delete(group);
-    for (const listener of listeners) listener();
-  };
-  return {
-    register(group, source) {
-      let members = groups.get(group);
-      if (members?.has(source)) return;
-      if (!members) {
-        members = /* @__PURE__ */ new Set();
-        groups.set(group, members);
-      }
-      members.add(source);
-      notify(group);
-    },
-    unregister(group, source) {
-      const members = groups.get(group);
-      if (!members?.delete(source)) return;
-      if (members.size === 0) groups.delete(group);
-      notify(group);
-    },
-    getMembers(group) {
-      const members = groups.get(group);
-      if (!members || members.size === 0) return EMPTY_MEMBERS;
-      const cached = snapshots.get(group);
-      if (cached) return cached;
-      const snapshot = Object.freeze([...members]);
-      snapshots.set(group, snapshot);
-      return snapshot;
-    },
-    subscribe(listener) {
-      listeners.add(listener);
-      return () => {
-        listeners.delete(listener);
-      };
-    }
-  };
-}
-const ERROR_MAP_PRIORITY = [
-  "onSubmit",
-  "onDynamic",
-  "onChange",
-  "onBlur",
-  "onMount",
-  "onServer"
-];
-function firstMemberError(errorMap) {
-  for (const cause of ERROR_MAP_PRIORITY) {
-    const normalized = normalizeFormError(errorMap[cause]);
-    if (normalized !== void 0) return normalized;
-  }
-  return void 0;
+	/** group → ordered set of member sources. */
+	const groups = /* @__PURE__ */ new Map();
+	const listeners = /* @__PURE__ */ new Set();
+	/** Per-group cached snapshot; invalidated (deleted) on that group's mutation. */
+	const snapshots = /* @__PURE__ */ new Map();
+	const notify = (group) => {
+		snapshots.delete(group);
+		for (const listener of listeners) listener();
+	};
+	return {
+		register(group, source) {
+			let members = groups.get(group);
+			if (members?.has(source)) return;
+			if (!members) {
+				members = /* @__PURE__ */ new Set();
+				groups.set(group, members);
+			}
+			members.add(source);
+			notify(group);
+		},
+		unregister(group, source) {
+			const members = groups.get(group);
+			if (!members?.delete(source)) return;
+			if (members.size === 0) groups.delete(group);
+			notify(group);
+		},
+		getMembers(group) {
+			const members = groups.get(group);
+			if (!members || members.size === 0) return EMPTY_MEMBERS;
+			const cached = snapshots.get(group);
+			if (cached) return cached;
+			const snapshot = Object.freeze([...members]);
+			snapshots.set(group, snapshot);
+			return snapshot;
+		},
+		subscribe(listener) {
+			listeners.add(listener);
+			return () => {
+				listeners.delete(listener);
+			};
+		}
+	};
 }
+/**
+* Pure reducer: aggregate a group's member fields into a badge-ready
+* {@link GroupState}. A member with NO `fieldMeta` entry (a registered field
+* not yet mounted) contributes nothing — it is treated as valid + clean, so a
+* pending mount never flips the group invalid. `isValid` is an AND (any invalid
+* member fails the group); `isDirty`/`isTouched`/`isValidating` are ORs.
+* `errors` collects the first displayable message per invalid member.
+*/
 function reduceGroupState(fieldMeta, members) {
-  let isValid = true;
-  let isDirty = false;
-  let isTouched = false;
-  let isValidating = false;
-  const errors = {};
-  for (const source of members) {
-    const meta = fieldMeta[source];
-    if (!meta) continue;
-    if (meta.isDirty) isDirty = true;
-    if (meta.isTouched) isTouched = true;
-    if (meta.isValidating) isValidating = true;
-    if (!meta.isValid) {
-      isValid = false;
-      const error = firstMemberError(meta.errorMap);
-      if (error !== void 0) errors[source] = error;
-    }
-  }
-  return { isValid, isDirty, isTouched, isValidating, errors };
+	let isValid = true;
+	let isDirty = false;
+	let isTouched = false;
+	let isValidating = false;
+	const errors = {};
+	for (const source of members) {
+		const meta = fieldMeta[source];
+		if (!meta) continue;
+		if (meta.isDirty) isDirty = true;
+		if (meta.isTouched) isTouched = true;
+		if (meta.isValidating) isValidating = true;
+		if (!meta.isValid) {
+			isValid = false;
+			const error = firstFieldError(meta.errorMap);
+			if (error !== void 0) errors[source] = error;
+		}
+	}
+	return {
+		isValid,
+		isDirty,
+		isTouched,
+		isValidating,
+		errors
+	};
 }
-export {
-  createFormGroups,
-  reduceGroupState
-};
+export { createFormGroups, reduceGroupState };

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

@@ -0,0 +1,175 @@
+import type { ValidationCause } from "@tanstack/form-core";
+import type { RegisteredResources } from "../resource/register.js";
+import type { RecordOf, ResourceMap } from "../resource/registry.js";
+import type { SourcePath, SourceValue } from "../resource/source-path.js";
+import { type ArrayBinding, type ArrayBindingOptions } from "./array-binding.js";
+import type { CheloneFormApi, CheloneFormState } from "./form-controller.js";
+import { type FieldBinding, type FieldBindingOptions } from "./input-binding.js";
+/**
+ * A map of resource name -> record type — the shape {@link FormContextHandleOf}
+ * reads. Core names the records and never their fields.
+ */
+export type RecordMap = {
+    [name: string]: object;
+};
+/** The records of a resource-config map, keyed by resource name. */
+type RecordsOf<TResources extends ResourceMap> = {
+    [TName in keyof TResources]: RecordOf<TResources, TName>;
+};
+/** form-core's derived store of a form's state, as the form itself keeps it. */
+type FormStore<TRecord> = CheloneFormApi<TRecord>["store"];
+/**
+ * The field-meta map of a form whose record type is erased: a form context
+ * spans every record below it and names none of them.
+ */
+export type AmbientFieldMeta = CheloneFormState<unknown>["fieldMeta"];
+/**
+ * The form state a handle reads: its values plus the flags an adapter renders.
+ * Deliberately not the whole form-core state — `fieldMeta` and `errorMap` are
+ * keyed by the record's paths and by its validator slots, and a handle has to
+ * stay readable from a form context that knows neither.
+ */
+export interface FormSnapshot<TRecord> {
+    values: TRecord;
+    isSubmitting: boolean;
+    isDirty: boolean;
+    isValid: boolean;
+    isTouched: boolean;
+    isDefaultValue: boolean;
+    isSubmitSuccessful: boolean;
+    canSubmit: boolean;
+}
+type AmbientFieldOptions = FieldBindingOptions<unknown, string, unknown>;
+type AmbientFieldBinding = FieldBinding<unknown, string, unknown>;
+type AmbientArrayOptions = ArrayBindingOptions<unknown, string>;
+type AmbientArrayBinding = ArrayBinding<unknown, string>;
+/**
+ * A form with its record type erased: the shape a form context carries, since
+ * one context spans every input below it whatever their record. Every path is a
+ * `string` and every value unchecked; a {@link FormHandle} is the way back to a
+ * record, and {@link UnboundFormHandle} is this form as a context member.
+ */
+export interface AmbientForm {
+    /**
+     * form-core's derived store of the record-free state: `values`, `fieldMeta`,
+     * `errorMap` and the form flags.
+     */
+    readonly store: FormStore<unknown>;
+    /** The value at a path. */
+    getFieldValue(path: string): unknown;
+    /** Writes a value at a path, marking the field touched and dirty. */
+    setFieldValue(path: string, value: unknown): void;
+    /** The field's meta (touched/dirty/errors/validators) at a path. */
+    getFieldMeta(path: string): AmbientFieldMeta[string];
+    /** Runs the validators of one field for `cause`, settling when they have. */
+    validateField(path: string, cause: ValidationCause): Promise<void>;
+    /** Runs the form's own submit: validate, then the save the form was built with. */
+    handleSubmit(): Promise<void>;
+    /** Rebaselines the form from `values`, or from its current defaults when omitted. */
+    reset(values?: unknown): void;
+    /**
+     * Binds one field of this form. Inert until the binding is subscribed to
+     * (see {@link FieldBinding}).
+     */
+    bindField(options: AmbientFieldOptions): AmbientFieldBinding;
+    /** Binds one array field of this form. Inert until subscribed to. */
+    bindArray(options: AmbientArrayOptions): AmbientArrayBinding;
+}
+/**
+ * The value at one path of `TRecord`. The path-union case — what a generic
+ * signature comparison instantiates `TPath` with — short-circuits instead of
+ * walking `Get` over the whole `Paths` union.
+ */
+type HandleValue<TRecord, TPath extends string> = string extends TPath ? unknown : SourceValue<TRecord, TPath>;
+/**
+ * The record-typed way into a form: every `source` is a path of `TRecord` and
+ * every value read or written is the value AT that path, not `unknown`.
+ *
+ * The handle is the form side of a form — values and state. Submission belongs
+ * to the controller that owns the save pipeline (`createFormController`,
+ * `createEditFormController`), which exposes a handle next to its own `submit`.
+ *
+ * Nothing here is keyed by the record's path union, so a handle always widens
+ * to {@link UnboundFormHandle} — the way a form context erases it.
+ */
+export interface FormHandle<TRecord> {
+    /** The same form with its record type erased — what a form context carries. */
+    readonly ambient: AmbientForm;
+    /** The current values and form flags. */
+    getSnapshot(): FormSnapshot<TRecord>;
+    /** The value at `TPath`, including the `null`/`undefined` of an optional parent. */
+    getFieldValue<TPath extends string>(path: TPath & SourcePath<TRecord>): HandleValue<TRecord, TPath>;
+    /** Writes `value` at `TPath` (touched + dirty, validated per the form's logic). */
+    setFieldValue<TPath extends string>(path: TPath & SourcePath<TRecord>, value: HandleValue<TRecord, TPath>): void;
+}
+/**
+ * A {@link FormHandle} tagged with the resource its form edits. `TFormData` is
+ * the form's data type (a `Partial` of the record: a create form holds none of
+ * it, an edit form some).
+ */
+export interface ResourceFormHandle<TName extends string, TFormData = unknown> extends FormHandle<TFormData> {
+    readonly resource: TName;
+}
+/** A handle the registry types no record for — the ambient form as a context member. */
+export interface UnboundFormHandle extends FormHandle<unknown> {
+    readonly resource: undefined;
+}
+/**
+ * The handle a form context can hold: one member per resource of `TRecords`,
+ * each narrowing on its own `resource`, plus {@link UnboundFormHandle} for a
+ * form the registry does not type. `UnboundFormHandle` alone when the map names
+ * no fixed resource (`ResourceMap`, the unregistered case).
+ */
+export type FormContextHandleOf<TRecords extends RecordMap> = string extends keyof TRecords ? UnboundFormHandle : {
+    [TName in keyof TRecords & string]: ResourceFormHandle<TName, Partial<TRecords[TName]>>;
+}[keyof TRecords & string] | UnboundFormHandle;
+/** {@link FormContextHandleOf} over the app's registered resources. */
+export type FormContextHandle = FormContextHandleOf<RecordsOf<RegisteredResources>>;
+/**
+ * Wraps a form-core form in a {@link FormHandle}: the typed members read and
+ * write through the form, and `ambient` is the same form with its record type
+ * erased.
+ */
+export declare function createFormHandle<TRecord>(form: CheloneFormApi<TRecord>): FormHandle<TRecord>;
+/**
+ * Tags `handle` with `resource`, keeping its record type: the handle a record
+ * view hands to its form components.
+ */
+export declare function toResourceFormHandle<TName extends string, TFormData>(handle: FormHandle<TFormData>, resource: TName): ResourceFormHandle<TName, TFormData>;
+/**
+ * Widens a handle to the form-context union, tagging it with `resource`, or
+ * leaving it unbound when the form edits no resource.
+ *
+ * A type-level move only: at runtime the object is `handle` with `resource`
+ * set. The registry — not the caller's generic — decides which record type the
+ * name carries, so no plain assignment can express it (see
+ * `form-handle.test-d.ts`).
+ */
+export declare function toFormContextHandle<TName extends string, TFormData>(handle: FormHandle<TFormData>, resource: TName | undefined): FormContextHandle;
+/**
+ * The members every form handle carries, whatever record it types. The
+ * inference anchor for {@link isResourceHandle}: a context union is a union of
+ * handles, and a union is not inferable through a mapped type.
+ */
+export interface AnyFormHandle {
+    readonly resource?: string;
+}
+/**
+ * The names `THandle` can carry. A handle union that names no resource (nothing
+ * registered) takes any string, so a generic caller still compiles.
+ */
+export type HandleName<THandle extends AnyFormHandle> = [
+    NonNullable<THandle["resource"]>
+] extends [never] ? string : NonNullable<THandle["resource"]>;
+/**
+ * Narrows a handle to the member that names `name`.
+ *
+ * The narrowing a generic body cannot do itself: `handle.resource === name`
+ * with a generic `name` leaves the whole union (probed in
+ * `form-handle.test-d.ts`) because the compiler cannot rule out the other
+ * members. At runtime this checks `resource` and nothing else.
+ */
+export declare function isResourceHandle<THandle extends AnyFormHandle, TName extends HandleName<THandle>>(handle: THandle, name: TName): handle is Extract<THandle, {
+    resource: TName;
+}> & ResourceFormHandle<TName>;
+export {};

package/dist/form/form-handle.js

@@ -0,0 +1,68 @@
+import { createArrayBinding } from "./array-binding.js";
+import { createFieldBinding } from "./input-binding.js";
+// src/form/form-handle.ts
+/**
+* Wraps a form-core form in a {@link FormHandle}: the typed members read and
+* write through the form, and `ambient` is the same form with its record type
+* erased.
+*/
+function createFormHandle(form) {
+	const loose = form;
+	const bindField = (options) => createFieldBinding(loose, options);
+	const bindArray = (options) => createArrayBinding(loose, options);
+	return {
+		ambient: {
+			store: loose.store,
+			getFieldValue: (path) => loose.getFieldValue(path),
+			setFieldValue: (path, value) => loose.setFieldValue(path, value),
+			getFieldMeta: (path) => loose.getFieldMeta(path),
+			validateField: async (path, cause) => {
+				await loose.validateField(path, cause);
+			},
+			handleSubmit: () => loose.handleSubmit(),
+			reset: (values) => loose.reset(values),
+			bindField,
+			bindArray
+		},
+		getSnapshot: () => form.state,
+		getFieldValue: (path) => loose.getFieldValue(path),
+		setFieldValue: (path, value) => loose.setFieldValue(path, value)
+	};
+}
+/**
+* Tags `handle` with `resource`, keeping its record type: the handle a record
+* view hands to its form components.
+*/
+function toResourceFormHandle(handle, resource) {
+	return {
+		...handle,
+		resource
+	};
+}
+/**
+* Widens a handle to the form-context union, tagging it with `resource`, or
+* leaving it unbound when the form edits no resource.
+*
+* A type-level move only: at runtime the object is `handle` with `resource`
+* set. The registry — not the caller's generic — decides which record type the
+* name carries, so no plain assignment can express it (see
+* `form-handle.test-d.ts`).
+*/
+function toFormContextHandle(handle, resource) {
+	return {
+		...handle,
+		resource
+	};
+}
+/**
+* Narrows a handle to the member that names `name`.
+*
+* The narrowing a generic body cannot do itself: `handle.resource === name`
+* with a generic `name` leaves the whole union (probed in
+* `form-handle.test-d.ts`) because the compiler cannot rule out the other
+* members. At runtime this checks `resource` and nothing else.
+*/
+function isResourceHandle(handle, name) {
+	return handle.resource === name;
+}
+export { createFormHandle, isResourceHandle, toFormContextHandle, toResourceFormHandle };

package/dist/form/input-binding.d.ts

@@ -1,32 +1,36 @@
-import { type DeepKeys, type DeepValue, FieldApi, type FieldAsyncValidateOrFn, type FieldValidateOrFn, type StandardSchemaV1 } from "@tanstack/form-core";
+import { FieldApi, type FieldAsyncValidateOrFn, type FieldValidateOrFn, type StandardSchemaV1 } from "@tanstack/form-core";
 import type { LooseRecord } from "../resource/record.js";
-import type { SourcePath } from "../resource/source-path.js";
+import type { SourcePath, SourceValue } from "../resource/source-path.js";
+import { type FieldData, type FieldName } from "./field-name.js";
 import type { AsyncValidator, CheloneFormApi, SyncValidator } from "./form-controller.js";
 import { type Validator } from "./validators.js";
 /**
  * ra's default format: render `null`/`undefined` as `''` so text inputs stay
  * controlled; every other value (including `0`/`false`) passes through.
  */
-export declare function defaultFormat(value: unknown): unknown;
+export declare function defaultFormat<TValue>(value: TValue): FormattedValue<TValue>;
+/**
+ * What a field's input holds under {@link defaultFormat}: the stored value with
+ * its holes spelled as `''`.
+ */
+export type FormattedValue<TValue> = Exclude<TValue, null | undefined> | "";
 /**
  * ra's default parse: store a cleared text input (`''`) as `null` — the
  * shape most backends expect; every other value (including `0`/`false`)
  * passes through.
  */
-export declare function defaultParse(input: unknown): unknown;
-/** The widest data type a runtime-composed source path can address. */
-type FieldData<TRecord> = DeepValue<TRecord, DeepKeys<TRecord>>;
+export declare function defaultParse<TInput>(input: TInput): Exclude<TInput, ""> | null;
 /** A sync field-validator slot at its widest legal instantiation. */
-type FieldSync<TRecord> = FieldValidateOrFn<TRecord, DeepKeys<TRecord>, FieldData<TRecord>> | undefined;
+type FieldSync<TRecord> = FieldValidateOrFn<TRecord, FieldName<TRecord>, FieldData<TRecord>> | undefined;
 /** An async field-validator slot at its widest legal instantiation. */
-type FieldAsync<TRecord> = FieldAsyncValidateOrFn<TRecord, DeepKeys<TRecord>, FieldData<TRecord>> | undefined;
+type FieldAsync<TRecord> = FieldAsyncValidateOrFn<TRecord, FieldName<TRecord>, FieldData<TRecord>> | undefined;
 /**
  * The wrapped FieldApi, generic in the DATA type only (the T1 strategy):
  * source paths are composed at runtime (`items[0].sku`), so the name/value
  * generics are pinned to their widest legal instantiations and the form
  * slots mirror {@link CheloneFormApi} exactly.
  */
-export type CheloneFieldApi<TRecord> = FieldApi<TRecord, DeepKeys<TRecord>, FieldData<TRecord>, FieldSync<TRecord>, // onMount
+export type CheloneFieldApi<TRecord> = FieldApi<TRecord, FieldName<TRecord>, FieldData<TRecord>, FieldSync<TRecord>, // onMount
 FieldSync<TRecord>, // onChange
 FieldAsync<TRecord>, // onChangeAsync
 FieldSync<TRecord>, // onBlur
@@ -49,28 +53,31 @@ never>;
 /** The field state snapshot type — what {@link FieldBinding.getSnapshot} returns. */
 export type CheloneFieldState<TRecord> = CheloneFieldApi<TRecord>["state"];
 /**
- * The third validator argument (ra's `props` slot): always carries the final
- * source path; the binding's `validatorMeta` (input props in the React
- * layer) is merged in.
+ * form-core's field store: `{ value, meta }` for an adapter selector. An adapter
+ * cannot know the record of the field it renders, so it reads the default.
  */
-export interface FieldValidatorMeta {
-    source: string;
-    [key: string]: unknown;
-}
-export interface FieldBindingOptions<TRecord = LooseRecord> {
-    /** The FINAL field path (already source-scoped — see `source.ts`). */
-    source: SourcePath<TRecord>;
+export type CheloneFieldStore<TRecord = unknown> = CheloneFieldApi<TRecord>["store"];
+/**
+ * Everything a field binding takes except the identity-defining `source`,
+ * spelled for one value type: `TValue` is what the field holds, `TInput` what
+ * the input holds.
+ */
+export interface FieldBindingBaseOptions<TValue, TInput> {
     /**
      * Input-level default, ra precedence: seeds ONLY into a hole (untouched
      * field whose form value is `undefined`) — an existing record value,
      * including `null`, always wins. Re-applied whenever the hole reopens
      * (reset/rehydration), never dirties the form.
      */
-    defaultValue?: unknown;
-    /** Read transform (raw form value -> input value). Default {@link defaultFormat}. */
-    format?: (value: unknown) => unknown;
+    defaultValue?: TValue;
+    /**
+     * Read transform (raw form value -> input value). Default {@link defaultFormat}.
+     * Takes the holes a record's type does not show: an untouched field is
+     * `undefined`, and {@link defaultParse} stores a cleared input as `null`.
+     */
+    format?: (value: TValue | null | undefined) => TInput;
     /** Write transform (input value -> stored value). Default {@link defaultParse}. */
-    parse?: (input: unknown) => unknown;
+    parse?: (input: TInput) => TValue;
     /** ra-contract validators — composed, first error wins, sync stays sync. */
     validate?: Validator | readonly Validator[];
     /**
@@ -82,8 +89,15 @@ export interface FieldBindingOptions<TRecord = LooseRecord> {
     /** Extra context merged into the validators' meta argument. */
     validatorMeta?: Record<string, unknown>;
 }
-/** `update()` payload: everything but the identity-defining source. */
-export type FieldBindingUpdateOptions = Omit<FieldBindingOptions<LooseRecord>, "source">;
+export interface FieldBindingOptions<TRecord = LooseRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>, TInput = FormattedValue<SourceValue<TRecord, TPath>>> extends FieldBindingBaseOptions<SourceValue<TRecord, TPath>, TInput> {
+    /** The FINAL field path (already source-scoped — see `source.ts`). */
+    source: TPath;
+}
+/**
+ * `update()` payload: everything but the identity-defining source. An adapter
+ * renders under any record, so it reads the defaults.
+ */
+export type FieldBindingUpdateOptions<TValue = unknown, TInput = unknown> = FieldBindingBaseOptions<TValue, TInput>;
 /**
  * Vanilla field binding over a single `@tanstack/form-core` FieldApi —
  * the useInput substrate (T4 wraps it in React contexts).
@@ -102,12 +116,17 @@ export type FieldBindingUpdateOptions = Omit<FieldBindingOptions<LooseRecord>, "
  * submit). The sync slot stays synchronous; the FIRST thenable result
  * latches the binding onto the async slot (injected lazily so pure-sync
  * validators never flicker `isValidating`).
+ *
+ * `TRecord` is the form's data type, `TPath` the field's own source path and
+ * `TInput` what the input holds (`TPath`'s value under `format`), so
+ * `getValue()`/`setValue()` are typed for one field, not for the widest value
+ * in the record.
  */
-export interface FieldBinding<TRecord> {
+export interface FieldBinding<TRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>, TInput = unknown> {
     /** The wrapped FieldApi — the full form-core surface for advanced use. */
     field: CheloneFieldApi<TRecord>;
     /** The final field path this binding is attached to. */
-    readonly source: string;
+    readonly source: TPath;
     /**
      * Refcounted subscription (uSES-compatible): registers `listener` with the
      * identity-memoized `field.store` (per-field render isolation) and mounts
@@ -117,10 +136,16 @@ export interface FieldBinding<TRecord> {
     subscribe(listener: () => void): () => void;
     /** The current field state — `field.store.state` (reference-stable until a write). */
     getSnapshot(): CheloneFieldState<TRecord>;
+    /**
+     * form-core's derived store of this field: `{ value, meta }` for an adapter
+     * selector. Same store object as `field.store` — subscribing here and to the
+     * form costs one subscription each, and neither mounts the field.
+     */
+    readonly store: CheloneFieldStore<TRecord>;
     /** The input-facing value: `format(raw)` — never `null`/`undefined` under the default format. */
-    getValue(): unknown;
+    getValue(): TInput;
     /** Writes `parse(input)` through `handleChange` (marks touched+dirty, validates per revalidation mode). */
-    setValue(input: unknown): void;
+    setValue(input: TInput): void;
     /** Marks the field blurred and runs blur-cause validation. */
     blur(): void;
     /** Requiredness detected from the RAW validate prop (`required()`'s tag). */
@@ -131,7 +156,7 @@ export interface FieldBinding<TRecord> {
      * current option set each render. Re-applies the guarded default when the
      * value hole reopened. Inert while detached (options apply on attach).
      */
-    update(options: FieldBindingUpdateOptions): void;
+    update(options: FieldBindingUpdateOptions<SourceValue<TRecord, TPath>, TInput>): void;
     /**
      * Imperative teardown for vanilla (non-React) consumers: unmounts if
      * attached, severs every listener, and blocks re-attach. Idempotent. React
@@ -139,5 +164,5 @@ export interface FieldBinding<TRecord> {
      */
     destroy(): void;
 }
-export declare function createFieldBinding<TRecord>(form: CheloneFormApi<TRecord>, options: FieldBindingOptions<TRecord>): FieldBinding<TRecord>;
+export declare function createFieldBinding<TRecord, TPath extends SourcePath<TRecord> = SourcePath<TRecord>, TInput = FormattedValue<SourceValue<TRecord, TPath>>>(form: CheloneFormApi<TRecord>, options: FieldBindingOptions<TRecord, TPath, TInput>): FieldBinding<TRecord, TPath, TInput>;
 export {};