@uniai-fe/uds-primitives 0.3.20 → 0.3.21

package/package.json

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

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

@@ -31,9 +31,7 @@ const normalizeSelectedIdsByMode = (
  * @param {DropdownTemplateProps} props Dropdown template props
  * @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 옵션
  * @param {DropdownMenuProps} [props.rootProps] Dropdown.Root 전달 props
@@ -44,9 +42,7 @@ const normalizeSelectedIdsByMode = (
 const DropdownTemplate = ({
   trigger,
   items,
-  selectedIds,
   onChange,
-  onSelect,
   size = "medium",
   width = "match",
   rootProps,
@@ -55,15 +51,7 @@ const DropdownTemplate = ({
   alt,
 }: DropdownTemplateProps) => {
   /**
-   * 1) 선택 상태 모드 결정
-   * - selectedIds prop이 들어오면 외부가 상태를 소유하는 controlled 모드다.
-   * - selectedIds prop이 없으면 Template 내부 state가 상태를 소유하는 uncontrolled 모드다.
-   * - 이 분기 기준은 렌더마다 동일해야 하므로 가장 먼저 계산한다.
-   */
-  const isSelectionControlled = selectedIds !== undefined;
-
-  /**
-   * 2) 선택 정책(single/multiple) 결정
+   * 1) 선택 정책(single/multiple) 결정
    * - item 중 하나라도 multiple=true이면 multiple 정책으로 해석한다.
    * - multiple 정책에서는 item id 배열 전체를 유지한다.
    * - single 정책에서는 언제나 최대 1개 id만 유지한다.
@@ -71,7 +59,7 @@ const DropdownTemplate = ({
   const isMultiple = items.some(item => item.multiple);
 
   /**
-   * 3) uncontrolled 초기 선택값 계산
+   * 2) 초기 선택값 계산
    * - source of truth: items[].selected
    * - multiple: selected=true인 모든 id를 초기값으로 사용한다.
    * - single: selected=true가 여러 개여도 첫 번째 id 하나만 사용한다.
@@ -86,9 +74,8 @@ const DropdownTemplate = ({
   }, [isMultiple, items]);
 
   /**
-   * 4) uncontrolled 내부 state 선언
-   * - controlled 모드에서는 이 state가 실제 화면 결정에 사용되지 않는다.
-   * - uncontrolled 모드에서는 이 state가 선택 결과의 단일 source가 된다.
+   * 3) 내부 선택 state 선언
+   * - Template은 items[].selected를 초기값으로 받아 내부 상태를 관리한다.
    * - 초기값은 selectedIdsFromItems를 그대로 사용한다.
    */
   const [uncontrolledSelectedIds, setUncontrolledSelectedIds] = useState<
@@ -96,19 +83,14 @@ const DropdownTemplate = ({
   >(() => selectedIdsFromItems);
 
   /**
-   * 5) options(items) 변경 동기화
-   * - controlled 모드에서는 외부 selectedIds를 신뢰해야 하므로 내부 state를 건드리지 않는다.
-   * - uncontrolled 모드에서는 내부 state를 items 변경에 맞춰 정합성 보정한다.
+   * 4) options(items) 변경 동기화
+   * - 내부 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 =>
@@ -128,38 +110,36 @@ const DropdownTemplate = ({
 
       return nextSelectedIds;
     });
-  }, [isMultiple, isSelectionControlled, items, selectedIdsFromItems]);
+  }, [isMultiple, items, selectedIdsFromItems]);
 
   /**
-   * 6) 최종 선택 id 계산
-   * - controlled: selectedIds prop을 그대로 사용한다(single은 첫 id만 허용).
-   * - uncontrolled: 내부 state(uncontrolledSelectedIds)를 그대로 사용한다.
+   * 5) 최종 선택 id 계산
+   * - 내부 state(uncontrolledSelectedIds)를 single/multiple 정책으로 정규화한다.
    * - 렌더/이벤트/selected 스타일 계산은 이 값만 참조한다.
    */
   const resolvedSelectedIds = normalizeSelectedIdsByMode(
-    isSelectionControlled ? (selectedIds ?? []) : uncontrolledSelectedIds,
+    uncontrolledSelectedIds,
     isMultiple,
   );
 
   /**
-   * 7) empty panel 분기
+   * 6) empty panel 분기
    * - item이 비어 있으면 alt 또는 기본 문구를 disabled item으로 렌더링한다.
    * - 별도 li를 만들지 않고 MenuItem을 재사용해 구조를 통일한다.
    */
   const hasItems = items.length > 0;
 
   /**
-   * 8) item 선택 처리
+   * 7) item 선택 처리
    * - 클릭된 item(id) 기준으로 다음 선택 배열을 계산한다.
    * - multiple: 토글(add/remove)
    * - single: 클릭한 id 하나로 교체
-   * - uncontrolled 모드면 내부 state를 즉시 반영한다.
+   * - 내부 state를 즉시 반영한다.
    * - onChange(payload)로 "현재 결과 전체"를 전달한다.
-   * - onSelect(item)은 하위호환을 위해 마지막에 유지 호출한다.
    */
   const handleItemSelect = (itemId: string) => {
     /**
-     * 8-1) 클릭된 item 조회
+     * 7-1) 클릭된 item 조회
      * - items 목록에 없는 id면 안전하게 종료한다.
      * - 외부 데이터 race 조건에서 방어적으로 동작하기 위한 가드다.
      */
@@ -170,7 +150,7 @@ const DropdownTemplate = ({
     }
 
     /**
-     * 8-2) 다음 selectedIds 계산
+     * 7-2) 다음 selectedIds 계산
      * - wasSelected: 토글 기준 값
      * - nextSelectedIds: 모드 정책을 적용한 다음 상태
      * - nextSelectedItems: payload 전달용 상세 데이터
@@ -186,16 +166,13 @@ const DropdownTemplate = ({
     );
 
     /**
-     * 8-3) 내부 state 업데이트(uncontrolled 전용)
-     * - controlled 모드에서는 외부 selectedIds prop이 곧 source of truth이므로
-     *   내부 state를 갱신하지 않는다.
+     * 7-3) 내부 state 업데이트
+     * - Template 내부 선택 상태를 즉시 반영한다.
      */
-    if (!isSelectionControlled) {
-      setUncontrolledSelectedIds(nextSelectedIds);
-    }
+    setUncontrolledSelectedIds(nextSelectedIds);
 
     /**
-     * 8-4) 신규 계약 이벤트(onChange)
+     * 7-4) 선택 결과 이벤트(onChange)
      * - 서비스/상위 컴포넌트가 선택 결과 전체를 즉시 사용할 수 있게
      *   현재 item + 선택 결과 배열을 함께 제공한다.
      */
@@ -206,17 +183,10 @@ const DropdownTemplate = ({
       selectedItems: nextSelectedItems,
       multiple: isMultiple,
     });
-
-    /**
-     * 8-5) legacy 계약 이벤트(onSelect)
-     * - 하위호환 경로를 유지하기 위해 onChange 이후 동일 선택을 전달한다.
-     * - 추후 마이그레이션 완료 시 제거 대상이다.
-     */
-    onSelect?.(currentItem);
   };
 
   /**
-   * 9) 렌더 구성
+   * 8) 렌더 구성
    * - Root → Trigger → Container → MenuList depth를 유지한다.
    * - 각 item은 resolvedSelectedIds 기준으로 selected 스타일을 결정한다.
    * - disabled item은 select 이벤트를 차단하고 상태만 노출한다.

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

@@ -167,9 +167,7 @@ export interface DropdownTemplateChangePayload {
  * 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 옵션
  * @property {DropdownMenuProps} [rootProps] Root 에 전달할 props
@@ -180,20 +178,10 @@ export interface DropdownTemplateChangePayload {
 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

@@ -41,7 +41,6 @@ const SELECT_CUSTOM_OPTION_VALUE = "CUSTOM";
  * @param {"default" | "focused" | "error" | "disabled"} [props.state="default"] trigger state
  * @param {boolean} [props.block] block 레이아웃 여부
  * @param {FormFieldWidth} [props.width] container width
- * @param {boolean} [props.isOpen] legacy open alias
  * @param {boolean} [props.disabled] disabled 여부
  * @param {boolean} [props.readOnly] readOnly 여부
  * @param {"button" | "submit" | "reset"} [props.buttonType] trigger button type
@@ -74,7 +73,6 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       state = "default",
       block,
       width,
-      isOpen,
       disabled,
       readOnly,
       buttonType,
@@ -182,7 +180,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
 
     // 12) open 제어형/비제어형 계약은 공용 hook으로 통합 처리한다.
     const { open: dropdownOpen, setOpen } = useSelectDropdownOpenState({
-      open: open ?? isOpen,
+      open,
       defaultOpen,
       onOpen,
     });

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

@@ -33,7 +33,6 @@ const SELECT_MULTIPLE_ALL_OPTION_BASE_ID = "__select_multiple_all__";
  * @param {"default" | "focused" | "disabled"} [props.state="default"] 시각 상태
  * @param {boolean} [props.block] block 여부
  * @param {FormFieldWidth} [props.width] container width preset
- * @param {boolean} [props.isOpen] dropdown open 여부
  * @param {boolean} [props.disabled] disabled 여부
  * @param {boolean} [props.readOnly] readOnly 여부
  * @param {SelectDropdownExtension} [props.dropdown] dropdown 확장 옵션
@@ -57,7 +56,6 @@ const SelectMultipleTrigger = forwardRef<
       state = "default",
       block,
       width,
-      isOpen,
       disabled,
       readOnly,
       tags,
@@ -257,7 +255,7 @@ const SelectMultipleTrigger = forwardRef<
      * - open/defaultOpen/onOpen 계약을 hook으로 통합 처리한다.
      */
     const { open: dropdownOpen, setOpen } = useSelectDropdownOpenState({
-      open: open ?? isOpen,
+      open,
       defaultOpen,
       onOpen,
     });

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

@@ -73,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;
 }
 
 /**
@@ -295,7 +295,7 @@ export interface SelectCustomOptionExtension {
  * @property {ReactNode} [placeholder] placeholder 텍스트
  * @property {ReactNode[]} [tags] multi select 태그 리스트
  * @property {boolean} [multiple] multi select 여부
- * @property {boolean} [isOpen] dropdown open 여부
+ * @property {boolean} [open] dropdown open 여부
  * @property {FormFieldWidth} [width] width preset 옵션
  */
 export type SelectProps = SelectStyleOptions &
@@ -311,7 +311,7 @@ export type SelectProps = SelectStyleOptions &
  * @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
@@ -362,7 +362,7 @@ 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 옵션

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

@@ -129,7 +129,7 @@ export interface SelectTriggerDefaultProps extends HTMLAttributes<HTMLElement> {
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
   /**
    * disabled 여부
    */
@@ -190,7 +190,7 @@ export interface SelectTriggerMultipleProps extends HTMLAttributes<HTMLElement>
   /**
    * dropdown open 여부
    */
-  isOpen?: boolean;
+  open?: boolean;
   /**
    * disabled 여부
    */