@uniai-fe/uds-primitives 0.2.8 → 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.8",
+  "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

@@ -7,11 +7,18 @@ import type { ReactNode } from "react";
 import { DropdownProvider } from "./Provider";
 
 /**
- * Dropdown root; Provider와 Radix Root를 래핑한다.
+ * Dropdown Foundation; Root Provider 래핑 컴포넌트
  * @component
  * @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,

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

@@ -8,10 +8,16 @@ import { mergeRefs } from "../../utils";
 import { useDropdownContext } from "./Provider";
 
 /**
- * Dropdown trigger; trigger ref를 context에 공유한다.
+ * Dropdown Foundation; Trigger ref 공유 컴포넌트
  * @component
  * @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, DropdownMenuTriggerProps>(
   ({ asChild = true, children, ...rest }, ref) => {

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/props.ts

@@ -138,6 +138,7 @@ export interface DropdownTemplateItem {
  * @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;
@@ -159,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

@@ -22,7 +22,18 @@ import type { SelectDefaultComponentProps } from "../types/props";
  * @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>(
   (
@@ -46,6 +57,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       dropdownRootProps,
       dropdownContainerProps,
       dropdownMenuListProps,
+      alt,
       open,
       defaultOpen,
       onOpenChange,
@@ -71,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);
@@ -79,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
@@ -113,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/props.ts

@@ -142,6 +142,7 @@ export type SelectProps = SelectStyleOptions &
  * @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 {
   /**
@@ -183,6 +184,10 @@ export interface SelectDropdownConfigProps {
    * Dropdown.Menu.List 전달 props
    */
   dropdownMenuListProps?: DropdownMenuListProps;
+  /**
+   * option이 비어 있을 때 렌더링할 alternate 콘텐츠
+   */
+  alt?: ReactNode;
 }
 
 /**
@@ -227,6 +232,7 @@ export interface SelectDropdownBehaviorProps {
  * @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 콜백
@@ -257,6 +263,7 @@ export type SelectDefaultComponentProps = SelectTriggerDefaultProps &
  * @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 콜백