@uniai-fe/uds-primitives 0.1.13 → 0.2.1

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

@@ -0,0 +1,208 @@
+import type {
+  DatePickerProps as MantineDatePickerProps,
+  DatePickerType,
+  DatePickerValue,
+} from "@mantine/dates";
+import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+
+/**
+ * Calendar 모드; 날짜/시간 조합을 구분한다.
+ */
+export type InputCalendarMode = "date" | "date-time" | "time";
+
+/**
+ * Calendar가 한 번에 렌더링할 열 개수.
+ * 단일/듀얼 달력을 명시적으로 구분한다.
+ */
+export type InputCalendarColumns = 1 | 2;
+
+/**
+ * Mantine DatePicker 값 타입을 문자열 기반으로 재정의한다.
+ */
+export type InputCalendarValue<Type extends DatePickerType = "default"> =
+  DatePickerValue<Type, string>;
+
+/**
+ * Calendar 값 변경 핸들러 시그니처.
+ * @template Type Mantine DatePickerType string literal
+ * @property {InputCalendarValue<Type>} value 현재 선택된 값
+ */
+export type InputCalendarOnChange<Type extends DatePickerType = "default"> = (
+  value: InputCalendarValue<Type>,
+) => void;
+
+/**
+ * footer 버튼 기본 속성.
+ * 공통 disabled/label 정책을 공유한다.
+ * @property {ReactNode} [label] 버튼 라벨
+ * @property {boolean} [disabled] 버튼 disabled 상태
+ * @property {boolean} [visible] 버튼 노출 여부. false면 숨김
+ */
+export interface InputCalendarActionButtonProps {
+  /**
+   * 버튼 라벨
+   */
+  label?: ReactNode;
+  /**
+   * 버튼 disabled 상태
+   */
+  disabled?: boolean;
+  /**
+   * 버튼 노출 여부. false면 숨김
+   */
+  visible?: boolean;
+}
+
+/**
+ * footer 액션 핸들러 묶음.
+ * @property {() => void} [onClear] 삭제 버튼 클릭 시 호출
+ * @property {() => void} [onToday] 오늘 버튼 클릭 시 호출
+ * @property {(value: InputCalendarValue) => void} [onApply] 적용 버튼 클릭 시 호출
+ */
+export interface InputCalendarActionHandlers<
+  Type extends DatePickerType = "default",
+> {
+  /**
+   * 삭제/초기화 버튼 핸들러
+   */
+  onClear?: () => void;
+  /**
+   * 오늘 버튼 핸들러
+   */
+  onToday?: () => void;
+  /**
+   * 적용 버튼 핸들러 (현재 값 전달)
+   */
+  onApply?: InputCalendarOnChange<Type>;
+}
+
+/**
+ * footer 액션 구성을 선언한다.
+ * @property {InputCalendarActionButtonProps} [clear] 삭제 버튼 옵션
+ * @property {InputCalendarActionButtonProps} [today] 오늘 버튼 옵션
+ * @property {InputCalendarActionButtonProps} [apply] 적용 버튼 옵션
+ */
+export interface InputCalendarActionOptions {
+  /**
+   * 삭제/초기화 버튼 옵션
+   */
+  clear?: InputCalendarActionButtonProps;
+  /**
+   * 오늘 버튼 옵션
+   */
+  today?: InputCalendarActionButtonProps;
+  /**
+   * 적용 버튼 옵션
+   */
+  apply?: InputCalendarActionButtonProps;
+}
+
+/**
+ * Mantine DatePicker props 중 Input 레이어에서 그대로 노출하지 않을 항목을 제외한 타입.
+ */
+export type InputCalendarMantineProps<Type extends DatePickerType = "default"> =
+  Partial<
+    Omit<
+      MantineDatePickerProps<Type>,
+      "value" | "defaultValue" | "onChange" | "type" | "classNames" | "styles"
+    >
+  >;
+
+/**
+ * Calendar trigger(Input) 영역에서 필요한 속성 묶음.
+ * FormField와의 조합을 고려해 label/helper 등을 상위 Template에 위임한다.
+ * @property {string} [id] trigger id (label htmlFor 연동)
+ * @property {string} [name] form name; register 미사용 시 수동 지정
+ * @property {UseFormRegisterReturn} [register] react-hook-form register 결과
+ * @property {ReactNode} [placeholder] trigger 내부 placeholder
+ * @property {string} [triggerClassName] trigger className (예: InputFoundation box)
+ */
+export interface InputCalendarTriggerProps extends Pick<
+  ComponentPropsWithoutRef<"button">,
+  "onClick" | "disabled"
+> {
+  /**
+   * trigger id (label htmlFor 연동)
+   */
+  id?: string;
+  /**
+   * form name; register 미사용 시 수동 지정
+   */
+  name?: string;
+  /**
+   * react-hook-form register 결과
+   */
+  register?: UseFormRegisterReturn;
+  /**
+   * trigger 내부 placeholder
+   */
+  placeholder?: ReactNode;
+  /**
+   * trigger className (예: InputFoundation box)
+   */
+  triggerClassName?: string;
+}
+
+/**
+ * Input Calendar core props.
+ * @property {InputCalendarMode} [mode="date"] 날짜/시간 모드
+ * @property {DatePickerType} [type="default"] Mantine range/multiple 모드
+ * @property {InputCalendarColumns} [columns=1] 동시에 노출할 달력 열 수
+ * @property {InputCalendarValue} [value] 제어형 값
+ * @property {InputCalendarValue} [defaultValue] 비제어 초기값
+ * @property {InputCalendarOnChange} [onChange] 값 변경 핸들러(직렬화 문자열 기준)
+ * @property {InputCalendarOnChange} [onValueChange] onChange 별칭(추가 파이프라인용)
+ * @property {boolean} [readOnly] 읽기 전용 여부
+ * @property {boolean} [disabled] disabled 여부
+ * @property {InputCalendarMantineProps} [datePickerProps] Mantine DatePicker 직접 옵션
+ * @property {InputCalendarActionOptions} [actions] footer 액션 옵션
+ * @property {InputCalendarActionHandlers} [actionHandlers] footer 버튼 핸들러
+ */
+export interface InputCalendarProps<Type extends DatePickerType = "default">
+  extends InputCalendarActionHandlers<Type>, InputCalendarTriggerProps {
+  /**
+   * 날짜/시간 모드
+   */
+  mode?: InputCalendarMode;
+  /**
+   * Mantine DatePicker type
+   */
+  type?: Type;
+  /**
+   * 동시에 노출할 달력 열 수
+   */
+  columns?: InputCalendarColumns;
+  /**
+   * 제어형 값
+   */
+  value?: InputCalendarValue<Type>;
+  /**
+   * 비제어 초기값
+   */
+  defaultValue?: InputCalendarValue<Type>;
+  /**
+   * 값 변경 핸들러
+   */
+  onChange?: InputCalendarOnChange<Type>;
+  /**
+   * onChange 별칭; 외부 파이프라인 시 사용
+   */
+  onValueChange?: InputCalendarOnChange<Type>;
+  /**
+   * 읽기 전용 여부
+   */
+  readOnly?: boolean;
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+  /**
+   * Mantine DatePicker 옵션
+   */
+  datePickerProps?: InputCalendarMantineProps<Type>;
+  /**
+   * footer 버튼 옵션
+   */
+  actions?: InputCalendarActionOptions;
+}

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

@@ -0,0 +1,194 @@
+import type {
+  ComponentPropsWithoutRef,
+  MouseEvent,
+  PointerEvent,
+  ReactNode,
+} from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+
+/**
+ * input; priority option
+ */
+export type InputPriority = "primary" | "secondary" | "tertiary";
+/**
+ * input; size option
+ */
+export type InputSize = "small" | "medium" | "large";
+/**
+ * input; state option
+ */
+export type InputState =
+  | "default"
+  | "active"
+  | "focused"
+  | "success"
+  | "error"
+  | "disabled"
+  | "loading";
+
+/**
+ * priority 축은 tokens 기반 테마 계층을 지정한다.
+ */
+export const INPUT_PRIORITIES: InputPriority[] = [
+  "primary",
+  "secondary",
+  "tertiary",
+];
+/**
+ * size 축은 높이/타이포/spacing을 결정한다.
+ */
+export const INPUT_SIZES: InputSize[] = ["small", "medium", "large"];
+/**
+ * 시각 상태는 success/error/disabled 를 포함한다.
+ */
+export const INPUT_STATES: InputState[] = [
+  "default",
+  "active",
+  "focused",
+  "success",
+  "error",
+  "disabled",
+  "loading",
+];
+
+type NativeInputProps = ComponentPropsWithoutRef<"input">;
+
+/**
+ * input; icon options
+ * @property {React.ReactNode} [left] input 왼쪽 컨텐츠
+ * @property {React.ReactNode} [right] input 오른쪽 컨텐츠
+ * @property {React.ReactNode} [clear] input reset버튼 커스텀 컨텐츠
+ * @property {React.ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
+ * @property {React.ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
+ */
+export interface InputIcon {
+  /**
+   * 왼쪽 슬롯 콘텐츠
+   */
+  left?: React.ReactNode;
+  /**
+   * 오른쪽 슬롯 콘텐츠
+   */
+  right?: React.ReactNode;
+  /**
+   * clear 버튼 아이콘
+   */
+  clear?: React.ReactNode;
+  /**
+   * success 상태 아이콘
+   */
+  success?: React.ReactNode;
+  /**
+   * error 상태 아이콘
+   */
+  error?: React.ReactNode;
+}
+
+/**
+ * Input; input base props
+ * @property {NativeInputProps} ... <input /> native attrs
+ * @property {InputPriority} [priority] 스타일 카테고리 타입
+ * @property {InputSize} [size] 스타일 사이즈 타입
+ * @property {InputState} [state] input 상태
+ * @property {boolean} [block] width: 100% 여부
+ * @property {string} [inputClassName]
+ * @property {string} [boxClassName]
+ * @property {UseFormRegisterReturn} [register]
+ * @property {React.ReactNode} [left] input 왼쪽 컨텐츠
+ * @property {React.ReactNode} [right] input 오른쪽 컨텐츠
+ * @property {React.ReactNode} [clear] input reset버튼 커스텀 컨텐츠
+ * @property {React.ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
+ * @property {React.ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
+ */
+export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
+  /**
+   * semantic color/token 세트
+   */
+  priority?: InputPriority;
+  /**
+   * 높이/타이포 세트
+   */
+  size?: InputSize;
+  /**
+   * 시각 상태. disabled prop과 조합된다
+   */
+  state?: InputState;
+  /**
+   * true면 width:100%
+   */
+  block?: boolean;
+  /**
+   * 실제 `<input>` className
+   */
+  inputClassName?: string;
+  /**
+   * `.input-box` className
+   */
+  boxClassName?: string;
+  /**
+   * react-hook-form register 반환값
+   */
+  register?: UseFormRegisterReturn;
+  /**
+   * Storybook 등에서 강제 상태 표현용
+   */
+  "data-simulated-state"?: InputState;
+}
+
+/**
+ * Input 오른쪽 유틸리티 props.
+ * @property {ReactNode} [children] right 슬롯 콘텐츠
+ * @property {ReactNode} [clear] clear 버튼 아이콘
+ * @property {ReactNode} [success] success 상태 아이콘
+ * @property {ReactNode} [error] error 상태 아이콘
+ * @property {InputState} state 현재 상태
+ * @property {boolean} isDisabled disabled 여부
+ * @property {boolean} isFocused focus 여부
+ * @property {boolean} hasValue 값 존재 여부
+ * @property {boolean} [readOnly] readOnly 여부
+ * @property {(event:MouseEvent|PointerEvent)=>void} [onClear] clear 버튼 핸들러
+ */
+export interface InputUtilityProps {
+  /**
+   * 오른쪽 슬롯 콘텐츠
+   */
+  children?: ReactNode;
+  /**
+   * clear 버튼 아이콘
+   */
+  clear?: ReactNode;
+  /**
+   * success 상태 아이콘
+   */
+  success?: ReactNode;
+  /**
+   * error 상태 아이콘
+   */
+  error?: ReactNode;
+  /**
+   * 현재 input 상태
+   */
+  state: InputState;
+  /**
+   * disabled 여부
+   */
+  isDisabled: boolean;
+  /**
+   * focus 여부
+   */
+  isFocused: boolean;
+  /**
+   * 값 존재 여부
+   */
+  hasValue: boolean;
+  /**
+   * readOnly 여부
+   */
+  readOnly?: boolean;
+  /**
+   * clear 버튼 핸들러
+   */
+  onClear?: (
+    event: MouseEvent<HTMLButtonElement> | PointerEvent<HTMLButtonElement>,
+  ) => void;
+}

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

@@ -0,0 +1,43 @@
+import type { ChangeEvent } from "react";
+
+/**
+ * 숫자 입력 필드 옵션.
+ * @property {string} [value] 제어형 값
+ * @property {string} [defaultValue] 비제어 초기값
+ * @property {number} [maxLength] 자리수 제한
+ */
+export interface UseDigitFieldOptions {
+  /**
+   * 제어형 값
+   */
+  value?: string;
+  /**
+   * 비제어 초기값
+   */
+  defaultValue?: string;
+  /**
+   * 최대 자리수
+   */
+  maxLength?: number;
+}
+
+/**
+ * 숫자 필드 hook 반환값.
+ * @property {string} digits 현재 숫자 문자열
+ * @property {boolean} isControlled 제어형 여부
+ * @property {(event:ChangeEvent<HTMLInputElement>)=>string} handleDigitsChange 입력 핸들러
+ */
+export interface UseDigitFieldResult {
+  /**
+   * 현재 숫자 문자열
+   */
+  digits: string;
+  /**
+   * 제어형 여부
+   */
+  isControlled: boolean;
+  /**
+   * onChange 핸들러
+   */
+  handleDigitsChange: (event: ChangeEvent<HTMLInputElement>) => string;
+}

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

@@ -1,87 +1,5 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
-import type { UseFormRegisterReturn } from "react-hook-form";
-
-/**
- * priority 축은 tokens 기반 테마 계층을 지정한다.
- */
-export const INPUT_PRIORITIES = ["primary", "secondary", "tertiary"] as const;
-/**
- * size 축은 높이/타이포/spacing을 결정한다.
- */
-export const INPUT_SIZES = ["small", "medium", "large"] as const;
-/**
- * 시각 상태는 success/error/disabled 를 포함한다.
- */
-export const INPUT_STATES = [
-  "default",
-  "active",
-  "focused",
-  "success",
-  "error",
-  "disabled",
-  "loading",
-] as const;
-
-export type InputPriority = (typeof INPUT_PRIORITIES)[number];
-export type InputSize = (typeof INPUT_SIZES)[number];
-export type InputState = (typeof INPUT_STATES)[number];
-
-type NativeInputProps = ComponentPropsWithoutRef<"input">;
-
-/**
- * 좌우 슬롯과 status 아이콘 정의.
- */
-export interface InputIcon {
-  left?: ReactNode;
-  right?: ReactNode;
-  clear?: ReactNode;
-  success?: ReactNode;
-  error?: ReactNode;
-}
-
-/**
- * label/helper 등 피드백 슬롯 정의.
- */
-export interface InputFeedback {
-  label?: ReactNode;
-  helper?: ReactNode;
-  hideHelper?: boolean;
-}
-
-/**
- * 텍스트 입력의 핵심 props. native input 속성에서 size는 제외하고 left/right 등 슬롯을 별도로 정의한다.
- */
-export interface InputProps
-  extends Omit<NativeInputProps, "size">, InputIcon, InputFeedback {
-  /** semantic color/token 세트 */
-  priority?: InputPriority;
-  /** 높이/타이포 세트 */
-  size?: InputSize;
-  /** 시각 상태. disabled prop과 조합된다 */
-  state?: InputState;
-  /** true면 width:100% */
-  block?: boolean;
-  /** 실제 `<input>` className */
-  inputClassName?: string;
-  /** `.input-box` className */
-  boxClassName?: string;
-  /** label attr 커스터마이즈 */
-  labelProps?: ComponentPropsWithoutRef<"label">;
-  /** helper attr 커스터마이즈 */
-  helperProps?: ComponentPropsWithoutRef<"div">;
-  /** react-hook-form register 반환값 */
-  register?: UseFormRegisterReturn;
-  /** Storybook 등에서 강제 상태 표현용 */
-  "data-simulated-state"?: InputState;
-}
-
-/**
- * className composer helper가 필요로 하는 파라미터 집합.
- */
-export interface InputClassNameOptions {
-  priority: InputPriority;
-  size: InputSize;
-  state: InputState;
-  block: boolean;
-  className?: string;
-}
+export type * from "./foundation";
+export type * from "./text";
+export type * from "./calendar";
+export type * from "./verification";
+export type * from "./hooks";