@uniai-fe/uds-primitives 0.3.26 → 0.3.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,

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

@@ -35,3 +35,11 @@ export type SelectState = "default" | "focused" | "error" | "disabled";
  * - reset: form reset trigger
  */
 export type SelectTriggerButtonType = "button" | "submit" | "reset";
+
+/**
+ * Select option data optionality
+ * @typedef {"optional" | "required"} SelectOptionDataOptionality
+ * - optional: option.data를 선택 속성으로 유지
+ * - required: option.data를 필수 속성으로 강제
+ */
+export type SelectOptionDataOptionality = "optional" | "required";

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

@@ -1,4 +1,5 @@
 import type { ReactNode } from "react";
+import type { SelectOptionDataOptionality } from "./base";
 
 /**
  * Select option value 타입
@@ -15,7 +16,7 @@ export type SelectOptionValue = string | number;
  * @property {boolean} [selected] uncontrolled 초기 선택 여부(권장 초기화 필드)
  * @property {OptionData} [data] 도메인 확장 payload(서비스 2차 활용 데이터)
  */
-export interface SelectOptionData<OptionData = unknown> {
+export interface SelectOptionDataBase {
   /**
    * 선택 상태 추적용 고유 id
    * - UI 선택 상태 비교의 기준값이다.
@@ -42,13 +43,61 @@ export interface SelectOptionData<OptionData = unknown> {
    * - selectedOptionIds 없이도 초기값을 선언할 수 있는 권장 필드다.
    */
   selected?: boolean;
-  /**
-   * 도메인 확장 payload
-   * - 선택 후 서비스 코드에서 2차 데이터로 활용할 수 있다.
-   */
-  data?: OptionData;
 }
 
+/**
+ * Select option data payload; optionality 제어 타입
+ * @property {OptionData} [data] optional 모드 데이터(생략 가능)
+ * @property {OptionData} data required 모드 데이터(필수)
+ * @example
+ * type OptionalPayload = SelectOptionDataPayload<{ id: number }, "optional">;
+ * // { data?: { id: number } }
+ *
+ * type RequiredPayload = SelectOptionDataPayload<{ id: number }, "required">;
+ * // { data: { id: number } }
+ */
+export type SelectOptionDataPayload<
+  OptionData = unknown,
+  DataOptionality extends SelectOptionDataOptionality = "optional",
+> = DataOptionality extends "required"
+  ? {
+      /**
+       * 도메인 확장 payload
+       * - 선택 후 서비스 코드에서 2차 데이터로 활용한다.
+       * - required 모드에서는 필수다.
+       */
+      data: OptionData;
+    }
+  : {
+      /**
+       * 도메인 확장 payload
+       * - 선택 후 서비스 코드에서 2차 데이터로 활용한다.
+       * - optional 모드에서는 생략 가능하다.
+       */
+      data?: OptionData;
+    };
+
+/**
+ * Select option data; optionality 제어가 포함된 최종 데이터 계약
+ * @property {string} id 선택 상태 추적용 고유 id
+ * @property {SelectOptionValue} value 실제 제출값
+ * @property {ReactNode} label 사용자 표시 라벨
+ * @property {boolean} [disabled] 선택 불가 상태 여부
+ * @property {boolean} [selected] uncontrolled 초기 선택 여부
+ * @property {OptionData} [data] optionality="optional"일 때 선택 payload
+ * @property {OptionData} data optionality="required"일 때 필수 payload
+ * @example
+ * type OptionalOption = SelectOptionData<{ code: string }, "optional">;
+ * // data?: { code: string }
+ *
+ * type RequiredOption = SelectOptionData<{ code: string }, "required">;
+ * // data: { code: string }
+ */
+export type SelectOptionData<
+  OptionData = unknown,
+  DataOptionality extends SelectOptionDataOptionality = "optional",
+> = SelectOptionDataBase & SelectOptionDataPayload<OptionData, DataOptionality>;
+
 /**
  * Select option render data; Dropdown.Menu.Item 시각 보조 정보
  * @property {ReactNode} [description] 보조 텍스트
@@ -88,11 +137,27 @@ export interface SelectOptionRenderData {
  * @property {ReactNode} label 사용자 노출 라벨
  * @property {boolean} [disabled] 비활성 여부
  * @property {boolean} [selected] uncontrolled 초기 선택 여부
- * @property {OptionData} [data] 추가 데이터 payload
+ * @property {OptionData} [data] optionality="optional"일 때 추가 데이터 payload
+ * @property {OptionData} data optionality="required"일 때 추가 데이터 payload(필수)
  * @property {ReactNode} [description] 보조 텍스트
  * @property {ReactNode} [left] 좌측 콘텐츠
  * @property {ReactNode} [right] 우측 콘텐츠
  * @property {boolean} [multiple] multi select 스타일 여부
+ * @example
+ * const optionA: SelectDropdownOption<{ metaKey: number }, "optional"> = {
+ *   id: "1",
+ *   value: 1,
+ *   label: "기본",
+ * };
+ *
+ * const optionB: SelectDropdownOption<{ metaKey: number }, "required"> = {
+ *   id: "2",
+ *   value: 2,
+ *   label: "필수",
+ *   data: { metaKey: 2 },
+ * };
  */
-export interface SelectDropdownOption<OptionData = unknown>
-  extends SelectOptionData<OptionData>, SelectOptionRenderData {}
+export type SelectDropdownOption<
+  OptionData = unknown,
+  DataOptionality extends SelectOptionDataOptionality = "optional",
+> = SelectOptionData<OptionData, DataOptionality> & SelectOptionRenderData;

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

@@ -12,7 +12,12 @@ import type {
   DropdownPanelWidth,
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
-import type { SelectPriority, SelectSize, SelectState } from "./base";
+import type {
+  SelectOptionDataOptionality,
+  SelectPriority,
+  SelectSize,
+  SelectState,
+} from "./base";
 import type { SelectDropdownOption } from "./option";
 import type {
   SelectTriggerDefaultProps,
@@ -165,13 +170,22 @@ export interface SelectFormRegisterExtension {
 
 /**
  * Select callback params
- * @property {SelectDropdownOption} [nextOption] 현재 상호작용한 option
- * @property {SelectDropdownOption} [prevOption] 이전 기준 option
+ * @property {SelectDropdownOption<OptionData, DataOptionality>} [nextOption] 현재 상호작용한 option
+ * @property {SelectDropdownOption<OptionData, DataOptionality>} [prevOption] 이전 기준 option
  * @property {Event} [event] 원본 메뉴 선택 이벤트
+ * @example
+ * const onChange: SelectCallbackParams<{ code: string }, "required"> = (
+ *   nextOption,
+ * ) => {
+ *   // nextOption?.data 는 { code: string } | undefined
+ * };
  */
-export type SelectCallbackParams<OptionData = unknown> = (
-  nextOption?: SelectDropdownOption<OptionData>,
-  prevOption?: SelectDropdownOption<OptionData>,
+export type SelectCallbackParams<
+  OptionData = unknown,
+  DataOptionality extends SelectOptionDataOptionality = "optional",
+> = (
+  nextOption?: SelectDropdownOption<OptionData, DataOptionality>,
+  prevOption?: SelectDropdownOption<OptionData, DataOptionality>,
   event?: Event,
 ) => void;
 
@@ -213,24 +227,30 @@ export interface SelectDropdownExtension {
 
 /**
  * Select dropdown 옵션 구성 props
- * @property {SelectDropdownOption[]} [items] dropdown item 리스트(권장: items[].selected 초기값)
- * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
- * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownOption<OptionData, DataOptionality>[]} [items] dropdown item 리스트(권장: items[].selected 초기값)
+ * @property {SelectCallbackParams<OptionData, DataOptionality>} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams<OptionData, DataOptionality>} [onSelectChange] 선택값 변경 콜백
  * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
+ * @example
+ * type Config = SelectDropdownConfigProps<{ metaKey: number }, "required">;
+ * // Config.items의 option은 data를 반드시 포함해야 한다.
  */
-export interface SelectDropdownConfigProps<OptionData = unknown> {
+export interface SelectDropdownConfigProps<
+  OptionData = unknown,
+  DataOptionality extends SelectOptionDataOptionality = "optional",
+> {
   /**
    * dropdown item 리스트
    */
-  items: SelectDropdownOption<OptionData>[];
+  items: SelectDropdownOption<OptionData, DataOptionality>[];
   /**
    * option 선택 액션 콜백
    */
-  onSelectOption?: SelectCallbackParams<OptionData>;
+  onSelectOption?: SelectCallbackParams<OptionData, DataOptionality>;
   /**
    * 선택값 변경 콜백
    */
-  onSelectChange?: SelectCallbackParams<OptionData>;
+  onSelectChange?: SelectCallbackParams<OptionData, DataOptionality>;
   /**
    * dropdown 확장 옵션
    */
@@ -316,9 +336,9 @@ export type SelectProps = SelectStyleOptions &
  * @property {boolean} [readOnly] readOnly 여부
  * @property {SelectTriggerButtonType} [buttonType] button type
  * @property {FormFieldWidth} [width] width preset 옵션
- * @property {SelectDropdownOption[]} [items] dropdown item 리스트
- * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
- * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownOption<OptionData>[]} [items] dropdown item 리스트
+ * @property {SelectCallbackParams<OptionData>} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams<OptionData>} [onSelectChange] 선택값 변경 콜백
  * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
@@ -328,6 +348,10 @@ export type SelectProps = SelectStyleOptions &
  * @property {SelectCustomInputProps} [inputProps] 직접 입력 input 구성
  * @property {UseFormRegisterReturn} [register] source field register
  * @property {UseFormRegisterReturn} [customRegister] custom field register
+ * @example
+ * type DefaultProps = SelectDefaultComponentProps<{ metaKey: number }>;
+ * type RequiredChange = SelectCallbackParams<{ metaKey: number }, "required">;
+ * // optionality 제어는 콜백/옵션 타입에서 필요할 때만 명시적으로 사용한다.
  */
 export type SelectDefaultComponentProps<OptionData = unknown> =
   SelectTriggerDefaultProps &
@@ -367,9 +391,9 @@ export interface SelectMultipleAllOptionProps {
  * @property {boolean} [disabled] disabled 여부
  * @property {boolean} [readOnly] readOnly 여부
  * @property {FormFieldWidth} [width] width preset 옵션
- * @property {SelectDropdownOption[]} [items] dropdown item 리스트
- * @property {SelectCallbackParams} [onSelectOption] option 선택 액션 콜백
- * @property {SelectCallbackParams} [onSelectChange] 선택값 변경 콜백
+ * @property {SelectDropdownOption<OptionData>[]} [items] dropdown item 리스트
+ * @property {SelectCallbackParams<OptionData>} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams<OptionData>} [onSelectChange] 선택값 변경 콜백
  * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
@@ -377,6 +401,10 @@ export interface SelectMultipleAllOptionProps {
  * @property {HTMLAttributes<HTMLElement>} [triggerProps] trigger native 속성/이벤트
  * @property {boolean} [showSelectAllOption] dropdown 첫 행에 "전체" 옵션 노출 여부
  * @property {ReactNode} [selectAllLabel] "전체" 옵션 라벨 커스터마이징
+ * @example
+ * type MultipleProps = SelectMultipleComponentProps<{ metaKey: number }>;
+ * type RequiredChange = SelectCallbackParams<{ metaKey: number }, "required">;
+ * // optionality 제어는 콜백/옵션 타입에서 필요할 때만 명시적으로 사용한다.
  */
 export type SelectMultipleComponentProps<OptionData = unknown> =
   SelectTriggerMultipleProps &