@bestow-ui/react 1.6.1 → 1.8.0

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import * as _bestow_ui_tokens from '@bestow-ui/tokens';
 import { space } from '@bestow-ui/tokens';
 import * as react from 'react';
-import { ReactNode, HTMLAttributes, ElementType, CSSProperties, ComponentPropsWithoutRef, InputHTMLAttributes, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, SelectHTMLAttributes, OlHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, ChangeEvent, TextareaHTMLAttributes } from 'react';
-export { composeExtraAddress, formatBusinessNumber, formatKoreanAmount, formatKoreanDate, formatPhoneNumber, isValidBusinessNumber } from '@bestow-ui/korean-utils';
+import { ReactNode, HTMLAttributes, ElementType, CSSProperties, ComponentPropsWithoutRef, InputHTMLAttributes, ButtonHTMLAttributes, AnchorHTMLAttributes, ReactElement, FocusEvent, SelectHTMLAttributes, OlHTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, ChangeEvent, TextareaHTMLAttributes } from 'react';
+export { ResidentNumberInfo, composeExtraAddress, formatBusinessNumber, formatKoreanAmount, formatKoreanDate, formatPhoneNumber, formatResidentNumber, isValidBusinessNumber, isValidResidentNumber, maskCardNumber, maskDigits, maskName, maskPhoneNumber, maskResidentNumber, parseResidentNumber } from '@bestow-ui/korean-utils';
 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';
@@ -10,7 +10,7 @@ import * as RadixPopover from '@radix-ui/react-popover';
 import * as RadixTabs from '@radix-ui/react-tabs';
 
 declare const lightTokens: {
-    color: _bestow_ui_tokens.SemanticColors;
+    color: _bestow_ui_tokens.DefaultSemanticColors;
     shadow: {
         readonly sm: "0 1px 2px rgba(0, 0, 0, 0.06)";
         readonly md: "0 4px 12px rgba(0, 0, 0, 0.08)";
@@ -161,6 +161,14 @@ declare const vars: {
             subtleHover: `var(--${string})`;
             text: `var(--${string})`;
         };
+        info: {
+            solid: `var(--${string})`;
+            solidHover: `var(--${string})`;
+            contrast: `var(--${string})`;
+            subtle: `var(--${string})`;
+            subtleHover: `var(--${string})`;
+            text: `var(--${string})`;
+        };
     };
     shadow: {
         readonly sm: `var(--${string})`;
@@ -233,6 +241,8 @@ declare const themeClass: {
     dark: string;
 };
 type ThemeName = keyof typeof themeClass;
+/** ThemeProvider 의 `theme`. `'system'` 은 OS 의 라이트·다크 설정을 따른다(바꾸면 바로 반영). */
+type ThemeMode = ThemeName | 'system';
 
 type DeepPartial<T> = {
     [K in keyof T]?: T[K] extends string ? string : DeepPartial<T[K]>;
@@ -263,7 +273,7 @@ declare function createTheme(...inputs: ThemeInput[]): BestowTheme;
 
 /** WCAG 대비율 (1 ~ 21) */
 declare function contrastRatio(a: string, b: string): number;
-type IntentName = 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
+type IntentName = 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
 /**
  * 대표색 하나로 intent(primary 등)의 라이트·다크 색 세트를 만든다. 결과는 createTheme 에 넘긴다.
  * - solid 는 넘긴 색을 그대로 쓴다 (다크모드에서 너무 어두우면 조금 밝힌다). 단 흰 글자·짙은 글자 모두
@@ -325,6 +335,7 @@ interface BestowMessages {
     /** Stepper — 목록 이름 "진행 단계", 완료한 단계에 붙는 "완료" (1.0 이후 추가, 선택 키) */
     steps?: string;
     stepCompleted?: string;
+    stepInProgress?: string;
     /**
      * FileUpload (1.0 이후 추가, 선택 키) — "파일 선택", "또는 여기로 끌어다 놓으세요", "선택한 파일", "○○ 삭제",
      * "파일 2개 선택됨", "○○ 삭제됨", 크기·형식·개수 초과 안내
@@ -364,6 +375,14 @@ interface BestowMessages {
     businessNumber: string;
     businessNumberInvalid: string;
     businessNumberIncomplete: string;
+    /** ResidentNumberInput — "주민등록번호", 두 칸의 이름, 검증 문구 (1.0 이후 추가, 선택 키) */
+    residentNumber?: string;
+    residentNumberFront?: string;
+    residentNumberBack?: string;
+    /** 앞 7자리만 받을 때 뒷칸 이름 — "뒷자리 첫 숫자" */
+    residentNumberBackFirst?: string;
+    residentNumberInvalid?: string;
+    residentNumberIncomplete?: (digits: number) => string;
     /** AmountInput — "금액", "원" */
     amount: string;
     currencyUnit: string;
@@ -425,6 +444,31 @@ declare function toISODate(date: Date): string;
 /** 'YYYY-MM-DD' → Date (로컬 자정). 형식이 틀리거나 없는 날짜(2월 30일 등)면 null */
 declare function parseISODate(value: string | null | undefined): Date | null;
 
+/**
+ * 반응형 구간 미디어쿼리(모바일 우선 min-width). `@bestow-ui/tokens` 의 breakpoint(px)를 em 으로 바꾼 값 —
+ * em 이라 브라우저 기본 글꼴 크기를 키우면 구간도 따라 바뀐다. 값을 직접 적는다(최상위에서 tokens 객체 속성을 읽으면
+ * tokens 전체가 번들에 딸려 온다 — responsive.test.ts 가 tokens 와 같은지 확인).
+ *
+ * @example style({ flexDirection: 'column', '@media': { [media.md]: { flexDirection: 'row' } } }) // vanilla-extract
+ */
+declare const media: {
+    readonly sm: "(min-width: 40em)";
+    readonly md: "(min-width: 48em)";
+    readonly lg: "(min-width: 64em)";
+    readonly xl: "(min-width: 80em)";
+};
+type Breakpoint = keyof typeof media;
+/**
+ * 한 값 또는 구간별 값. 구간 값은 그 폭 이상에서 쓰이고, 주지 않은 구간은 앞(좁은) 구간 값을 이어받는다.
+ *
+ * @example direction={{ base: 'column', md: 'row' }} // 768px 미만은 세로, 이상은 가로
+ */
+type Responsive<T> = T | ({
+    base?: T;
+} & {
+    [K in Breakpoint]?: T;
+});
+
 /** 주소 검색 결과 */
 interface AddressSearchResult {
     /** 우편번호 (5자리 국가기초구역번호) */
@@ -461,8 +505,8 @@ declare function hasAllRequiredAgreements(items: AgreementItem[], value: string[
 interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
     /** 시각적 스타일 */
     variant?: 'solid' | 'soft' | 'outline';
-    /** 의미 색상 */
-    color?: 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
+    /** 의미 색상. 일반 안내는 info (브랜드 색과 따로 파랑) */
+    color?: 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
     /** 크기 */
     size?: 'sm' | 'md' | 'lg';
     /** 텍스트 앞에 표시할 아이콘 (장식용 — 의미는 텍스트로 전달한다) */
@@ -488,6 +532,17 @@ declare const CardBody: react.ForwardRefExoticComponent<CardSectionProps & react
 /** 버튼 등 동작 영역. 오른쪽 정렬 */
 declare const CardFooter: react.ForwardRefExoticComponent<CardSectionProps & react.RefAttributes<HTMLDivElement>>;
 
+interface ContainerProps extends HTMLAttributes<HTMLElement> {
+    /** 렌더링할 요소 (페이지 본문이면 'main') */
+    as?: ElementType;
+    /** 최대 폭 — sm 640 · md 768 · lg 1024(기본) · xl 1280px(구간 폭과 같음, 기본 글꼴 크기를 따름), full 은 제한 없음 */
+    size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+    /** 좌우 여백을 없앤다 (기본은 좁은 화면 16px, md 구간부터 24px) */
+    flush?: boolean;
+}
+/** 내용을 가운데에 두고 최대 폭과 좌우 여백을 정하는 페이지 틀 */
+declare const Container: react.ForwardRefExoticComponent<ContainerProps & react.RefAttributes<HTMLElement>>;
+
 interface DescriptionListItem {
     /** 이름 (dt) */
     term: ReactNode;
@@ -540,6 +595,64 @@ interface DividerProps extends HTMLAttributes<HTMLDivElement> {
 }
 declare const Divider: react.ForwardRefExoticComponent<DividerProps & react.RefAttributes<HTMLDivElement>>;
 
+/**
+ * FormField 가 자식에게 넘기는 연결 속성. 입력 요소(또는 입력 역할을 하는 요소)에 그대로 펼쳐 넣는다.
+ * role="group" 처럼 aria-invalid·aria-required 를 받지 못하는 역할이면 그 둘은 빼고 안의 컨트롤에 준다(axe aria-allowed-attr).
+ */
+interface FormFieldControlProps {
+    id: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: true;
+    'aria-required'?: true;
+}
+/** render 함수의 둘째 인자 — 입력에 펼치지 않는 정보 */
+interface FormFieldMeta {
+    /** 레이블 요소의 id — label 로 이름을 받을 수 없는 요소(div role="combobox" 등)는 aria-labelledby 에 넣는다 */
+    labelId?: string;
+    /** 도움말 요소의 id */
+    helperId?: string;
+}
+interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'id'> {
+    /** 입력 위에 표시할 레이블 (짧게 — 보조 설명은 helperText) */
+    label?: ReactNode;
+    /** 입력 아래 도움말. error 일 때는 오류 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 오류 상태 — 자식에 aria-invalid 를 넘기고 helperText 를 오류 색으로 */
+    error?: boolean;
+    /** 필수 — 레이블에 * 를 붙이고 자식에 aria-required 를 넘긴다(네이티브 검증이 필요하면 입력에 required 를 직접) */
+    required?: boolean;
+    /** 입력 요소의 id. 생략하면 만든다 (ErrorSummary 링크·focusField 가 이 id 로 찾아간다) */
+    id?: string;
+    /** 부모 너비를 꽉 채운다 */
+    fullWidth?: boolean;
+    /**
+     * 입력을 그리는 함수. 첫째 인자를 입력 요소에 그대로 펼쳐 넣는다.
+     * @example {(field) => <input {...field} />}
+     * @example {(field, { labelId }) => <CustomSelect {...field} aria-labelledby={labelId} />}
+     */
+    children: (control: FormFieldControlProps, meta: FormFieldMeta) => ReactNode;
+}
+/**
+ * 직접 만든 입력·다른 라이브러리 입력에 TextField 와 같은 레이블·도움말·오류 연결을 붙인다.
+ * hook 은 useId 뿐이라 서버 컴포넌트에서도 쓸 수 있다.
+ */
+declare const FormField: react.ForwardRefExoticComponent<FormFieldProps & react.RefAttributes<HTMLDivElement>>;
+
+interface GridProps extends HTMLAttributes<HTMLElement> {
+    /** 렌더링할 요소 (목록이면 'ul') */
+    as?: ElementType;
+    /** 열 개수 (같은 폭). 구간별로: `{ base: 1, md: 2, lg: 3 }`. 생략하면 한 열 */
+    columns?: Responsive<number>;
+    /**
+     * 칸의 최소 폭(CSS 길이, 예: '220px'·'14rem'). 주면 화면 폭에 맞춰 열 개수를 자동으로 정한다(columns 대신).
+     * 화면이 이 폭보다 좁으면 칸이 화면 폭으로 줄어든다(가로 스크롤 없음).
+     */
+    minItemWidth?: string;
+    /** 칸 사이 간격 (space 토큰 키). 구간별 값도 받는다 */
+    gap?: Responsive<keyof typeof space>;
+}
+declare const Grid: react.ForwardRefExoticComponent<GridProps & react.RefAttributes<HTMLElement>>;
+
 interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
     /** 현재 값 (0 ~ max). 생략하거나 null 이면 진행률을 모르는 상태(indeterminate)로 움직이는 막대를 보여 준다 */
     value?: number | null;
@@ -576,17 +689,21 @@ interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
  */
 declare const Skeleton: react.ForwardRefExoticComponent<SkeletonProps & react.RefAttributes<HTMLSpanElement>>;
 
+type Direction = 'row' | 'column' | 'row-reverse' | 'column-reverse';
+type Align = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+type Justify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+type SpaceKey = keyof typeof space;
 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';
+    /** 배치 방향 (기본 column). 구간별로: `{ base: 'column', md: 'row' }` */
+    direction?: Responsive<Direction>;
+    /** 자식 사이 간격 (space 토큰 키). 구간별로: `{ base: 3, lg: 6 }` */
+    gap?: Responsive<SpaceKey>;
+    /** 교차축 정렬 (align-items). 구간별 값도 받는다 */
+    align?: Responsive<Align>;
+    /** 주축 정렬 (justify-content). 구간별 값도 받는다 */
+    justify?: Responsive<Justify>;
     /** 줄바꿈 허용 */
     wrap?: boolean;
 }
@@ -627,8 +744,11 @@ declare const VisuallyHidden: react.ForwardRefExoticComponent<VisuallyHiddenProp
 declare function focusField(target: string | HTMLElement | null | undefined): boolean;
 
 interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
-    /** 라이트/다크 모드. 생략하면 바깥 ThemeProvider 의 모드를 이어받는다 (최상위는 light). */
-    theme?: ThemeName;
+    /**
+     * 라이트/다크 모드. `'system'` 은 OS 설정을 따르고 바뀌면 바로 반영한다 — 서버 렌더링에서도 CSS 미디어쿼리로 그려
+     * 첫 화면이 깜빡이지 않는다. 생략하면 바깥 ThemeProvider 의 모드를 이어받는다 (최상위는 light).
+     */
+    theme?: ThemeMode;
     /**
      * createTheme 으로 만든 브랜드 테마. 모드를 바꿔도 유지되고, 중첩된 ThemeProvider 는 바깥 값을 이어받는다
      * (안쪽에서 준 값이 우선).
@@ -636,7 +756,10 @@ interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
     overrides?: BestowTheme;
 }
 declare const ThemeProvider: react.ForwardRefExoticComponent<ThemeProviderProps & react.RefAttributes<HTMLDivElement>>;
-/** 현재 적용 중인 모드(light/dark)를 반환한다. */
+/**
+ * 현재 적용 중인 모드(light/dark)를 반환한다. `theme="system"` 이면 OS 설정에 따른 값이다 —
+ * 단, 서버 렌더링과 hydration 첫 렌더에서는 OS 설정을 몰라 'light' 이고, 그 직후 실제 값으로 다시 렌더링된다.
+ */
 declare function useTheme(): ThemeName;
 /**
  * Portal 로 ThemeProvider 바깥(body)에 렌더링되는 요소에 펼쳐 넣을 props.
@@ -742,11 +865,11 @@ interface AgreementGroupProps {
  */
 declare const AgreementGroup: react.ForwardRefExoticComponent<AgreementGroupProps & react.RefAttributes<HTMLFieldSetElement>>;
 
-type AlertColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
+type AlertColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
 interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color' | 'title'> {
     /** 시각적 스타일 */
     variant?: 'soft' | 'outline' | 'solid';
-    /** 의미 색상. primary 는 일반 안내(info) 로 쓴다 */
+    /** 의미 색상. 일반 안내(공지·도움말)는 info — 브랜드 색(primary)을 바꿔도 파랑으로 남는다 */
     color?: AlertColor;
     /** 굵게 표시되는 제목 */
     title?: ReactNode;
@@ -939,6 +1062,13 @@ interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'col
      * `disabled` 와 달리 포커스는 유지된다.
      */
     loading?: boolean;
+    /**
+     * 자식 요소(라우터 링크 등)에 버튼 모양과 속성을 입혀 그대로 렌더링한다. 서버 컴포넌트에서도 쓸 수 있다.
+     * 페이지를 이동하는 주요 동작에 쓰고, 자식은 요소 하나여야 한다.
+     * `disabled` 면 `aria-disabled` 를 붙이고 Tab 순서에서 빼며 클릭을 막는다. 휠 클릭은 막지 못하니 링크는 되도록 비활성으로 두지 않는다.
+     * @example <Button asChild><NextLink href="/signup">시작하기</NextLink></Button>
+     */
+    asChild?: boolean;
 }
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 
@@ -990,6 +1120,53 @@ interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'siz
 }
 declare const Checkbox: react.ForwardRefExoticComponent<CheckboxProps & react.RefAttributes<HTMLInputElement>>;
 
+interface CheckboxOption {
+    value: string;
+    label: ReactNode;
+    /** 레이블 아래 보조 설명 (접근 가능한 이름이 아니라 설명으로 읽힌다) */
+    description?: ReactNode;
+    disabled?: boolean;
+}
+interface CheckboxGroupProps {
+    /** 선택지 목록 */
+    options: CheckboxOption[];
+    /** 선택된 값들 (제어 모드). undefined 를 넘기면 아무것도 선택하지 않은 상태 */
+    value?: string[];
+    /** 처음 선택된 값들 (비제어 모드) */
+    defaultValue?: string[];
+    /** 값이 바뀔 때 호출된다 — options 순서대로 정렬한 배열 */
+    onValueChange?: (value: string[]) => void;
+    /** 묶음 위에 표시할 레이블 */
+    label?: ReactNode;
+    /** 묶음 아래 도움말. error 일 때는 오류 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 오류 상태 — 각 체크박스에 aria-invalid */
+    error?: boolean;
+    /** 배치 방향 */
+    orientation?: 'vertical' | 'horizontal';
+    /** 크기 */
+    size?: 'sm' | 'md';
+    disabled?: boolean;
+    /**
+     * 하나 이상 골라야 함 — 레이블에 * 와 스크린리더용 "필수" 를 붙인다. "몇 개 이상" 검증은 폼(react-hook-form 등)에서 한다
+     * (체크박스마다 네이티브 required 를 주면 "모두 골라야 함" 이 되어 쓰지 않는다).
+     */
+    required?: boolean;
+    /** form 제출 시 사용할 이름 — 고른 값마다 같은 이름으로 제출된다(FormData.getAll) */
+    name?: string;
+    /** 묶음의 id (ErrorSummary 링크·focusField 가 이 id 로 첫(또는 선택된) 체크박스를 찾는다) */
+    id?: string;
+    /** label 이 없을 때 스크린리더용 이름 */
+    'aria-label'?: string;
+    /** 바깥 래퍼 className */
+    className?: string;
+}
+/**
+ * 여러 선택지 중 여러 개를 고르는 체크박스 묶음. 묶음 레이블·도움말·오류를 한 번에 연결한다.
+ * 약관 동의(전체 동의·필수/선택 표시·보기)는 AgreementGroup 을 쓴다.
+ */
+declare const CheckboxGroup: react.ForwardRefExoticComponent<CheckboxGroupProps & react.RefAttributes<HTMLDivElement>>;
+
 interface ComboboxOption {
     value: string;
     /** 표시·검색에 쓰는 이름 */
@@ -1306,6 +1483,8 @@ interface IconButtonProps extends Omit<ButtonProps, 'startIcon' | 'endIcon' | 'f
     loading?: boolean;
     /** 버튼이 하는 일을 설명하는 이름 (예: "삭제"). 아이콘만으로는 스크린리더가 알 수 없어 필수다 */
     'aria-label': string;
+    /** 자식 요소(라우터 링크 등)에 모양과 속성을 입혀 그대로 렌더링한다. 아이콘은 그 요소 안에 넣는다 */
+    asChild?: boolean;
     /** 아이콘. 크기는 버튼 size 에 맞춰 자동으로 조절된다 (sm 16px · md 20px · lg 24px) */
     children: ReactNode;
 }
@@ -1561,6 +1740,52 @@ interface RadioGroupProps {
  */
 declare const RadioGroup: react.ForwardRefExoticComponent<RadioGroupProps & react.RefAttributes<HTMLDivElement>>;
 
+interface ResidentNumberInputProps {
+    /** 숫자만 있는 값 (제어 모드). 예: "9001011234567" (digits={7} 이면 "9001011") */
+    value?: string;
+    /** 처음 값 (비제어 모드) */
+    defaultValue?: string;
+    /** 숫자만 있는 값과, 다 채웠을 때 생년월일·뒷자리 첫 숫자가 맞는지로 호출된다 (다 채우기 전에는 valid 가 null) */
+    onValueChange?: (digits: string, valid: boolean | null) => void;
+    /**
+     * 받을 자릿수. 13(기본)은 뒤 7자리를 가려서(password) 받고, 7 은 생년월일 + 뒷자리 첫 숫자만 받는다(나이·성별 확인 —
+     * 주민번호 전체가 필요 없으면 7 을 쓴다).
+     */
+    digits?: 13 | 7;
+    /**
+     * 다 채웠는데 생년월일·뒷자리 첫 숫자가 맞지 않으면 자동으로 오류를 보여 준다 (기본 true). 마지막 검증 숫자는 보지 않는다
+     * (2020년 10월 이후 번호는 임의 번호). 직접 error·helperText 를 주면 그 값이 우선한다.
+     */
+    validate?: boolean;
+    /** 자동 검증 오류 문구 */
+    invalidText?: string;
+    /** 위에 표시할 레이블 (기본 "주민등록번호") */
+    label?: ReactNode;
+    /** 아래 도움말. error 일 때는 오류 메시지로 표시된다 */
+    helperText?: ReactNode;
+    /** 오류 상태 */
+    error?: boolean;
+    /** 필수 입력 (레이블에 * 표시, required 속성) */
+    required?: boolean;
+    disabled?: boolean;
+    /** 크기 */
+    size?: 'sm' | 'md' | 'lg';
+    /** form 제출 시 사용할 이름 — 숫자만 있는 값을 숨긴 input 으로 제출한다 */
+    name?: string;
+    /** 묶음 id — 앞칸은 `${id}-front`, 뒷칸은 `${id}-back` (ErrorSummary 링크·focusField 는 이 id 로 앞칸을 찾는다) */
+    id?: string;
+    /** 바깥 래퍼 className */
+    className?: string;
+    onBlur?: (event: FocusEvent<HTMLDivElement>) => void;
+}
+/**
+ * 주민·외국인등록번호 입력 — 앞 6자리와 뒷자리를 두 칸으로 받고 뒷자리는 가린다(password). 번호를 통째로 앞칸에 붙여 넣으면 두 칸에 나눠 넣는다.
+ * 앞칸을 다 채워도 포커스를 옮기지 않는다(예고 없는 포커스 이동은 WCAG 3.2.2). 뒷칸이 비었을 때 Backspace 는 앞칸으로 간다.
+ *
+ * 주민등록번호는 법령에 근거가 있을 때만 수집할 수 있다(개인정보 보호법 제24조의2). 나이·성별만 필요하면 `digits={7}`.
+ */
+declare const ResidentNumberInput: react.ForwardRefExoticComponent<ResidentNumberInputProps & react.RefAttributes<HTMLInputElement>>;
+
 interface SegmentedControlOption {
     value: string;
     /** 칸에 보이는 글자 (접근 가능한 이름이 된다) */
@@ -1743,6 +1968,11 @@ interface StepperProps extends Omit<OlHTMLAttributes<HTMLOListElement>, 'childre
     current: number;
     /** horizontal(기본): 가로로 나란히, 이름은 원 아래. vertical: 세로로, 이름은 원 오른쪽(설명이 길 때) */
     orientation?: 'horizontal' | 'vertical';
+    /**
+     * 현재 단계가 진행 중이다(AI 응답·업로드 처리 등). 원 안에 스피너를 보여 주고 이름에 "(진행 중)" 을 함께 읽는다.
+     * 단계가 바뀌는 순간을 스크린리더에 알리려면 `role="status"` 영역을 따로 둔다.
+     */
+    loading?: boolean;
     /** 목록 이름 (기본 "진행 단계") */
     'aria-label'?: string;
 }
@@ -1950,7 +2180,7 @@ interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>
 }
 declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
 
-type ToastColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning';
+type ToastColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
 interface ToastOptions {
     /** 제목 */
     title: ReactNode;
@@ -2048,5 +2278,5 @@ interface VerificationCodeInputProps {
  */
 declare const VerificationCodeInput: react.ForwardRefExoticComponent<VerificationCodeInputProps & react.RefAttributes<HTMLInputElement>>;
 
-export { Accordion, AccordionItem, AddressInput, AgreementGroup, Alert, AmountInput, Avatar, Badge, Breadcrumb, BusinessNumberInput, Button, Calendar, Card, CardBody, CardFooter, CardHeader, Checkbox, Combobox, DatePicker, DateRangePicker, DescriptionList, Divider, Drawer, DrawerClose, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ErrorSummary, FileUpload, IconButton, Input, Link, LocaleProvider, Modal, ModalClose, NativeSelect, NumberInput, Pagination, PhoneNumberInput, Popover, PopoverClose, Progress, RadioGroup, SegmentedControl, Select, Skeleton, SkipLink, Slider, Spinner, Stack, Stepper, Switch, Table, TableBody, TableCell, TableEmpty, TableFooter, TableHead, TableHeader, TableRow, TableSkeleton, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, ThemeProvider, ToastProvider, Tooltip, Typography, VerificationCodeInput, VisuallyHidden, contrastRatio, createIntentColors, createTheme, dateRangePresets, en, focusField, hasAllRequiredAgreements, kakaoPostcodeProvider, parseISODate, presetRange, strongInputBorders, themeClass, toISODate, useMessages, usePortalProps, useTableSelection, useTheme, useToast, vars };
-export type { AccordionItemProps, AccordionProps, AddressInputProps, AddressProvider, AddressSearchResult, AddressValue, AgreementGroupProps, AgreementItem, AlertColor, AlertProps, AmountInputProps, AvatarProps, BadgeProps, BestowMessages, BestowTheme, BreadcrumbItemData, BreadcrumbProps, BusinessNumberInputProps, ButtonProps, CalendarProps, CardProps, CardSectionProps, CheckboxProps, ComboboxOption, ComboboxProps, DatePickerProps, DateRange, DateRangePickerProps, DateRangePreset, DeepPartial, DescriptionListItem, DescriptionListProps, DividerProps, DrawerProps, DropdownMenuCheckboxItemProps, DropdownMenuContentProps, DropdownMenuItemProps, DropdownMenuLabelProps, DropdownMenuProps, DropdownMenuRadioGroupProps, DropdownMenuRadioItemProps, DropdownMenuSeparatorProps, DropdownMenuSubContentProps, DropdownMenuSubProps, DropdownMenuSubTriggerProps, DropdownMenuTriggerProps, ErrorSummaryItem, ErrorSummaryProps, FileRejection, FileRejectionReason, FileUploadProps, IconButtonProps, InputProps, IntentName, LinkProps, LocaleProviderProps, Messages, ModalProps, NativeSelectOption, NativeSelectProps, NumberInputProps, PaginationItemType, PaginationProps, PhoneNumberInputProps, PopoverProps, ProgressProps, RadioGroupProps, RadioOption, SegmentedControlOption, SegmentedControlProps, SelectOption, SelectProps, SkeletonProps, SkipLinkProps, SliderProps, SpinnerProps, StackProps, StepperProps, StepperStep, SwitchProps, TableAlign, TableCellProps, TableEmptyProps, TableHeadProps, TableProps, TableRowProps, TableSize, TableSkeletonProps, TabsContentProps, TabsListProps, TabsProps, TabsTriggerProps, TextFieldProps, TextareaProps, ThemeInput, ThemeName, ThemeOverrides, ThemeProviderProps, ThemeTokens, ToastColor, ToastContextValue, ToastOptions, ToastProviderProps, TooltipProps, TypographyProps, TypographyVariant, VerificationCodeInputProps, VisuallyHiddenProps };
+export { Accordion, AccordionItem, AddressInput, AgreementGroup, Alert, AmountInput, Avatar, Badge, Breadcrumb, BusinessNumberInput, Button, Calendar, Card, CardBody, CardFooter, CardHeader, Checkbox, CheckboxGroup, Combobox, Container, DatePicker, DateRangePicker, DescriptionList, Divider, Drawer, DrawerClose, DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubContent, DropdownMenuSubTrigger, DropdownMenuTrigger, ErrorSummary, FileUpload, FormField, Grid, IconButton, Input, Link, LocaleProvider, Modal, ModalClose, NativeSelect, NumberInput, Pagination, PhoneNumberInput, Popover, PopoverClose, Progress, RadioGroup, ResidentNumberInput, SegmentedControl, Select, Skeleton, SkipLink, Slider, Spinner, Stack, Stepper, Switch, Table, TableBody, TableCell, TableEmpty, TableFooter, TableHead, TableHeader, TableRow, TableSkeleton, Tabs, TabsContent, TabsList, TabsTrigger, TextField, Textarea, ThemeProvider, ToastProvider, Tooltip, Typography, VerificationCodeInput, VisuallyHidden, contrastRatio, createIntentColors, createTheme, dateRangePresets, en, focusField, hasAllRequiredAgreements, kakaoPostcodeProvider, media, parseISODate, presetRange, strongInputBorders, themeClass, toISODate, useMessages, usePortalProps, useTableSelection, useTheme, useToast, vars };
+export type { AccordionItemProps, AccordionProps, AddressInputProps, AddressProvider, AddressSearchResult, AddressValue, AgreementGroupProps, AgreementItem, AlertColor, AlertProps, AmountInputProps, AvatarProps, BadgeProps, BestowMessages, BestowTheme, BreadcrumbItemData, BreadcrumbProps, Breakpoint, BusinessNumberInputProps, ButtonProps, CalendarProps, CardProps, CardSectionProps, CheckboxGroupProps, CheckboxOption, CheckboxProps, ComboboxOption, ComboboxProps, ContainerProps, DatePickerProps, DateRange, DateRangePickerProps, DateRangePreset, DeepPartial, DescriptionListItem, DescriptionListProps, DividerProps, DrawerProps, DropdownMenuCheckboxItemProps, DropdownMenuContentProps, DropdownMenuItemProps, DropdownMenuLabelProps, DropdownMenuProps, DropdownMenuRadioGroupProps, DropdownMenuRadioItemProps, DropdownMenuSeparatorProps, DropdownMenuSubContentProps, DropdownMenuSubProps, DropdownMenuSubTriggerProps, DropdownMenuTriggerProps, ErrorSummaryItem, ErrorSummaryProps, FileRejection, FileRejectionReason, FileUploadProps, FormFieldControlProps, FormFieldMeta, FormFieldProps, GridProps, IconButtonProps, InputProps, IntentName, LinkProps, LocaleProviderProps, Messages, ModalProps, NativeSelectOption, NativeSelectProps, NumberInputProps, PaginationItemType, PaginationProps, PhoneNumberInputProps, PopoverProps, ProgressProps, RadioGroupProps, RadioOption, ResidentNumberInputProps, Responsive, SegmentedControlOption, SegmentedControlProps, SelectOption, SelectProps, SkeletonProps, SkipLinkProps, SliderProps, SpinnerProps, StackProps, StepperProps, StepperStep, SwitchProps, TableAlign, TableCellProps, TableEmptyProps, TableHeadProps, TableProps, TableRowProps, TableSize, TableSkeletonProps, TabsContentProps, TabsListProps, TabsProps, TabsTriggerProps, TextFieldProps, TextareaProps, ThemeInput, ThemeMode, ThemeName, ThemeOverrides, ThemeProviderProps, ThemeTokens, ToastColor, ToastContextValue, ToastOptions, ToastProviderProps, TooltipProps, TypographyProps, TypographyVariant, VerificationCodeInputProps, VisuallyHiddenProps };