@uniai-fe/uds-primitives 0.2.7 → 0.2.9

package/dist/styles.css

@@ -1782,6 +1782,10 @@ figure.chip {
   margin: 0;
 }
 
+.dropdown-menu-item-trigger.dropdown-menu-alt[data-disabled] {
+  cursor: default;
+}
+
 .dropdown-menu-item {
   width: 100%;
 }

package/package.json

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

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

@@ -12,6 +12,16 @@ import DropdownTrigger from "./foundation/Trigger";
  * Dropdown reference template; trigger/panel/menu 조합을 제공한다.
  * @component
  * @param {DropdownTemplateProps} props Dropdown template props
+ * @param {ReactNode} props.trigger trigger 요소
+ * @param {DropdownTemplateItem[]} props.items 렌더링할 menu item 리스트
+ * @param {string[]} [props.selectedIds] 선택된 item id 배열
+ * @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
+ * @param {DropdownContainerProps} [props.containerProps] Dropdown.Container 전달 props
+ * @param {DropdownMenuListProps} [props.menuListProps] Dropdown.Menu.List 전달 props
+ * @param {ReactNode} [props.alt] empty 상태 대체 콘텐츠
  */
 const DropdownTemplate = ({
   trigger,
@@ -23,31 +33,45 @@ const DropdownTemplate = ({
   rootProps,
   containerProps,
   menuListProps,
+  alt,
 }: DropdownTemplateProps) => {
+  const hasItems = items.length > 0;
+
   return (
     <DropdownRoot {...rootProps}>
       <DropdownTrigger asChild>{trigger}</DropdownTrigger>
       <DropdownContainer {...containerProps} size={size} width={width}>
         <DropdownMenuList {...menuListProps}>
-          {items.map(item => (
+          {hasItems ? (
+            <>
+              {items.map(item => (
+                <DropdownMenuItem
+                  key={item.id}
+                  label={item.label}
+                  description={item.description}
+                  disabled={item.disabled}
+                  left={item.left}
+                  right={item.right}
+                  multiple={item.multiple}
+                  isSelected={selectedIds?.includes(item.id)}
+                  onSelect={event => {
+                    if (item.disabled) {
+                      event.preventDefault();
+                      return;
+                    }
+                    onSelect?.(item);
+                  }}
+                />
+              ))}
+            </>
+          ) : (
             <DropdownMenuItem
-              key={item.id}
-              label={item.label}
-              description={item.description}
-              disabled={item.disabled}
-              left={item.left}
-              right={item.right}
-              multiple={item.multiple}
-              isSelected={selectedIds?.includes(item.id)}
-              onSelect={event => {
-                if (item.disabled) {
-                  event.preventDefault();
-                  return;
-                }
-                onSelect?.(item);
-              }}
+              // 변경: 사용처 1회 상수 대신 인라인 fallback으로 empty label을 처리한다.
+              label={alt ?? "데이터가 없습니다."}
+              disabled
+              className="dropdown-menu-alt"
             />
-          ))}
+          )}
         </DropdownMenuList>
       </DropdownContainer>
     </DropdownRoot>

package/src/components/dropdown/markup/foundation/Container.tsx

@@ -8,11 +8,23 @@ import type { DropdownContainerProps } from "../../types/props";
 import { useDropdownContext } from "./Provider";
 
 /**
- * Dropdown container; trigger width 동기화 및 portal 관리
+ * Dropdown Foundation; Container 패널 렌더링 컴포넌트
  * @component
  * @param {DropdownContainerProps} props Dropdown container props
- * @param {DropdownPanelWidth} [props.width="match"] panel width 옵션
+ * @param {React.ReactNode} props.children dropdown panel 콘텐츠
+ * @param {string} [props.className] panel className
  * @param {DropdownSize} [props.size="medium"] option height scale
+ * @param {DropdownPanelWidth} [props.width="match"] panel width 옵션
+ * @param {HTMLElement | null} [props.portalContainer] portal 컨테이너
+ * @param {"start" | "center" | "end"} [props.align="start"] 정렬 기준
+ * @param {"top" | "right" | "bottom" | "left"} [props.side="bottom"] 패널 위치
+ * @param {number} [props.sideOffset=4] trigger 와 패널 사이 간격
+ * @param {number} [props.alignOffset] 정렬 보정값
+ * @param {React.CSSProperties} [props.style] 인라인 스타일
+ * @example
+ * <DropdownContainer width="match">
+ *   <Dropdown.Menu.List />
+ * </DropdownContainer>
  */
 const DropdownContainer = forwardRef<HTMLDivElement, DropdownContainerProps>(
   (

package/src/components/dropdown/markup/foundation/MenuItem.tsx

@@ -9,11 +9,20 @@ import { Checkbox } from "../../../checkbox/markup/Checkbox";
 import type { CheckboxProps } from "../../../checkbox/types";
 
 /**
- * Dropdown menu item; label/description/slot 구성을 처리한다.
+ * Dropdown Foundation; Menu Item 옵션 렌더링 컴포넌트
  * @component
  * @param {DropdownMenuItemProps} props dropdown menu option props
- * @param {boolean} [props.isSelected] 선택 상태
- * @param {boolean} [props.multiple] multi select 스타일 여부
+ * @param {React.ReactNode} [props.label] 옵션 라벨
+ * @param {React.ReactNode} [props.description] 보조 텍스트
+ * @param {React.ReactNode} [props.left] 좌측 콘텐츠
+ * @param {React.ReactNode} [props.right] 우측 콘텐츠
+ * @param {boolean} [props.isSelected=false] 선택 상태
+ * @param {boolean} [props.multiple=false] multi select 스타일 여부
+ * @param {CheckboxProps} [props.checkboxProps] multiple 시 checkbox props
+ * @param {React.ReactNode} [props.children] label 미지정 시 fallback 콘텐츠
+ * @param {string} [props.className] Dropdown item className
+ * @example
+ * <DropdownMenuItem label="옵션 A" isSelected />
  */
 const DropdownMenuItem = forwardRef<HTMLDivElement, DropdownMenuItemProps>(
   (
@@ -33,6 +42,13 @@ const DropdownMenuItem = forwardRef<HTMLDivElement, DropdownMenuItemProps>(
     ref,
   ) => {
     const labelContent = label ?? children;
+    // 변경: label/children이 string|number일 때만 준비된 label span으로 매핑하고, 그 외 ReactNode는 그대로 렌더링한다.
+    const resolvedLabelContent =
+      typeof labelContent === "string" || typeof labelContent === "number" ? (
+        <span className="dropdown-menu-item-label">{labelContent}</span>
+      ) : (
+        labelContent
+      );
     const hasDescription = Boolean(description);
     const shouldRenderCheckbox = multiple && !left;
 
@@ -84,9 +100,7 @@ const DropdownMenuItem = forwardRef<HTMLDivElement, DropdownMenuItemProps>(
         >
           {renderLeft()}
           <span className="dropdown-menu-item-body">
-            {labelContent ? (
-              <span className="dropdown-menu-item-label">{labelContent}</span>
-            ) : null}
+            {resolvedLabelContent}
             {description ? (
               <span className="dropdown-menu-item-description">
                 {description}

package/src/components/dropdown/markup/foundation/Root.tsx

@@ -1,23 +1,30 @@
 "use client";
 
 import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
 import type { ReactNode } from "react";
 
-import type { DropdownRootProps } from "../../types/base";
 import { DropdownProvider } from "./Provider";
 
 /**
- * Dropdown root; Provider와 Radix Root를 래핑한다.
+ * Dropdown Foundation; Root Provider 래핑 컴포넌트
  * @component
- * @param {DropdownRootProps} props Dropdown Root props
+ * @param {DropdownMenuProps} props Dropdown Root props
  * @param {ReactNode} props.children Dropdown 하위 node
  * @param {boolean} [props.modal=false] Radix modal 모드
+ * @param {boolean} [props.open] 제어형 open 상태
+ * @param {boolean} [props.defaultOpen] 비제어형 초기 open 상태
+ * @param {(open: boolean) => void} [props.onOpenChange] open 변경 콜백
+ * @example
+ * <DropdownRoot>
+ *   <Dropdown.Trigger>열기</Dropdown.Trigger>
+ * </DropdownRoot>
  */
 const DropdownRoot = ({
   children,
   modal = false,
   ...rootProps
-}: DropdownRootProps & { children: ReactNode }) => {
+}: DropdownMenuProps & { children: ReactNode }) => {
   return (
     <DropdownProvider>
       <DropdownMenu.Root modal={modal} {...rootProps}>

package/src/components/dropdown/markup/foundation/Trigger.tsx

@@ -1,19 +1,25 @@
 "use client";
 
 import * as DropdownMenu from "@radix-ui/react-dropdown-menu";
+import type { DropdownMenuTriggerProps } from "@radix-ui/react-dropdown-menu";
 import { forwardRef } from "react";
 
-import type { DropdownTriggerProps } from "../../types/props";
 import { mergeRefs } from "../../utils";
 import { useDropdownContext } from "./Provider";
 
 /**
- * Dropdown trigger; trigger ref를 context에 공유한다.
+ * Dropdown Foundation; Trigger ref 공유 컴포넌트
  * @component
- * @param {DropdownTriggerProps} props Dropdown trigger props
+ * @param {DropdownMenuTriggerProps} props Dropdown trigger props
  * @param {boolean} [props.asChild=true] asChild 패턴 유지 여부
+ * @param {React.ReactNode} props.children Trigger 하위 node
+ * @param {string} [props.className] Trigger className
+ * @example
+ * <DropdownTrigger asChild>
+ *   <button type="button">열기</button>
+ * </DropdownTrigger>
  */
-const DropdownTrigger = forwardRef<HTMLElement, DropdownTriggerProps>(
+const DropdownTrigger = forwardRef<HTMLElement, DropdownMenuTriggerProps>(
   ({ asChild = true, children, ...rest }, ref) => {
     const { triggerRef } = useDropdownContext("Dropdown.Trigger");
 

package/src/components/dropdown/styles/dropdown.scss

@@ -47,6 +47,10 @@
   margin: 0;
 }
 
+.dropdown-menu-item-trigger.dropdown-menu-alt[data-disabled] {
+  cursor: default;
+}
+
 .dropdown-menu-item {
   width: 100%;
 }

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

@@ -1,5 +1,3 @@
-import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
-
 /**
  * Dropdown size scale
  * @typedef {"small" | "medium" | "large"} DropdownSize
@@ -18,14 +16,3 @@ export type DropdownPanelWidth =
   | "max-content"
   | string
   | number;
-
-/**
- * Dropdown root props
- * @property {boolean} [modal] Radix modal 모드 여부
- */
-export interface DropdownRootProps extends DropdownMenuProps {
-  /**
-   * Radix modal 모드 여부
-   */
-  modal?: DropdownMenuProps["modal"];
-}

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

@@ -1,22 +1,12 @@
 import type {
+  DropdownMenuProps,
   DropdownMenuContentProps,
   DropdownMenuItemProps as RadixDropdownMenuItemProps,
-  DropdownMenuTriggerProps,
 } from "@radix-ui/react-dropdown-menu";
 import type { HTMLAttributes, MutableRefObject, ReactNode } from "react";
 
 import type { CheckboxProps } from "../../checkbox/types";
-import type {
-  DropdownPanelWidth,
-  DropdownRootProps,
-  DropdownSize,
-} from "./base";
-
-/**
- * Dropdown trigger props
- * @property {boolean} [asChild=true] trigger를 asChild 패턴으로 감쌀지 여부
- */
-export type DropdownTriggerProps = DropdownMenuTriggerProps;
+import type { DropdownPanelWidth, DropdownSize } from "./base";
 
 /**
  * Dropdown Container props
@@ -142,11 +132,13 @@ export interface DropdownTemplateItem {
  * @property {ReactNode} trigger trigger 요소
  * @property {DropdownTemplateItem[]} items 렌더링할 menu item 리스트
  * @property {string[]} [selectedIds] 선택된 item id 배열
+ * @property {(item: DropdownTemplateItem) => void} [onSelect] item 선택 콜백
  * @property {DropdownSize} [size="medium"] surface height scale
  * @property {DropdownPanelWidth} [width="match"] panel width 옵션
- * @property {DropdownRootProps} [rootProps] Root 에 전달할 props
+ * @property {DropdownMenuProps} [rootProps] Root 에 전달할 props
  * @property {DropdownContainerProps} [containerProps] Container 에 전달할 props
  * @property {DropdownMenuListProps} [menuListProps] MenuList 에 전달할 props
+ * @property {ReactNode} [alt] item이 비어 있을 때 렌더링할 alternate 콘텐츠
  */
 export interface DropdownTemplateProps {
   trigger: ReactNode;
@@ -157,8 +149,9 @@ export interface DropdownTemplateProps {
   width?: DropdownPanelWidth;
   /**
    * Root 에 전달할 props
+   * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
    */
-  rootProps?: DropdownRootProps;
+  rootProps?: DropdownMenuProps;
   /**
    * Container 에 전달할 props
    */
@@ -167,4 +160,8 @@ export interface DropdownTemplateProps {
    * MenuList 에 전달할 props
    */
   menuListProps?: DropdownMenuListProps;
+  /**
+   * item이 비어 있을 때 렌더링할 alternate 콘텐츠
+   */
+  alt?: ReactNode;
 }

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

@@ -1,45 +1 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
-
-import type { SelectDropdownBehaviorProps } from "../types/props";
-
-/**
- * Select dropdown open 상태를 제어하는 hook
- * @hook
- * @param {SelectDropdownBehaviorProps} props open 제어 옵션
- * @returns {{
- *   open: boolean;
- *   setOpen: (next: boolean) => void;
- *   isControlled: boolean;
- * }} resolved open state
- */
-export const useSelectDropdownOpenState = ({
-  open,
-  defaultOpen,
-  onOpenChange,
-}: SelectDropdownBehaviorProps) => {
-  const isControlled = useMemo(() => typeof open === "boolean", [open]);
-  const [uncontrolledOpen, setUncontrolledOpen] = useState(
-    defaultOpen ?? false,
-  );
-
-  useEffect(() => {
-    if (isControlled) {
-      return;
-    }
-    setUncontrolledOpen(defaultOpen ?? false);
-  }, [defaultOpen, isControlled]);
-
-  const resolvedOpen = isControlled ? (open as boolean) : uncontrolledOpen;
-
-  const setOpen = useCallback(
-    (nextOpen: boolean) => {
-      if (!isControlled) {
-        setUncontrolledOpen(nextOpen);
-      }
-      onOpenChange?.(nextOpen);
-    },
-    [isControlled, onOpenChange],
-  );
-
-  return { open: resolvedOpen, setOpen, isControlled };
-};
+export * from "./interaction";

package/src/components/select/hooks/interaction.ts

@@ -0,0 +1,62 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useState } from "react";
+
+import type {
+  UseSelectDropdownOpenStateParams,
+  UseSelectDropdownOpenStateReturn,
+} from "../types/interaction";
+
+/**
+ * Select Hook; Dropdown open 상태 제어 Hook
+ * @hook
+ * @param {UseSelectDropdownOpenStateParams} params open 제어 옵션
+ * @param {boolean} [params.open] 외부 제어형 open 상태
+ * @param {boolean} [params.defaultOpen] 비제어형 초기 open 상태
+ * @param {(open: boolean) => void} [params.onOpenChange] open 상태 변경 콜백
+ * @returns {{
+ *   open: boolean;
+ *   setOpen: (next: boolean) => void;
+ *   isControlled: boolean;
+ * }} resolved open state
+ * @example
+ * const { open, setOpen } = useSelectDropdownOpenState({
+ *   open: controlledOpen,
+ *   defaultOpen: false,
+ *   onOpenChange: onOpenChangeHandler,
+ * });
+ */
+export const useSelectDropdownOpenState = ({
+  open,
+  defaultOpen,
+  onOpenChange,
+}: UseSelectDropdownOpenStateParams): UseSelectDropdownOpenStateReturn => {
+  // 1) 제어형/비제어형 분기 기준을 먼저 확정한다.
+  const isControlled = useMemo(() => typeof open === "boolean", [open]);
+  // 2) 비제어형일 때만 내부 open state를 소유한다.
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(
+    defaultOpen ?? false,
+  );
+
+  // 3) defaultOpen 변경 시, 비제어형일 때만 내부 state를 동기화한다.
+  useEffect(() => {
+    if (isControlled) return;
+
+    setUncontrolledOpen(defaultOpen ?? false);
+  }, [defaultOpen, isControlled]);
+
+  // 4) 최종 open state는 제어형 우선, 아니면 내부 state를 사용한다.
+  const resolvedOpen = isControlled ? (open as boolean) : uncontrolledOpen;
+
+  // 5) setOpen은 내부 state 갱신 + 외부 콜백 브릿지를 동시에 담당한다.
+  const setOpen = useCallback(
+    (nextOpen: boolean) => {
+      if (!isControlled) setUncontrolledOpen(nextOpen);
+
+      onOpenChange?.(nextOpen);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  return { open: resolvedOpen, setOpen, isControlled };
+};

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

@@ -8,10 +8,8 @@ import { Dropdown } from "../../dropdown/markup";
 import { SelectTriggerBase, SelectTriggerSelected } from "./foundation";
 import Container from "./foundation/Container";
 import { useSelectDropdownOpenState } from "../hooks";
-import type {
-  SelectDefaultComponentProps,
-  SelectDropdownOption,
-} from "../types/props";
+import type { SelectDropdownOption } from "../types/option";
+import type { SelectDefaultComponentProps } from "../types/props";
 
 /**
  * Select default trigger; 단일 선택 드롭다운을 렌더링한다.
@@ -24,7 +22,18 @@ import type {
  * @param {"small" | "medium" | "large"} [props.size="medium"] size 스케일
  * @param {"default" | "focused" | "disabled"} [props.state="default"] 시각 상태
  * @param {boolean} [props.block] block 여부
+ * @param {FormFieldWidth} [props.width] container width preset
  * @param {boolean} [props.disabled] disabled 여부
+ * @param {SelectTriggerButtonType} [props.buttonType] trigger button type
+ * @param {"small" | "medium" | "large"} [props.dropdownSize] dropdown panel size
+ * @param {"match" | "fit-content" | "max-content" | string | number} [props.dropdownWidth="match"] dropdown panel width
+ * @param {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [props.dropdownRootProps] Dropdown.Root 전달 props
+ * @param {Omit<DropdownContainerProps, "children" | "size" | "width">} [props.dropdownContainerProps] Dropdown.Container 전달 props
+ * @param {DropdownMenuListProps} [props.dropdownMenuListProps] Dropdown.Menu.List 전달 props
+ * @param {ReactNode} [props.alt] empty 상태 대체 콘텐츠
+ * @param {boolean} [props.open] controlled open 상태
+ * @param {boolean} [props.defaultOpen] uncontrolled 초기 open 상태
+ * @param {(open: boolean) => void} [props.onOpenChange] open 상태 변경 콜백
  */
 const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
   (
@@ -48,6 +57,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       dropdownRootProps,
       dropdownContainerProps,
       dropdownMenuListProps,
+      alt,
       open,
       defaultOpen,
       onOpenChange,
@@ -73,7 +83,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       defaultOpen,
       onOpenChange,
     });
-    // Dropdown open 상태를 trigger data-state와 동기화한다.
+    // 변경: outside close는 Radix onOpenChange 기본 동작을 사용한다.
 
     const handleOptionSelect = (option: SelectDropdownOption) => {
       onOptionSelect?.(option);
@@ -81,7 +91,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
     };
 
     const panelSize = (dropdownSize ?? size) as DropdownSize;
-    const shouldRenderDropdown = options.length > 0;
+    const hasOptions = options.length > 0;
 
     return (
       <Container
@@ -115,36 +125,45 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
               />
             </SelectTriggerBase>
           </Dropdown.Trigger>
-          {shouldRenderDropdown ? (
-            <Dropdown.Container
-              {...dropdownContainerProps}
-              size={panelSize}
-              width={dropdownWidth}
-            >
-              <Dropdown.Menu.List {...dropdownMenuListProps}>
-                {/* Dropdown menu option들을 그대로 매핑해 선택 이벤트를 전달한다. */}
-                {options.map(option => (
-                  <Dropdown.Menu.Item
-                    key={option.id}
-                    label={option.label}
-                    description={option.description}
-                    disabled={option.disabled}
-                    left={option.left}
-                    right={option.right}
-                    multiple={Boolean(option.multiple)}
-                    isSelected={resolvedSelectedIds.includes(option.id)}
-                    onSelect={event => {
-                      if (option.disabled) {
-                        event.preventDefault();
-                        return;
-                      }
-                      handleOptionSelect(option);
-                    }}
-                  />
-                ))}
-              </Dropdown.Menu.List>
-            </Dropdown.Container>
-          ) : null}
+          <Dropdown.Container
+            {...dropdownContainerProps}
+            size={panelSize}
+            width={dropdownWidth}
+          >
+            <Dropdown.Menu.List {...dropdownMenuListProps}>
+              {hasOptions ? (
+                <>
+                  {/* Dropdown menu option들을 그대로 매핑해 선택 이벤트를 전달한다. */}
+                  {options.map(option => (
+                    <Dropdown.Menu.Item
+                      key={option.id}
+                      label={option.label}
+                      description={option.description}
+                      disabled={option.disabled}
+                      left={option.left}
+                      right={option.right}
+                      multiple={Boolean(option.multiple)}
+                      isSelected={resolvedSelectedIds.includes(option.id)}
+                      onSelect={event => {
+                        if (option.disabled) {
+                          event.preventDefault();
+                          return;
+                        }
+                        handleOptionSelect(option);
+                      }}
+                    />
+                  ))}
+                </>
+              ) : (
+                <Dropdown.Menu.Item
+                  // 변경: 사용처 1회 상수 대신 인라인 fallback으로 empty label을 처리한다.
+                  label={alt ?? "선택할 항목이 없습니다."}
+                  disabled
+                  className="dropdown-menu-alt"
+                />
+              )}
+            </Dropdown.Menu.List>
+          </Dropdown.Container>
         </Dropdown.Root>
       </Container>
     );

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

@@ -8,16 +8,24 @@ import { SelectIcon } from "./Icon";
 import type { SelectTriggerBaseProps } from "../../types/trigger";
 
 /**
- * Select trigger foundation; priority/size/state를 data attribute로 노출하고
- * Chevron 아이콘을 자동 연결하는 기본 요소다.
+ * Select Foundation; Trigger Base 슬롯 렌더링 컴포넌트
  * @component
  * @param {SelectTriggerBaseProps} props trigger base props
  * @param {"primary" | "secondary"} [props.priority="primary"] 스타일 우선순위
  * @param {"small" | "medium" | "large"} [props.size="medium"] 높이 스케일
  * @param {"default" | "focused" | "disabled"} [props.state="default"] 시각 상태
- * @param {boolean} [props.multiple] multi select 여부
+ * @param {boolean} [props.open=false] dropdown open 상태
+ * @param {boolean} [props.block=false] block 레이아웃 여부
+ * @param {boolean} [props.multiple=false] multi select 여부
+ * @param {boolean} [props.disabled=false] disabled 여부
  * @param {ElementType} [props.as="button"] polymorphic 태그
  * @param {"button" | "submit" | "reset"} [props.buttonType="button"] native button type
+ * @param {string} [props.className] trigger className
+ * @param {React.ReactNode} props.children trigger 콘텐츠
+ * @example
+ * <SelectTriggerBase open={false} size="medium">
+ *   <span>옵션 선택</span>
+ * </SelectTriggerBase>
  */
 const SelectTriggerBase = forwardRef<HTMLElement, SelectTriggerBaseProps>(
   (

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

@@ -1,6 +1,7 @@
 "use client";
 
 import clsx from "clsx";
+import { forwardRef } from "react";
 
 import type { SelectContainerProps } from "../../types/props";
 import {
@@ -14,40 +15,42 @@ import {
  * @param {SelectContainerProps} props Select container props
  * @param {string} [props.className] 사용자 정의 className
  * @param {boolean} [props.block] wrapper 전체 폭 확장 여부
+ * @param {FormFieldWidth} [props.width] Form.Field width preset
+ * @param {CSSProperties} [props.style] wrapper inline style
  * @param {React.ReactNode} props.children trigger 및 dropdown 콘텐츠
  */
-export default function SelectContainer({
-  className,
-  children,
-  block = false,
-  width,
-  style,
-  ...restProps
-}: SelectContainerProps) {
-  const widthAttr =
-    width !== undefined
-      ? getFormFieldWidthAttr(width)
-      : block
-        ? "full"
-        : undefined;
-  const widthValue =
-    width !== undefined ? getFormFieldWidthValue(width) : undefined;
-  const mergedStyle =
-    widthValue !== undefined
-      ? { ...(style ?? {}), ["--select-width" as const]: widthValue }
-      : style;
+const SelectContainer = forwardRef<HTMLDivElement, SelectContainerProps>(
+  ({ className, children, block = false, width, style, ...restProps }, ref) => {
+    const widthAttr =
+      width !== undefined
+        ? getFormFieldWidthAttr(width)
+        : block
+          ? "full"
+          : undefined;
+    const widthValue =
+      width !== undefined ? getFormFieldWidthValue(width) : undefined;
+    const mergedStyle =
+      widthValue !== undefined
+        ? { ...(style ?? {}), ["--select-width" as const]: widthValue }
+        : style;
 
-  return (
-    <div
-      className={clsx("select select-container", className, {
-        "select-block": block,
-      })}
-      data-width={widthAttr}
-      style={mergedStyle}
-      {...restProps}
-    >
-      {/** dropdown root 및 dropdown menu 등 포함 예정 */}
-      {children}
-    </div>
-  );
-}
+    return (
+      <div
+        ref={ref}
+        className={clsx("select select-container", className, {
+          "select-block": block,
+        })}
+        data-width={widthAttr}
+        style={mergedStyle}
+        {...restProps}
+      >
+        {/** dropdown root 및 dropdown menu 등 포함 예정 */}
+        {children}
+      </div>
+    );
+  },
+);
+
+SelectContainer.displayName = "SelectContainer";
+
+export default SelectContainer;

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

@@ -17,13 +17,27 @@ import { useSelectDropdownOpenState } from "../../hooks";
  * @component
  * @param {SelectMultipleComponentProps} props multi trigger props
  * @param {SelectMultipleTag[]} [props.tags] 선택된 tag 리스트
+ * @param {SelectDropdownOption[]} [props.options] dropdown option 목록
+ * @param {string[]} [props.selectedOptionIds] 선택된 option id 리스트
+ * @param {(option: SelectDropdownOption) => void} [props.onOptionSelect] option 선택 콜백
  * @param {React.ReactNode} [props.displayLabel] fallback 라벨
  * @param {React.ReactNode} [props.placeholder] placeholder 텍스트
  * @param {"primary" | "secondary"} [props.priority="primary"] priority scale
  * @param {"small" | "medium" | "large"} [props.size="medium"] size scale
+ * @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 {"small" | "medium" | "large"} [props.dropdownSize] dropdown panel size
+ * @param {"match" | "fit-content" | "max-content" | string | number} [props.dropdownWidth="match"] dropdown panel width
+ * @param {Omit<DropdownMenuProps, "open" | "defaultOpen" | "onOpenChange">} [props.dropdownRootProps] Dropdown.Root 전달 props
+ * @param {Omit<DropdownContainerProps, "children" | "size" | "width">} [props.dropdownContainerProps] Dropdown.Container 전달 props
+ * @param {DropdownMenuListProps} [props.dropdownMenuListProps] Dropdown.Menu.List 전달 props
+ * @param {ReactNode} [props.alt] empty 상태 대체 콘텐츠
+ * @param {boolean} [props.open] controlled open 상태
+ * @param {boolean} [props.defaultOpen] uncontrolled 초기 open 상태
+ * @param {(open: boolean) => void} [props.onOpenChange] open 상태 변경 콜백
  */
 const SelectMultipleTrigger = forwardRef<
   HTMLElement,
@@ -50,6 +64,7 @@ const SelectMultipleTrigger = forwardRef<
       dropdownRootProps,
       dropdownContainerProps,
       dropdownMenuListProps,
+      alt,
       open,
       defaultOpen,
       onOpenChange,
@@ -100,10 +115,10 @@ const SelectMultipleTrigger = forwardRef<
       defaultOpen,
       onOpenChange,
     });
-    // multi select에서도 동일한 open 상태를 유지하기 위해 공통 hook을 사용한다.
+    // 변경: outside close는 Radix onOpenChange 기본 동작을 사용한다.
 
     const panelSize = (dropdownSize ?? size) as DropdownSize;
-    const shouldRenderDropdown = options.length > 0;
+    const hasOptions = options.length > 0;
     const MAX_VISIBLE_TAGS = 3;
     const visibleTags = hasTags ? derivedTags.slice(0, MAX_VISIBLE_TAGS) : [];
     const overflowCount = hasTags
@@ -166,36 +181,45 @@ const SelectMultipleTrigger = forwardRef<
               )}
             </SelectTriggerBase>
           </Dropdown.Trigger>
-          {shouldRenderDropdown ? (
-            <Dropdown.Container
-              {...dropdownContainerProps}
-              size={panelSize}
-              width={dropdownWidth}
-            >
-              <Dropdown.Menu.List {...dropdownMenuListProps}>
-                {/* multi select 전용 옵션을 Dropdown.Menu.Item으로 노출한다. */}
-                {options.map(option => (
-                  <Dropdown.Menu.Item
-                    key={option.id}
-                    label={option.label}
-                    description={option.description}
-                    disabled={option.disabled}
-                    left={option.left}
-                    right={option.right}
-                    multiple
-                    isSelected={resolvedSelectedIds.includes(option.id)}
-                    onSelect={event => {
-                      if (option.disabled) {
-                        event.preventDefault();
-                        return;
-                      }
-                      onOptionSelect?.(option);
-                    }}
-                  />
-                ))}
-              </Dropdown.Menu.List>
-            </Dropdown.Container>
-          ) : null}
+          <Dropdown.Container
+            {...dropdownContainerProps}
+            size={panelSize}
+            width={dropdownWidth}
+          >
+            <Dropdown.Menu.List {...dropdownMenuListProps}>
+              {hasOptions ? (
+                <>
+                  {/* multi select 전용 옵션을 Dropdown.Menu.Item으로 노출한다. */}
+                  {options.map(option => (
+                    <Dropdown.Menu.Item
+                      key={option.id}
+                      label={option.label}
+                      description={option.description}
+                      disabled={option.disabled}
+                      left={option.left}
+                      right={option.right}
+                      multiple
+                      isSelected={resolvedSelectedIds.includes(option.id)}
+                      onSelect={event => {
+                        if (option.disabled) {
+                          event.preventDefault();
+                          return;
+                        }
+                        onOptionSelect?.(option);
+                      }}
+                    />
+                  ))}
+                </>
+              ) : (
+                <Dropdown.Menu.Item
+                  // 변경: 사용처 1회 상수 대신 인라인 fallback으로 empty label을 처리한다.
+                  label={alt ?? "선택할 항목이 없습니다."}
+                  disabled
+                  className="dropdown-menu-alt"
+                />
+              )}
+            </Dropdown.Menu.List>
+          </Dropdown.Container>
         </Dropdown.Root>
       </Container>
     );

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

@@ -6,13 +6,16 @@ import RemoveIcon from "../../img/remove.svg";
 import type { SelectMultipleChipProps } from "../../types/multiple";
 
 /**
- * Select multi chip; 선택된 값을 chip 형태로 표시하고 필요 시 제거 버튼을 노출한다.
+ * Select Markup; Multiple 선택값 Chip 렌더링 컴포넌트
  * @component
  * @param {SelectMultipleChipProps} props chip props
  * @param {React.ReactNode} props.label chip 라벨
  * @param {React.ReactNode} [props.suffix] 라벨 뒤에 붙는 서브 라벨
- * @param {boolean} [props.removable] remove 버튼 노출 여부
+ * @param {boolean} [props.removable=true] remove 버튼 노출 여부
  * @param {() => void} [props.onRemove] remove 클릭 핸들러
+ * @param {"value" | "summary"} [props.kind="value"] chip 용도 구분
+ * @example
+ * <SelectMultipleSelectedChip label="Apple" removable onRemove={() => {}} />
  */
 export function SelectMultipleSelectedChip({
   label,

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

@@ -1,5 +1,6 @@
 export type * from "./base";
 export type * from "./icon";
+export type * from "./interaction";
 export type * from "./props";
 export type * from "./trigger";
 export type * from "./multiple";

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

@@ -0,0 +1,30 @@
+import type { SelectDropdownBehaviorProps } from "./props";
+
+/**
+ * Select Hook Types; Dropdown open state hook 입력 파라미터
+ * @property {boolean} [open] 외부 제어형 open 상태
+ * @property {boolean} [defaultOpen] 비제어형 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open 상태 변경 콜백
+ */
+export interface UseSelectDropdownOpenStateParams extends SelectDropdownBehaviorProps {}
+
+/**
+ * Select Hook Types; Dropdown open state hook 반환값
+ * @property {boolean} open 최종 open 상태
+ * @property {(nextOpen: boolean) => void} setOpen open 상태 업데이트 함수
+ * @property {boolean} isControlled open prop 기반 제어형 여부
+ */
+export interface UseSelectDropdownOpenStateReturn {
+  /**
+   * 최종 open 상태
+   */
+  open: boolean;
+  /**
+   * open 상태 업데이트 함수
+   */
+  setOpen: (nextOpen: boolean) => void;
+  /**
+   * open prop 기반 제어형 여부
+   */
+  isControlled: boolean;
+}

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

@@ -1,13 +1,87 @@
 import type { ReactNode } from "react";
 
 /**
- * Select option 값 타입
+ * Select option value 타입
  * @typedef {string | number} SelectOptionValue
  */
 export type SelectOptionValue = string | number;
 
 /**
- * Select option 데이터 구조; legacy SelectDataType과 호환되는 구조다.
+ * Select option data; form 상태와 직결되는 데이터 계약
+ * @property {string} id 렌더링/선택 추적용 고유 id
+ * @property {SelectOptionValue} value 실제 form value
+ * @property {ReactNode} label 사용자 노출 라벨
+ * @property {boolean} [disabled] 비활성 여부
+ * @property {OptionData} [data] 추가 데이터 payload
+ */
+export interface SelectOptionData<OptionData = unknown> {
+  /**
+   * 렌더링/선택 추적용 고유 id
+   */
+  id: string;
+  /**
+   * 실제 form value
+   */
+  value: SelectOptionValue;
+  /**
+   * 사용자 노출 라벨
+   */
+  label: ReactNode;
+  /**
+   * 비활성 여부
+   */
+  disabled?: boolean;
+  /**
+   * 추가 데이터 payload
+   */
+  data?: OptionData;
+}
+
+/**
+ * Select option render data; Dropdown.Menu.Item 렌더링 보조 정보
+ * @property {ReactNode} [description] 보조 텍스트
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
+ * @property {boolean} [multiple] multi select 스타일 여부
+ */
+export interface SelectOptionRenderData {
+  /**
+   * 보조 텍스트
+   */
+  description?: ReactNode;
+  /**
+   * 좌측 콘텐츠
+   */
+  left?: ReactNode;
+  /**
+   * 우측 콘텐츠
+   */
+  right?: ReactNode;
+  /**
+   * multi select 스타일 여부
+   */
+  multiple?: boolean;
+}
+
+/**
+ * Select dropdown option; data 계약과 render 계약을 합쳐 Select 입력 모델을 구성한다.
+ * @extends SelectOptionData
+ * @extends SelectOptionRenderData
+ * @property {string} id 렌더링/선택 추적용 고유 id
+ * @property {SelectOptionValue} value 실제 form value
+ * @property {ReactNode} label 사용자 노출 라벨
+ * @property {boolean} [disabled] 비활성 여부
+ * @property {OptionData} [data] 추가 데이터 payload
+ * @property {ReactNode} [description] 보조 텍스트
+ * @property {ReactNode} [left] 좌측 콘텐츠
+ * @property {ReactNode} [right] 우측 콘텐츠
+ * @property {boolean} [multiple] multi select 스타일 여부
+ */
+export interface SelectDropdownOption<OptionData = unknown>
+  extends SelectOptionData<OptionData>, SelectOptionRenderData {}
+
+/**
+ * Select legacy option 데이터 구조; 과거 key/optionName 스키마 호환을 위해 유지한다.
  * @property {string} key 렌더링 키
  * @property {SelectOptionValue} value 실제 값
  * @property {ReactNode} optionName 사용자 노출 라벨
@@ -15,7 +89,7 @@ export type SelectOptionValue = string | number;
  * @property {boolean} [disabled] 비활성 여부
  * @property {OptionData} [data] 추가 데이터 payload
  */
-export interface SelectOption<OptionData = unknown> {
+export interface SelectLegacyOption<OptionData = unknown> {
   /**
    * 렌더링 키
    */

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

@@ -1,14 +1,14 @@
 import type { HTMLAttributes, ReactNode } from "react";
+import type { DropdownMenuProps } from "@radix-ui/react-dropdown-menu";
 
 import type {
   DropdownContainerProps,
   DropdownMenuListProps,
   DropdownPanelWidth,
-  DropdownRootProps,
-  DropdownTemplateItem,
 } from "../../dropdown/types";
 import type { FormFieldWidth } from "../../form/types";
 import type { SelectPriority, SelectSize, SelectState } from "./base";
+import type { SelectDropdownOption } from "./option";
 import type {
   SelectTriggerDefaultProps,
   SelectTriggerMultipleProps,
@@ -116,18 +116,22 @@ 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 option; Dropdown.Template item 계약을 그대로 따른다.
- * @extends DropdownTemplateItem
- */
-export interface SelectDropdownOption extends DropdownTemplateItem {}
-
 /**
  * Select dropdown 옵션 구성 props
  * @property {SelectDropdownOption[]} [options] dropdown option 리스트
@@ -135,9 +139,10 @@ export interface SelectDropdownOption extends DropdownTemplateItem {}
  * @property {(option: SelectDropdownOption) => void} [onOptionSelect] option 선택 콜백
  * @property {SelectSize} [dropdownSize] dropdown surface size 스케일
  * @property {DropdownPanelWidth} [dropdownWidth="match"] dropdown panel width 옵션
- * @property {DropdownRootProps} [dropdownRootProps] Dropdown.Root 전달 props(제어 props 제외)
+ * @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 콘텐츠
  */
 export interface SelectDropdownConfigProps {
   /**
@@ -162,9 +167,10 @@ export interface SelectDropdownConfigProps {
   dropdownWidth?: DropdownPanelWidth;
   /**
    * Dropdown.Root 전달 props(제어 props 제외)
+   * - 타입 출처를 명확히 하기 위해 Radix 원본 타입을 직접 사용한다.
    */
   dropdownRootProps?: Omit<
-    DropdownRootProps,
+    DropdownMenuProps,
     "open" | "defaultOpen" | "onOpenChange"
   >;
   /**
@@ -178,6 +184,10 @@ export interface SelectDropdownConfigProps {
    * Dropdown.Menu.List 전달 props
    */
   dropdownMenuListProps?: DropdownMenuListProps;
+  /**
+   * option이 비어 있을 때 렌더링할 alternate 콘텐츠
+   */
+  alt?: ReactNode;
 }
 
 /**
@@ -203,26 +213,62 @@ export interface SelectDropdownBehaviorProps {
 
 /**
  * Select.Default 컴포넌트 props
- * @extends SelectTriggerDefaultProps
- * @extends SelectDropdownConfigProps
- * @extends SelectDropdownBehaviorProps
+ * @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} [disabled] disabled 여부
+ * @property {SelectTriggerButtonType} [buttonType] button type
+ * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {SelectDropdownOption[]} [options] dropdown option 리스트
+ * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
+ * @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 {boolean} [open] dropdown open 상태
+ * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
  */
-export interface SelectDefaultComponentProps
-  extends
-    SelectTriggerDefaultProps,
-    SelectDropdownConfigProps,
-    SelectDropdownBehaviorProps,
-    SelectWidthOption {}
+export type SelectDefaultComponentProps = SelectTriggerDefaultProps &
+  SelectDropdownConfigProps &
+  SelectDropdownBehaviorProps &
+  SelectWidthOption;
 
 /**
  * Select.Multiple 컴포넌트 props
- * @extends SelectTriggerMultipleProps
- * @extends SelectDropdownConfigProps
- * @extends SelectDropdownBehaviorProps
+ * @typedef {SelectTriggerMultipleProps & SelectDropdownConfigProps & SelectDropdownBehaviorProps & SelectWidthOption} SelectMultipleComponentProps
+ * @property {ReactNode} [displayLabel] 선택된 라벨
+ * @property {ReactNode} [placeholder] placeholder 텍스트
+ * @property {SelectMultipleTag[]} [tags] multi select tag 리스트
+ * @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} [disabled] disabled 여부
+ * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {SelectDropdownOption[]} [options] dropdown option 리스트
+ * @property {string[]} [selectedOptionIds] 선택된 option id 리스트
+ * @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 {boolean} [open] dropdown open 상태
+ * @property {boolean} [defaultOpen] uncontrolled 초기 open 상태
+ * @property {(open: boolean) => void} [onOpenChange] open state change 콜백
  */
-export interface SelectMultipleComponentProps
-  extends
-    SelectTriggerMultipleProps,
-    SelectDropdownConfigProps,
-    SelectDropdownBehaviorProps,
-    SelectWidthOption {}
+export type SelectMultipleComponentProps = SelectTriggerMultipleProps &
+  SelectDropdownConfigProps &
+  SelectDropdownBehaviorProps &
+  SelectWidthOption;