@bestow-ui/react 0.11.0 → 0.12.0

package/dist/index.d.cts

@@ -1,7 +1,7 @@
 import * as _bestow_ui_tokens from '@bestow-ui/tokens';
 import { space } from '@bestow-ui/tokens';
 import * as react from 'react';
-import { HTMLAttributes, CSSProperties, ComponentPropsWithoutRef, ReactNode, InputHTMLAttributes, ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, TdHTMLAttributes, ThHTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { HTMLAttributes, CSSProperties, ReactNode, ComponentPropsWithoutRef, InputHTMLAttributes, ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, TdHTMLAttributes, ThHTMLAttributes, TextareaHTMLAttributes } from 'react';
 import * as RadixAccordion from '@radix-ui/react-accordion';
 import * as Dialog from '@radix-ui/react-dialog';
 import * as RadixMenu from '@radix-ui/react-dropdown-menu';
@@ -285,6 +285,108 @@ declare function usePortalProps(): {
  */
 declare function usePortalClassName(): string;
 
+/**
+ * 컴포넌트의 기본 문구. 모두 생략할 수 있고, 생략하면 각 컴포넌트의 한국어 기본값을 쓴다.
+ * 우선순위: 컴포넌트에 직접 준 prop > LocaleProvider 의 messages > 한국어 기본값.
+ *
+ * 한국어 기본값을 하나의 객체로 모으지 않고 각 컴포넌트에 두는 이유: 그 객체를 import 하면 Button 하나만 써도
+ * 모든 문구가 번들에 딸려 온다(Button → Spinner). 이 파일에는 타입과 Provider 만 둔다.
+ */
+interface BestowMessages {
+    /** 닫기 버튼 (Modal, Drawer, Popover, Toast, Alert) — "닫기" */
+    close: string;
+    /** Spinner — "로딩 중" */
+    loading: string;
+    /** Toast 영역 — "알림" */
+    notifications: string;
+    /** Breadcrumb — "이동 경로" */
+    breadcrumb: string;
+    /** Pagination — "페이지 탐색", "이전 페이지", "다음 페이지", "3 페이지" */
+    pagination: string;
+    paginationPrevious: string;
+    paginationNext: string;
+    paginationPage: (page: number) => string;
+    /** Link external — "(새 창)" */
+    newWindow: string;
+    /** Combobox — "결과가 없어요", "목록 열기" */
+    noResults: string;
+    openList: string;
+    /** Slider 범위 손잡이 — "최소", "최대" */
+    rangeStart: string;
+    rangeEnd: string;
+    /** AgreementGroup — "전체 동의", "필수", "선택", "보기", "접기" */
+    agreeAll: string;
+    required: string;
+    optional: string;
+    show: string;
+    hide: string;
+    /** VerificationCodeInput — "인증번호", "6자리 숫자를 입력하세요.", "재전송", "인증 시간이 지났어요. 재전송해 주세요." */
+    verificationCode: string;
+    verificationCodeHint: (length: number, type: 'numeric' | 'alphanumeric') => string;
+    resend: string;
+    verificationExpired: string;
+    /** PhoneNumberInput — "휴대폰 번호" */
+    phoneNumber: string;
+    /** BusinessNumberInput — "사업자등록번호" 와 검증 문구 */
+    businessNumber: string;
+    businessNumberInvalid: string;
+    businessNumberIncomplete: string;
+    /** AmountInput — "금액", "원" */
+    amount: string;
+    currencyUnit: string;
+    /** AddressInput */
+    address: string;
+    addressSearch: string;
+    addressSearchDescription: string;
+    postalCode: string;
+    baseAddress: string;
+    baseAddressPlaceholder: string;
+    detailAddress: string;
+    detailAddressPlaceholder: string;
+    addressLoading: string;
+    addressLoadError: string;
+    /** Calendar */
+    previousMonth: string;
+    nextMonth: string;
+    /** 달 제목 — month 는 1~12 */
+    monthTitle: (year: number, month: number) => string;
+    /** 요일 머리글 (일요일부터 7개) */
+    weekdaysShort: readonly string[];
+    /** 요일 전체 이름 (일요일부터 7개) */
+    weekdaysLong: readonly string[];
+    /** 날짜 버튼 이름 — 화면에 보이는 날짜 숫자로 시작해야 한다 (WCAG 2.5.3) */
+    dayLabel: (date: Date, weekdayLong: string) => string;
+    holiday: string;
+    today: string;
+    /** DatePicker */
+    date: string;
+    openCalendar: string;
+    calendar: string;
+    dateInvalid: string;
+    dateUnavailable: string;
+    dateIncomplete: string;
+}
+type Messages = Partial<BestowMessages>;
+interface LocaleProviderProps {
+    /** 바꿀 문구. 일부만 넘기면 나머지는 바깥 LocaleProvider 또는 한국어 기본값을 쓴다 */
+    messages: Messages;
+    children?: ReactNode;
+}
+/**
+ * 컴포넌트 기본 문구를 한곳에서 바꾼다 (다국어 대응 등). 중첩하면 바깥 값을 이어받고 안쪽이 우선한다.
+ * @example <LocaleProvider messages={en}>…</LocaleProvider>
+ * @example <LocaleProvider messages={{ close: '창 닫기' }}>…</LocaleProvider>
+ */
+declare function LocaleProvider({ messages, children }: LocaleProviderProps): react.JSX.Element;
+/** LocaleProvider 로 바꾼 문구 (없으면 빈 객체 — 각 컴포넌트가 한국어 기본값을 쓴다) */
+declare function useMessages(): Messages;
+
+/**
+ * 영어 문구. `<LocaleProvider messages={en}>` 로 쓴다. 따로 import 할 때만 번들에 들어간다.
+ * 한국 서비스 전용 부품(사업자등록번호 등)의 문구도 영어로 바뀌지만 서식(하이픈 위치 등)은 그대로다.
+ */
+declare const en: BestowMessages;
+
 /**
  * `type="single"`: 한 번에 하나만 열린다 (`value: string`). `collapsible` 이면 열린 항목을 다시 눌러 닫을 수 있다.
  * `type="multiple"`: 여러 개를 함께 열 수 있다 (`value: string[]`).
@@ -586,6 +688,36 @@ interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'col
 }
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
+interface CalendarProps {
+    /** 선택된 날짜 'YYYY-MM-DD' (제어 모드) */
+    value?: string;
+    /** 처음 선택된 날짜 (비제어 모드) */
+    defaultValue?: string;
+    /** 날짜를 고를 때 호출된다 */
+    onValueChange?: (value: string) => void;
+    /** 고를 수 있는 가장 이른 날짜 'YYYY-MM-DD' */
+    min?: string;
+    /** 고를 수 있는 가장 늦은 날짜 'YYYY-MM-DD' */
+    max?: string;
+    /** 고를 수 없는 날짜 (예: 주말 제외) */
+    isDateDisabled?: (date: Date) => boolean;
+    /** 공휴일. 일요일처럼 빨갛게 표시하고 스크린리더에 "공휴일" 을 덧붙인다 */
+    isHoliday?: (date: Date) => boolean;
+    /** 오늘 날짜 'YYYY-MM-DD'. 기본은 실제 오늘 — 테스트·스크린샷에서 고정할 때 쓴다 */
+    today?: string;
+    /** 처음 그릴 때 날짜(선택된 날짜, 없으면 오늘)로 포커스를 옮긴다 — 팝업 안에서 쓸 때 */
+    initialFocus?: boolean;
+    /** 이전·다음 달 버튼 이름 */
+    prevMonthLabel?: string;
+    nextMonthLabel?: string;
+    className?: string;
+}
+/**
+ * 달력 (WAI-ARIA grid). 일요일부터 시작하고 일요일·공휴일은 빨강, 토요일은 파랑으로 표시한다.
+ * 키보드: ←→ 하루, ↑↓ 일주일, Home/End 주의 처음·끝, PageUp/PageDown 한 달(Shift 와 함께 1년), Enter/Space 선택.
+ */
+declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<HTMLDivElement>>;
+
 interface CardProps extends HTMLAttributes<HTMLElement> {
     /** 시각적 스타일. outline 은 테두리, elevated 는 그림자(다크 모드는 가장자리 ring 포함), soft 는 옅은 배경 */
     variant?: 'outline' | 'elevated' | 'soft';
@@ -613,6 +745,8 @@ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'siz
     indeterminate?: boolean;
     /** 에러 상태 */
     invalid?: boolean;
+    /** 체크 상태가 바뀌면 호출된다 (Switch 와 같은 이름). 기본 `onChange` 도 그대로 쓸 수 있다 */
+    onCheckedChange?: (checked: boolean) => void;
 }
 declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
 
@@ -661,6 +795,47 @@ interface ComboboxProps {
  */
 declare const Combobox: react.ForwardRefExoticComponent<ComboboxProps & react.RefAttributes<HTMLInputElement>>;
 
+interface DatePickerProps {
+    /** 날짜 'YYYY-MM-DD' (제어 모드). 비어 있으면 '' */
+    value?: string;
+    /** 처음 날짜 (비제어 모드) */
+    defaultValue?: string;
+    /** 올바른 날짜를 다 입력하거나 달력에서 고르면 'YYYY-MM-DD', 지우거나 잘못되면 '' 로 호출된다 */
+    onValueChange?: (value: string) => void;
+    /** 고를 수 있는 가장 이른·늦은 날짜 'YYYY-MM-DD' */
+    min?: string;
+    max?: string;
+    /** 고를 수 없는 날짜 */
+    isDateDisabled?: (date: Date) => boolean;
+    /** 공휴일 (달력에 빨갛게 표시) */
+    isHoliday?: (date: Date) => boolean;
+    /** 오늘 날짜 'YYYY-MM-DD' (테스트·스크린샷 고정용) */
+    today?: string;
+    label?: ReactNode;
+    /** 아래 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    error?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    fullWidth?: boolean;
+    placeholder?: string;
+    /** 달력 버튼·달력 창 이름 */
+    calendarLabel?: string;
+    /** 자동 검증 문구 */
+    invalidText?: string;
+    unavailableText?: string;
+    incompleteText?: string;
+    /** form 제출 시 이름 ('YYYY-MM-DD' 가 제출된다) */
+    name?: string;
+    id?: string;
+    className?: string;
+}
+/**
+ * 날짜 입력. `YYYY-MM-DD` 로 직접 입력하거나(숫자만 쳐도 하이픈이 들어간다) 달력 버튼으로 고른다.
+ * 달력은 일요일부터 시작하고, 열면 선택된 날짜(없으면 오늘)로 포커스가 간다. 값은 시간대 문제가 없는 'YYYY-MM-DD' 문자열이다.
+ */
+declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<HTMLInputElement>>;
+
 interface DividerProps extends HTMLAttributes<HTMLDivElement> {
     /** 방향. vertical 은 flex 행 안에서 부모 높이를 채운다 */
     orientation?: 'horizontal' | 'vertical';
@@ -733,8 +908,11 @@ interface DropdownMenuItemProps extends Omit<ComponentPropsWithoutRef<typeof Rad
     icon?: ReactNode;
     /** 오른쪽에 표시할 단축키 (예: "⌘K"). 표시용이라 항목 이름에는 포함되지 않는다 */
     shortcut?: string;
-    /** danger 는 삭제처럼 되돌리기 어려운 동작 */
-    color?: 'default' | 'danger';
+    /**
+     * danger 는 삭제처럼 되돌리기 어려운 동작.
+     * `default` 는 0.x 의 옛 이름으로 `neutral` 과 같다 — **deprecated, 1.0 에서 제거**.
+     */
+    color?: 'neutral' | 'danger' | 'default';
 }
 declare const DropdownMenuItem: react.ForwardRefExoticComponent<DropdownMenuItemProps & react.RefAttributes<HTMLDivElement>>;
 type DropdownMenuLabelProps = ComponentPropsWithoutRef<typeof RadixMenu.Label>;
@@ -891,8 +1069,10 @@ interface PopoverProps {
     className?: string;
     /** 팝오버 style (너비 지정 등) */
     style?: CSSProperties;
+    /** 열릴 때 포커스 처리. 기본은 내용의 첫 요소로 간다 — `event.preventDefault()` 후 원하는 요소에 focus() 할 수 있다 */
+    onOpenAutoFocus?: (event: Event) => void;
 }
-declare function Popover({ content, children, title, 'aria-label': ariaLabel, showClose, showArrow, side, align, open, defaultOpen, onOpenChange, modal, className, style, }: PopoverProps): react.JSX.Element;
+declare function Popover({ content, children, title, 'aria-label': ariaLabel, showClose, showArrow, side, align, open, defaultOpen, onOpenChange, modal, className, style, onOpenAutoFocus, }: PopoverProps): react.JSX.Element;
 /**
  * 팝오버 내용 안에서 누르면 팝오버를 닫는 요소.
  * @example <PopoverClose asChild><Button>확인</Button></PopoverClose>
@@ -1056,8 +1236,11 @@ declare const Slider: react.ForwardRefExoticComponent<SliderProps & react.RefAtt
 interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
     /** 크기 (sm 16px, md 20px, lg 28px) */
     size?: 'sm' | 'md' | 'lg';
-    /** 색상. `current` 는 부모 글자색을 그대로 쓴다 */
-    color?: 'current' | 'primary' | 'neutral' | 'danger';
+    /**
+     * 색상. `inherit`(기본)는 부모 글자색을 그대로 쓴다.
+     * `current` 는 0.x 의 옛 이름으로 `inherit` 와 같다 — **deprecated, 1.0 에서 제거**.
+     */
+    color?: 'inherit' | 'primary' | 'neutral' | 'danger' | 'current';
     /**
      * 스크린리더가 읽을 텍스트 (기본 "로딩 중").
      * 빈 문자열이면 장식용으로 보고 `aria-hidden` 처리한다 — 버튼처럼 바깥 요소가 이미 상태를 알릴 때 쓴다.
@@ -1137,10 +1320,10 @@ interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
     selected?: boolean;
 }
 declare const TableRow: react.ForwardRefExoticComponent<TableRowProps & react.RefAttributes<HTMLTableRowElement>>;
-type Align = 'left' | 'center' | 'right';
+type TableAlign = 'left' | 'center' | 'right';
 interface TableHeadProps extends Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'> {
     /** 정렬 */
-    align?: Align;
+    align?: TableAlign;
     /**
      * 이 열의 정렬 상태. onSort 와 함께 주면 머리 셀이 정렬 버튼이 되고 `aria-sort` 를 붙인다.
      * 정렬되지 않은 열은 'none'.
@@ -1152,7 +1335,7 @@ interface TableHeadProps extends Omit<ThHTMLAttributes<HTMLTableCellElement>, 'a
 declare const TableHead: react.ForwardRefExoticComponent<TableHeadProps & react.RefAttributes<HTMLTableCellElement>>;
 interface TableCellProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, 'align'> {
     /** 정렬 (숫자는 right 권장) */
-    align?: Align;
+    align?: TableAlign;
 }
 declare const TableCell: react.ForwardRefExoticComponent<TableCellProps & react.RefAttributes<HTMLTableCellElement>>;
 
@@ -1208,12 +1391,17 @@ interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>
 }
 declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
 
+type ToastColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
 interface ToastOptions {
     /** 제목 */
     title: ReactNode;
     /** 설명 */
     description?: ReactNode;
-    /** 의미 색상 */
+    /** 의미 색상 (기본 neutral) — Alert·Badge 의 `color` 와 같은 이름 */
+    color?: ToastColor;
+    /**
+     * @deprecated `color` 를 쓰세요 (`'default'` → `'neutral'`). 1.0 에서 제거.
+     */
     variant?: 'default' | 'success' | 'warning' | 'danger';
     /** 자동으로 닫히기까지 시간(ms). Infinity 면 자동으로 닫히지 않는다 */
     duration?: number;
@@ -1239,7 +1427,7 @@ interface ToastProviderProps {
     label?: string;
 }
 /** 앱 최상단(ThemeProvider 안쪽)에 한 번 감싸고, 하위에서 useToast() 로 토스트를 띄운다. */
-declare function ToastProvider({ children, duration, label }: ToastProviderProps): react.JSX.Element;
+declare function ToastProvider({ children, duration, label: labelProp }: ToastProviderProps): react.JSX.Element;
 declare function useToast(): ToastContextValue;
 
 interface TooltipProps {
@@ -1347,4 +1535,14 @@ declare function isValidBusinessNumber(input: string): boolean;
  */
 declare function formatKoreanAmount(amount: number, unit?: string): string;
 
-export { Accordion, AccordionItem, type AccordionItemProps, type AccordionProps, AddressInput, type AddressInputProps, type AddressProvider, type AddressSearchResult, type AddressValue, AgreementGroup, type AgreementGroupProps, type AgreementItem, Alert, type AlertProps, AmountInput, type AmountInputProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BestowTheme, Breadcrumb, type BreadcrumbItemData, type BreadcrumbProps, BusinessNumberInput, type BusinessNumberInputProps, Button, type ButtonProps, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, Checkbox, type CheckboxProps, Combobox, type ComboboxOption, type ComboboxProps, type DeepPartial, Divider, type DividerProps, Drawer, DrawerClose, type DrawerProps, DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, type DropdownMenuProps, DropdownMenuSeparator, type DropdownMenuSeparatorProps, DropdownMenuTrigger, type DropdownMenuTriggerProps, IconButton, type IconButtonProps, Input, type InputProps, type IntentName, Link, type LinkProps, Modal, ModalClose, type ModalProps, Pagination, type PaginationProps, PhoneNumberInput, type PhoneNumberInputProps, Popover, PopoverClose, type PopoverProps, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Switch, type SwitchProps, Table, TableBody, TableCell, type TableCellProps, TableFooter, TableHead, type TableHeadProps, TableHeader, type TableProps, TableRow, type TableRowProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, TextField, type TextFieldProps, Textarea, type TextareaProps, type ThemeInput, type ThemeName, type ThemeOverrides, ThemeProvider, type ThemeProviderProps, type ThemeTokens, type ToastOptions, ToastProvider, type ToastProviderProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, VerificationCodeInput, type VerificationCodeInputProps, composeExtraAddress, contrastRatio, createIntentColors, createTheme, formatBusinessNumber, formatKoreanAmount, formatPhoneNumber, hasAllRequiredAgreements, isValidBusinessNumber, kakaoPostcodeProvider, themeClass, usePortalClassName, usePortalProps, useTheme, useToast, vars };
+/** Date → 'YYYY-MM-DD' (로컬 기준) */
+declare function toISODate(date: Date): string;
+/** 'YYYY-MM-DD' → Date (로컬 자정). 형식이 틀리거나 없는 날짜(2월 30일 등)면 null */
+declare function parseISODate(value: string | null | undefined): Date | null;
+/**
+ * 한국어 날짜. 스크린리더용 날짜 이름 등에 쓴다.
+ * @example formatKoreanDate(new Date(2026, 9, 15)) // '2026년 10월 15일 목요일'
+ */
+declare function formatKoreanDate(date: Date, withWeekday?: boolean): string;
+
+export { Accordion, AccordionItem, type AccordionItemProps, type AccordionProps, AddressInput, type AddressInputProps, type AddressProvider, type AddressSearchResult, type AddressValue, AgreementGroup, type AgreementGroupProps, type AgreementItem, Alert, type AlertColor, type AlertProps, AmountInput, type AmountInputProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BestowMessages, type BestowTheme, Breadcrumb, type BreadcrumbItemData, type BreadcrumbProps, BusinessNumberInput, type BusinessNumberInputProps, Button, type ButtonProps, Calendar, type CalendarProps, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, Checkbox, type CheckboxProps, Combobox, type ComboboxOption, type ComboboxProps, DatePicker, type DatePickerProps, type DeepPartial, Divider, type DividerProps, Drawer, DrawerClose, type DrawerProps, DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, type DropdownMenuProps, DropdownMenuSeparator, type DropdownMenuSeparatorProps, DropdownMenuTrigger, type DropdownMenuTriggerProps, IconButton, type IconButtonProps, Input, type InputProps, type IntentName, Link, type LinkProps, LocaleProvider, type LocaleProviderProps, type Messages, Modal, ModalClose, type ModalProps, Pagination, type PaginationProps, PhoneNumberInput, type PhoneNumberInputProps, Popover, PopoverClose, type PopoverProps, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Switch, type SwitchProps, Table, type TableAlign, TableBody, TableCell, type TableCellProps, TableFooter, TableHead, type TableHeadProps, TableHeader, type TableProps, TableRow, type TableRowProps, type TableSize, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, TextField, type TextFieldProps, Textarea, type TextareaProps, type ThemeInput, type ThemeName, type ThemeOverrides, ThemeProvider, type ThemeProviderProps, type ThemeTokens, type ToastColor, type ToastContextValue, type ToastOptions, ToastProvider, type ToastProviderProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, VerificationCodeInput, type VerificationCodeInputProps, composeExtraAddress, contrastRatio, createIntentColors, createTheme, en, formatBusinessNumber, formatKoreanAmount, formatKoreanDate, formatPhoneNumber, hasAllRequiredAgreements, isValidBusinessNumber, kakaoPostcodeProvider, parseISODate, themeClass, toISODate, useMessages, usePortalClassName, usePortalProps, useTheme, useToast, vars };

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as _bestow_ui_tokens from '@bestow-ui/tokens';
 import { space } from '@bestow-ui/tokens';
 import * as react from 'react';
-import { HTMLAttributes, CSSProperties, ComponentPropsWithoutRef, ReactNode, InputHTMLAttributes, ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, TdHTMLAttributes, ThHTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { HTMLAttributes, CSSProperties, ReactNode, ComponentPropsWithoutRef, InputHTMLAttributes, ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, TdHTMLAttributes, ThHTMLAttributes, TextareaHTMLAttributes } from 'react';
 import * as RadixAccordion from '@radix-ui/react-accordion';
 import * as Dialog from '@radix-ui/react-dialog';
 import * as RadixMenu from '@radix-ui/react-dropdown-menu';
@@ -285,6 +285,108 @@ declare function usePortalProps(): {
  */
 declare function usePortalClassName(): string;
 
+/**
+ * 컴포넌트의 기본 문구. 모두 생략할 수 있고, 생략하면 각 컴포넌트의 한국어 기본값을 쓴다.
+ * 우선순위: 컴포넌트에 직접 준 prop > LocaleProvider 의 messages > 한국어 기본값.
+ *
+ * 한국어 기본값을 하나의 객체로 모으지 않고 각 컴포넌트에 두는 이유: 그 객체를 import 하면 Button 하나만 써도
+ * 모든 문구가 번들에 딸려 온다(Button → Spinner). 이 파일에는 타입과 Provider 만 둔다.
+ */
+interface BestowMessages {
+    /** 닫기 버튼 (Modal, Drawer, Popover, Toast, Alert) — "닫기" */
+    close: string;
+    /** Spinner — "로딩 중" */
+    loading: string;
+    /** Toast 영역 — "알림" */
+    notifications: string;
+    /** Breadcrumb — "이동 경로" */
+    breadcrumb: string;
+    /** Pagination — "페이지 탐색", "이전 페이지", "다음 페이지", "3 페이지" */
+    pagination: string;
+    paginationPrevious: string;
+    paginationNext: string;
+    paginationPage: (page: number) => string;
+    /** Link external — "(새 창)" */
+    newWindow: string;
+    /** Combobox — "결과가 없어요", "목록 열기" */
+    noResults: string;
+    openList: string;
+    /** Slider 범위 손잡이 — "최소", "최대" */
+    rangeStart: string;
+    rangeEnd: string;
+    /** AgreementGroup — "전체 동의", "필수", "선택", "보기", "접기" */
+    agreeAll: string;
+    required: string;
+    optional: string;
+    show: string;
+    hide: string;
+    /** VerificationCodeInput — "인증번호", "6자리 숫자를 입력하세요.", "재전송", "인증 시간이 지났어요. 재전송해 주세요." */
+    verificationCode: string;
+    verificationCodeHint: (length: number, type: 'numeric' | 'alphanumeric') => string;
+    resend: string;
+    verificationExpired: string;
+    /** PhoneNumberInput — "휴대폰 번호" */
+    phoneNumber: string;
+    /** BusinessNumberInput — "사업자등록번호" 와 검증 문구 */
+    businessNumber: string;
+    businessNumberInvalid: string;
+    businessNumberIncomplete: string;
+    /** AmountInput — "금액", "원" */
+    amount: string;
+    currencyUnit: string;
+    /** AddressInput */
+    address: string;
+    addressSearch: string;
+    addressSearchDescription: string;
+    postalCode: string;
+    baseAddress: string;
+    baseAddressPlaceholder: string;
+    detailAddress: string;
+    detailAddressPlaceholder: string;
+    addressLoading: string;
+    addressLoadError: string;
+    /** Calendar */
+    previousMonth: string;
+    nextMonth: string;
+    /** 달 제목 — month 는 1~12 */
+    monthTitle: (year: number, month: number) => string;
+    /** 요일 머리글 (일요일부터 7개) */
+    weekdaysShort: readonly string[];
+    /** 요일 전체 이름 (일요일부터 7개) */
+    weekdaysLong: readonly string[];
+    /** 날짜 버튼 이름 — 화면에 보이는 날짜 숫자로 시작해야 한다 (WCAG 2.5.3) */
+    dayLabel: (date: Date, weekdayLong: string) => string;
+    holiday: string;
+    today: string;
+    /** DatePicker */
+    date: string;
+    openCalendar: string;
+    calendar: string;
+    dateInvalid: string;
+    dateUnavailable: string;
+    dateIncomplete: string;
+}
+type Messages = Partial<BestowMessages>;
+interface LocaleProviderProps {
+    /** 바꿀 문구. 일부만 넘기면 나머지는 바깥 LocaleProvider 또는 한국어 기본값을 쓴다 */
+    messages: Messages;
+    children?: ReactNode;
+}
+/**
+ * 컴포넌트 기본 문구를 한곳에서 바꾼다 (다국어 대응 등). 중첩하면 바깥 값을 이어받고 안쪽이 우선한다.
+ * @example <LocaleProvider messages={en}>…</LocaleProvider>
+ * @example <LocaleProvider messages={{ close: '창 닫기' }}>…</LocaleProvider>
+ */
+declare function LocaleProvider({ messages, children }: LocaleProviderProps): react.JSX.Element;
+/** LocaleProvider 로 바꾼 문구 (없으면 빈 객체 — 각 컴포넌트가 한국어 기본값을 쓴다) */
+declare function useMessages(): Messages;
+
+/**
+ * 영어 문구. `<LocaleProvider messages={en}>` 로 쓴다. 따로 import 할 때만 번들에 들어간다.
+ * 한국 서비스 전용 부품(사업자등록번호 등)의 문구도 영어로 바뀌지만 서식(하이픈 위치 등)은 그대로다.
+ */
+declare const en: BestowMessages;
+
 /**
  * `type="single"`: 한 번에 하나만 열린다 (`value: string`). `collapsible` 이면 열린 항목을 다시 눌러 닫을 수 있다.
  * `type="multiple"`: 여러 개를 함께 열 수 있다 (`value: string[]`).
@@ -586,6 +688,36 @@ interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'col
 }
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
+interface CalendarProps {
+    /** 선택된 날짜 'YYYY-MM-DD' (제어 모드) */
+    value?: string;
+    /** 처음 선택된 날짜 (비제어 모드) */
+    defaultValue?: string;
+    /** 날짜를 고를 때 호출된다 */
+    onValueChange?: (value: string) => void;
+    /** 고를 수 있는 가장 이른 날짜 'YYYY-MM-DD' */
+    min?: string;
+    /** 고를 수 있는 가장 늦은 날짜 'YYYY-MM-DD' */
+    max?: string;
+    /** 고를 수 없는 날짜 (예: 주말 제외) */
+    isDateDisabled?: (date: Date) => boolean;
+    /** 공휴일. 일요일처럼 빨갛게 표시하고 스크린리더에 "공휴일" 을 덧붙인다 */
+    isHoliday?: (date: Date) => boolean;
+    /** 오늘 날짜 'YYYY-MM-DD'. 기본은 실제 오늘 — 테스트·스크린샷에서 고정할 때 쓴다 */
+    today?: string;
+    /** 처음 그릴 때 날짜(선택된 날짜, 없으면 오늘)로 포커스를 옮긴다 — 팝업 안에서 쓸 때 */
+    initialFocus?: boolean;
+    /** 이전·다음 달 버튼 이름 */
+    prevMonthLabel?: string;
+    nextMonthLabel?: string;
+    className?: string;
+}
+/**
+ * 달력 (WAI-ARIA grid). 일요일부터 시작하고 일요일·공휴일은 빨강, 토요일은 파랑으로 표시한다.
+ * 키보드: ←→ 하루, ↑↓ 일주일, Home/End 주의 처음·끝, PageUp/PageDown 한 달(Shift 와 함께 1년), Enter/Space 선택.
+ */
+declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<HTMLDivElement>>;
+
 interface CardProps extends HTMLAttributes<HTMLElement> {
     /** 시각적 스타일. outline 은 테두리, elevated 는 그림자(다크 모드는 가장자리 ring 포함), soft 는 옅은 배경 */
     variant?: 'outline' | 'elevated' | 'soft';
@@ -613,6 +745,8 @@ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'siz
     indeterminate?: boolean;
     /** 에러 상태 */
     invalid?: boolean;
+    /** 체크 상태가 바뀌면 호출된다 (Switch 와 같은 이름). 기본 `onChange` 도 그대로 쓸 수 있다 */
+    onCheckedChange?: (checked: boolean) => void;
 }
 declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
 
@@ -661,6 +795,47 @@ interface ComboboxProps {
  */
 declare const Combobox: react.ForwardRefExoticComponent<ComboboxProps & react.RefAttributes<HTMLInputElement>>;
 
+interface DatePickerProps {
+    /** 날짜 'YYYY-MM-DD' (제어 모드). 비어 있으면 '' */
+    value?: string;
+    /** 처음 날짜 (비제어 모드) */
+    defaultValue?: string;
+    /** 올바른 날짜를 다 입력하거나 달력에서 고르면 'YYYY-MM-DD', 지우거나 잘못되면 '' 로 호출된다 */
+    onValueChange?: (value: string) => void;
+    /** 고를 수 있는 가장 이른·늦은 날짜 'YYYY-MM-DD' */
+    min?: string;
+    max?: string;
+    /** 고를 수 없는 날짜 */
+    isDateDisabled?: (date: Date) => boolean;
+    /** 공휴일 (달력에 빨갛게 표시) */
+    isHoliday?: (date: Date) => boolean;
+    /** 오늘 날짜 'YYYY-MM-DD' (테스트·스크린샷 고정용) */
+    today?: string;
+    label?: ReactNode;
+    /** 아래 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    error?: boolean;
+    required?: boolean;
+    disabled?: boolean;
+    fullWidth?: boolean;
+    placeholder?: string;
+    /** 달력 버튼·달력 창 이름 */
+    calendarLabel?: string;
+    /** 자동 검증 문구 */
+    invalidText?: string;
+    unavailableText?: string;
+    incompleteText?: string;
+    /** form 제출 시 이름 ('YYYY-MM-DD' 가 제출된다) */
+    name?: string;
+    id?: string;
+    className?: string;
+}
+/**
+ * 날짜 입력. `YYYY-MM-DD` 로 직접 입력하거나(숫자만 쳐도 하이픈이 들어간다) 달력 버튼으로 고른다.
+ * 달력은 일요일부터 시작하고, 열면 선택된 날짜(없으면 오늘)로 포커스가 간다. 값은 시간대 문제가 없는 'YYYY-MM-DD' 문자열이다.
+ */
+declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<HTMLInputElement>>;
+
 interface DividerProps extends HTMLAttributes<HTMLDivElement> {
     /** 방향. vertical 은 flex 행 안에서 부모 높이를 채운다 */
     orientation?: 'horizontal' | 'vertical';
@@ -733,8 +908,11 @@ interface DropdownMenuItemProps extends Omit<ComponentPropsWithoutRef<typeof Rad
     icon?: ReactNode;
     /** 오른쪽에 표시할 단축키 (예: "⌘K"). 표시용이라 항목 이름에는 포함되지 않는다 */
     shortcut?: string;
-    /** danger 는 삭제처럼 되돌리기 어려운 동작 */
-    color?: 'default' | 'danger';
+    /**
+     * danger 는 삭제처럼 되돌리기 어려운 동작.
+     * `default` 는 0.x 의 옛 이름으로 `neutral` 과 같다 — **deprecated, 1.0 에서 제거**.
+     */
+    color?: 'neutral' | 'danger' | 'default';
 }
 declare const DropdownMenuItem: react.ForwardRefExoticComponent<DropdownMenuItemProps & react.RefAttributes<HTMLDivElement>>;
 type DropdownMenuLabelProps = ComponentPropsWithoutRef<typeof RadixMenu.Label>;
@@ -891,8 +1069,10 @@ interface PopoverProps {
     className?: string;
     /** 팝오버 style (너비 지정 등) */
     style?: CSSProperties;
+    /** 열릴 때 포커스 처리. 기본은 내용의 첫 요소로 간다 — `event.preventDefault()` 후 원하는 요소에 focus() 할 수 있다 */
+    onOpenAutoFocus?: (event: Event) => void;
 }
-declare function Popover({ content, children, title, 'aria-label': ariaLabel, showClose, showArrow, side, align, open, defaultOpen, onOpenChange, modal, className, style, }: PopoverProps): react.JSX.Element;
+declare function Popover({ content, children, title, 'aria-label': ariaLabel, showClose, showArrow, side, align, open, defaultOpen, onOpenChange, modal, className, style, onOpenAutoFocus, }: PopoverProps): react.JSX.Element;
 /**
  * 팝오버 내용 안에서 누르면 팝오버를 닫는 요소.
  * @example <PopoverClose asChild><Button>확인</Button></PopoverClose>
@@ -1056,8 +1236,11 @@ declare const Slider: react.ForwardRefExoticComponent<SliderProps & react.RefAtt
 interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
     /** 크기 (sm 16px, md 20px, lg 28px) */
     size?: 'sm' | 'md' | 'lg';
-    /** 색상. `current` 는 부모 글자색을 그대로 쓴다 */
-    color?: 'current' | 'primary' | 'neutral' | 'danger';
+    /**
+     * 색상. `inherit`(기본)는 부모 글자색을 그대로 쓴다.
+     * `current` 는 0.x 의 옛 이름으로 `inherit` 와 같다 — **deprecated, 1.0 에서 제거**.
+     */
+    color?: 'inherit' | 'primary' | 'neutral' | 'danger' | 'current';
     /**
      * 스크린리더가 읽을 텍스트 (기본 "로딩 중").
      * 빈 문자열이면 장식용으로 보고 `aria-hidden` 처리한다 — 버튼처럼 바깥 요소가 이미 상태를 알릴 때 쓴다.
@@ -1137,10 +1320,10 @@ interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
     selected?: boolean;
 }
 declare const TableRow: react.ForwardRefExoticComponent<TableRowProps & react.RefAttributes<HTMLTableRowElement>>;
-type Align = 'left' | 'center' | 'right';
+type TableAlign = 'left' | 'center' | 'right';
 interface TableHeadProps extends Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'> {
     /** 정렬 */
-    align?: Align;
+    align?: TableAlign;
     /**
      * 이 열의 정렬 상태. onSort 와 함께 주면 머리 셀이 정렬 버튼이 되고 `aria-sort` 를 붙인다.
      * 정렬되지 않은 열은 'none'.
@@ -1152,7 +1335,7 @@ interface TableHeadProps extends Omit<ThHTMLAttributes<HTMLTableCellElement>, 'a
 declare const TableHead: react.ForwardRefExoticComponent<TableHeadProps & react.RefAttributes<HTMLTableCellElement>>;
 interface TableCellProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, 'align'> {
     /** 정렬 (숫자는 right 권장) */
-    align?: Align;
+    align?: TableAlign;
 }
 declare const TableCell: react.ForwardRefExoticComponent<TableCellProps & react.RefAttributes<HTMLTableCellElement>>;
 
@@ -1208,12 +1391,17 @@ interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>
 }
 declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
 
+type ToastColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
 interface ToastOptions {
     /** 제목 */
     title: ReactNode;
     /** 설명 */
     description?: ReactNode;
-    /** 의미 색상 */
+    /** 의미 색상 (기본 neutral) — Alert·Badge 의 `color` 와 같은 이름 */
+    color?: ToastColor;
+    /**
+     * @deprecated `color` 를 쓰세요 (`'default'` → `'neutral'`). 1.0 에서 제거.
+     */
     variant?: 'default' | 'success' | 'warning' | 'danger';
     /** 자동으로 닫히기까지 시간(ms). Infinity 면 자동으로 닫히지 않는다 */
     duration?: number;
@@ -1239,7 +1427,7 @@ interface ToastProviderProps {
     label?: string;
 }
 /** 앱 최상단(ThemeProvider 안쪽)에 한 번 감싸고, 하위에서 useToast() 로 토스트를 띄운다. */
-declare function ToastProvider({ children, duration, label }: ToastProviderProps): react.JSX.Element;
+declare function ToastProvider({ children, duration, label: labelProp }: ToastProviderProps): react.JSX.Element;
 declare function useToast(): ToastContextValue;
 
 interface TooltipProps {
@@ -1347,4 +1535,14 @@ declare function isValidBusinessNumber(input: string): boolean;
  */
 declare function formatKoreanAmount(amount: number, unit?: string): string;
 
-export { Accordion, AccordionItem, type AccordionItemProps, type AccordionProps, AddressInput, type AddressInputProps, type AddressProvider, type AddressSearchResult, type AddressValue, AgreementGroup, type AgreementGroupProps, type AgreementItem, Alert, type AlertProps, AmountInput, type AmountInputProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BestowTheme, Breadcrumb, type BreadcrumbItemData, type BreadcrumbProps, BusinessNumberInput, type BusinessNumberInputProps, Button, type ButtonProps, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, Checkbox, type CheckboxProps, Combobox, type ComboboxOption, type ComboboxProps, type DeepPartial, Divider, type DividerProps, Drawer, DrawerClose, type DrawerProps, DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, type DropdownMenuProps, DropdownMenuSeparator, type DropdownMenuSeparatorProps, DropdownMenuTrigger, type DropdownMenuTriggerProps, IconButton, type IconButtonProps, Input, type InputProps, type IntentName, Link, type LinkProps, Modal, ModalClose, type ModalProps, Pagination, type PaginationProps, PhoneNumberInput, type PhoneNumberInputProps, Popover, PopoverClose, type PopoverProps, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Switch, type SwitchProps, Table, TableBody, TableCell, type TableCellProps, TableFooter, TableHead, type TableHeadProps, TableHeader, type TableProps, TableRow, type TableRowProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, TextField, type TextFieldProps, Textarea, type TextareaProps, type ThemeInput, type ThemeName, type ThemeOverrides, ThemeProvider, type ThemeProviderProps, type ThemeTokens, type ToastOptions, ToastProvider, type ToastProviderProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, VerificationCodeInput, type VerificationCodeInputProps, composeExtraAddress, contrastRatio, createIntentColors, createTheme, formatBusinessNumber, formatKoreanAmount, formatPhoneNumber, hasAllRequiredAgreements, isValidBusinessNumber, kakaoPostcodeProvider, themeClass, usePortalClassName, usePortalProps, useTheme, useToast, vars };
+/** Date → 'YYYY-MM-DD' (로컬 기준) */
+declare function toISODate(date: Date): string;
+/** 'YYYY-MM-DD' → Date (로컬 자정). 형식이 틀리거나 없는 날짜(2월 30일 등)면 null */
+declare function parseISODate(value: string | null | undefined): Date | null;
+/**
+ * 한국어 날짜. 스크린리더용 날짜 이름 등에 쓴다.
+ * @example formatKoreanDate(new Date(2026, 9, 15)) // '2026년 10월 15일 목요일'
+ */
+declare function formatKoreanDate(date: Date, withWeekday?: boolean): string;
+
+export { Accordion, AccordionItem, type AccordionItemProps, type AccordionProps, AddressInput, type AddressInputProps, type AddressProvider, type AddressSearchResult, type AddressValue, AgreementGroup, type AgreementGroupProps, type AgreementItem, Alert, type AlertColor, type AlertProps, AmountInput, type AmountInputProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BestowMessages, type BestowTheme, Breadcrumb, type BreadcrumbItemData, type BreadcrumbProps, BusinessNumberInput, type BusinessNumberInputProps, Button, type ButtonProps, Calendar, type CalendarProps, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, Checkbox, type CheckboxProps, Combobox, type ComboboxOption, type ComboboxProps, DatePicker, type DatePickerProps, type DeepPartial, Divider, type DividerProps, Drawer, DrawerClose, type DrawerProps, DropdownMenu, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, type DropdownMenuProps, DropdownMenuSeparator, type DropdownMenuSeparatorProps, DropdownMenuTrigger, type DropdownMenuTriggerProps, IconButton, type IconButtonProps, Input, type InputProps, type IntentName, Link, type LinkProps, LocaleProvider, type LocaleProviderProps, type Messages, Modal, ModalClose, type ModalProps, Pagination, type PaginationProps, PhoneNumberInput, type PhoneNumberInputProps, Popover, PopoverClose, type PopoverProps, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, Select, type SelectOption, type SelectProps, Skeleton, type SkeletonProps, Slider, type SliderProps, Spinner, type SpinnerProps, Stack, type StackProps, Switch, type SwitchProps, Table, type TableAlign, TableBody, TableCell, type TableCellProps, TableFooter, TableHead, type TableHeadProps, TableHeader, type TableProps, TableRow, type TableRowProps, type TableSize, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, TextField, type TextFieldProps, Textarea, type TextareaProps, type ThemeInput, type ThemeName, type ThemeOverrides, ThemeProvider, type ThemeProviderProps, type ThemeTokens, type ToastColor, type ToastContextValue, type ToastOptions, ToastProvider, type ToastProviderProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, VerificationCodeInput, type VerificationCodeInputProps, composeExtraAddress, contrastRatio, createIntentColors, createTheme, en, formatBusinessNumber, formatKoreanAmount, formatKoreanDate, formatPhoneNumber, hasAllRequiredAgreements, isValidBusinessNumber, kakaoPostcodeProvider, parseISODate, themeClass, toISODate, useMessages, usePortalClassName, usePortalProps, useTheme, useToast, vars };