notform 2.0.0-alpha.4 → 2.0.0-alpha.6

package/README.md

@@ -1,29 +1,16 @@
-# vue-components-starter
+# notform
 
-A starter for creating a Vue component library.
+[![npm version](https://img.shields.io/npm/v/notform.svg?style=flat-square)](https://www.npmjs.com/package/notform)
+[![npm downloads](https://img.shields.io/npm/dm/notform.svg?style=flat-square)](https://www.npmjs.com/package/notform)
+[![license](https://img.shields.io/github/license/favorodera/notform.svg?style=flat-square)](https://github.com/favorodera/notform/blob/main/LICENSE)
+[![Bundle Size](https://img.shields.io/bundlephobia/minzip/notform.svg?style=flat-square)](https://bundlephobia.com/package/notform)
 
-## Development
+**The core engine for "Vue Forms Without the Friction."**
 
-- Install dependencies:
+`notform` is the backbone of the NotForm ecosystem, providing the core composables and state management logic for building robust forms in Vue 3.
 
-```bash
-npm install
-```
+## Documentation
 
-- Run the playground:
+For detailed guides, API reference, and examples, visit:
+**[notform-docs.vercel.app](https://notform-docs.vercel.app/)**
 
-```bash
-npm run playground
-```
-
-- Run the unit tests:
-
-```bash
-npm run test
-```
-
-- Build the library:
-
-```bash
-npm run build
-```

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as _$vue from "vue";
-import { ComputedRef, MaybeRefOrGetter, Raw, Ref } from "vue";
+import { ComputedRef, MaybeRefOrGetter, Raw, Ref, useAttrs } from "vue";
 import { StandardSchemaV1 } from "@standard-schema/spec";
 import { Get, PartialDeep, Paths as Paths$1 } from "type-fest";
 
@@ -45,17 +45,6 @@ type ObjectSchema = StandardSchemaV1 & {
     };
   };
 };
-/**
- * Represents a validation schema for array-based data structures.
- * Complies with the Standard Schema specification.
- */
-type ArraySchema = StandardSchemaV1 & {
-  '~standard': StandardSchemaV1['~standard'] & {
-    types?: {
-      input: Array<any>;
-    };
-  };
-};
 //#endregion
 //#region src/types/use-not-form.d.ts
 /**
@@ -217,11 +206,11 @@ type NotFormSlots = {
 declare function useNotForm<TSchema extends ObjectSchema>(config: UseNotFormConfig<TSchema>): NotFormInstance<TSchema>;
 //#endregion
 //#region src/components/not-form.vue.d.ts
-type __VLS_Slots = NotFormSlots;
-declare const __VLS_base: _$vue.DefineComponent<NotFormProps, {}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<NotFormProps> & Readonly<{}>, {}, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
-declare const __VLS_export$1: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
-declare const _default$1: typeof __VLS_export$1;
-type __VLS_WithSlots<T, S> = T & {
+type __VLS_Slots$1 = NotFormSlots;
+declare const __VLS_base$1: _$vue.DefineComponent<NotFormProps, {}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<NotFormProps> & Readonly<{}>, {}, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$3: __VLS_WithSlots$1<typeof __VLS_base$1, __VLS_Slots$1>;
+declare const _default$2: typeof __VLS_export$3;
+type __VLS_WithSlots$1<T, S> = T & {
   new (): {
     $slots: S;
   };
@@ -316,8 +305,8 @@ type NotFieldSlots<TSchema extends ObjectSchema> = {
 };
 //#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> & (typeof globalThis extends {
+declare const __VLS_export$2: <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<NotFieldProps> & (typeof globalThis extends {
     __VLS_PROPS_FALLBACK: infer P;
   } ? P : {});
   expose: (exposed: {}) => void;
@@ -327,7 +316,181 @@ declare const __VLS_export: <TSchema extends ObjectSchema>(__VLS_props: NonNulla
 }>) => _$vue.VNode & {
   __ctx?: Awaited<typeof __VLS_setup>;
 };
+declare const _default$1: typeof __VLS_export$2;
+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-message.d.ts
+/** Props for the `NotMessage` component. */
+type NotMessageProps = {
+  /** The name/path of the field whose error message should be displayed */path: string; /** HTML Tag `NotMessage` should render as - default is `span`. */
+  as?: string;
+  /**
+   * Explicit form instance override.
+   * Takes priority over the instance provided by a `NotForm` ancestor.
+   * Required when using `NotMessage` outside of a `NotForm` (singleton fields).
+   *
+   * ```vue
+   * <NotMessage :form="form" path="email" />
+   * ```
+   */
+  form?: NotFormInstance<any>;
+};
+/** Everything available inside the `NotMessage` default slot. */
+type NotMessageSlotProps = {
+  /** The first active validation error message for the specified field */message?: string; /** Attributes passed to the `NotMessage` component */
+  attributes?: ReturnType<typeof useAttrs>;
+};
+/** Slots for the `NotMessage` component. */
+type NotMessageSlots = {
+  /** The default slot receives the error message context for custom rendering */default: (props: NotMessageSlotProps) => [];
+};
+//#endregion
+//#region src/components/not-message.vue.d.ts
+type __VLS_Slots = NotMessageSlots;
+declare const __VLS_base: _$vue.DefineComponent<NotMessageProps, {}, {}, {}, {}, _$vue.ComponentOptionsMixin, _$vue.ComponentOptionsMixin, {}, string, _$vue.PublicProps, Readonly<NotMessageProps> & Readonly<{}>, {
+  as: string;
+}, {}, {}, {}, string, _$vue.ComponentProvideOptions, false, {}, any>;
+declare const __VLS_export$1: __VLS_WithSlots<typeof __VLS_base, __VLS_Slots>;
+declare const _default$3: typeof __VLS_export$1;
+type __VLS_WithSlots<T, S> = T & {
+  new (): {
+    $slots: S;
+  };
+};
+//#endregion
+//#region src/types/not-array-field.d.ts
+/** Props for the `NotArrayField` component. */
+type NotArrayFieldProps<TItemSchema extends StandardSchemaV1 = StandardSchemaV1> = {
+  /** Dot-separated path to the array within the form values. */path: string;
+  /**
+   * Schema for a single array item — used purely for type inference.
+   * Enables typed `append`, `prepend`, `insert`, and `update` methods in the slot.
+   *
+   * ```vue
+   * <NotArrayField path="tags" :item-schema="z.string()">
+   *   <!-- append now expects a string -->
+   * </NotArrayField>
+   * ```
+   */
+  itemSchema?: TItemSchema;
+  /**
+   * Explicit form instance override.
+   * Takes priority over the instance provided by a `NotForm` ancestor.
+   * Required when using `NotArrayField` outside of a `NotForm`.
+   */
+  form?: NotFormInstance<any>;
+  /**
+   * Per-field validation trigger overrides applied to the array as a whole.
+   * Merged over the form-wide `validateOn` — only the keys you specify are overridden.
+   */
+  validateOn?: Partial<Record<Extract<ValidationTrigger, 'onMount' | 'onChange'>, boolean>>;
+};
+/**
+ * Represents a single item in the array field.
+ * Use `key` for `v-for` tracking and `path` to pass to a nested `NotField`.
+ *
+ * ```vue
+ * <NotArrayField path="tags" v-slot="{ items }">
+ *   <NotField v-for="item in items" :key="item.key" :path="item.path" v-slot="{ events }">
+ *     <input v-model="form.values.tags[item.index]" v-bind="events" />
+ *   </NotField>
+ * </NotArrayField>
+ * ```
+ */
+type NotArrayFieldItem = {
+  /** Stable key for `v-for` — does not change when items are reordered. */key: string; /** Current index of this item in the array. */
+  index: number; /** Full dot-separated path to this item — pass directly to `NotField`. */
+  path: string;
+};
+/**
+ * Everything available inside the `NotArrayField` default slot.
+ * @template TSchema The form schema type.
+ * @template TItem The inferred type of a single array item.
+ */
+type NotArrayFieldSlotProps<TSchema extends ObjectSchema, TItem = any> = {
+  /** The dot-separated path to this array field. */path: string; /** The array items with stable keys and paths for use with `v-for`. */
+  items: NotArrayFieldItem[]; /** The current length of the array. */
+  length: number; /** All validation issues for this array field from the last validation run. */
+  errors: StandardSchemaV1.Issue[]; /** Whether this array field currently has no validation errors. */
+  isValid: boolean;
+  /**
+   * Whether any item in this array has been touched.
+   * Derived from the form's `touchedFields` set.
+   */
+  isTouched: boolean;
+  /**
+   * Whether any item in this array differs from its initial value.
+   * Derived from the form's `dirtyFields` set.
+   */
+  isDirty: boolean; /** Whether validation is currently running for this array field. */
+  isValidating: boolean;
+  /**
+   * Manually triggers validation for this array field.
+   * Useful when mutations are performed programmatically outside of the normal flow.
+   */
+  validate: () => ReturnType<NotFormInstance<TSchema>['validateField']>;
+  /**
+   * Appends a new item to the end of the array.
+   * @param value The value to append.
+   */
+  append: (value: TItem) => void;
+  /**
+   * Prepends a new item to the beginning of the array.
+   * @param value The value to prepend.
+   */
+  prepend: (value: TItem) => void;
+  /**
+   * Removes the item at the given index.
+   * @param index The index of the item to remove.
+   */
+  remove: (index: number) => void;
+  /**
+   * Inserts a new item at the given index, shifting subsequent items forward.
+   * @param index The index to insert the item at.
+   * @param value The value to insert.
+   */
+  insert: (index: number, value: TItem) => void;
+  /**
+   * Replaces the value at the given index.
+   * @param index The index of the item to replace.
+   * @param value The value to replace with.
+   */
+  update: (index: number, value: TItem) => void;
+  /**
+   * Swaps the positions of two items in the array.
+   * @param indexA The index of the first item.
+   * @param indexB The index of the second item.
+   */
+  swap: (indexA: number, indexB: number) => void;
+  /**
+   * Moves an item from one index to another, shifting items between them.
+   * @param from The current index of the item.
+   * @param to The target index.
+   */
+  move: (from: number, to: number) => void;
+};
+/**
+ * Slots for the `NotArrayField` component.
+ * @template TSchema The form schema type.
+ * @template TItem The inferred type of a single array item.
+ */
+type NotArrayFieldSlots<TSchema extends ObjectSchema, TItem = any> = {
+  /** The default slot receives the full array state and manipulation methods. */default: (props: NotArrayFieldSlotProps<TSchema, TItem>) => [];
+};
+//#endregion
+//#region src/components/not-array-field.vue.d.ts
+declare const __VLS_export: <TSchema extends ObjectSchema, TItemSchema extends StandardSchemaV1 = StandardSchemaV1, TItem = StandardSchemaV1.InferInput<TItemSchema>>(__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<NotArrayFieldProps<TItemSchema>> & (typeof globalThis extends {
+    __VLS_PROPS_FALLBACK: infer P;
+  } ? P : {});
+  expose: (exposed: {}) => void;
+  attrs: any;
+  slots: NotArrayFieldSlots<TSchema, TItem>;
+  emit: {};
+}>) => _$vue.VNode & {
+  __ctx?: Awaited<typeof __VLS_setup>;
+};
 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, NotFieldEvents, NotFieldProps, NotFieldSlotProps, NotFieldSlots, _default$1 as NotForm, NotFormInstance, NotFormProps, NotFormSlots, ObjectSchema, Paths, UseNotFormConfig, ValidationMode, ValidationTrigger, useNotForm };
+export { DeepPartial, _default as NotArrayField, NotArrayFieldItem, NotArrayFieldProps, NotArrayFieldSlotProps, NotArrayFieldSlots, _default$1 as NotField, NotFieldEvents, NotFieldProps, NotFieldSlotProps, NotFieldSlots, _default$2 as NotForm, NotFormInstance, NotFormProps, NotFormSlots, _default$3 as NotMessage, NotMessageProps, NotMessageSlotProps, NotMessageSlots, ObjectSchema, Paths, UseNotFormConfig, ValidationMode, ValidationTrigger, useNotForm };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { computed, createElementBlock, defineComponent, guardReactiveProps, inject, markRaw, nextTick, normalizeProps, onMounted, openBlock, provide, reactive, ref, renderSlot, toValue, unref, useAttrs } from "vue";
+import { computed, createBlock, createCommentVNode, createElementBlock, createTextVNode, defineComponent, guardReactiveProps, inject, markRaw, mergeProps, nextTick, normalizeProps, onMounted, openBlock, provide, reactive, ref, renderSlot, resolveDynamicComponent, toDisplayString, toValue, unref, useAttrs, withCtx } from "vue";
 import { klona } from "klona/full";
 import { dequal } from "dequal";
 import { deepKeys, deleteProperty, getProperty, hasProperty, parsePath, setProperty } from "dot-prop";
@@ -189,12 +189,9 @@ function useNotForm(config) {
 		if (newValues) initialValues = klona(newValues);
 		if (newErrors) initialErrors = klona(newErrors);
 		const freshValues = klona(initialValues);
-		deepKeys(values).forEach((path) => {
-			if (!hasProperty(freshValues, path)) deleteProperty(values, path);
-		});
-		deepKeys(freshValues).forEach((path) => {
-			setProperty(values, path, getProperty(freshValues, path));
-		});
+		const current = values;
+		for (const key of Object.keys(current)) if (!hasProperty(freshValues, key)) deleteProperty(values, key);
+		for (const key of Object.keys(freshValues)) setProperty(values, key, getProperty(freshValues, key));
 		errors.splice(0, errors.length, ...klona(initialErrors));
 		touchedFields.clear();
 		dirtyFields.clear();
@@ -365,4 +362,199 @@ var not_field_default = /* @__PURE__ */ defineComponent({
 	}
 });
 //#endregion
-export { not_field_default as NotField, not_form_default as NotForm, useNotForm };
+//#region src/components/not-message.vue
+var not_message_default = /* @__PURE__ */ defineComponent({
+	inheritAttrs: false,
+	__name: "not-message",
+	props: {
+		path: {
+			type: String,
+			required: true
+		},
+		as: {
+			type: String,
+			required: false,
+			default: "span"
+		},
+		form: {
+			type: null,
+			required: false
+		}
+	},
+	setup(__props) {
+		const attributes = useAttrs();
+		const props = __props;
+		const form = useNotFormInstance(props.form);
+		const message = computed(() => form.errorsMap.value[props.path]);
+		const slotProps = computed(() => ({
+			message: message.value,
+			attributes
+		}));
+		return (_ctx, _cache) => {
+			return renderSlot(_ctx.$slots, "default", normalizeProps(guardReactiveProps(slotProps.value)), () => [message.value ? (openBlock(), createBlock(resolveDynamicComponent(props.as), normalizeProps(mergeProps({ key: 0 }, unref(attributes))), {
+				default: withCtx(() => [createTextVNode(toDisplayString(message.value), 1)]),
+				_: 1
+			}, 16)) : createCommentVNode("v-if", true)]);
+		};
+	}
+});
+//#endregion
+//#region src/components/not-array-field.vue
+var not_array_field_default = /* @__PURE__ */ defineComponent({
+	inheritAttrs: false,
+	__name: "not-array-field",
+	props: {
+		path: {
+			type: String,
+			required: true
+		},
+		itemSchema: {
+			type: null,
+			required: false
+		},
+		form: {
+			type: null,
+			required: false
+		},
+		validateOn: {
+			type: Object,
+			required: false
+		}
+	},
+	setup(__props) {
+		const props = __props;
+		const form = useNotFormInstance(props.form);
+		const validateOn = computed(() => ({
+			onMount: props.validateOn?.onMount ?? form.validateOn.onMount,
+			onChange: props.validateOn?.onChange ?? form.validateOn.onChange
+		}));
+		const isValidating = ref(false);
+		/**
+		* Stable keys per item — survive reorders, removals, and inserts.
+		* Seeded from the length of the initial array so existing items have keys from the start.
+		*/
+		const itemKeys = ref((() => {
+			const initial = getProperty(form.values, props.path);
+			const length = Array.isArray(initial) ? initial.length : 0;
+			return Array.from({ length }, (_, index) => `${props.path}-${index}-${Date.now()}`);
+		})());
+		let keyCounter = itemKeys.value.length;
+		const generateKey = () => `${props.path}-${keyCounter++}-${Date.now()}`;
+		const array = computed(() => {
+			const value = getProperty(form.values, props.path);
+			return Array.isArray(value) ? value : [];
+		});
+		const items = computed(() => array.value.map((_, index) => ({
+			key: itemKeys.value[index] ?? `${props.path}-fallback-${index}`,
+			index,
+			path: `${props.path}.${index}`
+		})));
+		const errors = computed(() => form.getFieldErrors(props.path));
+		const isValid = computed(() => errors.value.length === 0);
+		/**
+		* Derived from the form's touchedFields set.
+		* True if the array path itself or any of its item paths have been touched.
+		*/
+		const isTouched = computed(() => form.touchedFields.has(props.path) || [...form.touchedFields].some((path) => path.startsWith(`${props.path}.`)));
+		/**
+		* Derived from the form's dirtyFields set.
+		* True if the array path itself or any of its item paths are dirty.
+		*/
+		const isDirty = computed(() => form.dirtyFields.has(props.path) || [...form.dirtyFields].some((path) => path.startsWith(`${props.path}.`)));
+		const validate = async () => {
+			isValidating.value = true;
+			try {
+				return await form.validateField(props.path);
+			} finally {
+				isValidating.value = false;
+			}
+		};
+		/**
+		* Re-aligns itemKeys with the current array length.
+		* Called at the start of every mutation so keys stay consistent
+		* after external changes (e.g. form.reset()).
+		*/
+		const syncKeys = () => {
+			const arrayLength = array.value.length;
+			if (itemKeys.value.length > arrayLength) itemKeys.value.length = arrayLength;
+			else while (itemKeys.value.length < arrayLength) itemKeys.value.push(generateKey());
+		};
+		/**
+		* Applies an update to a copy of the current array, writes it back to the form values,
+		* and marks the array path as touched. Dirty state is derived from the form's Sets
+		* automatically via the computed above so no explicit dirty call is needed here.
+		*/
+		const mutate = (updater) => {
+			syncKeys();
+			const current = [...array.value];
+			updater(current);
+			setProperty(form.values, props.path, current);
+			form.touchField(props.path);
+			if (dequal(current, getProperty(form.initialValues, props.path))) form.dirtyFields.delete(props.path);
+			else form.dirtyField(props.path);
+			if (validateOn.value.onChange) validate();
+		};
+		const append = (value) => {
+			itemKeys.value.push(generateKey());
+			mutate((current) => current.push(value));
+		};
+		const prepend = (value) => {
+			itemKeys.value.unshift(generateKey());
+			mutate((current) => current.unshift(value));
+		};
+		const remove = (index) => {
+			mutate((current) => current.splice(index, 1));
+			itemKeys.value.splice(index, 1);
+		};
+		const insert = (index, value) => {
+			itemKeys.value.splice(index, 0, generateKey());
+			mutate((current) => current.splice(index, 0, value));
+		};
+		const update = (index, value) => {
+			mutate((current) => {
+				current[index] = value;
+			});
+		};
+		const swap = (indexA, indexB) => {
+			mutate((current) => {
+				[current[indexA], current[indexB]] = [current[indexB], current[indexA]];
+			});
+			[itemKeys.value[indexA], itemKeys.value[indexB]] = [itemKeys.value[indexB], itemKeys.value[indexA]];
+		};
+		const move = (from, to) => {
+			mutate((current) => {
+				const [item] = current.splice(from, 1);
+				current.splice(to, 0, item);
+			});
+			const [key] = itemKeys.value.splice(from, 1);
+			itemKeys.value.splice(to, 0, key);
+		};
+		onMounted(async () => {
+			await nextTick();
+			if (validateOn.value.onMount) validate();
+		});
+		const slotProps = computed(() => ({
+			path: props.path,
+			items: items.value,
+			length: array.value.length,
+			errors: errors.value,
+			isValid: isValid.value,
+			isTouched: isTouched.value,
+			isDirty: isDirty.value,
+			isValidating: isValidating.value,
+			validate,
+			append,
+			prepend,
+			remove,
+			insert,
+			update,
+			swap,
+			move
+		}));
+		return (_ctx, _cache) => {
+			return renderSlot(_ctx.$slots, "default", normalizeProps(guardReactiveProps(slotProps.value)));
+		};
+	}
+});
+//#endregion
+export { not_array_field_default as NotArrayField, not_field_default as NotField, not_form_default as NotForm, not_message_default as NotMessage, useNotForm };

package/package.json

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