formController tools

The formController exposes various methods for managing forms. Each method has a specific role — together they manage the form's lifecycle. register registers inputs and wires event handlers; getValues and getErrors read current form state and errors. Use setValues and setErrors to inject external data or manipulate state, and handleSubmit to validate and run callbacks on successful submission. These tools enable declarative, maintainable form logic and improve developer productivity and code quality.

const {
  initValue,
  register,
  getValues,
  getErrors,
  setValues,
  setErrors,
  handleSubmit,
  handleServerAction
} = formController

register#

register registers an input with the Sicilian controller and auto-connects event handlers. As the type definitions below show, it supports many input types and provides type safety in TypeScript. The ExtractKeys<T> variant restricts allowed field names to those defined in initValue or validator, preventing typos. The string variant allows dynamic field addition. For radio, value is required to distinguish radio buttons sharing the same name. You may also pass a validate object per-field for custom rules.

type TRegister<T extends InitState> = {
  // For radio type – ExtractKeys<T> version
  <K extends ExtractKeys<T>>(params: { name: K; validate?: RegisterErrorObj<T>; type: 'radio'; value: string }): IRegister<T>,
  // For non-radio types – ExtractKeys<T> version
  <K extends ExtractKeys<T>>(params: { name: K; validate?: RegisterErrorObj<T>; type?: Exclude<ValidInputTypes, 'radio'> }): IRegister<T>,
  
  // For radio type – string version
  (params: { name: string; validate?: RegisterErrorObj<T>; type: 'radio'; value: string }): IRegister<T>,
  // For non-radio types – string version
  (params: { name: string; validate?: RegisterErrorObj<T>; type?: Exclude<ValidInputTypes, 'radio'> }): IRegister<T>;
}

The object returned by register (the IRegister interface) provides props and handlers to integrate with React inputs. onChange, onBlur, and onFocus update form state and optionally trigger validation. SicilianEvent handles DOM and custom events. name and id identify fields; type, checked, and value reflect native input props. Apply them to JSX with the spread syntax {...register({ name: "email" })} to reduce boilerplate.

export interface IRegister<T extends InitState> {
  onChange: (e: SicilianEvent) => void
  onFocus: (e: SicilianEvent) => void
  onBlur: (e: SicilianEvent) => void
  name: ExtractKeys<T> | string
  id: ExtractKeys<T> | string
  type: HTMLInputElement["type"]
  value?: string
  checked?: boolean
}

Values and Errors#

The formController provides access to current values and errors. getValues returns all values or a specific field; getErrors returns field error messages. These functions can be subscribed to so components re-render when observed values change. setStore and getStore expose low-level store access for advanced scenarios. Note:

The objects returned by getValues and getErrors reflect global state, which can cause re-render cascades similar to Context API patterns. To avoid broad re-renders, getValues and getErrors accept optional field names to subscribe to specific fields; without args they return complete objects.

getValues: State<T, unknown>;
getErrors: State<{ [key in keyof T]: string }, string>;
setValues: IStore<T>["setStore"];
setErrors: IStore<{ [key in keyof T]: string }>["setStore"];

export type State<T extends InitState, BasicReturnType> = {
  (): T & { [x: string]: BasicReturnType | undefined };
  <K extends ExtractKeys<T>>(name: K): T[K];
  (name: string): BasicReturnType | undefined;
}
 
export interface IStore<T> {
  ...
  setStore: (nextState: Partial<T> & { [x: string]: string | boolean | FileList }) => void;
  ...
}

setValues and setErrors update parts of the form state or error state, enabling fine-grained updates useful for performance optimization.

const { setValues } = ArticleFormController
 
const { data } = useQuery({
  queryKey: ["review", reviewId],
  queryFn: getReview(reviewId)
  }
});
 
useEffect(() => {
  setValues({
    title: data?.title ?? "",
    author: data?.author ?? "",
    description: data?.description ?? ""
  });
}, [data]);

handleSubmit#

handleSubmit accepts a callback invoked with the current formState and the event object. It internally calls e.preventDefault() to prevent navigation on form submit.

<form
  onSubmit={handleSubmit(async (data, e) => {
    const res = await fetch("URL", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify(data),
    });
  })}
>

You can implement submit logic by manually reading formState from getValues, but handleSubmit offers additional safety and conveniences.

• If any unresolved error message remains, handleSubmit cancels submission to prevent unwanted data from going to the backend.
• Similarly, if all inputs managed by the formController are empty, submission is canceled to avoid accidental HTTP requests.

Even if clearFormOn includes ["submit"], the form will not clear if submission fails.

handleServerAction#

handleServerAction handles server actions or server functions to submit form data and process responses. It integrates with server-side async functions and lets you provide a server action function that receives form data and an event. Validation runs before the server action is invoked; if validation fails, the server action won't be called. Optionally provide a callback to handle success or error responses from the server.

export function FeedbackModal() {
  const [state, execute, isPending] = useActionState(postFeedback);
  
  useEffect(() => {
    if (state?.message) {
      grunfeld.clear();
      toast.success("피드백이 제출되었습니다.");
    }
  }, [state?.message]);

  return <Form
    action={handleServerAction(execute)}
    className="flex flex-col w-full gap-24 overflow-y-scroll md:min-w-400"
  >
}

Typical server action functions accept a FormData argument, but handleServerAction converts form data to an object before calling the server action, making server-side handling easier and avoiding direct FormData manipulation. The event object is also passed for additional context.

"use server";

import { FeedbackTypeKr } from "@/shared/types";
import { getCookieValue } from "@/shared/utils/cookieUtils";
import { getEnumKeyByValue } from "@/shared/utils/enumUtils";
import { fetcher } from "@/shared/utils/fetcher";

export async function postFeedback(
  prev: unknown,
  {
    type,
    message,
  }: {
    type: FeedbackTypeKr | "";
    message: string;
  }
) {
  try {
    return await fetcher.post(
      `feedback`,
      {
        body: {
          type: getEnumKeyByValue(type, FeedbackTypeKr),
          message,
        },
      },
      {
        headers: {
          Cookie: await getCookieValue(),
        },
      }
    );
  } catch (error) {
    console.error("Error occurred while starting interview:", error);
  }
}

This design simplifies form submission and server communication using handleServerAction.