@uniai-fe/uds-primitives 0.2.3 → 0.2.5

package/src/components/input/markup/file/DragAndDrop.tsx

@@ -0,0 +1,59 @@
+"use client";
+
+import clsx from "clsx";
+import type { InputFileDragAndDropProps } from "../../types";
+import { useInputFile } from "../../hooks/useInputFile";
+
+/**
+ * Input Markup; File DragAndDrop 컴포넌트
+ * @component
+ * @param {InputFileDragAndDropProps} props drag-and-drop props
+ * @param {React.ReactNode} props.children drop zone 내부 콘텐츠
+ * @param {InputFileChangeHandler} props.onFilesChange 파일 변경 콜백
+ * @param {boolean} [props.disabled] drop 비활성화 여부
+ * @param {string} [props.className] root className
+ * @example
+ * ```tsx
+ * // DragAndDrop 단독 도입 예시
+ * <Input.File.DragAndDrop onFilesChange={files => console.log(files)}>
+ *   <span>파일을 드래그해 업로드하세요</span>
+ * </Input.File.DragAndDrop>
+ * ```
+ */
+const InputFileDragAndDrop = ({
+  className,
+  children,
+  onFilesChange,
+  disabled = false,
+  ...restProps
+}: InputFileDragAndDropProps) => {
+  // DragAndDrop에서 필요한 이벤트 핸들러만 useInputFile에서 선택적으로 가져온다.
+  const { isDragging, onDropFiles, onDragEnter, onDragLeave, onDragOver } =
+    useInputFile({
+      onFilesChange,
+      disabled,
+    });
+
+  return (
+    <div
+      // 외부 className을 병합하되, 루트 훅 class는 고정한다.
+      className={clsx("input-file-drag-and-drop", className)}
+      // 시각 상태는 class 추가 대신 data-*로 노출한다.
+      data-dragging={isDragging ? "true" : undefined}
+      data-disabled={disabled ? "true" : undefined}
+      // DnD 이벤트는 훅에서 생성한 핸들러를 그대로 연결한다.
+      onDrop={onDropFiles}
+      onDragEnter={onDragEnter}
+      onDragLeave={onDragLeave}
+      onDragOver={onDragOver}
+      // div native props(aria-*, id 등)는 외부에서 확장 가능하게 유지한다.
+      {...restProps}
+    >
+      {children}
+    </div>
+  );
+};
+
+InputFileDragAndDrop.displayName = "InputFileDragAndDrop";
+
+export default InputFileDragAndDrop;

package/src/components/input/markup/file/UploadButton.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { Button } from "../../../button";
+import type { MouseEvent } from "react";
+import type { InputFileUploadButtonProps } from "../../types";
+
+/**
+ * Input Markup; File Upload 트리거 버튼 컴포넌트
+ * @component
+ * @param {InputFileUploadButtonProps} props 업로드 버튼 props
+ * @param {InputFileOpenDialogHandler} [props.onOpenFileDialog] file dialog open 핸들러
+ * @param {ButtonProps} ... Button.Default props 전체를 그대로 전달
+ * @example
+ * ```tsx
+ * // 파일 선택창 오픈 동작만 추가된 Button.Default preset
+ * <Input.File.UploadButton
+ *   fill="outlined"
+ *   size="small"
+ *   priority="primary"
+ *   onOpenFileDialog={fileUpload.onOpenFileDialog}
+ * >
+ *   파일 선택
+ * </Input.File.UploadButton>
+ * ```
+ */
+export default function InputFileUploadButton({
+  onOpenFileDialog,
+  onClick,
+  ...buttonProps
+}: InputFileUploadButtonProps) {
+  /**
+   * Input Markup; File Upload 버튼 클릭 병합 핸들러
+   * @param {MouseEvent<HTMLElement>} event 클릭 이벤트
+   */
+  const handleButtonClick = (event: MouseEvent<HTMLElement>) => {
+    // 1) 업로드 preset 동작을 우선 실행한다.
+    onOpenFileDialog?.(event);
+    // 2) 소비자 onClick이 있으면 후속 실행한다.
+    onClick?.(event as never);
+  };
+
+  // Button.Default의 렌더링/스타일 계약은 그대로 유지한다.
+  return <Button.Default {...buttonProps} onClick={handleButtonClick} />;
+}

package/src/components/input/markup/file/UploadedChip.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import type { MouseEvent } from "react";
+import { Chip } from "../../../chip";
+import type { InputFileUploadedChipProps } from "../../types";
+
+/**
+ * Input Markup; File Upload 완료 상태 Chip 컴포넌트
+ * @component
+ * @param {InputFileUploadedChipProps} props 업로드 완료 칩 props
+ * @param {string} [props.fileId] 업로드 엔트리 id
+ * @param {string} props.fileName 업로드된 파일명
+ * @param {(fileId: string) => void} [props.onRemoveFromInput] input file 컨텍스트 제거 핸들러
+ * @param {() => void} [props.onClearSelectedFiles] fileId가 없을 때 선택 파일 초기화 핸들러
+ * @param {(event: MouseEvent<HTMLButtonElement>) => void} [props.onRemove] 파일 제거 핸들러
+ * @param {string} [props.removeButtonLabel="업로드 파일 삭제"] 제거 버튼 aria-label
+ * @example
+ * ```tsx
+ * // UploadedChip은 Chip(kind="input") preset으로 동작한다.
+ * <Input.File.UploadedChip
+ *   fileId={meta.id}
+ *   fileName={meta.name}
+ *   onRemoveFromInput={onRemoveFileById}
+ *   onRemove={onTrackRemove}
+ * />
+ * ```
+ */
+export default function InputFileUploadedChip({
+  fileId,
+  fileName,
+  onRemoveFromInput,
+  onClearSelectedFiles,
+  onRemove,
+  removeButtonLabel = "업로드 파일 삭제",
+  ...chipProps
+}: InputFileUploadedChipProps) {
+  /**
+   * Input Markup; File Upload Chip 제거 병합 핸들러
+   * @param {MouseEvent<HTMLButtonElement>} event 제거 클릭 이벤트
+   */
+  const handleRemove = (event: MouseEvent<HTMLButtonElement>) => {
+    // 기본 동작: fileId가 있으면 엔트리 제거, 없으면 선택 파일 전체를 초기화한다.
+    if (typeof fileId === "string" && fileId.length > 0) {
+      onRemoveFromInput?.(fileId);
+    } else {
+      onClearSelectedFiles?.();
+    }
+    // 추가 동작: 소비자 콜백을 후속으로 실행한다.
+    onRemove?.(event);
+  };
+
+  return (
+    <Chip
+      // 소비자 전달 Chip props(aria/className/data-*)를 유지한다.
+      {...chipProps}
+      // preset 목적상 kind는 input으로 고정한다.
+      kind="input"
+      // 기본 제거 동작 + 소비자 후속 콜백을 병합한 핸들러를 주입한다.
+      onRemove={handleRemove}
+      removeButtonLabel={removeButtonLabel}
+    >
+      {/* 파일명은 children slot으로 렌더링한다. */}
+      {fileName}
+    </Chip>
+  );
+}

package/src/components/input/markup/file/index.tsx

@@ -0,0 +1,25 @@
+import InputFileDragAndDrop from "./DragAndDrop";
+import InputFileUploadButton from "./UploadButton";
+import InputFileUploadedChip from "./UploadedChip";
+import { InputFileList } from "./list";
+
+/**
+ * Input Markup; File 네임스페이스
+ * @desc
+ * - DragAndDrop: 드래그 앤 드롭 입력 영역
+ * - UploadButton: 파일 선택창 트리거 버튼
+ * - UploadedChip: 업로드 완료 파일 표현/제거 preset
+ * - List: headless 파일 목록 구조(Container/Header/Body/Item/Remove)
+ * @example
+ * ```tsx
+ * <Input.File.UploadButton onOpenFileDialog={fileUpload.onOpenFileDialog}>
+ *   파일 추가
+ * </Input.File.UploadButton>
+ * ```
+ */
+export const InputFile = {
+  DragAndDrop: InputFileDragAndDrop,
+  UploadButton: InputFileUploadButton,
+  UploadedChip: InputFileUploadedChip,
+  List: InputFileList,
+};

package/src/components/input/markup/file/list/Body.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+import clsx from "clsx";
+import type { InputFileListBodyProps } from "../../../types";
+import { useInputFileListContext } from "./Provider";
+
+/**
+ * Input Markup; File List 본문 컴포넌트
+ * @component
+ * @param {InputFileListBodyProps} props list 본문 props
+ * @param {ReactNode} props.children 목록 콘텐츠
+ * @param {boolean} [props.forceMount=false] 접힘 상태에서도 DOM 유지 여부
+ * @example
+ * ```tsx
+ * // forceMount=true면 collapsed 상태에서도 DOM을 유지한다.
+ * <Input.File.List.Body>
+ *   <Input.File.List.Item>...</Input.File.List.Item>
+ * </Input.File.List.Body>
+ * ```
+ */
+const InputFileListBody = ({
+  className,
+  children,
+  forceMount = false,
+  ...restProps
+}: InputFileListBodyProps) => {
+  // List 공유 컨텍스트(접힘 상태)를 조회한다.
+  const context = useInputFileListContext();
+  // collapsible + collapsed 조합일 때만 실제 접힘 상태로 간주한다.
+  const isCollapsed = Boolean(context?.collapsible && context.collapsed);
+
+  // forceMount=false인 경우 접힘 상태에서는 렌더를 생략한다.
+  if (isCollapsed && !forceMount) {
+    return null;
+  }
+
+  return (
+    <div
+      // 루트 class + 외부 className 병합
+      className={clsx("input-file-list-body", className)}
+      // hidden 속성으로 스크린리더/레이아웃 동작을 일관되게 제어한다.
+      hidden={isCollapsed}
+      data-collapsed={isCollapsed ? "true" : undefined}
+      // div native props(id, aria-*)는 확장 가능하게 전달한다.
+      {...restProps}
+    >
+      {/* 접힘 상태에서도 forceMount 옵션으로 측정/애니메이션 요구를 대응할 수 있다. */}
+      {children}
+    </div>
+  );
+};
+
+InputFileListBody.displayName = "InputFileListBody";
+
+export default InputFileListBody;

package/src/components/input/markup/file/list/Container.tsx

@@ -0,0 +1,97 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import clsx from "clsx";
+import type { InputFileListContainerProps } from "../../../types";
+import { InputFileListContextProvider } from "./Provider";
+
+/**
+ * Input Markup; File List 컨테이너 컴포넌트
+ * @component
+ * @param {InputFileListContainerProps} props list 컨테이너 props
+ * @param {ReactNode} props.children list 하위 슬롯 콘텐츠
+ * @param {boolean} [props.collapsible] 헤더 트리거 기반 접기/펼치기 활성화 여부
+ * @param {boolean} [props.defaultCollapsed=false] uncontrolled 초기 접힘 상태
+ * @param {boolean} [props.collapsed] controlled 접힘 상태
+ * @param {(collapsed: boolean) => void} [props.onCollapsedChange] 접힘 상태 변경 콜백
+ * @example
+ * ```tsx
+ * // Header를 trigger로 사용해 List Body를 접고 펼친다.
+ * <Input.File.List.Container collapsible>
+ *   <Input.File.List.Header asTrigger>첨부파일 3</Input.File.List.Header>
+ *   <Input.File.List.Body>
+ *     {fileContext.fileMetas.map(meta => (
+ *       // 렌더링 key는 domain/category/item depth 포맷을 사용한다.
+ *       <Input.File.List.Item key={`input/file/list/item/${meta.id}`}>
+ *         {meta.name}
+ *       </Input.File.List.Item>
+ *     ))}
+ *   </Input.File.List.Body>
+ * </Input.File.List.Container>
+ * ```
+ */
+const InputFileListContainer = ({
+  className,
+  children,
+  collapsible = false,
+  defaultCollapsed = false,
+  collapsed,
+  onCollapsedChange,
+  ...restProps
+}: InputFileListContainerProps) => {
+  // uncontrolled 모드에서만 사용하는 내부 접힘 상태다.
+  const [internalCollapsed, setInternalCollapsed] = useState(defaultCollapsed);
+  // collapsed prop 제공 여부로 controlled/uncontrolled 모드를 구분한다.
+  const isControlled = typeof collapsed === "boolean";
+  // 최종 접힘 상태는 controlled 우선으로 계산한다.
+  const resolvedCollapsed = isControlled ? collapsed : internalCollapsed;
+
+  /**
+   * Input Markup; File List 접힘 상태 토글 핸들러
+   */
+  const onToggleCollapsed = useCallback(() => {
+    // collapsible=false면 토글 동작을 비활성화한다.
+    if (!collapsible) {
+      return;
+    }
+    // 현재 상태를 반전한 다음 상태를 계산한다.
+    const nextCollapsed = !resolvedCollapsed;
+    // uncontrolled 모드일 때만 내부 상태를 갱신한다.
+    if (!isControlled) {
+      setInternalCollapsed(nextCollapsed);
+    }
+    // 외부 콜백이 있으면 상태 변경을 통지한다.
+    onCollapsedChange?.(nextCollapsed);
+  }, [collapsible, isControlled, onCollapsedChange, resolvedCollapsed]);
+
+  // Provider value를 메모화해 불필요한 하위 리렌더를 줄인다.
+  const contextValue = useMemo(
+    () => ({
+      collapsible,
+      collapsed: resolvedCollapsed,
+      onToggleCollapsed,
+    }),
+    [collapsible, resolvedCollapsed, onToggleCollapsed],
+  );
+
+  return (
+    <InputFileListContextProvider value={contextValue}>
+      <section
+        // 루트 클래스는 고정하고 외부 className을 병합한다.
+        className={clsx("input-file-list-container", className)}
+        // 상태는 data-*로 노출해 SCSS에서 조건 스타일을 처리한다.
+        data-collapsible={collapsible ? "true" : undefined}
+        data-collapsed={resolvedCollapsed ? "true" : undefined}
+        // section native props(id, aria-*)는 확장 가능하게 전달한다.
+        {...restProps}
+      >
+        {/* List 루트 상태를 data-* 속성으로 고정해 외부 SCSS 제어를 단순화한다. */}
+        {children}
+      </section>
+    </InputFileListContextProvider>
+  );
+};
+
+InputFileListContainer.displayName = "InputFileListContainer";
+
+export default InputFileListContainer;

package/src/components/input/markup/file/list/Header.tsx

@@ -0,0 +1,86 @@
+"use client";
+
+import clsx from "clsx";
+import type { KeyboardEvent, MouseEvent } from "react";
+import type { InputFileListHeaderProps } from "../../../types";
+import { useInputFileListContext } from "./Provider";
+
+/**
+ * Input Markup; File List 헤더 컴포넌트
+ * @component
+ * @param {InputFileListHeaderProps} props list 헤더 props
+ * @param {ReactNode} props.children 헤더 콘텐츠
+ * @param {boolean} [props.asTrigger=false] 클릭/키보드 트리거로 접기/펼치기 제어 여부
+ * @example
+ * ```tsx
+ * // Header 클릭/키보드 Enter, Space로 collapsed 상태를 전환한다.
+ * <Input.File.List.Header asTrigger>
+ *   <span>첨부파일 3</span>
+ * </Input.File.List.Header>
+ * ```
+ */
+const InputFileListHeader = ({
+  className,
+  children,
+  asTrigger = false,
+  onClick,
+  onKeyDown,
+  ...restProps
+}: InputFileListHeaderProps) => {
+  // Provider에서 공유한 collapsible/collapsed 컨텍스트를 조회한다.
+  const context = useInputFileListContext();
+
+  /**
+   * Input Markup; File List 헤더 클릭 핸들러
+   * @param {MouseEvent<HTMLDivElement>} event 헤더 클릭 이벤트
+   */
+  const handleClick = (event: MouseEvent<HTMLDivElement>) => {
+    // 1) 소비자 onClick을 우선 실행한다.
+    onClick?.(event);
+    // 2) preventDefault되지 않았고 trigger 모드면 collapsed를 토글한다.
+    if (!event.defaultPrevented && asTrigger) {
+      context?.onToggleCollapsed();
+    }
+  };
+
+  /**
+   * Input Markup; File List 헤더 키보드 핸들러
+   * @param {KeyboardEvent<HTMLDivElement>} event 키보드 이벤트
+   */
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    // 1) 소비자 onKeyDown을 우선 실행한다.
+    onKeyDown?.(event);
+    // 2) trigger가 아니거나 preventDefault면 토글을 수행하지 않는다.
+    if (event.defaultPrevented || !asTrigger) {
+      return;
+    }
+    // 3) Enter/Space에서 button과 유사한 접근성 동작을 제공한다.
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      context?.onToggleCollapsed();
+    }
+  };
+
+  return (
+    <div
+      // 루트 class + 외부 className 병합
+      className={clsx("input-file-list-header", className)}
+      // 헤더의 트리거/상태 정보를 data-*로 노출한다.
+      data-trigger={asTrigger ? "true" : undefined}
+      data-collapsible={context?.collapsible ? "true" : undefined}
+      data-collapsed={context?.collapsed ? "true" : undefined}
+      // trigger 모드면 div를 button처럼 접근 가능하게 설정한다.
+      role={asTrigger ? "button" : undefined}
+      tabIndex={asTrigger ? 0 : restProps.tabIndex}
+      onClick={handleClick}
+      onKeyDown={handleKeyDown}
+      {...restProps}
+    >
+      {children}
+    </div>
+  );
+};
+
+InputFileListHeader.displayName = "InputFileListHeader";
+
+export default InputFileListHeader;

package/src/components/input/markup/file/list/Item.tsx

@@ -0,0 +1,35 @@
+import clsx from "clsx";
+import type { InputFileListItemProps } from "../../../types";
+
+/**
+ * Input Markup; File List 항목 컴포넌트
+ * @component
+ * @param {InputFileListItemProps} props list 항목 props
+ * @param {ReactNode} props.children 파일 항목 콘텐츠
+ * @example
+ * ```tsx
+ * // Item 내부 배치는 서비스/도메인에서 자유롭게 구성한다.
+ * fileContext.fileMetas.map(meta => (
+ *   <Input.File.List.Item key={`input/file/list/item/${meta.id}`}>
+ *     <span>{meta.name}</span>
+ *     <span>{meta.sizeLabel}</span>
+ *   </Input.File.List.Item>
+ * ));
+ * ```
+ */
+const InputFileListItem = ({
+  className,
+  children,
+  ...restProps
+}: InputFileListItemProps) => {
+  return (
+    // Item은 레이아웃 뼈대만 제공하고 콘텐츠/행동은 children으로 위임한다.
+    <div className={clsx("input-file-list-item", className)} {...restProps}>
+      {children}
+    </div>
+  );
+};
+
+InputFileListItem.displayName = "InputFileListItem";
+
+export default InputFileListItem;

package/src/components/input/markup/file/list/Provider.tsx

@@ -0,0 +1,35 @@
+"use client";
+
+import { createContext, useContext } from "react";
+import type { InputFileListContextValue } from "../../../types";
+
+/**
+ * Input Markup; File List 컨텍스트 인스턴스
+ */
+const InputFileListContext = createContext<InputFileListContextValue | null>(
+  null,
+);
+
+/**
+ * Input Markup; File List 컨텍스트 생성 헬퍼
+ */
+export const InputFileListContextProvider = InputFileListContext.Provider;
+
+/**
+ * Input Hook; File List 컨텍스트 조회 Hook
+ * @hook
+ * @returns {InputFileListContextValue | null} List 컨텍스트 값(null이면 Container 외부)
+ * @example
+ * ```tsx
+ * // Container 내부에서는 컨텍스트 값이 존재한다.
+ * const fileListContext = useInputFileListContext();
+ * if (!fileListContext) {
+ *   return null;
+ * }
+ * return <span>{fileListContext.collapsed ? "닫힘" : "열림"}</span>;
+ * ```
+ */
+export const useInputFileListContext = (): InputFileListContextValue | null => {
+  // createContext로 생성한 List 컨텍스트를 조회한다.
+  return useContext(InputFileListContext);
+};

package/src/components/input/markup/file/list/Remove.tsx

@@ -0,0 +1,54 @@
+"use client";
+
+import clsx from "clsx";
+import type { MouseEvent } from "react";
+import type { InputFileListRemoveProps } from "../../../types";
+
+/**
+ * Input Markup; File List 제거 액션 컴포넌트
+ * @component
+ * @param {InputFileListRemoveProps} props 제거 액션 props
+ * @param {ReactNode} [props.children] 제거 버튼 콘텐츠
+ * @param {(event: MouseEvent<HTMLButtonElement>) => void} [props.onRemove] 제거 핸들러
+ * @example
+ * ```tsx
+ * // Remove는 삭제 동작 트리거만 제공하고 라벨/아이콘은 외부에서 주입한다.
+ * <Input.File.List.Remove onRemove={() => onRemoveFileById(meta.id)}>
+ *   삭제
+ * </Input.File.List.Remove>
+ * ```
+ */
+const InputFileListRemove = ({
+  className,
+  children,
+  onRemove,
+  type = "button",
+  ...restProps
+}: InputFileListRemoveProps) => {
+  /**
+   * Input Markup; File List 제거 클릭 핸들러
+   * @param {MouseEvent<HTMLButtonElement>} event 제거 클릭 이벤트
+   */
+  const handleClick = (event: MouseEvent<HTMLButtonElement>) => {
+    // 소비자가 전달한 제거 콜백을 실행한다.
+    onRemove?.(event);
+  };
+
+  return (
+    <button
+      // 제출 버튼 오작동을 방지하기 위해 기본 type은 button으로 고정한다.
+      type={type}
+      // 루트 class + 외부 className 병합
+      className={clsx("input-file-list-remove", className)}
+      onClick={handleClick}
+      // button native props(aria-*, disabled 등)는 그대로 전달한다.
+      {...restProps}
+    >
+      {children}
+    </button>
+  );
+};
+
+InputFileListRemove.displayName = "InputFileListRemove";
+
+export default InputFileListRemove;

package/src/components/input/markup/file/list/index.tsx

@@ -0,0 +1,31 @@
+import InputFileListContainer from "./Container";
+import InputFileListHeader from "./Header";
+import InputFileListBody from "./Body";
+import InputFileListItem from "./Item";
+import InputFileListRemove from "./Remove";
+
+/**
+ * Input Markup; File List 네임스페이스
+ * @desc
+ * - Container: collapsible 상태를 관리하는 루트 래퍼
+ * - Header: trigger 모드(asTrigger) 지원 헤더
+ * - Body: collapsed 상태를 반영하는 목록 본문
+ * - Item: 파일 행 레이아웃 뼈대
+ * - Remove: 파일 제거 액션 버튼
+ * @example
+ * ```tsx
+ * <Input.File.List.Container collapsible>
+ *   <Input.File.List.Header asTrigger>첨부파일 2</Input.File.List.Header>
+ *   <Input.File.List.Body>
+ *     <Input.File.List.Item>...</Input.File.List.Item>
+ *   </Input.File.List.Body>
+ * </Input.File.List.Container>
+ * ```
+ */
+export const InputFileList = {
+  Container: InputFileListContainer,
+  Header: InputFileListHeader,
+  Body: InputFileListBody,
+  Item: InputFileListItem,
+  Remove: InputFileListRemove,
+};

package/src/components/input/markup/foundation/SideSlot.tsx

@@ -1,5 +1,3 @@
-"use client";
-
 import clsx from "clsx";
 
 /**

package/src/components/input/markup/foundation/index.tsx

@@ -1,5 +1,3 @@
-"use client";
-
 import InputBase from "./Input";
 import InputBaseSideSlot from "./SideSlot";
 import InputBaseUtil from "./Utility";

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

@@ -2,10 +2,12 @@ import { InputFoundation } from "./foundation";
 import { InputText } from "./text";
 import { InputDate } from "./date";
 import { InputAddress } from "./address";
+import { InputFile } from "./file";
 
 export const Input = {
   ...InputFoundation,
   Text: InputText,
   Date: InputDate,
   Address: InputAddress,
+  File: InputFile,
 };

package/src/components/input/markup/text/Search.tsx

@@ -1,5 +1,3 @@
-"use client";
-
 import { forwardRef } from "react";
 import type { SearchInputProps } from "../../types";
 import InputBase from "../foundation/Input";