@ehfuse/mui-form-controls 3.2.9 → 3.3.0

package/dist/types.d.ts

@@ -590,6 +590,39 @@ export type CorpNumTextFieldProps = Omit<TextFieldProps, "type" | "value"> & Bas
     fontColor?: string;
     fontFamily?: string;
 };
+/** 계좌 실명조회 요청 — BankAccountTextField 가 verify 콜백에 넘긴다 */
+export type BankAccountVerifyRequest = {
+    bankCode: string | null;
+    bankName: string | null;
+    accountNumber: string;
+    identityNum?: string;
+};
+/** 계좌 실명조회 결과 — verify 콜백이 돌려준다 */
+export type BankAccountVerifyResult = {
+    ok: boolean;
+    holderName?: string;
+    message?: string;
+};
+/** 계좌 실명조회 진행 상태 */
+export type BankAccountVerifyStatus = "idle" | "loading" | "verified" | "mismatch" | "failed";
+/**
+ * 계좌번호 텍스트 필드 타입
+ */
+export type BankAccountTextFieldProps = Omit<TextFieldProps, "type" | "value"> & BaseTextFieldProps & ValidatableTextFieldProps & {
+    value?: string;
+    bank?: string | null;
+    includeDash?: boolean;
+    copyIcon?: boolean;
+    verify?: (request: BankAccountVerifyRequest) => Promise<BankAccountVerifyResult>;
+    verifyButtonText?: string;
+    identityNum?: string;
+    holderName?: string;
+    autoVerify?: boolean;
+    onVerify?: (result: BankAccountVerifyResult, status: BankAccountVerifyStatus) => void;
+    fontSize?: string | number;
+    fontColor?: string;
+    fontFamily?: string;
+};
 /** CardNumTextField ref — `focus()`는 이어 쓸 위치로, `blur()`는 포커스 해제 */
 export type CardNumTextFieldHandle = {
     focus: () => void;

package/dist/utils/bankAccount.d.ts

@@ -0,0 +1,64 @@
+/**
+ * bankAccount.ts
+ *
+ * 국내 은행 계좌번호 포맷 유틸.
+ *
+ * 계좌번호 자리수·하이픈 위치는 공식 표준이 없다(은행마다, 같은 은행 안에서도 구계좌·신계좌·
+ * 가상계좌·합병 전 계좌마다 다르다). 금융결제원 오픈뱅킹도 계좌번호를 숫자 최대 16자리로만 다룬다.
+ * 그래서 여기서는 (은행, 자리수) 조합별로 알려진 대표 형식을 두고, 모르는 조합은 숫자만 표시한다.
+ * 하이픈은 표시용일 뿐이며 이체·실명조회에는 숫자만 쓴다.
+ *
+ * @license MIT
+ * @copyright 2025 김영진 (Kim Young Jin)
+ * @author 김영진 (ehfuse@gmail.com)
+ */
+/** 계좌번호 최대 자리수(금융결제원 account_num AN(16)) */
+export declare const BANK_ACCOUNT_MAX_LENGTH = 16;
+/** 은행 정보 */
+export type BankInfo = {
+    /** 금융결제원 표준 기관코드(3자리) */
+    code: string;
+    /** 표시 이름 */
+    name: string;
+    /** 다른 표기(구 명칭·약칭) — 이름으로 은행을 찾을 때 쓴다 */
+    aliases?: string[];
+    /**
+     * 하이픈 그룹 목록 (예: [6, 2, 6] = 000000-00-000000, 14자리).
+     * 자리수는 그룹 합으로 정해진다. 첫 번째가 대표(현행) 형식 — 입력 중에는 이것을 따라 나눈다.
+     */
+    formats?: number[][];
+};
+/**
+ * 은행 목록(금융결제원 표준 기관코드). 형식은 첫 번째가 현행 대표 형식이고,
+ * 같은 자리수에 여러 형식이 있는 은행(구계좌 등)은 더 흔한 쪽만 남겼다.
+ * 형식이 없는 은행(전북·경남 등)은 숫자만 표시한다.
+ */
+export declare const BANKS: BankInfo[];
+/**
+ * 은행 코드(3자리, "04"·"4" 같은 짧은 표기 포함) 또는 이름·별칭으로 은행을 찾는다.
+ * 못 찾으면 null.
+ */
+export declare function resolveBank(bank: string | null | undefined): BankInfo | null;
+/** 입력 문자열에서 숫자만 최대 16자리까지 남긴다. */
+export declare function sanitizeBankAccount(raw: string | null | undefined): string;
+/**
+ * 완성된 계좌번호 숫자열의 하이픈 그룹을 구한다. 형식을 모르면 null(숫자만 표시).
+ * @param bank 은행 코드·이름 또는 BankInfo
+ */
+export declare function getBankAccountGroups(bank: string | BankInfo | null | undefined, digits: string): number[] | null;
+/**
+ * 계좌번호를 은행·자리수에 맞게 하이픈으로 포맷한다. 적용 순서:
+ * 1. 자리수에 정확히 맞는 형식(010 11자리 평생계좌 포함)
+ * 2. 입력 중(자리수 모자람): 010 으로 시작하면 휴대폰형, 아니면 대표 형식 앞부분을 따라 나눈다
+ * 3. 그 외(은행 모름·대표 형식보다 김): 숫자만
+ */
+export declare function formatBankAccount(bank: string | BankInfo | null | undefined, raw: string | null | undefined): string;
+/** 그 은행에서 알려진 계좌번호 자리수 목록(오름차순). 모르면 빈 배열. */
+export declare function getBankAccountLengths(bank: string | BankInfo | null | undefined): number[];
+/**
+ * 자리수 기준 형식 검사. 계좌번호에는 공통 검증번호 알고리즘이 없어(은행마다 비공개) 자리수만 본다.
+ * - 은행 형식을 알면: 알려진 자리수 중 하나이거나 평생계좌(010 11자리)면 유효.
+ * - 모르면: 10~16자리면 유효.
+ * 실제 존재·예금주 여부는 실명조회(서버)로만 확인할 수 있다.
+ */
+export declare function isBankAccountLengthValid(bank: string | BankInfo | null | undefined, raw: string | null | undefined): boolean;

package/dist/utils/index.d.ts

@@ -18,3 +18,5 @@ export { validateCardNumber, detectCardBrand } from "./card";
 export type { CardBrand } from "./card";
 export { REGION_MAP, extractJuminInfo, validateJuminChecksum, validateJuminBirthDate, isJuminValueValid, isJuminValueInvalidState, sanitizeJuminFrontBirthDigits, canAppendJuminBirthDigit, maxDayForJuminFrontYyMm, } from "./jumin";
 export { isInteractionLocked, interactionLockSx, withInteractionLockSx, interactionLockInputProps, } from "./readonly";
+export { BANKS, BANK_ACCOUNT_MAX_LENGTH, resolveBank, sanitizeBankAccount, formatBankAccount, getBankAccountGroups, getBankAccountLengths, isBankAccountLengthValid, } from "./bankAccount";
+export type { BankInfo } from "./bankAccount";

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@ehfuse/mui-form-controls",
-    "version": "3.2.9",
+    "version": "3.3.0",
     "description": "Material-UI form controls and text fields for complex forms",
     "private": false,
     "publishConfig": {