@kalyx/react 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,744 @@
+import * as react from 'react';
+import { ReactNode, HTMLAttributes, InputHTMLAttributes, ButtonHTMLAttributes } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ISODateString, DisabledRule, WeekStartsOn, DateAdapter, DateRange, CalendarGrid, TimeValue } from '@kalyx/core';
+export { CalendarDay, DateAdapter, DateFnsAdapter, DateRange, DisabledRule, ISODateString, TimeValue } from '@kalyx/core';
+
+/**
+ * DatePicker의 Root 컴포넌트 props.
+ *
+ * @example 제어 모드
+ * ```tsx
+ * <DatePicker value={date} onChange={setDate}>
+ *   <DatePicker.Input />
+ *   <DatePicker.Popover>
+ *     <DatePicker.Calendar />
+ *   </DatePicker.Popover>
+ * </DatePicker>
+ * ```
+ *
+ * @example 비제어 모드
+ * ```tsx
+ * <DatePicker defaultValue="2026-01-15T00:00:00.000Z">
+ *   <DatePicker.Input />
+ * </DatePicker>
+ * ```
+ */
+interface DatePickerRootProps {
+    /** 선택된 날짜 (제어 모드, ISO 8601 UTC). `null`이면 빈 상태. */
+    value?: ISODateString | null;
+    /** 초기 날짜 (비제어 모드) */
+    defaultValue?: ISODateString;
+    /** 날짜 변경 콜백 */
+    onChange?: (value: ISODateString | null) => void;
+    /** 비활성화 규칙 */
+    disabled?: DisabledRule[] | boolean;
+    /** 읽기 전용 */
+    readOnly?: boolean;
+    /** 주 시작 요일 */
+    weekStartsOn?: WeekStartsOn;
+    /** 날짜 표시 포맷 */
+    displayFormat?: string;
+    /** BCP 47 locale (예: "en-US", "ko-KR", "ja-JP") */
+    locale?: string;
+    /** 날짜 어댑터 */
+    adapter?: DateAdapter;
+    /** 자식 컴포넌트 */
+    children: ReactNode;
+}
+declare function DatePickerRoot({ value: controlledValue, defaultValue, onChange, disabled, readOnly, weekStartsOn, displayFormat, locale, adapter, children, }: DatePickerRootProps): react_jsx_runtime.JSX.Element;
+
+interface DatePickerPopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    children?: ReactNode;
+}
+declare function DatePickerPopover({ children, ...props }: DatePickerPopoverProps): react_jsx_runtime.JSX.Element | null;
+
+interface DatePickerCalendarClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    navButton?: string;
+    grid?: string;
+    gridRow?: string;
+    gridCell?: string;
+    day?: string;
+    daySelected?: string;
+    dayToday?: string;
+    dayDisabled?: string;
+    dayOutsideMonth?: string;
+    weekdayHeader?: string;
+}
+interface DatePickerCalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: DatePickerCalendarClassNames;
+    /** 타이틀("January 2026") 클릭 시 콜백. Month/Year 뷰 전환에 사용. */
+    onTitleClick?: () => void;
+}
+declare function DatePickerCalendar({ classNames, onTitleClick, ...props }: DatePickerCalendarProps): react_jsx_runtime.JSX.Element;
+
+interface DatePickerMonthGridClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    navButton?: string;
+    grid?: string;
+    month?: string;
+    monthSelected?: string;
+    monthCurrent?: string;
+}
+interface DatePickerMonthGridProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: DatePickerMonthGridClassNames;
+    /** 월 선택 시 콜백. 일반적으로 day 뷰로 전환한다. */
+    onSelect?: () => void;
+    /** 타이틀(년도) 클릭 시 콜백. Year 뷰로 전환할 때 사용. */
+    onTitleClick?: () => void;
+}
+/**
+ * DatePicker.MonthGrid — 12개월 그리드에서 월을 빠르게 선택.
+ * Calendar 타이틀 클릭 → MonthGrid 표시 → 월 클릭 → Calendar로 복귀.
+ *
+ * @example
+ * ```tsx
+ * {view === 'months' && (
+ *   <DatePicker.MonthGrid
+ *     onSelect={() => setView('days')}
+ *     onTitleClick={() => setView('years')}
+ *   />
+ * )}
+ * ```
+ */
+declare function DatePickerMonthGrid({ classNames, onSelect, onTitleClick, ...props }: DatePickerMonthGridProps): react_jsx_runtime.JSX.Element;
+
+interface DatePickerYearGridClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    navButton?: string;
+    grid?: string;
+    year?: string;
+    yearSelected?: string;
+    yearCurrent?: string;
+}
+interface DatePickerYearGridProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: DatePickerYearGridClassNames;
+    /** 년 선택 시 콜백. 일반적으로 month 뷰로 전환한다. */
+    onSelect?: () => void;
+}
+/**
+ * DatePicker.YearGrid — 12년 단위 그리드에서 년도를 빠르게 선택.
+ * MonthGrid 타이틀 클릭 → YearGrid 표시 → 년 클릭 → MonthGrid로 복귀.
+ *
+ * @example
+ * ```tsx
+ * {view === 'years' && (
+ *   <DatePicker.YearGrid onSelect={() => setView('months')} />
+ * )}
+ * ```
+ */
+declare function DatePickerYearGrid({ classNames, onSelect, ...props }: DatePickerYearGridProps): react_jsx_runtime.JSX.Element;
+
+interface DatePickerInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
+    /** 날짜 표시 포맷 (기본: 부모의 displayFormat) */
+    format?: string;
+}
+
+interface DatePickerTriggerProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'type'> {
+    children?: ReactNode;
+}
+
+/**
+ * DatePicker — Headless, SSR-safe React DatePicker
+ *
+ * @example 기본
+ * ```tsx
+ * <DatePicker value={date} onChange={setDate}>
+ *   <DatePicker.Input placeholder="날짜 선택" />
+ *   <DatePicker.Popover>
+ *     <DatePicker.Calendar />
+ *   </DatePicker.Popover>
+ * </DatePicker>
+ * ```
+ *
+ * @example Month/Year 빠른 네비게이션
+ * ```tsx
+ * const [view, setView] = useState('days');
+ * <DatePicker value={date} onChange={setDate}>
+ *   <DatePicker.Input />
+ *   <DatePicker.Popover>
+ *     {view === 'days' && <DatePicker.Calendar onTitleClick={() => setView('months')} />}
+ *     {view === 'months' && <DatePicker.MonthGrid onSelect={() => setView('days')} onTitleClick={() => setView('years')} />}
+ *     {view === 'years' && <DatePicker.YearGrid onSelect={() => setView('months')} />}
+ *   </DatePicker.Popover>
+ * </DatePicker>
+ * ```
+ */
+declare const DatePicker: typeof DatePickerRoot & {
+    Input: react.ForwardRefExoticComponent<DatePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    Trigger: react.ForwardRefExoticComponent<DatePickerTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+    Popover: typeof DatePickerPopover;
+    Calendar: typeof DatePickerCalendar;
+    MonthGrid: typeof DatePickerMonthGrid;
+    YearGrid: typeof DatePickerYearGrid;
+};
+
+/**
+ * RangePicker의 Root 컴포넌트 props.
+ *
+ * @example
+ * ```tsx
+ * <RangePicker value={range} onChange={setRange}>
+ *   <RangePicker.Input part="start" />
+ *   <RangePicker.Input part="end" />
+ *   <RangePicker.Popover>
+ *     <RangePicker.Calendar />
+ *   </RangePicker.Popover>
+ * </RangePicker>
+ * ```
+ */
+interface RangePickerRootProps {
+    /** 선택된 범위 (제어 모드). `{ start, end }` 형태의 ISO string 또는 null. */
+    value?: DateRange;
+    /** 초기 범위 (비제어 모드) */
+    defaultValue?: DateRange;
+    /** 범위 변경 콜백 */
+    onChange?: (range: DateRange) => void;
+    /** 비활성화 규칙 */
+    disabled?: DisabledRule[] | boolean;
+    /** 읽기 전용 */
+    readOnly?: boolean;
+    /** 주 시작 요일 */
+    weekStartsOn?: WeekStartsOn;
+    /** 날짜 표시 포맷 */
+    displayFormat?: string;
+    /** BCP 47 locale */
+    locale?: string;
+    /** 날짜 어댑터 */
+    adapter?: DateAdapter;
+    /** 자식 컴포넌트 */
+    children: ReactNode;
+}
+declare function RangePickerRoot({ value: controlledValue, defaultValue, onChange, disabled, readOnly, weekStartsOn, displayFormat, locale, adapter, children, }: RangePickerRootProps): react_jsx_runtime.JSX.Element;
+
+interface RangePickerPopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    children?: ReactNode;
+}
+declare function RangePickerPopover({ children, ...props }: RangePickerPopoverProps): react_jsx_runtime.JSX.Element | null;
+
+interface RangePickerCalendarClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    navButton?: string;
+    grid?: string;
+    gridRow?: string;
+    gridCell?: string;
+    day?: string;
+    daySelected?: string;
+    dayToday?: string;
+    dayDisabled?: string;
+    dayOutsideMonth?: string;
+    dayRangeStart?: string;
+    dayRangeEnd?: string;
+    dayInRange?: string;
+    weekdayHeader?: string;
+}
+interface RangePickerCalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: RangePickerCalendarClassNames;
+}
+declare function RangePickerCalendar({ classNames, ...props }: RangePickerCalendarProps): react_jsx_runtime.JSX.Element;
+
+/** 미리 정의된 프리셋 키. 커스텀 범위도 가능. */
+type PresetKey = 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisYear';
+interface RangePickerPresetsClassNames {
+    root?: string;
+    preset?: string;
+    presetActive?: string;
+}
+interface RangePickerPresetsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: RangePickerPresetsClassNames;
+    children?: ReactNode;
+}
+/**
+ * RangePicker.Presets — 프리셋 버튼들을 감싸는 컨테이너.
+ * 내부에 `RangePicker.Preset` 버튼들을 배치한다.
+ *
+ * @example
+ * ```tsx
+ * <RangePicker.Presets>
+ *   <RangePicker.Preset value="last7days">Last 7 days</RangePicker.Preset>
+ *   <RangePicker.Preset value="thisMonth">This month</RangePicker.Preset>
+ * </RangePicker.Presets>
+ * ```
+ */
+declare function RangePickerPresets({ classNames, children, ...props }: RangePickerPresetsProps): react_jsx_runtime.JSX.Element;
+interface RangePickerPresetProps extends Omit<HTMLAttributes<HTMLButtonElement>, 'value'> {
+    /** 미리 정의된 프리셋 키 또는 직접 range 전달 시 생략 */
+    value?: PresetKey;
+    /** 직접 범위를 지정할 때 사용 (value 대신) */
+    range?: DateRange;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * RangePicker.Preset — 한 클릭으로 날짜 범위를 선택하는 프리셋 버튼.
+ *
+ * `value` (프리셋 키) 또는 `range` (직접 범위)를 전달한다.
+ *
+ * @example
+ * ```tsx
+ * <RangePicker.Preset value="last7days">Last 7 days</RangePicker.Preset>
+ * <RangePicker.Preset range={{ start: "2026-01-01T...", end: "2026-03-31T..." }}>
+ *   Q1 2026
+ * </RangePicker.Preset>
+ * ```
+ */
+declare function RangePickerPreset({ value: presetKey, range: directRange, children, onClick, ...props }: RangePickerPresetProps): react_jsx_runtime.JSX.Element;
+
+type RangeInputPart = 'start' | 'end';
+interface RangePickerInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
+    /** 어떤 부분의 입력인지 (start | end) */
+    part: RangeInputPart;
+    /** 날짜 표시 포맷 (기본: 부모의 displayFormat) */
+    format?: string;
+}
+
+/**
+ * RangePicker — Headless 날짜 범위 선택 컴포넌트
+ *
+ * @example 기본
+ * ```tsx
+ * <RangePicker value={range} onChange={setRange}>
+ *   <RangePicker.Input part="start" />
+ *   <RangePicker.Input part="end" />
+ *   <RangePicker.Popover>
+ *     <RangePicker.Calendar />
+ *   </RangePicker.Popover>
+ * </RangePicker>
+ * ```
+ *
+ * @example Presets (대시보드)
+ * ```tsx
+ * <RangePicker value={range} onChange={setRange}>
+ *   <RangePicker.Input part="start" />
+ *   <RangePicker.Input part="end" />
+ *   <RangePicker.Popover>
+ *     <RangePicker.Presets>
+ *       <RangePicker.Preset value="last7days">Last 7 days</RangePicker.Preset>
+ *       <RangePicker.Preset value="last30days">Last 30 days</RangePicker.Preset>
+ *       <RangePicker.Preset value="thisMonth">This month</RangePicker.Preset>
+ *     </RangePicker.Presets>
+ *     <RangePicker.Calendar />
+ *   </RangePicker.Popover>
+ * </RangePicker>
+ * ```
+ */
+declare const RangePicker: typeof RangePickerRoot & {
+    Input: react.ForwardRefExoticComponent<RangePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    Popover: typeof RangePickerPopover;
+    Calendar: typeof RangePickerCalendar;
+    Presets: typeof RangePickerPresets;
+    Preset: typeof RangePickerPreset;
+};
+
+type TimePickerFormat = '12h' | '24h';
+
+/**
+ * TimePicker의 Root 컴포넌트 props.
+ *
+ * @example
+ * ```tsx
+ * <TimePicker value={time} onChange={setTime} format="24h" step={15}>
+ *   <TimePicker.Input />
+ *   <TimePicker.HourList />
+ *   <TimePicker.MinuteList />
+ *   <TimePicker.AmPmToggle />
+ * </TimePicker>
+ * ```
+ */
+interface TimePickerRootProps {
+    /** 선택된 시간 (제어 모드, ISO 8601 UTC). 날짜 부분은 무시되고 시간만 사용. */
+    value?: ISODateString | null;
+    /** 초기 시간 (비제어 모드) */
+    defaultValue?: ISODateString;
+    /** 시간 변경 콜백 */
+    onChange?: (value: ISODateString | null) => void;
+    /** 12시간제 또는 24시간제 */
+    format?: TimePickerFormat;
+    /** 분 step (1, 5, 10, 15, 30 등) */
+    step?: number;
+    /** 초 표시 여부 */
+    withSeconds?: boolean;
+    /** 전체 비활성화 */
+    disabled?: boolean;
+    /** 읽기 전용 */
+    readOnly?: boolean;
+    /** 자식 컴포넌트 */
+    children: ReactNode;
+}
+declare function TimePickerRoot({ value: controlledValue, defaultValue, onChange, format, step, withSeconds, disabled, readOnly, children, }: TimePickerRootProps): react_jsx_runtime.JSX.Element;
+
+interface TimePickerHourListClassNames {
+    root?: string;
+    option?: string;
+    optionSelected?: string;
+}
+interface TimePickerHourListProps extends Omit<HTMLAttributes<HTMLUListElement>, 'role' | 'children'> {
+    classNames?: TimePickerHourListClassNames;
+}
+/**
+ * TimePicker.HourList — `role="listbox"` 패턴의 시간 선택 리스트.
+ * 12h/24h 모드에 따라 다르게 렌더링.
+ *
+ * ARIA 표준 listbox: <li role="option">이 직접 인터랙티브 요소.
+ * 키보드: ↑/↓로 이동, Enter/Space로 선택.
+ */
+declare function TimePickerHourList({ classNames, ...props }: TimePickerHourListProps): react_jsx_runtime.JSX.Element;
+
+interface TimePickerMinuteListClassNames {
+    root?: string;
+    option?: string;
+    optionSelected?: string;
+}
+interface TimePickerMinuteListProps extends Omit<HTMLAttributes<HTMLUListElement>, 'role' | 'children'> {
+    classNames?: TimePickerMinuteListClassNames;
+}
+/**
+ * TimePicker.MinuteList — `role="listbox"` 패턴의 분 선택 리스트.
+ * step prop에 따라 표시되는 분이 결정된다 (예: step=15 → [0, 15, 30, 45]).
+ */
+declare function TimePickerMinuteList({ classNames, ...props }: TimePickerMinuteListProps): react_jsx_runtime.JSX.Element;
+
+interface TimePickerAmPmToggleClassNames {
+    root?: string;
+    option?: string;
+    optionSelected?: string;
+}
+interface TimePickerAmPmToggleProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role' | 'children'> {
+    classNames?: TimePickerAmPmToggleClassNames;
+}
+/**
+ * TimePicker.AmPmToggle — 12시간제 모드에서만 표시되는 AM/PM 전환 버튼.
+ * 24시간제에서는 null을 반환한다.
+ */
+declare function TimePickerAmPmToggle({ classNames, ...props }: TimePickerAmPmToggleProps): react_jsx_runtime.JSX.Element | null;
+
+interface TimePickerInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
+}
+
+/**
+ * TimePicker — Headless 시간 선택 컴포넌트
+ *
+ * @example
+ * ```tsx
+ * <TimePicker value={time} onChange={setTime} format="24h" step={15}>
+ *   <TimePicker.Input />
+ *   <div>
+ *     <TimePicker.HourList />
+ *     <TimePicker.MinuteList />
+ *     <TimePicker.AmPmToggle />
+ *   </div>
+ * </TimePicker>
+ * ```
+ */
+declare const TimePicker: typeof TimePickerRoot & {
+    Input: react.ForwardRefExoticComponent<TimePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    HourList: typeof TimePickerHourList;
+    MinuteList: typeof TimePickerMinuteList;
+    AmPmToggle: typeof TimePickerAmPmToggle;
+};
+
+/**
+ * DateTimePicker의 Root 컴포넌트 props.
+ * 내부적으로 DatePickerContext + TimePickerContext를 동시에 제공 (Context Bridging).
+ *
+ * @example
+ * ```tsx
+ * <DateTimePicker value={dt} onChange={setDt} format="24h" step={15}>
+ *   <DateTimePicker.Input />
+ *   <DateTimePicker.Popover>
+ *     <DateTimePicker.Calendar />
+ *     <DateTimePicker.HourList />
+ *     <DateTimePicker.MinuteList />
+ *   </DateTimePicker.Popover>
+ * </DateTimePicker>
+ * ```
+ */
+interface DateTimePickerRootProps {
+    /** 선택된 datetime (제어 모드, ISO 8601 UTC). 날짜+시간 모두 포함. */
+    value?: ISODateString | null;
+    /** 초기 datetime (비제어 모드) */
+    defaultValue?: ISODateString;
+    /** datetime 변경 콜백 */
+    onChange?: (value: ISODateString | null) => void;
+    /** 12/24시간제 */
+    format?: TimePickerFormat;
+    /** 분 step (1, 5, 15, 30 등) */
+    step?: number;
+    /** 비활성화 규칙 (날짜) */
+    disabled?: DisabledRule[] | boolean;
+    /** 읽기 전용 */
+    readOnly?: boolean;
+    /** 주 시작 요일 */
+    weekStartsOn?: WeekStartsOn;
+    /** 날짜·시간 표시 포맷 (Input용) */
+    displayFormat?: string;
+    /** BCP 47 locale */
+    locale?: string;
+    /** 날짜 어댑터 */
+    adapter?: DateAdapter;
+    /** 자식 컴포넌트 */
+    children: ReactNode;
+}
+/**
+ * DateTimePicker.Root — DatePicker + TimePicker 통합 컴포넌트.
+ *
+ * 단일 ISO datetime을 source of truth로 관리하고, 내부적으로
+ * DatePickerContext와 TimePickerContext를 동시에 제공한다.
+ * 따라서 DatePicker.Calendar, TimePicker.HourList 등 기존 컴포넌트를
+ * 그대로 재사용할 수 있다.
+ *
+ * 핵심 동작:
+ * - Calendar에서 날짜 클릭 → 날짜 부분만 변경, 시간 부분 보존, 팝오버 유지
+ * - TimePicker에서 시간 변경 → 시간 부분만 변경, 날짜 부분 보존
+ * - Escape / 바깥 클릭 → 팝오버 닫기 (확정)
+ */
+declare function DateTimePickerRoot({ value: controlledValue, defaultValue, onChange, format, step, disabled, readOnly, weekStartsOn, displayFormat, locale, adapter, children, }: DateTimePickerRootProps): react_jsx_runtime.JSX.Element;
+
+interface DateTimePickerInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
+}
+
+/**
+ * DateTimePicker — 날짜와 시간을 함께 선택하는 통합 컴포넌트.
+ *
+ * 단일 ISO datetime을 source of truth로 관리하며, 내부적으로
+ * DatePickerContext와 TimePickerContext를 동시에 제공한다.
+ * 따라서 DatePicker.Calendar, TimePicker.HourList 등 기존 컴포넌트가
+ * 그대로 동작한다.
+ *
+ * @example
+ * ```tsx
+ * <DateTimePicker value={dt} onChange={setDt} format="24h" step={15}>
+ *   <DateTimePicker.Input />
+ *   <DateTimePicker.Popover>
+ *     <DateTimePicker.Calendar />
+ *     <DateTimePicker.HourList />
+ *     <DateTimePicker.MinuteList />
+ *   </DateTimePicker.Popover>
+ * </DateTimePicker>
+ * ```
+ *
+ * @example 12시간제 모드
+ * ```tsx
+ * <DateTimePicker value={dt} onChange={setDt} format="12h" step={15}>
+ *   <DateTimePicker.Input />
+ *   <DateTimePicker.Popover>
+ *     <DateTimePicker.Calendar />
+ *     <DateTimePicker.HourList />
+ *     <DateTimePicker.MinuteList />
+ *     <DateTimePicker.AmPmToggle />
+ *   </DateTimePicker.Popover>
+ * </DateTimePicker>
+ * ```
+ */
+declare const DateTimePicker: typeof DateTimePickerRoot & {
+    Input: react.ForwardRefExoticComponent<DateTimePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    Popover: typeof DatePickerPopover;
+    Calendar: typeof DatePickerCalendar;
+    MonthGrid: typeof DatePickerMonthGrid;
+    YearGrid: typeof DatePickerYearGrid;
+    HourList: typeof TimePickerHourList;
+    MinuteList: typeof TimePickerMinuteList;
+    AmPmToggle: typeof TimePickerAmPmToggle;
+};
+
+interface UseDatePickerOptions {
+    /** 선택된 날짜 (제어 모드) */
+    value?: ISODateString | null;
+    /** 초기 날짜 (비제어 모드) */
+    defaultValue?: ISODateString;
+    /** 날짜 변경 콜백 */
+    onChange?: (value: ISODateString | null) => void;
+    /** 비활성화 규칙 */
+    disabled?: DisabledRule[];
+    /** 주 시작 요일 */
+    weekStartsOn?: WeekStartsOn;
+    /** 날짜 어댑터 */
+    adapter?: DateAdapter;
+}
+interface UseDatePickerReturn {
+    /** 현재 선택된 날짜 (ISO string) */
+    value: ISODateString | null;
+    /** 팝오버 열림 상태 */
+    isOpen: boolean;
+    /** 팝오버 열기 */
+    open: () => void;
+    /** 팝오버 닫기 */
+    close: () => void;
+    /** 팝오버 토글 */
+    toggle: () => void;
+    /** 날짜 선택 */
+    selectDate: (iso: ISODateString | null) => void;
+    /** 현재 표시 중인 월 (ISO string) */
+    viewMonth: ISODateString;
+    /** 표시 월 변경 */
+    setViewMonth: (iso: ISODateString) => void;
+    /** 캘린더 그리드 데이터 */
+    calendar: CalendarGrid;
+    /** 포커스된 날짜 */
+    focusedDate: ISODateString;
+    /** 포커스 날짜 변경 */
+    setFocusedDate: (iso: ISODateString) => void;
+    /** 이전 달로 이동 */
+    previousMonth: () => void;
+    /** 다음 달로 이동 */
+    nextMonth: () => void;
+    /** 고유 ID */
+    pickerId: string;
+    /** 날짜 어댑터 */
+    adapter: DateAdapter;
+}
+/**
+ * DatePicker의 상태를 관리하는 Hook.
+ * 컴포넌트를 사용하지 않고 완전 커스텀 UI를 구현할 때 사용한다.
+ *
+ * @example
+ * ```tsx
+ * function MyDatePicker() {
+ *   const { value, isOpen, calendar, open, selectDate } = useDatePicker({
+ *     onChange: (iso) => console.log(iso),
+ *   });
+ *   // ... 커스텀 렌더링
+ * }
+ * ```
+ */
+declare function useDatePicker(options?: UseDatePickerOptions): UseDatePickerReturn;
+
+/** 다음에 선택할 부분 (start | end) */
+type RangeSelectingTarget = 'start' | 'end';
+
+interface UseRangePickerOptions {
+    /** 선택된 범위 (제어 모드) */
+    value?: DateRange;
+    /** 초기 범위 (비제어 모드) */
+    defaultValue?: DateRange;
+    /** 범위 변경 콜백 */
+    onChange?: (range: DateRange) => void;
+    /** 비활성화 규칙 */
+    disabled?: DisabledRule[];
+    /** 주 시작 요일 */
+    weekStartsOn?: WeekStartsOn;
+    /** 날짜 어댑터 */
+    adapter?: DateAdapter;
+}
+interface UseRangePickerReturn {
+    /** 현재 선택된 범위 */
+    value: DateRange;
+    /** 다음에 선택될 부분 */
+    selectingTarget: RangeSelectingTarget;
+    /** 단일 날짜 클릭 핸들러 */
+    selectDate: (iso: ISODateString) => void;
+    /** 범위 직접 설정 */
+    setRange: (range: DateRange) => void;
+    /** 팝오버 열림 상태 */
+    isOpen: boolean;
+    open: () => void;
+    close: () => void;
+    toggle: () => void;
+    /** hover 날짜 (미리보기용) */
+    hoverDate: ISODateString | null;
+    setHoverDate: (iso: ISODateString | null) => void;
+    /** 현재 표시 중인 월 */
+    viewMonth: ISODateString;
+    setViewMonth: (iso: ISODateString) => void;
+    /** 캘린더 그리드 */
+    calendar: CalendarGrid;
+    /** 포커스된 날짜 */
+    focusedDate: ISODateString;
+    setFocusedDate: (iso: ISODateString) => void;
+    /** 이전 달로 이동 */
+    previousMonth: () => void;
+    /** 다음 달로 이동 */
+    nextMonth: () => void;
+    /** 고유 ID */
+    pickerId: string;
+    /** 어댑터 */
+    adapter: DateAdapter;
+}
+/**
+ * RangePicker 상태 관리 Hook.
+ * 컴포넌트 없이 완전 커스텀 UI를 만들 때 사용한다.
+ *
+ * @example
+ * ```tsx
+ * function MyRangePicker() {
+ *   const { value, calendar, selectDate, selectingTarget } = useRangePicker({
+ *     onChange: (range) => console.log(range.start, range.end),
+ *   });
+ *   // selectingTarget === 'start' → 시작일 선택 대기
+ *   // selectingTarget === 'end' → 종료일 선택 대기
+ * }
+ * ```
+ */
+declare function useRangePicker(options?: UseRangePickerOptions): UseRangePickerReturn;
+
+interface UseTimePickerOptions {
+    /** 선택된 시간 (제어 모드) */
+    value?: ISODateString | null;
+    /** 초기 시간 (비제어 모드) */
+    defaultValue?: ISODateString;
+    /** 시간 변경 콜백 */
+    onChange?: (value: ISODateString | null) => void;
+    /** 12/24시간제 */
+    format?: TimePickerFormat;
+    /** 분 step */
+    step?: number;
+    /** 초 표시 */
+    withSeconds?: boolean;
+}
+interface UseTimePickerReturn {
+    /** 현재 ISO datetime 값 */
+    value: ISODateString | null;
+    /** 현재 시간 (TimeValue) */
+    currentTime: TimeValue;
+    /** 시간 부분 변경 */
+    setTime: (partial: Partial<TimeValue>) => void;
+    /** 시(hour) 직접 설정 (12h 모드면 1-12, 24h 모드면 0-23) */
+    setHour: (hour: number) => void;
+    /** 분 설정 */
+    setMinute: (minute: number) => void;
+    /** 초 설정 */
+    setSecond: (second: number) => void;
+    /** AM/PM 변경 (12h 모드 전용) */
+    setPeriod: (period: 'AM' | 'PM') => void;
+    /** 사용 가능한 시 리스트 */
+    availableHours: number[];
+    /** 사용 가능한 분 리스트 (step 적용) */
+    availableMinutes: number[];
+    /** 12/24h 모드 */
+    format: TimePickerFormat;
+    /** 현재 표시용 시 (12h 모드면 1-12) */
+    displayHour: number;
+    /** 현재 AM/PM (12h 모드 전용, 24h면 null) */
+    period: 'AM' | 'PM' | null;
+    /** 고유 ID */
+    pickerId: string;
+}
+/**
+ * TimePicker 상태 관리 Hook.
+ * 컴포넌트 없이 완전 커스텀 UI를 구현할 때 사용한다.
+ *
+ * @example
+ * ```tsx
+ * function MyTimePicker() {
+ *   const {
+ *     currentTime, displayHour, period,
+ *     availableHours, availableMinutes,
+ *     setHour, setMinute, setPeriod,
+ *   } = useTimePicker({ format: '12h', step: 15 });
+ *   // displayHour = 1-12, period = "AM" | "PM"
+ *   // availableMinutes = [0, 15, 30, 45]
+ * }
+ * ```
+ */
+declare function useTimePicker(options?: UseTimePickerOptions): UseTimePickerReturn;
+
+export { DatePicker, type DatePickerCalendarClassNames, type DatePickerCalendarProps, type DatePickerInputProps, type DatePickerMonthGridClassNames, type DatePickerMonthGridProps, type DatePickerPopoverProps, type DatePickerRootProps, type DatePickerTriggerProps, type DatePickerYearGridClassNames, type DatePickerYearGridProps, DateTimePicker, type DateTimePickerInputProps, type DateTimePickerRootProps, type PresetKey, type RangeInputPart, RangePicker, type RangePickerCalendarClassNames, type RangePickerCalendarProps, type RangePickerInputProps, type RangePickerPopoverProps, type RangePickerPresetProps, type RangePickerPresetsClassNames, type RangePickerPresetsProps, type RangePickerRootProps, TimePicker, type TimePickerAmPmToggleClassNames, type TimePickerAmPmToggleProps, type TimePickerHourListClassNames, type TimePickerHourListProps, type TimePickerInputProps, type TimePickerMinuteListClassNames, type TimePickerMinuteListProps, type TimePickerRootProps, type UseDatePickerOptions, type UseDatePickerReturn, type UseRangePickerOptions, type UseRangePickerReturn, type UseTimePickerOptions, type UseTimePickerReturn, useDatePicker, useRangePicker, useTimePicker };