@uniai-fe/uds-primitives 0.2.4 → 0.2.6

package/src/components/input/styles/file.scss

@@ -0,0 +1,60 @@
+.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;
+
+  &[data-dragging="true"] {
+    border-color: var(--input-border-active-color);
+    background-color: var(--input-surface-muted-color);
+  }
+
+  &[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;
+
+  &[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;
+}

package/src/components/input/types/file.ts

@@ -0,0 +1,531 @@
+import type {
+  ChangeEvent,
+  ComponentPropsWithoutRef,
+  DragEvent,
+  FocusEvent,
+  MouseEvent,
+  ReactNode,
+  RefObject,
+  SyntheticEvent,
+} from "react";
+import type { ButtonProps } from "../../button/types";
+import type { ChipInputProps } from "../../chip/types";
+import type { UseFormRegisterReturn } from "react-hook-form";
+
+/**
+ * Input Types; File Upload 소스 타입
+ */
+export type InputFileSource = "input" | "drop";
+
+/**
+ * Input Types; File Upload 이벤트 타입
+ */
+export type InputFileEvent =
+  | ChangeEvent<HTMLInputElement>
+  | DragEvent<HTMLElement>;
+
+/**
+ * Input Types; File Upload 변경 핸들러
+ */
+export type InputFileChangeHandler = (
+  files: File[],
+  source: InputFileSource,
+  event: InputFileEvent,
+) => void;
+
+/**
+ * Input Types; File Upload Hook 옵션
+ * @property {InputFileChangeHandler} onFilesChange 파일 변경 콜백
+ * @property {RefObject<HTMLInputElement | null>} [inputRef] 직접 제어할 file input ref
+ * @property {string} [selectorId] inputRef가 없을 때 조회할 input id
+ * @property {boolean} [disabled] 동작 비활성화 여부
+ * @property {boolean} [resetInputValue] 등록 후 input 값을 비울지 여부
+ */
+export interface UseInputFileOptions {
+  /**
+   * 파일 변경 콜백
+   */
+  onFilesChange: InputFileChangeHandler;
+  /**
+   * 직접 제어할 file input ref
+   */
+  inputRef?: RefObject<HTMLInputElement | null>;
+  /**
+   * inputRef가 없을 때 조회할 input id
+   */
+  selectorId?: string;
+  /**
+   * 동작 비활성화 여부
+   */
+  disabled?: boolean;
+  /**
+   * 등록 후 input 값을 비울지 여부
+   */
+  resetInputValue?: boolean;
+}
+
+/**
+ * Input Types; File Upload Hook 반환값
+ * @property {boolean} isDragging 드래그 오버 상태
+ * @property {File[]} selectedFiles 최근 선택된 파일 목록
+ * @property {boolean} hasSelectedFiles 파일 선택 여부
+ * @property {() => void} onClearSelectedFiles 선택된 파일 초기화 핸들러
+ * @property {(event?: SyntheticEvent<HTMLElement>) => void} onOpenFileDialog 파일 선택창 열기 핸들러
+ * @property {(event: ChangeEvent<HTMLInputElement>) => void} onInputFileChange file input change 핸들러
+ * @property {(event: DragEvent<HTMLElement>) => void} onDropFiles drop 핸들러
+ * @property {(event: DragEvent<HTMLElement>) => void} onDragEnter dragenter 핸들러
+ * @property {(event: DragEvent<HTMLElement>) => void} onDragOver dragover 핸들러
+ * @property {(event: DragEvent<HTMLElement>) => void} onDragLeave dragleave 핸들러
+ */
+export interface UseInputFileResult {
+  /**
+   * 드래그 오버 상태
+   */
+  isDragging: boolean;
+  /**
+   * 최근 선택된 파일 목록
+   */
+  selectedFiles: File[];
+  /**
+   * 파일 선택 여부
+   */
+  hasSelectedFiles: boolean;
+  /**
+   * 선택된 파일 초기화 핸들러
+   */
+  onClearSelectedFiles: () => void;
+  /**
+   * 파일 선택창 열기 핸들러
+   */
+  onOpenFileDialog: (event?: SyntheticEvent<HTMLElement>) => void;
+  /**
+   * file input change 핸들러
+   */
+  onInputFileChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  /**
+   * drop 핸들러
+   */
+  onDropFiles: (event: DragEvent<HTMLElement>) => void;
+  /**
+   * dragenter 핸들러
+   */
+  onDragEnter: (event: DragEvent<HTMLElement>) => void;
+  /**
+   * dragover 핸들러
+   */
+  onDragOver: (event: DragEvent<HTMLElement>) => void;
+  /**
+   * dragleave 핸들러
+   */
+  onDragLeave: (event: DragEvent<HTMLElement>) => void;
+}
+
+/**
+ * Input Types; File DragAndDrop 컴포넌트 props
+ * @property {React.ReactNode} children drop zone 내부 콘텐츠
+ * @property {InputFileChangeHandler} onFilesChange 파일 변경 콜백
+ * @property {boolean} [disabled] drop 비활성화 여부
+ */
+export interface InputFileDragAndDropProps extends Omit<
+  ComponentPropsWithoutRef<"div">,
+  "onDrop" | "onDragEnter" | "onDragLeave" | "onDragOver"
+> {
+  /**
+   * drop zone 내부 콘텐츠
+   */
+  children: ReactNode;
+  /**
+   * 파일 변경 콜백
+   */
+  onFilesChange: InputFileChangeHandler;
+  /**
+   * drop 비활성화 여부
+   */
+  disabled?: boolean;
+}
+
+/**
+ * Input Types; File Upload dialog open 핸들러
+ */
+export type InputFileOpenDialogHandler = (
+  event?: SyntheticEvent<HTMLElement>,
+) => void;
+
+/**
+ * Input Types; File Upload 버튼 props
+ * @property {InputFileOpenDialogHandler} [onOpenFileDialog] file dialog open 핸들러
+ * @property {ButtonProps} ... Button.Default props 전체
+ */
+export interface InputFileUploadButtonProps extends ButtonProps {
+  /**
+   * file dialog open 핸들러
+   */
+  onOpenFileDialog?: InputFileOpenDialogHandler;
+}
+
+/**
+ * Input Types; File UploadedChip 컴포넌트 props
+ * @property {string} [fileId] 업로드 엔트리 id
+ * @property {string} fileName 업로드된 파일명
+ * @property {(fileId: string) => void} [onRemoveFromInput] input file 컨텍스트 제거 핸들러
+ * @property {() => void} [onClearSelectedFiles] fileId가 없을 때 선택 파일 초기화 핸들러
+ * @property {(event: MouseEvent<HTMLButtonElement>) => void} [onRemove] 파일 제거 핸들러
+ * @property {string} [removeButtonLabel] 제거 버튼 aria-label
+ */
+export interface InputFileUploadedChipProps extends Omit<
+  ChipInputProps,
+  "kind" | "children" | "onRemove"
+> {
+  /**
+   * 업로드 엔트리 id
+   */
+  fileId?: string;
+  /**
+   * 업로드된 파일명
+   */
+  fileName: string;
+  /**
+   * input file 컨텍스트 제거 핸들러
+   */
+  onRemoveFromInput?: (fileId: string) => void;
+  /**
+   * fileId가 없을 때 선택 파일 초기화 핸들러
+   */
+  onClearSelectedFiles?: () => void;
+  /**
+   * 파일 제거 핸들러
+   */
+  onRemove?: (event: MouseEvent<HTMLButtonElement>) => void;
+}
+
+/**
+ * Input Types; File Upload List Container 컴포넌트 props
+ * @property {ReactNode} children list 하위 슬롯 콘텐츠
+ * @property {boolean} [collapsible] 헤더 트리거 기반 접기/펼치기 활성화 여부
+ * @property {boolean} [defaultCollapsed] uncontrolled 초기 접힘 상태
+ * @property {boolean} [collapsed] controlled 접힘 상태
+ * @property {(collapsed: boolean) => void} [onCollapsedChange] 접힘 상태 변경 콜백
+ */
+export interface InputFileListContainerProps extends ComponentPropsWithoutRef<"section"> {
+  /**
+   * list 하위 슬롯 콘텐츠
+   */
+  children: ReactNode;
+  /**
+   * 헤더 트리거 기반 접기/펼치기 활성화 여부
+   */
+  collapsible?: boolean;
+  /**
+   * uncontrolled 초기 접힘 상태
+   */
+  defaultCollapsed?: boolean;
+  /**
+   * controlled 접힘 상태
+   */
+  collapsed?: boolean;
+  /**
+   * 접힘 상태 변경 콜백
+   */
+  onCollapsedChange?: (collapsed: boolean) => void;
+}
+
+/**
+ * Input Types; File Upload List Header 컴포넌트 props
+ * @property {ReactNode} children 헤더 콘텐츠
+ * @property {boolean} [asTrigger] 클릭/키보드 트리거로 접기/펼치기 제어 여부
+ */
+export interface InputFileListHeaderProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * 헤더 콘텐츠
+   */
+  children: ReactNode;
+  /**
+   * 클릭/키보드 트리거로 접기/펼치기 제어 여부
+   */
+  asTrigger?: boolean;
+}
+
+/**
+ * Input Types; File Upload List Body 컴포넌트 props
+ * @property {ReactNode} children 목록 콘텐츠
+ * @property {boolean} [forceMount] 접힘 상태에서도 DOM 유지 여부
+ */
+export interface InputFileListBodyProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * 목록 콘텐츠
+   */
+  children: ReactNode;
+  /**
+   * 접힘 상태에서도 DOM 유지 여부
+   */
+  forceMount?: boolean;
+}
+
+/**
+ * Input Types; File Upload List Item 컴포넌트 props
+ * @property {ReactNode} children 파일 항목 콘텐츠
+ */
+export interface InputFileListItemProps extends ComponentPropsWithoutRef<"div"> {
+  /**
+   * 파일 항목 콘텐츠
+   */
+  children: ReactNode;
+}
+
+/**
+ * Input Types; File Upload List Remove 컴포넌트 props
+ * @property {ReactNode} [children] 제거 버튼 콘텐츠
+ * @property {(event: MouseEvent<HTMLButtonElement>) => void} [onRemove] 제거 핸들러
+ */
+export interface InputFileListRemoveProps extends Omit<
+  ComponentPropsWithoutRef<"button">,
+  "onClick"
+> {
+  /**
+   * 제거 버튼 콘텐츠
+   */
+  children?: ReactNode;
+  /**
+   * 제거 핸들러
+   */
+  onRemove?: (event: MouseEvent<HTMLButtonElement>) => void;
+}
+
+/**
+ * Input Types; File Upload List 컨텍스트 값 타입
+ * @property {boolean} collapsible 헤더 트리거 기반 접기/펼치기 활성화 여부
+ * @property {boolean} collapsed 현재 접힘 상태
+ * @property {() => void} onToggleCollapsed 접힘 상태 토글 핸들러
+ */
+export interface InputFileListContextValue {
+  /**
+   * 헤더 트리거 기반 접기/펼치기 활성화 여부
+   */
+  collapsible: boolean;
+  /**
+   * 현재 접힘 상태
+   */
+  collapsed: boolean;
+  /**
+   * 접힘 상태 토글 핸들러
+   */
+  onToggleCollapsed: () => void;
+}
+
+/**
+ * Input Types; File Upload 컨텍스트 merge 전략
+ */
+export type InputFileContextMergeMode = "replace" | "append";
+
+/**
+ * Input Types; File Upload 엔트리 타입
+ * @property {string} id 파일 엔트리 고유 id
+ * @property {File} file 원본 File 객체
+ */
+export interface InputFileEntry {
+  /**
+   * 파일 엔트리 고유 id
+   */
+  id: string;
+  /**
+   * 원본 File 객체
+   */
+  file: File;
+}
+
+/**
+ * Input Types; File Upload 메타데이터 타입
+ * @property {string} id 파일 엔트리 고유 id
+ * @property {string} title 파일 제목(확장자 제외)
+ * @property {string} name 파일명(확장자 포함)
+ * @property {number} size 파일 크기(Byte)
+ * @property {string} sizeLabel 사람이 읽기 쉬운 파일 크기 문자열
+ * @property {string} format 파일 MIME type 또는 확장자 fallback
+ * @property {string} extension 파일 확장자(소문자)
+ * @property {number} lastModified 마지막 수정 시간(ms)
+ */
+export interface InputFileMeta {
+  /**
+   * 파일 엔트리 고유 id
+   */
+  id: string;
+  /**
+   * 파일 제목(확장자 제외)
+   */
+  title: string;
+  /**
+   * 파일명(확장자 포함)
+   */
+  name: string;
+  /**
+   * 파일 크기(Byte)
+   */
+  size: number;
+  /**
+   * 사람이 읽기 쉬운 파일 크기 문자열
+   */
+  sizeLabel: string;
+  /**
+   * 파일 MIME type 또는 확장자 fallback
+   */
+  format: string;
+  /**
+   * 파일 확장자(소문자)
+   */
+  extension: string;
+  /**
+   * 마지막 수정 시간(ms)
+   */
+  lastModified: number;
+}
+
+/**
+ * Input Types; File Upload 컨텍스트 Hook 옵션
+ * @property {File[]} [initialFiles] 초기 파일 목록
+ * @property {InputFileContextMergeMode} [mergeMode="append"] 파일 합치기 전략
+ */
+export interface UseInputFileContextOptions {
+  /**
+   * 초기 파일 목록
+   */
+  initialFiles?: File[];
+  /**
+   * 파일 합치기 전략
+   */
+  mergeMode?: InputFileContextMergeMode;
+}
+
+/**
+ * Input Types; File Upload FormData 생성 옵션
+ * @property {string} [fieldName="files"] FormData에 append할 필드 이름
+ */
+export interface InputFileFormDataOptions {
+  /**
+   * FormData에 append할 필드 이름
+   */
+  fieldName?: string;
+}
+
+/**
+ * Input Types; File Upload RHF 통합 Hook 옵션
+ * @property {(event: ChangeEvent<HTMLInputElement>) => void} onInputFileChange 파일 입력 핸들러
+ * @property {RefObject<HTMLInputElement | null>} [inputRef] file input ref
+ * @property {UseFormRegisterReturn} [register] react-hook-form register 반환값
+ */
+export interface UseInputFileRHFOptions {
+  /**
+   * 파일 입력 핸들러
+   */
+  onInputFileChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  /**
+   * file input ref
+   */
+  inputRef?: RefObject<HTMLInputElement | null>;
+  /**
+   * react-hook-form register 반환값
+   */
+  register?: UseFormRegisterReturn;
+}
+
+/**
+ * Input Types; File Upload RHF 통합 input bind props
+ * @property {string} [name] input name
+ * @property {(node: HTMLInputElement | null) => void} ref register/ref 병합 함수
+ * @property {(event: ChangeEvent<HTMLInputElement>) => void} onChange register + file handler 병합 함수
+ * @property {(event: FocusEvent<HTMLInputElement>) => void} [onBlur] register onBlur 전달 함수
+ */
+export interface InputFileRHFBindProps {
+  /**
+   * input name
+   */
+  name?: string;
+  /**
+   * register/ref 병합 함수
+   */
+  ref: (node: HTMLInputElement | null) => void;
+  /**
+   * register + file handler 병합 함수
+   */
+  onChange: (event: ChangeEvent<HTMLInputElement>) => void;
+  /**
+   * register onBlur 전달 함수
+   */
+  onBlur?: (event: FocusEvent<HTMLInputElement>) => void;
+}
+
+/**
+ * Input Types; File Upload RHF 통합 Hook 반환값
+ * @property {InputFileRHFBindProps} inputBindProps file input에 spread할 bind props
+ */
+export interface UseInputFileRHFResult {
+  /**
+   * file input에 spread할 bind props
+   */
+  inputBindProps: InputFileRHFBindProps;
+}
+
+/**
+ * Input Types; File Upload 컨텍스트 Hook 반환값
+ * @property {InputFileEntry[]} entries 파일 엔트리 목록
+ * @property {File[]} files 원본 파일 목록
+ * @property {InputFileMeta[]} fileMetas 파일 메타데이터 목록
+ * @property {boolean} hasFiles 파일 존재 여부
+ * @property {number} fileCount 파일 개수
+ * @property {InputFileChangeHandler} onSyncFromInputFile useInputFile onFilesChange 연결용 핸들러
+ * @property {(files: File[]) => void} onReplaceFiles 파일 전체 교체 핸들러
+ * @property {(files: File[]) => void} onAppendFiles 파일 추가 핸들러
+ * @property {(id: string) => void} onRemoveFileById id 기준 파일 제거 핸들러
+ * @property {(index: number) => void} onRemoveFileByIndex index 기준 파일 제거 핸들러
+ * @property {() => void} onClearFiles 파일 전체 제거 핸들러
+ * @property {(options?: InputFileFormDataOptions) => FormData} toFormData 컨텍스트 파일 목록을 FormData로 직렬화하는 헬퍼
+ */
+export interface UseInputFileContextResult {
+  /**
+   * 파일 엔트리 목록
+   */
+  entries: InputFileEntry[];
+  /**
+   * 원본 파일 목록
+   */
+  files: File[];
+  /**
+   * 파일 메타데이터 목록
+   */
+  fileMetas: InputFileMeta[];
+  /**
+   * 파일 존재 여부
+   */
+  hasFiles: boolean;
+  /**
+   * 파일 개수
+   */
+  fileCount: number;
+  /**
+   * useInputFile onFilesChange 연결용 핸들러
+   */
+  onSyncFromInputFile: InputFileChangeHandler;
+  /**
+   * 파일 전체 교체 핸들러
+   */
+  onReplaceFiles: (files: File[]) => void;
+  /**
+   * 파일 추가 핸들러
+   */
+  onAppendFiles: (files: File[]) => void;
+  /**
+   * id 기준 파일 제거 핸들러
+   */
+  onRemoveFileById: (id: string) => void;
+  /**
+   * index 기준 파일 제거 핸들러
+   */
+  onRemoveFileByIndex: (index: number) => void;
+  /**
+   * 파일 전체 제거 핸들러
+   */
+  onClearFiles: () => void;
+  /**
+   * 컨텍스트 파일 목록을 FormData로 직렬화하는 헬퍼
+   */
+  toFormData: (options?: InputFileFormDataOptions) => FormData;
+}

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

@@ -4,3 +4,4 @@ export type * from "./date";
 export type * from "./verification";
 export type * from "./hooks";
 export type * from "./address";
+export type * from "./file";

package/src/components/input/utils/file.ts

@@ -0,0 +1,103 @@
+import type {
+  InputFileEntry,
+  InputFileFormDataOptions,
+  InputFileMeta,
+} from "../types";
+
+/**
+ * Input Utils; File Upload 확장자 추출 유틸
+ * @param {File} file 파일 객체
+ * @returns {string} 소문자 확장자
+ */
+export const resolveInputFileExtension = (file: File): string => {
+  const fileName = file.name ?? "";
+  const dotIndex = fileName.lastIndexOf(".");
+  if (dotIndex < 0 || dotIndex === fileName.length - 1) {
+    return "";
+  }
+  return fileName.slice(dotIndex + 1).toLowerCase();
+};
+
+/**
+ * Input Utils; File Upload 제목 추출 유틸
+ * @param {File} file 파일 객체
+ * @returns {string} 확장자를 제외한 파일 제목
+ */
+export const resolveInputFileTitle = (file: File): string => {
+  const fileName = file.name ?? "";
+  const dotIndex = fileName.lastIndexOf(".");
+  if (dotIndex <= 0) {
+    return fileName;
+  }
+  return fileName.slice(0, dotIndex);
+};
+
+/**
+ * Input Utils; File Upload 포맷 추출 유틸
+ * @param {File} file 파일 객체
+ * @returns {string} MIME type 또는 확장자 기반 fallback
+ */
+export const resolveInputFileFormat = (file: File): string => {
+  if (file.type.length > 0) {
+    return file.type;
+  }
+  const extension = resolveInputFileExtension(file);
+  return extension.length > 0 ? extension : "unknown";
+};
+
+/**
+ * Input Utils; File Upload 용량 포맷 유틸
+ * @param {number} size 파일 크기(Byte)
+ * @returns {string} 사람이 읽기 쉬운 용량 문자열
+ */
+export const formatInputFileSize = (size: number): string => {
+  if (size < 1024) {
+    return `${size} B`;
+  }
+  if (size < 1024 * 1024) {
+    return `${(size / 1024).toFixed(1)} KB`;
+  }
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+};
+
+/**
+ * Input Utils; File Upload 메타데이터 생성 유틸
+ * @param {InputFileEntry} entry 파일 엔트리
+ * @returns {InputFileMeta} 파일 메타데이터
+ */
+export const createInputFileMeta = (entry: InputFileEntry): InputFileMeta => {
+  const { file, id } = entry;
+  return {
+    id,
+    title: resolveInputFileTitle(file),
+    name: file.name,
+    size: file.size,
+    sizeLabel: formatInputFileSize(file.size),
+    format: resolveInputFileFormat(file),
+    extension: resolveInputFileExtension(file),
+    lastModified: file.lastModified,
+  };
+};
+
+/**
+ * Input Utils; File Upload FormData 직렬화 유틸
+ * @param {File[]} files 원본 파일 목록
+ * @param {InputFileFormDataOptions} [options] FormData 직렬화 옵션
+ * @param {string} [options.fieldName="files"] FormData append 필드명
+ * @returns {FormData} 파일이 append된 FormData
+ * @example
+ * const formData = createInputFileFormData(fileContext.files, {
+ *   fieldName: "attach_files",
+ * });
+ */
+export const createInputFileFormData = (
+  files: File[],
+  options?: InputFileFormDataOptions,
+): FormData => {
+  const formData = new FormData();
+  const fieldName = options?.fieldName ?? "files";
+  files.forEach(file => {
+    formData.append(fieldName, file);
+  });
+  return formData;
+};

package/src/components/input/utils/index.tsx

@@ -1,3 +1,4 @@
 export * from "./verification";
 export * from "./date";
 export * from "./address";
+export * from "./file";