@kalyx/react 0.3.0 → 1.0.0-rc.0

package/dist/index.d.ts

@@ -31,6 +31,13 @@ interface DatePickerRootProps {
     defaultValue?: ISODateString;
     /** Callback fired when the date changes */
     onChange?: (value: ISODateString | null) => void;
+    /** Callback fired when the popover open state changes */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Callback fired when the calendar view navigates to a different month.
+     * The value is the ISO string of the first day of the newly-visible month (UTC).
+     */
+    onCalendarNavigate?: (viewMonth: ISODateString) => void;
     /** Disabled rules */
     disabled?: DisabledRule[] | boolean;
     /** Read-only */
@@ -41,6 +48,12 @@ interface DatePickerRootProps {
     displayFormat?: string;
     /** BCP 47 locale (e.g., "en-US", "ko-KR", "ja-JP") */
     locale?: string;
+    /**
+     * IANA timezone used for display and selection semantics (e.g., "Asia/Seoul").
+     * When set, the Input formats the value in this zone, Calendar highlights the matching civil
+     * day, and selecting a date emits the civil midnight of that day (UTC-ISO form).
+     */
+    displayTimezone?: string;
     /** Date adapter */
     adapter?: DateAdapter;
     /** Override ARIA labels (defaults to English) */
@@ -48,7 +61,7 @@ interface DatePickerRootProps {
     /** Child components */
     children: ReactNode;
 }
-declare function DatePickerRoot({ value: controlledValue, defaultValue, onChange, disabled, readOnly, weekStartsOn, displayFormat, locale, adapter, labels: labelsProp, children, }: DatePickerRootProps): react_jsx_runtime.JSX.Element;
+declare function DatePickerRoot({ value: controlledValue, defaultValue, onChange, onOpenChange, onCalendarNavigate, disabled, readOnly, weekStartsOn, displayFormat, locale, displayTimezone, adapter, labels: labelsProp, children, }: DatePickerRootProps): react_jsx_runtime.JSX.Element;
 
 interface DatePickerPopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
     children?: ReactNode;
@@ -138,6 +151,50 @@ interface DatePickerYearGridProps extends Omit<HTMLAttributes<HTMLDivElement>, '
  */
 declare function DatePickerYearGrid({ classNames, onSelect, ...props }: DatePickerYearGridProps): react_jsx_runtime.JSX.Element;
 
+/** Predefined single-date preset keys. Pass a custom ISO via `date` for anything else. */
+type DatePickerPresetKey = 'today' | 'tomorrow' | 'yesterday' | 'startOfMonth' | 'endOfMonth' | 'startOfYear';
+interface DatePickerPresetsClassNames {
+    root?: string;
+    preset?: string;
+    presetActive?: string;
+}
+interface DatePickerPresetsProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: DatePickerPresetsClassNames;
+    children?: ReactNode;
+}
+/**
+ * DatePicker.Presets — Container wrapping preset buttons.
+ *
+ * @example
+ * ```tsx
+ * <DatePicker.Presets>
+ *   <DatePicker.Preset value="today">Today</DatePicker.Preset>
+ *   <DatePicker.Preset value="tomorrow">Tomorrow</DatePicker.Preset>
+ * </DatePicker.Presets>
+ * ```
+ */
+declare function DatePickerPresets({ classNames, children, ...props }: DatePickerPresetsProps): react_jsx_runtime.JSX.Element;
+interface DatePickerPresetProps extends Omit<HTMLAttributes<HTMLButtonElement>, 'value'> {
+    /** Predefined preset key; omit when passing `date` directly */
+    value?: DatePickerPresetKey;
+    /** Pass an ISO date directly (alternative to `value`) */
+    date?: ISODateString;
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * DatePicker.Preset — One-click preset button to select a specific date.
+ *
+ * Pass either `value` (a preset key) or `date` (a direct ISO string).
+ *
+ * @example
+ * ```tsx
+ * <DatePicker.Preset value="today">Today</DatePicker.Preset>
+ * <DatePicker.Preset date="2026-01-01T00:00:00.000Z">New Year's</DatePicker.Preset>
+ * ```
+ */
+declare function DatePickerPreset({ value: presetKey, date: directDate, children, onClick, ...props }: DatePickerPresetProps): react_jsx_runtime.JSX.Element;
+
 interface DatePickerInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
     /** Date display format (defaults to parent's displayFormat) */
     format?: string;
@@ -180,6 +237,8 @@ declare const DatePicker: typeof DatePickerRoot & {
     Calendar: typeof DatePickerCalendar;
     MonthGrid: typeof DatePickerMonthGrid;
     YearGrid: typeof DatePickerYearGrid;
+    Presets: typeof DatePickerPresets;
+    Preset: typeof DatePickerPreset;
 };
 
 /**
@@ -203,6 +262,13 @@ interface RangePickerRootProps {
     defaultValue?: DateRange;
     /** Callback fired when the range changes */
     onChange?: (range: DateRange) => void;
+    /** Callback fired when the popover open state changes */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Callback fired when the calendar view navigates to a different month.
+     * The value is the ISO string of the first day of the newly-visible month (UTC).
+     */
+    onCalendarNavigate?: (viewMonth: ISODateString) => void;
     /** Disabled rules */
     disabled?: DisabledRule[] | boolean;
     /** Read-only */
@@ -213,6 +279,12 @@ interface RangePickerRootProps {
     displayFormat?: string;
     /** BCP 47 locale */
     locale?: string;
+    /**
+     * IANA timezone for display (e.g., "Asia/Seoul"). When set, inputs format in this zone,
+     * calendar highlighting uses civil-day comparison in this zone, and selected start/end are
+     * emitted as civil midnight of the clicked day in this zone (UTC-ISO form).
+     */
+    displayTimezone?: string;
     /** Date adapter */
     adapter?: DateAdapter;
     /** Override ARIA labels (defaults to English) */
@@ -220,7 +292,7 @@ interface RangePickerRootProps {
     /** Child components */
     children: ReactNode;
 }
-declare function RangePickerRoot({ value: controlledValue, defaultValue, onChange, disabled, readOnly, weekStartsOn, displayFormat, locale, adapter, labels: labelsProp, children, }: RangePickerRootProps): react_jsx_runtime.JSX.Element;
+declare function RangePickerRoot({ value: controlledValue, defaultValue, onChange, onOpenChange, onCalendarNavigate, disabled, readOnly, weekStartsOn, displayFormat, locale, displayTimezone, adapter, labels: labelsProp, children, }: RangePickerRootProps): react_jsx_runtime.JSX.Element;
 
 interface RangePickerPopoverProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
     children?: ReactNode;
@@ -245,10 +317,18 @@ interface RangePickerCalendarClassNames {
     dayInRange?: string;
     weekdayHeader?: string;
 }
+/**
+ * Selection mode for the calendar grid.
+ * - `'range'` (default): RangePicker behavior — two clicks (start, end) commit a custom range.
+ * - `'week'`: WeekPicker behavior — a single click commits the entire week containing the clicked day.
+ */
+type RangePickerCalendarSelectionMode = 'range' | 'week';
 interface RangePickerCalendarProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
     classNames?: RangePickerCalendarClassNames;
+    /** @default 'range' */
+    selectionMode?: RangePickerCalendarSelectionMode;
 }
-declare function RangePickerCalendar({ classNames, ...props }: RangePickerCalendarProps): react_jsx_runtime.JSX.Element;
+declare function RangePickerCalendar({ classNames, selectionMode, ...props }: RangePickerCalendarProps): react_jsx_runtime.JSX.Element;
 
 /** Predefined preset keys. Custom ranges are also supported. */
 type PresetKey = 'today' | 'yesterday' | 'last7days' | 'last30days' | 'thisWeek' | 'lastWeek' | 'thisMonth' | 'lastMonth' | 'thisYear';
@@ -371,6 +451,11 @@ interface TimePickerRootProps {
     step?: number;
     /** Whether to display seconds */
     withSeconds?: boolean;
+    /**
+     * IANA timezone used to interpret time. When set, the hour/minute controls read and write
+     * the time as observed in this zone.
+     */
+    displayTimezone?: string;
     /** Whether entire picker is disabled */
     disabled?: boolean;
     /** Read-only */
@@ -380,7 +465,7 @@ interface TimePickerRootProps {
     /** Child components */
     children: ReactNode;
 }
-declare function TimePickerRoot({ value: controlledValue, defaultValue, onChange, format, step, withSeconds, disabled, readOnly, labels: labelsProp, children, }: TimePickerRootProps): react_jsx_runtime.JSX.Element;
+declare function TimePickerRoot({ value: controlledValue, defaultValue, onChange, format, step, withSeconds, displayTimezone, disabled, readOnly, labels: labelsProp, children, }: TimePickerRootProps): react_jsx_runtime.JSX.Element;
 
 interface TimePickerHourListClassNames {
     root?: string;
@@ -475,6 +560,13 @@ interface DateTimePickerRootProps {
     defaultValue?: ISODateString;
     /** Callback fired when the datetime changes */
     onChange?: (value: ISODateString | null) => void;
+    /** Callback fired when the popover open state changes */
+    onOpenChange?: (isOpen: boolean) => void;
+    /**
+     * Callback fired when the calendar view navigates to a different month.
+     * The value is the ISO string of the first day of the newly-visible month (UTC).
+     */
+    onCalendarNavigate?: (viewMonth: ISODateString) => void;
     /** 12-hour or 24-hour mode */
     format?: TimePickerFormat;
     /** Minute step (e.g., 1, 5, 15, 30) */
@@ -489,6 +581,12 @@ interface DateTimePickerRootProps {
     displayFormat?: string;
     /** BCP 47 locale */
     locale?: string;
+    /**
+     * IANA timezone used for display (e.g., "Asia/Seoul"). When set, Calendar highlights match
+     * civil days in this zone, TimePicker reads/writes the time in this zone, and the Input
+     * formats the combined date+time in this zone.
+     */
+    displayTimezone?: string;
     /** Date adapter */
     adapter?: DateAdapter;
     /** Override ARIA labels (defaults to English) */
@@ -508,7 +606,7 @@ interface DateTimePickerRootProps {
  * - Changing time in TimePicker -> changes only the time, preserves the date
  * - Escape / outside click -> close the popover (commit)
  */
-declare function DateTimePickerRoot({ value: controlledValue, defaultValue, onChange, format, step, disabled, readOnly, weekStartsOn, displayFormat, locale, adapter, labels: labelsProp, children, }: DateTimePickerRootProps): react_jsx_runtime.JSX.Element;
+declare function DateTimePickerRoot({ value: controlledValue, defaultValue, onChange, onOpenChange, onCalendarNavigate, format, step, disabled, readOnly, weekStartsOn, displayFormat, locale, displayTimezone, adapter, labels: labelsProp, children, }: DateTimePickerRootProps): react_jsx_runtime.JSX.Element;
 
 interface DateTimePickerInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'onChange' | 'type'> {
 }
@@ -556,6 +654,183 @@ declare const DateTimePicker: typeof DateTimePickerRoot & {
     AmPmToggle: typeof TimePickerAmPmToggle;
 };
 
+/** Props for MonthPicker Root — identical to DatePicker Root, but `displayFormat` defaults to `"yyyy-MM"`. */
+type MonthPickerRootProps = DatePickerRootProps;
+/**
+ * MonthPicker.Root — thin wrapper over DatePicker.Root that defaults `displayFormat` to `"yyyy-MM"`.
+ * All other behavior (controlled/uncontrolled, displayTimezone, disabled rules) is inherited.
+ */
+declare function MonthPickerRoot(props: MonthPickerRootProps): react_jsx_runtime.JSX.Element;
+
+interface MonthPickerGridClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    navButton?: string;
+    grid?: string;
+    gridRow?: string;
+    month?: string;
+    monthSelected?: string;
+    monthCurrent?: string;
+    monthDisabled?: string;
+}
+interface MonthPickerGridProps extends Omit<HTMLAttributes<HTMLDivElement>, "role"> {
+    classNames?: MonthPickerGridClassNames;
+}
+/**
+ * MonthPicker.Grid — 12-month commit grid. Clicking a month selects it and closes the popover.
+ *
+ * Unlike `DatePicker.MonthGrid` (drilldown), this component commits the month selection
+ * via `ctx.selectDate`, emitting the month-start ISO string.
+ *
+ * @example
+ * ```tsx
+ * <MonthPicker value={month} onChange={setMonth} displayFormat="yyyy-MM">
+ *   <MonthPicker.Input />
+ *   <MonthPicker.Popover>
+ *     <MonthPicker.Grid />
+ *   </MonthPicker.Popover>
+ * </MonthPicker>
+ * ```
+ */
+declare function MonthPickerGrid({ classNames, ...props }: MonthPickerGridProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * MonthPicker — Headless month selector. Value is the first day of the selected month (UTC-ISO).
+ *
+ * Reuses DatePicker infrastructure (Root, Input, Trigger, Popover) so the public surface stays
+ * consistent. The only new building block is `MonthPicker.Grid`, a 12-month commit grid.
+ *
+ * @example Basic
+ * ```tsx
+ * const [month, setMonth] = useState<string | null>(null);
+ * <MonthPicker value={month} onChange={setMonth}>
+ *   <MonthPicker.Input placeholder="Pick a month" />
+ *   <MonthPicker.Popover>
+ *     <MonthPicker.Grid />
+ *   </MonthPicker.Popover>
+ * </MonthPicker>
+ * ```
+ */
+declare const MonthPicker: typeof MonthPickerRoot & {
+    Input: react.ForwardRefExoticComponent<DatePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    Trigger: react.ForwardRefExoticComponent<DatePickerTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+    Popover: typeof DatePickerPopover;
+    Grid: typeof MonthPickerGrid;
+};
+
+/** Props for YearPicker Root — identical to DatePicker Root, but `displayFormat` defaults to `"yyyy"`. */
+type YearPickerRootProps = DatePickerRootProps;
+/**
+ * YearPicker.Root — thin wrapper over DatePicker.Root that defaults `displayFormat` to `"yyyy"`.
+ */
+declare function YearPickerRoot(props: YearPickerRootProps): react_jsx_runtime.JSX.Element;
+
+interface YearPickerGridClassNames {
+    root?: string;
+    header?: string;
+    title?: string;
+    navButton?: string;
+    grid?: string;
+    gridRow?: string;
+    year?: string;
+    yearSelected?: string;
+    yearCurrent?: string;
+    yearDisabled?: string;
+}
+interface YearPickerGridProps extends Omit<HTMLAttributes<HTMLDivElement>, 'role'> {
+    classNames?: YearPickerGridClassNames;
+}
+/**
+ * YearPicker.Grid — 12-year decade commit grid. Clicking a year selects it and closes the popover.
+ *
+ * Unlike `DatePicker.YearGrid` (drilldown), this component commits the year selection via
+ * `ctx.selectDate`, emitting the year-start ISO string (Jan 1 at UTC midnight).
+ *
+ * @example
+ * ```tsx
+ * <YearPicker value={year} onChange={setYear}>
+ *   <YearPicker.Input />
+ *   <YearPicker.Popover>
+ *     <YearPicker.Grid />
+ *   </YearPicker.Popover>
+ * </YearPicker>
+ * ```
+ */
+declare function YearPickerGrid({ classNames, ...props }: YearPickerGridProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * YearPicker — Headless year selector. Value is Jan 1 of the selected year (UTC-ISO).
+ *
+ * Reuses DatePicker infrastructure (Root, Input, Trigger, Popover) so the public surface stays
+ * consistent. The only new building block is `YearPicker.Grid`, a 12-year decade commit grid.
+ *
+ * @example Basic
+ * ```tsx
+ * const [year, setYear] = useState<string | null>(null);
+ * <YearPicker value={year} onChange={setYear}>
+ *   <YearPicker.Input placeholder="Pick a year" />
+ *   <YearPicker.Popover>
+ *     <YearPicker.Grid />
+ *   </YearPicker.Popover>
+ * </YearPicker>
+ * ```
+ */
+declare const YearPicker: typeof YearPickerRoot & {
+    Input: react.ForwardRefExoticComponent<DatePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    Trigger: react.ForwardRefExoticComponent<DatePickerTriggerProps & react.RefAttributes<HTMLButtonElement>>;
+    Popover: typeof DatePickerPopover;
+    Grid: typeof YearPickerGrid;
+};
+
+/** Props for WeekPicker.Root — reuses RangePicker.Root. */
+type WeekPickerRootProps = RangePickerRootProps;
+/**
+ * WeekPicker.Root — thin wrapper over RangePicker.Root.
+ *
+ * The wrapper is necessary (rather than aliasing `RangePickerRoot` directly) because
+ * `Object.assign` on the exported root mutates the target. Without a distinct identity here,
+ * `WeekPicker.Calendar` would leak onto `RangePicker.Calendar`.
+ */
+declare function WeekPickerRoot(props: WeekPickerRootProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * WeekPicker.Calendar — renders the same calendar grid as `RangePicker.Calendar` but with
+ * `selectionMode="week"` so a single click commits the full week containing the clicked day.
+ *
+ * This is a thin wrapper over `RangePicker.Calendar` — the two share all keyboard navigation,
+ * ARIA semantics, and rendering logic.
+ */
+declare function WeekPickerCalendar(props: Omit<RangePickerCalendarProps, 'selectionMode'>): react_jsx_runtime.JSX.Element;
+/** Re-export RangePicker calendar classNames — the surface is identical. */
+type WeekPickerCalendarClassNames = RangePickerCalendarClassNames;
+type WeekPickerCalendarProps = Omit<RangePickerCalendarProps, 'selectionMode'>;
+
+/**
+ * WeekPicker — Headless week selector. Value is a `DateRange` spanning the entire week (start
+ * and end days inclusive, based on `weekStartsOn`). A single click selects the full week.
+ *
+ * Internally reuses `RangePicker` infrastructure (Root, Input, Popover). The only new primitive
+ * is `WeekPicker.Calendar`, which overrides click behavior to commit the full week.
+ *
+ * @example Basic
+ * ```tsx
+ * const [week, setWeek] = useState<DateRange>({ start: null, end: null });
+ * <WeekPicker value={week} onChange={setWeek}>
+ *   <WeekPicker.Input part="start" />
+ *   <WeekPicker.Input part="end" />
+ *   <WeekPicker.Popover>
+ *     <WeekPicker.Calendar />
+ *   </WeekPicker.Popover>
+ * </WeekPicker>
+ * ```
+ */
+declare const WeekPicker: typeof WeekPickerRoot & {
+    Input: react.ForwardRefExoticComponent<RangePickerInputProps & react.RefAttributes<HTMLInputElement>>;
+    Popover: typeof RangePickerPopover;
+    Calendar: typeof WeekPickerCalendar;
+};
+
 interface UseDatePickerOptions {
     /** Selected date (controlled mode) */
     value?: ISODateString | null;
@@ -569,6 +844,8 @@ interface UseDatePickerOptions {
     weekStartsOn?: WeekStartsOn;
     /** Date adapter */
     adapter?: DateAdapter;
+    /** IANA timezone for display (see DatePickerRoot#displayTimezone) */
+    displayTimezone?: string;
 }
 interface UseDatePickerReturn {
     /** Currently selected date (ISO string) */
@@ -634,6 +911,8 @@ interface UseRangePickerOptions {
     weekStartsOn?: WeekStartsOn;
     /** Date adapter */
     adapter?: DateAdapter;
+    /** IANA timezone for display (see RangePickerRoot#displayTimezone) */
+    displayTimezone?: string;
 }
 interface UseRangePickerReturn {
     /** Currently selected range */
@@ -699,6 +978,8 @@ interface UseTimePickerOptions {
     step?: number;
     /** Whether seconds are shown */
     withSeconds?: boolean;
+    /** IANA timezone for time interpretation (see TimePickerRoot#displayTimezone) */
+    displayTimezone?: string;
 }
 interface UseTimePickerReturn {
     /** Current ISO datetime value */
@@ -747,4 +1028,4 @@ interface UseTimePickerReturn {
  */
 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 };
+export { DatePicker, type DatePickerCalendarClassNames, type DatePickerCalendarProps, type DatePickerInputProps, type DatePickerMonthGridClassNames, type DatePickerMonthGridProps, type DatePickerPopoverProps, type DatePickerPresetKey, type DatePickerPresetProps, type DatePickerPresetsClassNames, type DatePickerPresetsProps, type DatePickerRootProps, type DatePickerTriggerProps, type DatePickerYearGridClassNames, type DatePickerYearGridProps, DateTimePicker, type DateTimePickerInputProps, type DateTimePickerRootProps, MonthPicker, type MonthPickerGridClassNames, type MonthPickerGridProps, type DatePickerInputProps as MonthPickerInputProps, type DatePickerPopoverProps as MonthPickerPopoverProps, type MonthPickerRootProps, type DatePickerTriggerProps as MonthPickerTriggerProps, 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, WeekPicker, type WeekPickerCalendarClassNames, type WeekPickerCalendarProps, type RangePickerInputProps as WeekPickerInputProps, type RangePickerPopoverProps as WeekPickerPopoverProps, type WeekPickerRootProps, YearPicker, type YearPickerGridClassNames, type YearPickerGridProps, type DatePickerInputProps as YearPickerInputProps, type DatePickerPopoverProps as YearPickerPopoverProps, type YearPickerRootProps, type DatePickerTriggerProps as YearPickerTriggerProps, useDatePicker, useRangePicker, useTimePicker };