@uniai-fe/uds-primitives 0.3.7 → 0.3.8

package/package.json

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

package/src/components/dropdown/markup/Template.tsx

@@ -1,5 +1,7 @@
 "use client";
 
+import { useEffect, useMemo, useState } from "react";
+
 import type { DropdownTemplateProps } from "../types/props";
 
 import DropdownRoot from "./foundation/Root";
@@ -8,6 +10,21 @@ import DropdownMenuItem from "./foundation/MenuItem";
 import DropdownMenuList from "./foundation/MenuList";
 import DropdownTrigger from "./foundation/Trigger";
 
+const isSameIdList = (previousIds: string[], nextIds: string[]) =>
+  previousIds.length === nextIds.length &&
+  previousIds.every((selectedId, index) => selectedId === nextIds[index]);
+
+const normalizeSelectedIdsByMode = (
+  selectedIds: string[],
+  multiple: boolean,
+) => {
+  if (multiple) {
+    return selectedIds;
+  }
+
+  return selectedIds.length > 0 ? [selectedIds[0]] : [];
+};
+
 /**
  * Dropdown reference template; trigger/panel/menu 조합을 제공한다.
  * @component
@@ -15,6 +32,7 @@ import DropdownTrigger from "./foundation/Trigger";
  * @param {ReactNode} props.trigger trigger 요소
  * @param {DropdownTemplateItem[]} props.items 렌더링할 menu item 리스트
  * @param {string[]} [props.selectedIds] 선택된 item id 배열
+ * @param {(payload: DropdownTemplateChangePayload) => void} [props.onChange] 선택 결과 변경 콜백
  * @param {(item: DropdownTemplateItem) => void} [props.onSelect] item 선택 콜백
  * @param {"small" | "medium" | "large"} [props.size="medium"] menu size scale
  * @param {"match" | "fit-content" | "max-content" | string | number} [props.width="match"] panel width 옵션
@@ -26,7 +44,8 @@ import DropdownTrigger from "./foundation/Trigger";
 const DropdownTemplate = ({
   trigger,
   items,
-  selectedIds = [],
+  selectedIds,
+  onChange,
   onSelect,
   size = "medium",
   width = "match",
@@ -35,8 +54,173 @@ const DropdownTemplate = ({
   menuListProps,
   alt,
 }: DropdownTemplateProps) => {
+  /**
+   * 1) 선택 상태 모드 결정
+   * - selectedIds prop이 들어오면 외부가 상태를 소유하는 controlled 모드다.
+   * - selectedIds prop이 없으면 Template 내부 state가 상태를 소유하는 uncontrolled 모드다.
+   * - 이 분기 기준은 렌더마다 동일해야 하므로 가장 먼저 계산한다.
+   */
+  const isSelectionControlled = selectedIds !== undefined;
+
+  /**
+   * 2) 선택 정책(single/multiple) 결정
+   * - item 중 하나라도 multiple=true이면 multiple 정책으로 해석한다.
+   * - multiple 정책에서는 item id 배열 전체를 유지한다.
+   * - single 정책에서는 언제나 최대 1개 id만 유지한다.
+   */
+  const isMultiple = items.some(item => item.multiple);
+
+  /**
+   * 3) uncontrolled 초기 선택값 계산
+   * - source of truth: items[].selected
+   * - multiple: selected=true인 모든 id를 초기값으로 사용한다.
+   * - single: selected=true가 여러 개여도 첫 번째 id 하나만 사용한다.
+   * - useMemo로 계산해 동일 inputs에서 불필요한 재계산을 줄인다.
+   */
+  const selectedIdsFromItems = useMemo(() => {
+    const initialSelectedIds = items
+      .filter(item => item.selected)
+      .map(item => item.id);
+
+    return normalizeSelectedIdsByMode(initialSelectedIds, isMultiple);
+  }, [isMultiple, items]);
+
+  /**
+   * 4) uncontrolled 내부 state 선언
+   * - controlled 모드에서는 이 state가 실제 화면 결정에 사용되지 않는다.
+   * - uncontrolled 모드에서는 이 state가 선택 결과의 단일 source가 된다.
+   * - 초기값은 selectedIdsFromItems를 그대로 사용한다.
+   */
+  const [uncontrolledSelectedIds, setUncontrolledSelectedIds] = useState<
+    string[]
+  >(() => selectedIdsFromItems);
+
+  /**
+   * 5) options(items) 변경 동기화
+   * - controlled 모드에서는 외부 selectedIds를 신뢰해야 하므로 내부 state를 건드리지 않는다.
+   * - uncontrolled 모드에서는 내부 state를 items 변경에 맞춰 정합성 보정한다.
+   *   1) 기존 선택 id 중 현재 items에 존재하는 id만 필터링한다.
+   *   2) 유효 id가 남아 있으면 그대로 유지한다(single은 1개만 유지).
+   *   3) 유효 id가 없으면 selectedIdsFromItems(초기 선택 규칙)로 재초기화한다.
+   * - 이 effect는 외부 데이터 재조회/필터 변경 시 stale id를 자동 정리하는 역할을 한다.
+   */
+  useEffect(() => {
+    if (isSelectionControlled) {
+      return;
+    }
+
+    setUncontrolledSelectedIds(previousSelectedIds => {
+      const itemIdSet = new Set(items.map(item => item.id));
+      const filteredIds = previousSelectedIds.filter(selectedId =>
+        itemIdSet.has(selectedId),
+      );
+      const nextCandidateIds =
+        filteredIds.length > 0 ? filteredIds : selectedIdsFromItems;
+      const nextSelectedIds = normalizeSelectedIdsByMode(
+        nextCandidateIds,
+        isMultiple,
+      );
+
+      // 내용이 동일하면 기존 참조를 재사용해 불필요한 상태 갱신 루프를 차단한다.
+      if (isSameIdList(previousSelectedIds, nextSelectedIds)) {
+        return previousSelectedIds;
+      }
+
+      return nextSelectedIds;
+    });
+  }, [isMultiple, isSelectionControlled, items, selectedIdsFromItems]);
+
+  /**
+   * 6) 최종 선택 id 계산
+   * - controlled: selectedIds prop을 그대로 사용한다(single은 첫 id만 허용).
+   * - uncontrolled: 내부 state(uncontrolledSelectedIds)를 그대로 사용한다.
+   * - 렌더/이벤트/selected 스타일 계산은 이 값만 참조한다.
+   */
+  const resolvedSelectedIds = normalizeSelectedIdsByMode(
+    isSelectionControlled ? (selectedIds ?? []) : uncontrolledSelectedIds,
+    isMultiple,
+  );
+
+  /**
+   * 7) empty panel 분기
+   * - item이 비어 있으면 alt 또는 기본 문구를 disabled item으로 렌더링한다.
+   * - 별도 li를 만들지 않고 MenuItem을 재사용해 구조를 통일한다.
+   */
   const hasItems = items.length > 0;
 
+  /**
+   * 8) item 선택 처리
+   * - 클릭된 item(id) 기준으로 다음 선택 배열을 계산한다.
+   * - multiple: 토글(add/remove)
+   * - single: 클릭한 id 하나로 교체
+   * - uncontrolled 모드면 내부 state를 즉시 반영한다.
+   * - onChange(payload)로 "현재 결과 전체"를 전달한다.
+   * - onSelect(item)은 하위호환을 위해 마지막에 유지 호출한다.
+   */
+  const handleItemSelect = (itemId: string) => {
+    /**
+     * 8-1) 클릭된 item 조회
+     * - items 목록에 없는 id면 안전하게 종료한다.
+     * - 외부 데이터 race 조건에서 방어적으로 동작하기 위한 가드다.
+     */
+    const currentItem = items.find(item => item.id === itemId);
+
+    if (!currentItem) {
+      return;
+    }
+
+    /**
+     * 8-2) 다음 selectedIds 계산
+     * - wasSelected: 토글 기준 값
+     * - nextSelectedIds: 모드 정책을 적용한 다음 상태
+     * - nextSelectedItems: payload 전달용 상세 데이터
+     */
+    const wasSelected = resolvedSelectedIds.includes(itemId);
+    const nextSelectedIds = isMultiple
+      ? wasSelected
+        ? resolvedSelectedIds.filter(selectedId => selectedId !== itemId)
+        : [...resolvedSelectedIds, itemId]
+      : [itemId];
+    const nextSelectedItems = items.filter(item =>
+      nextSelectedIds.includes(item.id),
+    );
+
+    /**
+     * 8-3) 내부 state 업데이트(uncontrolled 전용)
+     * - controlled 모드에서는 외부 selectedIds prop이 곧 source of truth이므로
+     *   내부 state를 갱신하지 않는다.
+     */
+    if (!isSelectionControlled) {
+      setUncontrolledSelectedIds(nextSelectedIds);
+    }
+
+    /**
+     * 8-4) 신규 계약 이벤트(onChange)
+     * - 서비스/상위 컴포넌트가 선택 결과 전체를 즉시 사용할 수 있게
+     *   현재 item + 선택 결과 배열을 함께 제공한다.
+     */
+    onChange?.({
+      currentItem,
+      isSelected: isMultiple ? !wasSelected : true,
+      selectedIds: nextSelectedIds,
+      selectedItems: nextSelectedItems,
+      multiple: isMultiple,
+    });
+
+    /**
+     * 8-5) legacy 계약 이벤트(onSelect)
+     * - 하위호환 경로를 유지하기 위해 onChange 이후 동일 선택을 전달한다.
+     * - 추후 마이그레이션 완료 시 제거 대상이다.
+     */
+    onSelect?.(currentItem);
+  };
+
+  /**
+   * 9) 렌더 구성
+   * - Root → Trigger → Container → MenuList depth를 유지한다.
+   * - 각 item은 resolvedSelectedIds 기준으로 selected 스타일을 결정한다.
+   * - disabled item은 select 이벤트를 차단하고 상태만 노출한다.
+   */
   return (
     <DropdownRoot {...rootProps}>
       <DropdownTrigger asChild>{trigger}</DropdownTrigger>
@@ -53,13 +237,13 @@ const DropdownTemplate = ({
                   left={item.left}
                   right={item.right}
                   multiple={item.multiple}
-                  isSelected={selectedIds?.includes(item.id)}
+                  isSelected={resolvedSelectedIds.includes(item.id)}
                   onSelect={event => {
                     if (item.disabled) {
                       event.preventDefault();
                       return;
                     }
-                    onSelect?.(item);
+                    handleItemSelect(item.id);
                   }}
                 />
               ))}

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

@@ -3,7 +3,7 @@ import type {
   DropdownMenuContentProps,
   DropdownMenuItemProps as RadixDropdownMenuItemProps,
 } from "@radix-ui/react-dropdown-menu";
-import type { HTMLAttributes, MutableRefObject, ReactNode } from "react";
+import type { HTMLAttributes, ReactNode, RefObject } from "react";
 
 import type { CheckboxProps } from "../../checkbox/types";
 import type { DropdownPanelWidth, DropdownSize } from "./base";
@@ -77,13 +77,13 @@ export interface DropdownMenuListProps extends HTMLAttributes<HTMLUListElement>
 
 /**
  * Dropdown context value; trigger ref 공유용
- * @property {React.MutableRefObject<HTMLElement | null>} triggerRef trigger DOM ref
+ * @property {React.RefObject<HTMLElement | null>} triggerRef trigger DOM ref
  */
 export interface DropdownContextValue {
   /**
    * trigger DOM ref
    */
-  triggerRef: MutableRefObject<HTMLElement | null>;
+  triggerRef: RefObject<HTMLElement | null>;
 }
 
 /**
@@ -92,6 +92,7 @@ export interface DropdownContextValue {
  * @property {ReactNode} label 옵션 라벨
  * @property {ReactNode} [description] 보조 텍스트
  * @property {boolean} [disabled] 비활성 여부
+ * @property {boolean} [selected] uncontrolled 초기 선택 여부
  * @property {ReactNode} [left] 좌측 콘텐츠
  * @property {ReactNode} [right] 우측 콘텐츠
  * @property {boolean} [multiple] multi select 스타일 여부
@@ -113,6 +114,10 @@ export interface DropdownTemplateItem {
    * 비활성 여부
    */
   disabled?: boolean;
+  /**
+   * uncontrolled 초기 선택 여부
+   */
+  selected?: boolean;
   /**
    * 좌측 콘텐츠
    */
@@ -127,11 +132,43 @@ export interface DropdownTemplateItem {
   multiple?: boolean;
 }
 
+/**
+ * Dropdown template change payload
+ * @property {DropdownTemplateItem} currentItem 현재 상호작용한 item
+ * @property {boolean} isSelected currentItem 선택 여부
+ * @property {string[]} selectedIds 선택된 item id 목록
+ * @property {DropdownTemplateItem[]} selectedItems 선택된 item 목록
+ * @property {boolean} multiple 다중 선택 모드 여부
+ */
+export interface DropdownTemplateChangePayload {
+  /**
+   * 현재 상호작용한 item
+   */
+  currentItem: DropdownTemplateItem;
+  /**
+   * currentItem 선택 여부
+   */
+  isSelected: boolean;
+  /**
+   * 선택된 item id 목록
+   */
+  selectedIds: string[];
+  /**
+   * 선택된 item 목록
+   */
+  selectedItems: DropdownTemplateItem[];
+  /**
+   * 다중 선택 모드 여부
+   */
+  multiple: boolean;
+}
+
 /**
  * Dropdown template props
  * @property {ReactNode} trigger trigger 요소
  * @property {DropdownTemplateItem[]} items 렌더링할 menu item 리스트
  * @property {string[]} [selectedIds] 선택된 item id 배열
+ * @property {(payload: DropdownTemplateChangePayload) => void} [onChange] 선택 결과 변경 콜백
  * @property {(item: DropdownTemplateItem) => void} [onSelect] item 선택 콜백
  * @property {DropdownSize} [size="medium"] surface height scale
  * @property {DropdownPanelWidth} [width="match"] panel width 옵션
@@ -143,7 +180,19 @@ export interface DropdownTemplateItem {
 export interface DropdownTemplateProps {
   trigger: ReactNode;
   items: DropdownTemplateItem[];
+  /**
+   * 선택된 item id 배열
+   * @deprecated onChange + items[].selected 기반 계약을 우선 사용한다.
+   */
   selectedIds?: string[];
+  /**
+   * 선택 결과 변경 콜백
+   */
+  onChange?: (payload: DropdownTemplateChangePayload) => void;
+  /**
+   * item 선택 콜백
+   * @deprecated onChange로 대체되며 하위호환을 위해 유지된다.
+   */
   onSelect?: (item: DropdownTemplateItem) => void;
   size?: DropdownSize;
   width?: DropdownPanelWidth;

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

@@ -1,7 +1,7 @@
 "use client";
 
 import clsx from "clsx";
-import { forwardRef } from "react";
+import { forwardRef, useEffect, useMemo, useState } from "react";
 
 import type { DropdownSize } from "../../dropdown/types";
 import { Dropdown } from "../../dropdown/markup";
@@ -11,12 +11,20 @@ import { useSelectDropdownOpenState } from "../hooks";
 import type { SelectDropdownOption } from "../types/option";
 import type { SelectDefaultComponentProps } from "../types/props";
 
+const isSameIdList = (previousIds: string[], nextIds: string[]) =>
+  previousIds.length === nextIds.length &&
+  previousIds.every((selectedId, index) => selectedId === nextIds[index]);
+
+const normalizeSingleSelectedIds = (selectedIds: string[]) =>
+  selectedIds.length > 0 ? [selectedIds[0]] : [];
+
 /**
  * Select default trigger; 단일 선택 드롭다운을 렌더링한다.
  * @component
  * @param {SelectDefaultComponentProps} props default trigger props
  * @param {SelectDropdownOption[]} [props.options] dropdown option 목록
  * @param {string[]} [props.selectedOptionIds] 선택된 option id 리스트
+ * @param {(payload: SelectOptionChangePayload) => void} [props.onChange] 선택 결과 변경 콜백
  * @param {(option: SelectDropdownOption) => void} [props.onOptionSelect] option 선택 콜백
  * @param {"primary" | "secondary" | "table"} [props.priority="primary"] priority 스케일
  * @param {"small" | "medium" | "large"} [props.size="medium"] size 스케일
@@ -53,6 +61,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       buttonType,
       options = [],
       selectedOptionIds,
+      onChange,
       onOptionSelect,
       dropdownSize,
       dropdownWidth = "match",
@@ -67,30 +76,147 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
     },
     ref,
   ) => {
-    // 변경: table priority는 width 미지정 시 기본 full width를 사용한다.
+    /**
+     * 1) 레이아웃 기본값 계산
+     * - table priority는 셀 컨텍스트에서 full width가 기본 동작이므로
+     *   width 미지정 시 block=true처럼 동작하도록 보정한다.
+     * - 이 값은 trigger/container 양쪽에서 동일하게 사용한다.
+     */
     const resolvedBlock =
       block || (priority === "table" && width === undefined);
-    const resolvedSelectedIds = selectedOptionIds ?? [];
 
+    /**
+     * 2) 선택 상태 모드 결정
+     * - selectedOptionIds prop이 들어오면 controlled 모드(외부가 source of truth)
+     * - selectedOptionIds prop이 없으면 uncontrolled 모드(내부 state가 source of truth)
+     */
+    const isSelectionControlled = selectedOptionIds !== undefined;
+
+    /**
+     * 3) option 조회 최적화 맵 생성
+     * - 옵션 탐색(find/filter) 반복을 줄이기 위해 id 기반 맵을 만든다.
+     * - display label 계산, payload selectedOptions 계산, 렌더 시 선택 확인에 재사용한다.
+     */
+    const optionMap = useMemo(
+      () => new Map(options.map(option => [option.id, option])),
+      [options],
+    );
+
+    /**
+     * 4) uncontrolled 초기 선택값 계산
+     * - options[].selected를 초기 선택 입력으로 사용한다.
+     * - single-select이므로 selected=true가 여러 개여도 첫 id 하나만 채택한다.
+     */
+    const selectedIdsFromOptions = useMemo(() => {
+      const initialSelectedIds = options
+        .filter(option => option.selected)
+        .map(option => option.id);
+      return normalizeSingleSelectedIds(initialSelectedIds);
+    }, [options]);
+
+    /**
+     * 5) uncontrolled 내부 state 선언
+     * - controlled 모드에서는 실제 UI source로 쓰이지 않는다.
+     * - uncontrolled 모드에서는 최종 선택 id를 내부 state가 소유한다.
+     */
+    const [uncontrolledSelectedOptionIds, setUncontrolledSelectedOptionIds] =
+      useState<string[]>(() => selectedIdsFromOptions);
+
+    /**
+     * 6) options 변경 시 내부 state 정합성 보정(uncontrolled 전용)
+     * - controlled 모드는 외부 selectedOptionIds를 신뢰하므로 내부 state를 건드리지 않는다.
+     * - uncontrolled 모드는 옵션 리스트가 바뀌면 stale id를 정리해야 한다.
+     *   1) 기존 선택 id가 현재 options에 존재하는지 필터링
+     *   2) 남아 있으면 single 정책으로 첫 id 하나만 유지
+     *   3) 남지 않으면 selectedIdsFromOptions(초기 선택 규칙)로 재동기화
+     */
+    useEffect(() => {
+      if (isSelectionControlled) {
+        return;
+      }
+
+      setUncontrolledSelectedOptionIds(previousSelectedIds => {
+        const optionIdSet = new Set(options.map(option => option.id));
+        const filteredIds = previousSelectedIds.filter(selectedId =>
+          optionIdSet.has(selectedId),
+        );
+        const nextCandidateIds =
+          filteredIds.length > 0 ? filteredIds : selectedIdsFromOptions;
+        const nextSelectedIds = normalizeSingleSelectedIds(nextCandidateIds);
+
+        // 선택 결과가 동일하면 기존 배열 참조를 유지해 effect 루프를 방지한다.
+        if (isSameIdList(previousSelectedIds, nextSelectedIds)) {
+          return previousSelectedIds;
+        }
+
+        return nextSelectedIds;
+      });
+    }, [isSelectionControlled, options, selectedIdsFromOptions]);
+
+    /**
+     * 7) 최종 선택 id 계산
+     * - controlled: selectedOptionIds를 우선 사용
+     * - uncontrolled: 내부 state를 사용
+     * - single-select invariant 보장을 위해 항상 최대 1개 id만 반환한다.
+     */
+    const resolvedSelectedIds = useMemo(() => {
+      const sourceIds = isSelectionControlled
+        ? (selectedOptionIds ?? [])
+        : uncontrolledSelectedOptionIds;
+      return normalizeSingleSelectedIds(sourceIds);
+    }, [
+      isSelectionControlled,
+      selectedOptionIds,
+      uncontrolledSelectedOptionIds,
+    ]);
+    const selectedIdSet = useMemo(
+      () => new Set(resolvedSelectedIds),
+      [resolvedSelectedIds],
+    );
+
+    /**
+     * 8) 표시 라벨 계산
+     * - 외부 displayLabel이 있으면 최우선 사용
+     * - 없으면 현재 선택 id 기준으로 optionMap에서 label을 조회한다.
+     * - optionMap을 사용해 O(1) 조회로 단순화한다.
+     */
     const resolvedDisplayLabel =
       displayLabel ??
       (resolvedSelectedIds.length > 0
-        ? options.find(option => option.id === resolvedSelectedIds[0])?.label
+        ? optionMap.get(resolvedSelectedIds[0])?.label
         : undefined);
 
+    /**
+     * 9) placeholder/label 표시 상태 계산
+     * - null/undefined/빈 문자열이면 placeholder로 간주한다.
+     */
     const hasLabel =
       resolvedDisplayLabel !== undefined &&
       resolvedDisplayLabel !== null &&
       resolvedDisplayLabel !== "";
 
+    /**
+     * 10) dropdown open 상태 관리
+     * - open/defaultOpen/onOpenChange 계약은 기존 useSelectDropdownOpenState를 그대로 사용한다.
+     * - 내부 state와 controlled open 상태를 동시에 지원한다.
+     */
     const { open: dropdownOpen, setOpen } = useSelectDropdownOpenState({
       open: open ?? isOpen,
       defaultOpen,
       onOpenChange,
     });
-    // 변경: outside close는 Radix onOpenChange 기본 동작을 사용한다.
+
+    /**
+     * 11) 상호작용 차단 조건 계산
+     * - disabled/readOnly일 때는 open 토글과 option select를 모두 차단한다.
+     */
     const isInteractionBlocked = disabled || readOnly;
 
+    /**
+     * 12) open 상태 변경 핸들러
+     * - 차단 상태면 강제로 닫힘(false) 유지
+     * - 허용 상태면 전달받은 nextOpen 반영
+     */
     const handleOpenChange = (nextOpen: boolean) => {
       if (isInteractionBlocked) {
         setOpen(false);
@@ -99,17 +225,60 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       setOpen(nextOpen);
     };
 
+    /**
+     * 13) option 선택 처리(single)
+     * - single-select 정책: 클릭된 option 하나를 최종 선택값으로 고정
+     * - uncontrolled 모드면 내부 state 갱신
+     * - onChange(payload)로 현재 선택 결과 전체를 전달
+     * - legacy onOptionSelect는 하위호환으로 유지
+     */
     const handleOptionSelect = (option: SelectDropdownOption) => {
       if (isInteractionBlocked) {
         return;
       }
+
+      const nextSelectedOptionIds = [option.id];
+      const nextSelectedOptions = nextSelectedOptionIds
+        .map(selectedOptionId => optionMap.get(selectedOptionId))
+        .filter(
+          (
+            selectedOption,
+          ): selectedOption is NonNullable<typeof selectedOption> =>
+            Boolean(selectedOption),
+        );
+
+      if (!isSelectionControlled) {
+        setUncontrolledSelectedOptionIds(nextSelectedOptionIds);
+      }
+
+      onChange?.({
+        mode: "single",
+        selectedOptionIds: nextSelectedOptionIds,
+        selectedValues: nextSelectedOptions.map(
+          selectedOption => selectedOption.value,
+        ),
+        selectedOptions: nextSelectedOptions,
+        currentOption: option,
+        isSelected: true,
+      });
+
       onOptionSelect?.(option);
       setOpen(false);
     };
 
+    /**
+     * 14) dropdown 패널 렌더링 파생값
+     * - panelSize: trigger size와 동일 축을 기본으로 사용
+     * - hasOptions: empty 상태 분기
+     */
     const panelSize = (dropdownSize ?? size) as DropdownSize;
     const hasOptions = options.length > 0;
 
+    /**
+     * 15) 렌더
+     * - Container → Dropdown.Root → Trigger → Container → Menu.List depth 유지
+     * - empty 상태는 별도 구조를 만들지 않고 Dropdown.Menu.Item을 disabled로 재사용
+     */
     return (
       <Container
         className={clsx("select-trigger-container", className)}
@@ -161,7 +330,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
                       left={option.left}
                       right={option.right}
                       multiple={Boolean(option.multiple)}
-                      isSelected={resolvedSelectedIds.includes(option.id)}
+                      isSelected={selectedIdSet.has(option.id)}
                       onSelect={event => {
                         if (option.disabled) {
                           event.preventDefault();

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

@@ -1,7 +1,7 @@
 "use client";
 
 import clsx from "clsx";
-import { forwardRef, useMemo } from "react";
+import { forwardRef, useEffect, useMemo, useState } from "react";
 
 import Container from "../foundation/Container";
 import { Dropdown } from "../../../dropdown/markup";
@@ -12,6 +12,10 @@ import { SelectMultipleSelectedChip } from "./SelectedChip";
 import { SelectTriggerBase, SelectTriggerSelected } from "../foundation";
 import { useSelectDropdownOpenState } from "../../hooks";
 
+const isSameIdList = (previousIds: string[], nextIds: string[]) =>
+  previousIds.length === nextIds.length &&
+  previousIds.every((selectedId, index) => selectedId === nextIds[index]);
+
 /**
  * Select trigger for multi select; 선택된 tag들을 chip 형태로 렌더링한다.
  * @component
@@ -19,6 +23,7 @@ import { useSelectDropdownOpenState } from "../../hooks";
  * @param {SelectMultipleTag[]} [props.tags] 선택된 tag 리스트
  * @param {SelectDropdownOption[]} [props.options] dropdown option 목록
  * @param {string[]} [props.selectedOptionIds] 선택된 option id 리스트
+ * @param {(payload: SelectOptionChangePayload) => void} [props.onChange] 선택 결과 변경 콜백
  * @param {(option: SelectDropdownOption) => void} [props.onOptionSelect] option 선택 콜백
  * @param {React.ReactNode} [props.displayLabel] fallback 라벨
  * @param {React.ReactNode} [props.placeholder] placeholder 텍스트
@@ -60,6 +65,7 @@ const SelectMultipleTrigger = forwardRef<
       tags,
       options = [],
       selectedOptionIds,
+      onChange,
       onOptionSelect,
       dropdownSize,
       dropdownWidth = "match",
@@ -74,32 +80,119 @@ const SelectMultipleTrigger = forwardRef<
     },
     ref,
   ) => {
-    // 변경: table priority는 width 미지정 시 기본 full width를 사용한다.
+    /**
+     * 1) 레이아웃 기본값 계산
+     * - table priority는 width 미지정 시 full width를 기본 동작으로 사용한다.
+     * - trigger/container 양쪽에서 동일한 block 값을 재사용한다.
+     */
     const resolvedBlock =
       block || (priority === "table" && width === undefined);
-    // hook dependency 안정화를 위해 memoized selected id 배열을 유지한다.
+
+    /**
+     * 2) 선택 상태 모드 결정
+     * - selectedOptionIds prop이 있으면 controlled 모드
+     * - selectedOptionIds prop이 없으면 uncontrolled 모드
+     */
+    const isSelectionControlled = selectedOptionIds !== undefined;
+
+    /**
+     * 3) option 조회 최적화 맵 생성
+     * - selected id -> option 조회를 반복하므로 id 기반 맵을 생성한다.
+     * - label 계산, tag 파생, payload selectedOptions 계산에 공통 사용한다.
+     */
+    const optionMap = useMemo(
+      () => new Map(options.map(option => [option.id, option])),
+      [options],
+    );
+
+    /**
+     * 4) uncontrolled 초기 선택값 계산
+     * - options[].selected를 다중 선택 초기값으로 그대로 반영한다.
+     */
+    const selectedIdsFromOptions = useMemo(
+      () => options.filter(option => option.selected).map(option => option.id),
+      [options],
+    );
+
+    /**
+     * 5) uncontrolled 내부 state 선언
+     * - controlled 모드에서는 source로 사용되지 않는다.
+     * - uncontrolled 모드에서는 최종 선택 배열을 내부 state가 소유한다.
+     */
+    const [uncontrolledSelectedOptionIds, setUncontrolledSelectedOptionIds] =
+      useState<string[]>(() => selectedIdsFromOptions);
+
+    /**
+     * 6) options 변경 시 내부 state 정합성 보정(uncontrolled 전용)
+     * - 기존 선택 id 중 현재 options에 남아있는 id만 유지한다.
+     * - 남은 id가 없으면 selectedIdsFromOptions(초기 선택 규칙)로 재동기화한다.
+     */
+    useEffect(() => {
+      if (isSelectionControlled) {
+        return;
+      }
+
+      setUncontrolledSelectedOptionIds(previousSelectedIds => {
+        const optionIdSet = new Set(options.map(option => option.id));
+        const filteredIds = previousSelectedIds.filter(selectedId =>
+          optionIdSet.has(selectedId),
+        );
+        const nextSelectedIds =
+          filteredIds.length > 0 ? filteredIds : selectedIdsFromOptions;
+
+        // 동일한 선택 결과면 기존 배열 참조를 유지해 재렌더 루프를 방지한다.
+        if (isSameIdList(previousSelectedIds, nextSelectedIds)) {
+          return previousSelectedIds;
+        }
+
+        return nextSelectedIds;
+      });
+    }, [isSelectionControlled, options, selectedIdsFromOptions]);
+
+    /**
+     * 7) 최종 선택 id 계산
+     * - controlled: selectedOptionIds 우선
+     * - uncontrolled: 내부 state 사용
+     */
     const resolvedSelectedIds = useMemo(
-      () => selectedOptionIds ?? [],
-      [selectedOptionIds],
+      () =>
+        isSelectionControlled
+          ? (selectedOptionIds ?? [])
+          : uncontrolledSelectedOptionIds,
+      [isSelectionControlled, selectedOptionIds, uncontrolledSelectedOptionIds],
+    );
+    const selectedIdSet = useMemo(
+      () => new Set(resolvedSelectedIds),
+      [resolvedSelectedIds],
     );
 
+    /**
+     * 8) 표시 라벨 계산(보조)
+     * - tags가 비어 있을 때 fallback label 용도로 사용한다.
+     * - 외부 displayLabel 우선, 없으면 첫 선택 option label을 사용한다.
+     */
     const resolvedDisplayLabel =
       displayLabel ??
       (resolvedSelectedIds.length > 0
-        ? options.find(option => option.id === resolvedSelectedIds[0])?.label
+        ? optionMap.get(resolvedSelectedIds[0])?.label
         : undefined);
 
+    /**
+     * 9) tag 파생 계산
+     * - 외부 tags가 주어지면 해당 값을 그대로 사용한다(외부 커스텀 우선).
+     * - tags 미지정이면 selected ids 기반으로 option label을 자동 tag로 변환한다.
+     */
     const derivedTags = useMemo<SelectMultipleTag[]>(() => {
       if (tags && tags.length > 0) {
         return tags;
       }
 
-      if (options.length === 0 || resolvedSelectedIds.length === 0) {
+      if (optionMap.size === 0 || resolvedSelectedIds.length === 0) {
         return [];
       }
 
       return resolvedSelectedIds
-        .map(id => options.find(option => option.id === id))
+        .map(selectedId => optionMap.get(selectedId))
         .filter((option): option is NonNullable<typeof option> =>
           Boolean(option),
         )
@@ -107,22 +200,39 @@ const SelectMultipleTrigger = forwardRef<
           label: option.label,
           removable: false,
         }));
-    }, [tags, options, resolvedSelectedIds]);
+    }, [tags, resolvedSelectedIds, optionMap]);
 
+    /**
+     * 10) placeholder/label 표시 상태 계산
+     * - label 값이 비어 있으면 placeholder 표시로 간주한다.
+     */
     const hasTags = derivedTags.length > 0;
     const hasLabel =
       resolvedDisplayLabel !== undefined &&
       resolvedDisplayLabel !== null &&
       resolvedDisplayLabel !== "";
 
+    /**
+     * 11) dropdown open 상태 관리
+     * - open/defaultOpen/onOpenChange 계약을 hook으로 통합 처리한다.
+     */
     const { open: dropdownOpen, setOpen } = useSelectDropdownOpenState({
       open: open ?? isOpen,
       defaultOpen,
       onOpenChange,
     });
-    // 변경: outside close는 Radix onOpenChange 기본 동작을 사용한다.
+
+    /**
+     * 12) 상호작용 차단 조건
+     * - disabled/readOnly이면 open 토글/option toggle을 모두 차단한다.
+     */
     const isInteractionBlocked = disabled || readOnly;
 
+    /**
+     * 13) open 상태 변경 핸들러
+     * - 차단 상태에서는 항상 닫힘 유지
+     * - 허용 상태에서는 nextOpen 반영
+     */
     const handleOpenChange = (nextOpen: boolean) => {
       if (isInteractionBlocked) {
         setOpen(false);
@@ -131,6 +241,11 @@ const SelectMultipleTrigger = forwardRef<
       setOpen(nextOpen);
     };
 
+    /**
+     * 14) trigger 내 tag 표시 최적화 파생값
+     * - 최대 3개 tag만 표시하고 나머지는 summary chip(+N)로 축약한다.
+     * - 과도한 폭 확장을 방지해 trigger layout 안정성을 유지한다.
+     */
     const panelSize = (dropdownSize ?? size) as DropdownSize;
     const hasOptions = options.length > 0;
     const MAX_VISIBLE_TAGS = 3;
@@ -139,6 +254,56 @@ const SelectMultipleTrigger = forwardRef<
       ? Math.max(derivedTags.length - visibleTags.length, 0)
       : 0;
 
+    /**
+     * 15) option 선택 처리(multiple toggle)
+     * - 이미 선택된 id면 제거, 아니면 추가한다.
+     * - uncontrolled 모드면 내부 state 갱신
+     * - onChange(payload)로 결과 전체를 전달
+     * - legacy onOptionSelect는 하위호환으로 유지
+     */
+    const handleOptionSelect = (optionId: string) => {
+      const wasSelected = selectedIdSet.has(optionId);
+      const nextSelectedOptionIds = wasSelected
+        ? resolvedSelectedIds.filter(selectedId => selectedId !== optionId)
+        : [...resolvedSelectedIds, optionId];
+      const nextSelectedOptions = nextSelectedOptionIds
+        .map(selectedId => optionMap.get(selectedId))
+        .filter(
+          (
+            selectedOption,
+          ): selectedOption is NonNullable<typeof selectedOption> =>
+            Boolean(selectedOption),
+        );
+      const currentOption = optionMap.get(optionId);
+
+      if (!currentOption) {
+        return;
+      }
+
+      if (!isSelectionControlled) {
+        setUncontrolledSelectedOptionIds(nextSelectedOptionIds);
+      }
+
+      onChange?.({
+        mode: "multiple",
+        selectedOptionIds: nextSelectedOptionIds,
+        selectedValues: nextSelectedOptions.map(
+          selectedOption => selectedOption.value,
+        ),
+        selectedOptions: nextSelectedOptions,
+        currentOption,
+        isSelected: !wasSelected,
+      });
+
+      onOptionSelect?.(currentOption);
+    };
+
+    /**
+     * 16) 렌더
+     * - Container → Dropdown.Root → Trigger → Container → Menu.List depth 유지
+     * - hasTags에 따라 chips 또는 placeholder/label 뷰를 분기한다.
+     * - empty 상태는 Dropdown.Menu.Item disabled 조합으로 구조를 통일한다.
+     */
     return (
       <Container
         className={clsx("select-trigger-multiple", className)}
@@ -214,13 +379,13 @@ const SelectMultipleTrigger = forwardRef<
                       left={option.left}
                       right={option.right}
                       multiple
-                      isSelected={resolvedSelectedIds.includes(option.id)}
+                      isSelected={selectedIdSet.has(option.id)}
                       onSelect={event => {
                         if (option.disabled || isInteractionBlocked) {
                           event.preventDefault();
                           return;
                         }
-                        onOptionSelect?.(option);
+                        handleOptionSelect(option.id);
                       }}
                     />
                   ))}

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

@@ -7,38 +7,50 @@ import type { ReactNode } from "react";
 export type SelectOptionValue = string | number;
 
 /**
- * Select option data; form 상태와 직결되는 데이터 계약
- * @property {string} id 렌더링/선택 추적용 고유 id
- * @property {SelectOptionValue} value 실제 form value
- * @property {ReactNode} label 사용자 노출 라벨
- * @property {boolean} [disabled] 비활성 여부
- * @property {OptionData} [data] 추가 데이터 payload
+ * Select option data; 옵션 식별/제출/표시를 한 번에 담는 표준 데이터 계약
+ * @property {string} id 선택 상태 추적용 고유 id(권장: 영속 key)
+ * @property {SelectOptionValue} value 실제 제출값(form/value source of truth)
+ * @property {ReactNode} label 사용자에게 노출할 표시 텍스트/노드
+ * @property {boolean} [disabled] 선택 불가 상태 여부
+ * @property {boolean} [selected] uncontrolled 초기 선택 여부(권장 초기화 필드)
+ * @property {OptionData} [data] 도메인 확장 payload(서비스 2차 활용 데이터)
  */
 export interface SelectOptionData<OptionData = unknown> {
   /**
-   * 렌더링/선택 추적용 고유 id
+   * 선택 상태 추적용 고유 id
+   * - UI 선택 상태 비교의 기준값이다.
+   * - value와 분리해도 되며, 중복되지 않아야 한다.
    */
   id: string;
   /**
-   * 실제 form value
+   * 실제 제출값(form/value source of truth)
+   * - API 전송 또는 저장에 사용하는 값이다.
+   * - label과 분리해 사람이 읽는 문자열에 의존하지 않도록 유지한다.
    */
   value: SelectOptionValue;
   /**
-   * 사용자 노출 라벨
+   * 사용자에게 노출할 표시 라벨
+   * - 문자열뿐 아니라 ReactNode도 허용한다.
    */
   label: ReactNode;
   /**
-   * 비활성 여부
+   * 선택 불가 상태 여부
    */
   disabled?: boolean;
   /**
-   * 추가 데이터 payload
+   * uncontrolled 초기 선택 여부
+   * - selectedOptionIds 없이도 초기값을 선언할 수 있는 권장 필드다.
+   */
+  selected?: boolean;
+  /**
+   * 도메인 확장 payload
+   * - 선택 후 서비스 코드에서 2차 데이터로 활용할 수 있다.
    */
   data?: OptionData;
 }
 
 /**
- * Select option render data; Dropdown.Menu.Item 렌더링 보조 정보
+ * Select option render data; Dropdown.Menu.Item 시각 보조 정보
  * @property {ReactNode} [description] 보조 텍스트
  * @property {ReactNode} [left] 좌측 콘텐츠
  * @property {ReactNode} [right] 우측 콘텐츠
@@ -47,30 +59,35 @@ export interface SelectOptionData<OptionData = unknown> {
 export interface SelectOptionRenderData {
   /**
    * 보조 텍스트
+   * - label 하단에 부가 정보를 노출할 때 사용한다.
    */
   description?: ReactNode;
   /**
    * 좌측 콘텐츠
+   * - 아이콘/체크마크 등 leading 영역 커스텀에 사용한다.
    */
   left?: ReactNode;
   /**
    * 우측 콘텐츠
+   * - shortcut/badge 등 trailing 영역 커스텀에 사용한다.
    */
   right?: ReactNode;
   /**
    * multi select 스타일 여부
+   * - Dropdown.Menu.Item 다중 선택 스타일 토글에 사용한다.
    */
   multiple?: boolean;
 }
 
 /**
- * Select dropdown option; data 계약과 render 계약을 합쳐 Select 입력 모델을 구성한다.
+ * Select dropdown option; 데이터 계약 + 렌더 계약을 결합한 Select 표준 입력 모델
  * @extends SelectOptionData
  * @extends SelectOptionRenderData
  * @property {string} id 렌더링/선택 추적용 고유 id
  * @property {SelectOptionValue} value 실제 form value
  * @property {ReactNode} label 사용자 노출 라벨
  * @property {boolean} [disabled] 비활성 여부
+ * @property {boolean} [selected] uncontrolled 초기 선택 여부
  * @property {OptionData} [data] 추가 데이터 payload
  * @property {ReactNode} [description] 보조 텍스트
  * @property {ReactNode} [left] 좌측 콘텐츠
@@ -80,6 +97,49 @@ export interface SelectOptionRenderData {
 export interface SelectDropdownOption<OptionData = unknown>
   extends SelectOptionData<OptionData>, SelectOptionRenderData {}
 
+/**
+ * Select option change payload; 단일/다중 선택 결과를 서비스가 즉시 소비할 수 있게 전달한다.
+ * @property {"single" | "multiple"} mode 선택 모드
+ * @property {string[]} selectedOptionIds 선택된 option id 목록
+ * @property {SelectOptionValue[]} selectedValues 선택된 value 목록
+ * @property {SelectDropdownOption<OptionData>[]} selectedOptions 선택된 option 목록
+ * @property {SelectDropdownOption<OptionData>} currentOption 현재 상호작용한 option
+ * @property {boolean} isSelected currentOption 선택 여부
+ */
+export interface SelectOptionChangePayload<OptionData = unknown> {
+  /**
+   * 선택 모드
+   * - "single": 단일 선택
+   * - "multiple": 다중 선택
+   */
+  mode: "single" | "multiple";
+  /**
+   * 선택된 option id 목록
+   * - legacy controlled 상태 동기화가 필요할 때 사용한다.
+   */
+  selectedOptionIds: string[];
+  /**
+   * 선택된 value 목록
+   * - form 제출값을 바로 반영할 때 사용한다.
+   */
+  selectedValues: SelectOptionValue[];
+  /**
+   * 선택된 option 전체 데이터 목록
+   * - label/data 등 2차 데이터를 즉시 사용하려는 권장 소비 지점이다.
+   */
+  selectedOptions: SelectDropdownOption<OptionData>[];
+  /**
+   * 현재 상호작용한 option
+   * - 어떤 option 클릭으로 상태가 변경되었는지 추적할 때 사용한다.
+   */
+  currentOption: SelectDropdownOption<OptionData>;
+  /**
+   * currentOption 선택 여부
+   * - multiple 토글 시 add/remove 방향을 구분할 때 사용한다.
+   */
+  isSelected: boolean;
+}
+
 /**
  * Select legacy option 데이터 구조; 과거 key/optionName 스키마 호환을 위해 유지한다.
  * @property {string} key 렌더링 키
@@ -88,6 +148,7 @@ export interface SelectDropdownOption<OptionData = unknown>
  * @property {boolean} [selected] 선택 여부
  * @property {boolean} [disabled] 비활성 여부
  * @property {OptionData} [data] 추가 데이터 payload
+ * @deprecated SelectDropdownOption으로 마이그레이션한다.
  */
 export interface SelectLegacyOption<OptionData = unknown> {
   /**

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

@@ -8,7 +8,7 @@ import type {
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
 import type { SelectPriority, SelectSize, SelectState } from "./base";
-import type { SelectDropdownOption } from "./option";
+import type { SelectDropdownOption, SelectOptionChangePayload } from "./option";
 import type {
   SelectTriggerDefaultProps,
   SelectTriggerMultipleProps,
@@ -134,10 +134,11 @@ export type SelectProps = SelectStyleOptions &
   SelectWidthOption;
 
 /**
- * Select dropdown 옵션 구성 props
- * @property {SelectDropdownOption[]} [options] dropdown option 리스트
- * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
- * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
+ * 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 제외)
@@ -148,14 +149,22 @@ export type SelectProps = SelectStyleOptions &
 export interface SelectDropdownConfigProps {
   /**
    * dropdown option 리스트
+   * - 권장: uncontrolled 초기 선택은 options[].selected를 사용한다.
    */
   options?: SelectDropdownOption[];
   /**
    * 선택된 option id 리스트
+   * @deprecated onChange + options[].selected 기반 계약을 우선 사용한다.
    */
   selectedOptionIds?: string[];
+  /**
+   * 선택 결과 변경 콜백
+   * - 권장: payload.selectedOptions / payload.selectedValues를 직접 소비한다.
+   */
+  onChange?: (payload: SelectOptionChangePayload) => void;
   /**
    * option 선택 콜백
+   * @deprecated onChange로 대체되며 하위호환을 위해 유지된다.
    */
   onOptionSelect?: (option: SelectDropdownOption) => void;
   /**
@@ -192,7 +201,7 @@ export interface SelectDropdownConfigProps {
 }
 
 /**
- * Select dropdown 개방 제어 props
+ * Select dropdown 개방 제어 props; open controlled/uncontrolled 축을 정의한다.
  * @property {boolean} [open] dropdown open 상태
  * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
  * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
@@ -200,14 +209,17 @@ export interface SelectDropdownConfigProps {
 export interface SelectDropdownBehaviorProps {
   /**
    * dropdown open 상태
+   * - 값이 있으면 controlled open 모드로 동작한다.
    */
   open?: boolean;
   /**
    * uncontrolled 초기 open 상태
+   * - open prop이 없을 때만 초기값으로 사용된다.
    */
   defaultOpen?: boolean;
   /**
    * open state change 콜백
+   * - controlled/uncontrolled 모두에서 호출된다.
    */
   onOpenChange?: (open: boolean) => void;
 }
@@ -228,6 +240,7 @@ export interface SelectDropdownBehaviorProps {
  * @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 옵션
@@ -260,6 +273,7 @@ export type SelectDefaultComponentProps = SelectTriggerDefaultProps &
  * @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 옵션