@datum-cloud/datum-ui 0.5.0 → 0.6.0-alpha.3e04d8c

package/dist/form/adapters/conform/index.mjs

@@ -0,0 +1,327 @@
+import { t as FormAdapterProvider } from "../../../adapter-context-rWveHhDd.mjs";
+import { t as getFieldConstraints } from "../../../get-field-constraints-BicgDkfH.mjs";
+import * as React$1 from "react";
+import { jsx } from "react/jsx-runtime";
+import { FormProvider, getFormProps, getInputProps, useForm, useFormMetadata, useInputControl } from "@conform-to/react";
+import { isDirty, useFormData } from "@conform-to/react/future";
+import { getZodConstraint, parseWithZod } from "@conform-to/zod/v4";
+//#region src/components/features/form/adapters/conform/conform-adapter.tsx
+/**
+* Shared context for the touched fields set.
+* Created in useConformCreateForm and consumed by useConformField.
+*/
+const TouchedFieldsContext = React$1.createContext({ current: /* @__PURE__ */ new Set() });
+/**
+* Resolve a Conform field metadata object by dot-notation path.
+*
+* Handles:
+* - Top-level fields: `"email"` -> `fields.email`
+* - Nested objects: `"address.city"` -> `fields.address.getFieldset().city`
+* - Array items: `"items.0.name"` -> `fields.items.getFieldList()[0].getFieldset().name`
+*/
+function resolveConformField(fields, name) {
+	const parts = name.split(".");
+	let current = fields;
+	for (let i = 0; i < parts.length; i++) {
+		const part = parts[i];
+		if (!current) break;
+		if (/^\d+$/.test(part)) {
+			const fieldList = current.getFieldList?.();
+			if (fieldList) {
+				const item = fieldList[Number.parseInt(part, 10)];
+				if (i < parts.length - 1 && item?.getFieldset) current = item.getFieldset();
+				else current = item;
+			} else current = current[part];
+		} else if (current[part] !== void 0) current = current[part];
+		else if (typeof current.getFieldset === "function") current = current.getFieldset()[part];
+		else current = void 0;
+	}
+	return current;
+}
+function convertFromString(value) {
+	if (value === void 0) return void 0;
+	if (Array.isArray(value)) return value[0];
+	if (value === "on") return true;
+	if (value.startsWith("[") && value.endsWith("]")) try {
+		return JSON.parse(value);
+	} catch {
+		return value;
+	}
+	return value;
+}
+function convertToString(value) {
+	if (typeof value === "boolean") return value ? "on" : "";
+	if (value === null || value === void 0) return "";
+	if (Array.isArray(value)) return JSON.stringify(value);
+	return String(value);
+}
+/** Create a Conform form instance and normalize it to the adapter interface. */
+function useConformCreateForm(props) {
+	const { schema, defaultValues, mode, id, onSubmit, formRef } = props;
+	const [form, fields] = useForm({
+		id,
+		defaultValue: defaultValues,
+		constraint: getZodConstraint(schema),
+		shouldValidate: {
+			onBlur: "onBlur",
+			onChange: "onInput",
+			onSubmit: "onSubmit"
+		}[mode],
+		shouldRevalidate: mode !== "onSubmit" ? "onInput" : void 0,
+		onValidate: ({ formData }) => parseWithZod(formData, { schema }),
+		onSubmit: onSubmit ? (event, context) => {
+			event.preventDefault();
+			const submission = context.submission;
+			if (submission?.status === "success") onSubmit(submission.value);
+		} : void 0
+	});
+	const constraints = React$1.useMemo(() => getFieldConstraints(schema), [schema]);
+	const formIsDirty = useFormData(formRef, (formData) => isDirty(formData, { defaultValue: defaultValues }) ?? false) ?? false;
+	const dirtyFields = useFormData(formRef, (formData) => {
+		const result = {};
+		const defaults = defaultValues ?? {};
+		for (const key of Object.keys(defaults)) {
+			const current = formData.get(key);
+			const defaultVal = defaults[key];
+			result[key] = current !== (defaultVal === true ? "on" : defaultVal === false || defaultVal === null || defaultVal === void 0 ? "" : String(defaultVal));
+		}
+		for (const key of formData.keys()) if (!(key in result) && !key.startsWith("$")) {
+			const current = formData.get(key);
+			result[key] = current !== "" && current !== null;
+		}
+		const dirty = {};
+		for (const [key, value] of Object.entries(result)) if (value) dirty[key] = true;
+		return dirty;
+	}) ?? {};
+	const isValid = useFormData(formRef, (formData) => {
+		return parseWithZod(formData, { schema })?.status === "success";
+	}) ?? false;
+	const touchedFieldsRef = React$1.useRef(/* @__PURE__ */ new Set());
+	const [touchedFields, setTouchedFields] = React$1.useState({});
+	React$1.useEffect(() => {
+		const formEl = formRef?.current;
+		if (!formEl) return;
+		const handleFocusOut = (event) => {
+			const target = event.target;
+			if (target instanceof HTMLInputElement || target instanceof HTMLSelectElement || target instanceof HTMLTextAreaElement) {
+				const name = target.name;
+				if (name && !touchedFieldsRef.current.has(name)) {
+					touchedFieldsRef.current.add(name);
+					setTouchedFields((prev) => ({
+						...prev,
+						[name]: true
+					}));
+				}
+			}
+		};
+		formEl.addEventListener("focusout", handleFocusOut);
+		return () => formEl.removeEventListener("focusout", handleFocusOut);
+	}, [formRef]);
+	const formState = React$1.useMemo(() => ({
+		isDirty: formIsDirty,
+		isValid,
+		isSubmitted: false,
+		submitCount: 0,
+		dirtyFields,
+		touchedFields
+	}), [
+		formIsDirty,
+		isValid,
+		dirtyFields,
+		touchedFields
+	]);
+	const normalizedFields = React$1.useMemo(() => {
+		const result = {};
+		for (const [key, fieldMeta] of Object.entries(fields)) result[key] = {
+			id: fieldMeta.id ?? `${id ?? form.id}-${key}`,
+			errors: fieldMeta.errors ?? [],
+			required: constraints[key]?.required ?? false,
+			isDirty: dirtyFields[key] ?? false,
+			isTouched: touchedFields[key] ?? false
+		};
+		return result;
+	}, [
+		fields,
+		id,
+		form.id,
+		constraints,
+		dirtyFields,
+		touchedFields
+	]);
+	const conformFormProps = React$1.useMemo(() => getFormProps(form), [form]);
+	return React$1.useMemo(() => ({
+		id: form.id,
+		fields: normalizedFields,
+		formProps: conformFormProps,
+		formState,
+		submit: () => formRef?.current?.requestSubmit(),
+		reset: () => form.reset(),
+		getValues: () => {
+			if (!formRef?.current) return {};
+			const formData = new FormData(formRef.current);
+			const values = {};
+			for (const [key, value] of formData.entries()) values[key] = value;
+			return values;
+		},
+		raw: {
+			form,
+			fields,
+			touchedFieldsRef
+		}
+	}), [
+		form,
+		fields,
+		normalizedFields,
+		conformFormProps,
+		formState,
+		formRef
+	]);
+}
+/** Resolve a field by dot-notation path and return its normalized state. */
+function useConformField(name) {
+	const fieldMeta = resolveConformField(useFormMetadata().getFieldset(), name);
+	const touchedFieldsRef = React$1.use(TouchedFieldsContext);
+	const control = useInputControl(fieldMeta ?? {
+		name,
+		key: void 0,
+		id: name
+	});
+	if (!fieldMeta) throw new Error(`[Conform Adapter] Field "${name}" not found. Make sure the field name matches your schema.`);
+	const currentValue = convertFromString(control.value);
+	const defaultValue = convertFromString(fieldMeta.initialValue);
+	const fieldIsDirty = currentValue !== (defaultValue === void 0 ? "" : defaultValue);
+	const fieldIsTouched = touchedFieldsRef.current.has(name);
+	return React$1.useMemo(() => ({
+		name: fieldMeta.name,
+		id: fieldMeta.id,
+		errors: fieldMeta.errors ?? [],
+		required: fieldMeta.required ?? false,
+		isDirty: fieldIsDirty,
+		isTouched: fieldIsTouched,
+		value: currentValue,
+		change: (value) => control.change(convertToString(value)),
+		blur: () => control.blur(),
+		focus: () => control.focus(),
+		inputProps: getInputProps(fieldMeta, { type: "text" })
+	}), [
+		fieldMeta,
+		control,
+		currentValue,
+		fieldIsDirty,
+		fieldIsTouched
+	]);
+}
+/** Watch a single field's value reactively. */
+function useConformWatch(name) {
+	const fieldMeta = resolveConformField(useFormMetadata().getFieldset(), name);
+	if (!fieldMeta) return void 0;
+	return convertFromString(fieldMeta.value);
+}
+/** Watch multiple fields' values reactively. */
+function useConformWatchAll(names) {
+	const allFields = useFormMetadata().getFieldset();
+	const namesKey = names.join(",");
+	return React$1.useMemo(() => {
+		const result = {};
+		for (const name of names) {
+			const fieldMeta = resolveConformField(allFields, name);
+			if (fieldMeta) result[name] = convertFromString(fieldMeta.value);
+		}
+		return result;
+	}, [allFields, namesKey]);
+}
+/** Get field array helpers for a given array field name. */
+function useConformFieldArray(name) {
+	const formMeta = useFormMetadata();
+	const arrayField = resolveConformField(formMeta.getFieldset(), name);
+	const items = React$1.useMemo(() => {
+		if (!arrayField?.getFieldList) return [];
+		return arrayField.getFieldList().map((item, index) => ({
+			id: item.id ?? `${name}-${index}`,
+			key: item.key ?? `${name}-${index}`,
+			name: `${name}[${index}]`
+		}));
+	}, [arrayField, name]);
+	const arrayFieldName = arrayField?.name;
+	return {
+		items,
+		append: React$1.useCallback((defaultValue) => {
+			if (!arrayFieldName) return;
+			formMeta.insert({
+				name: arrayFieldName,
+				defaultValue
+			});
+		}, [formMeta, arrayFieldName]),
+		remove: React$1.useCallback((index) => {
+			if (!arrayFieldName) return;
+			formMeta.remove({
+				name: arrayFieldName,
+				index
+			});
+		}, [formMeta, arrayFieldName]),
+		move: React$1.useCallback((from, to) => {
+			if (!arrayFieldName) return;
+			formMeta.reorder({
+				name: arrayFieldName,
+				from,
+				to
+			});
+		}, [formMeta, arrayFieldName])
+	};
+}
+/**
+* Wraps children in Conform's FormProvider so that useFormMetadata() and
+* useInputControl() work inside field components.
+* Also provides the touched fields ref via context for useConformField.
+*/
+function ConformFormProviderWrapper({ instance, children }) {
+	const { form, touchedFieldsRef } = instance.raw;
+	return /* @__PURE__ */ jsx(FormProvider, {
+		context: form.context,
+		children: /* @__PURE__ */ jsx(TouchedFieldsContext, {
+			value: touchedFieldsRef,
+			children
+		})
+	});
+}
+/**
+* Conform.js adapter implementing the `FormAdapter` interface.
+*
+* Maps Conform's `useForm` / `useInputControl` / `useFormMetadata` APIs
+* to the normalized form adapter contract.
+*/
+const conformAdapter = {
+	name: "Conform",
+	useCreateForm: useConformCreateForm,
+	useField: useConformField,
+	useWatch: useConformWatch,
+	useWatchAll: useConformWatchAll,
+	useFieldArray: useConformFieldArray,
+	FormProvider: ConformFormProviderWrapper
+};
+//#endregion
+//#region src/components/features/form/adapters/conform/conform-provider.tsx
+/**
+* Wrap your application with this provider to use Conform.js as the form backend.
+*
+* @example
+* ```tsx
+* import { ConformAdapter } from '@datum-cloud/datum-ui/form/adapters/conform'
+*
+* function App() {
+*   return (
+*     <ConformAdapter>
+*       <MyApp />
+*     </ConformAdapter>
+*   )
+* }
+* ```
+*/
+function ConformAdapter({ children }) {
+	return /* @__PURE__ */ jsx(FormAdapterProvider, {
+		adapter: conformAdapter,
+		children
+	});
+}
+//#endregion
+export { ConformAdapter, conformAdapter };

package/dist/form/adapters/rhf/index.mjs

@@ -0,0 +1,267 @@
+import { t as FormAdapterProvider } from "../../../adapter-context-rWveHhDd.mjs";
+import { n as getObjectShape, t as getFieldConstraints } from "../../../get-field-constraints-BicgDkfH.mjs";
+import * as React$1 from "react";
+import { jsx } from "react/jsx-runtime";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { FormProvider, useController, useFieldArray, useForm, useFormContext, useWatch } from "react-hook-form";
+//#region src/components/features/form/utils/get-schema-defaults.ts
+/**
+* Derive default values from a Zod schema that match what React Hook Form's
+* `useController` will produce when fields register.
+*
+* This is critical for RHF's `isDirty` tracking: RHF compares current values
+* against `_defaultValues`. Without explicit defaults, RHF uses `{}` as the
+* baseline, so when `useController` registers fields (e.g. `username: ''`),
+* the form is immediately considered dirty.
+*
+* By passing these schema-derived defaults to `useForm({ defaultValues })`,
+* the baseline matches the registered values and `isDirty` starts as `false`.
+*
+* Maps Zod field types to their `useController` registration values:
+* - string -> `''`
+* - number -> `undefined`
+* - boolean -> `false`
+* - array -> `[]`
+* - object -> `{}` (recursive)
+* - optional/nullable wrappers -> unwrap and derive inner default
+* - `.default()` -> use the provided default value
+*/
+function getSchemaDefaults(schema) {
+	const shape = getObjectShape(schema);
+	if (!shape) return {};
+	const defaults = {};
+	for (const [key, fieldSchema] of Object.entries(shape)) defaults[key] = getFieldDefault(fieldSchema);
+	return defaults;
+}
+/**
+* Get the default value for a Zod field type that matches what RHF's
+* `useController` will produce when registering the field.
+*
+* Unwraps optional/nullable/default wrappers to find the inner type,
+* then returns the natural "empty" value for that type.
+*/
+function getFieldDefault(schema) {
+	const { type } = schema.def;
+	if (type === "default") return schema.def.defaultValue;
+	if (type === "optional" || type === "nullable") {
+		const innerDef = schema.def;
+		return getFieldDefault(innerDef.innerType);
+	}
+	if (type === "pipe") {
+		const pipeDef = schema.def;
+		return getFieldDefault(pipeDef.in);
+	}
+	if (type === "string") return "";
+	if (type === "number" || type === "bigint" || type === "nan") return void 0;
+	if (type === "boolean") return false;
+	if (type === "array") return [];
+	if (type === "object") return getSchemaDefaults(schema);
+}
+//#endregion
+//#region src/components/features/form/adapters/rhf/rhf-adapter.tsx
+const RHFFormIdContext = React$1.createContext("form");
+/** Create a React Hook Form instance and normalize it to the adapter interface. */
+function useRHFCreateForm(props) {
+	const { schema, defaultValues, mode, id, onSubmit, formRef } = props;
+	const modeMap = {
+		onBlur: "onBlur",
+		onChange: "onChange",
+		onSubmit: "onSubmit"
+	};
+	const schemaDefaults = React$1.useMemo(() => getSchemaDefaults(schema), [schema]);
+	const mergedDefaults = React$1.useMemo(() => ({
+		...schemaDefaults,
+		...defaultValues
+	}), [schemaDefaults, defaultValues]);
+	const form = useForm({
+		resolver: zodResolver(schema),
+		defaultValues: mergedDefaults,
+		mode: modeMap[mode]
+	});
+	const { errors, isDirty, isValid, dirtyFields, touchedFields } = form.formState;
+	const constraints = React$1.useMemo(() => getFieldConstraints(schema), [schema]);
+	const onSubmitRef = React$1.useRef(onSubmit);
+	onSubmitRef.current = onSubmit;
+	const normalizedFields = React$1.useMemo(() => {
+		const result = {};
+		for (const [key, constraint] of Object.entries(constraints)) {
+			const fieldError = errors[key];
+			result[key] = {
+				id: `${id ?? "form"}-${key}`,
+				errors: fieldError?.message ? [String(fieldError.message)] : [],
+				required: constraint.required,
+				isDirty: Boolean(dirtyFields[key]),
+				isTouched: Boolean(touchedFields[key])
+			};
+		}
+		return result;
+	}, [
+		constraints,
+		errors,
+		id,
+		dirtyFields,
+		touchedFields
+	]);
+	const formState = React$1.useMemo(() => ({
+		isDirty,
+		isValid,
+		isSubmitted: false,
+		submitCount: 0,
+		dirtyFields: Object.fromEntries(Object.entries(dirtyFields).map(([k, v]) => [k, Boolean(v)])),
+		touchedFields: Object.fromEntries(Object.entries(touchedFields).map(([k, v]) => [k, Boolean(v)]))
+	}), [
+		isDirty,
+		isValid,
+		dirtyFields,
+		touchedFields
+	]);
+	const handleSubmit = React$1.useMemo(() => form.handleSubmit((data) => {
+		onSubmitRef.current?.(data);
+	}), [form]);
+	const formProps = React$1.useMemo(() => ({
+		id,
+		onSubmit: handleSubmit,
+		noValidate: true
+	}), [id, handleSubmit]);
+	return React$1.useMemo(() => ({
+		id: id ?? "form",
+		fields: normalizedFields,
+		formProps,
+		formState,
+		submit: () => formRef?.current?.requestSubmit(),
+		reset: () => form.reset(),
+		getValues: () => form.getValues(),
+		raw: form
+	}), [
+		id,
+		normalizedFields,
+		formProps,
+		formState,
+		form,
+		formRef
+	]);
+}
+/** Resolve a field by name and return its normalized state. */
+function useRHFField(name) {
+	const form = useFormContext();
+	const formId = React$1.use(RHFFormIdContext);
+	const { field, fieldState } = useController({
+		name,
+		control: form.control
+	});
+	return React$1.useMemo(() => ({
+		name: field.name,
+		id: `${formId}-${name}`,
+		errors: fieldState.error?.message ? [String(fieldState.error.message)] : [],
+		required: false,
+		isDirty: fieldState.isDirty,
+		isTouched: fieldState.isTouched,
+		value: field.value,
+		change: (value) => field.onChange(value),
+		blur: () => field.onBlur(),
+		focus: () => form.setFocus(name)
+	}), [
+		field,
+		fieldState,
+		name,
+		formId,
+		form
+	]);
+}
+/** Watch a single field's value reactively. */
+function useRHFWatchHook(name) {
+	return useWatch({
+		name,
+		control: useFormContext().control
+	});
+}
+/** Watch multiple fields' values reactively. */
+function useRHFWatchAllHook(names) {
+	const values = useWatch({
+		name: names,
+		control: useFormContext().control
+	});
+	const namesKey = names.join(",");
+	return React$1.useMemo(() => {
+		const result = {};
+		names.forEach((n, index) => {
+			result[n] = values[index];
+		});
+		return result;
+	}, [namesKey, values]);
+}
+/** Get field array helpers for a given array field name. */
+function useRHFFieldArrayHook(name) {
+	const { fields, append, remove, move } = useFieldArray({
+		name,
+		control: useFormContext().control
+	});
+	return {
+		items: React$1.useMemo(() => fields.map((field, index) => ({
+			id: field.id,
+			key: field.id,
+			name: `${name}.${index}`
+		})), [fields, name]),
+		append: React$1.useCallback((defaultValue) => {
+			append(defaultValue ?? {});
+		}, [append]),
+		remove,
+		move
+	};
+}
+/**
+* Wraps children in React Hook Form's FormProvider so that useFormContext()
+* and useController() work inside field components.
+*/
+function RHFFormProviderWrapper({ instance, children }) {
+	const form = instance.raw;
+	return /* @__PURE__ */ jsx(RHFFormIdContext, {
+		value: instance.id,
+		children: /* @__PURE__ */ jsx(FormProvider, {
+			...form,
+			children
+		})
+	});
+}
+/**
+* React Hook Form adapter implementing the `FormAdapter` interface.
+*
+* Maps react-hook-form's `useForm` / `useController` / `useWatch` APIs
+* to the normalized form adapter contract. Uses `@hookform/resolvers/zod`
+* for Zod schema validation.
+*/
+const rhfAdapter = {
+	name: "React Hook Form",
+	useCreateForm: useRHFCreateForm,
+	useField: useRHFField,
+	useWatch: useRHFWatchHook,
+	useWatchAll: useRHFWatchAllHook,
+	useFieldArray: useRHFFieldArrayHook,
+	FormProvider: RHFFormProviderWrapper
+};
+//#endregion
+//#region src/components/features/form/adapters/rhf/rhf-provider.tsx
+/**
+* Wrap your application with this provider to use React Hook Form as the form backend.
+*
+* @example
+* ```tsx
+* import { RHFAdapter } from '@datum-cloud/datum-ui/form/adapters/rhf'
+*
+* function App() {
+*   return (
+*     <RHFAdapter>
+*       <MyApp />
+*     </RHFAdapter>
+*   )
+* }
+* ```
+*/
+function RHFAdapter({ children }) {
+	return /* @__PURE__ */ jsx(FormAdapterProvider, {
+		adapter: rhfAdapter,
+		children
+	});
+}
+//#endregion
+export { RHFAdapter, rhfAdapter };

package/dist/form/index.mjs

@@ -1,2 +1,3 @@
-import { A as FormButton, C as FormField, D as FormCustom, E as FormDescription, O as FormCopyBox, S as FormFieldArray, T as FormDialog, _ as FormSelectItem, a as useField, b as FormRadioItem, c as FormStep, d as useWatch, f as useWatchAll, g as FormSelect, h as FormSubmit, i as useFieldContext, j as FormAutocomplete, k as FormCheckbox, l as FormStepper, m as FormSwitch, n as useStepper, o as StepperNavigation, p as FormTextarea, r as useFormContext, s as StepperControls, t as Form, u as FormWhen, v as FormRoot, w as FormError, x as FormInput, y as FormRadioGroup } from "../form-Co3fM4B7.mjs";
-export { Form, FormAutocomplete, FormButton, FormCheckbox, FormCopyBox, FormCustom, FormDescription, FormDialog, FormError, FormField, FormFieldArray, FormInput, FormRadioGroup, FormRadioItem, FormRoot, FormSelect, FormSelectItem, FormStep, FormStepper, FormSubmit, FormSwitch, FormTextarea, FormWhen, StepperControls, StepperNavigation, useField, useFieldContext, useFormContext, useStepper, useWatch, useWatchAll };
+import { A as FormCheckbox, C as FormDialog, D as FormCustom, E as FormDatePicker, M as FormAutosearch, N as FormAutocomplete, O as FormCopyBox, S as FormError, T as FormDateTimePicker, _ as FormRadioGroup, a as useField, b as FormFieldArray, c as useWatchAll, d as FormTextarea, f as FormSwitch, g as FormRoot, h as FormSelectItem, i as useFieldContext, j as FormButton, k as FormCombobox, l as FormTransfer, m as FormSelect, n as useFormState, o as FormWhen, p as FormSubmit, r as useFormContext, s as useWatch, t as Form, u as FormTimePicker, v as FormRadioItem, w as FormDescription, x as FormField, y as FormInput } from "../form-D8OnRHdd.mjs";
+import { n as useAdapter, t as FormAdapterProvider } from "../adapter-context-rWveHhDd.mjs";
+export { Form, FormAdapterProvider, FormAutocomplete, FormAutosearch, FormButton, FormCheckbox, FormCombobox, FormCopyBox, FormCustom, FormDatePicker, FormDateTimePicker, FormDescription, FormDialog, FormError, FormField, FormFieldArray, FormInput, FormRadioGroup, FormRadioItem, FormRoot, FormSelect, FormSelectItem, FormSubmit, FormSwitch, FormTextarea, FormTimePicker, FormTransfer, FormWhen, useAdapter, useField, useFieldContext, useFormContext, useFormState, useWatch, useWatchAll };