@vizejs/composable 0.426.3 → 0.427.0

package/dist/use-form-field-props.mjs

@@ -0,0 +1,164 @@
+import { computed, toValue } from "vue";
+//#region src/use-form-field-props.ts
+/** Derive the default control id for a path. */
+function formFieldId(path, idPrefix = "field") {
+	const segment = path.replace(/[^A-Za-z0-9_-]+/g, "-");
+	return segment.length === 0 ? idPrefix : `${idPrefix}-${segment}`;
+}
+function readFlag(source, fallback) {
+	const value = source === void 0 ? void 0 : toValue(source);
+	return typeof value === "boolean" ? value : fallback;
+}
+/**
+* Bind one `useForm` field to accessible field markup and any `v-model` control.
+*
+* Returns ids, ARIA relations (`fieldProps`), label/description/error props,
+* and `modelProps` whose shapes match `@vizejs/ui`'s Field contracts
+* structurally, so the bridge lives here without a runtime dependency on the
+* UI package. Ids are derived from the path, so server and client agree
+* without any instance-local id sequence.
+*
+* Server rendering: pure derived state, no host access. Cleanup: none needed
+* beyond the owning form.
+*
+* @example
+* ```vue
+* <script setup lang="ts">
+* const form = useForm({ initialValues: { address: { city: "" } } });
+* const city = useFormFieldProps(form, "address.city");
+* <\/script>
+* <template>
+*   <label v-bind="city.labelProps.value">City</label>
+*   <TextInput v-bind="city.controlProps.value" />
+*   <p v-if="city.invalid.value" v-bind="city.errorMessageProps.value">{{ city.errorMessage.value }}</p>
+* </template>
+* ```
+*
+* @param form Controls returned by `useForm`.
+* @param path Typed dotted path.
+* @param options Id, relation, and error-visibility options.
+* @default options {}
+* @returns Typed bindings for the field.
+*/
+function useFormFieldProps(form, path, options = {}) {
+	const field = form.field(path);
+	const showErrors = options.showErrors ?? "touched";
+	const id = computed(() => {
+		const explicit = options.id === void 0 ? void 0 : toValue(options.id);
+		return typeof explicit === "string" && explicit.length > 0 ? explicit : formFieldId(path, options.idPrefix);
+	});
+	const invalid = computed(() => {
+		if (field.errors.value.length === 0) return false;
+		if (showErrors === "always") return true;
+		const submitted = form.submitCount.value > 0;
+		return showErrors === "submitted" ? submitted : submitted || field.touched.value;
+	});
+	const errorMessage = computed(() => invalid.value ? field.error.value : void 0);
+	const fieldProps = computed(() => {
+		const describedBy = [];
+		if (readFlag(options.hasDescription, false)) describedBy.push(`${id.value}-description`);
+		const referencesError = invalid.value && readFlag(options.hasErrorMessage, true);
+		if (referencesError) describedBy.push(`${id.value}-error`);
+		return {
+			id: id.value,
+			"aria-labelledby": `${id.value}-label`,
+			"aria-describedby": describedBy.length === 0 ? void 0 : describedBy.join(" "),
+			"aria-errormessage": referencesError ? `${id.value}-error` : void 0,
+			"aria-invalid": invalid.value ? "true" : void 0
+		};
+	});
+	const modelProps = computed(() => ({
+		modelValue: field.value.value,
+		"onUpdate:modelValue": (value) => {
+			field.value.value = value;
+		},
+		onBlur: field.onBlur
+	}));
+	return {
+		field,
+		id,
+		invalid,
+		errorMessage,
+		fieldProps,
+		labelProps: computed(() => ({
+			id: `${id.value}-label`,
+			for: id.value
+		})),
+		descriptionProps: computed(() => ({ id: `${id.value}-description` })),
+		errorMessageProps: computed(() => ({ id: `${id.value}-error` })),
+		modelProps,
+		controlProps: computed(() => ({
+			...fieldProps.value,
+			...modelProps.value
+		}))
+	};
+}
+/**
+* Convert form errors into ui `FormFieldError` entries (`{ name, message, path }`),
+* one per message, so `@vizejs/ui` `Field` components match them by `name`.
+*
+* @param errors `form.errors.value`.
+* @returns Entries in record order; the form-level `""` path has an empty `path`.
+*/
+function toFormFieldErrors(errors) {
+	return Object.entries(errors).flatMap(([name, messages]) => {
+		const path = name.length === 0 ? [] : name.split(".").map((segment) => /^\d+$/.test(segment) ? Number(segment) : segment);
+		return messages.map((message) => ({
+			name,
+			message,
+			path
+		}));
+	});
+}
+/**
+* Derive `@vizejs/ui` `ErrorSummary` fields from a `useForm` instance.
+*
+* Each invalid path becomes `{ id, message, label? }` pointing at the control
+* id that {@link useFormFieldProps} assigns, in `order` then error order.
+*
+* Server rendering: pure derived state. Cleanup: none.
+*
+* @example
+* ```vue
+* <ErrorSummary :fields="summary" heading="Fix these fields" />
+* ```
+*
+* @param form Controls returned by `useForm`.
+* @param options Id, label, ordering, and visibility options.
+* @default options {}
+* @returns Summary fields, empty until errors should be shown.
+*/
+function useFormErrorSummaryFields(form, options = {}) {
+	const order = options.order ?? [];
+	const ids = options.ids ?? {};
+	const labels = options.labels ?? {};
+	return computed(() => {
+		if ((options.showErrors ?? "submitted") === "submitted" && form.submitCount.value === 0) return [];
+		const record = form.errors.value;
+		const paths = Object.keys(record).filter((path) => (record[path]?.length ?? 0) > 0);
+		const rank = (path) => {
+			const index = order.indexOf(path);
+			return index === -1 ? order.length : index;
+		};
+		return paths.map((path, index) => ({
+			path,
+			index
+		})).sort((left, right) => rank(left.path) - rank(right.path) || left.index - right.index).flatMap(({ path }) => {
+			const message = record[path]?.[0];
+			if (message === void 0) return [];
+			if (path.length === 0 && options.rootId === void 0) return [];
+			const id = path.length === 0 ? options.rootId ?? "" : ids[path] ?? formFieldId(path, options.idPrefix);
+			const label = labels[path];
+			return [label === void 0 ? {
+				id,
+				message
+			} : {
+				id,
+				message,
+				label
+			}];
+		});
+	});
+}
+//#endregion
+export { formFieldId, toFormFieldErrors, useFormErrorSummaryFields, useFormFieldProps };

package/dist/use-form.d.mts

@@ -0,0 +1,324 @@
+import { d as StandardSchemaV1 } from "./standard-schema-DmNgFVK5.mjs";
+import { ComputedRef, Ref, ShallowRef, WritableComputedRef } from "vue";
+
+//#region src/use-form.d.ts
+/** Values treated as leaves: paths never descend into them. */
+type FormLeaf = string | number | bigint | boolean | symbol | null | undefined | Date | RegExp | Blob | Map<unknown, unknown> | Set<unknown> | ((...arguments_: never[]) => unknown);
+type Decrement = [never, 0, 1, 2, 3, 4, 5, 6, 7, 8];
+/**
+ * Every dotted path into `Values`, as template-literal keys.
+ *
+ * Objects contribute their string keys, arrays and tuples contribute
+ * `${number}` segments, and {@link FormLeaf} values end a path. Recursion
+ * is bounded at eight levels to keep type checking fast.
+ */
+type FormPath<Values, Depth extends number = 8> = [Depth] extends [never] ? never : Values extends FormLeaf ? never : Values extends readonly (infer Item)[] ? `${number}` | `${number}.${FormPath<Item, Decrement[Depth]>}` : { [Key in keyof Values & string]: Key | (FormPath<Values[Key], Decrement[Depth]> extends infer Rest extends string ? [Rest] extends [never] ? never : `${Key}.${Rest}` : never) }[keyof Values & string];
+/** Value type found at `Path` inside `Values`. */
+type FormPathValue<Values, Path extends string> = Path extends `${infer Head}.${infer Rest}` ? Values extends readonly (infer Item)[] ? Head extends `${number}` ? FormPathValue<Item, Rest> : never : Head extends keyof Values ? FormPathValue<Values[Head], Rest> : never : Values extends readonly (infer Item)[] ? Path extends `${number}` ? Item : never : Path extends keyof Values ? Values[Path] : never;
+/** Paths whose value is an array (usable with {@link FormControls.fieldArray}). */
+type FormArrayPath<Values> = { [Path in FormPath<Values>]: FormPathValue<Values, Path> extends readonly unknown[] ? Path : never }[FormPath<Values>];
+/** Item type of the array at `Path`. */
+type FormArrayItem<Values, Path extends string> = FormPathValue<Values, Path> extends readonly (infer Item)[] ? Item : never;
+/**
+ * Error messages keyed by dotted path; `""` holds form-level errors.
+ *
+ * Known paths are typed for autocompletion; the string index signature
+ * stays because schemas and servers may report paths that are not fields.
+ */
+type FormErrors<Values> = { readonly [Path in FormPath<Values> | ""]?: readonly string[] } & {
+  readonly [path: string]: readonly string[] | undefined;
+};
+/** Current errors as recorded: messages keyed by dotted path (`""` = form level). */
+type FormErrorRecord = Readonly<Record<string, readonly string[]>>;
+/** Result of a validator: messages, one message, or nothing when valid. */
+type ValidatorResult = string | readonly string[] | null | undefined | void;
+/** Context passed to field validators. */
+interface FieldValidatorContext<Values> {
+  /** Current form values (`undefined` for standalone fields). */
+  readonly values: Values;
+  /** Dotted path of the validated field. */
+  readonly path: string;
+  /** Aborted when a newer validation supersedes this one. */
+  readonly signal: AbortSignal;
+}
+/** Plain validator for one field value. */
+type FieldValidator<Value, Values = undefined> = (value: Value, context: FieldValidatorContext<Values>) => ValidatorResult | Promise<ValidatorResult>;
+/** Plain validator for the whole form, returning errors keyed by path. */
+type FormValidator<Values> = (values: Values, context: {
+  readonly signal: AbortSignal;
+}) => FormErrors<Values> | undefined | void | Promise<FormErrors<Values> | undefined | void>;
+/** Per-field validators keyed by path. */
+type FormFieldValidators<Values> = { readonly [Path in FormPath<Values>]?: FieldValidator<FormPathValue<Values, Path>, Values> };
+/** When validation runs automatically. */
+type FormValidationTrigger = "change" | "blur" | "submit";
+/** Discriminated outcome of {@link FormControls.validate} and submission. */
+type FormResult<Output> = {
+  /** Every validator passed. */readonly status: "valid"; /** Schema output, or the values when no schema is configured. */
+  readonly value: Output;
+} | {
+  /** At least one validator failed. */readonly status: "invalid"; /** Errors keyed by path. */
+  readonly errors: FormErrorRecord;
+} | {
+  /** A newer validation started before this one finished. */readonly status: "superseded";
+};
+/** Options for {@link useForm}. */
+interface UseFormOptions<Values extends object, Output> {
+  /** Initial values, or a factory producing fresh initial values. */
+  readonly initialValues: Values | (() => Values);
+  /**
+   * Standard Schema v1 validator for the whole form. Its output becomes the
+   * submitted value.
+   *
+   * @default undefined
+   */
+  readonly schema?: StandardSchemaV1<NoInfer<Values>, Output>;
+  /**
+   * Plain whole-form validator.
+   *
+   * @default undefined
+   */
+  readonly validate?: NoInfer<FormValidator<Values>>;
+  /**
+   * Plain per-field validators keyed by path.
+   *
+   * @default {}
+   */
+  readonly validators?: NoInfer<FormFieldValidators<Values>>;
+  /**
+   * When fields validate before the first submit.
+   *
+   * @default "submit"
+   */
+  readonly validateOn?: FormValidationTrigger;
+  /**
+   * When fields re-validate after the first submit.
+   *
+   * @default "change"
+   */
+  readonly revalidateOn?: FormValidationTrigger;
+  /**
+   * Default submit handler for {@link FormControls.submit}.
+   *
+   * @default undefined
+   */
+  readonly onSubmit?: (value: Output, context: {
+    readonly signal: AbortSignal;
+  }) => unknown;
+}
+/** Options for {@link FormControls.setValue}. */
+interface SetFieldValueOptions {
+  /**
+   * Mark the field touched.
+   *
+   * @default false
+   */
+  readonly touch?: boolean;
+  /**
+   * Validate the field after setting it.
+   *
+   * @default true while the active trigger is "change"
+   */
+  readonly validate?: boolean;
+}
+/** Reactive controls for one field, returned by {@link FormControls.field}. */
+interface FormFieldControls<Value, Path extends string = string> {
+  /** Dotted path of the field (also a suitable `name` attribute). */
+  readonly path: Path;
+  /** Writable value bound to the form state (use with `v-model`). */
+  readonly value: WritableComputedRef<Value>;
+  /** Current error messages. */
+  readonly errors: ComputedRef<readonly string[]>;
+  /** First error message. */
+  readonly error: ComputedRef<string | undefined>;
+  /** Whether the value differs from its initial value. */
+  readonly dirty: ComputedRef<boolean>;
+  /** Whether the field was blurred or touched programmatically. */
+  readonly touched: ComputedRef<boolean>;
+  /** Whether a validation of this field is pending. */
+  readonly validating: ComputedRef<boolean>;
+  /** Mark the field touched (wire to `blur`); validates when configured. */
+  readonly onBlur: () => void;
+  /**
+   * Validate this field.
+   *
+   * @returns Whether the field is valid (`false` also when superseded).
+   */
+  readonly validate: () => Promise<boolean>;
+  /** Restore the initial value and clear errors and touched state. */
+  readonly reset: () => void;
+}
+/** One entry of a field array, with a stable key for `v-for`. */
+interface FormArrayEntry<Item, Path extends string = string> {
+  /** Stable key that follows the item through moves. */
+  readonly key: number;
+  /** Current index. */
+  readonly index: number;
+  /** Dotted path of the item, e.g. `items.2`. */
+  readonly path: `${Path}.${number}`;
+  /** Current item value. */
+  readonly value: Item;
+}
+/** Typed operations on an array field, returned by {@link FormControls.fieldArray}. */
+interface FormFieldArrayControls<Item, Path extends string = string> {
+  /** Entries with stable keys. */
+  readonly entries: ComputedRef<readonly FormArrayEntry<Item, Path>[]>;
+  /** Append items. */
+  readonly append: (...items: Item[]) => void;
+  /** Prepend items. */
+  readonly prepend: (...items: Item[]) => void;
+  /** Insert an item at `index`. */
+  readonly insert: (index: number, item: Item) => void;
+  /** Remove the item at `index`, shifting errors and touched state. */
+  readonly remove: (index: number) => void;
+  /** Move an item from one index to another, carrying its state along. */
+  readonly move: (from: number, to: number) => void;
+  /** Swap two items. */
+  readonly swap: (first: number, second: number) => void;
+  /** Replace all items and reset their state. */
+  readonly replace: (items: readonly Item[]) => void;
+}
+/** Reactive state and actions returned by {@link useForm}. */
+interface FormControls<Values extends object, Output> {
+  /** Current values. Mutations are tracked (dirty state derives from them). */
+  readonly values: Ref<Values>;
+  /** Current errors keyed by path; `""` holds form-level errors. */
+  readonly errors: Readonly<ShallowRef<FormErrorRecord>>;
+  /** Whether no errors are currently recorded. */
+  readonly valid: ComputedRef<boolean>;
+  /** Whether any value differs from its initial value. */
+  readonly dirty: ComputedRef<boolean>;
+  /** Whether any validation is pending. */
+  readonly validating: ComputedRef<boolean>;
+  /** Whether a submission is in progress. */
+  readonly submitting: Readonly<Ref<boolean>>;
+  /** Number of submit attempts. */
+  readonly submitCount: Readonly<Ref<number>>;
+  /**
+   * Typed controls for one field.
+   *
+   * @param path Dotted path.
+   * @returns Field controls whose value type follows the path.
+   */
+  readonly field: <Path extends FormPath<Values>>(path: Path) => FormFieldControls<FormPathValue<Values, Path>, Path>;
+  /**
+   * Typed operations for an array field.
+   *
+   * @param path Dotted path of an array.
+   * @returns Field array controls.
+   */
+  readonly fieldArray: <Path extends FormArrayPath<Values>>(path: Path) => FormFieldArrayControls<FormArrayItem<Values, Path>, Path>;
+  /**
+   * Read the value at a path.
+   *
+   * @param path Dotted path.
+   * @returns The value.
+   */
+  readonly getValue: <Path extends FormPath<Values>>(path: Path) => FormPathValue<Values, Path>;
+  /**
+   * Write the value at a path.
+   *
+   * @param path Dotted path.
+   * @param value New value.
+   * @param options Touch and validation behavior.
+   */
+  readonly setValue: <Path extends FormPath<Values>>(path: Path, value: FormPathValue<Values, Path>, options?: SetFieldValueOptions) => void;
+  /**
+   * Replace (or shallowly merge) the values without touching initial values.
+   *
+   * @param values New values.
+   * @param options `merge: true` shallowly merges top-level keys.
+   */
+  readonly setValues: (values: Partial<Values>, options?: {
+    readonly merge?: boolean;
+  }) => void;
+  /**
+   * Whether a field was touched.
+   *
+   * @param path Dotted path.
+   * @returns Touched state.
+   */
+  readonly isTouched: (path: FormPath<Values>) => boolean;
+  /**
+   * Replace errors (for example with server-side errors).
+   *
+   * @param errors Errors keyed by path.
+   */
+  readonly setErrors: (errors: FormErrors<Values>) => void;
+  /**
+   * Clear errors of one path, or all errors.
+   *
+   * @param path Dotted path; omit to clear everything.
+   */
+  readonly clearErrors: (path?: FormPath<Values> | "") => void;
+  /**
+   * Run every validator, aborting any older validation still in flight.
+   *
+   * @returns The discriminated result; never rejects on validation failure.
+   */
+  readonly validate: () => Promise<FormResult<Output>>;
+  /**
+   * Validate and, when valid, call `handler` (or the `onSubmit` option).
+   * A newer submit aborts an older one's pending validation.
+   *
+   * @param handler Submit handler overriding `onSubmit`.
+   * @returns The validation result.
+   */
+  readonly submit: (handler?: (value: Output, context: {
+    readonly signal: AbortSignal;
+  }) => unknown) => Promise<FormResult<Output>>;
+  /**
+   * Create a `submit` event listener that prevents the native submission.
+   *
+   * @param handler Submit handler overriding `onSubmit`.
+   * @returns Event listener for `<form @submit>`.
+   */
+  readonly handleSubmit: (handler?: (value: Output, context: {
+    readonly signal: AbortSignal;
+  }) => unknown) => (event?: Event) => Promise<FormResult<Output>>;
+  /**
+   * Restore initial values (or install new ones) and clear all state.
+   *
+   * @param values New initial values.
+   */
+  readonly reset: (values?: Values) => void;
+}
+/**
+ * Fully typed form state with validation, field arrays, and submission.
+ *
+ * The value type is inferred from `initialValues`; every path is a
+ * template-literal key, so `field("address.city")` returns controls whose
+ * `value` is typed as the city's type and misspelled paths do not compile.
+ * Validation combines a Standard Schema v1 validator (Zod, Valibot, ArkType,
+ * … via the `~standard` protocol), a whole-form validator, and per-field
+ * validators; all may be asynchronous. A newer validation aborts older ones
+ * through their `signal` and their results are discarded, so a slow check
+ * can never overwrite fresher errors.
+ *
+ * This composable owns the *values*. `@vizejs/ui/form` owns accessible
+ * error presentation (error summaries, focus management, native constraint
+ * validation); feed {@link FormControls.errors} into it to render them.
+ *
+ * Server rendering: pure state, no host access; validation never runs
+ * automatically during setup, so server and client render the same markup.
+ * Pending validations are aborted when the owning scope stops.
+ *
+ * @example
+ * ```ts
+ * const form = useForm({
+ *   initialValues: { name: "", address: { city: "" }, tags: [] as string[] },
+ *   validators: { name: (name) => (name ? undefined : "Required") },
+ *   onSubmit: (values) => api.save(values),
+ * });
+ * const city = form.field("address.city"); // city.value: Ref<string>
+ * const tags = form.fieldArray("tags");
+ * tags.append("vue");
+ * ```
+ *
+ * @typeParam Values Form values, inferred from `initialValues`.
+ * @typeParam Output Submitted value, inferred from `schema` (defaults to `Values`).
+ * @param options Initial values, validators, triggers, and submit handler.
+ * @returns Form state and actions.
+ */
+declare function useForm<Values extends object, Output = Values>(options: UseFormOptions<Values, Output>): FormControls<Values, Output>;
+//#endregion
+export { FieldValidator, FieldValidatorContext, FormArrayEntry, FormArrayItem, FormArrayPath, FormControls, FormErrorRecord, FormErrors, FormFieldArrayControls, FormFieldControls, FormFieldValidators, FormLeaf, FormPath, FormPathValue, FormResult, FormValidationTrigger, FormValidator, SetFieldValueOptions, UseFormOptions, ValidatorResult, useForm };