Implement generalized solution for cross-field validation (#352)

Author: carina-akaia

components.json

@@ -5,14 +5,14 @@
   "tsx": true,
   "tailwind": {
     "config": "tailwind.config.ts",
-    "css": "src/common/ui/styles/theme.css",
+    "css": "src/common/ui/layout/styles/theme.css",
     "baseColor": "slate",
     "cssVariables": true,
     "prefix": ""
   },
   "aliases": {
-    "components": "@/common/ui",
-    "utils": "@/common/ui/utils",
-    "ui": "@/common/ui/components"
+    "components": "@/common/ui/layout",
+    "utils": "@/common/ui/layout/utils",
+    "ui": "@/common/ui/layout/components"
   }
 }

package.json

@@ -11,7 +11,7 @@
     "typecheck": "tsc --noEmit",
     "generate:api-clients": "orval --config api.config.cjs",
     "generate:clients": "concurrently 'yarn generate:api-clients'",
-    "generate:css": "unocss 'src/**/*.tsx' --out-file=src/common/ui/styles/uno.generated.css --write-transformed",
+    "generate:css": "unocss 'src/**/*.tsx' --out-file=src/common/ui/layout/styles/uno.generated.css --write-transformed",
     "dev:css": "yarn generate:css --watch",
     "dev:test": "yarn && vitest watch",
     "dev": "yarn && yarn generate:css && concurrently 'yarn dev:css' 'next dev'",

src/common/constants.ts

@@ -114,7 +114,7 @@ export const NATIVE_TOKEN_DECIMALS = NEAR_NOMINATION_EXP;
 export const NATIVE_TOKEN_ICON_URL = `${ICONS_ASSET_ENDPOINT_URL}/near.svg`;
 export const UNKNOWN_ACCOUNT_ID_PLACEHOLDER = "unknown-account-id";
 
-export const PLATFORM_LISTED_TOKEN_IDS: TokenId[] = [NATIVE_TOKEN_ID];
+export const PLATFORM_LISTED_TOKEN_IDS: TokenId[] = [];
 
 // List ID of PotLock Public Goods Registry
 export const PUBLIC_GOODS_REGISTRY_LIST_ID = 1;

src/common/ui/form-fields/checkbox.tsx src/common/ui/form/components/checkbox.tsx

@@ -1,5 +1,4 @@
-import { Checkbox } from "../components";
-import { FormControl, FormItem, FormLabel } from "../components/molecules/form";
+import { Checkbox, FormControl, FormItem, FormLabel } from "../../layout/components";
 
 export type CheckboxFieldProps = Pick<
   React.ComponentProps<typeof Checkbox>,

src/common/ui/form-fields/index.ts src/common/ui/form/components/index.ts

@@ -13,7 +13,7 @@ import {
   SelectLabel,
   SelectTrigger,
   SelectValue,
-} from "../components";
+} from "../../layout/components";
 
 export const SelectFieldOption = SelectItem;
 

src/common/ui/form-fields/select.tsx src/common/ui/form/components/select.tsx

@@ -1,7 +1,13 @@
 import { forwardRef, useMemo } from "react";
 
-import { FormControl, FormDescription, FormItem, FormLabel, FormMessage } from "../components";
-import { cn } from "../utils";
+import {
+  FormControl,
+  FormDescription,
+  FormItem,
+  FormLabel,
+  FormMessage,
+} from "../../layout/components";
+import { cn } from "../../layout/utils";
 
 export type TextFieldProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "className"> & {
   type: "email" | "text" | "number" | "tel" | "url" | "datetime-local";

src/common/ui/form-fields/text.tsx src/common/ui/form/components/text.tsx

@@ -8,8 +8,8 @@ import {
   FormMessage,
   Textarea,
   TextareaProps,
-} from "../components";
-import { cn } from "../utils";
+} from "../../layout/components";
+import { cn } from "../../layout/utils";
 
 export type TextAreaFieldProps = TextareaProps & {
   label: string;
@@ -30,7 +30,9 @@ export const TextAreaField = forwardRef<HTMLTextAreaElement, TextAreaFieldProps>
           <div un-flex="~" un-items="center" un-gap="1">
             {label && <FormLabel className="font-500 text-sm">{label}</FormLabel>}
 
-            {props.required && <span className="line-height-none text-destructive text-xl">*</span>}
+            {props.required && (
+              <span className="line-height-none text-destructive text-xl">{"*"}</span>
+            )}
           </div>
 
           {labelExtension ??
@@ -48,15 +50,17 @@ export const TextAreaField = forwardRef<HTMLTextAreaElement, TextAreaFieldProps>
           />
         </FormControl>
 
-        <FormDescription className="">
-          {hint && <span>{hint}</span>}
+        <div className="flex justify-between">
+          <FormMessage>{customErrorMessage}</FormMessage>
 
-          <span className="prose ml-auto">
-            {typeof maxLength === "number" ? `${currentLength}/${maxLength}` : currentLength}
-          </span>
-        </FormDescription>
+          <FormDescription className="ml-a">
+            {hint && <span>{hint}</span>}
 
-        <FormMessage>{customErrorMessage}</FormMessage>
+            <span className="prose ml-auto">
+              {typeof maxLength === "number" ? `${currentLength}/${maxLength}` : currentLength}
+            </span>
+          </FormDescription>
+        </div>
       </FormItem>
     );
   },

src/common/ui/form-fields/textarea.tsx src/common/ui/form/components/textarea.tsx

@@ -0,0 +1,111 @@
+import { useEffect } from "react";
+
+import { zodResolver } from "@hookform/resolvers/zod";
+import { type UseFormProps, type UseFormReturn, useForm } from "react-hook-form";
+import { isDeepEqual, keys, pick } from "remeda";
+import type { infer as FromSchema, ZodSchema } from "zod";
+
+import {
+  type FormCrossFieldZodValidationParams,
+  useFormCrossFieldZodValidation,
+} from "./zod-validation";
+
+export type EnhancedFormProps<TSchema extends ZodSchema> = Omit<
+  UseFormProps<FromSchema<TSchema>>,
+  "resolver"
+> &
+  Partial<Pick<FormCrossFieldZodValidationParams<TSchema>, "dependentFields">> & {
+    schema: TSchema;
+    /**
+     * Whether to keep track of the `defaultValues` state and re-populate the values automatically.
+     *
+     * @default false
+     */
+    followDefaultValues?: boolean;
+  };
+
+export type EnhancedFormBindings = {
+  /**
+   * Indicates whether the form is out of sync with the current defaultValues state.
+   *
+   * Useful when `defaultValues` is reactive and can potentially change.
+   */
+  isUnpopulated: boolean;
+};
+
+/**
+ * Enhanced version of react-hook-form's useForm that includes cross-field validation
+ * functionality and enforces Zod schema validation.
+ *
+ * @remarks
+ * This hook combines the power of react-hook-form with Zod validation and adds support
+ * for complex cross-field validation scenarios.
+ *
+ * @param props - form configuration and validation parameters. {@link EnhancedFormProps}
+ *
+ * @returns object - form with enhancements. {@link UseFormReturn} & {@link EnhancedFormBindings}
+ *
+ * @example
+ * ```tsx
+ * const schema = z.object({
+ *   password: z.string().min(8),
+ *   passwordConfirmation: z.string()
+ * }).refine(data => data.password === data.passwordConfirmation, {
+ *   message: "Passwords don't match",
+ *   path: ["passwordConfirmation"]
+ * });
+ *
+ * function App() {
+ *   const form = useEnhancedForm({
+ *     schema,
+ *     dependentFields: ["passwordConfirmation"],
+ *     defaultValues: {
+ *       password: "",
+ *       passwordConfirmation: ""
+ *     }
+ *   });
+ *
+ *   return (
+ *     <form onSubmit={form.handleSubmit(onSubmit)}>
+ *       <input {...form.register("password")} />
+ *       <input {...form.register("passwordConfirmation")} />
+ *       {form.formState.errors.passwordConfirmation && (
+ *         <span>{form.formState.errors.passwordConfirmation.message}</span>
+ *       )}
+ *       <button type="submit">Submit</button>
+ *     </form>
+ *   );
+ * }
+ * ```
+ */
+export const useEnhancedForm = <TSchema extends ZodSchema>({
+  schema,
+  dependentFields = [],
+  defaultValues,
+  followDefaultValues = false,
+  ...formProps
+}: EnhancedFormProps<TSchema>): {
+  form: UseFormReturn<FromSchema<TSchema>>;
+} & EnhancedFormBindings => {
+  const self = useForm<FromSchema<TSchema>>({
+    ...formProps,
+    resolver: zodResolver(schema),
+    defaultValues,
+  });
+
+  useFormCrossFieldZodValidation({ form: self, schema, dependentFields });
+
+  const isUnpopulated =
+    !isDeepEqual(
+      defaultValues,
+      pick(self.formState.defaultValues ?? {}, keys(defaultValues ?? {})),
+    ) && !self.formState.isDirty;
+
+  useEffect(() => {
+    if (followDefaultValues && isUnpopulated) {
+      self.reset(defaultValues);
+    }
+  }, [isUnpopulated, self, defaultValues, followDefaultValues]);
+
+  return { form: self, isUnpopulated };
+};

src/common/ui/form/hooks/enhanced.ts

@@ -0,0 +1,2 @@
+export * from "./enhanced";
+export * from "./zod-validation";

src/common/ui/form/hooks/index.ts

@@ -0,0 +1,77 @@
+import { useEffect } from "react";
+
+import { type Path, type UseFormReturn, useWatch } from "react-hook-form";
+import type { infer as FromSchema, ZodError, ZodSchema } from "zod";
+
+export type FormCrossFieldZodValidationParams<TSchema extends ZodSchema> = {
+  /**
+   * The form instance returned by react-hook-form's useForm
+   */
+  form: UseFormReturn<FromSchema<TSchema>>;
+  /**
+   * A Zod schema that defines the validation rules including cross-field validations
+   */
+  schema: TSchema;
+  /**
+   * Array of field names that should be validated when other fields change
+   */
+  dependentFields: Array<keyof FromSchema<TSchema>>;
+};
+
+/**
+ * Performs complex form validation where the validity of one field depends on
+ *  the state of other fields - a scenario not handled by react-hook-form's built-in validation.
+ *
+ * The hook watches for changes in form values and triggers Zod schema validation,
+ *  setting errors on the specified target fields when validation fails.
+ *
+ * @param params - The parameters object. {@link FormCrossFieldZodValidationParams}
+ *
+ * @example
+ * ```typescript
+ * const schema = z.object({
+ *   password: z.string(),
+ *   passwordConfirmation: z.string()
+ * }).refine(data => data.password === data.passwordConfirmation, {
+ *   message: "Passwords don't match",
+ *   path: ["passwordConfirmation"]
+ * });
+ *
+ * const form = useForm<z.infer<typeof schema>>();
+ *
+ * useFormCrossFieldValidation({
+ *   form,
+ *   schema,
+ *   dependentFields: ["passwordConfirmation"]
+ * });
+ * ```
+ *
+ * @returns void - This hook only produces side effects (setting form errors)
+ */
+export const useFormCrossFieldZodValidation = <TSchema extends ZodSchema>({
+  form,
+  schema,
+  dependentFields,
+}: FormCrossFieldZodValidationParams<TSchema>) => {
+  type Inputs = FromSchema<TSchema>;
+
+  const values = useWatch({ control: form.control });
+
+  useEffect(() => {
+    if (dependentFields.length > 0) {
+      schema.parseAsync(values).catch((error?: ZodError) =>
+        error?.issues.forEach(({ code, message, path }) => {
+          const fieldPath = path.at(0);
+
+          if (
+            dependentFields.includes(fieldPath as keyof Inputs) &&
+            typeof fieldPath === "string" &&
+            code === "custom"
+          ) {
+            form.setError(fieldPath as Path<Inputs>, { message, type: code });
+          }
+        }),
+      );
+    }
+  }, [schema, form, values, dependentFields]);
+};

src/common/ui/form/hooks/zod-validation.ts

@@ -2,7 +2,7 @@ import * as React from "react";
 
 import { type VariantProps, cva } from "class-variance-authority";
 
-import { cn } from "@/common/ui/utils";
+import { cn } from "@/common/ui/layout/utils";
 
 const badgeVariants = cva(
   cn(

src/common/ui/components/_deprecated/DeprecatedPagination.tsx src/common/ui/layout/components/_deprecated/DeprecatedPagination.tsx

@@ -4,7 +4,7 @@ import { forwardRef } from "react";
 
 import * as HoverCardPrimitive from "@radix-ui/react-hover-card";
 
-import { cn } from "@/common/ui/utils";
+import { cn } from "@/common/ui/layout/utils";
 
 const HoverCard = HoverCardPrimitive.Root;
 

src/common/ui/components/_deprecated/InfiniteScroll.tsx src/common/ui/layout/components/_deprecated/InfiniteScroll.tsx

@@ -4,7 +4,7 @@ import { forwardRef } from "react";
 
 import * as ScrollAreaPrimitive from "@radix-ui/react-scroll-area";
 
-import { cn } from "@/common/ui/utils";
+import { cn } from "@/common/ui/layout/utils";
 
 const ScrollArea = forwardRef<
   React.ElementRef<typeof ScrollAreaPrimitive.Root>,

src/common/ui/components/_deprecated/Radio/index.tsx src/common/ui/layout/components/_deprecated/Radio/index.tsx

@@ -1,5 +1,5 @@
 import { PLATFORM_NAME } from "@/common/_config";
-import { cn } from "@/common/ui/utils";
+import { cn } from "@/common/ui/layout/utils";
 
 export type SplashScreenProps = {
   className?: string;

src/common/ui/components/_deprecated/Radio/styles.ts src/common/ui/layout/components/_deprecated/Radio/styles.ts

@@ -1,6 +1,6 @@
 import * as React from "react";
 
-import { cn } from "@/common/ui/utils";
+import { cn } from "@/common/ui/layout/utils";
 
 const Table = React.forwardRef<HTMLTableElement, React.HTMLAttributes<HTMLTableElement>>(
   ({ className, ...props }, ref) => (

src/common/ui/components/_deprecated/TimeLeft.tsx src/common/ui/layout/components/_deprecated/TimeLeft.tsx

@@ -2,7 +2,7 @@ import { forwardRef } from "react";
 
 import * as TooltipPrimitive from "@radix-ui/react-tooltip";
 
-import { cn } from "@/common/ui/utils";
+import { cn } from "@/common/ui/layout/utils";
 
 const TooltipProvider = TooltipPrimitive.Provider;
 

src/common/ui/components/atoms/accordion.tsx src/common/ui/layout/components/atoms/accordion.tsx

@@ -2,7 +2,7 @@ import React, { ReactElement, useCallback, useState } from "react";
 
 import { CopyToClipboard } from "react-copy-to-clipboard";
 
-import { CopyPasteIcon } from "@/common/ui/svg";
+import { CopyPasteIcon } from "@/common/ui/layout/svg";
 
 export type ClipboardCopyButtonProps = {
   customIcon?: ReactElement;

src/common/ui/components/atoms/alert.tsx src/common/ui/layout/components/atoms/alert.tsx

@@ -2,7 +2,7 @@ import { forwardRef } from "react";
 
 import * as RadioGroupPrimitive from "@radix-ui/react-radio-group";
 
-import { RadioActiveIcon, RadioInactiveIcon } from "@/common/ui/svg";
+import { RadioActiveIcon, RadioInactiveIcon } from "@/common/ui/layout/svg";
 
 import { cn } from "../../utils";
 import { Label } from "../atoms/label";

src/common/ui/components/atoms/avatar.tsx src/common/ui/layout/components/atoms/avatar.tsx

@@ -3,13 +3,13 @@ import { useCallback, useState } from "react";
 import { Check } from "lucide-react";
 import CopyToClipboard from "react-copy-to-clipboard";
 
-import { CopyPasteIcon } from "@/common/ui/svg";
+import { CopyPasteIcon } from "@/common/ui/layout/svg";
 import {
   InstagramShareIcon,
   ShareIcon,
   TelegramShareIcon,
   TwitterShareIcon,
-} from "@/common/ui/svg/Share";
+} from "@/common/ui/layout/svg/Share";
 
 import { Button } from "../atoms/button";
 import { Popover, PopoverContent, PopoverTrigger } from "../atoms/popover";