@mondrianai/runyourai-design-system 0.0.21 → 0.0.23

package/dist/index.d.mts

@@ -1,13 +1,14 @@
 import * as React$1 from 'react';
 import React__default, { ReactNode } from 'react';
-import { Accordion as Accordion$1, AlertDialog as AlertDialog$1, Checkbox as Checkbox$1, Collapsible as Collapsible$1, Menubar as Menubar$1, Slider as Slider$1, Switch as Switch$1, Tooltip as Tooltip$1 } from 'radix-ui';
+import { Accordion as Accordion$1, AlertDialog as AlertDialog$1, Checkbox as Checkbox$1, Collapsible as Collapsible$1, Menubar as Menubar$1, Slider as Slider$1, Switch as Switch$1, Tooltip as Tooltip$1, Popover as Popover$1 } from 'radix-ui';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import { OTPInput } from 'input-otp';
 import * as _radix_ui_react_context from '@radix-ui/react-context';
-import { RowSelectionState, OnChangeFn, SortingState } from '@tanstack/react-table';
-export { OnChangeFn, PaginationState, RowSelectionState, SortingState } from '@tanstack/react-table';
+import { RowSelectionState, OnChangeFn, SortingState, ColumnFiltersState } from '@tanstack/react-table';
+export { ColumnFiltersState, OnChangeFn, PaginationState, RowSelectionState, SortingState } from '@tanstack/react-table';
+import { ExternalToast, ToasterProps } from 'sonner';
 
 declare const Accordion: React$1.ForwardRefExoticComponent<(Accordion$1.AccordionSingleProps | Accordion$1.AccordionMultipleProps) & React$1.RefAttributes<HTMLDivElement>>;
 declare const AccordionItem: React$1.ForwardRefExoticComponent<Omit<Accordion$1.AccordionItemProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
@@ -112,7 +113,7 @@ declare function BreadcrumbSeparator({ iconName, className, ...props }: React__d
 }): react_jsx_runtime.JSX.Element;
 
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "primary" | "secondary" | "outline" | "ghost" | "destructive" | null | undefined;
+    variant?: "link" | "primary" | "secondary" | "outline" | "ghost" | "destructive" | "ghostDestructive" | null | undefined;
     size?: "rounded" | "default" | "icon" | "pill" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
@@ -173,9 +174,24 @@ declare function Drawer({ open, onOpenChange, trigger, title, description, foote
 
 type DropdownMenuItemConfig = {
     type?: 'default' | 'checkbox' | 'radio';
-    label: string;
-    /** radio 아이템의 선택값. 미지정 시 label을 값으로 사용 */
+    /**
+     * 아이템 콘텐츠. 문자열뿐 아니라 임의 노드(아이콘 + 텍스트 + 트레일링 배지 등)를
+     * 넣을 수 있다. 문자열이 아닌 경우 React key·타입어헤드를 위해
+     * `value`·`textValue`를 함께 지정하는 것을 권장한다.
+     */
+    label: React$1.ReactNode;
+    /**
+     * 타입어헤드(키보드 입력으로 항목 이동) 매칭용 텍스트.
+     * label이 문자열이 아닐 때 지정한다. 미지정 시 label의 textContent가 사용된다.
+     */
+    textValue?: string;
+    /** radio 아이템의 선택값 / React key. 미지정 시 문자열 label 또는 index를 사용 */
     value?: string;
+    /**
+     * 현재 선택된 항목 강조. default 아이템에 selected 배경(bg-accent)을 적용한다.
+     * (checkbox/radio는 자체 체크 상태로 강조되므로 무시된다)
+     */
+    selected?: boolean;
     icon?: React$1.ReactNode;
     onClick?: () => void;
     onCheckedChange?: (checked: boolean) => void;
@@ -188,7 +204,13 @@ type DropdownMenuItemConfig = {
     subGroups?: DropdownMenuGroupConfig[];
 };
 type DropdownMenuGroupConfig = {
+    /** 문자열 그룹 헤더. 커스텀 렌더링이 필요하면 `header`를 사용한다. */
     label?: string;
+    /**
+     * 커스텀 그룹 헤더(ReactNode). 지정 시 `label` 대신 렌더링되며,
+     * 게이지·설명 등 자유로운 헤더를 구성할 수 있다. (포커스 대상이 아님)
+     */
+    header?: React$1.ReactNode;
     items: DropdownMenuItemConfig[];
     separator?: boolean;
     /** radio 그룹의 현재 선택값 (controlled) */
@@ -519,7 +541,7 @@ declare function Input({ className, type, ...props }: React$1.ComponentProps<"in
 
 declare function InputGroup({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
 declare const inputGroupAddonVariants: (props?: ({
-    align?: "inline-start" | "inline-end" | "block-start" | "block-end" | null | undefined;
+    align?: "inline-end" | "inline-start" | "block-end" | "block-start" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 declare function InputGroupAddon({ className, align, ...props }: React$1.ComponentProps<"div"> & VariantProps<typeof inputGroupAddonVariants>): react_jsx_runtime.JSX.Element;
 declare const inputGroupButtonVariants: (props?: ({
@@ -570,6 +592,24 @@ declare function MarkdownMessage({ content, isStreaming, footerMeta, className,
     className?: string;
 }): react_jsx_runtime.JSX.Element;
 
+/**
+ * footer 취소/확인 버튼 커스터마이즈 묶음.
+ * onClick(취소=onCancel, 확인=onConfirm)은 Modal 레벨에서 처리하므로 제외.
+ */
+interface ModalButtonProps {
+    /** 버튼 레이블 */
+    label?: string;
+    /** 텍스트 앞 아이콘 */
+    iconStart?: React$1.ReactNode;
+    /** 텍스트 뒤 아이콘 */
+    iconEnd?: React$1.ReactNode;
+    /** 비활성화 */
+    disabled?: boolean;
+    /** 로딩 상태 (스피너 표시, 클릭 불가) */
+    isLoading?: boolean;
+    /** 버튼에 추가할 className */
+    className?: string;
+}
 interface ModalProps {
     id?: string;
     /**
@@ -600,10 +640,10 @@ interface ModalProps {
     showCloseButton?: boolean;
     /** 모달 본문 */
     children?: React$1.ReactNode;
-    /** 취소 버튼 레이블 (기본: "취소") */
-    cancelLabel?: string;
-    /** 확인 버튼 레이블 (기본: "확인") */
-    confirmLabel?: string;
+    /** 취소 버튼 커스터마이즈 (label 기본: "취소") */
+    cancelButtonProps?: ModalButtonProps;
+    /** 확인 버튼 커스터마이즈 (label 기본: "확인") */
+    confirmButtonProps?: ModalButtonProps;
     /**
      * 확인 버튼 콜백.
      * Promise를 반환하면 resolve될 때까지 loading 상태를 내부에서 자동 처리하고
@@ -612,15 +652,12 @@ interface ModalProps {
     onConfirm?: () => void | Promise<void>;
     /** 취소/닫기 시 콜백 (cancel 버튼, X 버튼, ESC, 오버레이 클릭) */
     onCancel?: () => void;
-    /** 확인 버튼 비활성화 */
-    confirmDisabled?: boolean;
-    isLoading?: boolean;
     /** 오버레이 클릭 시 닫기 (기본: true) */
     closeOnOverlayClick?: boolean;
     /** 모달 패널에 추가할 className */
     className?: string;
 }
-declare function Modal({ id, trigger, open: openProp, onOpenChange, variant, title, description, showCloseButton, children, cancelLabel, confirmLabel, onConfirm, onCancel, confirmDisabled, closeOnOverlayClick, className, isLoading, }: ModalProps): react_jsx_runtime.JSX.Element;
+declare function Modal({ id, trigger, open: openProp, onOpenChange, variant, title, description, showCloseButton, children, cancelButtonProps, confirmButtonProps, onConfirm, onCancel, closeOnOverlayClick, className, }: ModalProps): react_jsx_runtime.JSX.Element;
 
 declare const Menubar: React$1.ForwardRefExoticComponent<Omit<Menubar$1.MenubarProps & React$1.RefAttributes<HTMLDivElement>, "ref"> & React$1.RefAttributes<HTMLDivElement>>;
 declare const MenubarMenu: {
@@ -701,7 +738,21 @@ interface SearchInputProps extends Omit<React$1.InputHTMLAttributes<HTMLInputEle
     /** onChange를 지연 호출할 ms. 지정하면 내부 draft 상태로 즉시 표시하고, 입력 완료 후 지연 커밋. */
     debounce?: number;
 }
-declare function SearchInput({ value, onChange, placeholder, className, debounce: debounceMs, ...props }: SearchInputProps): react_jsx_runtime.JSX.Element;
+/**
+ * ref로 노출되는 명령형 핸들.
+ * debounce 모드에서 부모가 "현재 value와 같은 값으로 리셋"해야 할 때 사용한다.
+ * (props value가 그대로면 동기화 effect가 발화하지 않으므로 prop만으로는 초기화 불가)
+ */
+interface SearchInputHandle {
+    /**
+     * 표시값·pending 커밋·예약된 debounce 타이머를 원자적으로 초기화한다.
+     * next 미지정 시 빈 문자열로 비운다. onChange는 호출하지 않는다.
+     */
+    reset: (next?: string) => void;
+    /** 내부 input에 포커스 */
+    focus: () => void;
+}
+declare const SearchInput: React$1.ForwardRefExoticComponent<SearchInputProps & React$1.RefAttributes<SearchInputHandle>>;
 
 interface SelectOption {
     value: string;
@@ -738,6 +789,14 @@ interface MultiSelectProps extends SelectBase {
     onValueChange?: (value: string[]) => void;
 }
 type SelectProps = SingleSelectProps | MultiSelectProps;
+/**
+ * 단일/다중 선택 셀렉트. multi-select를 위해 radix Select가 아니라 Popover 위에
+ * 커스텀 listbox를 렌더한다. 접근성은 WAI-ARIA listbox 패턴으로 직접 구현했다:
+ * - 열린 상태에서 listbox에 포커스가 이동하고 `aria-activedescendant`로 활성 옵션을 연결한다.
+ * - 키보드: ↑/↓/Home/End 이동, Enter/Space 선택(다중은 토글), Esc 닫힘, 타입어헤드 점프.
+ * - 역할: 컨테이너 `role="listbox"`(+다중 시 `aria-multiselectable`), 옵션 `role="option"`+`aria-selected`.
+ * 배경·설계 근거: {@link ../../../docs/todo/select-a11y-keyboard-aria.md}
+ */
 declare function Select(props: SelectProps): react_jsx_runtime.JSX.Element;
 
 type SheetSide = 'top' | 'right' | 'bottom' | 'left';
@@ -1008,15 +1067,79 @@ declare function Pagination({ currentPage, totalPages, onPageChange, simple, pre
 
 type SortDirection = 'ASC' | 'DESC' | null;
 interface TableColumn<T> {
-    key: string;
+    /**
+     * 컬럼 식별자(antd Table의 dataIndex에 대응).
+     * - T의 실제 필드명은 IDE 자동완성으로 제안된다(Extract<keyof T, string>).
+     * - 파생·가상 컬럼(예: 파일명에서 도출한 '유형')은 임의 문자열도 허용((string & {})).
+     *   실제 값 추출은 sortValue/filterValue/cell의 (row: T)가 담당하므로 key는 식별자일 뿐이다.
+     */
+    key: Extract<keyof T, string> | (string & {});
     header: string;
     sortable?: boolean;
     /** 정렬 기준값 추출. sortable=true 시 필수 */
     sortValue?: (row: T) => string | number;
+    /**
+     * true이면 헤더에 필터 아이콘을 노출하고, 체크박스로 여러 값을 다중 선택해
+     * 해당 컬럼을 필터링할 수 있다. (sortable과 독립적으로 함께 사용 가능)
+     */
+    filterable?: boolean;
+    /**
+     * 필터 기준값 추출. filterable=true 시 필수.
+     * 반환한 문자열이 "선택된 옵션 value"와 일치하는 행만 통과한다.
+     * (sortValue와 독립 — 정렬·필터 기준을 다르게 둘 수 있다)
+     */
+    filterValue?: (row: T) => string;
+    /**
+     * 필터 체크박스 옵션 목록. 미제공 시 data에서 filterValue 고유값을 자동 도출한다.
+     * - label: 체크박스에 표시할 텍스트
+     * - value: filterValue 반환값과 매칭되는 값
+     */
+    filterOptions?: {
+        label: string;
+        value: string;
+    }[];
+    /**
+     * 초기 선택 필터값. 지정 시 첫 렌더부터 이 값들로 필터가 걸린 상태로 시작한다.
+     * (정렬의 defaultSorting과 대칭)
+     */
+    defaultFilter?: string[];
     /** 헤더·셀 text-align. 기본값 "left" */
     align?: 'left' | 'center' | 'right';
     cellClassName?: string;
     headerClassName?: string;
+    /**
+     * 고정 px 너비. 컨테이너가 넓어져도 이 컬럼은 늘어나지 않는다.
+     * (grow와 함께 주면 width가 우선해 고정으로 처리된다)
+     *
+     * ⚠️ 한 테이블에서 width/minWidth/grow 중 하나라도 쓰면 그 테이블은 "flex 레이아웃"으로
+     * 전환된다. 이때 컬럼 너비는 이 세 prop으로만 정하고, headerClassName의 w-[..] 같은
+     * 너비 클래스는 무시된다(정렬·색상 등 다른 스타일에는 계속 headerClassName 사용 가능).
+     *
+     * @example width: 124  // 항상 124px 고정
+     */
+    width?: number;
+    /**
+     * 가변 컬럼의 최소 px 너비(floor). 남은 공간이 부족해도 이 값 아래로는 줄어들지 않고,
+     * 대신 테이블이 가로로 넘쳐 스크롤된다. grow와 함께 사용한다.
+     */
+    minWidth?: number;
+    /**
+     * 가변 컬럼의 성장 가중치. 고정 컬럼(width)을 뺀 "남은 폭"을 grow 비율대로 나눠 갖는다.
+     * (각 컬럼의 minWidth를 먼저 보장한 뒤, 그 위로 남는 여백만 grow 비율로 분배)
+     *
+     * - width/minWidth/grow를 아무것도 지정하지 않은 컬럼은 grow:1로 취급된다
+     *   → 여러 개면 남은 폭을 1:1로 균등 분배(headerClassName 없이 나열하던 기존 동작과 동일).
+     * - 한 테이블에서 width(고정)와 grow(가변)를 섞어 쓸 수 있다.
+     *
+     * @example
+     * // 남는 폭을 name : group : members = 3 : 1 : 1 로 분배.
+     * // 각 컬럼은 minWidth 이하로는 줄지 않고, 그 아래로 좁아지면 가로 스크롤.
+     * { key: 'name',    grow: 3, minWidth: 180 }
+     * { key: 'group',   grow: 1, minWidth: 128 }
+     * { key: 'members', grow: 1, minWidth: 128 }
+     * { key: 'date',    width: 136 } // 고정 컬럼은 늘어나지 않음
+     */
+    grow?: number;
     /**
      * true이면 셀 내용을 한 줄로 잘라내고 hover 시 tooltip으로 전체 내용을 표시.
      * tooltip에 표시할 텍스트를 별도로 지정하려면 ellipsisTooltip을 함께 사용.
@@ -1099,6 +1222,12 @@ interface TableProps<T> {
      * 빈 배열(정렬 해제)은 전달되지 않으므로 항상 최소 1개 항목 보장.
      */
     onSortingChange?: (sorting: SortingState) => void;
+    /**
+     * 필터 상태 변경 콜백. 서버사이드 필터 연동에 사용.
+     * 내부 상태는 그대로 유지되며, 변경될 때마다 현재 전체 필터 배열을 전달한다.
+     * (필터 전체 해제 시 빈 배열이 전달된다)
+     */
+    onColumnFiltersChange?: (filters: ColumnFiltersState) => void;
     className?: string;
     /**
      * 설정 시 tbody 영역만 스크롤되고 thead가 상단에 고정됩니다.
@@ -1109,10 +1238,14 @@ interface TableProps<T> {
 declare function SortIcon({ direction }: {
     direction: SortDirection;
 }): react_jsx_runtime.JSX.Element;
-declare function Table<T>({ columns, data, rowKey, pagination, defaultSorting, loading, empty, enableRowSelection, rowSelection: rowSelectionProp, onRowSelectionChange, rowActions, onRowClick, isRowDisabled, onSortingChange, className, maxHeight, }: TableProps<T>): react_jsx_runtime.JSX.Element;
+declare function Table<T>({ columns, data, rowKey, pagination, defaultSorting, loading, empty, enableRowSelection, rowSelection: rowSelectionProp, onRowSelectionChange, rowActions, onRowClick, isRowDisabled, onSortingChange, onColumnFiltersChange, className, maxHeight, }: TableProps<T>): react_jsx_runtime.JSX.Element;
 
 declare const TooltipProvider: React$1.FC<Tooltip$1.TooltipProviderProps>;
-interface TooltipProps extends Pick<React$1.ComponentPropsWithoutRef<typeof Tooltip$1.Root>, 'open' | 'defaultOpen' | 'onOpenChange' | 'delayDuration'>, Omit<React$1.ComponentPropsWithoutRef<typeof Tooltip$1.Content>, 'children' | 'content'> {
+interface TooltipSizeProps {
+    /** 말풍선 최대 너비 (숫자는 px). @default 280 */
+    maxWidth?: number | string;
+}
+interface TooltipProps extends Pick<React$1.ComponentPropsWithoutRef<typeof Tooltip$1.Root>, 'open' | 'defaultOpen' | 'onOpenChange' | 'delayDuration'>, Omit<React$1.ComponentPropsWithoutRef<typeof Tooltip$1.Content>, 'children' | 'content'>, TooltipSizeProps {
     /** 툴팁 말풍선에 표시할 내용 */
     content: React$1.ReactNode;
     /** 호버 시 툴팁을 여는 트리거 요소 (asChild로 렌더링) */
@@ -1136,6 +1269,170 @@ declare function UserMessageBubble({ content }: {
     content: string;
 }): react_jsx_runtime.JSX.Element;
 
+type PopoverContentProps = React$1.ComponentPropsWithoutRef<typeof Popover$1.Content>;
+interface PopoverProps extends Pick<React$1.ComponentPropsWithoutRef<typeof Popover$1.Root>, 'open' | 'defaultOpen' | 'onOpenChange'> {
+    /** 팝오버를 여는 트리거 요소 (asChild 로 렌더링) */
+    triggerNode: React$1.ReactNode;
+    /** 팝오버 내부에 표시할 내용 */
+    children: React$1.ReactNode;
+    /** 트리거 상호작용 방식. @default 'click' */
+    trigger?: 'click' | 'hover';
+    /** 트리거 기준 표시 방향. @default 'bottom' */
+    side?: PopoverContentProps['side'];
+    /** 트리거 기준 정렬. @default 'center' */
+    align?: PopoverContentProps['align'];
+    /** 트리거와의 거리(px). @default 8 */
+    sideOffset?: number;
+    /** align 축 오프셋(px). @default 0 */
+    alignOffset?: number;
+    /** 팝오버 컨테이너 추가 클래스(폭·패딩 등 오버라이드) */
+    className?: string;
+    /** 팝오버 컨테이너 인라인 스타일 */
+    style?: React$1.CSSProperties;
+    /** trigger='click' 의 모달 동작(바깥 상호작용 차단). @default false */
+    modal?: boolean;
+    /** trigger='hover' 일 때 열림 지연(ms) */
+    openDelay?: number;
+    /** trigger='hover' 일 때 닫힘 지연(ms) */
+    closeDelay?: number;
+    /** Portal 대상 컨테이너. 미지정 시 document.body */
+    container?: HTMLElement | null;
+}
+declare function Popover({ triggerNode, children, trigger, open, defaultOpen, onOpenChange, side, align, sideOffset, alignOffset, className, style, modal, openDelay, closeDelay, container, }: PopoverProps): react_jsx_runtime.JSX.Element;
+
+/** antd `message`의 success/warning/info/error 를 커버하는 토스트 유형. */
+type ToastType = 'success' | 'warning' | 'info' | 'error';
+/**
+ * DS `toast()` 옵션 — sonner 옵션 전부가 아니라 사용처에서 자주 쓰는 것만 노출한다.
+ * (그 외 세부 제어는 `<Toaster />` prop으로 전역 설정)
+ */
+type ToastOptions = {
+    /** 토스트 유형(아이콘·색). 미지정 시 중립(기본). */
+    type?: ToastType;
+    /** 제목 아래 보조 설명 문구 */
+    description?: React$1.ReactNode;
+    /**
+     * 떠 있는 시간(ms). 미지정 시 `<Toaster />` 기본값(sonner 기본 4000ms).
+     * `Infinity`를 주면 사용자가 닫기 전까지 유지된다.
+     */
+    duration?: number;
+    /** 표시 위치. 미지정 시 `<Toaster />` 기본값(top-center). */
+    position?: ExternalToast['position'];
+    /** 토스트 컨테이너에 추가할 클래스 */
+    className?: string;
+};
+type ToastMessage = React$1.ReactNode;
+/** type을 제외한 옵션 — 편의 메서드/핸들에서 사용(유형은 메서드가 이미 결정). */
+type ToastMethodOptions = Omit<ToastOptions, 'type'>;
+declare function baseToast(message: ToastMessage, options?: ToastOptions): string | number;
+/** `toast.promise` 문구 설정 — 성공/실패 문구는 결과·에러로 만드는 함수도 허용. */
+type ToastPromiseMessages<T> = {
+    /** 로딩 중 문구 */
+    loading: ToastMessage;
+    /** 성공 시 문구(또는 결과값으로 만드는 함수) */
+    success: ToastMessage | ((data: T) => ToastMessage);
+    /** 실패 시 문구(또는 에러로 만드는 함수) */
+    error: ToastMessage | ((error: unknown) => ToastMessage);
+    /** 보조 설명(선택) */
+    description?: ToastMessage;
+};
+/**
+ * Promise(또는 async 함수)의 진행 상태를 로딩→성공/실패 토스트로 자동 전환한다.
+ * 하나의 토스트가 상태에 따라 아이콘/문구만 바뀌므로 외부에서 id를 들고
+ * 수동으로 갱신할 필요가 없다.
+ *
+ * @remarks
+ * react-query와 함께 쓸 때는 **`mutateAsync`를 넘겨야** 로딩 토스트가 보인다.
+ * `mutate`는 `void`를 반환해 Promise가 아니므로 로딩 상태를 추적할 수 없다.
+ * (로딩 없이 콜백으로만 처리하려면 `toast.loading()`이 반환하는 핸들을 참고.)
+ *
+ * @example
+ * // ✅ react-query — mutateAsync 사용 (로딩 O)
+ * const { mutateAsync, isPending } = useMutation({ mutationFn: saveModel });
+ * const onSave = () =>
+ *   toast.promise(mutateAsync(payload), {
+ *     loading: '저장 중입니다...',
+ *     success: (data) => `${data.name} 저장되었습니다`,
+ *     error: (e) => `저장 실패: ${String(e)}`,
+ *   });
+ * // 버튼 중복 클릭 방지에만 isPending 사용: <Button disabled={isPending} …/>
+ *
+ * @example
+ * // 일반 Promise / async 함수도 동일하게 동작
+ * toast.promise(() => fetch('/api').then((r) => r.json()), {
+ *   loading: '불러오는 중...',
+ *   success: '완료',
+ *   error: '실패',
+ * });
+ */
+declare function promiseToast<T>(promise: Promise<T> | (() => Promise<T>), messages: ToastPromiseMessages<T>): string | number;
+/**
+ * 이미 떠 있는 하나의 토스트를 이후 상태로 갱신하는 핸들.
+ * `toast.loading()`이 반환하며, `{ id }`를 옵션으로 넘겨 다시 지정할 필요 없이
+ * 같은 토스트를 성공/실패 등으로 전환한다.
+ */
+type ToastHandle = {
+    /** 이 토스트의 id (직접 참조가 필요할 때만 사용) */
+    readonly id: string | number;
+    /** 같은 토스트를 성공 상태로 전환 */
+    success: (message: ToastMessage, options?: ToastMethodOptions) => void;
+    /** 같은 토스트를 실패 상태로 전환 */
+    error: (message: ToastMessage, options?: ToastMethodOptions) => void;
+    /** 같은 토스트를 경고 상태로 전환 */
+    warning: (message: ToastMessage, options?: ToastMethodOptions) => void;
+    /** 같은 토스트를 정보 상태로 전환 */
+    info: (message: ToastMessage, options?: ToastMethodOptions) => void;
+    /** 로딩 문구만 갱신 */
+    loading: (message: ToastMessage, options?: ToastMethodOptions) => void;
+    /** 중립(기본) 문구로 갱신 */
+    message: (message: ToastMessage, options?: ToastMethodOptions) => void;
+    /** 이 토스트 닫기 */
+    dismiss: () => void;
+};
+/**
+ * 토스트를 띄운다. 사용처의 antd `message.{success|warning|info|error}` 패턴을 대체한다.
+ * 렌더 지점인 `<Toaster />`는 앱 루트에 한 번만 마운트하면 된다(RyaiDsProvider에 포함).
+ *
+ * @example
+ * toast('저장되었습니다');                         // 중립(기본)
+ * toast('복사되었습니다', { type: 'success' });     // 유형 지정
+ * toast.success('복사되었습니다');                  // antd message 스타일 편의 메서드
+ * toast.error('삭제에 실패했습니다', { description: '잠시 후 다시 시도해 주세요.' });
+ */
+declare const toast: typeof baseToast & {
+    success: (message: ToastMessage, options?: ToastMethodOptions) => string | number;
+    warning: (message: ToastMessage, options?: ToastMethodOptions) => string | number;
+    info: (message: ToastMessage, options?: ToastMethodOptions) => string | number;
+    error: (message: ToastMessage, options?: ToastMethodOptions) => string | number;
+    /**
+     * 로딩 스피너 토스트를 띄우고, 이후 상태로 전환할 수 있는 핸들을 돌려준다.
+     * `{ id }`를 다시 넘길 필요 없이 핸들 메서드로 같은 토스트를 갱신한다.
+     *
+     * Promise를 받을 수 있으면 `toast.promise`가 더 간단하다. 이 API는 react-query의
+     * `mutate`처럼 Promise가 없는 콜백 방식에서 유용하다.
+     *
+     * @example
+     * // react-query — mutate(콜백) 방식
+     * const t = toast.loading('저장 중입니다...');
+     * mutate(payload, {
+     *   onSuccess: () => t.success('저장되었습니다'),
+     *   onError:   () => t.error('저장 실패'),
+     * });
+     */
+    loading: (message: ToastMessage, options?: ToastMethodOptions) => ToastHandle;
+    /** Promise/async 함수를 받아 로딩→성공/실패로 자동 전환. */
+    promise: typeof promiseToast;
+    /** id로 특정 토스트를 닫는다. 인자 없으면 전체 닫기. */
+    dismiss: (id?: number | string) => string | number;
+};
+/**
+ * 토스트 렌더 지점. 앱 루트에 한 번만 마운트한다.
+ * 배경/글자/테두리 색은 팔레트·시맨틱 토큰(CSS 변수)만 사용하고,
+ * 유형별 색상은 아이콘에만 적용한다(Alert 컴포넌트와 동일 원칙).
+ * position 기본값은 antd `message`와 유사한 top-center.
+ */
+declare function Toaster({ position, ...props }: ToasterProps): react_jsx_runtime.JSX.Element;
+
 /**
  * 디자인 시스템 전역 Provider 묶음.
  * layout.tsx (Server Component) 안에서 children을 감싸는 용도.
@@ -1144,6 +1441,7 @@ declare function UserMessageBubble({ content }: {
  *  - TooltipProvider: Radix Tooltip 전역 설정
  *    · delayDuration  — hover → open 지연 시간 (ms)
  *    · skipDelayDuration — 빠르게 연속 이동 시 딜레이 스킵 임계치 (ms)
+ *  - Toaster: sonner 토스트 렌더 지점(앱 루트 1회 마운트). `toast()`로 호출한다.
  */
 declare function RyaiDsProvider({ children }: {
     children: React.ReactNode;
@@ -1656,4 +1954,4 @@ declare function WordFileIcon({ className }: {
     className?: string;
 }): react_jsx_runtime.JSX.Element;
 
-export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AgentBlogIcon, AgentCsIcon, AgentDataIcon, AgentHrIcon, AgentMailIcon, AgentTrendIcon, AiAgentIcon, AiBuilderIcon, AiCloudIcon, AiDatacenterIcon, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, AlignJustifyIcon, AlignLeftIcon, ArrowDownIcon, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarProps, type AvatarSize, BADGE_VARIANT_STYLES, Badge, type BadgeProps, type BadgeVariant, BlockquoteIcon, BoldIcon, BookOpenIcon, BookUpIcon, Breadcrumb, Button, type ButtonProps, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxProps, ChevronsUpDownIcon, ChoiceCardGroup, type ChoiceCardGroupProps, ChoiceCardItem, type ChoiceCardItemProps, CircleCheckFillIcon, CircleHelpIcon, CircleIndicator, type CircleIndicatorProps, CircleOutlineIcon, ClaudeIcon, CodeIcon, CodeSquareIcon, Collapsible, CollapsibleContent, type CollapsibleProps, CollapsibleRoot, CollapsibleTrigger, type CollapsibleWorkspace, Combobox, type ComboboxOption, type ComboboxProps, CreditIcon, DataSection, type DataSectionProps, DatePicker, type DatePickerLocale, type DatePickerMode, type DatePickerProps, type DateRange, DeepSeekIcon, type DisabledDateRule, DownloadIcon, Drawer, type DrawerProps, DriveIcon, DropdownMenu, type DropdownMenuGroupConfig, type DropdownMenuItemConfig, type DropdownMenuProps, Empty, EmptyTrayIcon, Field, FieldDivider, type FieldProps, FieldRow, type FieldRowProps, FieldSection, type FieldSectionProps, FileCodeIcon, FileSearchIcon, FileTypeCornerIcon, FolderAmberIcon, FolderBlueIcon, FolderClosedIcon, FolderGreenIcon, FolderVioletIcon, GeminiIcon, GoogleIcon, HangulFileIcon, Header, type HeaderNavItem, type HeaderProps, HeadingIcon, HtmlFileIcon, ICON_NODES, Icon, type IconProps, ImageIcon, ImportIcon, IndentIcon, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, ItalicIcon, KbCard, type KbCardMetadataItem, type KbCardProps, KeyRoundIcon, type LanguageItem, LayersIcon, LayoutGridIcon, LineChartIcon, LinkIcon, ListIcon, ListOrderedIcon, MarkdownFileIcon, MarkdownMessage, Menubar, MenubarContent, MenubarGroup, MenubarItem, MenubarMenu, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, MessageCircleIcon, MessageFooter, type MessageFooterProps, MessagesSquareIcon, Modal, type ModalProps, MyPageIcon, type NavDropdownItem, type NotificationItem, NumberBadge, type NumberBadgeProps, OpenAiIcon, OutdentIcon, Pagination, type PaginationProps, PanelLeftIcon, PdfFileIcon, PenLineIcon, PencilLineIcon, PresentationIcon, Progress, type ProgressProps, type ProgressThreshold, RefreshCwIcon, RyaiDsProvider, RyaiLogoIcon, SearchInput, type SearchInputProps, SegmentedControl, Select, type SelectGroup, type SelectOption, type SelectProps, Sheet, SheetFileIcon, type SheetProps, ShoppingBagIcon, Sidebar, SidebarLink, type SidebarMainMenuItem, type SidebarSubMenuItem, type SidebarUtilityItem, Skeleton, type SkeletonProps, SlideFileIcon, Slider, SmileIcon, type SortDirection, SortIcon, SparklesIcon, SquareCheckIcon, SquareCheckOutlineIcon, StarIcon, Stepper, type StepperProps, StrikethroughIcon, Switch, SwitchField, type SwitchFieldProps, type TabItem, Table, type TableColumn, type TablePaginationConfig, TablePropertiesIcon, type TableProps, type TableSortingItem, Tabs, type TabsProps, Toggle, ToggleGroup, type ToggleGroupItemData, type ToggleGroupProps, type ToggleProps, Tooltip, type TooltipProps, TooltipProvider, TooltipWithIcon, type TooltipWithIconProps, TrashIcon, UpstageIcon, type UserMenuSection, type UserMenuSectionItem, UserMessageBubble, WandSparklesIcon, WordFileIcon, buttonVariants, toggleBaseClasses, toggleSizeClasses };
+export { Accordion, AccordionContent, AccordionItem, AccordionTrigger, AgentBlogIcon, AgentCsIcon, AgentDataIcon, AgentHrIcon, AgentMailIcon, AgentTrendIcon, AiAgentIcon, AiBuilderIcon, AiCloudIcon, AiDatacenterIcon, Alert, AlertDescription, AlertDialog, AlertDialogAction, AlertDialogCancel, AlertDialogContent, AlertDialogDescription, AlertDialogFooter, AlertDialogHeader, AlertDialogOverlay, AlertDialogPortal, AlertDialogTitle, AlertDialogTrigger, AlertTitle, AlignJustifyIcon, AlignLeftIcon, ArrowDownIcon, Avatar, AvatarGroup, type AvatarGroupItem, type AvatarGroupProps, type AvatarProps, type AvatarSize, BADGE_VARIANT_STYLES, Badge, type BadgeProps, type BadgeVariant, BlockquoteIcon, BoldIcon, BookOpenIcon, BookUpIcon, Breadcrumb, Button, type ButtonProps, Card, CardAction, CardContent, CardDescription, CardFooter, CardHeader, CardTitle, Checkbox, CheckboxCard, type CheckboxCardProps, type CheckboxProps, ChevronsUpDownIcon, ChoiceCardGroup, type ChoiceCardGroupProps, ChoiceCardItem, type ChoiceCardItemProps, CircleCheckFillIcon, CircleHelpIcon, CircleIndicator, type CircleIndicatorProps, CircleOutlineIcon, ClaudeIcon, CodeIcon, CodeSquareIcon, Collapsible, CollapsibleContent, type CollapsibleProps, CollapsibleRoot, CollapsibleTrigger, type CollapsibleWorkspace, Combobox, type ComboboxOption, type ComboboxProps, CreditIcon, DataSection, type DataSectionProps, DatePicker, type DatePickerLocale, type DatePickerMode, type DatePickerProps, type DateRange, DeepSeekIcon, type DisabledDateRule, DownloadIcon, Drawer, type DrawerProps, DriveIcon, DropdownMenu, type DropdownMenuGroupConfig, type DropdownMenuItemConfig, type DropdownMenuProps, Empty, EmptyTrayIcon, Field, FieldDivider, type FieldProps, FieldRow, type FieldRowProps, FieldSection, type FieldSectionProps, FileCodeIcon, FileSearchIcon, FileTypeCornerIcon, FolderAmberIcon, FolderBlueIcon, FolderClosedIcon, FolderGreenIcon, FolderVioletIcon, GeminiIcon, GoogleIcon, HangulFileIcon, Header, type HeaderNavItem, type HeaderProps, HeadingIcon, HtmlFileIcon, ICON_NODES, Icon, type IconProps, ImageIcon, ImportIcon, IndentIcon, Input, InputGroup, InputGroupAddon, InputGroupButton, InputGroupInput, InputGroupText, InputGroupTextarea, InputOTP, InputOTPGroup, InputOTPSeparator, InputOTPSlot, ItalicIcon, KbCard, type KbCardMetadataItem, type KbCardProps, KeyRoundIcon, type LanguageItem, LayersIcon, LayoutGridIcon, LineChartIcon, LinkIcon, ListIcon, ListOrderedIcon, MarkdownFileIcon, MarkdownMessage, Menubar, MenubarContent, MenubarGroup, MenubarItem, MenubarMenu, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger, MessageCircleIcon, MessageFooter, type MessageFooterProps, MessagesSquareIcon, Modal, type ModalButtonProps, type ModalProps, MyPageIcon, type NavDropdownItem, type NotificationItem, NumberBadge, type NumberBadgeProps, OpenAiIcon, OutdentIcon, Pagination, type PaginationProps, PanelLeftIcon, PdfFileIcon, PenLineIcon, PencilLineIcon, Popover, type PopoverProps, PresentationIcon, Progress, type ProgressProps, type ProgressThreshold, RefreshCwIcon, RyaiDsProvider, RyaiLogoIcon, SearchInput, type SearchInputHandle, type SearchInputProps, SegmentedControl, Select, type SelectGroup, type SelectOption, type SelectProps, Sheet, SheetFileIcon, type SheetProps, ShoppingBagIcon, Sidebar, SidebarLink, type SidebarMainMenuItem, type SidebarSubMenuItem, type SidebarUtilityItem, Skeleton, type SkeletonProps, SlideFileIcon, Slider, SmileIcon, type SortDirection, SortIcon, SparklesIcon, SquareCheckIcon, SquareCheckOutlineIcon, StarIcon, Stepper, type StepperProps, StrikethroughIcon, Switch, SwitchField, type SwitchFieldProps, type TabItem, Table, type TableColumn, type TablePaginationConfig, TablePropertiesIcon, type TableProps, type TableSortingItem, Tabs, type TabsProps, type ToastHandle, type ToastOptions, type ToastPromiseMessages, type ToastType, Toaster, Toggle, ToggleGroup, type ToggleGroupItemData, type ToggleGroupProps, type ToggleProps, Tooltip, type TooltipProps, TooltipProvider, type TooltipSizeProps, TooltipWithIcon, type TooltipWithIconProps, TrashIcon, UpstageIcon, type UserMenuSection, type UserMenuSectionItem, UserMessageBubble, WandSparklesIcon, WordFileIcon, buttonVariants, toast, toggleBaseClasses, toggleSizeClasses };