🧩 hooks module

React 프로젝트에서 결제 폼을 만들 때 사용할 수 있는 커스텀 훅 모음입니다.
카드 번호, 유효기간, CVC 등 다양한 입력 필드에 대해 유효성 검사와 상태 관리 기능을 함께 제공합니다.

✨ Features

• 카드 정보 입력 필드별 상태 및 유효성 검증 일괄 관리
• 카드 브랜드(VISA, MasterCard 등) 자동 감지
• 타입 안전한 TypeScript 기반
• skipValidation 옵션 제공으로 유연한 상태 업데이트 가능

📦 Installation

npm i @jae-o/hooks-module

🧪 제공 훅 목록

• useCardNumbers: 카드 번호 입력 (3~4칸) 상태 및 검증
• useExpiryDate: 유효기간 (MM/YY) 입력 및 검증
• useCVC: 카드 CVC 입력 및 검증

사용 예시: useCardNumbers

import { useCardNumbers } from '@jae-o/hooks-module';

function CardInputForm() {
  const { cardNumbers, validationResults, cardBrand, handleCardNumbersChange } =
    useCardNumbers([
      { name: 'part1', length: 4 },
      { name: 'part2', length: 4 },
      { name: 'part3', length: 4 },
      { name: 'part4', length: 4 },
    ]);

  return (
    <div>
      {(['part1', 'part2', 'part3', 'part4'] as const).map((key) => (
        <input
          key={key}
          value={cardNumbers[key]}
          onChange={(e) => handleCardNumbersChange(key, e.target.value)}
        />
      ))}
      <p>Detected Brand: {cardBrand}</p>
      <p>Error: {validationResults.part1.errorMessage}</p>
    </div>
  );
}

📘 API Reference

useCardNumbers

• 카드 번호 입력 필드(3~4칸)의 상태와 유효성 검사, 카드 브랜드 감지를 지원합니다.

| 반환값 | 타입 | 설명 | | ------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------- | | cardNumbers | Record<필드이름, string> | 입력된 카드 번호 값들 | | validationResults | Record<필드이름, { isValid: boolean; errorMessage: string }> | 각 필드별 유효성 검사 결과 | | cardBrand | 'VISA' \| 'MASTERCARD' \| 'AMEX' \| 'DINERS' \| 'UNIONPAY' \| 'UNKNOWN' | 카드 브랜드 감지 결과 | | handleCardNumbersChange | ({ key, value, options }: { key: 필드이름; value: string; options?: { skipValidation?: boolean } }) => void | 입력 변경 핸들러 | | getCardNumberValidationError | (key: 필드이름, value: string) => 에러타입 \| null | 카드 번호 조각 유효성 검사 함수 |

옵션 설명

• skipValidation: true로 설정 시 유효성 오류가 있어도 값을 강제로 업데이트합니다. (자동완성, 서버 데이터 주입 시 유용)

useExpiryDate

• 카드 유효기간(MM/YY) 입력을 관리하고, 만료 여부도 검증합니다.

| 반환값 | 타입 | 설명 | | ------------------------------ | ----------------------------------------------- | ------------------------ | | expiryDate | { month: string; year: string } | 월/연도 입력 값 | | validationResults | Record<'month' \| 'year', ValidationResult> | 각 필드 유효성 결과 | | handleExpiryDateChange | (key, value, options?) => void | 월 또는 연도 변경 핸들러 | | getExpiryDateValidationError | (key, value) => 에러타입 \| null | 포맷 검증 함수 | | getExpiryDateExpiredError | (key, value, otherFields) => 에러타입 \| null | 만료 여부 검증 함수 |

useCVC

• 카드 CVC 입력 필드를 관리합니다.

| 반환값 | 타입 | 설명 | | ----------------------- | -------------------------------------------- | ------------------ | | CVC | string | 입력된 CVC 값 | | validationResult | { isValid: boolean; errorMessage: string } | 유효성 검사 결과 | | handleCVCChange | (value, options?) => void | CVC 값 변경 핸들러 | | getCVCValidationError | (value) => 에러타입 \| null | 포맷 검증 함수 |