notform 2.0.0-alpha.2 → 2.0.0-alpha.3

package/dist/index.d.ts

@@ -2749,7 +2749,6 @@ type DeepPartial<TData> = PartialDeep<TData, {
  */
 type Paths<TReference> = Extract<Paths$1<TReference, {
   maxRecursionDepth: 10;
-  bracketNotation: true;
 }>, string> | (string & {});
 /**
  * Represents a validation schema for object-based data structures.
@@ -2800,7 +2799,7 @@ type UseNotFormConfig<TSchema extends ObjectSchema> = {
  * The core state and methods provided by a form instance.
  * @template TSchema The validation schema type derived from ObjectSchema.
  */
-type NotFormInstance<TSchema extends ObjectSchema> = Omit<UseNotFormConfig<TSchema>, 'schema' | 'onSubmit'> & {
+type NotFormInstance<TSchema extends ObjectSchema> = {
   /**
    * A convenience self-reference to the form instance.
    * Useful when you prefer to destructure the composable return value but still need
@@ -2809,7 +2808,14 @@ type NotFormInstance<TSchema extends ObjectSchema> = Omit<UseNotFormConfig<TSche
    * const { values, submit, instance } = useNotForm({ schema, onSubmit })
    * // <NotForm :form="instance" />
    */
-  instance: NotFormInstance<TSchema>; /** Deeply reactive object of field values */
+  instance: NotFormInstance<TSchema>; /** The initial values the form was created or last reset with */
+  readonly initialValues: UseNotFormConfig<TSchema>['initialValues']; /** The initial errors the form was created or last reset with */
+  readonly initialErrors: UseNotFormConfig<TSchema>['initialErrors'];
+  /**
+   * The validation triggers of the form.
+   * @default { onBlur: true, onChange: true, onInput: true }
+   */
+  readonly validateOn: UseNotFormConfig<TSchema>['validateOn']; /** Deeply reactive object of field values */
   values: Ref<StandardSchemaV1.InferInput<TSchema>>;
   /**
    * Updates a specific field value by path.
@@ -2875,14 +2881,8 @@ type NotFormInstance<TSchema extends ObjectSchema> = Omit<UseNotFormConfig<TSche
    * Returns all validation issues for a specific field path.
    * @param path Dot-separated path to the field.
    */
-  getFieldErrors: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => StandardSchemaV1.Issue[];
-  /**
-   * Reactive set of field paths currently being validated.
-   * Empty when no validation is in progress.
-   * Populated with all paths during full-form validation.
-   */
-  validatingFields: Ref<Set<Paths<StandardSchemaV1.InferInput<TSchema>>>>; /** Whether any field or the full form is currently being validated */
-  isValidating: ComputedRef<boolean>;
+  getFieldErrors: (path: Paths<StandardSchemaV1.InferInput<TSchema>>) => StandardSchemaV1.Issue[]; /** Whether any field or the full form is currently being validated */
+  isValidating: Ref<boolean>;
   /**
    * Validates the entire form against the schema.
    * @returns A promise resolving to the validation result.
@@ -2924,6 +2924,9 @@ type NotFormSlots = {
   /** The default slot */default: [];
 };
 //#endregion
+//#region src/composables/use-not-form.d.ts
+declare function useNotForm<TSchema extends ObjectSchema>(config: UseNotFormConfig<TSchema>): NotFormInstance<TSchema>;
+//#endregion
 //#region src/components/not-form.vue.d.ts
 declare const __VLS_export$1: <TSchema extends ObjectSchema>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal$1<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
   props: _$vue.PublicProps & __VLS_PrettifyLocal$1<NotFormProps<TSchema>> & (typeof globalThis extends {
@@ -2940,39 +2943,69 @@ declare const _default$1: typeof __VLS_export$1;
 type __VLS_PrettifyLocal$1<T> = (T extends any ? { [K in keyof T]: T[K] } : { [K in keyof T as K]: T[K] }) & {};
 //#endregion
 //#region src/types/not-field.d.ts
+/** The event handlers provided by a field instance for binding to native or custom inputs. */
+type NotFieldEvents = {
+  /** Triggered when the field loses focus */onBlur: () => void; /** Triggered on every keystroke or value change */
+  onInput: () => void; /** Triggered when the field value is committed */
+  onChange: () => void; /** Triggered when the field gains focus */
+  onFocus: () => void;
+};
 /**
  * Props for the NotField component
  * @template TSchema The validation schema type derived from ObjectSchema.
+ * @template TPath The dot-separated path to the field within the form state.
  */
-type NotFieldProps<TSchema extends ObjectSchema> = {
-  /** The unique name/path identifying the field within the form state */path: string; /** The optional form instance to use - takes priority over injected context */
+type NotFieldProps<TSchema extends ObjectSchema, TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>> = {
+  /** The dot-separated path to the field within the form state */path: TPath; /** Optional form instance — takes priority over injected context */
   form?: NotFormInstance<TSchema>;
+  /**
+   * Per-field validation trigger overrides.
+   * Merged over the form-wide validateOn config — only the keys you specify are overridden.
+   */
+  validateOn?: Partial<Record<ValidationTrigger, boolean>>;
 };
 /**
  * The core state and methods provided by a field instance.
  * @template TSchema The validation schema type derived from ObjectSchema.
+ * @template TPath The dot-separated path to the field within the form state.
  */
-type NotFieldInstance<TSchema extends ObjectSchema> = {
-  /** The unique name/path identifying the field within the form state */path: string; /** The errors of the field */
-  errors: StandardSchemaV1.Issue[]; /** The validate method of the field */
-  validate: () => ReturnType<NotFormInstance<TSchema>['validateField']>;
+type NotFieldInstance<TSchema extends ObjectSchema, TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>> = {
+  /** The dot-separated path to the field within the form state */path: TPath; /** The current value of the field */
+  value: any; /** Whether the field is currently being validated */
+  isValidating: boolean; /** Validates this field against the form schema */
+  validate: () => ReturnType<NotFormInstance<TSchema>['validateField']>; /** The validation issues for this field */
+  errors: StandardSchemaV1.Issue[]; /** Marks the field as touched */
+  touch: () => void; /** Marks the field as not touched */
+  unTouch: () => void; /** Marks the field as dirty */
+  dirty: () => void; /** Marks the field as not dirty */
+  unDirty: () => void;
+  /**
+   * All event handlers combined — spread directly onto native inputs.
+   * @example <input v-bind="events" />
+   */
+  events: NotFieldEvents; /** Triggered when the field loses focus */
+  onBlur: NotFieldEvents['onBlur']; /** Triggered on every keystroke or value change */
+  onInput: NotFieldEvents['onInput']; /** Triggered when the field value is committed */
+  onChange: NotFieldEvents['onChange']; /** Triggered when the field gains focus */
+  onFocus: NotFieldEvents['onFocus'];
 };
 /**
  * Slots for the NotField component
  * @template TSchema The validation schema type derived from ObjectSchema.
+ * @template TPath The dot-separated path to the field within the form state.
  */
-type NotFieldSlots<TSchema extends ObjectSchema> = {
-  /** The default slot receives the field instance for use within templates */default: (props: NotFieldInstance<TSchema>) => [];
+type NotFieldSlots<TSchema extends ObjectSchema, TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>> = {
+  /** The default slot receives the full field instance */default: (props: NotFieldInstance<TSchema, TPath>) => [];
 };
 //#endregion
 //#region src/components/not-field.vue.d.ts
-declare const __VLS_export: <TSchema extends ObjectSchema>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
-  props: _$vue.PublicProps & __VLS_PrettifyLocal<NotFieldProps<TSchema>> & (typeof globalThis extends {
+declare const __VLS_export: <TSchema extends ObjectSchema, TPath extends Paths<StandardSchemaV1.InferInput<TSchema>>>(__VLS_props: NonNullable<Awaited<typeof __VLS_setup>>["props"], __VLS_ctx?: __VLS_PrettifyLocal<Pick<NonNullable<Awaited<typeof __VLS_setup>>, "attrs" | "emit" | "slots">>, __VLS_exposed?: NonNullable<Awaited<typeof __VLS_setup>>["expose"], __VLS_setup?: Promise<{
+  props: _$vue.PublicProps & __VLS_PrettifyLocal<NotFieldProps<TSchema, TPath>> & (typeof globalThis extends {
     __VLS_PROPS_FALLBACK: infer P;
   } ? P : {});
   expose: (exposed: {}) => void;
   attrs: any;
-  slots: NotFieldSlots<TSchema>;
+  slots: NotFieldSlots<TSchema, TPath>;
   emit: {};
 }>) => _$vue.VNode & {
   __ctx?: Awaited<typeof __VLS_setup>;
@@ -2980,4 +3013,4 @@ declare const __VLS_export: <TSchema extends ObjectSchema>(__VLS_props: NonNulla
 declare const _default: typeof __VLS_export;
 type __VLS_PrettifyLocal<T> = (T extends any ? { [K in keyof T]: T[K] } : { [K in keyof T as K]: T[K] }) & {};
 //#endregion
-export { ArraySchema, DeepPartial, _default as NotField, NotFieldInstance, NotFieldProps, NotFieldSlots, _default$1 as NotForm, NotFormInstance, NotFormProps, NotFormSlots, ObjectSchema, Paths, UseNotFormConfig, ValidationTrigger };
+export { ArraySchema, DeepPartial, _default as NotField, NotFieldEvents, NotFieldInstance, NotFieldProps, NotFieldSlots, _default$1 as NotForm, NotFormInstance, NotFormProps, NotFormSlots, ObjectSchema, Paths, UseNotFormConfig, ValidationTrigger, useNotForm };

package/dist/index.js

@@ -1,4 +1,207 @@
-import { computed, createElementBlock, defineComponent, guardReactiveProps, inject, normalizeProps, openBlock, provide, reactive, renderSlot, unref, useAttrs } from "vue";
+import { computed, createElementBlock, defineComponent, guardReactiveProps, inject, nextTick, normalizeProps, onMounted, openBlock, provide, reactive, ref, renderSlot, toValue, unref, useAttrs } from "vue";
+import { klona } from "klona/full";
+import { dequal } from "dequal";
+import { deepKeys, getProperty, parsePath, setProperty } from "dot-prop";
+//#region src/utils/form-utils.ts
+/**
+* Normalizes a validation path segment into a standard property key.
+* @param segment The path segment to normalize.
+* @returns The normalized key.
+*/
+function normalizeSegment(segment) {
+	if (typeof segment === "object" && segment !== null && "key" in segment) return segment.key;
+	return segment;
+}
+/**
+* Checks if a validation issue path matches a target field path.
+* @param issuePath The path array from the validation issue.
+* @param targetPath The normalized path to compare against.
+* @returns True if the paths are equivalent.
+*/
+function isIssuePathEqual(issuePath, targetPath) {
+	if (!issuePath) return false;
+	if (issuePath.length !== targetPath.length) return false;
+	return issuePath.every((segment, index) => {
+		const normalizedSegment = normalizeSegment(segment);
+		const targetSegment = targetPath[index];
+		if (typeof normalizedSegment === "number" || typeof targetSegment === "number") return Number(normalizedSegment) === Number(targetSegment);
+		return normalizedSegment === targetSegment;
+	});
+}
+//#endregion
+//#region src/composables/use-not-form.ts
+function useNotForm(config) {
+	let initialValues = klona(config.initialValues ?? {});
+	let initialErrors = klona(config.initialErrors ?? []);
+	const validateOn = {
+		onBlur: config.validateOn?.onBlur ?? true,
+		onChange: config.validateOn?.onChange ?? true,
+		onInput: config.validateOn?.onInput ?? true,
+		onMount: config.validateOn?.onMount ?? false,
+		onFocus: config.validateOn?.onFocus ?? false
+	};
+	const values = ref(klona(initialValues));
+	const errors = ref([...initialErrors]);
+	const touchedFields = ref(/* @__PURE__ */ new Set());
+	const dirtyFields = ref(/* @__PURE__ */ new Set());
+	const isSubmitting = ref(false);
+	const isValidating = ref(false);
+	const errorsMap = computed(() => {
+		return errors.value.reduce((accumulator, issue) => {
+			const path = issue.path?.join(".");
+			if (path && !accumulator[path]) accumulator[path] = issue.message;
+			return accumulator;
+		}, {});
+	});
+	const isDirty = computed(() => dirtyFields.value.size > 0);
+	const isTouched = computed(() => touchedFields.value.size > 0);
+	const isValid = computed(() => errors.value.length === 0);
+	const touchField = (path) => {
+		touchedFields.value.add(path);
+	};
+	const unTouchField = (path) => {
+		touchedFields.value.delete(path);
+	};
+	const touchAllFields = () => {
+		deepKeys(values.value).forEach((path) => touchedFields.value.add(path));
+	};
+	const unTouchAllFields = () => {
+		touchedFields.value.clear();
+	};
+	const dirtyField = (path) => {
+		dirtyFields.value.add(path);
+	};
+	const unDirtyField = (path) => {
+		dirtyFields.value.delete(path);
+	};
+	const dirtyAllFields = () => {
+		deepKeys(values.value).forEach((path) => dirtyFields.value.add(path));
+	};
+	const unDirtyAllFields = () => {
+		dirtyFields.value.clear();
+	};
+	const setValue = (path, value) => {
+		setProperty(values.value, path, value);
+		touchField(path);
+		if (dequal(value, getProperty(initialValues, path))) unDirtyField(path);
+		else dirtyField(path);
+		if (validateOn.onChange) validateField(path);
+	};
+	const setValues = (newValues) => {
+		for (const [path, value] of Object.entries(newValues)) setValue(path, value);
+	};
+	const setError = (newIssue) => {
+		const newPath = newIssue.path?.join(".");
+		errors.value = [...errors.value.filter((error) => error.path?.join(".") !== newPath), newIssue];
+	};
+	const setErrors = (newIssues) => {
+		errors.value = [...newIssues];
+	};
+	const clearErrors = () => {
+		errors.value = [];
+	};
+	const getFieldErrors = (path) => {
+		const pathArray = parsePath(path);
+		return errors.value.filter((error) => isIssuePathEqual(error.path, pathArray));
+	};
+	const validate = async () => {
+		isValidating.value = true;
+		try {
+			const result = await toValue(config.schema)["~standard"].validate(values.value);
+			if (result?.issues) {
+				setErrors([...result.issues]);
+				return { issues: result.issues };
+			}
+			clearErrors();
+			return { value: result.value };
+		} finally {
+			isValidating.value = false;
+		}
+	};
+	const validateField = async (path) => {
+		isValidating.value = true;
+		try {
+			const result = await toValue(config.schema)["~standard"].validate(values.value);
+			const pathArray = parsePath(path);
+			errors.value = errors.value.filter((error) => !isIssuePathEqual(error.path, pathArray));
+			if (result?.issues) {
+				const fieldIssues = result.issues.filter((issue) => isIssuePathEqual(issue.path, pathArray));
+				if (fieldIssues.length > 0) {
+					errors.value = [...errors.value, ...fieldIssues];
+					return { issues: fieldIssues };
+				}
+				return { value: getProperty(values.value, path) };
+			}
+			return { value: getProperty(result.value, path) };
+		} finally {
+			isValidating.value = false;
+		}
+	};
+	const submit = async (event) => {
+		isSubmitting.value = true;
+		try {
+			touchAllFields();
+			dirtyAllFields();
+			const result = await validate();
+			if (result?.issues) {
+				event.preventDefault();
+				return;
+			}
+			if (config.onSubmit) {
+				event.preventDefault();
+				await config.onSubmit(result.value);
+			}
+		} catch {
+			event.preventDefault();
+		} finally {
+			isSubmitting.value = false;
+		}
+	};
+	const reset = (newValues, newErrors) => {
+		if (newValues) initialValues = klona(newValues);
+		if (newErrors) initialErrors = klona(newErrors);
+		values.value = klona(initialValues);
+		errors.value = klona(initialErrors);
+		touchedFields.value.clear();
+		dirtyFields.value.clear();
+	};
+	const resolvedInstance = {
+		initialValues,
+		initialErrors,
+		validateOn,
+		values,
+		setValue,
+		setValues,
+		touchedFields,
+		touchField,
+		unTouchField,
+		touchAllFields,
+		unTouchAllFields,
+		isTouched,
+		dirtyFields,
+		dirtyField,
+		unDirtyField,
+		dirtyAllFields,
+		unDirtyAllFields,
+		isDirty,
+		errors,
+		errorsMap,
+		setError,
+		setErrors,
+		clearErrors,
+		getFieldErrors,
+		isValidating,
+		validate,
+		validateField,
+		isValid,
+		isSubmitting,
+		submit,
+		reset
+	};
+	resolvedInstance.instance = resolvedInstance;
+	return resolvedInstance;
+}
+//#endregion
 //#region src/utils/instance-utils.ts
 /** Injection key for the current active form instance */
 const NOT_FORM_INSTANCE_KEY = Symbol("notform:instance");
@@ -17,7 +220,7 @@ function provideNotFormInstance(instance) {
 function useNotFormInstance(explicitInstance) {
 	const injected = inject(NOT_FORM_INSTANCE_KEY);
 	const instance = explicitInstance ?? injected;
-	if (!instance) throw new Error("[NotForm] No form instance found. Add a <NotForm :form=\"...\"> ancestor or pass :form directly.");
+	if (!instance) throw new Error("[NotForm] No form instance found. Add a <NotForm :instance=\"...\"> ancestor or pass :form directly.");
 	return instance;
 }
 //#endregion
@@ -43,24 +246,78 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 	__name: "not-field",
 	props: {
 		path: {
-			type: String,
+			type: null,
 			required: true
 		},
 		form: {
 			type: Object,
 			required: false
+		},
+		validateOn: {
+			type: Object,
+			required: false
 		}
 	},
 	setup(__props) {
 		const props = __props;
 		const formInstance = useNotFormInstance(props.form);
+		const isValidating = ref(false);
 		const path = computed(() => props.path);
-		const errors = formInstance.getFieldErrors(path.value);
-		const validate = () => formInstance.validateField(path.value);
+		const value = computed(() => getProperty(formInstance.values.value, props.path));
+		const errors = computed(() => formInstance.getFieldErrors(path.value));
+		const touch = () => formInstance.touchField(path.value);
+		const unTouch = () => formInstance.unTouchField(path.value);
+		const dirty = () => formInstance.dirtyField(path.value);
+		const unDirty = () => formInstance.unDirtyField(path.value);
+		const validate = async () => {
+			isValidating.value = true;
+			try {
+				return await formInstance.validateField(path.value);
+			} finally {
+				isValidating.value = false;
+			}
+		};
+		const validateOn = computed(() => ({
+			...formInstance.validateOn,
+			...props.validateOn
+		}));
+		const onBlur = () => {
+			touch();
+			if (validateOn.value.onBlur) validate();
+		};
+		const onChange = () => {
+			if (validateOn.value.onChange) validate();
+		};
+		const onInput = () => {
+			if (validateOn.value.onInput) validate();
+		};
+		const onFocus = () => {
+			if (validateOn.value.onFocus) validate();
+		};
 		const fieldInstance = reactive({
-			path: path.value,
+			path,
+			value,
+			isValidating,
+			validate,
 			errors,
-			validate
+			touch,
+			unTouch,
+			dirty,
+			unDirty,
+			events: computed(() => ({
+				onBlur,
+				onInput,
+				onChange,
+				onFocus
+			})),
+			onBlur,
+			onInput,
+			onChange,
+			onFocus
+		});
+		onMounted(async () => {
+			await nextTick();
+			if (validateOn.value.onMount) validate();
 		});
 		return (_ctx, _cache) => {
 			return renderSlot(_ctx.$slots, "default", normalizeProps(guardReactiveProps(fieldInstance)));
@@ -68,4 +325,4 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 	}
 });
 //#endregion
-export { not_field_default as NotField, not_form_default as NotForm };
+export { not_field_default as NotField, not_form_default as NotForm, useNotForm };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "notform",
-  "version": "2.0.0-alpha.2",
+  "version": "2.0.0-alpha.3",
   "type": "module",
   "private": false,
   "description": "Vue Forms Without the Friction",