@uniai-fe/uds-primitives 0.2.8 → 0.2.10

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

@@ -10,7 +10,7 @@ import type { FormFieldWidth } from "../../form/types/props";
 /**
  * input; priority option
  */
-export type InputPriority = "primary" | "secondary" | "tertiary";
+export type InputPriority = "primary" | "secondary" | "tertiary" | "table";
 /**
  * input; size option
  */
@@ -34,6 +34,7 @@ export const INPUT_PRIORITIES: InputPriority[] = [
   "primary",
   "secondary",
   "tertiary",
+  "table",
 ];
 /**
  * size 축은 높이/타이포/spacing을 결정한다.
@@ -56,11 +57,11 @@ type NativeInputProps = ComponentPropsWithoutRef<"input">;
 
 /**
  * input; icon options
- * @property {React.ReactNode} [left] input 왼쪽 컨텐츠
- * @property {React.ReactNode} [right] input 오른쪽 컨텐츠
- * @property {React.ReactNode} [clear] input reset버튼 커스텀 컨텐츠
- * @property {React.ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
- * @property {React.ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
+ * @property {ReactNode} [left] input 왼쪽 컨텐츠
+ * @property {ReactNode} [right] input 오른쪽 컨텐츠
+ * @property {ReactNode} [clear] input reset버튼 커스텀 컨텐츠
+ * @property {ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
+ * @property {ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
  */
 export interface InputIcon {
   /**
@@ -95,12 +96,13 @@ export interface InputIcon {
  * @property {string} [inputClassName]
  * @property {string} [boxClassName]
  * @property {UseFormRegisterReturn} [register]
- * @property {React.ReactNode} [left] input 왼쪽 컨텐츠
- * @property {React.ReactNode} [right] input 오른쪽 컨텐츠
- * @property {React.ReactNode} [clear] input reset버튼 커스텀 컨텐츠
- * @property {React.ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
- * @property {React.ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
+ * @property {ReactNode} [left] input 왼쪽 컨텐츠
+ * @property {ReactNode} [right] input 오른쪽 컨텐츠
+ * @property {ReactNode} [clear] input reset버튼 커스텀 컨텐츠
+ * @property {ReactNode} [success] input 입력상태 성공시 커스텀 컨텐츠
+ * @property {ReactNode} [error] input 입력상태 에러시 커스텀 컨텐츠
  * @property {FormFieldWidth} [width] width preset 옵션
+ * @property {InputState} [data-simulated-state] Storybook 시각 상태 강제용
  */
 export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
   /**
@@ -147,6 +149,7 @@ export interface InputProps extends Omit<NativeInputProps, "size">, InputIcon {
  * @property {ReactNode} [clear] clear 버튼 아이콘
  * @property {ReactNode} [success] success 상태 아이콘
  * @property {ReactNode} [error] error 상태 아이콘
+ * @property {InputPriority} priority input priority
  * @property {InputState} state 현재 상태
  * @property {boolean} isDisabled disabled 여부
  * @property {boolean} isFocused focus 여부
@@ -171,6 +174,10 @@ export interface InputUtilityProps {
    * error 상태 아이콘
    */
   error?: ReactNode;
+  /**
+   * priority 축
+   */
+  priority: InputPriority;
   /**
    * 현재 input 상태
    */

package/src/components/input/utils/date.ts

@@ -51,7 +51,21 @@ export const serializeCalendarValue = (value: CalendarValue) => value ?? "";
  * @param {CalendarValue} value 현재 값
  * @returns {string} 표시 문자열
  */
-export const formatTriggerValue = (value: CalendarValue) => value ?? "";
+export const formatTriggerValue = (
+  value: CalendarValue,
+  format = DATE_FORMAT,
+) => {
+  if (!value) {
+    return "";
+  }
+
+  const parsed = dayjs(value);
+  if (!parsed.isValid()) {
+    return value;
+  }
+
+  return parsed.format(format);
+};
 
 /**
  * columns 값을 Mantine numberOfColumns와 맞춘다.

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

@@ -18,11 +18,22 @@ import type { SelectDefaultComponentProps } from "../types/props";
  * @param {SelectDropdownOption[]} [props.options] dropdown option 목록
  * @param {string[]} [props.selectedOptionIds] 선택된 option id 리스트
  * @param {(option: SelectDropdownOption) => void} [props.onOptionSelect] option 선택 콜백
- * @param {"primary" | "secondary"} [props.priority="primary"] priority 스케일
+ * @param {"primary" | "secondary" | "table"} [props.priority="primary"] priority 스케일
  * @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,
@@ -53,6 +65,9 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
     },
     ref,
   ) => {
+    // 변경: table priority는 width 미지정 시 기본 full width를 사용한다.
+    const resolvedBlock =
+      block || (priority === "table" && width === undefined);
     const resolvedSelectedIds = selectedOptionIds ?? [];
 
     const resolvedDisplayLabel =
@@ -71,7 +86,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
       defaultOpen,
       onOpenChange,
     });
-    // Dropdown open 상태를 trigger data-state와 동기화한다.
+    // 변경: outside close는 Radix onOpenChange 기본 동작을 사용한다.
 
     const handleOptionSelect = (option: SelectDropdownOption) => {
       onOptionSelect?.(option);
@@ -79,12 +94,12 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
     };
 
     const panelSize = (dropdownSize ?? size) as DropdownSize;
-    const shouldRenderDropdown = options.length > 0;
+    const hasOptions = options.length > 0;
 
     return (
       <Container
         className={clsx("select-trigger-container", className)}
-        block={block}
+        block={resolvedBlock}
         width={width}
       >
         <Dropdown.Root
@@ -100,7 +115,7 @@ const SelectDefault = forwardRef<HTMLElement, SelectDefaultComponentProps>(
               priority={priority}
               size={size}
               state={disabled ? "disabled" : state}
-              block={block}
+              block={resolvedBlock}
               open={dropdownOpen}
               disabled={disabled}
               buttonType={buttonType}
@@ -113,36 +128,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 {"primary" | "secondary" | "table"} [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/foundation/Icon.tsx

@@ -41,10 +41,13 @@ const SelectChevronSecondaryIcon: SelectIconSizeMap = {
  * Select; Chevron 아이콘 컬렉션
  * - primary (small, medium, large)
  * - secondary (small, medium, large)
+ * - table (small, medium, large)
  */
 const SelectChevronIcon: SelectIconPriorityMap = {
   primary: SelectChevronPrimaryIcon,
   secondary: SelectChevronSecondaryIcon,
+  // 변경: table priority는 secondary chevron 자산을 재사용한다.
+  table: SelectChevronSecondaryIcon,
 };
 
 /**
@@ -61,10 +64,12 @@ const SelectMultipleRemoveIcon: SelectIconSizeMap = {
 
 /**
  * Select; Remove 아이콘 컬렉션
- * - primary (small, medium, large)
+ * - primary/secondary/table (small, medium, large)
  */
 const SelectRemoveIcon: SelectIconRemovePriorityMap = {
   primary: SelectMultipleRemoveIcon,
+  secondary: SelectMultipleRemoveIcon,
+  table: SelectMultipleRemoveIcon,
 };
 
 /**

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 {"primary" | "secondary" | "table"} [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,
@@ -57,6 +72,9 @@ const SelectMultipleTrigger = forwardRef<
     },
     ref,
   ) => {
+    // 변경: table priority는 width 미지정 시 기본 full width를 사용한다.
+    const resolvedBlock =
+      block || (priority === "table" && width === undefined);
     // hook dependency 안정화를 위해 memoized selected id 배열을 유지한다.
     const resolvedSelectedIds = useMemo(
       () => selectedOptionIds ?? [],
@@ -100,10 +118,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
@@ -113,7 +131,7 @@ const SelectMultipleTrigger = forwardRef<
     return (
       <Container
         className={clsx("select-trigger-multiple", className)}
-        block={block}
+        block={resolvedBlock}
         width={width}
       >
         <Dropdown.Root
@@ -129,7 +147,7 @@ const SelectMultipleTrigger = forwardRef<
               priority={priority}
               size={size}
               state={disabled ? "disabled" : state}
-              block={block}
+              block={resolvedBlock}
               open={dropdownOpen}
               multiple
               disabled={disabled}
@@ -166,36 +184,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>
     );