@uniai-fe/uds-primitives 0.3.60 → 0.4.0

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

@@ -102,7 +102,7 @@ export interface InputIcon {
  * @property {ReactNode} [clear] input reset버튼 커스텀 컨텐츠
  * @property {ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
  * @property {ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
- * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] width preset 옵션
  * @property {InputState} [data-simulated-state] Storybook 시각 상태 강제용
  */
 export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {

package/src/components/navigation/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * Navigation; mobile bottom navigation 카테고리 배럴
+ * @desc
+ * - `BottomNavigation`: 모바일 하단 네비게이션 루트다.
+ * - `NavigationItem`, `NavigationItemKey`: item/public type 계약이다.
+ * - `composeNavigationClassName`, `isHrefNavigationItem`: navigation util이다.
+ */
 import "./index.scss";
 
 export * from "./markup";

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

@@ -1,2 +1,8 @@
+/**
+ * Navigation; mobile/web navigation markup export 배럴
+ * @desc
+ * - `BottomNavigation`: 현재 mobile 구현에서 제공되는 하단 네비게이션 루트다.
+ * - `web/*`: 플랫폼 확정 전까지 placeholder export를 유지한다.
+ */
 export * from "./mobile";
 export * from "./web";

package/src/components/pagination/index.tsx

@@ -1,5 +1,10 @@
 /**
- * pagination 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Pagination; list/carousel/count indicator 카테고리 배럴
+ * @desc
+ * - `Pagination`: 숫자 기반 페이지 이동 컨트롤이다.
+ * - `PaginationCarousel`: dot 기반 step indicator다.
+ * - `PaginationCount`: 현재/전체 step 카운트 표시다.
+ * - `normalizePaginationState`, `createPaginationPages`: pagination util이다.
  */
 import "./index.scss";
 

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

@@ -1,3 +1,10 @@
+/**
+ * Pagination; list/carousel/count markup export 배럴
+ * @desc
+ * - `Pagination`: list variant다.
+ * - `PaginationCarousel`: carousel(dot) variant다.
+ * - `PaginationCount`: count variant다.
+ */
 export { Pagination } from "./Pagination";
 export { PaginationCarousel } from "./Carousel";
 export { PaginationCount } from "./Count";

package/src/components/pop-over/index.tsx

@@ -1,3 +1,10 @@
+/**
+ * PopOver; namespace 배럴 export
+ * @desc
+ * - `PopOver.Root`: open 상태 계약
+ * - `PopOver.Trigger`: asChild trigger 연결
+ * - `PopOver.Content`: overlay shell + 위치/폭 계약
+ */
 import "./index.scss";
 
 export * from "./markup";

package/src/components/pop-over/markup/index.tsx

@@ -5,10 +5,11 @@ import PopOverTrigger from "./Trigger";
 export { PopOverRoot, PopOverTrigger, PopOverContent };
 
 /**
- * PopOver namespace.
- * - Root
- * - Trigger
- * - Content
+ * PopOver; 컴포넌트 모듈
+ * @namespace PopOver
+ * - `PopOver.Root`
+ * - `PopOver.Trigger`
+ * - `PopOver.Content`
  */
 export const PopOver = {
   Root: PopOverRoot,

package/src/components/radio/index.tsx

@@ -1,5 +1,9 @@
 /**
- * radio 카테고리 배럴; markup과 타입 exports를 노출한다.
+ * Radio; namespace 배럴 export
+ * @desc
+ * - `Radio`, `RadioField`: base radio primitives
+ * - `RadioCard`, `RadioCardGroup`: card variation
+ * - hooks/types/utils는 별도 배럴로 함께 export한다
  */
 import "./index.scss";
 

package/src/components/scrollbar/hooks/index.ts

@@ -1,4 +1,4 @@
 /**
- * TODO(scrollbar): 접근성/상태 계산 hook을 정의한다.
+ * Scrollbar Hooks; 현재 공개된 훅이 없는 placeholder 엔트리
  */
 export {};

package/src/components/scrollbar/index.tsx

@@ -1,4 +1,4 @@
 /**
- * scrollbar 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Scrollbar; 현재 public export가 없는 placeholder 카테고리 배럴
  */
 export * from "./markup";

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

@@ -1,4 +1,4 @@
 /**
- * TODO(scrollbar): SOT 및 사용자 제약에 따라 컴포넌트를 구현한다.
+ * Scrollbar Markup; 현재 공개된 컴포넌트가 없는 placeholder 엔트리
  */
 export {};

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

@@ -1,4 +1,4 @@
 /**
- * TODO(scrollbar): variant/slot 타입 정의를 작성한다.
+ * Scrollbar Types; 현재 공개된 타입이 없는 placeholder 엔트리
  */
 export {};

package/src/components/scrollbar/utils/index.ts

@@ -1,4 +1,4 @@
 /**
- * TODO(scrollbar): 토큰 매핑과 클래스명 유틸을 구현한다.
+ * Scrollbar Utils; 현재 공개된 유틸이 없는 placeholder 엔트리
  */
 export {};

package/src/components/segmented-control/index.tsx

@@ -1,5 +1,9 @@
 /**
- * segmented-control 카테고리 배럴
+ * SegmentedControl; single-select segmented control 카테고리 배럴
+ * @desc
+ * - `SegmentedControl`: 옵션 배열 기반 단일 선택 루트다.
+ * - `SegmentedControlLabel`: 옵션 텍스트 슬롯이다.
+ * - `SegmentedControlProps`, `SegmentedControlOption`: public contract 타입이다.
  */
 import "./index.scss";
 

package/src/components/segmented-control/markup/index.ts

@@ -1,2 +1,8 @@
+/**
+ * SegmentedControl; single-select segmented control markup export 배럴
+ * @desc
+ * - `SegmentedControl`: 옵션 배열 기반 단일 선택 루트다.
+ * - `SegmentedControlLabel`: 옵션 텍스트 슬롯이다.
+ */
 export * from "./Container";
 export { default as SegmentedControlLabel } from "./Label";

package/src/components/select/index.tsx

@@ -1,5 +1,10 @@
 /**
- * select 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Select; namespace 배럴 export
+ * @desc
+ * - `Select.Default`: single select
+ * - `Select.Multiple`: multi select
+ * - `Select.Container`, `Select.Trigger.Base`, `Select.Selected.*`: headless 조합 레이어
+ * - hooks/types/utils는 별도 배럴로 함께 export한다
  */
 import "./index.scss";
 

package/src/components/select/markup/Default.tsx

@@ -10,20 +10,13 @@ import Container from "./foundation/Container";
 import { useSelectDropdownOpenState } from "../hooks";
 import type { SelectDropdownOption } from "../types/option";
 import type { SelectDefaultComponentProps } from "../types/props";
+import { toSelectInputText } from "../utils";
 import {
   isSameSelectedValue,
   normalizeSingleSelectedValue,
   toSelectedValueKey,
 } from "../../../utils/selected-values";
 
-const toInputText = (value?: ReactNode): string => {
-  if (typeof value === "string" || typeof value === "number") {
-    return String(value);
-  }
-
-  return "";
-};
-
 const SELECT_CUSTOM_OPTION_BASE_ID = "__select_custom_input__";
 const SELECT_CUSTOM_OPTION_VALUE = "CUSTOM";
 
@@ -44,8 +37,8 @@ const SELECT_CUSTOM_OPTION_VALUE = "CUSTOM";
  * @param {boolean} [props.icon] chevron 아이콘 비활성화 여부
  * @param {"button" | "submit" | "reset"} [props.buttonType] trigger button type
  * @param {SelectDropdownOption[]} props.items dropdown 아이템 목록
- * @param {SelectCallbackParams} [props.onSelectOption] option interaction 콜백
- * @param {SelectCallbackParams} [props.onSelectChange] selection change 콜백
+ * @param {SelectCallbackParams} [props.onSelectOption] option interaction 콜백(legacy)
+ * @param {SelectCallbackParams} [props.onSelectChange] 권장 선택값 변경 콜백
  * @param {SelectDropdownExtension} [props.dropdownOptions] dropdown 확장 옵션
  * @param {boolean} [props.open] controlled open 값
  * @param {boolean} [props.defaultOpen] uncontrolled 초기 open 값
@@ -163,7 +156,9 @@ export function SelectDefault<OptionData = unknown>({
   );
 
   // 9) customOptions가 있는 경우 inputProps.value가 있고 option 매칭이 없으면 custom mode로 간주한다.
-  const forcedCustomLabelValue = toInputText(inputProps?.value as ReactNode);
+  const forcedCustomLabelValue = toSelectInputText(
+    inputProps?.value as ReactNode,
+  );
   const shouldForceCustomFromInput = Boolean(
     customOptions && !selectedOption && forcedCustomLabelValue,
   );
@@ -262,7 +257,7 @@ export function SelectDefault<OptionData = unknown>({
       typeof inputProps?.value === "number"
       ? String(inputProps.value)
       : customLabelValue
-    : toInputText(resolvedDisplayLabel);
+    : toSelectInputText(resolvedDisplayLabel);
 
   // 17) 렌더: Container → Dropdown.Root → Trigger → Menu.List 구조를 유지한다.
   return (
@@ -297,7 +292,8 @@ export function SelectDefault<OptionData = unknown>({
               label={resolvedDisplayLabel}
               placeholder={
                 isCustomInputActive
-                  ? (customOptions?.placeholder ?? toInputText(placeholder))
+                  ? (customOptions?.placeholder ??
+                    toSelectInputText(placeholder))
                   : placeholder
               }
               isPlaceholder={
@@ -329,6 +325,7 @@ export function SelectDefault<OptionData = unknown>({
           {...dropdownOptions?.containerProps}
           size={dropdownOptions?.size ?? resolvedSize}
           width={dropdownOptions?.width ?? "match"}
+          minWidth={dropdownOptions?.minWidth}
         >
           <Dropdown.Menu.List {...dropdownOptions?.menuListProps}>
             {mergedOptions.length > 0 ? (

package/src/components/select/markup/foundation/Selected.tsx

@@ -4,14 +4,7 @@ import clsx from "clsx";
 import { useEffect, useRef } from "react";
 import type { ReactNode } from "react";
 import type { SelectSelectedProps } from "../../types/trigger";
-
-const toInputText = (value?: ReactNode): string => {
-  if (typeof value === "string" || typeof value === "number") {
-    return String(value);
-  }
-
-  return "";
-};
+import { toSelectInputText } from "../../utils";
 
 /**
  * Select trigger value renderer; trigger 내부 label/value input 렌더링 컴포넌트
@@ -56,31 +49,38 @@ const SelectTriggerSelected = ({
   const labelInputRef = useRef<HTMLInputElement>(null);
 
   // 2) placeholder/label은 text input에 들어갈 수 있는 문자열로 정규화한다.
-  const resolvedPlaceholder = toInputText(placeholder);
+  const resolvedPlaceholder = toSelectInputText(placeholder);
   // 변경 설명: readOnly + customOptions 조합에서 valueText가 비어도 inputProps.value를 표시 문자열로 사용한다.
-  const resolvedInputValueText = toInputText(inputProps?.value as ReactNode);
+  const resolvedInputValueText = toSelectInputText(
+    inputProps?.value as ReactNode,
+  );
   const resolvedLabelText =
-    valueText || resolvedInputValueText || toInputText(label);
+    valueText || resolvedInputValueText || toSelectInputText(label);
   // 변경 설명: 색상 계약은 hidden value 또는 label value 중 지정된 source를 기준으로 계산한다.
   const resolvedHiddenValueText =
     typeof valueFieldValue === "string" || typeof valueFieldValue === "number"
       ? String(valueFieldValue)
       : "";
+  const hasReadonlyLabelNode =
+    readOnly &&
+    !isPlaceholder &&
+    label !== undefined &&
+    label !== null &&
+    !resolvedLabelText;
   const hasDisplayValue =
     valueStateSource === "hidden"
       ? resolvedHiddenValueText.length > 0
-      : resolvedLabelText.length > 0;
+      : resolvedLabelText.length > 0 || hasReadonlyLabelNode;
   const isLabelTextLike =
     typeof label === "string" || typeof label === "number";
   const shouldUsePlaceholderStyle = !hasDisplayValue;
-  // 변경 설명: readOnly에서 non-text label을 직접 렌더링하되, placeholder 상태일 때는 input placeholder 경로를 유지한다.
-  // custom mode처럼 valueText가 있는 경우에는 input 렌더 경로를 유지해 값 표시를 보장한다.
-  const shouldRenderReadonlyLabelNode =
-    readOnly &&
-    !isLabelTextLike &&
-    !isPlaceholder &&
-    !shouldUsePlaceholderStyle &&
-    !resolvedLabelText;
+  // 변경 설명: readOnly 경로는 input 대신 표시 노드를 직접 렌더링해 fit-content가 실제 콘텐츠 폭을 기준으로 계산되게 한다.
+  const shouldRenderReadonlyView = readOnly;
+  const readonlyContent = shouldUsePlaceholderStyle
+    ? resolvedPlaceholder
+    : !isLabelTextLike && !resolvedLabelText
+      ? label
+      : resolvedLabelText;
 
   // 3) custom mode 활성 시에만 label input focus를 부여한다.
   useEffect(() => {
@@ -96,15 +96,20 @@ const SelectTriggerSelected = ({
       className="select-value"
       data-has-value={hasDisplayValue ? "true" : "false"}
     >
-      {shouldRenderReadonlyLabelNode ? (
-        // 변경 설명: readonly + ReactNode label일 때는 문자열 변환 없이 label 노드를 직접 렌더링한다.
+      {shouldRenderReadonlyView ? (
+        // 변경 설명: readOnly 표시 경로는 text/ReactNode를 그대로 유지해 trigger width가 실제 표시 콘텐츠에 맞춰지도록 한다.
         <div
-          className={clsx("select-input-label", inputProps?.className, {
-            "select-input-label-placeholder": shouldUsePlaceholderStyle,
-          })}
+          className={clsx(
+            "select-input-label",
+            "select-input-label-readonly",
+            inputProps?.className,
+            {
+              "select-input-label-placeholder": shouldUsePlaceholderStyle,
+            },
+          )}
           data-has-value={hasDisplayValue ? "true" : "false"}
         >
-          {label}
+          {readonlyContent}
         </div>
       ) : (
         <input

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

@@ -4,7 +4,7 @@ import { SelectTriggerBase, SelectTriggerSelected } from "./foundation";
 import SelectContainer from "./foundation/Container";
 
 /**
- * Selec; 컴포넌트 모듈
+ * Select; 컴포넌트 모듈
  * @namespace Select
  * - <Select.Default />: Select 기본
  * - <Select.Multiple />: Select multi select

package/src/components/select/markup/multiple/Multiple.tsx

@@ -11,6 +11,7 @@ import type { SelectDropdownOption } from "../../types/option";
 import { SelectMultipleSelectedChip } from "./SelectedChip";
 import { SelectTriggerBase, SelectTriggerSelected } from "../foundation";
 import { useSelectDropdownOpenState } from "../../hooks";
+import { renderCommaSeparatedSelectLabels } from "../../utils";
 import {
   isSameSelectedValue,
   isSameSelectedValueList,
@@ -26,8 +27,8 @@ const SELECT_MULTIPLE_ALL_OPTION_BASE_ID = "__select_multiple_all__";
  * @param {string} [props.className] container className
  * @param {SelectMultipleTag[]} [props.tags] 선택된 tag 리스트
  * @param {SelectDropdownOption[]} [props.items] dropdown item 목록
- * @param {SelectCallbackParams} [props.onSelectOption] option 선택 액션 콜백
- * @param {SelectCallbackParams} [props.onSelectChange] 선택값 변경 콜백
+ * @param {SelectCallbackParams} [props.onSelectOption] option 선택 액션 콜백(legacy)
+ * @param {SelectCallbackParams} [props.onSelectChange] 권장 선택값 변경 콜백
  * @param {React.ReactNode} [props.displayLabel] fallback 라벨
  * @param {React.ReactNode} [props.placeholder] placeholder 텍스트
  * @param {"primary" | "secondary" | "table"} [props.priority="primary"] priority scale
@@ -45,6 +46,7 @@ const SELECT_MULTIPLE_ALL_OPTION_BASE_ID = "__select_multiple_all__";
  * @param {(open: boolean) => void} [props.onOpen] open 상태 변경 콜백
  * @param {boolean} [props.showSelectAllOption] dropdown 첫 번째에 "전체" 옵션 노출 여부
  * @param {React.ReactNode} [props.selectAllLabel="전체"] 전체 옵션 라벨
+ * @param {"chip" | "text"} [props.displayMode="chip"] 선택값 표시 방식
  */
 export function SelectMultipleTrigger<OptionData = unknown>({
   className,
@@ -67,6 +69,7 @@ export function SelectMultipleTrigger<OptionData = unknown>({
   onOpen,
   showSelectAllOption,
   selectAllLabel = "전체",
+  displayMode = "chip",
   triggerProps,
 }: SelectMultipleComponentProps<OptionData>) {
   /**
@@ -208,11 +211,22 @@ export function SelectMultipleTrigger<OptionData = unknown>({
    * - tags가 비어 있을 때 fallback label 용도로 사용한다.
    * - 외부 displayLabel 우선, 없으면 첫 선택 option label을 사용한다.
    */
+  const selectedOptions = useMemo(
+    () =>
+      resolvedSelectedValues
+        .map(selectedValue => optionMap.get(toSelectedValueKey(selectedValue)))
+        .filter((option): option is NonNullable<typeof option> =>
+          Boolean(option),
+        ),
+    [optionMap, resolvedSelectedValues],
+  );
   const resolvedDisplayLabel =
     displayLabel ??
-    (resolvedSelectedValues.length > 0
-      ? optionMap.get(toSelectedValueKey(resolvedSelectedValues[0]))?.label
-      : undefined);
+    (displayMode === "text"
+      ? renderCommaSeparatedSelectLabels(selectedOptions)
+      : selectedOptions.length > 0
+        ? selectedOptions[0]?.label
+        : undefined);
 
   /**
    * 9) tag 파생 계산
@@ -224,24 +238,23 @@ export function SelectMultipleTrigger<OptionData = unknown>({
       return tags;
     }
 
-    if (optionMap.size === 0 || resolvedSelectedValues.length === 0) {
+    if (selectedOptions.length === 0) {
       return [];
     }
 
-    return resolvedSelectedValues
-      .map(selectedValue => optionMap.get(toSelectedValueKey(selectedValue)))
-      .filter((option): option is NonNullable<typeof option> => Boolean(option))
-      .map(option => ({
-        label: option.label,
-        removable: false,
-      }));
-  }, [tags, resolvedSelectedValues, optionMap]);
+    return selectedOptions.map(option => ({
+      label: option.label,
+      removable: false,
+    }));
+  }, [tags, selectedOptions]);
 
   /**
    * 10) placeholder/label 표시 상태 계산
    * - label 값이 비어 있으면 placeholder 표시로 간주한다.
    */
   const hasTags = derivedTags.length > 0;
+  const shouldRenderTextDisplay =
+    displayMode === "text" && selectedOptions.length > 0;
 
   /**
    * 11) dropdown open 상태 관리
@@ -361,6 +374,9 @@ export function SelectMultipleTrigger<OptionData = unknown>({
       className={clsx("select-trigger-multiple", className)}
       block={resolvedBlock}
       width={width}
+      priority={priority}
+      size={resolvedSize}
+      state={disabled ? "disabled" : state}
     >
       <Dropdown.Root
         open={dropdownOpen}
@@ -382,7 +398,7 @@ export function SelectMultipleTrigger<OptionData = unknown>({
             as="div"
             {...triggerProps}
           >
-            {hasTags ? (
+            {hasTags && !shouldRenderTextDisplay ? (
               <div className="select-tags">
                 {visibleTags.map(
                   ({ label, suffix, removable, onRemove }, index) => (
@@ -422,6 +438,7 @@ export function SelectMultipleTrigger<OptionData = unknown>({
           {...dropdown?.containerProps}
           size={dropdown?.size ?? resolvedSize}
           width={dropdown?.width ?? "match"}
+          minWidth={dropdown?.minWidth}
         >
           <Dropdown.Menu.List {...dropdown?.menuListProps}>
             {hasOptions ? (

package/src/components/select/styles/select.scss

@@ -26,7 +26,10 @@
   --select-flex: 1 1 0%;
 }
 
-.select[data-width="full"],
+.select:where([data-width="full"]) {
+  --select-width: 100%;
+  --select-flex: 0 0 100%;
+}
 .select-block {
   --select-width: 100%;
   --select-flex: 0 0 100%;
@@ -177,13 +180,14 @@
     border-color: var(--select-primary-color-border-disabled);
     background-color: var(--select-primary-color-surface-disabled);
     cursor: default;
-    --select-icon-fill: var(--select-icon-color-disabled);
+    --select-icon-fill: var(--select-icon-color-readonly);
   }
 
   &:where([data-priority="secondary"]):where([data-readonly="true"]) {
-    border-color: transparent;
-    background-color: var(--select-color-surface-secondary-disabled);
+    border-color: var(--select-secondary-color-border-readonly);
+    background-color: var(--select-color-surface-secondary-readonly);
     cursor: default;
+    --select-icon-fill: var(--select-icon-color-readonly);
 
     &::after {
       background-color: var(--select-color-border-secondary-disabled);
@@ -195,7 +199,7 @@
     border-color: var(--select-table-border-readonly-color);
     background-color: var(--select-table-surface-readonly-color);
     cursor: not-allowed;
-    --select-icon-fill: var(--select-table-icon-color-disabled);
+    --select-icon-fill: var(--select-table-icon-color-readonly);
   }
 
   // &:not([data-priority="secondary"]):hover:not(:disabled) {
@@ -211,7 +215,7 @@
 
   &:where([data-priority="secondary"]):where([data-state="disabled"]),
   &:where([data-priority="secondary"]):disabled {
-    border-color: transparent;
+    border-color: var(--select-secondary-color-border-disabled);
     background-color: var(--select-color-surface-secondary-disabled);
 
     &::after {
@@ -297,6 +301,11 @@
   }
 }
 
+.select-input-label-readonly {
+  width: auto;
+  max-width: 100%;
+}
+
 .select-button:where(:not([data-state="disabled"]))
   .select-value[data-has-value="true"]
   .select-input-label {

package/src/components/select/styles/variables.scss

@@ -120,6 +120,8 @@
   --select-secondary-color-text-readonly: var(
     --select-primary-color-text-readonly
   );
+  --select-secondary-color-border-disabled: var(--color-label-disabled);
+  --select-secondary-color-border-readonly: transparent;
   --select-secondary-color-placeholder: var(--color-label-alternative);
   --select-secondary-color-placeholder-disabled: var(--color-label-disabled);
   --select-secondary-color-placeholder-readonly: var(
@@ -129,10 +131,12 @@
   --select-color-surface-secondary-hover: var(--color-surface-static-cool-gray);
   --select-color-surface-secondary-active: var(--color-surface-standard);
   --select-color-surface-secondary-disabled: var(--color-surface-neutral);
+  --select-color-surface-secondary-readonly: transparent;
 
   --select-icon-color-default: var(--color-cool-gray-75);
   --select-icon-color-focused: var(--color-cool-gray-20);
   --select-icon-color-disabled: var(--color-cool-gray-85);
+  --select-icon-color-readonly: transparent;
 
   /* Multi select chip */
   --select-multiple-chip-gap: var(--spacing-gap-2);

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

@@ -1,5 +1,24 @@
 import type { ReactNode } from "react";
 
+/**
+ * Select multiple display mode
+ * @typedef {"chip" | "text"} SelectMultipleDisplayMode
+ */
+export type SelectMultipleDisplayMode = "chip" | "text";
+
+/**
+ * Select multiple display props
+ * @property {SelectMultipleDisplayMode} [displayMode] 선택값 표시 방식
+ */
+export interface SelectMultipleDisplayProps {
+  /**
+   * 선택값 표시 방식
+   * - chip: 기존 chip list 표시
+   * - text: comma-separated text 표시
+   */
+  displayMode?: SelectMultipleDisplayMode;
+}
+
 /**
  * Select multiple chip props
  * @property {ReactNode} label 표시할 라벨

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

@@ -9,6 +9,7 @@ import type { UseFormRegisterReturn } from "react-hook-form";
 import type {
   DropdownContainerProps,
   DropdownMenuListProps,
+  DropdownPanelMinWidth,
   DropdownPanelWidth,
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
@@ -19,7 +20,7 @@ import type {
   SelectState,
   SelectTriggerButtonType,
 } from "./base";
-import type { SelectMultipleTag } from "./multiple";
+import type { SelectMultipleDisplayProps, SelectMultipleTag } from "./multiple";
 import type { SelectDropdownOption } from "./option";
 import type {
   SelectTriggerBaseFoundationProps,
@@ -192,8 +193,9 @@ export type SelectCallbackParams<
  * Select dropdown 확장 props
  * @property {SelectSize} [size] dropdown surface size 스케일
  * @property {DropdownPanelWidth} [width] dropdown panel width 옵션
+ * @property {DropdownPanelMinWidth} [minWidth] dropdown panel 최소 너비 옵션
  * @property {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [rootProps] Dropdown.Root 전달 props
- * @property {Omit<DropdownContainerProps, "children" | "size" | "width">} [containerProps] Dropdown.Container 전달 props
+ * @property {Omit<DropdownContainerProps, "children" | "size" | "width" | "minWidth">} [containerProps] Dropdown.Container 전달 props
  * @property {DropdownMenuListProps} [menuListProps] Dropdown.Menu.List 전달 props
  * @property {ReactNode} [alt] option이 비어 있을 때 렌더링할 alternate 콘텐츠
  */
@@ -206,14 +208,21 @@ export interface SelectDropdownExtension {
    * dropdown panel width 옵션
    */
   width?: DropdownPanelWidth;
+  /**
+   * dropdown panel 최소 너비 옵션
+   */
+  minWidth?: DropdownPanelMinWidth;
   /**
    * Dropdown.Root 전달 props(제어 props 제외)
    */
   rootProps?: Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">;
   /**
-   * Dropdown.Container 전달 props(children/size/width 제외)
+   * Dropdown.Container 전달 props(children/size/width/minWidth 제외)
    */
-  containerProps?: Omit<DropdownContainerProps, "children" | "size" | "width">;
+  containerProps?: Omit<
+    DropdownContainerProps,
+    "children" | "size" | "width" | "minWidth"
+  >;
   /**
    * Dropdown.Menu.List 전달 props
    */
@@ -227,7 +236,7 @@ export interface SelectDropdownExtension {
 /**
  * Select dropdown 옵션 구성 props
  * @property {SelectDropdownOption<OptionData, DataOptionality>[]} [items] dropdown item 리스트(권장: items[].selected 초기값)
- * @property {SelectCallbackParams<OptionData, DataOptionality>} [onSelectOption] option 선택 액션 콜백
+ * @property {SelectCallbackParams<OptionData, DataOptionality>} [onSelectOption] option 선택 액션 콜백(legacy)
  * @property {SelectCallbackParams<OptionData, DataOptionality>} [onSelectChange] 선택값 변경 콜백
  * @property {SelectDropdownExtension} [dropdown] dropdown 확장 옵션
  * @example
@@ -244,6 +253,8 @@ export interface SelectDropdownConfigProps<
   items?: SelectDropdownOption<OptionData, DataOptionality>[];
   /**
    * option 선택 액션 콜백
+   * @deprecated
+   * legacy 호환용이며, 신규 계약은 `onSelectChange`를 권장한다.
    */
   onSelectOption?: SelectCallbackParams<OptionData, DataOptionality>;
   /**
@@ -447,6 +458,7 @@ export interface SelectMultipleAllOptionProps {
  * @property {(open: boolean) => void} [onOpen] open state change 콜백
  * @property {boolean} [showSelectAllOption] dropdown 첫 행에 "전체" 옵션 노출 여부
  * @property {ReactNode} [selectAllLabel] "전체" 옵션 라벨 커스터마이징
+ * @property {"chip" | "text"} [displayMode] 선택값 표시 방식
  * @example
  * type MultipleProps = SelectMultipleComponentProps<{ metaKey: number }>;
  * type RequiredChange = SelectCallbackParams<{ metaKey: number }, "required">;
@@ -458,4 +470,5 @@ export type SelectMultipleComponentProps<OptionData = unknown> =
     SelectDropdownConfigProps<OptionData> &
     SelectDropdownBehaviorProps &
     SelectWidthOption &
-    SelectMultipleAllOptionProps;
+    SelectMultipleAllOptionProps &
+    SelectMultipleDisplayProps;