@uniai-fe/uds-primitives 0.2.1 → 0.2.3

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

@@ -0,0 +1,249 @@
+import type { ReactNode } from "react";
+import type { Address } from "react-daum-postcode";
+import type {
+  ButtonFill,
+  ButtonPriority,
+  ButtonSize,
+} from "../../button/types";
+import type { InputProps } from "./foundation";
+
+/**
+ * 주소 문자열/배열 정규화 결과.
+ * @property {string} text 최종 병합된 주소 문자열
+ * @property {string[]} parts 주소를 구성하는 파트 배열
+ */
+export interface AddressResolvedValue {
+  /**
+   * 최종 병합된 주소 문자열
+   */
+  text: string;
+  /**
+   * 주소 파트 배열
+   */
+  parts: string[];
+}
+
+/**
+ * 주소 검색 완료 데이터.
+ * @property {string} address 전체 주소 문자열
+ * @property {string[]} [addressParts] 주소를 구성하는 문자열 배열
+ * @property {AddressStructure} [addressStructure] 주소 구성 정보(기본/추가 파트)
+ * @property {string} zipCode 우편번호(5자리)
+ * @property {string} [buildingName] 건물명
+ * @property {string} [district] 법정동/읍면 정보
+ * @property {Address} raw react-daum-postcode Address 원본 데이터
+ */
+export interface AddressSearchResult {
+  /**
+   * 전체 주소 문자열
+   */
+  address: string;
+  /**
+   * 주소를 구성하는 문자열 배열
+   */
+  addressParts?: string[];
+  /**
+   * 주소 구성 정보(기본 주소 + 추가 파트)
+   */
+  addressStructure?: AddressStructure;
+  /**
+   * 우편번호(5자리)
+   */
+  zipCode: string;
+  /**
+   * 건물명
+   */
+  buildingName?: string;
+  /**
+   * 법정동/읍면 정보
+   */
+  district?: string;
+  /**
+   * react-daum-postcode Address 원본 데이터
+   */
+  raw: Address;
+}
+
+/**
+ * 주소 구성 정보.
+ * @property {string} main 기본 주소
+ * @property {string[]} extras 추가 주소 파트 배열
+ * @example
+ * ```ts
+ * const structure: AddressStructure = {
+ *   main: "서울시 강남구 ...",
+ *   extras: ["도곡동", "OO아파트"],
+ * };
+ * ```
+ */
+export interface AddressStructure {
+  /**
+   * 기본 주소
+   */
+  main: string;
+  /**
+   * 추가 주소 파트 배열
+   */
+  extras: string[];
+}
+
+/**
+ * 주소 선택 처리 공통 옵션.
+ * @property {string} [addressFieldName] react-hook-form에 적용할 주소 필드 이름
+ * @property {string} [detailFieldName] react-hook-form에 적용할 상세 주소 필드 이름
+ * @property {string} [zipCodeFieldName] react-hook-form에 적용할 우편번호 필드 이름
+ * @property {boolean} [triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @property {boolean} [resetDetailOnSelect=true] 새 주소 선택 시 상세 주소를 초기화할지 여부
+ * @property {(payload:AddressSearchResult)=>void} [onSelect] 주소 선택 후 콜백
+ */
+export interface AddressSelectionOptions {
+  /**
+   * react-hook-form 주소 필드 이름
+   */
+  addressFieldName?: string;
+  /**
+   * react-hook-form 상세 주소 필드 이름
+   */
+  detailFieldName?: string;
+  /**
+   * react-hook-form 우편번호 필드 이름
+   */
+  zipCodeFieldName?: string;
+  /**
+   * setValue 이후 trigger 실행 여부
+   */
+  triggerValidation?: boolean;
+  /**
+   * 새 주소 선택 시 상세 주소 초기화 여부
+   */
+  resetDetailOnSelect?: boolean;
+  /**
+   * 주소 선택 후 콜백
+   */
+  onSelect?: (payload: AddressSearchResult) => void;
+}
+
+/**
+ * 제한된 입력 스타일 props; priority/size/state/block만 공유한다.
+ */
+export type AddressSharedInputStyleProps = Pick<
+  InputProps,
+  "priority" | "size" | "state"
+>;
+
+/**
+ * 주소 검색 버튼 props.
+ * @property {ReactNode} [children] 버튼 라벨
+ * @property {ButtonPriority} [priority] 버튼 priority
+ * @property {ButtonFill} [fill] 버튼 fill 타입
+ * @property {ButtonSize} [size] 버튼 size
+ * @property {string} [className] 추가 className
+ * @property {"button"|"submit"|"reset"} [type] button type
+ * @property {boolean} [disabled] disabled 여부
+ * @property {string} [addressFieldName] react-hook-form에 적용할 주소 필드 이름
+ * @property {string} [zipCodeFieldName] react-hook-form에 적용할 우편번호 필드 이름
+ * @property {boolean} [triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @property {(payload:AddressSearchResult)=>void} [onSelect] 주소 선택 후 콜백
+ */
+export interface AddressFindButtonProps extends AddressSelectionOptions {
+  /**
+   * 버튼 라벨
+   */
+  label?: ReactNode;
+  /**
+   * 버튼 priority
+   */
+  priority?: ButtonPriority;
+  /**
+   * 버튼 fill 타입
+   */
+  fill?: ButtonFill;
+  /**
+   * 버튼 size
+   */
+  size?: ButtonSize;
+  /**
+   * 추가 className
+   */
+  className?: string;
+  /**
+   * button type
+   */
+  type?: "button" | "submit" | "reset";
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+}
+
+/**
+ * 주소 템플릿 버튼 옵션.
+ * @property {ReactNode} [label] 버튼 라벨
+ * @property {ButtonPriority} [priority] 버튼 priority
+ * @property {ButtonFill} [fill] 버튼 fill 타입
+ * @property {ButtonSize} [size] 버튼 size
+ * @property {boolean} [disabled] 버튼 disabled 여부
+ */
+export interface AddressTemplateButtonOptions {
+  /**
+   * 버튼 라벨
+   */
+  label?: ReactNode;
+  /**
+   * 버튼 priority
+   */
+  priority?: ButtonPriority;
+  /**
+   * 버튼 fill 타입
+   */
+  fill?: ButtonFill;
+  /**
+   * 버튼 size
+   */
+  size?: ButtonSize;
+  /**
+   * 버튼 disabled 여부
+   */
+  disabled?: boolean;
+}
+
+/**
+ * 주소 필드 템플릿 props.
+ * @property {string} [className] container className
+ * @property {AddressSharedInputStyleProps} [inputStyle] 공통 입력 스타일 props
+ * @property {InputProps} addressInput 주소 입력 Input props
+ * @property {InputProps} [detailInput] 상세 주소 입력 props
+ * @property {string} [detailFieldName] react-hook-form에 적용할 상세 주소 필드 이름
+ * @property {AddressTemplateButtonOptions} [buttonProps] 버튼 옵션
+ * @property {boolean} [disabled] 템플릿 disabled 여부
+ * @property {string} [addressFieldName] react-hook-form에 적용할 주소 필드 이름
+ * @property {string} [zipCodeFieldName] react-hook-form에 적용할 우편번호 필드 이름
+ * @property {boolean} [triggerValidation=true] setValue 이후 trigger 실행 여부
+ * @property {(payload:AddressSearchResult)=>void} [onSelect] 주소 선택 후 콜백
+ */
+export interface AddressTemplateProps extends AddressSelectionOptions {
+  /**
+   * container className
+   */
+  className?: string;
+  /**
+   * 공통 입력 스타일 props
+   */
+  inputStyle?: AddressSharedInputStyleProps;
+  /**
+   * 주소 입력 Input props
+   */
+  addressInput: InputProps;
+  /**
+   * 상세 주소 입력 Input props
+   */
+  detailInput?: InputProps;
+  /**
+   * 버튼 옵션
+   */
+  buttonProps?: AddressTemplateButtonOptions;
+  /**
+   * 템플릿 disabled 여부
+   */
+  disabled?: boolean;
+}

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

@@ -0,0 +1,366 @@
+import type { MouseEvent, ReactNode } from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+import type {
+  CalendarColumns,
+  CalendarDatePickerProps,
+  CalendarMode,
+  CalendarOnChange,
+  CalendarValue,
+} from "../../calendar";
+
+/**
+ * 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 {(event: MouseEvent<Element>) => void} [onClick] trigger 클릭 핸들러
+ * @property {boolean} [disabled] disabled 여부
+ * @property {string} [placeholder] trigger 내부 placeholder
+ */
+export interface InputCalendarTriggerProps {
+  /**
+   * trigger id (label htmlFor 연동)
+   */
+  id?: string;
+  /**
+   * form name; register 미사용 시 수동 지정
+   */
+  name?: string;
+  /**
+   * react-hook-form register 결과
+   */
+  register?: UseFormRegisterReturn;
+  /**
+   * trigger 클릭 핸들러
+   */
+  onClick?: (event: MouseEvent<Element>) => void;
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+  /**
+   * trigger 내부 placeholder
+   */
+  placeholder?: string;
+}
+
+/**
+ * Trigger view에서만 사용하는 부가 props.
+ * @property {string} [className] trigger root className
+ * @property {string} [displayValue] 표시 값 문자열
+ */
+export interface InputCalendarTriggerViewProps extends InputCalendarTriggerProps {
+  /**
+   * trigger root className
+   */
+  className?: string;
+  /**
+   * 표시 값 문자열
+   */
+  displayValue?: string;
+}
+
+/**
+ * Calendar Root가 커스텀 trigger에 전달하는 렌더 props.
+ * @property {string} [id] trigger id
+ * @property {string} [name] input name
+ * @property {string} [displayValue] 트리거 표시 문자열
+ * @property {string} [placeholder] 트리거 placeholder
+ * @property {boolean} [disabled] disabled 여부
+ * @property {(event: MouseEvent<Element>) => void} [onClick] 트리거 클릭 핸들러
+ */
+export interface InputCalendarTriggerRenderProps {
+  /**
+   * trigger id
+   */
+  id?: string;
+  /**
+   * input name
+   */
+  name?: string;
+  /**
+   * 트리거 표시 문자열
+   */
+  displayValue?: string;
+  /**
+   * 트리거 placeholder
+   */
+  placeholder?: string;
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+  /**
+   * 트리거 클릭 핸들러
+   */
+  onClick?: (event: MouseEvent<Element>) => void;
+}
+
+/**
+ * Input Calendar core props.
+ * @property {CalendarMode} [mode="date"] 날짜/시간 모드
+ * @property {CalendarColumns} [columns=1] 동시에 노출할 달력 열 수
+ * @property {CalendarValue} [value] 제어형 값
+ * @property {CalendarValue} [defaultValue] 비제어 초기값
+ * @property {CalendarOnChange} [onChange] 값 변경 핸들러(직렬화 문자열 기준)
+ * @property {CalendarOnChange} [onValueChange] onChange 별칭(추가 파이프라인용)
+ * @property {boolean} [readOnly] 읽기 전용 여부
+ * @property {boolean} [disabled] disabled 여부
+ * @property {CalendarDatePickerProps} [datePickerProps] Mantine DatePicker 직접 옵션
+ * @property {ReactNode} [header] 커스텀 header 콘텐츠
+ * @property {ReactNode} [footer] 커스텀 footer 콘텐츠
+ * @property {unknown} [timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
+ * @property {boolean} [calendarOpened] calendar 열림 제어 여부
+ * @property {string} [className] root className
+ * @property {ReactNode} [trigger] 커스텀 trigger 슬롯
+ * @property {(props: InputCalendarTriggerRenderProps) => ReactNode} [renderTrigger] 커스텀 trigger 렌더 함수
+ */
+export interface InputCalendarProps extends InputCalendarTriggerProps {
+  /**
+   * 날짜/시간 모드
+   */
+  mode?: CalendarMode;
+  /**
+   * 동시에 노출할 달력 열 수
+   */
+  columns?: CalendarColumns;
+  /**
+   * 제어형 값
+   */
+  value?: CalendarValue;
+  /**
+   * 비제어 초기값
+   */
+  defaultValue?: CalendarValue;
+  /**
+   * 값 변경 핸들러
+   */
+  onChange?: CalendarOnChange;
+  /**
+   * onChange 별칭; 외부 파이프라인 시 사용
+   */
+  onValueChange?: CalendarOnChange;
+  /**
+   * 읽기 전용 여부
+   */
+  readOnly?: boolean;
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+  /**
+   * Mantine DatePicker 옵션
+   */
+  datePickerProps?: CalendarDatePickerProps;
+  /**
+   * 커스텀 header 콘텐츠
+   */
+  header?: ReactNode;
+  /**
+   * 커스텀 footer 콘텐츠
+   */
+  footer?: ReactNode;
+  /**
+   * TimePicker 확장용 예약 슬롯(현재 미구현).
+   * 추후 Calendar Body 조합 확장 시점에 구체 타입을 확정한다.
+   */
+  timePicker?: unknown;
+  /**
+   * calendar 열림 제어 여부
+   */
+  calendarOpened?: boolean;
+  /**
+   * root className
+   */
+  className?: string;
+  /**
+   * 커스텀 trigger 슬롯
+   */
+  trigger?: ReactNode;
+  /**
+   * 커스텀 trigger 렌더 함수
+   */
+  renderTrigger?: (props: InputCalendarTriggerRenderProps) => ReactNode;
+}
+
+/**
+ * Calendar Container props; Header/Body/Footer depth를 고정한다.
+ * @deprecated Input.Date가 Calendar.Root 직접 위임 구조로 전환되어 현재는 호환용 타입으로만 유지한다.
+ * @property {string} [className] 커스텀 className
+ * @property {InputCalendarViewProps} calendarProps Calendar props
+ * @property {ReactNode} [header] header 콘텐츠
+ * @property {ReactNode} [footer] footer 콘텐츠
+ * @property {CalendarMode} [mode="date"] Calendar 모드
+ * @property {CalendarColumns} [columns=1] 동시에 노출할 열 수
+ * @property {boolean} [disabled] disabled 여부
+ * @property {boolean} [readOnly] readOnly 여부
+ */
+export interface InputCalendarContainerProps {
+  /**
+   * 커스텀 className
+   */
+  className?: string;
+  /**
+   * Calendar props
+   */
+  calendarProps: InputCalendarViewProps;
+  /**
+   * header 콘텐츠
+   */
+  header?: ReactNode;
+  /**
+   * footer 콘텐츠
+   */
+  footer?: ReactNode;
+  /**
+   * Calendar 모드
+   */
+  mode?: CalendarMode;
+  /**
+   * 동시에 노출할 열 수
+   */
+  columns?: CalendarColumns;
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+  /**
+   * readOnly 여부
+   */
+  readOnly?: boolean;
+}
+
+/**
+ * Calendar 본문(DatePicker/TimePicker) props.
+ * @deprecated Input.Date 내부에서 직접 사용하지 않으며, 과거 구조 호환을 위해 유지한다.
+ * @property {CalendarColumns} [columns=1] 열 개수
+ * @property {CalendarValue} value 현재 값
+ * @property {CalendarOnChange} onChange 값 변경 핸들러
+ * @property {CalendarDatePickerProps} [datePickerProps] Mantine DatePicker 옵션
+ * @property {unknown} [timePicker] TimePicker 확장용 예약 슬롯(현재 미구현)
+ */
+export interface InputCalendarViewProps {
+  /**
+   * 열 개수
+   */
+  columns?: CalendarColumns;
+  /**
+   * 현재 값
+   */
+  value: CalendarValue;
+  /**
+   * 값 변경 핸들러
+   */
+  onChange: CalendarOnChange;
+  /**
+   * Mantine DatePicker 옵션
+   */
+  datePickerProps?: CalendarDatePickerProps;
+  /**
+   * TimePicker 확장용 예약 슬롯(현재 미구현).
+   * 추후 Calendar Body 조합 확장 시점에 구체 타입을 확정한다.
+   */
+  timePicker?: unknown;
+}
+
+/**
+ * footer 개별 버튼 공용 props.
+ * @property {ReactNode} [children] 버튼 라벨
+ * @property {() => void} [onClick] click 핸들러
+ * @property {boolean} [disabled] disabled 여부
+ * @property {string} [className] 버튼 className
+ */
+export interface InputCalendarInlineButtonProps {
+  /**
+   * 버튼 라벨
+   */
+  children?: ReactNode;
+  /**
+   * click 핸들러
+   */
+  onClick?: () => void;
+  /**
+   * disabled 여부
+   */
+  disabled?: boolean;
+  /**
+   * 버튼 className
+   */
+  className?: string;
+}
+
+/**
+ * Apply 버튼 전용 props.
+ * @extends InputCalendarInlineButtonProps
+ * @property {ReactNode} [label] children 미지정 시 사용할 기본 라벨
+ */
+export interface InputCalendarApplyButtonProps extends InputCalendarInlineButtonProps {
+  /**
+   * 버튼 라벨
+   */
+  label?: ReactNode;
+}
+
+/**
+ * Footer template의 util 버튼 컨테이너 props.
+ * @property {ReactNode} [children] util 버튼(children)
+ * @property {string} [className] container className
+ */
+export interface InputCalendarFooterUtilContainerProps {
+  /**
+   * util 버튼(children)
+   */
+  children?: ReactNode;
+  /**
+   * container className
+   */
+  className?: string;
+}
+
+/**
+ * Footer template의 루트 컨테이너 props.
+ * @property {ReactNode} [children] footer 내부 children
+ * @property {string} [className] container className
+ */
+export interface InputCalendarFooterTemplateContainerProps {
+  /**
+   * footer 내부 children
+   */
+  children?: ReactNode;
+  /**
+   * container className
+   */
+  className?: string;
+}
+
+/**
+ * 기본 FooterTemplate props.
+ * @property {string} [className] root className
+ * @property {() => void} [onClear] clear 버튼 클릭 핸들러
+ * @property {() => void} [onToday] today 버튼 클릭 핸들러
+ * @property {() => void} [onApply] apply 버튼 클릭 핸들러
+ * @property {boolean} [disabled] 전체 버튼 disabled 여부
+ */
+export interface InputCalendarFooterTemplateProps {
+  /**
+   * root className
+   */
+  className?: string;
+  /**
+   * clear 버튼 클릭 핸들러
+   */
+  onClear?: () => void;
+  /**
+   * today 버튼 클릭 핸들러
+   */
+  onToday?: () => void;
+  /**
+   * apply 버튼 클릭 핸들러
+   */
+  onApply?: () => void;
+  /**
+   * 전체 버튼 disabled 여부
+   */
+  disabled?: boolean;
+}

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

@@ -5,6 +5,7 @@ import type {
   ReactNode,
 } from "react";
 import type { UseFormRegisterReturn } from "react-hook-form";
+import type { FormFieldWidth } from "../../form/types/props";
 
 /**
  * input; priority option
@@ -99,6 +100,7 @@ export interface InputIcon {
  * @property {React.ReactNode} [clear] input reset버튼 커스텀 컨텐츠
  * @property {React.ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
  * @property {React.ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
+ * @property {FormFieldWidth} [width] width preset 옵션
  */
 export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
   /**
@@ -129,6 +131,10 @@ export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
    * react-hook-form register 반환값
    */
   register?: UseFormRegisterReturn;
+  /**
+   * width preset 옵션
+   */
+  width?: FormFieldWidth;
   /**
    * Storybook 등에서 강제 상태 표현용
    */

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

@@ -1,5 +1,6 @@
 export type * from "./foundation";
 export type * from "./text";
-export type * from "./calendar";
+export type * from "./date";
 export type * from "./verification";
 export type * from "./hooks";
+export type * from "./address";