formController 객체의 도구들

formController 객체에는 form을 관리하기 위한 다양한 메서드가 들어있습니다. 이 메서드들은 각각 특정한 역할을 담당하며 함께 동작하여 폼의 전체 생명주기를 관리합니다. useRegister는 입력 필드를 등록하고 이벤트 핸들러를 자동으로 연결하며, useFields는 값/에러/메타를 읽어옵니다. setValues와 setErrors를 통해 외부 데이터를 주입하거나 상태를 직접 제어할 수 있고, handleSubmit은 폼 제출 시 데이터 유효성을 검증하고 성공 시에만 콜백 함수를 실행합니다. 이러한 도구들을 활용하면 복잡한 폼 로직을 선언적이고 체계적으로 관리할 수 있어 개발 생산성과 코드 품질을 모두 향상시킬 수 있습니다.

const {
  initValue,
  useRegister,
  useFields,
  setValues,
  setErrors,
  handleSubmit,
  handleServerAction
} = formController

useRegister#

useRegister 함수는 폼 필드를 Sicilian 폼 컨트롤러에 등록하고 필요한 이벤트 핸들러를 자동으로 연결하는 핵심 기능입니다. 아래 타입 정의에서 볼 수 있듯이, 다양한 입력 유형을 지원하며 특히 타입스크립트 환경에서 타입 안전성을 제공합니다. ExtractKeys<T> 버전은 initValue나 validator에 정의된 필드명만 허용하여 오타나 존재하지 않는 필드를 사용할 수 없게 합니다. 반면 string 버전은 동적으로 필드를 추가할 때 유연성을 제공합니다. radio 타입은 일반 입력 필드와 달리 value 속성이 필수적으로 요구되며, 이를 통해 동일한 name을 가진 여러 radio 버튼을 구분합니다. 또한 각 필드에 validate 객체를 옵션으로 제공하여 개별적인 유효성 검사 규칙을 적용할 수 있습니다.

type TRegister<T extends InitState> = {
  // For radio type – ExtractKeys<T> version
  <K extends ExtractKeys<T>>(name: K, options: RegisterRadioOptions<T>): IRegister<T>,
  // For non-radio types – ExtractKeys<T> version
  <K extends ExtractKeys<T>>(name: K, options?: RegisterOptions<T>): IRegister<T>,
  
  // For radio type – string version
  (name: string, options: RegisterRadioOptions<T>): IRegister<T>,
  // For non-radio types – string version
  (name: string, options?: RegisterOptions<T>): IRegister<T>;
}

useRegister 함수가 반환하는 IRegister 인터페이스는 리액트 입력 요소와 통합할 수 있는 이벤트 핸들러와 속성들을 제공합니다. onChange, onBlur, onFocus 핸들러는 각각 입력값 변경, 포커스 해제, 포커스 획득 시 폼 상태를 업데이트하고 필요에 따라 유효성 검사를 실행합니다. 특히 SicilianEvent 타입을 사용하여 일반적인 DOM 이벤트뿐 아니라 커스텀 이벤트 객체도 처리할 수 있습니다. name과 id 속성은 필드 식별자로 작용하며, type 속성은 HTML 입력 요소의 타입을 지정합니다. 또한 체크박스나 라디오 버튼 같은 요소를 위한 checked 속성과 select 요소 등을 위한 value 속성도 필요에 따라 제공됩니다. 이 모든 프로퍼티는 스프레드 연산자{...useRegister('email')}를 통해 JSX 요소에 간편하게 적용할 수 있어 보일러플레이트 코드를 대폭 줄여줍니다.

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#

useFields는 입력 필드의 현재 값과 오류 상태, 그리고 메타 정보를 제공합니다. 전체 폼을 구독하거나 특정 필드만 구독할 수 있습니다. setStore와 getStore는 더 낮은 수준에서 폼 상태 저장소에 직접 접근할 수 있게 해주어 복잡한 상태 관리 시나리오에서 유용합니다.

인자 없이 useFields()를 호출하면 전체 필드를 구독하므로 리렌더링 범위가 커질 수 있습니다. 필요한 필드만 구독하려면 useFields(name) 형태를 권장합니다.

useFields: TUseFields<T>;
setValues: IStore<T>["setStore"];
setErrors: IStore<{ [key in keyof T]: string }>["setStore"];

export type TUseFields<T extends InitState> = {
  (): AllFieldsState<T>;
  <K extends ExtractKeys<T>>(name: K): FieldState<T, K>;
  (name: string): FieldStateValue;
}

export type FieldStateValue = {
  value: StoreValue | undefined;
  error: string;
  touched: boolean;
  dirty: boolean;
  isValid: boolean;
}

export interface IStore<T> {
  ...
  setStore: (nextState: Partial<T> & { [x: string]: string | boolean | FileList }) => void;
  ...
}

setValues와 setErrors는 각각 폼 값과 오류 상태를 부분적으로 업데이트할 수 있게 해주며, 이러한 유연한 API 설계 덕분에 전체 폼 상태를 한번에 조회하거나 특정 필드만 선택적으로 관찰할 수 있어 성능 최적화에 도움이 됩니다.

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 함수는 콜백 함수를 인자로 받습니다. 이 콜백 함수는 onSubmit이 발생한 시점의 전체 formState와 이벤트 객체를 인자로 받습니다. 또한 내부적으로 e.preventDefault() 처리가 되어있어 form submit으로 인한 리다이렉트가 발생하지 않습니다.

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

useFields()를 통해 전체 formState를 읽어 직접 submit 로직을 구현할 수도 있습니다. 하지만 handleSubmit을 사용하면 몇 가지 이점을 얻을 수 있습니다.

만약 해결되지 않은 에러 메세지가 하나라도 남아있다면 handleSubmit은 submit을 중지시킵니다. 이를 통해 원치 않는 값이 백엔드로 가는 것을 방지할 수 있습니다.
비슷하게, formController가 관리하는 input이 모두 비어있는 경우에도 submit을 중지시킵니다. 따라서 유저가 실수로 submit 버튼을 눌러도 http 통신이 발생하지 않습니다.

clearFormOn: ["submit"] 옵션이 제공된 상태라도 submit에 실패했다면 form이 초기화되지 않습니다.

handleServerAction#

handleServerAction 메서드는 서버 액션 혹은 서버 함수라고 불리는 상호작용을 처리하며, 폼 데이터 전송 및 응답 처리를 포함합니다. 이 메서드는 서버 측에서 실행되는 비동기 함수와 통합되어, 폼 제출 시점에 서버로 데이터를 전송하고, 서버로부터의 응답을 처리할 수 있도록 설계되었습니다.

사용자는 handleServerAction 메서드에 서버 액션 함수를 인자로 전달하며, 이 함수는 폼 데이터와 이벤트 객체를 받아 서버와의 통신을 수행합니다. 이 과정에서 폼 데이터의 유효성 검사가 자동으로 이루어지며, 검증에 실패할 경우 서버 액션이 호출되지 않습니다. 또한, 이 메서드는 서버로부터의 응답을 처리하는 콜백 함수를 추가로 인자로 받을 수 있어, 성공적인 응답이나 오류 상황에 대한 후속 작업을 쉽게 구현할 수 있습니다.

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"
  >
}

일반적인 서버 액션 함수는 FormData 객체를 인자로 받습니다. 하지만 handleServerAction 메서드는 폼 데이터를 객체 형태로 변환하여 전달합니다. 이는 서버 액션 함수 내에서 폼 데이터를 보다 직관적으로 다룰 수 있게 해주며, FormData 객체를 직접 조작하는 번거로움을 줄여줍니다. 또한, 이벤트 객체도 함께 전달되어 폼 제출과 관련된 추가적인 컨텍스트 정보를 활용할 수 있습니다.

"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);
  }
}

이러한 설계를 통해 handleServerAction 메서드는 폼 제출과 서버 통신을 간소화하고, 개발자가 서버와의 상호작용을 보다 효율적으로 관리할 수 있도록 돕습니다.

useFields#

useFields 훅은 개별 필드의 상태를 선택적으로 구독할 수 있는 기능입니다. 이 훅을 사용하면 전체 폼 상태가 아닌 특정 필드의 값이나 오류만 구독할 수 있어, 불필요한 리렌더링을 방지하고 성능을 최적화할 수 있습니다.

export default function MySimpleForm() {
  const { useRegister, handleSubmit, useFields } = useForm({
    initValue: {
      name: '',
      email: ''
    },
    validator: {
      name: {
        required: { required: true, message: 'name is required' }
      },
      email: {
        required: { required: true, message: 'email is required' },
        RegExp: {
          RegExp: /^[a-zA-Z0-9+-_.]+@[a-zA-Z0-9-]+.[a-zA-Z0-9-.]+$/,
          message: 'email format is invalid'
        }
      }
    }
  });

  const onSubmit = (data) => {
    console.log('data:', data);
  };

  // useFields를 사용하여 개별 필드 상태 구독
  const nameField = useFields('name');
  const emailField = useFields('email');

  return (
    <form onSubmit={handleSubmit(onSubmit)}>
      <div>
        <label htmlFor="name">name:</label>
        <input id="name" {...useRegister('name', { type: 'text' })} />
        {/* nameField.error를 통해 해당 필드의 오류만 접근 */}
        {nameField.error}
      </div>

      <div>
        <label htmlFor="email">email:</label>
        <input id="email" {...useRegister('email', { type: 'email' })} />
        {/* emailField.error를 통해 해당 필드의 오류만 접근 */}
        {emailField.error}
      </div>

      <button type="submit">login</button>
    </form>
  );
}

useFields 훅은 필드 이름을 인자로 받아 해당 필드의 상태 객체를 반환합니다. 반환된 객체에는 value, error, touched, dirty, isValid가 포함됩니다. 이를 통해 컴포넌트는 전역 폼 상태에 직접 접근하지 않고도 필요한 필드 정보만 선택적으로 사용할 수 있습니다.

성능 최적화: useFields(name)는 특정 필드만 구독하므로, 해당 필드가 변경될 때만 컴포넌트가 리렌더링됩니다. 이를 통해 전체 폼 상태 변경으로 인한 불필요한 리렌더링을 효과적으로 방지할 수 있습니다.
타입 안전성: TypeScript 환경에서 useFields는 필드 이름을 기반으로 정확한 타입 추론을 제공합니다. 잘못된 필드 이름을 사용하면 컴파일 시점에 오류가 발생하여 런타임 오류를 미리 방지할 수 있습니다.
편리한 사용법: useFields가 반환하는 상태 객체는 해당 필드의 값/오류/메타 정보를 포함하므로, 별도의 상태 관리 로직 없이도 간단하게 상태를 표시할 수 있습니다.