@uniai-fe/uds-primitives 0.9.3 → 0.10.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.9.3",
+  "version": "0.10.1",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -66,7 +66,7 @@
     "@radix-ui/react-checkbox": "^1.3.3",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
     "@radix-ui/react-popover": "^1.1.15",
-    "@radix-ui/react-radio-group": "^1.3.8",
+    "@radix-ui/react-radio-group": "^1.4.1",
     "@radix-ui/react-tabs": "^1.1.13",
     "@radix-ui/react-tooltip": "^1.2.8",
     "@radix-ui/react-visually-hidden": "^1.2.4",
@@ -79,19 +79,19 @@
     "@mantine/dates": "^8.3.18",
     "@mantine/hooks": "^8.3.18",
     "@svgr/webpack": "^8.1.0",
-    "@types/node": "^24.12.3",
+    "@types/node": "^24.13.2",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "eslint": "^9.39.2",
-    "prettier": "^3.8.4",
-    "react-hook-form": "^7.80.0",
+    "eslint": "^9.39.4",
+    "prettier": "^3.8.5",
+    "react-hook-form": "^7.81.0",
     "sass": "^1.101.0",
     "typescript": "6.0.3",
-    "@uniai-fe/eslint-config": "0.2.0",
-    "@uniai-fe/next-devkit": "0.3.0",
+    "@uniai-fe/eslint-config": "0.4.1",
     "@uniai-fe/uds-foundation": "0.5.0",
+    "@uniai-fe/util-functions": "0.4.3",
     "@uniai-fe/tsconfig": "0.2.0",
-    "@uniai-fe/util-functions": "0.4.1"
+    "@uniai-fe/next-devkit": "0.4.0"
   },
   "scripts": {
     "check:pre-commit": "pnpm --dir ../../.. run check:pre-commit",

package/src/components/calendar/markup/Core.tsx

@@ -5,7 +5,7 @@ import {
   DatesProvider,
   type DateStringValue,
 } from "@mantine/dates";
-import { useEffect, useState } from "react";
+import { useState } from "react";
 import { dayjs } from "../../../init/dayjs";
 import { CalendarIcon } from "./Icon";
 import type { CalendarDatePickerProps, CalendarGridProps } from "../types";
@@ -43,16 +43,23 @@ export default function CalendarCore({
   void valueFormat;
 
   const isDisplayedDateControlled = date !== undefined;
-  const [displayedDate, setDisplayedDate] = useState<Date | DateStringValue>(
-    () => date ?? mapValueToPicker(value) ?? defaultDate ?? new Date(),
-  );
+  const [displayedDateState, setDisplayedDateState] = useState(() => ({
+    defaultDate,
+    displayedDate: date ?? mapValueToPicker(value) ?? defaultDate ?? new Date(),
+    value,
+  }));
 
-  useEffect(() => {
-    if (isDisplayedDateControlled) {
-      return;
-    }
-    setDisplayedDate(mapValueToPicker(value) ?? defaultDate ?? new Date());
-  }, [defaultDate, isDisplayedDateControlled, value]);
+  if (
+    !isDisplayedDateControlled &&
+    (displayedDateState.value !== value ||
+      displayedDateState.defaultDate !== defaultDate)
+  ) {
+    setDisplayedDateState({
+      defaultDate,
+      displayedDate: mapValueToPicker(value) ?? defaultDate ?? new Date(),
+      value,
+    });
+  }
 
   // 기본 DatePicker 옵션/스타일 책임을 Calendar.Core에 고정한다.
   const resolvedDatePickerProps = {
@@ -101,7 +108,10 @@ export default function CalendarCore({
 
   const handleDateChange = (nextDate: DateStringValue) => {
     if (!isDisplayedDateControlled) {
-      setDisplayedDate(nextDate);
+      setDisplayedDateState(previousState => ({
+        ...previousState,
+        displayedDate: nextDate,
+      }));
     }
     onDateChange?.(nextDate);
   };
@@ -124,7 +134,7 @@ export default function CalendarCore({
         value={mapValueToPicker(value) as never}
         onChange={handleChange as never}
         {...resolvedDatePickerProps}
-        date={date ?? displayedDate}
+        date={date ?? displayedDateState.displayedDate}
         onDateChange={handleDateChange}
       />
     </DatesProvider>

package/src/components/carousel/hooks/useContext.ts

@@ -183,6 +183,9 @@ export const useCarouselProviderController = ({
       setCurrentIndex(previousIndex =>
         Math.min(previousIndex, Math.max(normalizedCount - visibleCount, 0)),
       );
+      setFocusIndexState(previousFocusIndex =>
+        Math.min(previousFocusIndex, Math.max(normalizedCount - 1, 0)),
+      );
     },
     [visibleCount],
   );
@@ -234,11 +237,6 @@ export const useCarouselProviderController = ({
     );
   }, [fixedVisibleCount, itemCount]);
 
-  useEffect(() => {
-    // item 수/폭 조건 변화 시 visibleCount를 재계산한다.
-    updateVisibleCount();
-  }, [updateVisibleCount, itemCount]);
-
   useEffect(() => {
     /**
      * ResizeObserver effect
@@ -502,13 +500,6 @@ export const useCarouselProviderController = ({
     }
   }, [currentIndex, onIndexChange]);
 
-  useEffect(() => {
-    // 아이템 수 감소 시 focusIndex 범위를 보정한다.
-    setFocusIndexState(previousFocusIndex =>
-      Math.min(previousFocusIndex, Math.max(itemCount - 1, 0)),
-    );
-  }, [itemCount]);
-
   useEffect(() => {
     // 상태 변화마다 edge를 재평가해 버튼 disabled 오차를 줄인다.
     syncScrollEdgeState();

package/src/components/carousel/markup/Track.tsx

@@ -32,17 +32,18 @@ const CarouselTrack = ({
   itemClassName,
   ...restProps
 }: CarouselTrackProps) => {
-  const carousel = useCarousel();
+  const { focusIndex, registerItemCount, trackRef, viewportRef } =
+    useCarousel();
   const childArray = Children.toArray(children);
   const itemCount = childArray.length;
 
   useEffect(() => {
     // track에 렌더된 panel 개수를 Provider에 등록한다.
-    carousel.registerItemCount(itemCount);
-  }, [carousel, itemCount]);
+    registerItemCount(itemCount);
+  }, [itemCount, registerItemCount]);
 
   const enhancedChildren = childArray.map((child, index) => {
-    const isFocused = index === carousel.focusIndex;
+    const isFocused = index === focusIndex;
     const itemProps = {
       className: clsx("carousel-item", itemClassName),
       "data-carousel-index": index,
@@ -68,13 +69,10 @@ const CarouselTrack = ({
   return (
     <div
       className={clsx("carousel-viewport", className)}
-      ref={carousel.viewportRef}
+      ref={viewportRef}
       {...restProps}
     >
-      <ul
-        className={clsx("carousel-track", trackClassName)}
-        ref={carousel.trackRef}
-      >
+      <ul className={clsx("carousel-track", trackClassName)} ref={trackRef}>
         {enhancedChildren}
       </ul>
     </div>

package/src/components/drawer/markup/Drawer.tsx

@@ -1,15 +1,22 @@
 import { VisuallyHidden } from "@radix-ui/react-visually-hidden";
 import clsx from "clsx";
 import {
+  Component,
   forwardRef,
   useCallback,
   useEffect,
   useMemo,
   useRef,
   useState,
+  useSyncExternalStore,
 } from "react";
 import { createPortal } from "react-dom";
-import type { CSSProperties } from "react";
+import type {
+  ComponentPropsWithoutRef,
+  CSSProperties,
+  ForwardedRef,
+  ReactNode,
+} from "react";
 import CloseIcon from "../img/close.svg";
 import type {
   DrawerContextValue,
@@ -34,6 +41,23 @@ import {
 } from "../utils";
 
 const ANIMATION_DURATION = 320;
+const subscribeToClient = () => () => undefined;
+const getClientSnapshot = () => true;
+const getServerSnapshot = () => false;
+
+interface DrawerButtonLikeProps {
+  asChild?: boolean;
+  buttonProps: ComponentPropsWithoutRef<"button">;
+  buttonRef: ForwardedRef<HTMLButtonElement>;
+  children: ReactNode;
+}
+
+class DrawerButtonLike extends Component<DrawerButtonLikeProps> {
+  override render() {
+    const { asChild, buttonProps, buttonRef, children } = this.props;
+    return renderButtonLike(asChild, children, buttonProps, buttonRef);
+  }
+}
 
 /**
  * DrawerRoot — open 상태/phase를 관리하는 컨텍스트 루트.
@@ -55,7 +79,17 @@ const DrawerRoot = ({
     defaultOpen ?? false,
   );
   const open = isControlled ? (openProp as boolean) : uncontrolledOpen;
-  const [phase, setPhase] = useState<DrawerPhase>(open ? "entered" : "exited");
+  const [phaseState, setPhaseState] = useState(() => ({
+    open,
+    phase: (open ? "entered" : "exited") as DrawerPhase,
+  }));
+  if (phaseState.open !== open) {
+    setPhaseState({
+      open,
+      phase: open ? "entering" : "exiting",
+    });
+  }
+  const phase = phaseState.phase;
   const closeTimerRef = useRef<number | null>(null);
   const enterRafRef = useRef<number | null>(null);
 
@@ -75,9 +109,8 @@ const DrawerRoot = ({
         window.clearTimeout(closeTimerRef.current);
         closeTimerRef.current = null;
       }
-      setPhase("entering");
       enterRafRef.current = window.requestAnimationFrame(() => {
-        setPhase("entered");
+        setPhaseState({ open: true, phase: "entered" });
         enterRafRef.current = null;
       });
       return () => {
@@ -91,9 +124,8 @@ const DrawerRoot = ({
       window.cancelAnimationFrame(enterRafRef.current);
       enterRafRef.current = null;
     }
-    setPhase("exiting");
     closeTimerRef.current = window.setTimeout(() => {
-      setPhase("exited");
+      setPhaseState({ open: false, phase: "exited" });
       closeTimerRef.current = null;
     }, ANIMATION_DURATION);
     return () => {
@@ -142,11 +174,14 @@ const DrawerTrigger = forwardRef<HTMLButtonElement, DrawerTriggerProps>(
   ({ asChild, children, onClick, ...props }, forwardedRef) => {
     const { setOpen } = useDrawerContext();
     const handleClick = composeEventHandlers(onClick, () => setOpen(true));
-    return renderButtonLike(
-      asChild,
-      children,
-      { ...props, onClick: handleClick },
-      forwardedRef,
+    return (
+      <DrawerButtonLike
+        asChild={asChild}
+        buttonProps={{ ...props, onClick: handleClick }}
+        buttonRef={forwardedRef}
+      >
+        {children}
+      </DrawerButtonLike>
     );
   },
 );
@@ -160,12 +195,11 @@ DrawerTrigger.displayName = "DrawerTrigger";
  */
 const DrawerPortal = ({ children }: DrawerPortalProps) => {
   useDrawerContext();
-  const [mounted, setMounted] = useState(false);
-
-  useEffect(() => {
-    setMounted(true);
-    return () => setMounted(false);
-  }, []);
+  const mounted = useSyncExternalStore(
+    subscribeToClient,
+    getClientSnapshot,
+    getServerSnapshot,
+  );
 
   if (!mounted) {
     return null;
@@ -453,11 +487,14 @@ const DrawerClose = forwardRef<HTMLButtonElement, DrawerCloseProps>(
   ({ asChild, children, onClick, ...props }, forwardedRef) => {
     const { setOpen } = useDrawerContext();
     const handleClick = composeEventHandlers(onClick, () => setOpen(false));
-    return renderButtonLike(
-      asChild,
-      children,
-      { ...props, onClick: handleClick },
-      forwardedRef,
+    return (
+      <DrawerButtonLike
+        asChild={asChild}
+        buttonProps={{ ...props, onClick: handleClick }}
+        buttonRef={forwardedRef}
+      >
+        {children}
+      </DrawerButtonLike>
     );
   },
 );

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useEffect, useMemo, useState } from "react";
+import { useMemo, useState } from "react";
 
 import type {
   DropdownTemplateItem,
@@ -82,30 +82,27 @@ const DropdownTemplate = ({
    * - Template은 items[].selected를 초기값으로 받아 내부 상태를 관리한다.
    * - 초기값은 selectedValuesFromItems를 그대로 사용한다.
    */
-  const [uncontrolledSelectedValues, setUncontrolledSelectedValues] = useState<
-    DropdownTemplateValue[]
-  >(() => selectedValuesFromItems);
+  const [selectionState, setSelectionState] = useState(() => ({
+    selectedValues: selectedValuesFromItems,
+    selectedValuesFromItems,
+  }));
 
   /**
    * 4) options(items) 변경 동기화
    * - source of truth를 items[].selected로 고정해 외부 선택 상태를 즉시 반영한다.
    * - single/multiple 정책은 normalizeSelectedValuesByMode로 통일 적용한다.
    */
-  useEffect(() => {
-    setUncontrolledSelectedValues(previousSelectedValues => {
-      const nextSelectedValues = normalizeSelectedValuesByMode(
-        selectedValuesFromItems,
-        isMultiple,
-      );
-
-      // 내용이 동일하면 기존 참조를 재사용해 불필요한 상태 갱신 루프를 차단한다.
-      if (isSameSelectedValueList(previousSelectedValues, nextSelectedValues)) {
-        return previousSelectedValues;
-      }
-
-      return nextSelectedValues;
+  if (
+    !isSameSelectedValueList(
+      selectionState.selectedValuesFromItems,
+      selectedValuesFromItems,
+    )
+  ) {
+    setSelectionState({
+      selectedValues: selectedValuesFromItems,
+      selectedValuesFromItems,
     });
-  }, [isMultiple, selectedValuesFromItems]);
+  }
 
   /**
    * 5) 최종 선택 value 계산
@@ -113,7 +110,7 @@ const DropdownTemplate = ({
    * - 렌더/이벤트/selected 스타일 계산은 이 값만 참조한다.
    */
   const resolvedSelectedValues = normalizeSelectedValuesByMode(
-    uncontrolledSelectedValues,
+    selectionState.selectedValues,
     isMultiple,
   );
   const selectedValueKeySet = useMemo(
@@ -173,7 +170,10 @@ const DropdownTemplate = ({
      * 7-3) 내부 state 업데이트
      * - Template 내부 선택 상태를 즉시 반영한다.
      */
-    setUncontrolledSelectedValues(nextSelectedValues);
+    setSelectionState(previousState => ({
+      ...previousState,
+      selectedValues: nextSelectedValues,
+    }));
 
     /**
      * 7-4) 선택 결과 이벤트(onChange)

package/src/components/input/hooks/useDigitField.ts

@@ -1,6 +1,6 @@
 "use client";
 
-import { ChangeEvent, useCallback, useEffect, useMemo, useState } from "react";
+import { ChangeEvent, useCallback, useMemo, useState } from "react";
 import type { UseDigitFieldOptions, UseDigitFieldResult } from "../types";
 
 /**
@@ -31,18 +31,15 @@ export const useDigitField = ({
     clampDigits(defaultValue ?? ""),
   );
 
-  // uncontrolled 값이 있고 maxLength가 줄어들면 즉시 잘라낸다.
-  useEffect(() => {
-    if (isControlled) {
-      return;
-    }
-    setInnerDigits(prev => clampDigits(prev));
-  }, [clampDigits, isControlled]);
+  const clampedInnerDigits = clampDigits(innerDigits);
+  if (!isControlled && innerDigits !== clampedInnerDigits) {
+    setInnerDigits(clampedInnerDigits);
+  }
 
   const resolvedDigits = useMemo(() => {
-    const target = isControlled ? (value ?? "") : innerDigits;
+    const target = isControlled ? (value ?? "") : clampedInnerDigits;
     return clampDigits(target);
-  }, [clampDigits, innerDigits, isControlled, value]);
+  }, [clampDigits, clampedInnerDigits, isControlled, value]);
 
   const handleDigitsChange = useCallback(
     (event: ChangeEvent<HTMLInputElement>) => {

package/src/components/input/hooks/useInputFileContext.ts

@@ -1,6 +1,13 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from "react";
 import type {
   InputFileEntry,
   InputFileEvent,
@@ -47,11 +54,12 @@ export const useInputFileContext = ({
   initialFiles,
   mergeMode = "append",
 }: UseInputFileContextOptions = {}): UseInputFileContextResult => {
+  const initialEntryId = useId();
   /**
    * Input Hook; File Upload 엔트리 고유 id 시퀀스 ref
    */
   // 파일이 추가될 때마다 증가하는 시퀀스를 유지한다.
-  const entryIdRef = useRef(0);
+  const entryIdRef = useRef(initialFiles?.length ?? 0);
 
   /**
    * Input Hook; File Upload 엔트리 id 생성
@@ -83,13 +91,22 @@ export const useInputFileContext = ({
    * Input Hook; File Upload 엔트리 상태
    */
   const [entries, setEntries] = useState<InputFileEntry[]>(() =>
-    // 초기 렌더에서 initialFiles를 내부 엔트리 형식으로 변환한다.
-    mapFilesToEntries(initialFiles ?? []),
+    // 초기 렌더에서는 ref 기반 id generator를 읽지 않고 useId 기반 key를 만든다.
+    (initialFiles ?? []).map((file, index) => ({
+      id: `${initialEntryId}-${index + 1}`,
+      file,
+    })),
   );
   /**
    * Input Hook; File Upload initialFiles 시그니처 비교 ref
    */
-  const initialFilesSignatureRef = useRef("");
+  const initialFilesSignatureRef = useRef(
+    (initialFiles ?? [])
+      .map(
+        file => `${file.name}-${file.size}-${file.lastModified}-${file.type}`,
+      )
+      .join("|"),
+  );
 
   /**
    * Input Hook; File Upload 파일 전체 교체 핸들러

package/src/components/input/markup/date/Trigger.tsx

@@ -4,7 +4,7 @@ import clsx from "clsx";
 import type {
   ClipboardEvent,
   DragEvent,
-  FormEvent,
+  InputEvent,
   KeyboardEvent,
   MouseEvent,
 } from "react";
@@ -122,7 +122,7 @@ const InputDateTrigger = forwardRef<
       event.preventDefault();
     };
 
-    const handleBeforeInput = (event: FormEvent<HTMLInputElement>) => {
+    const handleBeforeInput = (event: InputEvent<HTMLInputElement>) => {
       if (shouldBlockTyping) {
         event.preventDefault();
       }

package/src/components/radio/markup/RadioCardGroup.tsx

@@ -1,7 +1,7 @@
 import clsx from "clsx";
 import { forwardRef, useState } from "react";
 import * as RadixRadioGroup from "@radix-ui/react-radio-group";
-import type { ElementRef } from "react";
+import type { ComponentRef } from "react";
 import { RadioCard } from "./RadioCard";
 import type { RadioCardGroupProps } from "../types";
 
@@ -23,7 +23,7 @@ const RADIO_CARD_GROUP_CLASSNAME = "radio-card-group";
  * <RadioCardGroup options={[{ id: "farm-1", title: "농장" }]} value="farm-1" />
  */
 const RadioCardGroup = forwardRef<
-  ElementRef<typeof RadixRadioGroup.Root>,
+  ComponentRef<typeof RadixRadioGroup.Root>,
   RadioCardGroupProps
 >(function RadioCardGroup(
   {

package/src/components/segmented-control/markup/List.tsx

@@ -14,7 +14,7 @@ import SegmentedControlLabel from "./Label";
  * @param {SegmentedControlValue | undefined} props.selectedValue 현재 선택된 값.
  * @param {number} props.focusableIndex 포커스를 받을 기본 index.
  * @param {number} props.fallbackIndex 첫 번째 활성화 index.
- * @param {MutableRefObject<Array<HTMLButtonElement | null>>} props.itemRefs 버튼 ref 목록.
+ * @param {RefObject<Array<HTMLButtonElement | null>>} props.itemRefs 버튼 ref 목록.
  * @param {(value: SegmentedControlValue | undefined) => void} props.onSelect 값 변경 콜백.
  * @param {(index: number) => void} props.onFocusItemAt index 포커스 함수.
  * @param {(event: KeyboardEvent<HTMLButtonElement>, currentIndex: number) => void} props.onArrowNavigate 화살표 키 처리 콜백.

package/src/components/segmented-control/types/index.ts

@@ -3,8 +3,8 @@ import type {
   FocusEvent,
   KeyboardEvent,
   MouseEvent,
-  MutableRefObject,
   PointerEvent,
+  RefObject,
 } from "react";
 import type { SlotTextProps } from "../../slot";
 
@@ -67,7 +67,7 @@ export interface SegmentedControlListProps {
   selectedValue?: SegmentedControlValue;
   focusableIndex: number;
   fallbackIndex: number;
-  itemRefs: MutableRefObject<Array<HTMLButtonElement | null>>;
+  itemRefs: RefObject<Array<HTMLButtonElement | null>>;
   onSelect: (value: SegmentedControlValue | undefined) => void;
   onFocusItemAt: (index: number) => void;
   onArrowNavigate: (

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

@@ -1,6 +1,6 @@
 "use client";
 
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useMemo, useState } from "react";
 
 import type {
   UseSelectDropdownOpenStateParams,
@@ -38,17 +38,10 @@ export const useSelectDropdownOpenState = ({
     defaultOpen ?? false,
   );
 
-  // 3) defaultOpen 변경 시, 비제어형일 때만 내부 state를 동기화한다.
-  useEffect(() => {
-    if (isControlled) return;
-
-    setUncontrolledOpen(defaultOpen ?? false);
-  }, [defaultOpen, isControlled]);
-
-  // 4) 최종 open state는 제어형 우선, 아니면 내부 state를 사용한다.
+  // 3) 최종 open state는 제어형 우선, 아니면 최초 defaultOpen으로 만든 내부 state를 사용한다.
   const resolvedOpen = isControlled ? (open as boolean) : uncontrolledOpen;
 
-  // 5) setOpen은 내부 state 갱신 + 외부 콜백 브릿지를 동시에 담당한다.
+  // 4) setOpen은 내부 state 갱신 + 외부 콜백 브릿지를 동시에 담당한다.
   const setOpen = useCallback(
     (nextOpen: boolean) => {
       if (!isControlled) setUncontrolledOpen(nextOpen);

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

@@ -1,10 +1,11 @@
 "use client";
 
 import clsx from "clsx";
-import { useEffect, useMemo, useState } from "react";
+import { useMemo, useRef, useState } from "react";
 import type { ReactNode } from "react";
 
 import { Dropdown } from "../../dropdown/markup";
+import type { DropdownContainerProps } from "../../dropdown/types";
 import { SelectTriggerBase, SelectTriggerSelected } from "./foundation";
 import Container from "./foundation/Container";
 import { useSelectDropdownOpenState } from "../hooks";
@@ -20,9 +21,21 @@ import {
 const SELECT_CUSTOM_OPTION_BASE_ID = "__select_custom_input__";
 const SELECT_CUSTOM_OPTION_VALUE = "CUSTOM";
 
+/**
+ * Radix DropdownMenu.Content가 runtime에서 처리하는 open auto-focus 확장 props
+ * @property {(event: Event) => void} [onOpenAutoFocus] open 직후 focus 이동을 제어하는 consumer handler
+ */
+type DropdownContainerRuntimeProps = DropdownContainerProps & {
+  /**
+   * open 직후 focus 이동을 제어하는 consumer handler
+   */
+  onOpenAutoFocus?: (event: Event) => void;
+};
+
 /**
  * Select default trigger; 단일 선택 드롭다운을 렌더링한다.
  * @component
+ * @desc enabled selected option이 있으면 open 직후 해당 item을 focus하고 dropdown panel viewport만 nearest 기준으로 정렬한다. consumer open auto-focus handler가 기본 동작을 막으면 consumer 결정을 우선한다.
  * @param {SelectDefaultComponentProps} props default trigger props
  * @param {string} [props.className] container className
  * @param {ReactNode} [props.displayLabel] 강제 표시 라벨
@@ -86,10 +99,7 @@ export function SelectDefault<OptionData = unknown>({
   const resolvedSize =
     priority !== "primary" && size === "xsmall" ? "small" : size;
 
-  // 2) custom mode의 입력값은 내부 state로 유지한다.
-  const [customLabelValue, setCustomLabelValue] = useState("");
-
-  // 3) custom option id가 기존 item id와 충돌하지 않도록 안전한 id를 만든다.
+  // 2) custom option id가 기존 item id와 충돌하지 않도록 안전한 id를 만든다.
   const customOptionId = useMemo(() => {
     const existingIdSet = new Set(items.map(option => option.id));
     if (!existingIdSet.has(SELECT_CUSTOM_OPTION_BASE_ID)) {
@@ -132,38 +142,42 @@ export function SelectDefault<OptionData = unknown>({
   }, [items]);
 
   // 6) 내부 선택 state를 선언한다.
-  const [uncontrolledSelectedValue, setUncontrolledSelectedValue] = useState<
-    string | number | undefined
-  >(() => selectedValueFromItems);
+  const [selectionState, setSelectionState] = useState(() => ({
+    hasCustomOptions: Boolean(customOptions),
+    selectedValue: selectedValueFromItems,
+    selectedValueFromItems,
+  }));
 
   // 7) 외부 items 변경 시 value 규칙으로 내부 선택 state를 재동기화한다.
-  useEffect(() => {
-    setUncontrolledSelectedValue(previousSelectedValue => {
-      if (
+  if (
+    selectionState.hasCustomOptions !== Boolean(customOptions) ||
+    !isSameSelectedValue(
+      selectionState.selectedValueFromItems,
+      selectedValueFromItems,
+    )
+  ) {
+    setSelectionState({
+      hasCustomOptions: Boolean(customOptions),
+      selectedValue:
         customOptions &&
         isSameSelectedValue(
-          previousSelectedValue,
+          selectionState.selectedValue,
           SELECT_CUSTOM_OPTION_VALUE,
         ) &&
         selectedValueFromItems === undefined
-      ) {
-        // 변경 설명: custom option은 mergedOptions에만 주입되므로 source items 재동기화가 첫 클릭 CUSTOM 상태를 지우지 않게 한다.
-        return previousSelectedValue;
-      }
-      if (isSameSelectedValue(previousSelectedValue, selectedValueFromItems)) {
-        return previousSelectedValue;
-      }
-      return selectedValueFromItems;
+          ? selectionState.selectedValue
+          : selectedValueFromItems,
+      selectedValueFromItems,
     });
-  }, [customOptions, selectedValueFromItems]);
+  }
 
   // 8) value 기반으로 현재 선택 option을 계산한다.
   const selectedOption = useMemo(
     () =>
       mergedOptions.find(option =>
-        isSameSelectedValue(option.value, uncontrolledSelectedValue),
+        isSameSelectedValue(option.value, selectionState.selectedValue),
       ),
-    [mergedOptions, uncontrolledSelectedValue],
+    [mergedOptions, selectionState.selectedValue],
   );
 
   // 9) customOptions가 있는 경우 inputProps.value가 있고 option 매칭이 없으면 custom mode로 간주한다.
@@ -190,12 +204,16 @@ export function SelectDefault<OptionData = unknown>({
       toSelectedValueKey(SELECT_CUSTOM_OPTION_VALUE),
   );
 
-  useEffect(() => {
-    // 변경: custom mode에서 일반 옵션으로 이탈하면 내부 직접 입력값을 초기화한다.
-    if (!isCustomInputActive) {
-      setCustomLabelValue("");
-    }
-  }, [isCustomInputActive]);
+  const [customInputState, setCustomInputState] = useState({
+    isActive: false,
+    value: "",
+  });
+  if (customInputState.isActive !== isCustomInputActive) {
+    setCustomInputState({
+      isActive: isCustomInputActive,
+      value: isCustomInputActive ? customInputState.value : "",
+    });
+  }
 
   // 11) 외부 displayLabel이 있으면 우선 사용하고, 없으면 선택 option label을 사용한다.
   const resolvedDisplayLabel =
@@ -212,6 +230,42 @@ export function SelectDefault<OptionData = unknown>({
   // 13) disabled/readOnly 상태에서는 open/option 선택 인터랙션을 모두 차단한다.
   const isInteractionBlocked = disabled || readOnly;
 
+  // 13-1) panel과 enabled selected item을 runtime focus/viewport 정렬 대상으로 추적한다.
+  const dropdownPanelRef = useRef<HTMLDivElement>(null);
+  const selectedOptionRef = useRef<HTMLDivElement>(null);
+
+  // 13-2) consumer handler → selected focus → panel-only nearest scroll 순서를 보존한다.
+  const onOpenAutoFocus = (event: Event) => {
+    // consumer가 명시적으로 기본 동작을 막으면 내부 focus/scroll을 적용하지 않는다.
+    (
+      dropdownOptions?.containerProps as
+        DropdownContainerRuntimeProps | undefined
+    )?.onOpenAutoFocus?.(event);
+    if (event.defaultPrevented) {
+      return;
+    }
+
+    const panel = dropdownPanelRef.current;
+    const selectedItem = selectedOptionRef.current;
+    // selected가 없거나 disabled이면 ref가 없으므로 Radix 기본 focus 동작을 유지한다.
+    if (!panel || !selectedItem) {
+      return;
+    }
+
+    // Radix의 panel focus를 막고 outer container/document scroll 없이 selected item만 focus한다.
+    event.preventDefault();
+    selectedItem.focus({ preventScroll: true });
+
+    // viewport 밖으로 벗어난 거리만 panel.scrollTop에 반영해 nearest 정렬을 수행한다.
+    const panelRect = panel.getBoundingClientRect();
+    const selectedItemRect = selectedItem.getBoundingClientRect();
+    if (selectedItemRect.top < panelRect.top) {
+      panel.scrollTop -= panelRect.top - selectedItemRect.top;
+    } else if (selectedItemRect.bottom > panelRect.bottom) {
+      panel.scrollTop += selectedItemRect.bottom - panelRect.bottom;
+    }
+  };
+
   // 14) open 상태 변경 처리: 차단 상태면 닫힘 고정, 아니면 nextOpen 반영.
   const handleOpenChange = (nextOpen: boolean) => {
     if (isInteractionBlocked) {
@@ -255,7 +309,10 @@ export function SelectDefault<OptionData = unknown>({
         });
       }
 
-      setUncontrolledSelectedValue(option.value);
+      setSelectionState(previousState => ({
+        ...previousState,
+        selectedValue: option.value,
+      }));
       onSelectChange?.(option, previousOption, event);
     }
 
@@ -266,8 +323,8 @@ export function SelectDefault<OptionData = unknown>({
   const labelInputValue = isCustomInputActive
     ? typeof inputProps?.value === "string" ||
       typeof inputProps?.value === "number"
-      ? String(inputProps.value) || customLabelValue
-      : customLabelValue
+      ? String(inputProps.value) || customInputState.value
+      : customInputState.value
     : toSelectInputText(resolvedDisplayLabel);
 
   // 17) 렌더: Container → Dropdown.Root → Trigger → Menu.List 구조를 유지한다.
@@ -328,15 +385,24 @@ export function SelectDefault<OptionData = unknown>({
               valueStateSource={isCustomInputActive ? "label" : "hidden"}
               // 변경: custom mode 진입 시 label input에 focus를 연결한다.
               shouldFocusInput={isCustomInputActive}
-              onLabelChange={setCustomLabelValue}
+              onLabelChange={value => {
+                setCustomInputState(previousState => ({
+                  ...previousState,
+                  value,
+                }));
+              }}
             />
           </SelectTriggerBase>
         </Dropdown.Trigger>
         <Dropdown.Container
           {...dropdownOptions?.containerProps}
+          ref={dropdownPanelRef}
           size={dropdownOptions?.size ?? resolvedSize}
           width={dropdownOptions?.width ?? "match"}
           minWidth={dropdownOptions?.minWidth}
+          {...({
+            onOpenAutoFocus,
+          } as DropdownContainerProps)}
         >
           <Dropdown.Menu.List {...dropdownOptions?.menuListProps}>
             {mergedOptions.length > 0 ? (
@@ -344,6 +410,16 @@ export function SelectDefault<OptionData = unknown>({
                 {mergedOptions.map(option => (
                   <Dropdown.Menu.Item
                     key={option.id}
+                    // disabled option은 초기 focus 대상에서 제외하고 현재 단일 selected item만 추적한다.
+                    ref={
+                      !option.disabled &&
+                      isSameSelectedValue(
+                        resolvedSelectedOption?.value,
+                        option.value,
+                      )
+                        ? selectedOptionRef
+                        : undefined
+                    }
                     label={option.label}
                     description={option.description}
                     disabled={option.disabled}

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

@@ -1,7 +1,7 @@
 "use client";
 
 import clsx from "clsx";
-import { useEffect, useMemo, useState } from "react";
+import { useMemo, useState } from "react";
 
 import Container from "../foundation/Container";
 import { Dropdown } from "../../../dropdown/markup";
@@ -146,26 +146,26 @@ export function SelectMultipleTrigger<OptionData = unknown>({
    * - controlled 모드에서는 source로 사용되지 않는다.
    * - uncontrolled 모드에서는 최종 선택 배열을 내부 state가 소유한다.
    */
-  const [uncontrolledSelectedValues, setUncontrolledSelectedValues] = useState<
-    Array<string | number>
-  >(() => selectedValuesFromOptions);
+  const [selectionState, setSelectionState] = useState(() => ({
+    selectedValues: selectedValuesFromOptions,
+    selectedValuesFromOptions,
+  }));
 
   /**
    * 6) items 변경 시 내부 state 정합성 보정
    * - source of truth를 items[].selected(value)로 고정해 외부 선택 상태를 즉시 반영한다.
    */
-  useEffect(() => {
-    setUncontrolledSelectedValues(previousSelectedValues => {
-      const nextSelectedValues = selectedValuesFromOptions;
-
-      // 동일한 선택 결과면 기존 배열 참조를 유지해 재렌더 루프를 방지한다.
-      if (isSameSelectedValueList(previousSelectedValues, nextSelectedValues)) {
-        return previousSelectedValues;
-      }
-
-      return nextSelectedValues;
+  if (
+    !isSameSelectedValueList(
+      selectionState.selectedValuesFromOptions,
+      selectedValuesFromOptions,
+    )
+  ) {
+    setSelectionState({
+      selectedValues: selectedValuesFromOptions,
+      selectedValuesFromOptions,
     });
-  }, [selectedValuesFromOptions]);
+  }
 
   /**
    * 7) 최종 선택 value 계산
@@ -173,10 +173,10 @@ export function SelectMultipleTrigger<OptionData = unknown>({
    */
   const resolvedSelectedValues = useMemo(
     () =>
-      uncontrolledSelectedValues.filter(selectedValue =>
+      selectionState.selectedValues.filter(selectedValue =>
         optionMap.has(toSelectedValueKey(selectedValue)),
       ),
-    [optionMap, uncontrolledSelectedValues],
+    [optionMap, selectionState.selectedValues],
   );
   const selectedValueKeySet = useMemo(
     () =>
@@ -340,7 +340,10 @@ export function SelectMultipleTrigger<OptionData = unknown>({
 
       onSelectOption?.(selectAllOption, undefined, event);
       if (didChange) {
-        setUncontrolledSelectedValues(nextSelectedValues);
+        setSelectionState(previousState => ({
+          ...previousState,
+          selectedValues: nextSelectedValues,
+        }));
         onSelectChange?.(selectAllOption, undefined, event);
       }
       return;
@@ -359,7 +362,10 @@ export function SelectMultipleTrigger<OptionData = unknown>({
       : [...resolvedSelectedValues, option.value];
 
     onSelectOption?.(option, undefined, event);
-    setUncontrolledSelectedValues(nextSelectedValues);
+    setSelectionState(previousState => ({
+      ...previousState,
+      selectedValues: nextSelectedValues,
+    }));
     onSelectChange?.(option, undefined, event);
   };