@bigtablet/design-system 3.2.2 → 3.4.0

package/dist/index.d.ts

@@ -1,6 +1,5 @@
 import * as React$1 from 'react';
 import * as _react_spring_web from '@react-spring/web';
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import { LucideProps, LucideIcon } from 'lucide-react';
 export { LucideIcon, LucideProps } from 'lucide-react';
 
@@ -37,6 +36,21 @@ declare const cn: (...classes: ClassValue[]) => string;
 
 declare function useFocusTrap(containerRef: React$1.RefObject<HTMLElement | null>, isActive: boolean): void;
 
+/**
+ * 사용자가 OS 수준에서 "동작 줄이기"를 켰는지 반환한다 (WCAG 2.3.3).
+ * spring 훅이나 JS 애니메이션에서 모션을 끌 때 사용. SSR에서는 false.
+ *
+ * React 표준 `useSyncExternalStore` 로 matchMedia 를 구독한다 - 불필요한
+ * 마운트 리렌더 없이 hydration-safe 하게 동작.
+ *
+ * @example
+ * ```tsx
+ * const reduced = useReducedMotion();
+ * const style = useSpring({ ..., immediate: reduced });
+ * ```
+ */
+declare function useReducedMotion(): boolean;
+
 /**
  * 마우스 hover 시 spring 기반 lift 효과를 만든다. 카드/CTA 강조에 사용.
  *
@@ -100,7 +114,9 @@ interface AccordionProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "o
     defaultOpenKeys?: string[];
     /** 제어형: 펼쳐진 키들 */
     openKeys?: string[];
-    /** 펼침/접힘 콜백 */
+    /** 펼침/접힘 콜백 (canonical). 열린 키 배열 전달 */
+    onValueChange?: (openKeys: string[]) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. */
     onChange?: (openKeys: string[]) => void;
 }
 /**
@@ -111,7 +127,7 @@ interface AccordionProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "o
  * <Accordion items={faqItems} multiple />
  * ```
  */
-declare const Accordion: ({ items, multiple, defaultOpenKeys, openKeys: controlledKeys, onChange, className, ...props }: AccordionProps) => react_jsx_runtime.JSX.Element;
+declare const Accordion: ({ items, multiple, defaultOpenKeys, openKeys: controlledKeys, onValueChange, onChange, className, ...props }: AccordionProps) => React$1.JSX.Element;
 
 type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl";
 type AvatarShape = "circle" | "square";
@@ -137,7 +153,7 @@ interface AvatarProps extends React$1.HTMLAttributes<HTMLSpanElement> {
  * <Avatar name="Sangmin Park" size="lg" /> // initials "SP"
  * ```
  */
-declare const Avatar: ({ src, name, size, shape, bgColor, className, style, ...props }: AvatarProps) => react_jsx_runtime.JSX.Element;
+declare const Avatar: ({ src, name, size, shape, bgColor, className, style, ...props }: AvatarProps) => React$1.JSX.Element;
 
 type BadgeVariant = "accent" | "neutral" | "info" | "success" | "warning" | "error";
 type BadgeShape = "dot" | "count" | "label";
@@ -177,7 +193,7 @@ interface BadgeProps extends React$1.HTMLAttributes<HTMLSpanElement> {
  * <Badge variant="success" appearance="soft">+5%</Badge>
  * ```
  */
-declare const Badge: ({ variant, shape, size, appearance, count, max, className, children, ...props }: BadgeProps) => react_jsx_runtime.JSX.Element;
+declare const Badge: ({ variant, shape, size, appearance, count, max, className, children, ...props }: BadgeProps) => React$1.JSX.Element;
 
 interface BottomNavProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "onChange"> {
     /** 스크린 리더 레이블 (기본 "주요 메뉴") */
@@ -202,7 +218,7 @@ interface BottomNavProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "onCh
  * <BottomNavSpacer />
  * ```
  */
-declare const BottomNav: ({ ariaLabel, className, children, ...props }: BottomNavProps) => react_jsx_runtime.JSX.Element;
+declare const BottomNav: ({ ariaLabel, className, children, ...props }: BottomNavProps) => React$1.JSX.Element;
 interface BottomNavItemCommon {
     /** 아이콘 (필수) */
     icon: React$1.ReactNode;
@@ -228,12 +244,12 @@ type BottomNavItemProps = BottomNavItemButton | BottomNavItemAnchor;
  * `BottomNav` 의 항목. icon + label 수직 스택.
  * active 시 `aria-current="page"` 자동 부여.
  */
-declare const BottomNavItem: (props: BottomNavItemProps) => react_jsx_runtime.JSX.Element;
+declare const BottomNavItem: (props: BottomNavItemProps) => React$1.JSX.Element;
 /**
  * 페이지 본문 끝에 두면 `BottomNav` 가 콘텐츠를 가리지 않게 빈 공간 확보.
  * `--bt-bottom-nav-height` (+ safe-area) 만큼 height.
  */
-declare const BottomNavSpacer: ({ className, ...props }: React$1.HTMLAttributes<HTMLDivElement>) => react_jsx_runtime.JSX.Element;
+declare const BottomNavSpacer: ({ className, ...props }: React$1.HTMLAttributes<HTMLDivElement>) => React$1.JSX.Element;
 
 interface BreadcrumbItem {
     /** 표시 텍스트 */
@@ -261,7 +277,7 @@ interface BreadcrumbProps extends React$1.HTMLAttributes<HTMLElement> {
  * ]} />
  * ```
  */
-declare const Breadcrumb: ({ items, separator, className, ...props }: BreadcrumbProps) => react_jsx_runtime.JSX.Element;
+declare const Breadcrumb: ({ items, separator, className, ...props }: BreadcrumbProps) => React$1.JSX.Element;
 
 interface EmptyStateProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title"> {
     /** 일러스트 영역 (아이콘/이미지 등) */
@@ -288,7 +304,7 @@ interface EmptyStateProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "
  * />
  * ```
  */
-declare const EmptyState: ({ illustration, title, description, action, size, className, ...props }: EmptyStateProps) => react_jsx_runtime.JSX.Element;
+declare const EmptyState: ({ illustration, title, description, action, size, className, ...props }: EmptyStateProps) => React$1.JSX.Element;
 
 type ErrorStateVariant = "page" | "widget";
 interface ErrorStateProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title"> {
@@ -324,7 +340,7 @@ interface ErrorStateProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "
  * <ErrorState variant="widget" title="불러오기 실패" action={<Button size="sm" onClick={retry}>재시도</Button>} />
  * ```
  */
-declare const ErrorState: ({ title, description, icon, action, variant, className, ...props }: ErrorStateProps) => react_jsx_runtime.JSX.Element;
+declare const ErrorState: ({ title, description, icon, action, variant, className, ...props }: ErrorStateProps) => React$1.JSX.Element;
 
 interface MenuItem {
     key: string;
@@ -359,7 +375,7 @@ interface MenuProps {
  * />
  * ```
  */
-declare const Menu: ({ items, trigger, align }: MenuProps) => react_jsx_runtime.JSX.Element;
+declare const Menu: ({ items, trigger, align }: MenuProps) => React$1.JSX.Element;
 
 type NavBarVariant = "default" | "transparent" | "accent";
 type NavBarLayout = "contained" | "fluid";
@@ -372,8 +388,10 @@ interface NavBarLocaleConfig {
     current: string;
     /** 가능한 옵션 */
     options: NavBarLocaleOption[];
-    /** locale 변경 콜백 */
-    onChange: (next: string) => void;
+    /** locale 변경 콜백 (canonical) */
+    onValueChange?: (next: string) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. */
+    onChange?: (next: string) => void;
     /** 표시 라벨 - 기본은 옵션의 label, 미지정 시 short code 표시 */
     hideLabel?: boolean;
 }
@@ -419,12 +437,12 @@ interface NavBarProps extends React$1.HTMLAttributes<HTMLElement> {
  * />
  * ```
  */
-declare const NavBar: ({ brand, searchSlot, actions, locale, profile, divider, variant, layout, sticky, className, children, ...props }: NavBarProps) => react_jsx_runtime.JSX.Element;
+declare const NavBar: ({ brand, searchSlot, actions, locale, profile, divider, variant, layout, sticky, className, children, ...props }: NavBarProps) => React$1.JSX.Element;
 interface NavLinkProps extends React$1.AnchorHTMLAttributes<HTMLAnchorElement> {
     /** 현재 활성 페이지 여부 */
     active?: boolean;
 }
-declare const NavLink: ({ active, className, children, ...props }: NavLinkProps) => react_jsx_runtime.JSX.Element;
+declare const NavLink: ({ active, className, children, ...props }: NavLinkProps) => React$1.JSX.Element;
 
 type SidebarMode = "auto" | "static";
 interface SidebarProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "onChange"> {
@@ -470,7 +488,7 @@ interface SidebarProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "onChan
  * </Sidebar>
  * ```
  */
-declare const Sidebar: ({ header, headerCollapsed, footer, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange, collapsible, toggleLabel, width, collapsedWidth, mode, className, children, style, ...props }: SidebarProps) => react_jsx_runtime.JSX.Element;
+declare const Sidebar: ({ header, headerCollapsed, footer, collapsed: collapsedProp, defaultCollapsed, onCollapsedChange, collapsible, toggleLabel, width, collapsedWidth, mode, className, children, style, ...props }: SidebarProps) => React$1.JSX.Element;
 interface SidebarItemCommon {
     /** 왼쪽 아이콘 */
     icon?: React$1.ReactNode;
@@ -488,13 +506,13 @@ type SidebarItemAnchor = SidebarItemCommon & {
     href: string;
 } & Omit<React$1.AnchorHTMLAttributes<HTMLAnchorElement>, "type">;
 type SidebarItemProps = SidebarItemButton | SidebarItemAnchor;
-declare const SidebarItem: (props: SidebarItemProps) => react_jsx_runtime.JSX.Element;
+declare const SidebarItem: (props: SidebarItemProps) => React$1.JSX.Element;
 interface SidebarSectionProps extends React$1.HTMLAttributes<HTMLDivElement> {
     /** 섹션 라벨 (collapsed 상태에선 hidden) */
     label?: string;
 }
 /** SidebarItem 그룹 라벨. collapsed에선 sr-only로 숨김. */
-declare const SidebarSection: ({ label, className, children, ...props }: SidebarSectionProps) => react_jsx_runtime.JSX.Element;
+declare const SidebarSection: ({ label, className, children, ...props }: SidebarSectionProps) => React$1.JSX.Element;
 
 type TabsVariant = "line" | "fills";
 type TabsSize = "sm" | "md";
@@ -516,24 +534,24 @@ interface TabsProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onChan
  * - 제어형: `value` + `onValueChange`
  * - 비제어형: `defaultValue`
  */
-declare const Tabs: ({ value: controlledValue, defaultValue, onValueChange, variant, size, className, children, ...props }: TabsProps) => react_jsx_runtime.JSX.Element;
+declare const Tabs: ({ value: controlledValue, defaultValue, onValueChange, variant, size, className, children, ...props }: TabsProps) => React$1.JSX.Element;
 interface TabListProps extends React$1.HTMLAttributes<HTMLDivElement> {
     /** 스크린리더 라벨 */
     ariaLabel?: string;
 }
-declare const TabList: ({ ariaLabel, className, children, ...props }: TabListProps) => react_jsx_runtime.JSX.Element;
+declare const TabList: ({ ariaLabel, className, children, ...props }: TabListProps) => React$1.JSX.Element;
 interface TabProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButtonElement>, "value"> {
     /** 이 tab의 value */
     value: string;
 }
-declare const Tab: ({ value, className, children, onClick, ...props }: TabProps) => react_jsx_runtime.JSX.Element;
+declare const Tab: ({ value, className, children, onClick, ...props }: TabProps) => React$1.JSX.Element;
 interface TabPanelProps extends React$1.HTMLAttributes<HTMLDivElement> {
     /** 이 panel을 활성화할 tab의 value */
     value: string;
     /** 비활성 panel을 unmount 할지 (기본 true). false면 display: none으로 유지 */
     unmountInactive?: boolean;
 }
-declare const TabPanel: ({ value, unmountInactive, className, children, ...props }: TabPanelProps) => react_jsx_runtime.JSX.Element | null;
+declare const TabPanel: ({ value, unmountInactive, className, children, ...props }: TabPanelProps) => React$1.JSX.Element | null;
 
 type PopoverPlacement = "top" | "bottom" | "left" | "right";
 interface PopoverProps {
@@ -576,7 +594,7 @@ interface PopoverProps {
  * ```
  */
 declare const Popover: {
-    ({ trigger, content, placement, open: openProp, defaultOpen, onOpenChange, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, className, }: PopoverProps): react_jsx_runtime.JSX.Element;
+    ({ trigger, content, placement, open: openProp, defaultOpen, onOpenChange, "aria-label": ariaLabel, "aria-labelledby": ariaLabelledby, className, }: PopoverProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -602,7 +620,7 @@ interface TooltipProps {
  * </Tooltip>
  * ```
  */
-declare const Tooltip: ({ content, placement, delay, disabled, children, }: TooltipProps) => react_jsx_runtime.JSX.Element;
+declare const Tooltip: ({ content, placement, delay, disabled, children, }: TooltipProps) => React$1.JSX.Element;
 
 declare const a11y: {
     readonly focusRing: "0 0 0 3px rgba(0, 0, 0, 0.15)";
@@ -652,10 +670,11 @@ declare const baseColors: {
     readonly neutral900: "#121212";
     readonly neutral925: "#141414";
     readonly neutral950: "#0A0A0A";
-    readonly statusError: "#EF4444";
-    readonly statusSuccess: "#10B981";
-    readonly statusWarning: "#F59E0B";
-    readonly statusInfo: "#3B82F6";
+    readonly textCaptionLight: "#6F6F6F";
+    readonly statusError: "#B91C1C";
+    readonly statusSuccess: "#047857";
+    readonly statusWarning: "#B45309";
+    readonly statusInfo: "#1D4ED8";
     readonly alphaBlack5: "rgba(0, 0, 0, 0.05)";
     readonly alphaBlack8: "rgba(0, 0, 0, 0.08)";
     readonly alphaBlack12: "rgba(26, 26, 26, 0.12)";
@@ -673,7 +692,7 @@ declare const colors: {
     readonly text: {
         readonly heading: "#121212";
         readonly body: "#666666";
-        readonly caption: "#888888";
+        readonly caption: "#6F6F6F";
         readonly brand: "#121212";
         readonly inverse: "#FFFFFF";
         readonly disabled: "rgba(26, 26, 26, 0.38)";
@@ -700,10 +719,10 @@ declare const colors: {
         readonly disabled: "#F2F2F2";
     };
     readonly status: {
-        readonly error: "#EF4444";
-        readonly success: "#10B981";
-        readonly warning: "#F59E0B";
-        readonly info: "#3B82F6";
+        readonly error: "#B91C1C";
+        readonly success: "#047857";
+        readonly warning: "#B45309";
+        readonly info: "#1D4ED8";
     };
     readonly accent: {
         readonly subtle: "rgba(0, 0, 0, 0.05)";
@@ -723,6 +742,14 @@ declare const elevation: {
     readonly level5: "0 8px 10px -5px rgba(0, 0, 0, 0.20), 0 20px 20px 0px rgba(0, 0, 0, 0.12)";
 };
 
+declare const iconSize: {
+    readonly xs: 14;
+    readonly sm: 16;
+    readonly md: 18;
+    readonly lg: 20;
+    readonly xl: 32;
+};
+
 declare const motion: {
     readonly transition: {
         readonly fast: "0.1s ease-in-out";
@@ -1121,6 +1148,8 @@ interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
      * filled: 빨간 bg, outline: 빨간 텍스트/border, tonal: 빨간 wash.
      */
     danger?: boolean;
+    /** 루트 button 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLButtonElement>;
 }
 /**
  * 버튼을 렌더링한다.
@@ -1128,7 +1157,7 @@ interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
  * @param props 버튼 속성
  * @returns 렌더링된 버튼 요소
  */
-declare const Button: ({ variant, size, leadingIcon, trailingIcon, fullWidth, radius, danger, className, children, ...props }: ButtonProps) => react_jsx_runtime.JSX.Element;
+declare const Button: ({ variant, size, leadingIcon, trailingIcon, fullWidth, radius, danger, type, ref, className, children, ...props }: ButtonProps) => React$1.JSX.Element;
 
 type CardVariant = "default" | "accent" | "glass" | "outlined";
 type CardFooterAlign = "start" | "between" | "end";
@@ -1156,6 +1185,8 @@ interface CardProps extends React$1.HTMLAttributes<HTMLDivElement> {
     footer?: React$1.ReactNode;
     /** footer 정렬 (기본값: "end") */
     footerAlign?: CardFooterAlign;
+    /** 루트 div 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLDivElement>;
 }
 /**
  * 카드 컴포넌트를 렌더링한다.
@@ -1163,7 +1194,7 @@ interface CardProps extends React$1.HTMLAttributes<HTMLDivElement> {
  * @param props 카드 속성
  * @returns 렌더링된 카드 UI
  */
-declare const Card: ({ heading, headingAs: HeadingTag, shadow, padding, bordered, variant, interactive, footer, footerAlign, className, children, ...props }: CardProps) => react_jsx_runtime.JSX.Element;
+declare const Card: ({ heading, headingAs: HeadingTag, shadow, padding, bordered, variant, interactive, footer, footerAlign, ref, className, children, ...props }: CardProps) => React$1.JSX.Element;
 
 interface CheckboxProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>, "size"> {
     /** 체크박스 옆에 표시할 라벨 */
@@ -1182,7 +1213,7 @@ interface CheckboxProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElemen
  * @returns 렌더링된 체크박스 UI
  */
 declare const Checkbox: {
-    ({ label, indeterminate, error, className, ref, ...props }: CheckboxProps): react_jsx_runtime.JSX.Element;
+    ({ label, indeterminate, error, className, ref, ...props }: CheckboxProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1213,17 +1244,15 @@ interface ChipProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onClic
     /** 삭제 버튼 클릭 시 콜백 */
     onRemove?: () => void;
 }
-declare const Chip: ({ type, size, tone, label, selected, removable, disabled, open, leadingIcon, onClick, onRemove, className, ...props }: ChipProps) => react_jsx_runtime.JSX.Element;
+declare const Chip: ({ type, size, tone, label, selected, removable, disabled, open, leadingIcon, onClick, onRemove, className, ...props }: ChipProps) => React$1.JSX.Element;
 
 type DatePickerMode = "year-month" | "year-month-day";
 type SelectableRange = "all" | "until-today";
-interface DatePickerProps {
+interface DatePickerBaseProps {
     /** 데이트 피커 위에 표시할 라벨 텍스트 */
     label?: string;
     /** 제어형 날짜 값 ("YYYY-MM" 또는 "YYYY-MM-DD" 형식) */
     value?: string;
-    /** 날짜 변경 시 호출되는 콜백. `mode` 값에 따라 "YYYY-MM" 또는 "YYYY-MM-DD" 형식의 문자열이 전달됩니다. */
-    onChange: (value: string) => void;
     /** 선택 모드 (기본값: "year-month-day") */
     mode?: DatePickerMode;
     /** 연도 선택 범위 시작 (기본값: 1950) */
@@ -1260,11 +1289,19 @@ interface DatePickerProps {
      */
     selectableRangeUntilTodaySrText?: string;
 }
+type DatePickerCallbacks = {
+    onValueChange: (value: string) => void;
+    onChange?: (value: string) => void;
+} | {
+    onValueChange?: (value: string) => void;
+    onChange: (value: string) => void;
+};
+type DatePickerProps = DatePickerBaseProps & DatePickerCallbacks;
 /**
  * 연/월/일 선택형 데이트 피커를 렌더링한다.
  * 내부적으로 DS Dropdown 3개를 조합해 드롭다운 UX 일관성을 유지한다.
  */
-declare const DatePicker: ({ label, value, onChange, mode, startYear, endYear: endYearProp, minDate, selectableRange, disabled, fullWidth, width, yearLabel, monthLabel, dayLabel, minDateSrFormat, selectableRangeUntilTodaySrText, }: DatePickerProps) => react_jsx_runtime.JSX.Element;
+declare const DatePicker: ({ label, value, onValueChange, onChange, mode, startYear, endYear: endYearProp, minDate, selectableRange, disabled, fullWidth, width, yearLabel, monthLabel, dayLabel, minDateSrFormat, selectableRangeUntilTodaySrText, }: DatePickerProps) => React$1.JSX.Element;
 
 interface DividerProps extends React$1.HTMLAttributes<HTMLHRElement> {
     /** 구분선 두께 (기본값: "standard") */
@@ -1276,7 +1313,43 @@ interface DividerProps extends React$1.HTMLAttributes<HTMLHRElement> {
  * @param props 구분선 속성
  * @returns 렌더링된 구분선 UI
  */
-declare const Divider: ({ weight, className, ...props }: DividerProps) => react_jsx_runtime.JSX.Element;
+declare const Divider: ({ weight, className, ...props }: DividerProps) => React$1.JSX.Element;
+
+/** Drawer 가 미끄러져 들어오는 방향 (top 은 범위 외) */
+type DrawerPlacement = "left" | "right" | "bottom";
+interface DrawerProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** 드로어 열림 여부 */
+    open: boolean;
+    /** 드로어 닫기 콜백 */
+    onClose?: () => void;
+    /** 슬라이드 방향 (기본값: "right") */
+    placement?: DrawerPlacement;
+    /** 패널 크기 - left/right 는 너비, bottom 은 높이 (기본값: 360). number ⇒ px */
+    size?: number | string;
+    /** 드로어 제목 (헤더 h2, heading_small_bold) */
+    title?: React$1.ReactNode;
+    /** 하단 액션 영역 (Button들). 미지정 시 footer 영역 자체가 안 보임 */
+    footer?: React$1.ReactNode;
+    /** 오버레이 클릭 시 닫기 여부 (기본값: true) */
+    closeOnOverlay?: boolean;
+    /** 우상단 X 닫기 아이콘 표시 여부 (기본값: true) */
+    showCloseIcon?: boolean;
+    /** X 닫기 버튼 접근성 레이블 (기본값: "닫기") */
+    closeLabel?: string;
+    /** 드로어 접근성 레이블 (title 없을 때 사용, 기본값: "Dialog") */
+    ariaLabel?: string;
+}
+/**
+ * 화면 가장자리에서 미끄러져 들어오는 패널(Drawer)을 렌더링한다.
+ * react-spring 기반 방향별 슬라이드 진입/퇴출 + 포커스 트랩 + 바디 스크롤 잠금.
+ *
+ * @param props 드로어 속성
+ * @returns 열림 상태일 때 렌더링된 드로어, 닫힘 상태면 null
+ */
+declare const Drawer: {
+    ({ open, onClose, placement, size, title, footer, closeOnOverlay, showCloseIcon, closeLabel, ariaLabel, children, className, ...props }: DrawerProps): React$1.JSX.Element | null;
+    displayName: string;
+};
 
 type DropdownSize = "sm" | "md" | "lg";
 interface DropdownOption {
@@ -1292,7 +1365,8 @@ interface DropdownOption {
     /** 아이템 아래 구분선 표시 여부 */
     showDivider?: boolean;
 }
-interface DropdownProps {
+/** single/multiple 공통 속성 */
+interface DropdownCommonProps {
     /** 드롭다운 요소의 id (미입력 시 자동 생성) */
     id?: string;
     /** 드롭다운 위에 표시할 플로팅 라벨 텍스트 */
@@ -1301,12 +1375,6 @@ interface DropdownProps {
     placeholder?: string;
     /** 표시할 옵션 목록 */
     options: DropdownOption[];
-    /** 제어형 선택 값 */
-    value?: string | null;
-    /** 값 변경 시 호출되는 콜백. 선택된 값과 전체 옵션 객체를 인자로 전달합니다. */
-    onChange?: (value: string | null, option?: DropdownOption | null) => void;
-    /** 비제어형 초기 선택 값 */
-    defaultValue?: string | null;
     /** 비활성화 여부 */
     disabled?: boolean;
     /** 드롭다운 크기 (기본값: "md") */
@@ -1325,14 +1393,53 @@ interface DropdownProps {
      * @deprecated textAlign은 더 이상 지원되지 않습니다.
      */
     textAlign?: "left" | "center";
+    /**
+     * 검색 가능 여부. 활성화 시 열린 패널 상단에 검색 입력이 표시되고, 옵션 `label` 부분 일치로 필터링됩니다.
+     * (기본값: false)
+     */
+    searchable?: boolean;
+    /** 검색 입력의 placeholder (기본값: "검색…") */
+    searchPlaceholder?: string;
+    /** 필터 결과가 0개일 때 표시할 텍스트 (기본값: "결과 없음") */
+    emptyText?: string;
+    /** 멀티 선택 요약 텍스트 (기본값: "N개 선택") */
+    selectedSummary?: (count: number) => string;
+}
+/** 단일 선택 (기본) */
+interface DropdownSingleProps extends DropdownCommonProps {
+    /** 다중 선택 모드 (기본값: false) */
+    multiple?: false;
+    /** 제어형 선택 값 */
+    value?: string | null;
+    /** 값 변경 콜백 (canonical). 선택된 값과 전체 옵션 객체를 전달합니다. */
+    onValueChange?: (value: string | null, option?: DropdownOption | null) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. */
+    onChange?: (value: string | null, option?: DropdownOption | null) => void;
+    /** 비제어형 초기 선택 값 */
+    defaultValue?: string | null;
 }
+/** 다중 선택 */
+interface DropdownMultipleProps extends DropdownCommonProps {
+    /** 다중 선택 모드 */
+    multiple: true;
+    /** 제어형 선택 값 목록 */
+    value?: string[];
+    /** 값 변경 콜백 (canonical). 선택된 값 목록과 옵션 객체 목록을 전달합니다. */
+    onValueChange?: (values: string[], options: DropdownOption[]) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. */
+    onChange?: (values: string[], options: DropdownOption[]) => void;
+    /** 비제어형 초기 선택 값 목록 */
+    defaultValue?: string[];
+}
+type DropdownProps = DropdownSingleProps | DropdownMultipleProps;
 /**
  * 드롭다운 컴포넌트를 렌더링한다.
- * 제어형/비제어형 상태를 지원하며, 키보드/마우스 상호작용과 플로팅 라벨을 관리한다.
+ * 제어형/비제어형 상태를 지원하며, 키보드/마우스 상호작용과 정적 라벨을 관리한다.
+ * `searchable` 로 라벨 부분 일치 검색을, `multiple` 로 다중 선택을 opt-in 할 수 있다.
  * @param props 드롭다운 속성
  * @returns 렌더링된 드롭다운 UI
  */
-declare const Dropdown: ({ id, label, placeholder, options, value, onChange, defaultValue, disabled, size, className, }: DropdownProps) => react_jsx_runtime.JSX.Element;
+declare const Dropdown: (props: DropdownProps) => React$1.JSX.Element;
 
 type FileInputVariant = "button" | "preview";
 interface FileInputProps extends React$1.InputHTMLAttributes<HTMLInputElement> {
@@ -1359,7 +1466,7 @@ interface FileInputProps extends React$1.InputHTMLAttributes<HTMLInputElement> {
  * @param props 파일 입력 속성
  * @returns 렌더링된 파일 입력 UI
  */
-declare const FileInput: ({ label, onFiles, supportingText, preview, variant, previewSize, className, disabled, accept, onChange, ...props }: FileInputProps) => react_jsx_runtime.JSX.Element;
+declare const FileInput: ({ label, onFiles, supportingText, preview, variant, previewSize, className, disabled, accept, onChange, ...props }: FileInputProps) => React$1.JSX.Element;
 
 interface HeroAction {
     /** 버튼 라벨 */
@@ -1408,7 +1515,7 @@ interface HeroProps extends Omit<React$1.HTMLAttributes<HTMLElement>, "title"> {
  * @param props 히어로 속성
  * @returns 히어로 섹션
  */
-declare const Hero: ({ height, align, backgroundImage, backgroundColor, overlay, title, subtitle, eyebrow, textColor, primaryAction, secondaryAction, children, className, style, ...props }: HeroProps) => react_jsx_runtime.JSX.Element;
+declare const Hero: ({ height, align, backgroundImage, backgroundColor, overlay, title, subtitle, eyebrow, textColor, primaryAction, secondaryAction, children, className, style, ...props }: HeroProps) => React$1.JSX.Element;
 
 interface IconProps extends Omit<LucideProps, "ref"> {
     /** lucide-react 아이콘 컴포넌트 */
@@ -1430,7 +1537,7 @@ interface IconProps extends Omit<LucideProps, "ref"> {
  * lucide-react 아이콘 전체 카탈로그: https://lucide.dev/icons/
  */
 declare const Icon: {
-    ({ icon: IconComponent, ...props }: IconProps): react_jsx_runtime.JSX.Element;
+    ({ icon: IconComponent, ...props }: IconProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1443,6 +1550,8 @@ interface IconButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement
     size?: IconButtonSize;
     /** 표시할 아이콘 */
     icon: React$1.ReactNode;
+    /** 루트 button 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLButtonElement>;
 }
 /**
  * 아이콘만 표시하는 버튼을 렌더링한다.
@@ -1450,7 +1559,7 @@ interface IconButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement
  * @param props 아이콘 버튼 속성
  * @returns 렌더링된 아이콘 버튼 요소
  */
-declare const IconButton: ({ variant, size, icon, className, ...props }: IconButtonProps) => react_jsx_runtime.JSX.Element;
+declare const IconButton: ({ variant, size, icon, type, ref, className, ...props }: IconButtonProps) => React$1.JSX.Element;
 
 interface LinearProgressProps extends React.HTMLAttributes<HTMLDivElement> {
     /** 전체 단계 수 */
@@ -1466,7 +1575,7 @@ interface LinearProgressProps extends React.HTMLAttributes<HTMLDivElement> {
  * @param props 진행 표시기 속성
  * @returns 렌더링된 진행 표시기 요소
  */
-declare const LinearProgress: ({ totalSteps, currentStep, className, ...props }: LinearProgressProps) => react_jsx_runtime.JSX.Element;
+declare const LinearProgress: ({ totalSteps, currentStep, className, ...props }: LinearProgressProps) => React$1.JSX.Element;
 
 interface ListItemProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onClick"> {
     /** 오버라인 (상단 작은 글씨). 문자열 또는 노드(강조/링크/아이콘) */
@@ -1496,7 +1605,7 @@ interface ListItemProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "on
  * @param props 리스트 아이템 속성
  * @returns 렌더링된 리스트 아이템 UI
  */
-declare const ListItem: ({ overline, label, supportingText, metadata, leadingElement, trailingElement, alignment, disabled, selected, onClick, className, ...props }: ListItemProps) => react_jsx_runtime.JSX.Element;
+declare const ListItem: ({ overline, label, supportingText, metadata, leadingElement, trailingElement, alignment, disabled, selected, onClick, className, ...props }: ListItemProps) => React$1.JSX.Element;
 
 type MediaCardImagePosition = "top" | "left" | "overlay";
 type MediaCardShadow = "none" | "sm" | "md" | "lg";
@@ -1532,7 +1641,7 @@ interface MediaCardProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "t
  * @param props 카드 속성
  * @returns 이미지 카드
  */
-declare const MediaCard: ({ image, imagePosition, aspectRatio, heading, headingAs: HeadingTag, eyebrow, shadow, bordered, clickable, meta, children, className, ...props }: MediaCardProps) => react_jsx_runtime.JSX.Element;
+declare const MediaCard: ({ image, imagePosition, aspectRatio, heading, headingAs: HeadingTag, eyebrow, shadow, bordered, clickable, meta, children, className, ...props }: MediaCardProps) => React$1.JSX.Element;
 
 type ModalFooterAlign = "end" | "between" | "start";
 interface ModalProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title"> {
@@ -1565,14 +1674,16 @@ interface ModalProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "title
  * @param props 모달 속성
  * @returns 열림 상태일 때 렌더링된 모달, 닫힘 상태면 null
  */
-declare const Modal: ({ open, onClose, closeOnOverlay, width, title, description, footer, footerAlign, showCloseIcon, closeLabel, children, className, ariaLabel, ...props }: ModalProps) => react_jsx_runtime.JSX.Element | null;
+declare const Modal: ({ open, onClose, closeOnOverlay, width, title, description, footer, footerAlign, showCloseIcon, closeLabel, children, className, ariaLabel, ...props }: ModalProps) => React$1.JSX.Element | null;
 
 interface OtpInputProps {
     /** OTP 자릿수 (기본값: 6) */
     length?: 4 | 6;
     /** 제어형 값 */
     value?: string;
-    /** 값 변경 콜백 */
+    /** 값 변경 콜백 (canonical) */
+    onValueChange?: (value: string) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. */
     onChange?: (value: string) => void;
     /** 에러 상태 */
     error?: boolean;
@@ -1594,29 +1705,35 @@ interface OtpInputProps {
  * @returns 렌더링된 OTP 입력 요소
  */
 declare const OtpInput: {
-    ({ length, value, onChange, error, disabled, supportingText, autoFocus, ariaLabel, className, }: OtpInputProps): react_jsx_runtime.JSX.Element;
+    ({ length, value, onValueChange, onChange, error, disabled, supportingText, autoFocus, ariaLabel, className, }: OtpInputProps): React$1.JSX.Element;
     displayName: string;
 };
 
-interface PaginationProps {
+interface PaginationBaseProps {
     /** 현재 페이지 번호 (1-based) */
     page: number;
     /** 전체 페이지 수 */
     totalPages: number;
-    /** 페이지 변경 시 호출되는 콜백 */
-    onChange: (page: number) => void;
     /** 이전 페이지 버튼 aria-label (기본값: "Previous page") */
     prevLabel?: string;
     /** 다음 페이지 버튼 aria-label (기본값: "Next page") */
     nextLabel?: string;
 }
+type PaginationCallbacks = {
+    onPageChange: (page: number) => void;
+    onChange?: (page: number) => void;
+} | {
+    onPageChange?: (page: number) => void;
+    onChange: (page: number) => void;
+};
+type PaginationProps = PaginationBaseProps & PaginationCallbacks;
 /**
  * 페이지네이션을 렌더링한다.
  * 이전/다음 버튼과 페이지 목록을 구성해 전달된 콜백으로 페이지 변경을 전달한다.
  * @param props 페이지네이션 속성
  * @returns 렌더링된 페이지네이션 UI
  */
-declare const Pagination: ({ page, totalPages, onChange, prevLabel, nextLabel, }: PaginationProps) => react_jsx_runtime.JSX.Element;
+declare const Pagination: ({ page, totalPages, onPageChange, onChange, prevLabel, nextLabel, }: PaginationProps) => React$1.JSX.Element;
 
 interface RadioProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>, "size"> {
     /** 라디오 버튼 옆에 표시할 라벨 */
@@ -1634,7 +1751,7 @@ interface RadioProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>,
  * @returns 렌더링된 라디오 UI
  */
 declare const Radio: {
-    ({ label, size: sizeProp, className, ref, value, checked, onChange, name: nameProp, disabled: disabledProp, ...props }: RadioProps): react_jsx_runtime.JSX.Element;
+    ({ label, size: sizeProp, className, ref, value, checked, onChange, name: nameProp, disabled: disabledProp, ...props }: RadioProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1681,7 +1798,7 @@ interface RadioGroupProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "
  * ```
  */
 declare const RadioGroup: {
-    ({ value: controlledValue, defaultValue, onValueChange, name: nameProp, label, supportingText, error, size, orientation, disabled, className, children, ...props }: RadioGroupProps): react_jsx_runtime.JSX.Element;
+    ({ value: controlledValue, defaultValue, onValueChange, name: nameProp, label, supportingText, error, size, orientation, disabled, className, children, ...props }: RadioGroupProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1701,7 +1818,7 @@ interface SkeletonProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "ch
  * @param props 스켈레톤 속성
  * @returns 스켈레톤 요소
  */
-declare const Skeleton: ({ variant, width, height, radius, className, style, ...props }: SkeletonProps) => react_jsx_runtime.JSX.Element;
+declare const Skeleton: ({ variant, width, height, radius, className, style, ...props }: SkeletonProps) => React$1.JSX.Element;
 
 interface SpinnerProps {
     /** 스피너 크기(px) (기본값: 24) */
@@ -1715,9 +1832,16 @@ interface SpinnerProps {
  * @param props 스피너 속성
  * @returns 렌더링된 스피너 요소
  */
-declare const Spinner: ({ size, ariaLabel }: SpinnerProps) => react_jsx_runtime.JSX.Element;
+declare const Spinner: ({ size, ariaLabel }: SpinnerProps) => React$1.JSX.Element;
 
 type TableSize = "sm" | "md" | "lg";
+type TableSortDirection = "asc" | "desc";
+interface TableSort {
+    /** 정렬 중인 컬럼의 `TableColumn.key` */
+    key: string;
+    /** 정렬 방향 */
+    direction: TableSortDirection;
+}
 interface TableColumn<T extends object> {
     /** 컬럼 식별자 - `data[key]` 자동 렌더링에도 쓰임 */
     key: string;
@@ -1729,8 +1853,26 @@ interface TableColumn<T extends object> {
     width?: string;
     /** 정렬 (기본값: "left") */
     align?: "left" | "center" | "right";
-}
-interface TableProps<T extends object> {
+    /** 정렬 가능한 컬럼 여부 (기본값: false). 클릭 시 `onSortChange` 발화 - 실제 정렬은 소비자가 수행 */
+    sortable?: boolean;
+}
+/** `selectable` 시 `rowKey` 를 요구하기 위한 판별 유니온 */
+type TableSelectionProps<T extends object> = {
+    /** 행 선택(체크박스 컬럼) 활성화 여부 */
+    selectable: true;
+    /** 행 고유 key 추출 함수 - `selectable` 사용 시 필수 */
+    rowKey: (row: T) => string;
+    /** 선택된 행 key 배열 (제어형) */
+    selectedKeys?: string[];
+    /** 선택 변경 콜백 */
+    onSelectionChange?: (keys: string[]) => void;
+} | {
+    selectable?: false;
+    rowKey?: (row: T) => string;
+    selectedKeys?: string[];
+    onSelectionChange?: (keys: string[]) => void;
+};
+type TableProps<T extends object> = {
     /** 컬럼 정의 */
     columns: TableColumn<T>[];
     /** 표시할 데이터 배열 */
@@ -1755,13 +1897,21 @@ interface TableProps<T extends object> {
     className?: string;
     /** 행 클릭 콜백 */
     onRowClick?: (item: T, index: number) => void;
-}
+    /** 현재 정렬 상태 (제어형). `undefined` 는 정렬 없음 */
+    sort?: TableSort;
+    /** 정렬 가능한 헤더 클릭 시 발화 (none→asc→desc→none 순환). DS는 데이터를 직접 정렬하지 않음 - 정렬된 `data` 를 다시 전달해야 함 */
+    onSortChange?: (sort: TableSort | undefined) => void;
+    /** 전체 선택 체크박스 aria-label (기본값: "전체 선택") */
+    selectAllAriaLabel?: string;
+    /** 개별 행 선택 체크박스 aria-label (기본값: (i) => `${i+1}번째 행 선택`) */
+    selectRowAriaLabel?: (index: number) => string;
+} & TableSelectionProps<T>;
 /**
  * 데이터 테이블을 렌더링한다. 로딩 중에는 헤더 유지, 바디에 스켈레톤 행을 표시한다.
  * @param props 테이블 속성
  * @returns 테이블 컴포넌트
  */
-declare const Table: <T extends object>({ columns, data, keyExtractor, emptyMessage, isLoading, skeletonRows, size, hoverable, stickyHeader, ariaLabel, className, onRowClick, }: TableProps<T>) => react_jsx_runtime.JSX.Element;
+declare const Table: <T extends object>({ columns, data, keyExtractor, emptyMessage, isLoading, skeletonRows, size, hoverable, stickyHeader, ariaLabel, className, onRowClick, sort, onSortChange, selectAllAriaLabel, selectRowAriaLabel, selectable, rowKey, selectedKeys, onSelectionChange, }: TableProps<T>) => React$1.JSX.Element;
 
 type ThemeMode = "light" | "dark" | "system";
 type ResolvedTheme = "light" | "dark";
@@ -1826,7 +1976,9 @@ interface TextFieldProps extends Omit<React$1.InputHTMLAttributes<HTMLInputEleme
     clearable?: boolean;
     /** 컨테이너 전체 너비 차지 여부 */
     fullWidth?: boolean;
-    /** 값 변경 시 호출되는 콜백. 호출 시점은 `imeStrategy` 에 따름 (기본: 조합 완료 후) */
+    /** 값 변경 콜백 (canonical). 호출 시점은 `imeStrategy` 에 따름 (기본: 조합 완료 후) */
+    onValueChange?: (value: string) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. (Next 서버액션 전달용으로 `Action` 접미사가 필요하면 그대로 사용 가능) */
     onChangeAction?: (value: string) => void;
     /**
      * IME 조합 중 콜백 전략 (기본값: "delayed").
@@ -1850,7 +2002,7 @@ interface TextFieldProps extends Omit<React$1.InputHTMLAttributes<HTMLInputEleme
  * @returns 렌더링된 텍스트 필드 UI
  */
 declare const TextField: {
-    ({ id, label, showLabel, supportingText, error, leadingIcon, trailingIcon, clearable, fullWidth, size, className, onChangeAction, imeStrategy, value, defaultValue, transformValue, ref, ...props }: TextFieldProps): react_jsx_runtime.JSX.Element;
+    ({ id, label, showLabel, supportingText, error, leadingIcon, trailingIcon, clearable, fullWidth, size, className, onValueChange, onChangeAction, imeStrategy, value, defaultValue, transformValue, ref, ...props }: TextFieldProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1869,7 +2021,9 @@ interface TextareaProps extends Omit<React$1.TextareaHTMLAttributes<HTMLTextArea
     error?: boolean;
     /** 컨테이너 전체 너비 차지 여부 */
     fullWidth?: boolean;
-    /** 값 변경 시 호출되는 콜백. 호출 시점은 `imeStrategy` 에 따름 (기본: 조합 완료 후) */
+    /** 값 변경 콜백 (canonical). 호출 시점은 `imeStrategy` 에 따름 (기본: 조합 완료 후) */
+    onValueChange?: (value: string) => void;
+    /** @deprecated `onValueChange` 를 사용하세요. (Next 서버액션 전달용으로 `Action` 접미사가 필요하면 그대로 사용 가능) */
     onChangeAction?: (value: string) => void;
     /**
      * IME 조합 중 콜백 전략 (기본값: "delayed").
@@ -1909,7 +2063,7 @@ interface TextareaProps extends Omit<React$1.TextareaHTMLAttributes<HTMLTextArea
  * ```
  */
 declare const Textarea: {
-    ({ id, label, showLabel, supportingText, error, fullWidth, size, className, onChangeAction, imeStrategy, value, defaultValue, transformValue, rows, minRows, maxRows, showCounter, resize, maxLength, ref, ...props }: TextareaProps): react_jsx_runtime.JSX.Element;
+    ({ id, label, showLabel, supportingText, error, fullWidth, size, className, onValueChange, onChangeAction, imeStrategy, value, defaultValue, transformValue, rows, minRows, maxRows, showCounter, resize, maxLength, ref, ...props }: TextareaProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1927,7 +2081,7 @@ interface ToastProviderProps {
  * @param props Provider 속성
  * @returns 렌더링된 Provider와 토스트 컨테이너
  */
-declare const ToastProvider: ({ children, maxCount, closeAriaLabel, }: ToastProviderProps) => react_jsx_runtime.JSX.Element;
+declare const ToastProvider: ({ children, maxCount, closeAriaLabel, }: ToastProviderProps) => React$1.JSX.Element;
 
 /**
  * 토스트 메시지를 표시하는 훅.
@@ -1952,7 +2106,9 @@ interface ToggleProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButtonElemen
     checked?: boolean;
     /** 비제어형 초기 토글 상태 */
     defaultChecked?: boolean;
-    /** 상태 변경 시 호출되는 콜백 */
+    /** 상태 변경 콜백 (canonical) */
+    onCheckedChange?: (checked: boolean) => void;
+    /** @deprecated `onCheckedChange` 를 사용하세요. */
     onChange?: (checked: boolean) => void;
     /** 토글 크기 (기본값: "sm") */
     size?: "sm" | "md";
@@ -1970,7 +2126,7 @@ interface ToggleProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButtonElemen
  * @returns 렌더링된 토글 요소
  */
 declare const Toggle: {
-    ({ checked, defaultChecked, onChange, size, disabled, className, ariaLabel, ref, ...props }: ToggleProps): react_jsx_runtime.JSX.Element;
+    ({ checked, defaultChecked, onCheckedChange, onChange, size, disabled, className, ariaLabel, ref, ...props }: ToggleProps): React$1.JSX.Element;
     displayName: string;
 };
 
@@ -1992,7 +2148,7 @@ interface TopLoadingProps {
  * @param props 로딩바 속성
  * @returns 렌더링된 로딩바 요소 또는 null
  */
-declare const TopLoading: ({ progress, color, height, isLoading, ariaLabel, }: TopLoadingProps) => react_jsx_runtime.JSX.Element | null;
+declare const TopLoading: ({ progress, color, height, isLoading, ariaLabel, }: TopLoadingProps) => React$1.JSX.Element | null;
 
 type ContainerSize = "sm" | "md" | "lg" | "xl" | "full";
 interface ContainerProps extends React$1.HTMLAttributes<HTMLDivElement> {
@@ -2006,6 +2162,8 @@ interface ContainerProps extends React$1.HTMLAttributes<HTMLDivElement> {
     center?: boolean;
     /** 렌더링할 HTML 요소 */
     as?: React$1.ElementType;
+    /** 루트 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLElement>;
 }
 /**
  * max-width 제한 + 반응형 수평 패딩을 가진 컨테이너.
@@ -2019,7 +2177,7 @@ interface ContainerProps extends React$1.HTMLAttributes<HTMLDivElement> {
  * </Container>
  * ```
  */
-declare const Container: ({ size, center, as: Tag, className, children, ...props }: ContainerProps) => react_jsx_runtime.JSX.Element;
+declare const Container: ({ size, center, as: Tag, ref, className, children, ...props }: ContainerProps) => React$1.JSX.Element;
 
 type SectionSpacing = "xs" | "sm" | "md" | "lg" | "xl";
 type SectionBg = "default" | "dim" | "accent" | "inverted" | "transparent";
@@ -2038,6 +2196,8 @@ interface SectionProps extends React$1.HTMLAttributes<HTMLElement> {
     bg?: SectionBg;
     /** 렌더링할 HTML 요소 */
     as?: React$1.ElementType;
+    /** 루트 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLElement>;
 }
 /**
  * 마케팅 페이지의 섹션 단위. 수직 여백 + 배경색 variants.
@@ -2052,7 +2212,7 @@ interface SectionProps extends React$1.HTMLAttributes<HTMLElement> {
  * </Section>
  * ```
  */
-declare const Section: ({ spacing, bg, as: Tag, className, children, ...props }: SectionProps) => react_jsx_runtime.JSX.Element;
+declare const Section: ({ spacing, bg, as: Tag, ref, className, children, ...props }: SectionProps) => React$1.JSX.Element;
 
 type StackDirection = "vertical" | "horizontal";
 type StackAlign = "start" | "center" | "end" | "stretch";
@@ -2078,6 +2238,8 @@ interface StackProps extends React$1.HTMLAttributes<HTMLDivElement> {
     wrap?: StackWrap;
     /** 렌더링할 HTML 요소 */
     as?: React$1.ElementType;
+    /** 루트 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLElement>;
 }
 /**
  * Flex 기반 1D 레이아웃 컨테이너.
@@ -2096,7 +2258,7 @@ interface StackProps extends React$1.HTMLAttributes<HTMLDivElement> {
  * </Stack>
  * ```
  */
-declare const Stack: ({ direction, gap, align, justify, wrap, as: Tag, className, children, style, ...props }: StackProps) => react_jsx_runtime.JSX.Element;
+declare const Stack: ({ direction, gap, align, justify, wrap, as: Tag, ref, className, children, style, ...props }: StackProps) => React$1.JSX.Element;
 
 type GridCols = 1 | 2 | 3 | 4 | 5 | 6 | "auto";
 type GridGap = 0 | 4 | 8 | 12 | 16 | 20 | 24 | 32 | 40 | 48;
@@ -2124,6 +2286,8 @@ interface GridProps extends React$1.HTMLAttributes<HTMLDivElement> {
     singleColOnMobile?: boolean;
     /** 렌더링할 HTML 요소 */
     as?: React$1.ElementType;
+    /** 루트 요소 ref (React 19 ref-as-prop) */
+    ref?: React$1.Ref<HTMLElement>;
 }
 /**
  * CSS Grid 기반 2D 레이아웃 컨테이너.
@@ -2142,6 +2306,6 @@ interface GridProps extends React$1.HTMLAttributes<HTMLDivElement> {
  * </Grid>
  * ```
  */
-declare const Grid: ({ cols, minColWidth, gap, rowGap, colGap, singleColOnMobile, as: Tag, className, children, style, ...props }: GridProps) => react_jsx_runtime.JSX.Element;
+declare const Grid: ({ cols, minColWidth, gap, rowGap, colGap, singleColOnMobile, as: Tag, ref, className, children, style, ...props }: GridProps) => React$1.JSX.Element;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertProvider, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, Badge, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeVariant, BottomNav, BottomNavItem, type BottomNavItemProps, type BottomNavProps, BottomNavSpacer, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardFooterAlign, type CardProps, type CardVariant, Checkbox, type CheckboxProps, Chip, type ChipProps, type ChipSize, type ChipTone, type ChipType, Container, type ContainerProps, type ContainerSize, DatePicker, type DatePickerProps, Divider, type DividerProps, Dropdown, type DropdownOption, type DropdownProps, type DropdownSize, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type ErrorStateVariant, FileInput, type FileInputProps, Grid, type GridCols, type GridGap, type GridProps, Hero, type HeroAction, type HeroAlign, type HeroHeight, type HeroOverlay, type HeroProps, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconProps, type ImeStrategy, LinearProgress, type LinearProgressProps, ListItem, type ListItemProps, MediaCard, type MediaCardImage, type MediaCardImagePosition, type MediaCardProps, type MediaCardShadow, Menu, type MenuItem, type MenuProps, Modal, type ModalProps, NavBar, type NavBarLayout, type NavBarLocaleConfig, type NavBarLocaleOption, type NavBarProps, type NavBarVariant, NavLink, type NavLinkProps, OtpInput, type OtpInputProps, Pagination, type PaginationProps, Popover, type PopoverPlacement, type PopoverProps, Radio, RadioGroup, type RadioGroupOrientation, type RadioGroupProps, type RadioGroupSize, type RadioProps, type ResolvedTheme, Section, type SectionBg, type SectionProps, type SectionSpacing, Sidebar, SidebarItem, type SidebarItemProps, type SidebarMode, type SidebarProps, SidebarSection, type SidebarSectionProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackDirection, type StackGap, type StackJustify, type StackProps, type StackWrap, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, type TableColumn, type TableProps, type TableSize, Tabs, type TabsProps, type TabsSize, type TabsVariant, TextField, type TextFieldProps, type TextFieldSize, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type ThemeMode, ThemeProvider, type ThemeProviderProps, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipPlacement, type TooltipProps, TopLoading, type TopLoadingProps, a11y, baseBorderWidth, baseColors, baseTypography, borderWidth, breakpoints, cn, colors, elevation, motion, opacity, radius, skeleton, spacing, typography, useAlert, useFocusTrap, useSpringHover, useSpringPresence, useTheme, useToast, zIndex };
+export { Accordion, type AccordionItem, type AccordionProps, AlertProvider, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, Badge, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeVariant, BottomNav, BottomNavItem, type BottomNavItemProps, type BottomNavProps, BottomNavSpacer, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardFooterAlign, type CardProps, type CardVariant, Checkbox, type CheckboxProps, Chip, type ChipProps, type ChipSize, type ChipTone, type ChipType, Container, type ContainerProps, type ContainerSize, DatePicker, type DatePickerProps, Divider, type DividerProps, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, type DropdownOption, type DropdownProps, type DropdownSize, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type ErrorStateVariant, FileInput, type FileInputProps, Grid, type GridCols, type GridGap, type GridProps, Hero, type HeroAction, type HeroAlign, type HeroHeight, type HeroOverlay, type HeroProps, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconProps, type ImeStrategy, LinearProgress, type LinearProgressProps, ListItem, type ListItemProps, MediaCard, type MediaCardImage, type MediaCardImagePosition, type MediaCardProps, type MediaCardShadow, Menu, type MenuItem, type MenuProps, Modal, type ModalProps, NavBar, type NavBarLayout, type NavBarLocaleConfig, type NavBarLocaleOption, type NavBarProps, type NavBarVariant, NavLink, type NavLinkProps, OtpInput, type OtpInputProps, Pagination, type PaginationProps, Popover, type PopoverPlacement, type PopoverProps, Radio, RadioGroup, type RadioGroupOrientation, type RadioGroupProps, type RadioGroupSize, type RadioProps, type ResolvedTheme, Section, type SectionBg, type SectionProps, type SectionSpacing, Sidebar, SidebarItem, type SidebarItemProps, type SidebarMode, type SidebarProps, SidebarSection, type SidebarSectionProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackDirection, type StackGap, type StackJustify, type StackProps, type StackWrap, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, type TableColumn, type TableProps, type TableSize, type TableSort, type TableSortDirection, Tabs, type TabsProps, type TabsSize, type TabsVariant, TextField, type TextFieldProps, type TextFieldSize, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type ThemeMode, ThemeProvider, type ThemeProviderProps, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipPlacement, type TooltipProps, TopLoading, type TopLoadingProps, a11y, baseBorderWidth, baseColors, baseTypography, borderWidth, breakpoints, cn, colors, elevation, iconSize, motion, opacity, radius, skeleton, spacing, typography, useAlert, useFocusTrap, useReducedMotion, useSpringHover, useSpringPresence, useTheme, useToast, zIndex };