sales-frontend-components 3.0.9 → 4.0.0

package/dist/index.d.ts

@@ -104,6 +104,25 @@ interface StepIndicatorProps {
 
 declare const StepIndicator: ({ items, onClickItem, currentIndex, defaultValue, dotCount, isLoading }: StepIndicatorProps) => react_jsx_runtime.JSX.Element;
 
+/**
+ * 촬영으로 확보한 단일 이미지 원천입니다.
+ * 화면 표시(`uri`)와 후속 `File` 변환 방식(`kind`)을 함께 보관해, 가공 시점을 호출부가 자유롭게 결정할 수 있게 합니다.
+ * - `file`: 웹 input / video 캡처처럼 이미 `File`을 확보한 경우입니다.
+ * - `scheme`: Android 네이티브가 반환한 scheme URL 입니다.
+ * - `base64`: iOS 네이티브 세션 pull 로 받은 base64 data URL 입니다.
+ */
+type CapturedSource = {
+    kind: 'file';
+    file: File;
+    uri: string;
+} | {
+    kind: 'scheme';
+    uri: string;
+} | {
+    kind: 'base64';
+    uri: string;
+};
+
 /**
  * 카메라 훅이 화면에 표시하는 첨부 이미지 메타데이터입니다.
  * 실제 업로드용 원본 `File` 자체가 아니라, 목록 렌더링과 삭제 처리를 위한 식별자/미리보기 정보를 담습니다.
@@ -116,6 +135,17 @@ interface AttachedPhoto {
     /** 화면에 함께 표시할 파일명입니다. 없으면 UI에서 이름 표시를 생략할 수 있습니다. */
     name?: string;
 }
+/**
+ * 카메라 촬영을 수행할 엔진 종류입니다.
+ * `native`는 앱 브리지(멀티페이지 documentCapture), `input`은 웹 파일 input, `video`는 WebRTC video 태그 기반 촬영을 의미합니다.
+ */
+type CaptureEngineType = 'native' | 'input' | 'video';
+/**
+ * 촬영 이미지의 리사이즈(가공) 시점입니다.
+ * - `onCapture`: 촬영 즉시 리사이즈하여 가공본을 썸네일로 저장합니다. (기존 `useCamera`/V1 동작)
+ * - `onRetrieve`: 원본을 즉시 썸네일로 표시하고, `getImage` 호출 시점에 리사이즈합니다. (기존 `useCameraV2`/V2 동작)
+ */
+type ResizeTiming = 'onCapture' | 'onRetrieve';
 /**
  * `useCamera` 훅 동작을 제어하는 옵션입니다.
  * 호출부에서 첨부 UI 노출 방식, 카메라 실행 방식, 변환/리사이즈 정책을 함께 정의할 때 사용합니다.
@@ -134,7 +164,25 @@ interface cameraOptions {
     onChange?: (file: File) => void;
     /** 사용자가 기존 첨부 사진을 삭제했을 때 호출되는 콜백입니다. 전달값은 삭제된 사진의 `id`입니다. */
     onDelete?: (id: string) => void;
-    /** 앱 환경에서 브리지 기반 네이티브 카메라/문서 캡처를 사용할지 여부입니다. */
+    /**
+     * 카메라 촬영에 사용할 엔진입니다.
+     * 값이 없으면 기존 호환성을 위해 `useNativeCamera` 값으로 `native` 또는 `input`을 결정합니다.
+     */
+    captureEngineType?: CaptureEngineType;
+    /**
+     * 촬영 이미지 리사이즈(가공) 시점입니다. 값이 없으면 `onCapture`(V1 동작)로 동작합니다.
+     * `useCameraV2` 동작이 필요하면 `onRetrieve`를 사용합니다.
+     */
+    resizeTiming?: ResizeTiming;
+    /**
+     * 네이티브 멀티페이지 촬영 시 최대 촬영 장수입니다. 1 ~ 20 범위로 clamp 되며 기본값은 1 입니다.
+     * V1/V2 래퍼는 항상 1로 고정되어 기존 단일 촬영 동작을 유지합니다.
+     */
+    pageLimit?: number;
+    /**
+     * 앱 환경에서 브리지 기반 네이티브 카메라/문서 캡처를 사용할지 여부입니다.
+     * @deprecated 신규 구현에서는 `captureEngineType: 'native'` 또는 `'input'`을 사용하세요.
+     */
     useNativeCamera?: boolean;
     /** 웹 `input[type="file"]` 사용 시 앨범/파일 선택 없이 카메라 촬영만 허용할지 여부입니다. */
     cameraOnly: boolean;
@@ -150,6 +198,21 @@ interface cameraOptions {
      * `fetch`, `xhr`, `canvas` 중 환경 제약과 호환성에 맞는 전략을 선택할 수 있습니다.
      */
     convertType: 'fetch' | 'xhr' | 'canvas';
+    /**
+     * 첨부 가능한 최대 사진 개수입니다.
+     * 지정하지 않으면 `type === 'single'`은 1, 그 외에는 `Math.max(4, pageLimit ?? 1)`로 계산됩니다.
+     */
+    maxPhotos?: number;
+    /**
+     * `maxPhotos`를 초과하는 입력이 들어왔을 때 동작입니다.
+     * 지정하지 않으면 `maxPhotosErrorHandler`가 있을 때 `'error'`, 없으면 `'truncate'`로 동작합니다.
+     */
+    overMaxPhotosBehavior?: OverMaxPhotosBehavior;
+    /**
+     * `maxPhotos` 초과 시 호출되는 핸들러입니다. 전달된 원본 데이터는 가공 없이 그대로 흘려보냅니다.
+     * 핸들러가 호출되면 훅은 해당 입력을 첨부 목록에 등록하지 않습니다.
+     */
+    maxPhotosErrorHandler?: (overflow: MaxPhotosOverflowInfo) => void;
     /** 첨부 후 이미지 크기와 용량을 줄이기 위한 리사이즈 옵션입니다. */
     resize?: {
         /** 반복 축소 시 한 번에 줄일 비율입니다. `5`면 매 반복마다 약 5%씩 축소합니다. */
@@ -171,10 +234,68 @@ interface AddImageInfo {
     data: Blob | string;
     name?: string;
 }
+/**
+ * 최대 첨부 개수 초과 시 동작 방식입니다.
+ * - `truncate`: 남은 슬롯 수만큼만 자르고 등록합니다.
+ * - `error`: 등록하지 않고 `maxPhotosErrorHandler`를 호출합니다.
+ */
+type OverMaxPhotosBehavior = 'truncate' | 'error';
+/**
+ * 최대 첨부 개수 초과를 발생시킨 입력 경로입니다.
+ */
+type MaxPhotosOverflowSource = 'input' | 'video' | 'native' | 'addImage';
+/**
+ * 최대 첨부 개수 초과 시 에러 핸들러에 전달되는 정보입니다.
+ * `data`는 각 경로에서 받은 원본 형태를 그대로 흘려보냅니다.
+ */
+type MaxPhotosOverflowInfo = {
+    source: 'input';
+    /** 현재 첨부된 사진 수 */
+    current: number;
+    /** 허용된 최대 첨부 수 */
+    max: number;
+    /** 이번에 추가하려던 항목 수 */
+    attempted: number;
+    /** input[type=file]에서 선택된 원본 File 배열 */
+    data: File[];
+} | {
+    source: 'video';
+    current: number;
+    max: number;
+    attempted: number;
+    /** Video 모달에서 촬영된 원본 File 배열 */
+    data: File[];
+} | {
+    source: 'native';
+    current: number;
+    max: number;
+    attempted: number;
+    /** 브리지에서 반환된 원본 CapturedSource 배열 */
+    data: CapturedSource[];
+} | {
+    source: 'addImage';
+    current: number;
+    max: number;
+    attempted: number;
+    /** addImage 호출 시 전달된 원본 AddImageInfo 배열 */
+    data: AddImageInfo[];
+};
 
-declare function useCamera({ onChange, resize: resizeOption, cameraOnly, onDelete, show, type, buttonText, initData, useNativeCamera, responseFileType, convertType }?: Partial<cameraOptions>): {
-    onClick: () => void;
+/**
+ * 첨부형 카메라 UI와 촬영/파일 선택 로직을 제공하는 훅입니다. (V1)
+ *
+ * 내부적으로 `useCameraV3`를 호출하며, 기존 호환성을 위해 다음을 고정합니다.
+ * - `resizeTiming: 'onCapture'` : 촬영 즉시 가공 후 가공본을 썸네일로 저장합니다.
+ * - `getImage` : 기존 동기 시그니처를 유지합니다.
+ *
+ * `pageLimit` 기본값은 1이며, 멀티페이지 촬영이 필요하면 2 이상(최대 20)을 전달할 수 있습니다.
+ *
+ * @param options 카메라 동작 옵션입니다.
+ * @returns 첨부 UI 컴포넌트와 첨부 제어 함수들입니다.
+ */
+declare function useCamera(options?: Partial<cameraOptions>): {
     getImage: (imageId: string) => AttachedPhoto | undefined;
+    onClick: () => void;
     deleteImage: (imageId: string) => void;
     deleteAllImages: () => void;
     attachedPhotos: AttachedPhoto[];
@@ -182,13 +303,59 @@ declare function useCamera({ onChange, resize: resizeOption, cameraOnly, onDelet
     addImage: (data: AddImageInfo[]) => void;
 };
 
-declare function useCameraV2({ onChange, resize: resizeOption, cameraOnly, onDelete, show, type, buttonText, initData, useNativeCamera, responseFileType, convertType }: cameraOptions): {
+/**
+ * 이미지 URL 중심으로 첨부 상태를 관리하는 카메라 훅입니다. (V2)
+ *
+ * 내부적으로 `useCameraV3`를 호출하며, 기존 호환성을 위해 다음을 고정합니다.
+ * - `resizeTiming: 'onRetrieve'` : 원본을 즉시 썸네일로 표시하고 `getImage` 호출 시점에 가공합니다.
+ * - `getImage` : 기존 비동기 시그니처를 그대로 유지합니다.
+ *
+ * `pageLimit` 기본값은 1이며, 멀티페이지 촬영이 필요하면 2 이상(최대 20)을 전달할 수 있습니다.
+ *
+ * @param options 카메라 동작 옵션입니다.
+ * @returns 첨부 UI 컴포넌트와 첨부 제어 함수들입니다.
+ */
+declare function useCameraV2(options: cameraOptions): {
     onClick: () => void;
-    getImage: (imageId: string) => Promise<{
-        src: string;
-        id: string;
-        name?: string;
-    }>;
+    getImage: (imageId: string) => Promise<AttachedPhoto>;
+    deleteImage: (imageId: string) => void;
+    deleteAllImages: () => void;
+    attachedPhotos: AttachedPhoto[];
+    Attachment: () => react_jsx_runtime.JSX.Element;
+    addImage: (data: AddImageInfo[]) => void;
+};
+
+/**
+ * `useCamera`(V1) / `useCameraV2`(V2)를 통합한 카메라 훅입니다.
+ *
+ * - 캡처 엔진: `captureEngineType`(`native` 멀티페이지 / `input` / `video`)으로 선택합니다.
+ * - 가공 시점: `resizeTiming`(`onCapture` V1식 / `onRetrieve` V2식)으로 선택합니다.
+ * - 촬영 장수: `pageLimit`(1~20)으로 네이티브 멀티페이지 장수를 선택합니다.
+ *
+ * ### `maxPhotos` × `pageLimit` 누적 동작 (`type`이 `'multiple'` / `'linear'`)
+ * 한 번의 `onClick` 호출은 최대 `pageLimit` 장을 캡처하고, 결과는 기존 첨부 목록에 누적됩니다.
+ * 누적 총량은 `maxPhotos`로 제한됩니다.
+ *
+ * 예) `maxPhotos: 10`, `pageLimit: 5` → 5장씩 두 번 촬영하면 총 10장이 채워집니다.
+ * - 1차: current=0, remaining=10-0=10 → 5장 전부 통과 (총 5장)
+ * - 2차: current=5, remaining=10-5=5  → 5장 전부 통과 (총 10장)
+ * - 3차: remaining=0 → 등록 차단. `maxPhotosErrorHandler`가 있고
+ *   `overMaxPhotosBehavior`가 `'error'`(기본)면 핸들러 호출, `'truncate'`면 조용히 잘립니다.
+ *
+ * ### 주의 사항 (조합에 따른 동작 차이)
+ * 1. `type === 'single'`이면 매번 마지막 1장으로 덮어써 누적되지 않습니다. (`storeCapturedSources` 참고)
+ * 2. 한 번에 남은 슬롯보다 더 많이 들어오면(예: 2차에 6장):
+ *    - `maxPhotosErrorHandler` 등록 + `'error'` 모드 → 6장 전부 등록 거부 후 핸들러 호출
+ *    - `'truncate'` 모드 → 남은 슬롯(5장)만 잘라 등록 → 총 10장
+ *    - 기본 `overMaxPhotosBehavior`는 핸들러 유무로 결정됩니다(`maxPhotosErrorHandler`가 있으면 `'error'`).
+ * 3. `captureEngineType === 'video'`도 동일 흐름입니다.
+ *    `VideoCaptureModal`에 `maxShots={pageLimit}`이 전달되어 같은 `storeCapturedSources` 경로로 누적됩니다.
+ *
+ * 공개 API는 단일·자기완결 형태(`getImage`는 항상 비동기)라, 추후 V1/V2 래퍼를 제거해도 단독으로 동작합니다.
+ */
+declare function useCameraV3({ onChange, resize: resizeOption, cameraOnly, onDelete, show, type, buttonText, initData, captureEngineType, resizeTiming, pageLimit, useNativeCamera, convertType, maxPhotos, overMaxPhotosBehavior, maxPhotosErrorHandler }?: Partial<cameraOptions>): {
+    onClick: () => void;
+    getImage: (imageId: string) => Promise<AttachedPhoto>;
     deleteImage: (imageId: string) => void;
     deleteAllImages: () => void;
     attachedPhotos: AttachedPhoto[];
@@ -213,8 +380,13 @@ interface AttachmentProps {
     show: boolean;
     type?: cameraItemType;
     buttonText?: string;
+    /**
+     * 첨부 가능한 최대 사진 개수입니다. 추가 버튼 노출 여부와 카운터 표기에 사용합니다.
+     * 지정하지 않으면 `type === 'single'`은 1, 그 외에는 4로 동작해 기존 호환성을 유지합니다.
+     */
+    maxPhotos?: number;
 }
-declare function Attachment({ photos, onAddPhoto, onRemovePhoto, show, type, buttonText }: AttachmentProps): react_jsx_runtime.JSX.Element | null;
+declare function Attachment({ photos, onAddPhoto, onRemovePhoto, show, type, buttonText, maxPhotos }: AttachmentProps): react_jsx_runtime.JSX.Element | null;
 
 interface Pen {
     /** 펜 굵기 */
@@ -373,6 +545,8 @@ interface UseCustomerSearchReturn {
     searchInput: string;
     customerList: CustomerDto[];
     searchKeyword: string;
+    /** 검색 API 요청 중 여부 */
+    isLoading: boolean;
     onSearchInputChange: (e: React.ChangeEvent<HTMLInputElement>) => void;
     onKeyUp: (e: React.KeyboardEvent<HTMLInputElement>) => void;
     search: () => void;
@@ -1134,5 +1308,5 @@ interface UseTermsReturn<T> {
  */
 declare function useTerms<T extends object>(initialValue: T): UseTermsReturn<T>;
 
-export { AUTH_TEMPLATE_CODES, Attachment, BANK_STOCK_ICON_LIST, BANK_STOCK_SEARCH_MODAL_TABS, BankStockSearchModal, CustomerSearch, CustomerSearchModal, DeaCustomerSearchModal, DudDownload, DudUpload, EmployeeSearchModal, GtmIframe, HookFormCheckbox, HookFormCheckboxButton, HookFormDatePickerRenew, HookFormDateRangePickerRenew, HookFormSearchJobField, HookFormSegmentGroup, HookFormSelect, HookFormTextField, JobVehicleSearchModal, OrganizationSearchModal, RATING_DATA, RIV_SEARCH_PARAM_MAP, RemoteIdentityVerification, RivModalIframe, StepIndicator, TermsCancerCollectQR, TermsCancerMarketing, TermsCancerProvideQR, TermsCancerSystem, TermsCheckboxButton, TermsDesign, TermsExecution, TermsLoan, TermsMarketing, TermsMarketingCollectQR, TermsMarketingProviderQR, TermsMobileCard, TermsRadio, TermsRatingBar, TermsSignature, TermsTransfer, VERIFICATION_CODES, highlightOnSearchKeyword, resize, testSignatureBase64Data, useAddressComponent, useBankStockSearch, useCamera, useCameraV2, useCanvasPaint, useCustomerSearch, useDownloader, useJobSearchModal, useJobVehicleSearch, useJobVehicleSearchModal, useNationalityComponent, useNxlOneModal, useRemoteIdentityVerification, useRemoteIdentityVerificationIframe, useSearchAddress, useSearchNationality, useSearchVisa, useTerms, useVisaComponent };
-export type { AddImageInfo, AttachedPhoto, AttachmentProps, AuthCodeSet, AuthStep, BankStockSearchModalProps, BaseTermsProps, CustomerSearchProps, DownloadProps, DownloadTargetInfo, DownloaderProps, FormFactor, HookFormCheckboxButtonProps, HookFormCheckboxProps, HookFormDatePickerRenewProps, HookFormDateRangePickerRenewProps, HookFormSearchJobFieldProps, HookFormSegmentGroupProps, HookFormSelectProps, HookFormTextFieldProps, InitSearchParams, PaintProps, Pen, RemoteIdentityVerificationProps, RemoteIdentityVerificationSuccess, RemoteIdentityVerificationViewForwardProps, RemoteIdentityVerificationViewProps, RivModalIframeProps, RivModalIframeReturnProps, RivUrlParams, SearchInputProps, StepIndicatorProps, StepItem, TermsCancerMarketingData, TermsCancerMarketingProps, TermsCancerSystemData, TermsCancerSystemDataProps, TermsDesignData, TermsDesignProps, TermsExecutionData, TermsExecutionProps, TermsLoanData, TermsLoanDataProps, TermsMarketingData, TermsMarketingProps, TermsRadioOption, TermsRatingType, TermsSignatureData, UseRemoteIdentityVerificationProps, UseRemoteIdentityVerificationReturn, UseTermsReturn, Vehicle, VerificationResponse, cameraItemType, cameraOptions };
+export { AUTH_TEMPLATE_CODES, Attachment, BANK_STOCK_ICON_LIST, BANK_STOCK_SEARCH_MODAL_TABS, BankStockSearchModal, CustomerSearch, CustomerSearchModal, DeaCustomerSearchModal, DudDownload, DudUpload, EmployeeSearchModal, GtmIframe, HookFormCheckbox, HookFormCheckboxButton, HookFormDatePickerRenew, HookFormDateRangePickerRenew, HookFormSearchJobField, HookFormSegmentGroup, HookFormSelect, HookFormTextField, JobVehicleSearchModal, OrganizationSearchModal, RATING_DATA, RIV_SEARCH_PARAM_MAP, RemoteIdentityVerification, RivModalIframe, StepIndicator, TermsCancerCollectQR, TermsCancerMarketing, TermsCancerProvideQR, TermsCancerSystem, TermsCheckboxButton, TermsDesign, TermsExecution, TermsLoan, TermsMarketing, TermsMarketingCollectQR, TermsMarketingProviderQR, TermsMobileCard, TermsRadio, TermsRatingBar, TermsSignature, TermsTransfer, VERIFICATION_CODES, highlightOnSearchKeyword, resize, testSignatureBase64Data, useAddressComponent, useBankStockSearch, useCamera, useCameraV2, useCameraV3, useCanvasPaint, useCustomerSearch, useDownloader, useJobSearchModal, useJobVehicleSearch, useJobVehicleSearchModal, useNationalityComponent, useNxlOneModal, useRemoteIdentityVerification, useRemoteIdentityVerificationIframe, useSearchAddress, useSearchNationality, useSearchVisa, useTerms, useVisaComponent };
+export type { AddImageInfo, AttachedPhoto, AttachmentProps, AuthCodeSet, AuthStep, BankStockSearchModalProps, BaseTermsProps, CaptureEngineType, CapturedSource, CustomerSearchProps, DownloadProps, DownloadTargetInfo, DownloaderProps, FormFactor, HookFormCheckboxButtonProps, HookFormCheckboxProps, HookFormDatePickerRenewProps, HookFormDateRangePickerRenewProps, HookFormSearchJobFieldProps, HookFormSegmentGroupProps, HookFormSelectProps, HookFormTextFieldProps, InitSearchParams, MaxPhotosOverflowInfo, MaxPhotosOverflowSource, OverMaxPhotosBehavior, PaintProps, Pen, RemoteIdentityVerificationProps, RemoteIdentityVerificationSuccess, RemoteIdentityVerificationViewForwardProps, RemoteIdentityVerificationViewProps, ResizeTiming, RivModalIframeProps, RivModalIframeReturnProps, RivUrlParams, SearchInputProps, StepIndicatorProps, StepItem, TermsCancerMarketingData, TermsCancerMarketingProps, TermsCancerSystemData, TermsCancerSystemDataProps, TermsDesignData, TermsDesignProps, TermsExecutionData, TermsExecutionProps, TermsLoanData, TermsLoanDataProps, TermsMarketingData, TermsMarketingProps, TermsRadioOption, TermsRatingType, TermsSignatureData, UseRemoteIdentityVerificationProps, UseRemoteIdentityVerificationReturn, UseTermsReturn, Vehicle, VerificationResponse, cameraItemType, cameraOptions };