@bestow-ui/react 1.0.0 → 1.2.0

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 { ReactNode, HTMLAttributes, CSSProperties, ComponentPropsWithoutRef, InputHTMLAttributes, ElementType, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, TdHTMLAttributes, ThHTMLAttributes, TextareaHTMLAttributes } from 'react';
+import { ReactNode, HTMLAttributes, ElementType, CSSProperties, ComponentPropsWithoutRef, InputHTMLAttributes, 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,16 @@ interface BestowMessages {
     /** Combobox — "결과가 없어요", "목록 열기" */
     noResults: string;
     openList: string;
+    /**
+     * Combobox clearable — "선택 지우기".
+     * 1.0 이후에 추가한 키는 선택(?)으로 둔다 — 직접 만든 BestowMessages 객체(다른 언어 묶음)가 타입 오류로 깨지지 않게.
+     */
+    clearSelection?: string;
+    /** SkipLink — "본문 바로가기" (1.0 이후 추가, 선택 키) */
+    skipToContent?: string;
+    /** NumberInput −/+ 버튼 — "줄이기", "늘리기" (1.0 이후 추가, 선택 키) */
+    decrement?: string;
+    increment?: string;
     /** Slider 범위 손잡이 — "최소", "최대" */
     rangeStart: string;
     rangeEnd: string;
@@ -440,6 +450,118 @@ interface AgreementItem {
 /** 필수 항목에 모두 동의했는지 */
 declare function hasAllRequiredAgreements(items: AgreementItem[], value: string[]): boolean;
 
+interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
+    /** 시각적 스타일 */
+    variant?: 'solid' | 'soft' | 'outline';
+    /** 의미 색상 */
+    color?: 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 텍스트 앞에 표시할 아이콘 (장식용 — 의미는 텍스트로 전달한다) */
+    startIcon?: ReactNode;
+}
+declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttributes<HTMLSpanElement>>;
+
+interface CardProps extends HTMLAttributes<HTMLElement> {
+    /** 시각적 스타일. outline 은 테두리, elevated 는 그림자(다크 모드는 가장자리 ring 포함), soft 는 옅은 배경 */
+    variant?: 'outline' | 'elevated' | 'soft';
+    /** 안쪽 여백 (sm 16px, md 24px, lg 32px). 이미지를 가장자리까지 붙이려면 none */
+    padding?: 'none' | 'sm' | 'md' | 'lg';
+    /** 렌더링할 요소 (기본 div). 목록이면 li, 독립된 콘텐츠면 article 등 */
+    as?: ElementType;
+}
+/** 배경·테두리·radius·padding 을 가진 컨테이너. 자식 사이 간격은 16px. */
+declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLElement>>;
+type CardSectionProps = HTMLAttributes<HTMLDivElement>;
+/** 제목·설명 영역. Typography 와 함께 쓴다. */
+declare const CardHeader: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
+/** 본문 영역 */
+declare const CardBody: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
+/** 버튼 등 동작 영역. 오른쪽 정렬 */
+declare const CardFooter: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
+
+interface DividerProps extends HTMLAttributes<HTMLDivElement> {
+    /** 방향. vertical 은 flex 행 안에서 부모 높이를 채운다 */
+    orientation?: 'horizontal' | 'vertical';
+    /** 시각적 구분만 하고 의미가 없으면 true — 스크린리더에서 숨긴다 */
+    decorative?: boolean;
+    /**
+     * 가운데에 표시할 텍스트 (예: "또는"). horizontal 에서만 쓴다.
+     * separator 역할의 자식은 스크린리더가 읽지 않으므로, 텍스트가 있으면 선만 숨기고 텍스트는 읽히게 둔다.
+     */
+    children?: ReactNode;
+}
+declare const Divider: react.ForwardRefExoticComponent<DividerProps & react.RefAttributes<HTMLDivElement>>;
+
+interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
+    /** 현재 값 (0 ~ max). 생략하거나 null 이면 진행률을 모르는 상태(indeterminate)로 움직이는 막대를 보여 준다 */
+    value?: number | null;
+    /** 최댓값 */
+    max?: number;
+    /** 막대 위에 보이는 레이블. progressbar 의 이름이 된다 */
+    label?: ReactNode;
+    /** 레이블이 없을 때 스크린리더용 이름 */
+    'aria-label'?: string;
+    /** 오른쪽에 값 텍스트(기본 "42%")를 보여 준다 */
+    showValue?: boolean;
+    /** 값 텍스트 형식. 화면 표시와 스크린리더(aria-valuetext)에 함께 쓴다 (예: (v, max) => `${v}/${max}개`) */
+    formatValue?: (value: number, max: number) => string;
+    /** 막대 두께 (sm 4px · md 8px · lg 12px) */
+    size?: 'sm' | 'md' | 'lg';
+    /** 의미 색상 */
+    color?: 'primary' | 'neutral' | 'success' | 'warning' | 'danger';
+}
+declare const Progress: react.ForwardRefExoticComponent<ProgressProps & react.RefAttributes<HTMLDivElement>>;
+
+interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
+    /** 모양. text 는 글자 높이(1em), circle 은 width 를 지름으로 쓴다 */
+    variant?: 'text' | 'rect' | 'circle';
+    /** 너비. 숫자는 px (기본: text·rect 100%, circle 40px) */
+    width?: number | string;
+    /** 높이. 숫자는 px (기본: text 1em, rect 100px, circle 은 width 와 같음) */
+    height?: number | string;
+    /** text 에서 여러 줄을 그린다. 마지막 줄은 60% 너비 */
+    lines?: number;
+}
+/**
+ * 콘텐츠를 불러오는 동안 자리를 표시한다. 장식용이라 스크린리더에서 숨긴다 —
+ * 로딩 중인 영역(감싸는 요소)에 `aria-busy="true"` 를 붙여 상태를 알린다.
+ */
+declare const Skeleton: react.ForwardRefExoticComponent<SkeletonProps & react.RefAttributes<HTMLSpanElement>>;
+
+interface StackProps extends HTMLAttributes<HTMLElement> {
+    /** 렌더링할 요소 */
+    as?: ElementType;
+    /** 배치 방향 */
+    direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
+    /** 자식 사이 간격 (space 토큰 키) */
+    gap?: keyof typeof space;
+    /** 교차축 정렬 (align-items) */
+    align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+    /** 주축 정렬 (justify-content) */
+    justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+    /** 줄바꿈 허용 */
+    wrap?: boolean;
+}
+declare const Stack: react.ForwardRefExoticComponent<StackProps & react.RefAttributes<HTMLElement>>;
+
+type TypographyVariant = 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'body-lg' | 'body' | 'body-sm' | 'caption';
+interface TypographyProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
+    /** 텍스트 스타일 */
+    variant?: TypographyVariant;
+    /** 렌더링할 요소. 기본값은 variant 에 따라 결정된다 (h1, p, span 등) */
+    as?: ElementType;
+    /** 글자 색상 */
+    color?: 'default' | 'muted' | 'subtle' | 'primary' | 'danger' | 'success' | 'warning' | 'inherit';
+    /** variant 의 기본 굵기를 덮어쓴다 */
+    weight?: 'regular' | 'medium' | 'semibold' | 'bold';
+    /** 정렬 */
+    align?: 'start' | 'center' | 'end';
+    /** 한 줄로 자르고 말줄임표를 표시한다 */
+    truncate?: boolean;
+}
+declare const Typography: react.ForwardRefExoticComponent<TypographyProps & react.RefAttributes<HTMLElement>>;
+
 interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
     /** 라이트/다크 모드. 생략하면 바깥 ThemeProvider 의 모드를 이어받는다 (최상위는 light). */
     theme?: ThemeName;
@@ -601,6 +723,19 @@ interface TextFieldProps extends Omit<InputProps, 'invalid'> {
     helperText?: ReactNode;
     /** 에러 상태 */
     error?: boolean;
+    /** 필수 입력 (레이블에 * 표시, required 속성) */
+    required?: boolean;
+    disabled?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    /** 입력창 앞에 표시할 요소 (아이콘, 단위 등) */
+    startAdornment?: ReactNode;
+    /** 입력창 뒤에 표시할 요소 */
+    endAdornment?: ReactNode;
+    placeholder?: string;
+    type?: InputHTMLAttributes<HTMLInputElement>['type'];
 }
 declare const TextField: react.ForwardRefExoticComponent<TextFieldProps & react.RefAttributes<HTMLInputElement>>;
 
@@ -620,6 +755,22 @@ interface AmountInputProps extends Omit<TextFieldProps, 'value' | 'defaultValue'
      * helperText 를 주면 그 아래 줄로 함께 보여 준다.
      */
     showKoreanAmount?: boolean;
+    /** 입력창 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 에러 상태 */
+    error?: boolean;
+    /** 필수 입력 (레이블에 * 표시, required 속성) */
+    required?: boolean;
+    disabled?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    placeholder?: string;
+    /** form 제출 시 사용할 이름 */
+    name?: string;
 }
 /**
  * 금액 입력. 천 단위 쉼표를 넣고 뒤에 단위("원")를 붙이며, 아래에 "12만 5,000원" 처럼 읽기 쉬운 금액을 보여 준다.
@@ -643,18 +794,6 @@ interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
 }
 declare const Avatar: react.ForwardRefExoticComponent<AvatarProps & react.RefAttributes<HTMLSpanElement>>;
 
-interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
-    /** 시각적 스타일 */
-    variant?: 'solid' | 'soft' | 'outline';
-    /** 의미 색상 */
-    color?: 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
-    /** 크기 */
-    size?: 'sm' | 'md' | 'lg';
-    /** 텍스트 앞에 표시할 아이콘 (장식용 — 의미는 텍스트로 전달한다) */
-    startIcon?: ReactNode;
-}
-declare const Badge: react.ForwardRefExoticComponent<BadgeProps & react.RefAttributes<HTMLSpanElement>>;
-
 interface BreadcrumbItemData {
     /** 표시할 이름 */
     label: ReactNode;
@@ -693,6 +832,22 @@ interface BusinessNumberInputProps extends Omit<TextFieldProps, 'value' | 'defau
     validate?: boolean;
     /** 자동 검증 오류 문구 */
     invalidText?: string;
+    /** 입력창 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 에러 상태 */
+    error?: boolean;
+    /** 필수 입력 (레이블에 * 표시, required 속성) */
+    required?: boolean;
+    disabled?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    placeholder?: string;
+    /** form 제출 시 사용할 이름 */
+    name?: string;
 }
 /**
  * 사업자등록번호 입력. 123-45-67890 형식으로 하이픈을 넣고, 10자리를 채우면 검증 공식으로 확인한다.
@@ -755,24 +910,6 @@ interface CalendarProps {
  */
 declare const Calendar: react.ForwardRefExoticComponent<CalendarProps & react.RefAttributes<HTMLDivElement>>;
 
-interface CardProps extends HTMLAttributes<HTMLElement> {
-    /** 시각적 스타일. outline 은 테두리, elevated 는 그림자(다크 모드는 가장자리 ring 포함), soft 는 옅은 배경 */
-    variant?: 'outline' | 'elevated' | 'soft';
-    /** 안쪽 여백 (sm 16px, md 24px, lg 32px). 이미지를 가장자리까지 붙이려면 none */
-    padding?: 'none' | 'sm' | 'md' | 'lg';
-    /** 렌더링할 요소 (기본 div). 목록이면 li, 독립된 콘텐츠면 article 등 */
-    as?: ElementType;
-}
-/** 배경·테두리·radius·padding 을 가진 컨테이너. 자식 사이 간격은 16px. */
-declare const Card: react.ForwardRefExoticComponent<CardProps & react.RefAttributes<HTMLElement>>;
-type CardSectionProps = HTMLAttributes<HTMLDivElement>;
-/** 제목·설명 영역. Typography 와 함께 쓴다. */
-declare const CardHeader: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
-/** 본문 영역 */
-declare const CardBody: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
-/** 버튼 등 동작 영역. 오른쪽 정렬 */
-declare const CardFooter: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
-
 interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
     /** 체크박스 옆에 표시할 레이블 */
     label?: ReactNode;
@@ -823,6 +960,13 @@ interface ComboboxProps {
     'aria-label'?: string;
     /** 목록 열기 버튼의 이름 */
     toggleLabel?: string;
+    /**
+     * 값이 있을 때 "선택 지우기" 버튼을 보여 준다. 버튼이 없어도 입력창 글자를 모두 지우고 닫으면(포커스 이동·Esc·Enter) 선택이 지워진다.
+     * 지우면 `onValueChange('')` 가 호출된다.
+     */
+    clearable?: boolean;
+    /** "선택 지우기" 버튼의 이름 */
+    clearLabel?: string;
     /** 입력창 래퍼 className */
     className?: string;
 }
@@ -873,19 +1017,6 @@ interface DatePickerProps {
  */
 declare const DatePicker: react.ForwardRefExoticComponent<DatePickerProps & react.RefAttributes<HTMLInputElement>>;
 
-interface DividerProps extends HTMLAttributes<HTMLDivElement> {
-    /** 방향. vertical 은 flex 행 안에서 부모 높이를 채운다 */
-    orientation?: 'horizontal' | 'vertical';
-    /** 시각적 구분만 하고 의미가 없으면 true — 스크린리더에서 숨긴다 */
-    decorative?: boolean;
-    /**
-     * 가운데에 표시할 텍스트 (예: "또는"). horizontal 에서만 쓴다.
-     * separator 역할의 자식은 스크린리더가 읽지 않으므로, 텍스트가 있으면 선만 숨기고 텍스트는 읽히게 둔다.
-     */
-    children?: ReactNode;
-}
-declare const Divider: react.ForwardRefExoticComponent<DividerProps & react.RefAttributes<HTMLDivElement>>;
-
 interface DrawerProps {
     /** 열림 상태 (제어 모드) */
     open?: boolean;
@@ -954,6 +1085,41 @@ type DropdownMenuLabelProps = ComponentPropsWithoutRef<typeof RadixMenu.Label>;
 declare const DropdownMenuLabel: react.ForwardRefExoticComponent<Omit<RadixMenu.DropdownMenuLabelProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 type DropdownMenuSeparatorProps = ComponentPropsWithoutRef<typeof RadixMenu.Separator>;
 declare const DropdownMenuSeparator: react.ForwardRefExoticComponent<Omit<RadixMenu.DropdownMenuSeparatorProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
+interface DropdownMenuCheckboxItemProps extends ComponentPropsWithoutRef<typeof RadixMenu.CheckboxItem> {
+    /** 켜짐 여부. `'indeterminate'` 는 일부만 선택된 상태(− 표시) */
+    checked?: boolean | 'indeterminate';
+    /** 상태가 바뀔 때 */
+    onCheckedChange?: (checked: boolean) => void;
+}
+/**
+ * 켜고 끄는 항목 (role="menuitemcheckbox" + aria-checked). 기본으로 고르면 메뉴가 닫힌다 —
+ * 여러 개를 이어서 바꾸게 하려면 `onSelect={(e) => e.preventDefault()}` 로 열어 둔다.
+ */
+declare const DropdownMenuCheckboxItem: react.ForwardRefExoticComponent<DropdownMenuCheckboxItemProps & react.RefAttributes<HTMLDivElement>>;
+/**
+ * 하나만 고르는 항목 묶음 (role="group"). 안에 `DropdownMenuRadioItem` 을 둔다.
+ * 선택 상태를 스스로 갖지 않는다 — 항상 `value` + `onValueChange` 로 제어한다.
+ */
+declare const DropdownMenuRadioGroup: react.ForwardRefExoticComponent<RadixMenu.DropdownMenuRadioGroupProps & react.RefAttributes<HTMLDivElement>>;
+type DropdownMenuRadioGroupProps = ComponentPropsWithoutRef<typeof RadixMenu.RadioGroup>;
+interface DropdownMenuRadioItemProps extends ComponentPropsWithoutRef<typeof RadixMenu.RadioItem> {
+    /** 이 항목을 고르면 RadioGroup 의 value 가 된다 */
+    value: string;
+}
+/** 묶음 안에서 하나만 고르는 항목 (role="menuitemradio" + aria-checked) */
+declare const DropdownMenuRadioItem: react.ForwardRefExoticComponent<DropdownMenuRadioItemProps & react.RefAttributes<HTMLDivElement>>;
+/** 하위 메뉴 루트. `open`/`defaultOpen`/`onOpenChange` 를 받는다 */
+declare const DropdownMenuSub: react.FC<RadixMenu.DropdownMenuSubProps>;
+type DropdownMenuSubProps = ComponentPropsWithoutRef<typeof RadixMenu.Sub>;
+interface DropdownMenuSubTriggerProps extends ComponentPropsWithoutRef<typeof RadixMenu.SubTrigger> {
+    /** 텍스트 앞 아이콘 (장식용) */
+    icon?: ReactNode;
+}
+/** 하위 메뉴를 여는 항목. → 또는 Enter·Space 로 열고 ← 로 닫는다 (오른쪽 화살표 표시는 장식) */
+declare const DropdownMenuSubTrigger: react.ForwardRefExoticComponent<DropdownMenuSubTriggerProps & react.RefAttributes<HTMLDivElement>>;
+type DropdownMenuSubContentProps = ComponentPropsWithoutRef<typeof RadixMenu.SubContent>;
+/** 하위 메뉴 목록. 부모 메뉴처럼 portal 로 그리고 테마를 이어받는다 */
+declare const DropdownMenuSubContent: react.ForwardRefExoticComponent<Omit<RadixMenu.DropdownMenuSubContentProps & react.RefAttributes<HTMLDivElement>, "ref"> & react.RefAttributes<HTMLDivElement>>;
 
 interface IconButtonProps extends Omit<ButtonProps, 'startIcon' | 'endIcon' | 'fullWidth' | 'children' | 'variant' | 'color' | 'size' | 'loading'> {
     /** 시각적 스타일 (기본 ghost) */
@@ -1039,6 +1205,52 @@ declare function Modal({ open, defaultOpen, onOpenChange, trigger, title, descri
  */
 declare const ModalClose: react.ForwardRefExoticComponent<Dialog.DialogCloseProps & react.RefAttributes<HTMLButtonElement>>;
 
+interface NumberInputProps extends Omit<TextFieldProps, 'value' | 'defaultValue' | 'onChange' | 'type' | 'inputMode' | 'startAdornment' | 'endAdornment' | 'min' | 'max' | 'step' | 'role'> {
+    /** 값 (제어 모드). 비어 있으면 null */
+    value?: number | null;
+    /** 처음 값 (비제어 모드) */
+    defaultValue?: number | null;
+    /** 값이 바뀔 때 호출된다. 비우면 null. 입력 중에는 범위를 벗어난 값도 오고, 포커스가 빠질 때 범위 안으로 맞춘 값이 온다 */
+    onValueChange?: (value: number | null) => void;
+    /** 최솟값. 0 이상이면 "-" 를 입력할 수 없다 */
+    min?: number;
+    /** 최댓값 */
+    max?: number;
+    /** ↑/↓·버튼으로 바꾸는 단위 (기본 1) */
+    step?: number;
+    /** PageUp/PageDown 으로 바꾸는 단위 (기본 step × 10) */
+    largeStep?: number;
+    /** 소수 자릿수 (기본: step 의 소수 자릿수 — step 0.1 이면 1). 0 이면 정수만 */
+    precision?: number;
+    /** 단위 (입력창 뒤에 표시, 스크린리더 값에도 붙는다 — 예: "개", "명") */
+    unit?: string;
+    /** 천 단위 쉼표 (기본 true) */
+    thousandSeparator?: boolean;
+    /** −/+ 버튼을 숨긴다 (키보드 ↑/↓ 는 그대로) */
+    hideStepper?: boolean;
+    /** 입력창 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 에러 상태 */
+    error?: boolean;
+    /** 필수 입력 (레이블에 * 표시, required 속성) */
+    required?: boolean;
+    disabled?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    placeholder?: string;
+    /** form 제출 시 사용할 이름 (쉼표 없는 숫자로 제출된다) */
+    name?: string;
+}
+/**
+ * 숫자 입력 (수량·인원·나이 등). −/+ 버튼, ↑/↓·PageUp/PageDown 으로 바꾸고, 천 단위 쉼표를 넣는다.
+ * WAI-ARIA spinbutton 패턴 — 스크린리더가 현재 값·최소·최대를 읽는다. 금액은 AmountInput(한글 금액 읽기)을 쓴다.
+ */
+declare const NumberInput: react.ForwardRefExoticComponent<NumberInputProps & react.RefAttributes<HTMLInputElement>>;
+
 /** getItemLabel 이 이름을 만드는 버튼 종류 */
 type PaginationItemType = 'previous' | 'next' | 'page';
 interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
@@ -1068,6 +1280,22 @@ interface PhoneNumberInputProps extends Omit<TextFieldProps, 'value' | 'defaultV
     defaultValue?: string;
     /** 숫자만 있는 값으로 호출된다 (하이픈 없음) */
     onValueChange?: (digits: string) => void;
+    /** 입력창 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 에러 상태 */
+    error?: boolean;
+    /** 필수 입력 (레이블에 * 표시, required 속성) */
+    required?: boolean;
+    disabled?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    placeholder?: string;
+    /** form 제출 시 사용할 이름 */
+    name?: string;
 }
 /**
  * 전화번호 입력. 입력하는 대로 하이픈을 넣고(010-1234-5678, 02-123-4567, 1588-1234), 값은 숫자만 넘긴다.
@@ -1114,26 +1342,6 @@ declare function Popover({ content, children, title, 'aria-label': ariaLabel, sh
  */
 declare const PopoverClose: react.ForwardRefExoticComponent<RadixPopover.PopoverCloseProps & react.RefAttributes<HTMLButtonElement>>;
 
-interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
-    /** 현재 값 (0 ~ max). 생략하거나 null 이면 진행률을 모르는 상태(indeterminate)로 움직이는 막대를 보여 준다 */
-    value?: number | null;
-    /** 최댓값 */
-    max?: number;
-    /** 막대 위에 보이는 레이블. progressbar 의 이름이 된다 */
-    label?: ReactNode;
-    /** 레이블이 없을 때 스크린리더용 이름 */
-    'aria-label'?: string;
-    /** 오른쪽에 값 텍스트(기본 "42%")를 보여 준다 */
-    showValue?: boolean;
-    /** 값 텍스트 형식. 화면 표시와 스크린리더(aria-valuetext)에 함께 쓴다 (예: (v, max) => `${v}/${max}개`) */
-    formatValue?: (value: number, max: number) => string;
-    /** 막대 두께 (sm 4px · md 8px · lg 12px) */
-    size?: 'sm' | 'md' | 'lg';
-    /** 의미 색상 */
-    color?: 'primary' | 'neutral' | 'success' | 'warning' | 'danger';
-}
-declare const Progress: react.ForwardRefExoticComponent<ProgressProps & react.RefAttributes<HTMLDivElement>>;
-
 interface RadioOption {
     value: string;
     label: ReactNode;
@@ -1170,8 +1378,56 @@ interface RadioGroupProps {
     /** 바깥 래퍼 className */
     className?: string;
 }
+/**
+ * 여러 선택지 중 하나를 고르는 라디오 버튼 묶음.
+ *
+ * 네이티브 `<input type="radio">` 로 만든다 — 화살표 이동·선택, Tab 으로 들어오기, 비활성 건너뛰기, 폼 제출·`required` 검증을
+ * 브라우저가 처리한다. (1.1 까지는 Radix RadioGroup 이었는데, Radix 는 "포커스가 옮겨질 때 화살표 키가 아직 눌려 있는지" 로
+ * 선택을 정해서 키를 바로 떼는 입력(자동화·일부 보조기기)에서는 포커스만 옮겨지고 선택이 빠졌다 — E2E 에서 20회 중 19회.)
+ */
 declare const RadioGroup: react.ForwardRefExoticComponent<RadioGroupProps & react.RefAttributes<HTMLDivElement>>;
 
+interface SegmentedControlOption {
+    value: string;
+    /** 칸에 보이는 글자 (접근 가능한 이름이 된다) */
+    label: ReactNode;
+    /** 글자 앞 아이콘 (장식용) */
+    icon?: ReactNode;
+    disabled?: boolean;
+}
+interface SegmentedControlProps {
+    /** 선택지 (2~5개 권장 — 많으면 Select 를 쓴다) */
+    options: SegmentedControlOption[];
+    /** 선택된 값 (제어 모드) */
+    value?: string;
+    /** 처음 선택된 값 (비제어 모드) */
+    defaultValue?: string;
+    /** 값이 바뀔 때 호출된다 */
+    onValueChange?: (value: string) => void;
+    /** 위에 보이는 레이블. 없으면 aria-label 로 이름을 준다 */
+    label?: ReactNode;
+    /** label 이 없을 때 스크린리더용 이름 (예: "기간") */
+    'aria-label'?: string;
+    /** 크기 — 전체 높이가 Button·Input 과 같다 (sm 32 / md 40 / lg 48) */
+    size?: 'sm' | 'md' | 'lg';
+    /** 부모 너비를 꽉 채우고 칸을 같은 너비로 나눈다 */
+    fullWidth?: boolean;
+    disabled?: boolean;
+    /** form 제출 시 사용할 이름 */
+    name?: string;
+    id?: string;
+    className?: string;
+}
+/**
+ * 여러 값 중 하나를 고르는 칸 묶음 (기간 일/주/월, 보기 방식 등).
+ * 의미는 라디오 그룹과 같다(WAI-ARIA radiogroup): Tab 으로 그룹에 들어가면 선택된 칸, 화살표로 옮기면 바로 선택된다.
+ * 선택에 따라 아래 내용이 바뀌는 "패널" 이 있으면 Tabs 를 쓴다.
+ *
+ * Radix RadioGroup 을 쓰지 않고 직접 구현한다 — Radix 는 "포커스가 옮겨질 때 화살표 키가 아직 눌려 있는지" 로 선택을 정해서
+ * 키를 아주 빨리 떼는 입력(자동화·일부 보조기기)에서는 포커스만 옮겨지고 선택이 안 되는 경우가 있었다(E2E 에서 약 20%).
+ */
+declare const SegmentedControl: react.ForwardRefExoticComponent<SegmentedControlProps & react.RefAttributes<HTMLDivElement>>;
+
 interface SelectOption {
     value: string;
     label: ReactNode;
@@ -1210,21 +1466,22 @@ interface SelectProps {
 }
 declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
 
-interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
-    /** 모양. text 는 글자 높이(1em), circle 은 width 를 지름으로 쓴다 */
-    variant?: 'text' | 'rect' | 'circle';
-    /** 너비. 숫자는 px (기본: text·rect 100%, circle 40px) */
-    width?: number | string;
-    /** 높이. 숫자는 px (기본: text 1em, rect 100px, circle 은 width 와 같음) */
-    height?: number | string;
-    /** text 에서 여러 줄을 그린다. 마지막 줄은 60% 너비 */
-    lines?: number;
+interface SkipLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** 건너뛸 곳(본문)의 id 를 가리키는 주소. 기본 "#main" — 본문 요소에 id="main" 을 준다 */
+    href?: string;
 }
 /**
- * 콘텐츠를 불러오는 동안 자리를 표시한다. 장식용이라 스크린리더에서 숨긴다 —
- * 로딩 중인 영역(감싸는 요소)에 `aria-busy="true"` 를 붙여 상태를 알린다.
+ * 본문 바로가기 (KWCAG 2.2 6.4.1 반복 영역 건너뛰기 / WCAG 2.4.1).
+ * 페이지 맨 앞(머리글·메뉴보다 먼저)에 둔다. 평소에는 보이지 않고, 첫 Tab 에 왼쪽 위에 나타난다.
+ * 누르면 본문으로 포커스를 옮긴다 — 본문 요소가 원래 포커스를 받지 못하면 tabindex="-1" 을 붙여 옮긴다
+ * (주소의 #만 바꾸면 일부 브라우저·SPA 라우터에서 포커스가 그대로 남는다).
+ *
+ * @example
+ * <SkipLink />            // "본문 바로가기" → #main
+ * <Header />
+ * <main id="main">…</main>
  */
-declare const Skeleton: react.ForwardRefExoticComponent<SkeletonProps & react.RefAttributes<HTMLSpanElement>>;
+declare const SkipLink: react.ForwardRefExoticComponent<SkipLinkProps & react.RefAttributes<HTMLAnchorElement>>;
 
 interface SliderProps {
     /** 값 (제어 모드). 손잡이 하나면 `[50]`, 범위면 `[20, 80]` */
@@ -1281,22 +1538,6 @@ interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
 }
 declare const Spinner: react.ForwardRefExoticComponent<SpinnerProps & react.RefAttributes<HTMLSpanElement>>;
 
-interface StackProps extends HTMLAttributes<HTMLElement> {
-    /** 렌더링할 요소 */
-    as?: ElementType;
-    /** 배치 방향 */
-    direction?: 'row' | 'column' | 'row-reverse' | 'column-reverse';
-    /** 자식 사이 간격 (space 토큰 키) */
-    gap?: keyof typeof space;
-    /** 교차축 정렬 (align-items) */
-    align?: 'start' | 'center' | 'end' | 'stretch' | 'baseline';
-    /** 주축 정렬 (justify-content) */
-    justify?: 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
-    /** 줄바꿈 허용 */
-    wrap?: boolean;
-}
-declare const Stack: react.ForwardRefExoticComponent<StackProps & react.RefAttributes<HTMLElement>>;
-
 interface SwitchProps {
     /** 스위치 옆에 표시할 레이블 */
     label?: ReactNode;
@@ -1371,7 +1612,7 @@ interface TableCellProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, 'a
 }
 declare const TableCell: react.ForwardRefExoticComponent<TableCellProps & react.RefAttributes<HTMLTableCellElement>>;
 
-interface TabsProps extends Omit<ComponentPropsWithoutRef<typeof RadixTabs.Root>, 'orientation'> {
+interface TabsProps extends ComponentPropsWithoutRef<typeof RadixTabs.Root> {
     /** 시각적 스타일. line 은 밑줄, soft 는 배경이 있는 세그먼트 */
     variant?: 'line' | 'soft';
     /** 크기 */
@@ -1387,6 +1628,11 @@ interface TabsProps extends Omit<ComponentPropsWithoutRef<typeof RadixTabs.Root>
      * manual: 방향키로 포커스만 옮기고 Enter/Space 로 선택한다 (탭 전환 비용이 클 때).
      */
     activationMode?: 'automatic' | 'manual';
+    /**
+     * horizontal(기본): 탭 목록이 위, ←/→ 로 이동.
+     * vertical: 탭 목록이 왼쪽(내용은 오른쪽), ↑/↓ 로 이동. 탭이 많거나 이름이 길 때(설정 화면 등).
+     */
+    orientation?: 'horizontal' | 'vertical';
 }
 declare const Tabs: react.ForwardRefExoticComponent<TabsProps & react.RefAttributes<HTMLDivElement>>;
 type TabsListProps = ComponentPropsWithoutRef<typeof RadixTabs.List>;
@@ -1482,23 +1728,6 @@ interface TooltipProps {
 }
 declare function Tooltip({ content, children, side, align, delay, open, defaultOpen, onOpenChange, disabled, className, }: TooltipProps): react.JSX.Element;
 
-type TypographyVariant = 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'body-lg' | 'body' | 'body-sm' | 'caption';
-interface TypographyProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
-    /** 텍스트 스타일 */
-    variant?: TypographyVariant;
-    /** 렌더링할 요소. 기본값은 variant 에 따라 결정된다 (h1, p, span 등) */
-    as?: ElementType;
-    /** 글자 색상 */
-    color?: 'default' | 'muted' | 'subtle' | 'primary' | 'danger' | 'success' | 'warning' | 'inherit';
-    /** variant 의 기본 굵기를 덮어쓴다 */
-    weight?: 'regular' | 'medium' | 'semibold' | 'bold';
-    /** 정렬 */
-    align?: 'start' | 'center' | 'end';
-    /** 한 줄로 자르고 말줄임표를 표시한다 */
-    truncate?: boolean;
-}
-declare const Typography: react.ForwardRefExoticComponent<TypographyProps & react.RefAttributes<HTMLElement>>;
-
 interface VerificationCodeInputProps {
     /** 자릿수 */
     length?: number;
@@ -1538,4 +1767,4 @@ interface VerificationCodeInputProps {
  */
 declare const VerificationCodeInput: react.ForwardRefExoticComponent<VerificationCodeInputProps & react.RefAttributes<HTMLInputElement>>;
 
-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 PaginationItemType, 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, usePortalProps, useTheme, useToast, vars };
+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, DropdownMenuCheckboxItem, type DropdownMenuCheckboxItemProps, DropdownMenuContent, type DropdownMenuContentProps, DropdownMenuGroup, DropdownMenuItem, type DropdownMenuItemProps, DropdownMenuLabel, type DropdownMenuLabelProps, type DropdownMenuProps, DropdownMenuRadioGroup, type DropdownMenuRadioGroupProps, DropdownMenuRadioItem, type DropdownMenuRadioItemProps, DropdownMenuSeparator, type DropdownMenuSeparatorProps, DropdownMenuSub, DropdownMenuSubContent, type DropdownMenuSubContentProps, type DropdownMenuSubProps, DropdownMenuSubTrigger, type DropdownMenuSubTriggerProps, DropdownMenuTrigger, type DropdownMenuTriggerProps, IconButton, type IconButtonProps, Input, type InputProps, type IntentName, Link, type LinkProps, LocaleProvider, type LocaleProviderProps, type Messages, Modal, ModalClose, type ModalProps, NumberInput, type NumberInputProps, Pagination, type PaginationItemType, type PaginationProps, PhoneNumberInput, type PhoneNumberInputProps, Popover, PopoverClose, type PopoverProps, Progress, type ProgressProps, RadioGroup, type RadioGroupProps, type RadioOption, SegmentedControl, type SegmentedControlOption, type SegmentedControlProps, Select, type SelectOption, type SelectProps, Skeleton, type SkeletonProps, SkipLink, type SkipLinkProps, 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, usePortalProps, useTheme, useToast, vars };