@nikala-ui/hooks 0.9.11 → 0.10.0

package/README.md

@@ -80,6 +80,31 @@ const [value, setValue] = createControllableSignal({
 });
 ```
 
+### Form validation and submission
+
+`createForm` supports change-, blur-, and submit-time validation, typed checkbox/select event values, stale async validation protection, and submit error state:
+
+```tsx
+const form = createForm({
+  initialValues: { email: "", marketing: false },
+  validateOn: "blur",
+  validate: (values) => ({
+    ...(!values.email.includes("@") && { email: "Enter a valid email." }),
+  }),
+  onSubmit: async (values) => saveProfile(values),
+});
+
+<Form onSubmit={form.handleSubmit} loading={form.isSubmitting()}>
+  <Input
+    value={form.values().email}
+    onInput={form.handleChange("email")}
+    onBlur={form.handleBlur("email")}
+  />
+  <FormMessage form={form} name="email" />
+  {form.submitError() && <p>Could not save changes.</p>}
+</Form>
+```
+
 ---
 
 ## Documentation & Links

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nikala-ui/hooks",
-  "version": "0.9.11",
+  "version": "0.10.0",
   "description": "Reactive SolidJS primitives and primitives for Nikala UI",
   "type": "module",
   "main": "./src/index.ts",

package/src/create-form.ts

@@ -2,12 +2,22 @@ import { createSignal, createMemo, type Accessor } from "solid-js";
 
 export type FormErrors<T> = Partial<Record<keyof T, string>>;
 export type FormTouched<T> = Partial<Record<keyof T, boolean>>;
+export type ValidateOn = "change" | "blur" | "submit";
+
+export type FormInputEvent = Event & {
+  currentTarget:
+    | HTMLInputElement
+    | HTMLTextAreaElement
+    | HTMLSelectElement;
+};
 
 export interface CreateFormOptions<T extends Record<string, any>> {
   /** Initial form field values object */
   initialValues: T;
   /** Custom validation function returning error messages object */
   validate?: (values: T) => FormErrors<T> | Promise<FormErrors<T>>;
+  /** Event that triggers validation. Defaults to "change". */
+  validateOn?: ValidateOn;
   /** Submit handler callback invoked when validation succeeds */
   onSubmit?: (values: T) => void | Promise<void>;
 }
@@ -21,6 +31,8 @@ export interface CreateFormReturn<T extends Record<string, any>> {
   touched: Accessor<FormTouched<T>>;
   /** Accessor indicating if form is currently submitting */
   isSubmitting: Accessor<boolean>;
+  /** Accessor containing an exception thrown by onSubmit, if any */
+  submitError: Accessor<unknown>;
   /** Accessor indicating if form has zero validation errors */
   isValid: Accessor<boolean>;
   /** Accessor indicating if form values differ from initial values */
@@ -32,11 +44,11 @@ export interface CreateFormReturn<T extends Record<string, any>> {
   /** Set specific form field touched state */
   setFieldTouched: <K extends keyof T>(field: K, isTouched?: boolean) => void;
   /** Input change event listener helper factory function */
-  handleChange: <K extends keyof T>(field: K) => (e: Event & { currentTarget: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement }) => void;
+  handleChange: <K extends keyof T>(field: K) => (e: FormInputEvent) => void;
   /** Input blur event listener helper factory function */
   handleBlur: <K extends keyof T>(field: K) => () => void;
   /** Form onSubmit event handler */
-  handleSubmit: (e?: Event) => void;
+  handleSubmit: (e?: Event) => Promise<void>;
   /** Reset form values, errors, and touched states to initial values */
   resetForm: () => void;
 }
@@ -55,6 +67,9 @@ export function createForm<T extends Record<string, any>>(
   const [errors, setErrors] = createSignal<FormErrors<T>>({});
   const [touched, setTouched] = createSignal<FormTouched<T>>({});
   const [isSubmitting, setIsSubmitting] = createSignal(false);
+  const [submitError, setSubmitError] = createSignal<unknown>();
+  const validateOn = options.validateOn ?? "change";
+  let validationSequence = 0;
 
   const isDirty = createMemo(() => {
     const current = values();
@@ -67,17 +82,27 @@ export function createForm<T extends Record<string, any>>(
   });
 
   const runValidation = async (currentValues: T): Promise<FormErrors<T>> => {
-    if (!options.validate) return {};
+    const sequence = ++validationSequence;
+    if (!options.validate) {
+      setErrors(() => ({}));
+      return {};
+    }
+
     const result = await options.validate(currentValues);
     const newErrors = result || {};
-    setErrors(() => newErrors);
+    // Ignore stale async validations that finished after a newer request.
+    if (sequence === validationSequence) {
+      setErrors(() => newErrors);
+    }
     return newErrors;
   };
 
   const setFieldValue = <K extends keyof T>(field: K, value: T[K]) => {
     const next = { ...values(), [field]: value };
     setValues(() => next);
-    runValidation(next);
+    if (validateOn === "change") {
+      void runValidation(next);
+    }
   };
 
   const setFieldError = <K extends keyof T>(field: K, error: string | undefined) => {
@@ -94,21 +119,37 @@ export function createForm<T extends Record<string, any>>(
   };
 
   const handleChange = <K extends keyof T>(field: K) => {
-    return (e: Event & { currentTarget: HTMLInputElement | HTMLTextAreaElement | HTMLSelectElement }) => {
-      const val = e.currentTarget.value;
-      setFieldValue(field, val as any);
+    return (e: FormInputEvent) => {
+      const target = e.currentTarget;
+      let value: unknown = target.value;
+
+      if (
+        "checked" in target &&
+        ((target as HTMLInputElement).type === "checkbox" ||
+          (target as HTMLInputElement).type === "radio")
+      ) {
+        value = (target as HTMLInputElement).checked;
+      } else if ("selectedOptions" in target && target.multiple) {
+        value = Array.from(target.selectedOptions, (option) => option.value);
+      }
+
+      setFieldValue(field, value as T[K]);
     };
   };
 
   const handleBlur = <K extends keyof T>(field: K) => {
     return () => {
       setFieldTouched(field, true);
+      if (validateOn === "blur") {
+        void runValidation(values());
+      }
     };
   };
 
   const handleSubmit = async (e?: Event) => {
     e?.preventDefault();
     setIsSubmitting(true);
+    setSubmitError(undefined);
 
     // Mark all fields as touched on submit
     const allTouched = Object.keys(values()).reduce((acc, key) => {
@@ -117,14 +158,18 @@ export function createForm<T extends Record<string, any>>(
     }, {} as FormTouched<T>);
     setTouched(() => allTouched);
 
-    const validationErrors = await runValidation(values());
-    if (Object.keys(validationErrors).length === 0) {
-      if (options.onSubmit) {
-        await options.onSubmit(values());
+    try {
+      const validationErrors = await runValidation(values());
+      if (Object.keys(validationErrors).length === 0 && options.onSubmit) {
+        try {
+          await options.onSubmit(values());
+        } catch (error) {
+          setSubmitError(() => error);
+        }
       }
+    } finally {
+      setIsSubmitting(false);
     }
-
-    setIsSubmitting(false);
   };
 
   const resetForm = () => {
@@ -132,6 +177,8 @@ export function createForm<T extends Record<string, any>>(
     setErrors(() => ({}));
     setTouched(() => ({}));
     setIsSubmitting(false);
+    setSubmitError(undefined);
+    validationSequence += 1;
   };
 
   return {
@@ -139,6 +186,7 @@ export function createForm<T extends Record<string, any>>(
     errors,
     touched,
     isSubmitting,
+    submitError,
     isValid,
     isDirty,
     setFieldValue,