sales-frontend-solution 0.0.46 → 0.0.48

package/dist/index.d.ts

@@ -23,14 +23,132 @@ type KeypadSessionType = {
 
 type KeypadType = ReactElement<KeypadFieldType>;
 
-type Props = {
+/**
+ * 키패드 영역 정보
+ */
+interface KeypadRect {
+    /** 키패드 높이 */
+    height: number;
+    /** 키패드 상단 위치 (viewport 기준) */
+    top: number;
+    /** 키패드 하단 위치 (viewport 기준) */
+    bottom: number;
+    /** 키패드 너비 */
+    width: number;
+    /** 키패드 왼쪽 위치 */
+    left: number;
+    /** 키패드 오른쪽 위치 */
+    right: number;
+}
+/**
+ * onShow 콜백 파라미터
+ */
+interface KeypadShowEvent {
+    /** 키패드 표시 여부 */
+    isShow: boolean;
+    /** 키패드 DOM 요소 (열림 상태일 때만 존재) */
+    keypadElement: HTMLElement | null;
+    /** 키패드 영역 정보 (열림 상태일 때만 존재) */
+    keypadRect: KeypadRect | null;
+    /** 입력 필드 DOM 요소 */
+    inputElement: HTMLInputElement;
+}
+/**
+ * Keypad 컴포넌트 Props
+ */
+interface KeypadProps {
+    /** 키패드 세션 값 */
     value: KeypadSessionType | null;
+    /** 입력 엘리먼트 (React Element) */
     inputElement: KeypadType;
+    /** 키패드 모드 (QWERTY_SMART, NUMBER) */
     mode: KeypadModeEnum;
+    /** 값 변경 콜백 */
     onChange: (value: KeypadSessionType | null) => void;
+    /** 최대 입력 길이 */
+    maxLength: number;
+    /**
+     * 키패드 표시 상태 콜백
+     * @param event - 키패드 상태 및 영역 정보 (keypadRect로 직접 레이아웃 처리 가능)
+     */
+    onShow?: (event: KeypadShowEvent) => void;
+    /** 숫자 키 행 수 (기본값: 3) */
+    numberKeyRowCount?: number;
+    /** 키패드가 input을 가릴 때 translateY 처리할 최상위 컨테이너 요소의 ID */
+    wrapId?: string;
+}
+/**
+ * 보안 키패드 컴포넌트
+ *
+ * 한화생명 보안 키패드를 React 컴포넌트로 래핑합니다.
+ * 입력 엘리먼트를 받아 키패드 기능을 추가합니다.
+ *
+ * @example
+ * ```tsx
+ * <Keypad
+ *   value={sessionInfo}
+ *   onChange={setSessionInfo}
+ *   mode={KeypadModeEnum.NUMBER}
+ *   maxLength={6}
+ *   inputElement={<input placeholder="비밀번호 입력" />}
+ *   onShow={({ isShow, keypadElement, keypadRect }) => {
+ *     if (isShow && keypadRect) {
+ *       // 키패드 높이만큼 하단 여백 추가
+ *       document.body.style.paddingBottom = `${keypadRect.height}px`;
+ *     } else {
+ *       document.body.style.paddingBottom = '';
+ *     }
+ *     // 또는 keypadElement를 직접 활용
+ *     console.log('키패드 DOM:', keypadElement);
+ *   }}
+ * />
+ * ```
+ */
+declare function Keypad({ value, onChange, mode, maxLength, inputElement, onShow, numberKeyRowCount, wrapId }: KeypadProps): react_jsx_runtime.JSX.Element;
+
+type KeypadInitializeType = {
+    name: string;
+    editBox: HTMLInputElement;
+    keyType: KeypadModeEnum;
+    width: number;
+    position: {
+        top: number;
+        left: null;
+    };
+    viewType: string;
+    closeDelay: number;
+    autoKeyResize: boolean;
+    isE2E: boolean;
+    onlyMobile: boolean;
+    hasPressEffect: boolean;
     maxLength: number;
+    numberKeyRowCount: number;
+    onInputChange: (newLength: number) => void;
+    onKeypadClose: () => void;
+};
+
+declare enum KeypadMessageTypeEnum {
+    NotSupportDevice = -1,
+    Already = -2
+}
+
+type KeypadActionType = {
+    addIt: (name: string) => void;
+    alert_focus: VoidFunction;
+    alert_hide: VoidFunction;
+    alert_show: VoidFunction;
+    auto_refresh: VoidFunction;
+    refresh: VoidFunction;
+    clear: VoidFunction;
+    close: VoidFunction;
+    enter: VoidFunction;
+    get_Vinput: VoidFunction;
+    get_input: VoidFunction;
+    get_sessionInfo: () => KeypadSessionType;
+    isOpend: () => boolean;
+    isOpen: () => boolean;
+    initialize: (props: KeypadInitializeType) => KeypadMessageTypeEnum;
 };
-declare function Keypad({ value, onChange, mode, maxLength, inputElement }: Props): react_jsx_runtime.JSX.Element;
 
 type KeypadResponseType = {
     length: number;
@@ -40,47 +158,194 @@ type KeypadResponseType = {
     name: string;
 };
 
+/**
+ * useKeypad 훅 반환 타입
+ */
+interface UseKeypadReturn {
+    /** 키패드 표시 */
+    show: (inputRef: HTMLInputElement, onInputChange: (length: number) => void, onKeypadClose: (res: KeypadResponseType) => void, keyType?: KeypadModeEnum, maxLength?: number, numberKeyRowCount?: number) => void;
+    /** 키패드 닫기 */
+    close: (name?: string) => void;
+    /** 키패드 입력 초기화 */
+    clear: (name?: string) => void;
+    /** 키패드 새로고침 */
+    refresh: (name?: string) => void;
+    /** 세션 정보 조회 */
+    getValue: (name: string) => ReturnType<KeypadActionType['get_sessionInfo']> | null | undefined;
+    /** 키패드 열림 상태 확인 */
+    isOpen: (name?: string) => boolean;
+    /** 키패드 인스턴스 찾기 */
+    find: (name?: string) => KeypadActionType | undefined;
+    /** 키패드 표시 상태 */
+    isShow: boolean;
+    /** 현재 키패드 ID (DOM id는 `xk-pad-${keypadId}`) */
+    keypadId: string | null;
+}
+/**
+ * 보안 키패드 훅
+ *
+ * 한화생명 보안 키패드를 React에서 사용하기 위한 커스텀 훅입니다.
+ *
+ * @example
+ * ```tsx
+ * const { show, close, isShow } = useKeypad();
+ *
+ * const handleClick = () => {
+ *   show(
+ *     inputRef.current,
+ *     (length) => console.log('입력 길이:', length),
+ *     (res) => console.log('세션 정보:', res.sessionInfo),
+ *   );
+ * };
+ * ```
+ */
+declare function useKeypad(): UseKeypadReturn;
+
 type KeypadFieldType = {
     ref: React.Ref<any>;
     value: string;
     onClick: () => void;
     onFocus: () => void;
+    isKeypadActive?: boolean;
 };
 
-type NxlOneProps = {
+declare const NXL_ONE_ENV_URLS: {
+    readonly dev: "https://nxl-nlc-dev.hanwhalife.com";
+    readonly stg: "https://nxl-nlc-stg.hanwhalife.com";
+    readonly prd: "https://nxl-nlc.hanwhalife.com";
+};
+type NxlOneEnv = keyof typeof NXL_ONE_ENV_URLS;
+type NxlOneAction = 'error' | 'close' | 'complete';
+type NxlOneResponse = {
+    action?: NxlOneAction;
+    redirectUrl?: string;
+    nlcCtfnId?: string;
+};
+/** NxlOne 에러 코드 값 */
+declare const NXL_ONE_ERROR_CODES: {
+    /** 팝업이 브라우저에 의해 차단됨 */
+    readonly POPUP_BLOCKED: "POPUP_BLOCKED";
+    /** 사용자가 인증을 취소함 */
+    readonly AUTH_CANCELLED: "AUTH_CANCELLED";
+    /** 인증 실패 */
+    readonly AUTH_FAILED: "AUTH_FAILED";
+    /** 잘못된 응답 */
+    readonly INVALID_RESPONSE: "INVALID_RESPONSE";
+};
+/** NxlOne 에러 코드 타입 */
+type NxlOneErrorCode = (typeof NXL_ONE_ERROR_CODES)[keyof typeof NXL_ONE_ERROR_CODES];
+/** NxlOne 에러 객체 */
+type NxlOneError = {
+    /** 에러 코드 */
+    code: NxlOneErrorCode;
+    /** 사용자 친화적 메시지 */
+    message: string;
+};
+/** NxlOne 에러 생성 */
+declare const createNxlOneError: (code: NxlOneErrorCode, customMessage?: string) => NxlOneError;
+/** NxlOneError 타입 가드 */
+declare const isNxlOneError: (value: unknown) => value is NxlOneError;
+
+/** @deprecated NxlOneResponse를 사용하세요 */
+type NxlOneIframeResponse = NxlOneResponse;
+type NxlOneIframeProps = {
+    /** 비즈니스 코드 */
     bizCode: string;
+    /** 템플릿 코드 */
     tmplCode: string;
+    /** NCSR 정보 UUID */
     ncsrInfoUuid?: string;
+    /** NLC 인증 ID */
     nlcCtfnId?: string;
-    t?: string;
-    env?: 'dev' | 'stg' | 'prod';
+    /** 환경 (미지정 시 현재 URL 기반 자동 감지) */
+    env?: NxlOneEnv;
+    /** iframe 너비 (기본: '100%') */
+    width?: number | string;
+    /** iframe 높이 (기본: '100%') */
+    height?: number | string;
+    /** CSS 클래스명 */
+    className?: string;
+    /** 인라인 스타일 */
+    style?: React.CSSProperties;
+    /** iframe allow 속성 */
+    allow?: string;
+    /** iframe sandbox 속성 */
+    sandbox?: string;
+    /** 인증 성공 시 호출 */
+    onSuccess?: (response: NxlOneResponse) => void;
+    /** 에러 발생 시 호출 */
+    onError?: (response: NxlOneResponse) => void;
+    /** 닫기 시 호출 */
+    onClose: (response: NxlOneResponse) => void;
+    /** origin 검증 여부 (기본: true) */
+    strictOrigin?: boolean;
+    /** 콜백 호출 시 자동으로 iframe 숨김 (기본: false) */
+    autoHide?: boolean;
 };
-type NxlOneResponse = {
-    action?: 'error' | 'close' | 'complete';
-    redirectUrl?: string;
+/**
+ * NEXTLAB ONE 인증을 위한 Iframe 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * <NxlOneIframe
+ *   bizCode="BIZ001"
+ *   tmplCode="TMPL001"
+ *   env="dev"
+ *   autoHide
+ *   onSuccess={(res) => console.log("성공", res)}
+ *   onError={(res) => console.log("에러", res)}
+ *   onClose={(res) => console.log("닫기", res)}
+ * />
+ * ```
+ */
+declare function NxlOneIframe({ bizCode, tmplCode, ncsrInfoUuid, nlcCtfnId, env, width, height, className, style, allow, sandbox, onSuccess, onError, onClose, strictOrigin, autoHide }: NxlOneIframeProps): react_jsx_runtime.JSX.Element | null;
+
+type NxlOneProps = {
+    /** 비즈니스 코드 */
+    bizCode: string;
+    /** 템플릿 코드 */
+    tmplCode: string;
+    /** NCSR 정보 UUID */
+    ncsrInfoUuid?: string;
+    /** NLC 인증 ID */
     nlcCtfnId?: string;
+    /** 환경 (미지정 시 현재 URL 기반 자동 감지) */
+    env?: NxlOneEnv;
 };
-type OpenOptionType = {
-    popupWidth?: number;
-    popupHeight?: number;
-    popupLeft?: number;
-    popupTop?: number;
+
+type PopupOptions = {
+    /** 팝업 너비 (기본: 744) */
+    width?: number;
+    /** 팝업 높이 (기본: 720) */
+    height?: number;
+    /** 팝업 X 위치 (기본: 화면 중앙) */
+    left?: number;
+    /** 팝업 Y 위치 (기본: 화면 중앙) */
+    top?: number;
+    /** 팝업 창 이름 (기본: "self_cert") */
     windowName?: string;
 };
-declare function useNxlOne({ bizCode, tmplCode, ncsrInfoUuid, nlcCtfnId, t }: NxlOneProps): {
+/**
+ * NEXTLAB ONE 인증을 위한 훅
+ *
+ * @example
+ * ```tsx
+ * const { redirect, open } = useNxlOne({
+ *   bizCode: "BIZ001",
+ *   tmplCode: "TMPL001",
+ *   env: "dev",
+ * });
+ *
+ * // 리다이렉트 방식
+ * <button onClick={redirect}>인증하기</button>
+ *
+ * // 팝업 방식
+ * <button onClick={() => open().then(console.log)}>팝업으로 인증</button>
+ * ```
+ */
+declare function useNxlOne({ bizCode, tmplCode, ncsrInfoUuid, nlcCtfnId, env }: NxlOneProps): {
     redirect: () => void;
-    open: (options?: OpenOptionType) => Promise<NxlOneResponse>;
-    Iframe: ({ height, className, style, allow, sandbox, onSuccess, onError, onClose, strictOrigin }: {
-        height?: number | string;
-        className?: string;
-        style?: React.CSSProperties;
-        allow?: string;
-        sandbox?: string;
-        onSuccess?: (response: NxlOneResponse) => void;
-        onError?: (response: NxlOneResponse) => void;
-        onClose: (response: NxlOneResponse) => void;
-        strictOrigin?: boolean;
-    }) => react_jsx_runtime.JSX.Element;
+    open: (options?: PopupOptions) => Promise<NxlOneResponse>;
 };
 
-export { Keypad, type KeypadFieldType, KeypadModeEnum, type KeypadResponseType, type KeypadSessionType, type KeypadType, type NxlOneProps, type NxlOneResponse, V3Provider, useNxlOne, useV3 };
+export { Keypad, type KeypadFieldType, KeypadModeEnum, type KeypadProps, type KeypadRect, type KeypadResponseType, type KeypadSessionType, type KeypadShowEvent, type KeypadType, NXL_ONE_ERROR_CODES, type NxlOneAction, type NxlOneEnv, type NxlOneError, type NxlOneErrorCode, NxlOneIframe, type NxlOneIframeProps, type NxlOneIframeResponse, type NxlOneProps, type NxlOneResponse, type PopupOptions, type UseKeypadReturn, V3Provider, createNxlOneError, isNxlOneError, useKeypad, useNxlOne, useV3 };