@bug-on/m3-expressive 1.0.0

package/dist/pickers.d.mts

@@ -0,0 +1,1074 @@
+import * as React from 'react';
+
+/**
+ * @file date-time-pickers/shared/types.ts
+ *
+ * Shared TypeScript base types cho hệ thống Date Pickers và Time Pickers (tương lai).
+ * Được thiết kế để reuse across cả hai picker systems.
+ *
+ * @see https://m3.material.io/components/date-pickers/overview
+ */
+/**
+ * Chế độ hiển thị của picker.
+ * - `picker` — calendar/dial UI (mặc định)
+ * - `input`  — text input mode để nhập thủ công
+ *
+ * Tương đương `DisplayMode` enum trong Android Compose Material3.
+ */
+type DisplayMode = "picker" | "input";
+/**
+ * Ngày bắt đầu tuần.
+ * - `0` = Sunday (US standard)
+ * - `1` = Monday (ISO 8601, mặc định của thư viện này)
+ */
+type WeekStartsOn = 0 | 1;
+/**
+ * Cấu hình locale cho Date Picker.
+ * Dùng `Intl.DateTimeFormat` native API — zero bundle overhead.
+ *
+ * @example
+ * ```tsx
+ * const state = useDatePickerState({
+ *   locale: { locale: 'vi-VN', weekStartsOn: 1 }
+ * });
+ * ```
+ */
+interface DateLocale {
+    /**
+     * BCP 47 language tag.
+     * @example 'en-US', 'vi-VN', 'ja-JP'
+     * @default navigator.language (runtime)
+     */
+    locale?: string;
+    /**
+     * Ngày bắt đầu tuần.
+     * @default 1 (Monday)
+     */
+    weekStartsOn?: WeekStartsOn;
+}
+/** Required version — tất cả fields đã được resolved */
+type ResolvedDateLocale = Required<DateLocale>;
+/**
+ * Interface để filter các ngày/năm không thể chọn.
+ * Tương đương `SelectableDates` interface trong Android Compose Material3.
+ *
+ * @example
+ * ```tsx
+ * // Chặn ngày cuối tuần
+ * const selectableDates: SelectableDates = {
+ *   isSelectableDate(utcMs) {
+ *     const day = new Date(utcMs).getUTCDay();
+ *     return day !== 0 && day !== 6;
+ *   },
+ *   isSelectableYear(year) {
+ *     return year >= 2020;
+ *   }
+ * };
+ * ```
+ */
+interface SelectableDates {
+    /**
+     * Kiểm tra ngày có thể chọn không.
+     * @param utcTimeMs - UTC milliseconds (đã normalize về UTC midnight)
+     * @returns `true` nếu ngày có thể chọn
+     */
+    isSelectableDate(utcTimeMs: number): boolean;
+    /**
+     * Kiểm tra năm có thể chọn không.
+     * Năm không thể chọn sẽ bị disabled trong year grid.
+     * @param year - Full year (e.g., 2025)
+     * @returns `true` nếu năm có thể chọn
+     */
+    isSelectableYear(year: number): boolean;
+}
+/**
+ * Khoảng ngày với start và end.
+ * Cả hai đều có thể null trong quá trình selection.
+ */
+interface DateRange {
+    /** UTC milliseconds của ngày bắt đầu (UTC midnight). Null nếu chưa chọn. */
+    start: number | null;
+    /** UTC milliseconds của ngày kết thúc (UTC midnight). Null nếu chưa chọn. */
+    end: number | null;
+}
+
+/**
+ * @file date-picker/date-picker.types.ts
+ *
+ * TypeScript interfaces và types cho Date Picker component system.
+ * Tương đương với DatePickerState + rememberDatePickerState trong Android Compose.
+ *
+ * @see https://m3.material.io/components/date-pickers/overview
+ */
+
+/**
+ * State object cho DatePicker — hoisted state pattern.
+ * Tương đương `DatePickerState` class trong Android Compose Material3.
+ *
+ * @example
+ * ```tsx
+ * const state = useDatePickerState({ locale: { locale: 'vi-VN' } });
+ *
+ * <DatePicker state={state} />
+ * <p>Selected: {state.selectedDateMs}</p>
+ * ```
+ */
+interface DatePickerState {
+    /** UTC ms của ngày đang được chọn. Null nếu chưa chọn. */
+    readonly selectedDateMs: number | null;
+    /** UTC ms của ngày 1 của tháng đang hiển thị trong calendar. */
+    readonly displayedMonthMs: number;
+    /** Chế độ hiển thị hiện tại: 'picker' | 'input' */
+    readonly displayMode: DisplayMode;
+    /** Khoảng năm có thể chọn [min, max] */
+    readonly yearRange: [number, number];
+    /** Locale đã được resolve (với default values) */
+    readonly locale: ResolvedDateLocale;
+    /** SelectableDates config */
+    readonly selectableDates: SelectableDates;
+    /** Chọn một ngày theo UTC ms. Truyền null để bỏ chọn. */
+    selectDate(ms: number | null): void;
+    /** Navigate tháng trước hoặc sau */
+    navigateMonth(direction: "prev" | "next"): void;
+    /** Navigate đến tháng+năm cụ thể */
+    navigateToMonth(year: number, month: number): void;
+    /** Chuyển đổi giữa 'picker' và 'input' mode */
+    setDisplayMode(mode: DisplayMode): void;
+    /** Reset về trạng thái ban đầu */
+    reset(): void;
+}
+/**
+ * Options cho `useDatePickerState` hook.
+ * Tương đương parameters của `rememberDatePickerState()` trong Compose.
+ */
+interface UseDatePickerStateOptions {
+    /**
+     * Ngày được chọn ban đầu (UTC ms hoặc null).
+     * @default null
+     */
+    initialSelectedDateMs?: number | null;
+    /**
+     * Tháng hiển thị ban đầu (UTC ms của bất kỳ ngày nào trong tháng đó).
+     * @default tháng hiện tại
+     */
+    initialDisplayedMonthMs?: number;
+    /**
+     * Khoảng năm có thể chọn [min, max].
+     * @default [1900, 2100]
+     */
+    yearRange?: [number, number];
+    /**
+     * Filter ngày/năm không thể chọn.
+     * @default ALL_DATES_SELECTABLE
+     */
+    selectableDates?: SelectableDates;
+    /**
+     * Chế độ hiển thị ban đầu.
+     * @default 'picker'
+     */
+    initialDisplayMode?: DisplayMode;
+    /**
+     * Locale configuration cho calendar.
+     * @default { weekStartsOn: 1 } (Monday)
+     */
+    locale?: DateLocale;
+}
+/**
+ * State object cho DateRangePicker — hoisted state pattern.
+ * Tương đương `DateRangePickerState` class trong Android Compose Material3.
+ */
+interface DateRangePickerState {
+    /** UTC ms của ngày bắt đầu. Null nếu chưa chọn. */
+    readonly selectedStartMs: number | null;
+    /** UTC ms của ngày kết thúc. Null nếu chưa chọn. */
+    readonly selectedEndMs: number | null;
+    /** UTC ms của ngày 1 của tháng đang hiển thị. */
+    readonly displayedMonthMs: number;
+    /** Chế độ hiển thị: 'picker' | 'input' */
+    readonly displayMode: DisplayMode;
+    /** Khoảng năm có thể chọn */
+    readonly yearRange: [number, number];
+    /** Locale đã được resolve */
+    readonly locale: ResolvedDateLocale;
+    /** SelectableDates config */
+    readonly selectableDates: SelectableDates;
+    /**
+     * Chọn một ngày.
+     * Logic: click 1 = set start, click 2 = set end (nếu ms > start).
+     * Nếu ms <= start hoặc đã có cả start lẫn end, reset về start mới.
+     */
+    selectDate(ms: number): void;
+    /** Xóa toàn bộ selection */
+    clearRange(): void;
+    /** Navigate tháng */
+    navigateMonth(direction: "prev" | "next"): void;
+    /** Navigate đến tháng+năm cụ thể */
+    navigateToMonth(year: number, month: number): void;
+    /** Chuyển display mode */
+    setDisplayMode(mode: DisplayMode): void;
+    /** Reset */
+    reset(): void;
+}
+/** Options cho `useDateRangePickerState` */
+interface UseDateRangePickerStateOptions {
+    /** Start date ban đầu (UTC ms) */
+    initialStartMs?: number | null;
+    /** End date ban đầu (UTC ms) */
+    initialEndMs?: number | null;
+    /** Tháng hiển thị ban đầu */
+    initialDisplayedMonthMs?: number;
+    /** Khoảng năm @default [1900, 2100] */
+    yearRange?: [number, number];
+    /** Filter ngày không thể chọn */
+    selectableDates?: SelectableDates;
+    /** Display mode ban đầu @default 'picker' */
+    initialDisplayMode?: DisplayMode;
+    /** Locale config */
+    locale?: DateLocale;
+}
+/** Props cho `DatePicker` component */
+interface DatePickerProps {
+    /** Hoisted state từ `useDatePickerState()` */
+    state: DatePickerState;
+    /**
+     * Hiện nút toggle giữa picker và input mode.
+     * @default true
+     */
+    showModeToggle?: boolean;
+    /**
+     * Title slot — hiển thị ở phía trên header.
+     * @default "Select date"
+     */
+    title?: React.ReactNode;
+    /**
+     * Headline slot — hiển thị ngày đang chọn.
+     * @default formatted selected date hoặc "--"
+     */
+    headline?: React.ReactNode;
+    /** CSS class bổ sung cho container */
+    className?: string;
+}
+/** Props cho `DateRangePicker` component */
+interface DateRangePickerProps {
+    /** Hoisted state từ `useDateRangePickerState()` */
+    state: DateRangePickerState;
+    /**
+     * Hiện nút toggle picker/input.
+     * @default false (range picker thường không dùng input mode)
+     */
+    showModeToggle?: boolean;
+    /**
+     * Title slot.
+     * @default "Select dates"
+     */
+    title?: React.ReactNode;
+    /** CSS class bổ sung */
+    className?: string;
+}
+/** Props cho `DatePickerDialog` component */
+interface DatePickerDialogProps {
+    /** Trạng thái mở/đóng dialog */
+    open: boolean;
+    /** Callback khi dialog cần đóng (click scrim, Escape) */
+    onDismiss: () => void;
+    /** Title cho dialog (dùng cho screen reader và accessibility) */
+    title?: string;
+    /**
+     * Nút xác nhận — caller tự render (ví dụ: Button "OK").
+     * Dialog không set up event handlers — caller tự xử lý.
+     */
+    confirmButton: React.ReactNode;
+    /**
+     * Nút hủy — optional.
+     * @default null
+     */
+    dismissButton?: React.ReactNode;
+    /** Content — thường là `DatePicker` hoặc `DateRangePicker` */
+    children: React.ReactNode;
+    /** CSS class bổ sung cho dialog panel */
+    className?: string;
+}
+/** Props cho `DatePickerInput` component */
+interface DatePickerInputProps {
+    /**
+     * Giá trị text hiện tại (format: "MM/DD/YYYY").
+     */
+    value: string;
+    /** Callback khi user thay đổi text */
+    onChange(value: string): void;
+    /**
+     * Callback khi user confirm ngày (blur hoặc Enter).
+     * Truyền parsed UTC ms, hoặc null nếu input không hợp lệ.
+     */
+    onCommit(ms: number | null): void;
+    /** Label cho text field */
+    label?: string;
+    /** Error message (hiện khi format không hợp lệ) */
+    error?: string;
+    /** Locale string để hint format phù hợp */
+    locale?: string;
+    /** CSS class bổ sung */
+    className?: string;
+}
+
+/**
+ * @file date-picker/date-picker.tsx
+ *
+ * DatePicker — calendar UI component (không bao gồm dialog wrapper).
+ * Tương đương composable `DatePicker` trong Android Compose Material3.
+ *
+ * Layout:
+ *   CalendarHeader (title, headline, month nav)
+ *   ↓
+ *   CalendarGrid | YearPickerGrid (AnimatePresence toggle)
+ *   ↓
+ *   DatePickerInput (khi displayMode === 'input')
+ *
+ * @see https://m3.material.io/components/date-pickers/overview
+ */
+
+/**
+ * DatePicker calendar UI.
+ *
+ * @example
+ * ```tsx
+ * const state = useDatePickerState({ locale: { locale: 'vi-VN' } });
+ *
+ * <DatePicker
+ *   state={state}
+ *   showModeToggle
+ *   title="Chọn ngày"
+ * />
+ * ```
+ */
+declare const DatePicker: React.FC<DatePickerProps>;
+
+/**
+ * @file date-picker/date-picker.tokens.ts
+ *
+ * MD3 Design tokens cho Date Picker component.
+ * Map từ DatePickerModalTokens.kt → CSS variables trong packages/tailwind/src/index.css.
+ *
+ * @see docs/m3/date-and-time-pickers/date-pickers/DatePickerModalTokens.kt
+ * @see packages/tailwind/src/index.css
+ */
+/** Color tokens — dùng CSS custom properties từ MD3 theme */
+declare const DP_COLORS: {
+    /** Dialog container — SurfaceContainerHigh */
+    readonly container: "var(--md-sys-color-surface-container-high)";
+    /** Selected day background — Primary */
+    readonly daySelected: "var(--md-sys-color-primary)";
+    /** Selected day text — OnPrimary */
+    readonly daySelectedText: "var(--md-sys-color-on-primary)";
+    /** Today outline — Primary */
+    readonly todayOutline: "var(--md-sys-color-primary)";
+    /** Today text — Primary */
+    readonly todayText: "var(--md-sys-color-primary)";
+    /** Unselected day text — OnSurface */
+    readonly dayText: "var(--md-sys-color-on-surface)";
+    /** Weekday header text — OnSurface */
+    readonly weekdayText: "var(--md-sys-color-on-surface)";
+    /** Header headline + supporting text — OnSurfaceVariant */
+    readonly headerText: "var(--md-sys-color-on-surface-variant)";
+    /** Range highlight background — SecondaryContainer */
+    readonly rangeHighlight: "var(--md-sys-color-secondary-container)";
+    /** Range highlight text — OnSecondaryContainer */
+    readonly rangeText: "var(--md-sys-color-on-secondary-container)";
+    /** Unselected year text — OnSurfaceVariant */
+    readonly yearText: "var(--md-sys-color-on-surface-variant)";
+    /** Selected year background — Primary */
+    readonly yearSelected: "var(--md-sys-color-primary)";
+    /** Selected year text — OnPrimary */
+    readonly yearSelectedText: "var(--md-sys-color-on-primary)";
+    /** Scrim overlay */
+    readonly scrim: "var(--md-sys-color-scrim)";
+};
+/** Shape tokens — corner radii từ MD3 shape scale */
+declare const DP_SHAPE: {
+    /** Dialog container — CornerExtraLarge = 28px */
+    readonly container: "var(--md-sys-shape-corner-extra-large)";
+    /** Day cell — CornerFull = pill */
+    readonly day: "var(--md-sys-shape-corner-full)";
+    /** Range start/end indicator — CornerFull */
+    readonly rangeEndpoint: "var(--md-sys-shape-corner-full)";
+    /** Year chip — CornerFull */
+    readonly year: "var(--md-sys-shape-corner-full)";
+};
+/** Fixed dimension tokens từ DatePickerModalTokens.kt */
+declare const DP_SIZE: {
+    /** Dialog container width */
+    readonly containerWidth: 360;
+    /** Dialog container height */
+    readonly containerHeight: 568;
+    /** Day cell width/height */
+    readonly dayCell: 40;
+    /** Today border width */
+    readonly todayOutlineWidth: 1;
+    /** Header container height */
+    readonly headerHeight: 120;
+    /** Range picker header height */
+    readonly rangeHeaderHeight: 128;
+    /** Year chip height */
+    readonly yearChipHeight: 36;
+    /** Year chip width */
+    readonly yearChipWidth: 72;
+};
+/**
+ * Tailwind utility class strings cho Date Picker elements.
+ * Sử dụng với `cn()` function.
+ */
+declare const DP_CLASSES: {
+    /** Dialog container */
+    readonly dialog: string;
+    /** Day cell container */
+    readonly dayCell: string;
+    /** Day cell: selected state */
+    readonly dayCellSelected: string;
+    /** Day cell: today state */
+    readonly dayCellToday: string;
+    /** Day cell: disabled state */
+    readonly dayCellDisabled: "opacity-[0.38] pointer-events-none cursor-not-allowed";
+    /** Range highlight (between start and end) */
+    readonly rangeHighlight: "bg-m3-secondary-container";
+    /** Weekday header row */
+    readonly weekdayRow: "text-[length:var(--md-typescale-body-large-size,14px)] text-m3-on-surface";
+};
+
+/**
+ * @file date-picker/date-picker-dialog.tsx
+ *
+ * Modal container cho Date Pickers — tái sử dụng Dialog + DialogPortal từ thư viện bug-on/md3-react.
+ * Tương đương composable `DatePickerDialog` trong Android Compose Material3.
+ *
+ * Tokens từ DatePickerModalTokens.kt:
+ * - ContainerColor = SurfaceContainerHigh (#ece6f0)
+ * - ContainerShape = CornerExtraLarge (28px)
+ * - ContainerElevation = Level3
+ * - ContainerWidth = 360px, ContainerHeight = 568px (single date)
+ *
+ * @see https://m3.material.io/components/date-pickers/overview
+ */
+
+/**
+ * Modal Date Picker dialog với MD3 Expressive spring animations.
+ *
+ * Tái sử dụng `<Dialog>` (Root) và `<DialogPortal>` (AnimatePresence + Portal lifecycle)
+ * từ thư viện, trong khi tự quản lý Overlay và Content để giữ đúng
+ * layout specs MD3 Date Picker (không có padding p-6, kích thước cố định, animation riêng).
+ *
+ * @example
+ * ```tsx
+ * const state = useDatePickerState();
+ * const [open, setOpen] = React.useState(false);
+ *
+ * <DatePickerDialog
+ *   open={open}
+ *   onDismiss={() => setOpen(false)}
+ *   confirmButton={
+ *     <Button variant="text" onClick={() => { handleConfirm(state.selectedDateMs); setOpen(false); }}>
+ *       OK
+ *     </Button>
+ *   }
+ *   dismissButton={
+ *     <Button variant="text" onClick={() => setOpen(false)}>Cancel</Button>
+ *   }
+ * >
+ *   <DatePicker state={state} />
+ * </DatePickerDialog>
+ * ```
+ */
+declare const DatePickerDialog: React.FC<DatePickerDialogProps>;
+
+/**
+ * @file date-picker/date-picker-input.tsx
+ *
+ * Text input mode cho Date Picker — nhập ngày thủ công dạng MM/DD/YYYY.
+ * Sử dụng TextField component của thư viện.
+ *
+ * @see https://m3.material.io/components/date-pickers/overview
+ */
+
+/**
+ * Text input cho Date Picker với format MM/DD/YYYY.
+ * Validate realtime, commit khi blur hoặc Enter.
+ */
+declare const DatePickerInput: React.FC<DatePickerInputProps>;
+
+/**
+ * @file date-picker/date-range-picker.tsx
+ *
+ * DateRangePicker — calendar UI cho chọn khoảng ngày.
+ * Tương đương composable `DateRangePicker` trong Android Compose Material3.
+ *
+ * Khác biệt so với DatePicker:
+ * - Highlight range giữa start và end (SecondaryContainer)
+ * - Headline hiển thị "Start date → End date"
+ * - Default title: "Select dates" (plural)
+ *
+ * @see https://m3.material.io/components/date-pickers/overview
+ */
+
+/**
+ * DateRangePicker calendar UI.
+ *
+ * @example
+ * ```tsx
+ * const state = useDateRangePickerState();
+ *
+ * <DateRangePicker
+ *   state={state}
+ *   title="Select travel dates"
+ * />
+ * ```
+ */
+declare const DateRangePicker: React.FC<DateRangePickerProps>;
+
+/**
+ * @file date-picker/use-date-picker-state.ts
+ *
+ * Core state hook cho DatePicker — hoisted state pattern.
+ * Tương đương `rememberDatePickerState()` trong Android Compose Material3.
+ *
+ * @example
+ * ```tsx
+ * const state = useDatePickerState({
+ *   locale: { locale: 'vi-VN', weekStartsOn: 1 },
+ *   selectableDates: {
+ *     isSelectableDate: (ms) => new Date(ms).getUTCDay() !== 0,
+ *     isSelectableYear: (year) => year >= 2020,
+ *   }
+ * });
+ *
+ * <DatePicker state={state} />
+ * <p>Selected: {state.selectedDateMs}</p>
+ * ```
+ */
+
+/**
+ * Hook quản lý state cho DatePicker.
+ *
+ * @param options - Cấu hình ban đầu cho state
+ * @returns `DatePickerState` object với các actions
+ */
+declare const useDatePickerState: (options?: UseDatePickerStateOptions) => DatePickerState;
+
+/**
+ * @file date-picker/use-date-range-picker-state.ts
+ *
+ * Core state hook cho DateRangePicker — hoisted state pattern.
+ * Tương đương `rememberDateRangePickerState()` trong Android Compose Material3.
+ *
+ * Logic chọn range:
+ * - Click 1: set start date
+ * - Click 2 (ms > start): set end date → range complete
+ * - Click 2 (ms <= start): reset, set start = ms
+ * - Nếu đã có cả start lẫn end: reset, set start = ms
+ *
+ * @example
+ * ```tsx
+ * const state = useDateRangePickerState();
+ *
+ * <DateRangePicker state={state} />
+ * <p>Start: {state.selectedStartMs}, End: {state.selectedEndMs}</p>
+ * ```
+ */
+
+/**
+ * Hook quản lý state cho DateRangePicker.
+ *
+ * @param options - Cấu hình ban đầu
+ * @returns `DateRangePickerState` object với các actions
+ */
+declare const useDateRangePickerState: (options?: UseDateRangePickerStateOptions) => DateRangePickerState;
+
+/**
+ * @file time-picker/time-picker.types.ts
+ *
+ * TypeScript interfaces và types cho Time Picker component system.
+ * Port từ `TimePickerState` interface trong Android Compose Material3.
+ *
+ * @see https://m3.material.io/components/time-pickers/overview
+ * @see docs/m3/date-and-time-pickers/time-pickers/TimePickerState.md
+ */
+
+/**
+ * Phần nào của time đang được chọn — hour hoặc minute.
+ * Tương đương `TimePickerSelectionMode` enum trong Android Compose.
+ */
+type TimePickerSelectionMode = "hour" | "minute";
+/** Visual arrangement of the clock display. */
+type TimePickerLayout = "auto" | "vertical" | "horizontal";
+/**
+ * State object cho TimePicker — hoisted state pattern.
+ * Tương đương `TimePickerState` interface trong Android Compose Material3.
+ *
+ * Tách biệt `hour`/`minute` (luôn valid) và `hourInput`/`minuteInput`
+ * (raw input, có thể invalid mid-typing trong TimeInput mode).
+ *
+ * @example
+ * ```tsx
+ * const state = useTimePickerState({ initialHour: 7, initialMinute: 0 });
+ *
+ * <TimePicker state={state} />
+ * <p>Selected: {state.hour}:{String(state.minute).padStart(2, '0')}</p>
+ * ```
+ */
+interface TimePickerState {
+    /** Giờ hiện tại (0-23). Luôn valid. */
+    readonly hour: number;
+    /** Phút hiện tại (0-59). Luôn valid. */
+    readonly minute: number;
+    /**
+     * Raw input cho giờ — UI bind vào giá trị này.
+     * Có thể invalid khi đang nhập (vd: đang gõ "1" trước khi gõ "2").
+     * Khi valid thì tự động cập nhật `hour`.
+     */
+    readonly hourInput: number;
+    /**
+     * Raw input cho phút — UI bind vào giá trị này.
+     * Có thể invalid khi đang nhập.
+     * Khi valid thì tự động cập nhật `minute`.
+     */
+    readonly minuteInput: number;
+    /** Sử dụng định dạng 24h (`true`) hay 12h AM/PM (`false`). */
+    readonly is24hour: boolean;
+    /** Phần nào đang được chọn (hour hoặc minute). */
+    readonly selection: TimePickerSelectionMode;
+    /** `true` nếu cả hourInput và minuteInput đều valid. */
+    readonly isInputValid: boolean;
+    /** `true` nếu hourInput là valid hour (0-23 với 24h, 1-12 với 12h). */
+    readonly isHourInputValid: boolean;
+    /** `true` nếu minuteInput là valid minute (0-59). */
+    readonly isMinuteInputValid: boolean;
+    /** `true` nếu giờ hiện tại là PM (hour >= 12). */
+    readonly isPm: boolean;
+    /**
+     * Set giờ hợp lệ (0-23). Cũng cập nhật hourInput.
+     * Dùng cho clock dial interaction.
+     */
+    setHour(h: number): void;
+    /**
+     * Set phút hợp lệ (0-59). Cũng cập nhật minuteInput.
+     * Dùng cho clock dial interaction.
+     */
+    setMinute(m: number): void;
+    /**
+     * Set raw hour input (có thể invalid).
+     * Dùng cho TimeInput text field.
+     * Chỉ cập nhật `hour` khi giá trị valid.
+     */
+    setHourInput(h: number): void;
+    /**
+     * Set raw minute input (có thể invalid).
+     * Dùng cho TimeInput text field.
+     * Chỉ cập nhật `minute` khi giá trị valid.
+     */
+    setMinuteInput(m: number): void;
+    /** Đổi selection giữa 'hour' và 'minute'. */
+    setSelection(mode: TimePickerSelectionMode): void;
+    /**
+     * Toggle AM/PM.
+     * Tự động convert giờ (vd: 7 AM → 19, 15 PM → 3 AM).
+     */
+    setIsPm(pm: boolean): void;
+    /** Reset về trạng thái ban đầu. */
+    reset(): void;
+}
+/**
+ * Options cho `useTimePickerState` hook.
+ * Tương đương parameters của `rememberTimePickerState()` trong Compose.
+ *
+ * @example
+ * ```tsx
+ * const state = useTimePickerState({
+ *   initialHour: 14,
+ *   initialMinute: 30,
+ *   is24hour: true,
+ * });
+ * ```
+ */
+interface UseTimePickerStateOptions {
+    /**
+     * Giờ ban đầu (0-23).
+     * @default 0
+     */
+    initialHour?: number;
+    /**
+     * Phút ban đầu (0-59).
+     * @default 0
+     */
+    initialMinute?: number;
+    /**
+     * Sử dụng định dạng 24h hay 12h AM/PM.
+     * @default false (12h format với AM/PM selector)
+     */
+    is24hour?: boolean;
+}
+/**
+ * Props cho `TimePicker` component (dial/clock mode).
+ * Tương đương `TimePicker` composable trong Android Compose.
+ */
+interface TimePickerProps {
+    /** Hoisted state từ `useTimePickerState()`. */
+    state: TimePickerState;
+    /**
+     * Arrangement of the clock header and dial.
+     * `auto` uses the Android-style horizontal layout in a sufficiently wide
+     * landscape viewport and the vertical layout elsewhere.
+     * @default "auto"
+     */
+    layout?: TimePickerLayout;
+    /** CSS class bổ sung cho container. */
+    className?: string;
+}
+/**
+ * Props cho `TimeInput` component (text input mode).
+ * Tương đương `TimeInput` composable trong Android Compose.
+ */
+interface TimeInputProps {
+    /** Hoisted state từ `useTimePickerState()`. */
+    state: TimePickerState;
+    /** CSS class bổ sung cho container. */
+    className?: string;
+}
+/**
+ * Props cho `TimePickerDialog` component.
+ * Tương đương `TimePickerDialog` composable trong Android Compose.
+ */
+interface TimePickerDialogProps {
+    /** Trạng thái mở/đóng dialog. */
+    open: boolean;
+    /** Callback khi dialog cần đóng (click scrim, Escape). */
+    onDismiss: () => void;
+    /**
+     * Nút xác nhận — caller tự render (vd: Button "OK").
+     * Dialog không set up event handlers — caller tự xử lý.
+     */
+    confirmButton: React.ReactNode;
+    /**
+     * Nút hủy — optional.
+     * @default null
+     */
+    dismissButton?: React.ReactNode;
+    /**
+     * Nút toggle giữa Dial và Input mode — optional.
+     * Hiển thị ở bottom-left của footer.
+     */
+    modeToggleButton?: React.ReactNode;
+    /**
+     * Title hiển thị trên dialog (accessible).
+     * @default "Select time"
+     */
+    title?: string;
+    /** Content — thường là `<TimePicker>` hoặc `<TimeInput>`. */
+    children: React.ReactNode;
+    /** CSS class bổ sung cho dialog panel. */
+    className?: string;
+}
+
+/**
+ * @file time-picker/time-input.tsx
+ *
+ * TimeInput — text input mode cho time entry.
+ *
+ * Layout:
+ * ```
+ *   ┌────────────────────────────────┐
+ *   │ Enter time                     │  ← headline (labelMedium)
+ *   │ [07] : [00] [AM]              │  ← input fields + PeriodSelector
+ *   │              [PM]             │
+ *   │  Hour   Minute                │  ← helper labels (bodySmall)
+ *   └────────────────────────────────┘
+ * ```
+ *
+ * Behavior:
+ * - Hai `<input>` cho giờ và phút
+ * - Auto-advance: nhập đủ 2 digits hợp lệ → focus field kế
+ * - Validation: error state nếu giá trị ngoài range
+ * - AM/PM toggle bên phải (ẩn khi is24hour)
+ *
+ * Port từ `TimeInputImpl` trong TimePicker.kt.
+ *
+ * @see docs/m3/date-and-time-pickers/time-pickers/TimePicker.kt (TimeInputImpl)
+ */
+
+/**
+ * TimeInput — text input mode.
+ *
+ * Dùng cùng với `useTimePickerState`:
+ *
+ * @example
+ * ```tsx
+ * const state = useTimePickerState({ initialHour: 9, initialMinute: 30 });
+ *
+ * // Standalone
+ * <TimeInput state={state} />
+ *
+ * // In dialog (with toggle)
+ * <TimePickerDialog
+ *   open={open}
+ *   onDismiss={() => setOpen(false)}
+ *   confirmButton={<Button variant="text" onClick={() => setOpen(false)}>OK</Button>}
+ * >
+ *   <TimeInput state={state} />
+ * </TimePickerDialog>
+ * ```
+ */
+declare const TimeInput: React.FC<TimeInputProps>;
+
+/**
+ * @file time-picker/time-picker.tsx
+ *
+ * Android MD3 clock picker. The picker uses a compact vertical arrangement in
+ * portrait and moves the clock beside the display on larger landscape screens.
+ */
+
+declare const TimePicker: React.FC<TimePickerProps>;
+
+/**
+ * @file time-picker/time-picker.tokens.ts
+ *
+ * MD3 Design tokens cho Time Picker component system.
+ * Verified mapping từ:
+ *   - TimePickerTokens.kt → ClockDial, TimeSelector, PeriodSelector (Picker mode)
+ *   - TimeInputTokens.kt  → TimeField, PeriodSelector (Input mode)
+ *
+ * CSS variables → packages/tokens/src/colors.css
+ * Tailwind classes → packages/tailwind/src/index.css
+ *
+ * @see docs/m3/date-and-time-pickers/time-pickers/TimePickerTokens.kt
+ * @see docs/m3/date-and-time-pickers/time-pickers/TimeInputTokens.kt
+ */
+/**
+ * Color tokens cho Time Picker — map từ TimePickerTokens.kt + TimeInputTokens.kt.
+ * Dùng CSS custom properties từ MD3 theme (packages/tokens/src/colors.css).
+ */
+declare const TP_COLORS: {
+    /** Dial background — SurfaceContainerHighest */
+    readonly clockDial: "var(--md-sys-color-surface-container-highest)";
+    /** Selected number text — OnPrimary */
+    readonly clockDialSelected: "var(--md-sys-color-on-primary)";
+    /** Unselected number text — OnSurface */
+    readonly clockDialUnselected: "var(--md-sys-color-on-surface)";
+    /** Selector handle circle — Primary */
+    readonly selectorHandle: "var(--md-sys-color-primary)";
+    /** Selector track line — Primary */
+    readonly selectorTrack: "var(--md-sys-color-primary)";
+    /** Selector center dot — Primary */
+    readonly selectorCenter: "var(--md-sys-color-primary)";
+    /** Picker/Input container — SurfaceContainerHigh */
+    readonly container: "var(--md-sys-color-surface-container-high)";
+    /** Selected selector (hour/min button) — PrimaryContainer */
+    readonly timeSelectorSelected: "var(--md-sys-color-primary-container)";
+    /** Unselected selector — SurfaceContainerHighest */
+    readonly timeSelectorUnselected: "var(--md-sys-color-surface-container-highest)";
+    /** Selected selector text — OnPrimaryContainer */
+    readonly timeSelectorSelectedText: "var(--md-sys-color-on-primary-container)";
+    /** Unselected selector text — OnSurface */
+    readonly timeSelectorUnselectedText: "var(--md-sys-color-on-surface)";
+    /** AM/PM selected background — TertiaryContainer */
+    readonly periodSelected: "var(--md-sys-color-tertiary-container)";
+    /** AM/PM unselected background — transparent */
+    readonly periodUnselected: "transparent";
+    /** AM/PM selected text — OnTertiaryContainer */
+    readonly periodSelectedText: "var(--md-sys-color-on-tertiary-container)";
+    /** AM/PM unselected text — OnSurfaceVariant */
+    readonly periodUnselectedText: "var(--md-sys-color-on-surface-variant)";
+    /** AM/PM border — Outline */
+    readonly periodOutline: "var(--md-sys-color-outline)";
+    /** Time field default background — SurfaceContainerHighest */
+    readonly timeField: "var(--md-sys-color-surface-container-highest)";
+    /** Time field focused background — PrimaryContainer */
+    readonly timeFieldFocus: "var(--md-sys-color-primary-container)";
+    /** Time field focused text — OnPrimaryContainer */
+    readonly timeFieldFocusText: "var(--md-sys-color-on-primary-container)";
+    /** Time field focus outline — Primary */
+    readonly timeFieldFocusOutline: "var(--md-sys-color-primary)";
+    /** Time field default text — OnSurface */
+    readonly timeFieldText: "var(--md-sys-color-on-surface)";
+    /** ":" separator — OnSurface */
+    readonly separator: "var(--md-sys-color-on-surface)";
+    /** Headline label ("Select time") — OnSurfaceVariant */
+    readonly headline: "var(--md-sys-color-on-surface-variant)";
+};
+/**
+ * Tailwind utility class strings cho Time Picker elements.
+ * Dùng với `cn()` function.
+ * Map chính xác từ packages/tailwind/src/index.css (--color-m3-* tokens).
+ */
+declare const TP_CLASSES: {
+    /** Main picker/input container */
+    readonly container: "bg-m3-surface-container-high rounded-m3-xl select-none";
+    /** Hour/minute selector button — selected */
+    readonly timeSelectorSelected: "bg-m3-primary-container text-m3-on-primary-container";
+    /** Hour/minute selector button — unselected */
+    readonly timeSelectorUnselected: "bg-m3-surface-container-highest text-m3-on-surface";
+    /** AM/PM button — selected */
+    readonly periodSelected: "bg-m3-primary-container text-m3-on-primary-container";
+    /** AM/PM button — unselected */
+    readonly periodUnselected: "bg-transparent text-m3-on-surface-variant";
+    /** Time input field — default */
+    readonly timeField: "bg-m3-surface-container-highest text-m3-on-surface";
+    /** Time input field — focused */
+    readonly timeFieldFocused: "bg-m3-primary-container text-m3-on-primary-container ring-2 ring-m3-primary";
+    /** Clock dial background circle */
+    readonly clockDial: "fill-[var(--md-sys-color-surface-container-highest)]";
+    /** Selected number on dial */
+    readonly clockDialSelectedText: "fill-[var(--md-sys-color-on-primary)]";
+    /** Unselected number on dial */
+    readonly clockDialUnselectedText: "fill-[var(--md-sys-color-on-surface)]";
+    /** Selector handle, track, center dot */
+    readonly selectorPrimary: "fill-m3-primary stroke-m3-primary";
+};
+/**
+ * Shape tokens — corner radii từ MD3 shape scale.
+ * Map từ ShapeKeyTokens trong TimePickerTokens.kt + TimeInputTokens.kt.
+ *
+ * Sử dụng Tailwind class names từ packages/tailwind/src/index.css.
+ */
+declare const TP_SHAPE: {
+    /** Dialog container — CornerExtraLarge = 28px */
+    readonly container: "rounded-m3-xl";
+    /** Hour/minute selector button — CornerSmall = 8px */
+    readonly timeSelector: "rounded-m3-sm";
+    /** Period (AM/PM) container — CornerSmall = 8px */
+    readonly periodSelector: "rounded-m3-sm";
+    /** Clock dial circle — CornerFull */
+    readonly clockDial: "rounded-m3-full";
+    /** Time field — CornerSmall = 8px */
+    readonly timeField: "rounded-m3-sm";
+};
+/**
+ * Fixed dimension tokens từ TimePickerTokens.kt + TimeInputTokens.kt.
+ * Đơn vị: px (đã convert từ dp).
+ */
+declare const TP_SIZE: {
+    /** ClockDialContainerSize = 256dp */
+    readonly clockDialSize: 256;
+    /** ClockDialSelectorHandleContainerSize = 48dp */
+    readonly selectorHandleSize: 48;
+    /** ClockDialSelectorCenterContainerSize = 8dp */
+    readonly selectorCenterSize: 8;
+    /** ClockDialSelectorTrackContainerWidth = 2dp */
+    readonly selectorTrackWidth: 2;
+    /** TimeSelectorContainerWidth = 96dp */
+    readonly timeSelectorWidth: 96;
+    /** TimeSelectorContainerHeight = 80dp */
+    readonly timeSelectorHeight: 80;
+    /** TimeSelector24HVerticalContainerWidth = 114dp (24h mode) */
+    readonly timeSelector24hWidth: 114;
+    /** PeriodSelectorVerticalContainerWidth = 52dp */
+    readonly periodSelectorVerticalWidth: 52;
+    /** PeriodSelectorVerticalContainerHeight = 80dp */
+    readonly periodSelectorVerticalHeight: 80;
+    /** PeriodSelectorHorizontalContainerWidth = 216dp */
+    readonly periodSelectorHorizWidth: 216;
+    /** PeriodSelectorHorizontalContainerHeight = 38dp */
+    readonly periodSelectorHorizHeight: 38;
+    /** TimeFieldContainerWidth = 96dp */
+    readonly timeFieldWidth: 96;
+    /** TimeFieldContainerHeight = 72dp */
+    readonly timeFieldHeight: 72;
+    /** PeriodSelectorContainerHeight (Input mode) = 72dp */
+    readonly periodInputHeight: 72;
+    /** PeriodSelectorContainerWidth (Input mode) = 52dp */
+    readonly periodInputWidth: 52;
+};
+
+/**
+ * @file time-picker/time-picker-dialog.tsx
+ *
+ * TimePickerDialog — modal container cho TimePicker và TimeInput.
+ * Tái sử dụng Dialog + DialogPortal từ thư viện bug-on/md3-react,
+ * giống pattern của DatePickerDialog.
+ *
+ * Layout:
+ * ```
+ *   ┌─────────────────────┐
+ *   │  [Content]          │  ← TimePicker hoặc TimeInput
+ *   │─────────────────────│
+ *   │ 🎹  [Cancel] [OK]   │  ← footer: modeToggle + spacer + dismiss + confirm
+ *   └─────────────────────┘
+ * ```
+ *
+ * Tokens từ TimePickerDialog.kt (dùng chung với DatePickerDialog):
+ * - ContainerColor = SurfaceContainerHigh
+ * - ContainerShape = CornerExtraLarge (28px)
+ * - ContainerElevation = Level3
+ *
+ * Port từ `TimePickerDialog.kt` và pattern `DatePickerDialog`.
+ *
+ * @see docs/m3/date-and-time-pickers/time-pickers/TimePickerDialog.kt
+ * @see packages/react/src/ui/date-time-pickers/date-picker/date-picker-dialog.tsx
+ */
+
+/**
+ * TimePickerDialog — modal dialog cho TimePicker / TimeInput.
+ *
+ * Tái sử dụng `<Dialog>` (Root) và `<DialogPortal>` (AnimatePresence + Portal)
+ * từ thư viện, đồng thời tự quản lý Overlay và Content để giữ đúng
+ * layout specs MD3 Time Picker.
+ *
+ * @example Basic usage
+ * ```tsx
+ * const state = useTimePickerState({ initialHour: 7 });
+ * const [open, setOpen] = React.useState(false);
+ * const [mode, setMode] = React.useState<'dial' | 'input'>('dial');
+ *
+ * <TimePickerDialog
+ *   open={open}
+ *   onDismiss={() => setOpen(false)}
+ *   modeToggleButton={
+ *     <button onClick={() => setMode(m => m === 'dial' ? 'input' : 'dial')}>
+ *       <span className="md-icon">{mode === 'dial' ? 'keyboard' : 'schedule'}</span>
+ *     </button>
+ *   }
+ *   confirmButton={
+ *     <Button variant="text" onClick={() => { handleConfirm(state); setOpen(false); }}>
+ *       OK
+ *     </Button>
+ *   }
+ *   dismissButton={
+ *     <Button variant="text" onClick={() => setOpen(false)}>Cancel</Button>
+ *   }
+ * >
+ *   {mode === 'dial' ? <TimePicker state={state} /> : <TimeInput state={state} />}
+ * </TimePickerDialog>
+ * ```
+ */
+declare const TimePickerDialog: React.FC<TimePickerDialogProps>;
+
+/**
+ * @file time-picker/use-time-picker-state.ts
+ *
+ * Core state hook cho TimePicker — hoisted state pattern.
+ * Port từ `rememberTimePickerState()` trong Android Compose Material3.
+ *
+ * Tách biệt `hour`/`minute` (luôn valid) và `hourInput`/`minuteInput`
+ * (raw input, có thể invalid mid-typing) — giữ nguyên semantics từ Kotlin.
+ *
+ * @see docs/m3/date-and-time-pickers/time-pickers/TimePickerState.md
+ *
+ * @example
+ * ```tsx
+ * const state = useTimePickerState({
+ *   initialHour: 7,
+ *   initialMinute: 0,
+ *   is24hour: false,
+ * });
+ *
+ * <TimePicker state={state} />
+ * <p>{state.hour}:{String(state.minute).padStart(2, '0')} {state.isPm ? 'PM' : 'AM'}</p>
+ * ```
+ */
+
+/**
+ * Hook quản lý state cho TimePicker và TimeInput.
+ * Tương đương `rememberTimePickerState()` trong Android Compose.
+ *
+ * @param options - Cấu hình ban đầu
+ * @returns `TimePickerState` object với actions
+ */
+declare const useTimePickerState: (options?: UseTimePickerStateOptions) => TimePickerState;
+
+export { DP_CLASSES, DP_COLORS, DP_SHAPE, DP_SIZE, type DateLocale, DatePicker, DatePickerDialog, type DatePickerDialogProps, DatePickerInput, type DatePickerInputProps, type DatePickerProps, type DatePickerState, type DateRange, DateRangePicker, type DateRangePickerProps, type DateRangePickerState, type DisplayMode, type SelectableDates, TP_CLASSES, TP_COLORS, TP_SHAPE, TP_SIZE, TimeInput, type TimeInputProps, TimePicker, TimePickerDialog, type TimePickerDialogProps, type TimePickerLayout, type TimePickerProps, type TimePickerSelectionMode, type TimePickerState, type UseDatePickerStateOptions, type UseDateRangePickerStateOptions, type UseTimePickerStateOptions, useDatePickerState, useDateRangePickerState, useTimePickerState };