@hua-labs/ui 1.0.0 → 1.1.0-alpha.0.2

package/dist/form.d.mts

@@ -0,0 +1,803 @@
+import React from 'react';
+
+/**
+ * Input 컴포넌트의 props / Input component props
+ * HTML input 요소의 모든 표준 속성을 상속받습니다.
+ * Inherits all standard attributes of HTML input element.
+ * @typedef {Object} InputProps
+ * @extends {React.InputHTMLAttributes<HTMLInputElement>}
+ */
+interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+}
+/**
+ * Input 컴포넌트 / Input component
+ *
+ * 표준 HTML input 요소를 래핑한 스타일링된 입력 필드 컴포넌트입니다.
+ * 접근성 속성(aria-invalid)을 자동으로 처리합니다.
+ *
+ * Styled input field component wrapping standard HTML input element.
+ * Automatically handles accessibility attributes (aria-invalid).
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Input type="text" placeholder="이름을 입력하세요" />
+ *
+ * @example
+ * // 에러 상태 / Error state
+ * <Input
+ *   type="email"
+ *   placeholder="이메일"
+ *   aria-invalid={true}
+ * />
+ *
+ * @example
+ * // ref 사용 / Using ref
+ * const inputRef = useRef<HTMLInputElement>(null)
+ * <Input ref={inputRef} type="text" />
+ *
+ * @param {InputProps} props - Input 컴포넌트의 props / Input component props
+ * @param {React.Ref<HTMLInputElement>} ref - input 요소 ref / input element ref
+ * @returns {JSX.Element} Input 컴포넌트 / Input component
+ */
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Form 컴포넌트의 props / Form component props
+ * @typedef {Object} FormProps
+ * @property {(e: React.FormEvent<HTMLFormElement>) => void} [onSubmit] - 폼 제출 핸들러 / Form submit handler
+ * @property {"default" | "glass"} [variant="default"] - Form 스타일 변형 / Form style variant
+ * @extends {React.FormHTMLAttributes<HTMLFormElement>}
+ */
+interface FormProps extends React.FormHTMLAttributes<HTMLFormElement> {
+    onSubmit?: (e: React.FormEvent<HTMLFormElement>) => void;
+    variant?: "default" | "glass";
+}
+/**
+ * FormField 컴포넌트의 props / FormField component props
+ * @typedef {Object} FormFieldProps
+ * @property {string} [error] - 에러 메시지 / Error message
+ * @property {boolean} [required=false] - 필수 필드 여부 / Required field
+ * @extends {React.HTMLAttributes<HTMLDivElement>}
+ */
+interface FormFieldProps extends React.HTMLAttributes<HTMLDivElement> {
+    error?: string;
+    required?: boolean;
+}
+/**
+ * FormGroup 컴포넌트의 props / FormGroup component props
+ * @typedef {Object} FormGroupProps
+ * @property {boolean} [inline=false] - 인라인 레이아웃 여부 / Inline layout
+ * @extends {React.HTMLAttributes<HTMLDivElement>}
+ */
+interface FormGroupProps extends React.HTMLAttributes<HTMLDivElement> {
+    inline?: boolean;
+}
+/**
+ * Form 컴포넌트 / Form component
+ *
+ * 폼 컨테이너 컴포넌트입니다.
+ * FormField, FormGroup과 함께 사용하여 구조화된 폼을 구성합니다.
+ *
+ * Form container component.
+ * Used with FormField and FormGroup to create structured forms.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Form onSubmit={(e) => { e.preventDefault(); console.log('제출') }}>
+ *   <FormField>
+ *     <Label>이름</Label>
+ *     <Input />
+ *   </FormField>
+ * </Form>
+ *
+ * @example
+ * // Glass 스타일 / Glass style
+ * <Form variant="glass" onSubmit={handleSubmit}>
+ *   <FormGroup>
+ *     <FormField>
+ *       <Label>이메일</Label>
+ *       <Input type="email" />
+ *     </FormField>
+ *   </FormGroup>
+ * </Form>
+ *
+ * @param {FormProps} props - Form 컴포넌트의 props / Form component props
+ * @param {React.Ref<HTMLFormElement>} ref - form 요소 ref / form element ref
+ * @returns {JSX.Element} Form 컴포넌트 / Form component
+ */
+declare const Form: React.ForwardRefExoticComponent<FormProps & React.RefAttributes<HTMLFormElement>>;
+/**
+ * FormField 컴포넌트 / FormField component
+ *
+ * 폼 필드를 감싸는 컨테이너입니다.
+ * 에러 메시지를 표시하고 필수 필드 표시를 지원합니다.
+ *
+ * Container that wraps a form field.
+ * Displays error messages and supports required field indication.
+ *
+ * @component
+ * @example
+ * <FormField error="이 필드는 필수입니다" required>
+ *   <Label>이름</Label>
+ *   <Input />
+ * </FormField>
+ *
+ * @param {FormFieldProps} props - FormField 컴포넌트의 props / FormField component props
+ * @param {React.Ref<HTMLDivElement>} ref - div 요소 ref / div element ref
+ * @returns {JSX.Element} FormField 컴포넌트 / FormField component
+ */
+declare const FormField: React.ForwardRefExoticComponent<FormFieldProps & React.RefAttributes<HTMLDivElement>>;
+/**
+ * FormGroup 컴포넌트 / FormGroup component
+ *
+ * 여러 폼 필드를 그룹화하는 컨테이너입니다.
+ * Container that groups multiple form fields.
+ *
+ * @component
+ * @example
+ * <FormGroup inline>
+ *   <FormField>
+ *     <Label>이름</Label>
+ *     <Input />
+ *   </FormField>
+ *   <FormField>
+ *     <Label>성</Label>
+ *     <Input />
+ *   </FormField>
+ * </FormGroup>
+ *
+ * @param {FormGroupProps} props - FormGroup 컴포넌트의 props / FormGroup component props
+ * @param {React.Ref<HTMLDivElement>} ref - div 요소 ref / div element ref
+ * @returns {JSX.Element} FormGroup 컴포넌트 / FormGroup component
+ */
+declare const FormGroup: React.ForwardRefExoticComponent<FormGroupProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Label 컴포넌트의 props / Label component props
+ * @typedef {Object} LabelProps
+ * @property {boolean} [required=false] - 필수 필드 여부 / Required field indicator
+ * @property {boolean} [error=false] - 에러 상태 표시 / Error state
+ * @property {boolean} [disabled=false] - 비활성화 상태 / Disabled state
+ * @property {"default" | "glass"} [variant="default"] - Label 스타일 변형 / Label style variant
+ * @extends {React.LabelHTMLAttributes<HTMLLabelElement>}
+ */
+interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+    required?: boolean;
+    error?: boolean;
+    disabled?: boolean;
+    variant?: "default" | "glass";
+}
+/**
+ * Label 컴포넌트 / Label component
+ *
+ * 폼 필드의 레이블을 표시하는 컴포넌트입니다.
+ * 필수 필드 표시와 에러 상태를 지원합니다.
+ *
+ * Component for displaying form field labels.
+ * Supports required field indicator and error state.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Label htmlFor="email">이메일</Label>
+ * <Input id="email" />
+ *
+ * @example
+ * // 필수 필드 / Required field
+ * <Label required htmlFor="name">이름</Label>
+ * <Input id="name" required />
+ *
+ * @example
+ * // 에러 상태 / Error state
+ * <Label error htmlFor="password">비밀번호</Label>
+ * <Input id="password" aria-invalid />
+ *
+ * @param {LabelProps} props - Label 컴포넌트의 props / Label component props
+ * @param {React.Ref<HTMLLabelElement>} ref - label 요소 ref / label element ref
+ * @returns {JSX.Element} Label 컴포넌트 / Label component
+ *
+ * @todo 접근성 개선: required일 때 aria-required="true" 추가 필요 / Accessibility improvement: add aria-required="true" when required
+ */
+declare const Label: React.ForwardRefExoticComponent<LabelProps & React.RefAttributes<HTMLLabelElement>>;
+
+/**
+ * Checkbox 컴포넌트의 props / Checkbox component props
+ * @typedef {Object} CheckboxProps
+ * @property {"default" | "outline" | "filled" | "glass"} [variant="default"] - Checkbox 스타일 변형 / Checkbox style variant
+ * @property {"sm" | "md" | "lg"} [size="md"] - Checkbox 크기 / Checkbox size
+ * @property {boolean} [error=false] - 에러 상태 표시 / Error state
+ * @property {boolean} [success=false] - 성공 상태 표시 / Success state
+ * @property {string} [label] - 체크박스 레이블 텍스트 / Checkbox label text
+ * @property {string} [description] - 체크박스 설명 텍스트 / Checkbox description text
+ * @extends {Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>}
+ */
+interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    variant?: "default" | "outline" | "filled" | "glass";
+    size?: "sm" | "md" | "lg";
+    error?: boolean;
+    success?: boolean;
+    label?: string;
+    description?: string;
+}
+/**
+ * Checkbox 컴포넌트 / Checkbox component
+ *
+ * 체크박스 입력 필드를 제공하는 컴포넌트입니다.
+ * ARIA 속성을 자동으로 설정하여 접근성을 지원합니다.
+ *
+ * Checkbox input field component.
+ * Automatically sets ARIA attributes for accessibility support.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Checkbox label="이용약관에 동의합니다" />
+ *
+ * @example
+ * // 에러 상태와 설명 / Error state with description
+ * <Checkbox
+ *   label="필수 항목"
+ *   description="이 항목은 필수입니다"
+ *   error
+ * />
+ *
+ * @example
+ * // 제어 컴포넌트 / Controlled component
+ * const [checked, setChecked] = useState(false)
+ * <Checkbox
+ *   checked={checked}
+ *   onChange={(e) => setChecked(e.target.checked)}
+ *   label="동의"
+ * />
+ *
+ * @param {CheckboxProps} props - Checkbox 컴포넌트의 props / Checkbox component props
+ * @param {React.Ref<HTMLInputElement>} ref - input 요소 ref / input element ref
+ * @returns {JSX.Element} Checkbox 컴포넌트 / Checkbox component
+ */
+declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Radio 컴포넌트의 props / Radio component props
+ * @typedef {Object} RadioProps
+ * @property {"default" | "outline" | "filled" | "glass"} [variant="default"] - Radio 스타일 변형 / Radio style variant
+ * @property {"sm" | "md" | "lg"} [size="md"] - Radio 크기 / Radio size
+ * @property {boolean} [error=false] - 에러 상태 표시 / Error state
+ * @property {boolean} [success=false] - 성공 상태 표시 / Success state
+ * @property {string} [label] - 라디오 버튼 레이블 텍스트 / Radio button label text
+ * @property {string} [description] - 라디오 버튼 설명 텍스트 / Radio button description text
+ * @extends {Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>}
+ */
+interface RadioProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    variant?: "default" | "outline" | "filled" | "glass";
+    size?: "sm" | "md" | "lg";
+    error?: boolean;
+    success?: boolean;
+    label?: string;
+    description?: string;
+}
+/**
+ * Radio 컴포넌트 / Radio component
+ *
+ * 라디오 버튼 입력 필드를 제공하는 컴포넌트입니다.
+ * 같은 name 속성을 가진 여러 Radio는 그룹으로 동작합니다.
+ * ARIA 속성을 자동으로 설정하여 접근성을 지원합니다.
+ *
+ * Radio button input field component.
+ * Multiple Radio components with the same name attribute work as a group.
+ * Automatically sets ARIA attributes for accessibility support.
+ *
+ * @component
+ * @example
+ * // 기본 사용 (그룹) / Basic usage (group)
+ * <Radio name="option" value="1" label="옵션 1" />
+ * <Radio name="option" value="2" label="옵션 2" />
+ * <Radio name="option" value="3" label="옵션 3" />
+ *
+ * @example
+ * // 에러 상태 / Error state
+ * <Radio
+ *   name="gender"
+ *   value="male"
+ *   label="남성"
+ *   error
+ * />
+ *
+ * @param {RadioProps} props - Radio 컴포넌트의 props / Radio component props
+ * @param {React.Ref<HTMLInputElement>} ref - input 요소 ref / input element ref
+ * @returns {JSX.Element} Radio 컴포넌트 / Radio component
+ */
+declare const Radio: React.ForwardRefExoticComponent<RadioProps & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Select 컴포넌트의 props / Select component props
+ * @typedef {Object} SelectProps
+ * @property {"default" | "outline" | "filled" | "ghost" | "glass"} [variant="default"] - Select 스타일 변형 / Select style variant
+ * @property {"sm" | "md" | "lg"} [size="md"] - Select 크기 / Select size
+ * @property {boolean} [error=false] - 에러 상태 표시 / Error state
+ * @property {boolean} [success=false] - 성공 상태 표시 / Success state
+ * @property {React.ReactNode} [leftIcon] - 왼쪽 아이콘 / Left icon
+ * @property {string} [placeholder] - 플레이스홀더 텍스트 / Placeholder text
+ * @extends {Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'size'>}
+ */
+interface SelectProps extends Omit<React.SelectHTMLAttributes<HTMLSelectElement>, 'size'> {
+    variant?: "default" | "outline" | "filled" | "ghost" | "glass";
+    size?: "sm" | "md" | "lg";
+    error?: boolean;
+    success?: boolean;
+    leftIcon?: React.ReactNode;
+    placeholder?: string;
+}
+/**
+ * SelectOption 컴포넌트의 props / SelectOption component props
+ * @typedef {Object} SelectOptionProps
+ * @property {string} value - 옵션 값 / Option value
+ * @property {React.ReactNode} children - 옵션 표시 텍스트 / Option display text
+ * @extends {React.OptionHTMLAttributes<HTMLOptionElement>}
+ */
+interface SelectOptionProps extends React.OptionHTMLAttributes<HTMLOptionElement> {
+    value: string;
+    children: React.ReactNode;
+}
+/**
+ * Select 컴포넌트 / Select component
+ *
+ * 드롭다운 선택 메뉴를 제공하는 컴포넌트입니다.
+ * 다양한 스타일 변형과 크기를 지원하며, 접근성 속성을 포함합니다.
+ *
+ * Dropdown selection menu component.
+ * Supports various style variants and sizes, includes accessibility attributes.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Select>
+ *   <option value="option1">옵션 1</option>
+ *   <option value="option2">옵션 2</option>
+ * </Select>
+ *
+ * @example
+ * // 에러 상태와 아이콘 / Error state with icon
+ * <Select
+ *   error
+ *   leftIcon={<Icon name="alert" />}
+ *   aria-label="국가 선택"
+ * >
+ *   <option value="">국가를 선택하세요</option>
+ *   <option value="kr">한국</option>
+ *   <option value="us">미국</option>
+ * </Select>
+ *
+ * @example
+ * // 다양한 변형 / Various variants
+ * <Select variant="outline" size="lg">
+ *   <option value="1">항목 1</option>
+ * </Select>
+ *
+ * @param {SelectProps} props - Select 컴포넌트의 props / Select component props
+ * @param {React.Ref<HTMLSelectElement>} ref - select 요소 ref / select element ref
+ * @returns {JSX.Element} Select 컴포넌트 / Select component
+ */
+declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<HTMLSelectElement>>;
+declare const SelectOption: React.ForwardRefExoticComponent<SelectOptionProps & React.RefAttributes<HTMLOptionElement>>;
+
+/**
+ * Switch 컴포넌트의 props / Switch component props
+ * @typedef {Object} SwitchProps
+ * @property {"default" | "outline" | "filled" | "glass"} [variant="default"] - Switch 스타일 변형 / Switch style variant
+ * @property {"sm" | "md" | "lg"} [size="md"] - Switch 크기 / Switch size
+ * @property {boolean} [error=false] - 에러 상태 표시 / Error state
+ * @property {boolean} [success=false] - 성공 상태 표시 / Success state
+ * @property {string} [label] - 스위치 레이블 텍스트 / Switch label text
+ * @property {string} [description] - 스위치 설명 텍스트 / Switch description text
+ * @extends {Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'>}
+ */
+interface SwitchProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
+    variant?: "default" | "outline" | "filled" | "glass";
+    size?: "sm" | "md" | "lg";
+    error?: boolean;
+    success?: boolean;
+    label?: string;
+    description?: string;
+}
+/**
+ * Switch 컴포넌트 / Switch component
+ *
+ * 토글 스위치 입력 필드를 제공하는 컴포넌트입니다.
+ * ARIA 속성을 자동으로 설정하여 접근성을 지원합니다.
+ *
+ * Toggle switch input field component.
+ * Automatically sets ARIA attributes for accessibility support.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Switch label="알림 받기" />
+ *
+ * @example
+ * // 제어 컴포넌트 / Controlled component
+ * const [enabled, setEnabled] = useState(false)
+ * <Switch
+ *   checked={enabled}
+ *   onChange={(e) => setEnabled(e.target.checked)}
+ *   label="다크 모드"
+ * />
+ *
+ * @example
+ * // 에러 상태 / Error state
+ * <Switch
+ *   label="필수 설정"
+ *   description="이 설정을 활성화해야 합니다"
+ *   error
+ * />
+ *
+ * @param {SwitchProps} props - Switch 컴포넌트의 props / Switch component props
+ * @param {React.Ref<HTMLInputElement>} ref - input 요소 ref / input element ref
+ * @returns {JSX.Element} Switch 컴포넌트 / Switch component
+ */
+declare const Switch: React.ForwardRefExoticComponent<SwitchProps & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Slider 컴포넌트의 props
+ * @typedef {Object} SliderProps
+ * @property {"default" | "primary" | "success" | "warning" | "danger"} [variant="default"] - Slider 스타일 변형
+ * @property {"sm" | "md" | "lg"} [size="md"] - Slider 크기
+ * @property {boolean} [showValue=false] - 현재 값 표시 여부
+ * @property {boolean} [showLabel=false] - 라벨 표시 여부
+ * @property {string} [label] - 라벨 텍스트
+ * @property {number} [min=0] - 최소값
+ * @property {number} [max=100] - 최대값
+ * @property {number} [step=1] - 단계값
+ * @property {number | number[]} [value=0] - 현재 값 (배열이면 범위 슬라이더)
+ * @property {(value: number | number[]) => void} [onValueChange] - 값 변경 콜백
+ * @property {"horizontal" | "vertical"} [orientation="horizontal"] - Slider 방향
+ * @property {boolean} [disabled=false] - 비활성화 여부
+ * @property {string} [className] - 추가 CSS 클래스
+ * @extends {Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange' | 'size'>}
+ */
+interface SliderProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'type' | 'value' | 'onChange' | 'size'> {
+    variant?: "default" | "primary" | "success" | "warning" | "danger";
+    size?: "sm" | "md" | "lg";
+    showValue?: boolean;
+    showLabel?: boolean;
+    label?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    value?: number | number[];
+    onValueChange?: (value: number | number[]) => void;
+    orientation?: "horizontal" | "vertical";
+    disabled?: boolean;
+    className?: string;
+}
+/**
+ * Slider 컴포넌트 / Slider component
+ *
+ * 숫자 값을 선택하는 슬라이더 컴포넌트입니다.
+ * 단일 값 또는 범위 값을 선택할 수 있습니다.
+ *
+ * Slider component for selecting numeric values.
+ * Supports single value or range value selection.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * const [value, setValue] = useState(50)
+ * <Slider value={value} onValueChange={setValue} />
+ *
+ * @example
+ * // 범위 슬라이더 / Range slider
+ * const [range, setRange] = useState([20, 80])
+ * <Slider
+ *   value={range}
+ *   onValueChange={setRange}
+ *   showValue
+ *   label="가격 범위"
+ * />
+ *
+ * @example
+ * // 세로 슬라이더 / Vertical slider
+ * <Slider
+ *   orientation="vertical"
+ *   variant="primary"
+ *   size="lg"
+ *   className="h-64"
+ * />
+ *
+ * @param {SliderProps} props - Slider 컴포넌트의 props / Slider component props
+ * @param {React.Ref<HTMLInputElement>} ref - input 요소 ref / input element ref
+ * @returns {JSX.Element} Slider 컴포넌트 / Slider component
+ */
+declare const Slider: React.ForwardRefExoticComponent<SliderProps & React.RefAttributes<HTMLInputElement>>;
+
+/**
+ * Textarea 컴포넌트의 props / Textarea component props
+ * @typedef {Object} TextareaProps
+ * @property {"default" | "outline" | "filled" | "ghost" | "glass"} [variant="default"] - Textarea 스타일 변형 / Textarea style variant
+ * @property {"sm" | "md" | "lg"} [size="md"] - Textarea 크기 / Textarea size
+ * @property {boolean} [error=false] - 에러 상태 표시 / Error state
+ * @property {boolean} [success=false] - 성공 상태 표시 / Success state
+ * @property {"none" | "vertical" | "horizontal" | "both"} [resize="vertical"] - 크기 조절 방향 / Resize direction
+ * @extends {React.TextareaHTMLAttributes<HTMLTextAreaElement>}
+ */
+interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+    variant?: "default" | "outline" | "filled" | "ghost" | "glass";
+    size?: "sm" | "md" | "lg";
+    error?: boolean;
+    success?: boolean;
+    resize?: "none" | "vertical" | "horizontal" | "both";
+}
+/**
+ * Textarea 컴포넌트 / Textarea component
+ *
+ * 여러 줄 텍스트 입력을 위한 텍스트 영역 컴포넌트입니다.
+ * 다양한 스타일 변형과 크기를 지원하며, 접근성 속성을 포함합니다.
+ *
+ * Text area component for multi-line text input.
+ * Supports various style variants and sizes, includes accessibility attributes.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Textarea placeholder="내용을 입력하세요" />
+ *
+ * @example
+ * // 에러 상태 / Error state
+ * <Textarea
+ *   error
+ *   placeholder="에러가 발생했습니다"
+ *   aria-label="설명 입력"
+ * />
+ *
+ * @example
+ * // 크기 조절 비활성화 / Disable resize
+ * <Textarea
+ *   resize="none"
+ *   rows={5}
+ *   placeholder="고정 크기 텍스트 영역"
+ * />
+ *
+ * @param {TextareaProps} props - Textarea 컴포넌트의 props / Textarea component props
+ * @param {React.Ref<HTMLTextAreaElement>} ref - textarea 요소 ref / textarea element ref
+ * @returns {JSX.Element} Textarea 컴포넌트 / Textarea component
+ *
+ * @todo 접근성 개선: aria-invalid 속성 자동 추가 필요 / Accessibility improvement: auto-add aria-invalid attribute
+ */
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+
+/**
+ * DatePicker 컴포넌트의 props / DatePicker component props
+ * @typedef {Object} DatePickerProps
+ * @property {Date | null} [value] - 선택된 날짜 / Selected date
+ * @property {(date: Date | null) => void} [onChange] - 날짜 변경 핸들러 / Date change handler
+ * @property {Date} [minDate] - 최소 날짜 / Minimum date
+ * @property {Date} [maxDate] - 최대 날짜 / Maximum date
+ * @property {string} [placeholder="날짜를 선택하세요"] - 플레이스홀더 / Placeholder
+ * @property {boolean} [disabled=false] - 비활성화 상태 / Disabled state
+ * @property {boolean} [error=false] - 에러 상태 / Error state
+ * @property {string} [dateFormat="YYYY-MM-DD"] - 날짜 포맷 / Date format
+ * @property {string} [locale="ko-KR"] - 로케일 / Locale
+ * @property {"sm" | "md" | "lg"} [size="md"] - 크기 / Size
+ * @property {string} [className] - 추가 클래스명 / Additional class name
+ * @extends {Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>}
+ */
+interface DatePickerProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    value?: Date | null;
+    onChange?: (date: Date | null) => void;
+    minDate?: Date;
+    maxDate?: Date;
+    placeholder?: string;
+    disabled?: boolean;
+    error?: boolean;
+    dateFormat?: string;
+    locale?: string;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/**
+ * DatePicker 컴포넌트 / DatePicker component
+ *
+ * 날짜를 선택할 수 있는 컴포넌트입니다.
+ * 캘린더 팝오버를 통해 직관적으로 날짜를 선택할 수 있습니다.
+ *
+ * Component for selecting dates.
+ * Allows intuitive date selection through a calendar popover.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <DatePicker
+ *   value={selectedDate}
+ *   onChange={setSelectedDate}
+ * />
+ *
+ * @example
+ * // 날짜 범위 제한 / Date range restriction
+ * <DatePicker
+ *   value={date}
+ *   onChange={setDate}
+ *   minDate={new Date("2024-01-01")}
+ *   maxDate={new Date("2024-12-31")}
+ *   placeholder="날짜 선택"
+ * />
+ *
+ * @param {DatePickerProps} props - DatePicker 컴포넌트의 props / DatePicker component props
+ * @returns {JSX.Element} DatePicker 컴포넌트 / DatePicker component
+ */
+declare const DatePicker: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * 업로드된 파일 정보 인터페이스 / Uploaded file information interface
+ * @typedef {Object} UploadedFile
+ * @property {string} id - 파일 고유 ID / File unique ID
+ * @property {File} file - 파일 객체 / File object
+ * @property {string} name - 파일 이름 / File name
+ * @property {number} size - 파일 크기 (bytes) / File size in bytes
+ * @property {string} type - 파일 타입 / File type
+ * @property {number} [progress] - 업로드 진행률 (0-100) / Upload progress (0-100)
+ * @property {"pending" | "uploading" | "success" | "error"} [status] - 업로드 상태 / Upload status
+ * @property {string} [url] - 업로드된 파일 URL / Uploaded file URL
+ * @property {string} [error] - 에러 메시지 / Error message
+ */
+interface UploadedFile {
+    id: string;
+    file: File;
+    name: string;
+    size: number;
+    type: string;
+    progress?: number;
+    status?: "pending" | "uploading" | "success" | "error";
+    url?: string;
+    error?: string;
+}
+/**
+ * Upload 컴포넌트의 props / Upload component props
+ * @typedef {Object} UploadProps
+ * @property {UploadedFile[]} [files] - 업로드된 파일 목록 / Uploaded files list
+ * @property {(files: File[]) => void} [onChange] - 파일 선택 핸들러 / File selection handler
+ * @property {(file: UploadedFile) => void} [onRemove] - 파일 제거 핸들러 / File removal handler
+ * @property {boolean} [multiple=false] - 다중 파일 선택 허용 / Allow multiple file selection
+ * @property {string} [accept] - 허용할 파일 타입 (예: "image/*", ".pdf") / Accepted file types
+ * @property {number} [maxSize] - 최대 파일 크기 (bytes) / Maximum file size in bytes
+ * @property {number} [maxFiles] - 최대 파일 개수 / Maximum number of files
+ * @property {boolean} [disabled=false] - 비활성화 상태 / Disabled state
+ * @property {boolean} [dragDrop=true] - 드래그 앤 드롭 활성화 / Enable drag and drop
+ * @property {string} [placeholder="파일을 선택하거나 여기에 드래그하세요"] - 플레이스홀더 / Placeholder
+ * @property {"sm" | "md" | "lg"} [size="md"] - 크기 / Size
+ * @property {string} [className] - 추가 클래스명 / Additional class name
+ */
+interface UploadProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    files?: UploadedFile[];
+    onChange?: (files: File[]) => void;
+    onRemove?: (file: UploadedFile) => void;
+    multiple?: boolean;
+    accept?: string;
+    maxSize?: number;
+    maxFiles?: number;
+    disabled?: boolean;
+    dragDrop?: boolean;
+    placeholder?: string;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/**
+ * Upload 컴포넌트 / Upload component
+ *
+ * 파일을 업로드할 수 있는 컴포넌트입니다.
+ * 드래그 앤 드롭, 다중 파일 선택, 파일 크기 제한 등을 지원합니다.
+ *
+ * Component for uploading files.
+ * Supports drag and drop, multiple file selection, file size limits, and more.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Upload
+ *   onChange={(files) => console.log(files)}
+ * />
+ *
+ * @example
+ * // 이미지만, 다중 선택 / Images only, multiple selection
+ * <Upload
+ *   accept="image/*"
+ *   multiple
+ *   maxSize={5 * 1024 * 1024} // 5MB
+ *   maxFiles={5}
+ *   files={uploadedFiles}
+ *   onRemove={(file) => handleRemove(file)}
+ * />
+ *
+ * @param {UploadProps} props - Upload 컴포넌트의 props / Upload component props
+ * @returns {JSX.Element} Upload 컴포넌트 / Upload component
+ */
+declare const Upload: React.ForwardRefExoticComponent<UploadProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Autocomplete 옵션 인터페이스 / Autocomplete option interface
+ * @typedef {Object} AutocompleteOption
+ * @property {string} value - 옵션 값 / Option value
+ * @property {string} label - 옵션 라벨 / Option label
+ * @property {string} [description] - 옵션 설명 / Option description
+ * @property {React.ReactNode} [icon] - 옵션 아이콘 / Option icon
+ * @property {Record<string, unknown>} [data] - 추가 데이터 / Additional data
+ */
+interface AutocompleteOption {
+    value: string;
+    label: string;
+    description?: string;
+    icon?: React.ReactNode;
+    data?: Record<string, unknown>;
+}
+/**
+ * Autocomplete 컴포넌트의 props / Autocomplete component props
+ * @typedef {Object} AutocompleteProps
+ * @property {AutocompleteOption[]} options - 옵션 목록 / Options list
+ * @property {string} [value] - 선택된 값 / Selected value
+ * @property {(value: string, option?: AutocompleteOption) => void} [onChange] - 값 변경 핸들러 / Value change handler
+ * @property {string} [placeholder="검색하거나 선택하세요"] - 플레이스홀더 / Placeholder
+ * @property {boolean} [disabled=false] - 비활성화 상태 / Disabled state
+ * @property {boolean} [error=false] - 에러 상태 / Error state
+ * @property {boolean} [loading=false] - 로딩 상태 / Loading state
+ * @property {number} [maxHeight=300] - 드롭다운 최대 높이 (px) / Dropdown max height in px
+ * @property {boolean} [clearable=true] - 지우기 버튼 표시 / Show clear button
+ * @property {boolean} [filterable=true] - 필터링 활성화 / Enable filtering
+ * @property {(query: string) => AutocompleteOption[] | Promise<AutocompleteOption[]>} [onSearch] - 검색 핸들러 (비동기 지원) / Search handler (async support)
+ * @property {React.ReactNode} [emptyText="결과가 없습니다"] - 빈 결과 텍스트 / Empty result text
+ * @property {"sm" | "md" | "lg"} [size="md"] - 크기 / Size
+ * @property {string} [className] - 추가 클래스명 / Additional class name
+ * @extends {Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'>}
+ */
+interface AutocompleteProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+    options: AutocompleteOption[];
+    value?: string;
+    onChange?: (value: string, option?: AutocompleteOption) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    error?: boolean;
+    loading?: boolean;
+    maxHeight?: number;
+    clearable?: boolean;
+    filterable?: boolean;
+    onSearch?: (query: string) => AutocompleteOption[] | Promise<AutocompleteOption[]>;
+    emptyText?: string;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+/**
+ * Autocomplete 컴포넌트 / Autocomplete component
+ *
+ * 자동완성 입력 컴포넌트입니다.
+ * 입력하면서 옵션을 필터링하고 선택할 수 있습니다.
+ *
+ * Autocomplete input component.
+ * Filters and selects options as you type.
+ *
+ * @component
+ * @example
+ * // 기본 사용 / Basic usage
+ * <Autocomplete
+ *   options={[
+ *     { value: "1", label: "옵션 1" },
+ *     { value: "2", label: "옵션 2" }
+ *   ]}
+ *   onChange={(value) => console.log(value)}
+ * />
+ *
+ * @example
+ * // 비동기 검색 / Async search
+ * <Autocomplete
+ *   options={options}
+ *   onSearch={async (query) => {
+ *     const results = await searchAPI(query)
+ *     return results
+ *   }}
+ *   loading={isLoading}
+ * />
+ *
+ * @param {AutocompleteProps} props - Autocomplete 컴포넌트의 props / Autocomplete component props
+ * @returns {JSX.Element} Autocomplete 컴포넌트 / Autocomplete component
+ */
+declare const Autocomplete: React.ForwardRefExoticComponent<AutocompleteProps & React.RefAttributes<HTMLDivElement>>;
+
+export { Autocomplete, type AutocompleteOption, type AutocompleteProps, Checkbox, type CheckboxProps, DatePicker, type DatePickerProps, Form, FormField, type FormFieldProps, FormGroup, type FormGroupProps, type FormProps, Input, type InputProps, Label, type LabelProps, Radio, type RadioProps, Select, SelectOption, type SelectOptionProps, type SelectProps, Slider, type SliderProps, Switch, type SwitchProps, Textarea, type TextareaProps, Upload, type UploadProps, type UploadedFile };