@uniai-fe/uds-primitives 0.2.4 → 0.2.5

package/dist/styles.css

@@ -2366,6 +2366,62 @@ figure.chip {
   width: 100%;
 }
 
+.input-file-drag-and-drop {
+  width: 100%;
+  border: 1px dashed var(--input-border-color);
+  border-radius: var(--input-default-radius-base);
+  background-color: var(--input-surface-color);
+  transition: border-color 0.2s ease, background-color 0.2s ease;
+}
+.input-file-drag-and-drop[data-dragging=true] {
+  border-color: var(--input-border-active-color);
+  background-color: var(--input-surface-muted-color);
+}
+.input-file-drag-and-drop[data-disabled=true] {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+
+.input-file-list-container {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+}
+
+.input-file-list-header {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+}
+.input-file-list-header[data-trigger=true] {
+  cursor: pointer;
+}
+
+.input-file-list-body {
+  width: 100%;
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+}
+
+.input-file-list-item {
+  width: 100%;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: 8px;
+}
+
+.input-file-list-remove {
+  border: 0;
+  padding: 0;
+  background: transparent;
+  color: inherit;
+  cursor: pointer;
+}
+
 /* Select tokens mapped to Input primary tokens for visual parity */
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

package/src/components/input/hooks/index.ts

@@ -1,2 +1,5 @@
 export { useDigitField } from "./useDigitField";
 export { useAddress, useAddressFields } from "./useAddress";
+export { useInputFile } from "./useInputFile";
+export { useInputFileContext } from "./useInputFileContext";
+export { useInputFileRHF } from "./useInputFileRHF";

package/src/components/input/hooks/useInputFile.ts

@@ -0,0 +1,254 @@
+"use client";
+
+import { useCallback, useRef, useState } from "react";
+import type { DragEvent, SyntheticEvent, ChangeEvent } from "react";
+import type { UseInputFileOptions, UseInputFileResult } from "../types";
+
+/**
+ * Input Hook; File Upload 이벤트 제어 Hook
+ * @hook
+ * @param {UseInputFileOptions} options file upload 옵션
+ * @param {InputFileChangeHandler} options.onFilesChange 파일 변경 콜백
+ * @param {RefObject<HTMLInputElement | null>} [options.inputRef] 직접 제어할 file input ref
+ * @param {string} [options.selectorId] inputRef가 없을 때 조회할 input id
+ * @param {boolean} [options.disabled=false] 동작 비활성화 여부
+ * @param {boolean} [options.resetInputValue=true] 등록 후 input 값을 비울지 여부
+ * @returns {UseInputFileResult} file 업로드 핸들러 묶음
+ * @desc
+ * - return.state: { isDragging, selectedFiles, hasSelectedFiles }
+ * - return.input: { onOpenFileDialog, onInputFileChange }
+ * - return.dragdrop: { onDropFiles, onDragEnter, onDragOver, onDragLeave }
+ * - return.helper: { onClearSelectedFiles }
+ * @example
+ * ```ts
+ * // 1) input element ref 준비
+ * const inputRef = useRef<HTMLInputElement | null>(null);
+ *
+ * // 2) 파일 이벤트 제어 훅 연결
+ * const fileUpload = useInputFile({
+ *   inputRef,
+ *   onFilesChange: (files, source) => {
+ *     console.log(source, files);
+ *   },
+ * });
+ *
+ * // 3) 업로드 트리거 + input change 연결
+ * <input ref={inputRef} type="file" hidden onChange={fileUpload.onInputFileChange} />
+ * <Input.File.UploadButton onOpenFileDialog={fileUpload.onOpenFileDialog}>
+ *   파일 선택
+ * </Input.File.UploadButton>
+ *
+ * // 4) 목록 렌더링 시 key는 안정적인 식별자(id) + depth 포맷을 사용
+ * fileContext.fileMetas.map(meta => (
+ *   <Input.File.List.Item key={`input/file/list/item/${meta.id}`}>
+ *     {meta.name}
+ *   </Input.File.List.Item>
+ * ));
+ * ```
+ */
+export const useInputFile = ({
+  onFilesChange,
+  inputRef,
+  selectorId,
+  disabled = false,
+  resetInputValue = true,
+}: UseInputFileOptions): UseInputFileResult => {
+  /**
+   * Input Hook; File Upload 드래그 오버 상태
+   */
+  // dragenter/dragleave/drop 이벤트에 따라 drop zone 시각 상태를 제어한다.
+  const [isDragging, setIsDragging] = useState(false);
+  /**
+   * Input Hook; File Upload 최근 선택 파일 상태
+   */
+  // input change 또는 drop으로 유입된 최신 파일 배열을 보관한다.
+  const [selectedFiles, setSelectedFiles] = useState<File[]>([]);
+  /**
+   * Input Hook; File Upload dragenter/dragleave depth 추적 ref
+   */
+  // 중첩 DOM에서 연속 발생하는 drag 이벤트를 안정적으로 계산하기 위한 depth 카운터다.
+  const dragDepthRef = useRef(0);
+
+  /**
+   * Input Hook; File Upload input element 조회
+   */
+  const resolveInputElement = useCallback(() => {
+    // 우선순위 1: 소비자가 직접 전달한 ref를 그대로 사용한다.
+    if (inputRef?.current) {
+      return inputRef.current;
+    }
+    // 우선순위 2: selectorId 기반으로 DOM을 조회한다.
+    if (!selectorId || typeof document === "undefined") {
+      // selectorId가 없거나 SSR 환경이면 조회할 수 없으므로 null을 반환한다.
+      return null;
+    }
+    // selectorId가 있으면 file input element를 querySelector로 찾는다.
+    return document.querySelector<HTMLInputElement>(`#${selectorId}`);
+  }, [inputRef, selectorId]);
+
+  /**
+   * Input Hook; File Upload 파일 선택창 열기 핸들러
+   * @param {SyntheticEvent<HTMLElement>} [event] 파일 선택창 오픈 트리거 이벤트
+   */
+  const onOpenFileDialog = useCallback(
+    (event?: SyntheticEvent<HTMLElement>) => {
+      // 버튼 클릭 시 기본 submit/navigation 동작을 방지한다.
+      event?.preventDefault();
+      // 비활성화 상태거나 window가 없는 환경(SSR)에서는 즉시 중단한다.
+      if (disabled || typeof window === "undefined") {
+        return;
+      }
+      // 현재 연결 가능한 file input element를 조회한다.
+      const inputElement = resolveInputElement();
+      // native file dialog를 열기 위해 input.click()을 호출한다.
+      inputElement?.click();
+    },
+    [disabled, resolveInputElement],
+  );
+
+  /**
+   * Input Hook; File Upload input change 등록 핸들러
+   * @param {ChangeEvent<HTMLInputElement>} event file input change 이벤트
+   */
+  const onInputFileChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      // disabled 상태에서는 입력 이벤트를 무시한다.
+      if (disabled) {
+        return;
+      }
+      // change 이벤트에서 FileList를 읽는다.
+      const files = event.currentTarget.files;
+      // FileList가 비었으면 아무 동작도 하지 않는다.
+      if (!files || files.length === 0) {
+        return;
+      }
+      // FileList를 배열로 변환해 후속 로직에서 다루기 쉽게 만든다.
+      const fileArray = Array.from(files);
+      // 최근 선택 파일 상태를 갱신한다.
+      setSelectedFiles(fileArray);
+      // 외부 콜백으로 입력 소스(input)와 함께 파일 배열을 전달한다.
+      onFilesChange(fileArray, "input", event);
+
+      // Input Hook; 같은 파일 재선택 시 change 이벤트 재트리거 보장
+      if (resetInputValue) {
+        // 입력값을 비워 같은 파일 재선택 시에도 change가 다시 발생하도록 한다.
+        event.currentTarget.value = "";
+      }
+    },
+    [disabled, onFilesChange, resetInputValue],
+  );
+
+  /**
+   * Input Hook; File Upload dragenter 상태 진입 핸들러
+   * @param {DragEvent<HTMLElement>} event dragenter 이벤트
+   */
+  const onDragEnter = useCallback(
+    (event: DragEvent<HTMLElement>) => {
+      // 브라우저 기본 drop 처리(파일 열기)를 방지한다.
+      event.preventDefault();
+      // 상위 핸들러로 이벤트 전파를 막아 상태 갱신 충돌을 줄인다.
+      event.stopPropagation();
+      // disabled 상태에서는 drag 상태를 변경하지 않는다.
+      if (disabled) {
+        return;
+      }
+      // dragenter가 중첩 호출될 수 있어 depth를 증가시킨다.
+      dragDepthRef.current += 1;
+      // drop zone 진입 상태를 true로 전환한다.
+      setIsDragging(true);
+    },
+    [disabled],
+  );
+
+  /**
+   * Input Hook; File Upload dragover 기본 이벤트 차단 핸들러
+   * @param {DragEvent<HTMLElement>} event dragover 이벤트
+   */
+  const onDragOver = useCallback((event: DragEvent<HTMLElement>) => {
+    // dragover의 기본 동작을 막아 drop 가능 상태를 유지한다.
+    event.preventDefault();
+    // 불필요한 이벤트 버블링을 차단한다.
+    event.stopPropagation();
+  }, []);
+
+  /**
+   * Input Hook; File Upload dragleave 상태 이탈 핸들러
+   * @param {DragEvent<HTMLElement>} event dragleave 이벤트
+   */
+  const onDragLeave = useCallback(
+    (event: DragEvent<HTMLElement>) => {
+      // 브라우저 기본 동작을 방지한다.
+      event.preventDefault();
+      // 이벤트 전파를 차단한다.
+      event.stopPropagation();
+      // disabled 상태에서는 drag 상태를 변경하지 않는다.
+      if (disabled) {
+        return;
+      }
+      // 중첩 leave 이벤트를 고려해 depth를 1 감소시킨다.
+      dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+      // depth가 0이면 실제로 영역 밖으로 벗어난 상태로 판단한다.
+      if (dragDepthRef.current === 0) {
+        // drop zone 시각 상태를 기본값(false)으로 되돌린다.
+        setIsDragging(false);
+      }
+    },
+    [disabled],
+  );
+
+  /**
+   * Input Hook; File Upload drop 파일 등록 핸들러
+   * @param {DragEvent<HTMLElement>} event drop 이벤트
+   */
+  const onDropFiles = useCallback(
+    (event: DragEvent<HTMLElement>) => {
+      // drop 시 브라우저 기본 파일 열기 동작을 방지한다.
+      event.preventDefault();
+      // 이벤트 전파를 차단해 상위 충돌을 방지한다.
+      event.stopPropagation();
+      // drop 시점에는 drag depth를 초기화한다.
+      dragDepthRef.current = 0;
+      // drop 완료 후 drag 시각 상태를 해제한다.
+      setIsDragging(false);
+      // disabled 상태에서는 파일 등록 로직을 수행하지 않는다.
+      if (disabled) {
+        return;
+      }
+      // drop 이벤트에서 전달된 FileList를 읽는다.
+      const files = event.dataTransfer.files;
+      // 파일이 없으면 중단한다.
+      if (!files || files.length === 0) {
+        return;
+      }
+      // FileList를 배열로 변환한다.
+      const fileArray = Array.from(files);
+      // 최근 선택 파일 상태를 drop 기준으로 갱신한다.
+      setSelectedFiles(fileArray);
+      // 외부 콜백으로 입력 소스(drop)와 함께 파일 배열을 전달한다.
+      onFilesChange(fileArray, "drop", event);
+    },
+    [disabled, onFilesChange],
+  );
+
+  /**
+   * Input Hook; File Upload 선택 파일 상태 초기화 핸들러
+   */
+  const onClearSelectedFiles = useCallback(() => {
+    // 최근 선택 파일 상태를 빈 배열로 초기화한다.
+    setSelectedFiles([]);
+  }, []);
+
+  // 훅 소비자가 바로 사용하도록 상태/핸들러를 역할별로 반환한다.
+  return {
+    isDragging,
+    selectedFiles,
+    hasSelectedFiles: selectedFiles.length > 0,
+    onClearSelectedFiles,
+    onOpenFileDialog,
+    onInputFileChange,
+    onDropFiles,
+    onDragEnter,
+    onDragOver,
+    onDragLeave,
+  };
+};

package/src/components/input/hooks/useInputFileContext.ts

@@ -0,0 +1,244 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import type {
+  InputFileEntry,
+  InputFileEvent,
+  InputFileFormDataOptions,
+  InputFileSource,
+  UseInputFileContextOptions,
+  UseInputFileContextResult,
+} from "../types";
+import { createInputFileFormData, createInputFileMeta } from "../utils/file";
+
+/**
+ * Input Hook; File Upload 컨텍스트 관리 Hook
+ * @hook
+ * @param {UseInputFileContextOptions} [options] 파일 컨텍스트 옵션
+ * @param {File[]} [options.initialFiles] 초기 파일 목록
+ * @param {InputFileContextMergeMode} [options.mergeMode="append"] 파일 합치기 전략
+ * @returns {UseInputFileContextResult} 파일 컨텍스트 상태/액션
+ * @desc
+ * - return.state: { entries, files, fileMetas, hasFiles, fileCount }
+ * - return.sync: { onSyncFromInputFile }
+ * - return.collection: { onReplaceFiles, onAppendFiles, onRemoveFileById, onRemoveFileByIndex, onClearFiles }
+ * - return.submit: { toFormData }
+ * @example
+ * ```ts
+ * // 1) 파일 컨텍스트를 append 모드로 생성
+ * const fileContext = useInputFileContext({ mergeMode: "append" });
+ *
+ * // 2) Input 이벤트를 컨텍스트 동기화 핸들러에 연결
+ * const fileUpload = useInputFile({
+ *   onFilesChange: fileContext.onSyncFromInputFile,
+ * });
+ *
+ * // 3) 목록 렌더링은 fileMetas로 구성
+ * fileContext.fileMetas.map(meta => {
+ *   return `${meta.name} / ${meta.sizeLabel}`;
+ * });
+ *
+ * // 4) submit payload는 컨텍스트에서 직렬화
+ * const formData = fileContext.toFormData({ fieldName: "attach_files" });
+ * formData.append("message", "hello");
+ * ```
+ */
+export const useInputFileContext = ({
+  initialFiles,
+  mergeMode = "append",
+}: UseInputFileContextOptions = {}): UseInputFileContextResult => {
+  /**
+   * Input Hook; File Upload 엔트리 고유 id 시퀀스 ref
+   */
+  // 파일이 추가될 때마다 증가하는 시퀀스를 유지한다.
+  const entryIdRef = useRef(0);
+
+  /**
+   * Input Hook; File Upload 엔트리 id 생성
+   */
+  const createEntryId = useCallback((): string => {
+    // 시퀀스를 1 증가시킨다.
+    entryIdRef.current += 1;
+    // 엔트리 key로 사용할 고유 문자열을 반환한다.
+    return `input-file-${entryIdRef.current}`;
+  }, []);
+
+  /**
+   * Input Hook; File Upload 원본 파일 배열을 엔트리 배열로 변환
+   * @param {File[]} files 원본 File 배열
+   */
+  const mapFilesToEntries = useCallback(
+    (files: File[]): InputFileEntry[] =>
+      // 원본 File 배열을 내부 엔트리(id + file) 배열로 정규화한다.
+      files.map(file => ({
+        // 각 파일에 고유 id를 부여한다.
+        id: createEntryId(),
+        // 원본 파일 객체를 그대로 보관한다.
+        file,
+      })),
+    [createEntryId],
+  );
+
+  /**
+   * Input Hook; File Upload 엔트리 상태
+   */
+  const [entries, setEntries] = useState<InputFileEntry[]>(() =>
+    // 초기 렌더에서 initialFiles를 내부 엔트리 형식으로 변환한다.
+    mapFilesToEntries(initialFiles ?? []),
+  );
+  /**
+   * Input Hook; File Upload initialFiles 시그니처 비교 ref
+   */
+  const initialFilesSignatureRef = useRef("");
+
+  /**
+   * Input Hook; File Upload 파일 전체 교체 핸들러
+   * @param {File[]} files 교체할 File 배열
+   */
+  const onReplaceFiles = useCallback(
+    (files: File[]) => {
+      // 전달받은 파일 배열을 내부 엔트리 배열로 변환 후 전체 교체한다.
+      setEntries(mapFilesToEntries(files));
+    },
+    [mapFilesToEntries],
+  );
+
+  /**
+   * Input Hook; File Upload 파일 추가 핸들러
+   * @param {File[]} files 추가할 File 배열
+   */
+  const onAppendFiles = useCallback(
+    (files: File[]) => {
+      // 추가할 파일이 없으면 상태 변경을 생략한다.
+      if (files.length === 0) {
+        return;
+      }
+      // 기존 엔트리 뒤에 신규 엔트리를 이어 붙인다.
+      setEntries(prevEntries => [...prevEntries, ...mapFilesToEntries(files)]);
+    },
+    [mapFilesToEntries],
+  );
+
+  /**
+   * Input Hook; File Upload useInputFile 연결 동기화 핸들러
+   * @param {File[]} files 입력된 File 배열
+   * @param {InputFileSource} _source 입력 소스(input | drop)
+   * @param {InputFileEvent} _event 원본 이벤트 객체
+   */
+  const onSyncFromInputFile = useCallback(
+    (files: File[], _source: InputFileSource, _event: InputFileEvent) => {
+      // source/event 인자는 확장 포인트를 위해 시그니처에 유지한다.
+      void _source;
+      void _event;
+      // UI 전략에 따라 append/replace를 선택할 수 있도록 mergeMode를 분리한다.
+      if (mergeMode === "replace") {
+        // replace 모드면 기존 파일을 모두 교체한다.
+        onReplaceFiles(files);
+        return;
+      }
+      // append 모드면 기존 파일 뒤에 신규 파일을 추가한다.
+      onAppendFiles(files);
+    },
+    [mergeMode, onAppendFiles, onReplaceFiles],
+  );
+
+  /**
+   * Input Hook; File Upload id 기준 파일 제거 핸들러
+   * @param {string} id 제거할 파일 엔트리 id
+   */
+  const onRemoveFileById = useCallback((id: string) => {
+    // 전달받은 id와 일치하지 않는 엔트리만 남겨 제거를 수행한다.
+    setEntries(prevEntries =>
+      prevEntries.filter(entry => {
+        return entry.id !== id;
+      }),
+    );
+  }, []);
+
+  /**
+   * Input Hook; File Upload index 기준 파일 제거 핸들러
+   * @param {number} index 제거할 파일 인덱스
+   */
+  const onRemoveFileByIndex = useCallback((index: number) => {
+    setEntries(prevEntries => {
+      // 범위를 벗어난 index면 기존 배열을 그대로 반환한다.
+      if (index < 0 || index >= prevEntries.length) {
+        return prevEntries;
+      }
+      // 지정된 index를 제외한 엔트리만 유지한다.
+      return prevEntries.filter((_, itemIndex) => itemIndex !== index);
+    });
+  }, []);
+
+  /**
+   * Input Hook; File Upload 파일 전체 초기화 핸들러
+   */
+  const onClearFiles = useCallback(() => {
+    // 모든 파일 엔트리를 비워 컨텍스트를 초기화한다.
+    setEntries([]);
+  }, []);
+
+  /**
+   * Input Hook; File Upload initialFiles 변경 동기화
+   */
+  useEffect(() => {
+    // undefined를 방지하기 위해 기본 빈 배열을 사용한다.
+    const files = initialFiles ?? [];
+    // 파일 목록 내용을 비교하기 위한 시그니처 문자열을 생성한다.
+    const currentSignature = files
+      .map(
+        file => `${file.name}-${file.size}-${file.lastModified}-${file.type}`,
+      )
+      .join("|");
+    // 시그니처가 이전과 같으면 동기화를 생략한다.
+    if (initialFilesSignatureRef.current === currentSignature) {
+      return;
+    }
+    // 최신 시그니처를 저장한다.
+    initialFilesSignatureRef.current = currentSignature;
+    // 외부 initialFiles 변경을 내부 상태로 동기화한다.
+    onReplaceFiles(files);
+  }, [initialFiles, onReplaceFiles]);
+
+  /**
+   * Input Hook; File Upload 원본 파일 배열 메모값
+   */
+  const files = useMemo(() => entries.map(entry => entry.file), [entries]);
+  /**
+   * Input Hook; File Upload 파일 메타데이터 배열 메모값
+   */
+  const fileMetas = useMemo(
+    // entries를 화면 렌더링/표시에 유리한 메타데이터로 변환한다.
+    () => entries.map(entry => createInputFileMeta(entry)),
+    [entries],
+  );
+
+  /**
+   * Input Hook; File Upload 제출용 FormData 직렬화
+   * @param {InputFileFormDataOptions} [options] FormData 직렬화 옵션
+   */
+  const toFormData = useCallback(
+    (options?: InputFileFormDataOptions) => {
+      // 현재 컨텍스트 파일 목록을 API 제출용 FormData로 직렬화한다.
+      return createInputFileFormData(files, options);
+    },
+    [files],
+  );
+
+  // 상태/조작/동기화/직렬화 API를 하나의 객체로 반환한다.
+  return {
+    entries,
+    files,
+    fileMetas,
+    hasFiles: entries.length > 0,
+    fileCount: entries.length,
+    onSyncFromInputFile,
+    onReplaceFiles,
+    onAppendFiles,
+    onRemoveFileById,
+    onRemoveFileByIndex,
+    onClearFiles,
+    // Input Hook; 소비처에서 즉시 submit payload를 만들 수 있도록 직렬화 헬퍼를 노출한다.
+    toFormData,
+  };
+};

package/src/components/input/hooks/useInputFileRHF.ts

@@ -0,0 +1,105 @@
+"use client";
+
+import { useCallback } from "react";
+import type { ChangeEvent, FocusEvent } from "react";
+import type { UseInputFileRHFOptions, UseInputFileRHFResult } from "../types";
+
+/**
+ * Input Hook; File Upload RHF 통합 Hook
+ * @hook
+ * @param {UseInputFileRHFOptions} options RHF 통합 옵션
+ * @param {(event: ChangeEvent<HTMLInputElement>) => void} options.onInputFileChange 파일 입력 핸들러
+ * @param {RefObject<HTMLInputElement | null>} [options.inputRef] file input ref
+ * @param {UseFormRegisterReturn} [options.register] react-hook-form register 반환값
+ * @returns {UseInputFileRHFResult} file input bind props
+ * @desc
+ * - return.inputBindProps: { name, ref, onChange, onBlur }
+ * - return.inputBindProps.ref: inputRef와 RHF register.ref를 병합한다.
+ * - return.inputBindProps.onChange: RHF onChange 후 file handler를 순차 실행한다.
+ * - return.inputBindProps.onBlur: RHF onBlur를 전달한다(register 사용 시에만 제공).
+ * @example
+ * ```ts
+ * // 1) Input.File 컨텍스트/핸들러 준비
+ * const fileContext = useInputFileContext();
+ * const fileUpload = useInputFile({
+ *   onFilesChange: fileContext.onSyncFromInputFile,
+ * });
+ *
+ * // 2) RHF register와 file input 핸들러 병합
+ * const { inputBindProps } = useInputFileRHF({
+ *   register: register("form.attach_files"),
+ *   inputRef,
+ *   onInputFileChange: fileUpload.onInputFileChange,
+ * });
+ *
+ * // 3) hidden input에 bind props 연결
+ * <input {...inputBindProps} type="file" hidden multiple />
+ *
+ * // 4) submit 시 payload 직렬화
+ * const payload = fileContext.toFormData({ fieldName: "attach_files" });
+ * ```
+ */
+export const useInputFileRHF = ({
+  onInputFileChange,
+  inputRef,
+  register,
+}: UseInputFileRHFOptions): UseInputFileRHFResult => {
+  /**
+   * Input Hook; File Upload RHF ref 병합 핸들러
+   * @param {HTMLInputElement | null} node file input DOM 노드
+   */
+  const handleRef = useCallback(
+    (node: HTMLInputElement | null) => {
+      // 소비자가 전달한 inputRef가 있으면 동일한 DOM 노드를 동기화한다.
+      if (inputRef) {
+        inputRef.current = node;
+      }
+      // RHF register.ref에도 같은 노드를 전달해 폼 제어를 연결한다.
+      register?.ref(node);
+    },
+    [inputRef, register],
+  );
+
+  /**
+   * Input Hook; File Upload RHF onChange 병합 핸들러
+   * @param {ChangeEvent<HTMLInputElement>} event file input change 이벤트
+   */
+  const handleChange = useCallback(
+    (event: ChangeEvent<HTMLInputElement>) => {
+      // RHF onChange를 먼저 호출해 폼 상태를 최신화한다.
+      register?.onChange(event);
+      // 이후 file upload 훅의 change 핸들러를 호출해 파일 로직을 수행한다.
+      onInputFileChange(event);
+    },
+    [onInputFileChange, register],
+  );
+
+  /**
+   * Input Hook; File Upload RHF onBlur 전달 핸들러
+   * @param {FocusEvent<HTMLInputElement>} event file input blur 이벤트
+   */
+  const handleBlur = useCallback(
+    (event: FocusEvent<HTMLInputElement>) => {
+      // blur 이벤트는 RHF에 전달해 touched/validation 흐름을 유지한다.
+      register?.onBlur(event);
+    },
+    [register],
+  );
+
+  /**
+   * Input Hook; File Upload RHF input bind props 반환 객체
+   */
+  // file input spread에 필요한 속성을 하나로 묶어 반환한다.
+  return {
+    inputBindProps: {
+      // RHF name을 그대로 노출한다(register가 없으면 undefined).
+      name: register?.name,
+      // ref 병합 핸들러
+      ref: handleRef,
+      // onChange 병합 핸들러
+      onChange: handleChange,
+      // register가 있을 때만 onBlur를 주입한다.
+      onBlur: register ? handleBlur : undefined,
+    },
+  };
+};

package/src/components/input/index.scss

@@ -3,3 +3,4 @@
 @use "./styles/text.scss" as inputText;
 @use "./styles/date.scss" as inputDate;
 @use "./styles/address.scss" as inputAddress;
+@use "./styles/file.scss" as inputFile;