@uniai-fe/uds-primitives 0.3.19 → 0.3.21

package/src/components/select/types/props.ts

@@ -1,5 +1,10 @@
-import type { HTMLAttributes, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  HTMLAttributes,
+  ReactNode,
+} from "react";
 import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
+import type { UseFormRegisterReturn } from "react-hook-form";
 
 import type {
   DropdownContainerProps,
@@ -8,7 +13,7 @@ import type {
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
 import type { SelectPriority, SelectSize, SelectState } from "./base";
-import type { SelectDropdownOption, SelectOptionChangePayload } from "./option";
+import type { SelectDropdownOption } from "./option";
 import type {
   SelectTriggerDefaultProps,
   SelectTriggerMultipleProps,
@@ -24,7 +29,6 @@ import type {
 export interface SelectStyleOptions {
   /**
    * priority scale
-   * - table 우선순위는 width 미지정 시 기본 block(full)로 동작한다.
    */
   priority?: SelectPriority;
   /**
@@ -69,13 +73,13 @@ export interface SelectValueOptions {
 
 /**
  * Select; 상태 옵션
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  */
 export interface SelectComponentState {
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
 }
 
 /**
@@ -83,6 +87,7 @@ export interface SelectComponentState {
  * @property {string} [className] 사용자 정의 className
  * @property {ReactNode} children trigger/Dropdown 등 내부 콘텐츠
  * @property {boolean} [block] block 여부
+ * @property {FormFieldWidth} [width] width preset
  */
 export interface SelectContainerProps extends HTMLAttributes<HTMLDivElement> {
   /**
@@ -115,147 +120,222 @@ export interface SelectWidthOption {
 }
 
 /**
- * Select root props
- * @typedef {SelectStyleOptions & SelectValueOptions & SelectComponentState} SelectProps
- * @property {SelectPriority} [priority] priority scale
- * @property {SelectSize} [size] size scale
- * @property {SelectState} [state] visual state
- * @property {boolean} [block] block 여부
- * @property {ReactNode} [displayLabel] 선택된 라벨
- * @property {ReactNode} [placeholder] placeholder 텍스트
- * @property {ReactNode[]} [tags] multi select 태그 리스트
- * @property {boolean} [multiple] multi select 여부
- * @property {boolean} [isOpen] dropdown open 여부
- * @property {FormFieldWidth} [width] width preset 옵션
- */
-export type SelectProps = SelectStyleOptions &
-  SelectValueOptions &
-  SelectComponentState &
-  SelectWidthOption;
-
-/**
- * Select dropdown 옵션 구성 props; 옵션 모델/이벤트/하위호환 제어 축을 정의한다.
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트(권장: options[].selected로 초기값 선언)
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트(legacy controlled)
- * @property {(payload: SelectOptionChangePayload) => void} [onChange] 선택 결과 변경 콜백(권장)
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백(legacy)
- * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
- * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {DropdownMenuProps} [dropdownRootProps] Dropdown.Root 전달 props(제어 props 제외)
- * @property {DropdownContainerProps} [dropdownContainerProps] Dropdown.Container 전달 props(children/size 제외)
- * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
- * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ * Select custom option props
+ * @property {string} [placeholder] 직접입력 모드 전용 placeholder
+ * @property {ReactNode} [optionName] dropdown의 "직접 입력" 옵션 문구
  */
-export interface SelectDropdownConfigProps {
+export interface SelectCustomOptions {
   /**
-   * dropdown option 리스트
-   * - 권장: uncontrolled 초기 선택은 options[].selected를 사용한다.
+   * 직접입력 모드 전용 placeholder
+   * - 미지정 시 Select root placeholder를 재사용한다.
    */
-  options?: SelectDropdownOption[];
+  placeholder?: string;
   /**
-   * 선택된 option id 리스트
-   * @deprecated onChange + options[].selected 기반 계약을 우선 사용한다.
+   * dropdown의 "직접 입력" 옵션 문구
+   * - 미지정 시 "직접 입력"을 기본값으로 사용한다.
    */
-  selectedOptionIds?: string[];
+  optionName?: ReactNode;
+}
+
+/**
+ * Select custom input props
+ * @property {ComponentPropsWithoutRef<"input">} [native] label input native 속성
+ */
+export interface SelectCustomInputProps extends ComponentPropsWithoutRef<"input"> {
+  placeholder?: never;
+}
+
+/**
+ * Select form register extension
+ * @property {UseFormRegisterReturn} [register] source field register(기본: hidden value input)
+ * @property {UseFormRegisterReturn} [customRegister] custom field register(직접입력 label input)
+ */
+export interface SelectFormRegisterExtension {
   /**
-   * 선택 결과 변경 콜백
-   * - 권장: payload.selectedOptions / payload.selectedValues를 직접 소비한다.
+   * source field register
+   * - Select value 제출 필드(`select-input-value`)에 연결한다.
    */
-  onChange?: (payload: SelectOptionChangePayload) => void;
+  register?: UseFormRegisterReturn;
   /**
-   * option 선택 콜백
-   * @deprecated onChange로 대체되며 하위호환을 위해 유지된다.
+   * custom field register
+   * - 직접입력 label 필드(`select-input-label`)에 연결한다.
    */
-  onOptionSelect?: (option: SelectDropdownOption) => void;
+  customRegister?: UseFormRegisterReturn;
+}
+
+/**
+ * Select callback params
+ * @property {SelectDropdownOption} [nextOption] 현재 상호작용한 option
+ * @property {SelectDropdownOption} [prevOption] 이전 기준 option
+ * @property {Event} [event] 원본 메뉴 선택 이벤트
+ */
+export type SelectCallbackParams = (
+  nextOption?: SelectDropdownOption,
+  prevOption?: SelectDropdownOption,
+  event?: Event,
+) => void;
+
+/**
+ * Select dropdown 확장 props
+ * @property {SelectSize} [size] dropdown surface size 스케일
+ * @property {DropdownPanelWidth} [width] dropdown panel width 옵션
+ * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [rootProps] Dropdown.Root 전달 props
+ * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [containerProps] Dropdown.Container 전달 props
+ * @property {DropdownMenuListProps} [menuListProps] Dropdown.Menu.List 전달 props
+ * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ */
+export interface SelectDropdownExtension {
   /**
    * dropdown surface size 스케일
    */
-  dropdownSize?: SelectSize;
+  size?: SelectSize;
   /**
    * dropdown panel width 옵션
    */
-  dropdownWidth?: DropdownPanelWidth;
+  width?: DropdownPanelWidth;
   /**
    * Dropdown.Root 전달 props(제어 props 제외)
-   * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
    */
-  dropdownRootProps?: Omit<
-    DropdownMenuProps,
-    "open" | "defaultOpen" | "onOpenChange"
-  >;
+  rootProps?: Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">;
   /**
-   * Dropdown.Container 전달 props(children/size 제외)
+   * Dropdown.Container 전달 props(children/size/width 제외)
    */
-  dropdownContainerProps?: Omit<
-    DropdownContainerProps,
-    "children" | "size" | "width"
-  >;
+  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
   /**
    * Dropdown.Menu.List 전달 props
    */
-  dropdownMenuListProps?: DropdownMenuListProps;
+  menuListProps?: DropdownMenuListProps;
   /**
-   * option이 비어 있을 때 렌더링할 alternate 콘텐츠
+   * item이 비어 있을 때 렌더링할 alternate 콘텐츠
    */
   alt?: ReactNode;
 }
 
 /**
- * Select dropdown 개방 제어 props; open controlled/uncontrolled 축을 정의한다.
+ * Select dropdown 옵션 구성 props
+ * @property {SelectDropdownOption[]} [items] dropdown item 리스트(권장: items[].selected 초기값)
+ * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
+ */
+export interface SelectDropdownConfigProps {
+  /**
+   * dropdown item 리스트
+   */
+  items: SelectDropdownOption[];
+  /**
+   * option 선택 액션 콜백
+   */
+  onSelectOption?: SelectCallbackParams;
+  /**
+   * 선택값 변경 콜백
+   */
+  onSelectChange?: SelectCallbackParams;
+  /**
+   * dropdown 확장 옵션
+   */
+  dropdownOptions?: SelectDropdownExtension;
+}
+
+/**
+ * Select dropdown 개방 제어 props
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
- * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
+ * @property {(open: boolean) => void} [onOpen] open state change 콜백
  */
 export interface SelectDropdownBehaviorProps {
   /**
    * dropdown open 상태
-   * - 값이 있으면 controlled open 모드로 동작한다.
    */
   open?: boolean;
   /**
    * uncontrolled 초기 open 상태
-   * - open prop이 없을 때만 초기값으로 사용된다.
    */
   defaultOpen?: boolean;
   /**
    * open state change 콜백
-   * - controlled/uncontrolled 모두에서 호출된다.
    */
-  onOpenChange?: (open: boolean) => void;
+  onOpen?: (open: boolean) => void;
+}
+
+/**
+ * Select trigger native event props
+ * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
+ */
+export interface SelectTriggerEventProps {
+  /**
+   * trigger native 속성/이벤트
+   */
+  triggerProps?: HTMLAttributes<HTMLElement>;
+}
+
+/**
+ * Select custom option extension
+ * @property {SelectCustomOptions} [customOptions] 직접 입력 옵션 구성
+ * @property {SelectCustomInputProps} [inputProps] 직접 입력 input 구성
+ */
+export interface SelectCustomOptionExtension {
+  /**
+   * 직접 입력 옵션 구성
+   */
+  customOptions?: SelectCustomOptions;
+  /**
+   * 직접 입력 input 구성
+   */
+  inputProps?: SelectCustomInputProps;
 }
 
+/**
+ * Select root props
+ * @property {SelectPriority} [priority] priority scale
+ * @property {SelectSize} [size] size scale
+ * @property {SelectState} [state] visual state
+ * @property {boolean} [block] block 여부
+ * @property {ReactNode} [displayLabel] 선택된 라벨
+ * @property {ReactNode} [placeholder] placeholder 텍스트
+ * @property {ReactNode[]} [tags] multi select 태그 리스트
+ * @property {boolean} [multiple] multi select 여부
+ * @property {boolean} [open] dropdown open 여부
+ * @property {FormFieldWidth} [width] width preset 옵션
+ */
+export type SelectProps = SelectStyleOptions &
+  SelectValueOptions &
+  SelectComponentState &
+  SelectWidthOption;
+
 /**
  * Select.Default 컴포넌트 props
- * @typedef {SelectTriggerDefaultProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption} SelectDefaultComponentProps
  * @property {ReactNode} [displayLabel] 선택된 라벨
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {SelectPriority} [priority] priority scale
  * @property {SelectSize} [size] size scale
  * @property {SelectState} [state] visual state
  * @property {boolean} [block] block 여부
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {SelectTriggerButtonType} [buttonType] button type
  * @property {FormFieldWidth} [width] width preset 옵션
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
- * @property {(payload: SelectOptionChangePayload) => void} [onChange] 선택 결과 변경 콜백
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
- * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
- * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [dropdownRootProps] Dropdown.Root 전달 props
- * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [dropdownContainerProps] Dropdown.Container 전달 props
- * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
- * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ * @property {SelectDropdownOption[]} [items] dropdown item 리스트
+ * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
- * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
+ * @property {(open: boolean) => void} [onOpen] open state change 콜백
+ * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
+ * @property {SelectCustomOptions} [customOptions] 직접 입력 옵션 구성
+ * @property {SelectCustomInputProps} [inputProps] 직접 입력 input 구성
+ * @property {UseFormRegisterReturn} [register] source field register
+ * @property {UseFormRegisterReturn} [customRegister] custom field register
  */
 export type SelectDefaultComponentProps = SelectTriggerDefaultProps &
   SelectDropdownConfigProps &
   SelectDropdownBehaviorProps &
-  SelectWidthOption;
+  SelectWidthOption &
+  SelectTriggerEventProps &
+  SelectCustomOptionExtension &
+  SelectFormRegisterExtension;
 
 /**
  * Select.Multiple 전체 선택 옵션 props
@@ -275,7 +355,6 @@ export interface SelectMultipleAllOptionProps {
 
 /**
  * Select.Multiple 컴포넌트 props
- * @typedef {SelectTriggerMultipleProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption & SelectMultipleAllOptionProps} SelectMultipleComponentProps
  * @property {ReactNode} [displayLabel] 선택된 라벨
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {SelectMultipleTag[]} [tags] multi select tag 리스트
@@ -283,23 +362,18 @@ export interface SelectMultipleAllOptionProps {
  * @property {SelectSize} [size] size scale
  * @property {SelectState} [state] visual state
  * @property {boolean} [block] block 여부
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {FormFieldWidth} [width] width preset 옵션
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
- * @property {(payload: SelectOptionChangePayload) => void} [onChange] 선택 결과 변경 콜백
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
- * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
- * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [dropdownRootProps] Dropdown.Root 전달 props
- * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [dropdownContainerProps] Dropdown.Container 전달 props
- * @property {DropdownMenuListProps} [dropdownMenuListProps] Dropdown.Menu.List 전달 props
- * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
+ * @property {SelectDropdownOption[]} [items] dropdown item 리스트
+ * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
- * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
+ * @property {(open: boolean) => void} [onOpen] open state change 콜백
+ * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
  * @property {boolean} [showSelectAllOption] dropdown 첫 행에 "전체" 옵션 노출 여부
  * @property {ReactNode} [selectAllLabel] "전체" 옵션 라벨 커스터마이징
  */
@@ -307,4 +381,5 @@ export type SelectMultipleComponentProps = SelectTriggerMultipleProps &
   SelectDropdownConfigProps &
   SelectDropdownBehaviorProps &
   SelectWidthOption &
-  SelectMultipleAllOptionProps;
+  SelectMultipleAllOptionProps &
+  SelectTriggerEventProps;

package/src/components/select/types/trigger.ts

@@ -1,4 +1,11 @@
-import type { ElementType, HTMLAttributes, ReactNode } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  ElementType,
+  HTMLAttributes,
+  ReactNode,
+} from "react";
+import type { UseFormRegisterReturn } from "react-hook-form";
+import type { SelectOptionValue } from "./option";
 
 import type {
   SelectPriority,
@@ -32,6 +39,7 @@ export interface SelectTriggerBaseProps extends HTMLAttributes<HTMLElement> {
   priority?: SelectPriority;
   /**
    * size scale
+   * - xsmall (primary 전용)
    * - small
    * - medium
    * - large
@@ -101,6 +109,7 @@ export interface SelectTriggerDefaultProps extends HTMLAttributes<HTMLElement> {
   priority?: SelectPriority;
   /**
    * size scale
+   * - xsmall (primary 전용)
    * - small
    * - medium
    * - large
@@ -120,7 +129,7 @@ export interface SelectTriggerDefaultProps extends HTMLAttributes<HTMLElement> {
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
   /**
    * disabled 여부
    */
@@ -161,6 +170,7 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
   priority?: SelectPriority;
   /**
    * size scale
+   * - xsmall (primary 전용)
    * - small
    * - medium
    * - large
@@ -180,7 +190,7 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
   /**
    * disabled 여부
    */
@@ -196,6 +206,14 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
  * @property {ReactNode} [label] 표시할 라벨
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {boolean} [isPlaceholder] placeholder 상태 여부
+ * @property {boolean} [readOnly] readOnly 여부
+ * @property {UseFormRegisterReturn} [register] source field register
+ * @property {UseFormRegisterReturn} [customRegister] custom field register
+ * @property {ComponentPropsWithoutRef<"input">} [inputProps] label input native 속성
+ * @property {string} [valueText] label input 표시 문자열
+ * @property {SelectOptionValue | ""} [valueFieldValue] hidden value input 값
+ * @property {boolean} [shouldFocusInput] custom mode 진입 시 label input focus 여부
+ * @property {(value: string) => void} [onLabelChange] label 입력 변경 콜백
  */
 export interface SelectSelectedProps {
   /**
@@ -210,4 +228,37 @@ export interface SelectSelectedProps {
    * placeholder 상태 여부
    */
   isPlaceholder?: boolean;
+  /**
+   * readOnly 여부
+   */
+  readOnly?: boolean;
+  /**
+   * source field register
+   */
+  register?: UseFormRegisterReturn;
+  /**
+   * custom field register
+   */
+  customRegister?: UseFormRegisterReturn;
+  /**
+   * label input native 속성
+   * - placeholder는 root/customOptions 경로가 우선하므로 제외한다.
+   */
+  inputProps?: Omit<ComponentPropsWithoutRef<"input">, "placeholder">;
+  /**
+   * label input 표시 문자열
+   */
+  valueText?: string;
+  /**
+   * hidden value input 값
+   */
+  valueFieldValue?: SelectOptionValue | "";
+  /**
+   * custom mode 진입 시 label input focus 여부
+   */
+  shouldFocusInput?: boolean;
+  /**
+   * label 입력 변경 콜백
+   */
+  onLabelChange?: (value: string) => void;
 }