@bug-on/m3-expressive 1.0.0 → 1.1.0

package/dist/pickers.d.ts

@@ -3,58 +3,59 @@ 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.
+ * Shared TypeScript base types for Date Pickers and Time Pickers system.
+ * Designed for reuse across both 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
+ * Picker display mode.
+ * - `picker` — calendar/dial UI (default)
+ * - `input`  — text input mode for manual entry
  *
- * Tương đương `DisplayMode` enum trong Android Compose Material3.
+ * Equivalent to `DisplayMode` enum in Android Compose Material3.
  */
 type DisplayMode = "picker" | "input";
 /**
- * Ngày bắt đầu tuần.
+ * First day of the week.
  * - `0` = Sunday (US standard)
- * - `1` = Monday (ISO 8601, mặc định của thư viện này)
+ * - `1` = Monday (ISO 8601, default for this library)
  */
 type WeekStartsOn = 0 | 1;
 /**
- * Cấu hình locale cho Date Picker.
- * Dùng `Intl.DateTimeFormat` native API — zero bundle overhead.
+ * Locale configuration for Date Picker.
+ * Uses native `Intl.DateTimeFormat` API — zero bundle overhead.
  *
  * @example
  * ```tsx
  * const state = useDatePickerState({
- *   locale: { locale: 'vi-VN', weekStartsOn: 1 }
+ *   locale: { locale: 'en-US', weekStartsOn: 1 }
  * });
  * ```
  */
 interface DateLocale {
     /**
      * BCP 47 language tag.
-     * @example 'en-US', 'vi-VN', 'ja-JP'
+     * @example 'en-US', 'fr-FR', 'ja-JP'
      * @default navigator.language (runtime)
      */
     locale?: string;
     /**
-     * Ngày bắt đầu tuần.
+     * First day of the week.
      * @default 1 (Monday)
      */
     weekStartsOn?: WeekStartsOn;
 }
-/** Required version — tất cả fields đã được resolved */
+/** Required version — all fields 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.
+ * Interface for filtering selectable dates and years.
+ * Equivalent to `SelectableDates` interface in Android Compose Material3.
+
  *
  * @example
  * ```tsx
- * // Chặn ngày cuối tuần
+ * // Disable weekends
  * const selectableDates: SelectableDates = {
  *   isSelectableDate(utcMs) {
  *     const day = new Date(utcMs).getUTCDay();
@@ -68,193 +69,193 @@ type ResolvedDateLocale = Required<DateLocale>;
  */
 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
+     * Checks if a date is selectable.
+     * @param utcTimeMs - UTC milliseconds (normalized to UTC midnight)
+     * @returns `true` if date is selectable
      */
     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.
+     * Checks if a year is selectable.
+     * Unselectable years are disabled in year grid view.
      * @param year - Full year (e.g., 2025)
-     * @returns `true` nếu năm có thể chọn
+     * @returns `true` if year is selectable
      */
     isSelectableYear(year: number): boolean;
 }
 /**
- * Khoảng ngày với start và end.
- * Cả hai đều có thể null trong quá trình selection.
+ * Date range with start and end.
+ * Both can be null during selection flow.
  */
 interface DateRange {
-    /** UTC milliseconds của ngày bắt đầu (UTC midnight). Null nếu chưa chọn. */
+    /** Start date UTC milliseconds (UTC midnight). Null if unselected. */
     start: number | null;
-    /** UTC milliseconds của ngày kết thúc (UTC midnight). Null nếu chưa chọn. */
+    /** End date UTC milliseconds (UTC midnight). Null if unselected. */
     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.
+ * TypeScript interfaces and types for Date Picker component system.
+ * Equivalent to DatePickerState + rememberDatePickerState in 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.
+ * State object for DatePicker — hoisted state pattern.
+ * Equivalent to `DatePickerState` class in Android Compose Material3.
  *
  * @example
  * ```tsx
- * const state = useDatePickerState({ locale: { locale: 'vi-VN' } });
+ * const state = useDatePickerState({ locale: { locale: 'en-US' } });
  *
  * <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. */
+    /** UTC ms of currently selected date. Null if unselected. */
     readonly selectedDateMs: number | null;
-    /** UTC ms của ngày 1 của tháng đang hiển thị trong calendar. */
+    /** UTC ms of 1st day of month currently displayed in calendar. */
     readonly displayedMonthMs: number;
-    /** Chế độ hiển thị hiện tại: 'picker' | 'input' */
+    /** Current display mode: 'picker' | 'input' */
     readonly displayMode: DisplayMode;
-    /** Khoảng năm có thể chọn [min, max] */
+    /** Selectable year range [min, max] */
     readonly yearRange: [number, number];
-    /** Locale đã được resolve (với default values) */
+    /** Resolved locale (with 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. */
+    /** Selects a date by UTC ms. Pass null to deselect. */
     selectDate(ms: number | null): void;
-    /** Navigate tháng trước hoặc sau */
+    /** Navigates month backward or forward */
     navigateMonth(direction: "prev" | "next"): void;
-    /** Navigate đến tháng+năm cụ thể */
+    /** Navigates to a specific year and month */
     navigateToMonth(year: number, month: number): void;
-    /** Chuyển đổi giữa 'picker' và 'input' mode */
+    /** Switches display mode between 'picker' and 'input' */
     setDisplayMode(mode: DisplayMode): void;
-    /** Reset về trạng thái ban đầu */
+    /** Resets to initial state */
     reset(): void;
 }
 /**
- * Options cho `useDatePickerState` hook.
- * Tương đương parameters của `rememberDatePickerState()` trong Compose.
+ * Options for `useDatePickerState` hook.
+ * Equivalent to `rememberDatePickerState()` parameters in Compose.
  */
 interface UseDatePickerStateOptions {
     /**
-     * Ngày được chọn ban đầu (UTC ms hoặc null).
+     * Initial selected date (UTC ms or 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
+     * Initial displayed month (UTC ms of any date in target month).
+     * @default current month
      */
     initialDisplayedMonthMs?: number;
     /**
-     * Khoảng năm có thể chọn [min, max].
+     * Selectable year range [min, max].
      * @default [1900, 2100]
      */
     yearRange?: [number, number];
     /**
-     * Filter ngày/năm không thể chọn.
+     * Filter for unselectable dates/years.
      * @default ALL_DATES_SELECTABLE
      */
     selectableDates?: SelectableDates;
     /**
-     * Chế độ hiển thị ban đầu.
+     * Initial display mode.
      * @default 'picker'
      */
     initialDisplayMode?: DisplayMode;
     /**
-     * Locale configuration cho calendar.
+     * Locale configuration for calendar.
      * @default { weekStartsOn: 1 } (Monday)
      */
     locale?: DateLocale;
 }
 /**
- * State object cho DateRangePicker — hoisted state pattern.
- * Tương đương `DateRangePickerState` class trong Android Compose Material3.
+ * State object for DateRangePicker — hoisted state pattern.
+ * Equivalent to `DateRangePickerState` class in Android Compose Material3.
  */
 interface DateRangePickerState {
-    /** UTC ms của ngày bắt đầu. Null nếu chưa chọn. */
+    /** Start date UTC ms. Null if unselected. */
     readonly selectedStartMs: number | null;
-    /** UTC ms của ngày kết thúc. Null nếu chưa chọn. */
+    /** End date UTC ms. Null if unselected. */
     readonly selectedEndMs: number | null;
-    /** UTC ms của ngày 1 của tháng đang hiển thị. */
+    /** UTC ms of 1st day of displayed month. */
     readonly displayedMonthMs: number;
-    /** Chế độ hiển thị: 'picker' | 'input' */
+    /** Display mode: 'picker' | 'input' */
     readonly displayMode: DisplayMode;
-    /** Khoảng năm có thể chọn */
+    /** Selectable year range */
     readonly yearRange: [number, number];
-    /** Locale đã được resolve */
+    /** Resolved locale */
     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.
+     * Selects a date.
+     * Logic: click 1 = set start, click 2 = set end (if ms > start).
+     * If ms <= start or both start and end exist, resets to new start.
      */
     selectDate(ms: number): void;
-    /** Xóa toàn bộ selection */
+    /** Clears entire range selection */
     clearRange(): void;
-    /** Navigate tháng */
+    /** Navigates month */
     navigateMonth(direction: "prev" | "next"): void;
-    /** Navigate đến tháng+năm cụ thể */
+    /** Navigates to a specific year and month */
     navigateToMonth(year: number, month: number): void;
-    /** Chuyển display mode */
+    /** Switches display mode */
     setDisplayMode(mode: DisplayMode): void;
-    /** Reset */
+    /** Resets */
     reset(): void;
 }
-/** Options cho `useDateRangePickerState` */
+/** Options for `useDateRangePickerState` */
 interface UseDateRangePickerStateOptions {
-    /** Start date ban đầu (UTC ms) */
+    /** Initial start date (UTC ms) */
     initialStartMs?: number | null;
-    /** End date ban đầu (UTC ms) */
+    /** Initial end date (UTC ms) */
     initialEndMs?: number | null;
-    /** Tháng hiển thị ban đầu */
+    /** Initial displayed month */
     initialDisplayedMonthMs?: number;
-    /** Khoảng năm @default [1900, 2100] */
+    /** Year range @default [1900, 2100] */
     yearRange?: [number, number];
-    /** Filter ngày không thể chọn */
+    /** Filter unselectable dates */
     selectableDates?: SelectableDates;
-    /** Display mode ban đầu @default 'picker' */
+    /** Initial display mode @default 'picker' */
     initialDisplayMode?: DisplayMode;
     /** Locale config */
     locale?: DateLocale;
 }
-/** Props cho `DatePicker` component */
+/** Props for `DatePicker` component */
 interface DatePickerProps {
-    /** Hoisted state từ `useDatePickerState()` */
+    /** Hoisted state from `useDatePickerState()` */
     state: DatePickerState;
     /**
-     * Hiện nút toggle giữa picker và input mode.
+     * Show toggle button between picker and input mode.
      * @default true
      */
     showModeToggle?: boolean;
     /**
-     * Title slot — hiển thị ở phía trên header.
+     * Title slot — displayed above header.
      * @default "Select date"
      */
     title?: React.ReactNode;
     /**
-     * Headline slot — hiển thị ngày đang chọn.
-     * @default formatted selected date hoặc "--"
+     * Headline slot — displays selected date.
+     * @default formatted selected date or "--"
      */
     headline?: React.ReactNode;
-    /** CSS class bổ sung cho container */
+    /** Additional CSS class for container */
     className?: string;
 }
-/** Props cho `DateRangePicker` component */
+/** Props for `DateRangePicker` component */
 interface DateRangePickerProps {
-    /** Hoisted state từ `useDateRangePickerState()` */
+    /** Hoisted state from `useDateRangePickerState()` */
     state: DateRangePickerState;
     /**
-     * Hiện nút toggle picker/input.
-     * @default false (range picker thường không dùng input mode)
+     * Show toggle button for picker/input mode.
+     * @default false (range pickers typically don't use text input mode)
      */
     showModeToggle?: boolean;
     /**
@@ -262,67 +263,66 @@ interface DateRangePickerProps {
      * @default "Select dates"
      */
     title?: React.ReactNode;
-    /** CSS class bổ sung */
+    /** Additional CSS class */
     className?: string;
 }
-/** Props cho `DatePickerDialog` component */
+/** Props for `DatePickerDialog` component */
 interface DatePickerDialogProps {
-    /** Trạng thái mở/đóng dialog */
+    /** Open/close state of dialog */
     open: boolean;
-    /** Callback khi dialog cần đóng (click scrim, Escape) */
+    /** Callback when dialog requests dismissal (scrim click, Escape) */
     onDismiss: () => void;
-    /** Title cho dialog (dùng cho screen reader và accessibility) */
+    /** Title for dialog (screen reader 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ý.
+     * Confirm button element rendered by caller (e.g. Button "OK").
      */
     confirmButton: React.ReactNode;
     /**
-     * Nút hủy — optional.
+     * Optional cancel/dismiss button element.
      * @default null
      */
     dismissButton?: React.ReactNode;
-    /** Content — thường là `DatePicker` hoặc `DateRangePicker` */
+    /** Content — typically `DatePicker` or `DateRangePicker` */
     children: React.ReactNode;
-    /** CSS class bổ sung cho dialog panel */
+    /** Additional CSS class for dialog panel */
     className?: string;
 }
-/** Props cho `DatePickerInput` component */
+/** Props for `DatePickerInput` component */
 interface DatePickerInputProps {
     /**
-     * Giá trị text hiện tại (format: "MM/DD/YYYY").
+     * Current text value (format: "MM/DD/YYYY").
      */
     value: string;
-    /** Callback khi user thay đổi text */
+    /** Callback when user changes 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ệ.
+     * Callback when user confirms date (blur or Enter).
+     * Passes parsed UTC ms, or null if invalid input.
      */
     onCommit(ms: number | null): void;
-    /** Label cho text field */
+    /** Label for text field */
     label?: string;
-    /** Error message (hiện khi format không hợp lệ) */
+    /** Error message (shown when format is invalid) */
     error?: string;
-    /** Locale string để hint format phù hợp */
+    /** Locale string for format hint */
     locale?: string;
-    /** CSS class bổ sung */
+    /** Additional CSS class */
     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.
+ * DatePicker — calendar UI component (excluding dialog wrapper).
+ * Equivalent to `DatePicker` composable in Android Compose Material3.
  *
  * Layout:
  *   CalendarHeader (title, headline, month nav)
  *   ↓
  *   CalendarGrid | YearPickerGrid (AnimatePresence toggle)
  *   ↓
- *   DatePickerInput (khi displayMode === 'input')
+ *   DatePickerInput (when displayMode === 'input')
  *
  * @see https://m3.material.io/components/date-pickers/overview
  */
@@ -332,12 +332,12 @@ interface DatePickerInputProps {
  *
  * @example
  * ```tsx
- * const state = useDatePickerState({ locale: { locale: 'vi-VN' } });
+ * const state = useDatePickerState({ locale: { locale: 'en-US' } });
  *
  * <DatePicker
  *   state={state}
  *   showModeToggle
- *   title="Chọn ngày"
+ *   title="Select date"
  * />
  * ```
  */
@@ -346,13 +346,13 @@ 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.
+ * MD3 Design tokens for Date Picker component.
+ * Maps from DatePickerModalTokens.kt → CSS variables in 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 */
+/** Color tokens — uses CSS custom properties from MD3 theme */
 declare const DP_COLORS: {
     /** Dialog container — SurfaceContainerHigh */
     readonly container: "var(--md-sys-color-surface-container-high)";
@@ -383,7 +383,7 @@ declare const DP_COLORS: {
     /** Scrim overlay */
     readonly scrim: "var(--md-sys-color-scrim)";
 };
-/** Shape tokens — corner radii từ MD3 shape scale */
+/** Shape tokens — corner radii from MD3 shape scale */
 declare const DP_SHAPE: {
     /** Dialog container — CornerExtraLarge = 28px */
     readonly container: "var(--md-sys-shape-corner-extra-large)";
@@ -394,7 +394,7 @@ declare const DP_SHAPE: {
     /** Year chip — CornerFull */
     readonly year: "var(--md-sys-shape-corner-full)";
 };
-/** Fixed dimension tokens từ DatePickerModalTokens.kt */
+/** Fixed dimension tokens from DatePickerModalTokens.kt */
 declare const DP_SIZE: {
     /** Dialog container width */
     readonly containerWidth: 360;
@@ -414,8 +414,8 @@ declare const DP_SIZE: {
     readonly yearChipWidth: 72;
 };
 /**
- * Tailwind utility class strings cho Date Picker elements.
- * Sử dụng với `cn()` function.
+ * Tailwind utility class strings for Date Picker elements.
+ * Used with `cn()` function.
  */
 declare const DP_CLASSES: {
     /** Dialog container */
@@ -437,10 +437,10 @@ declare const DP_CLASSES: {
 /**
  * @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.
+ * Modal container for Date Pickers — reuses Dialog + DialogPortal primitives.
+ * Equivalent to `DatePickerDialog` composable in Android Compose Material3.
  *
- * Tokens từ DatePickerModalTokens.kt:
+ * Tokens from DatePickerModalTokens.kt:
  * - ContainerColor = SurfaceContainerHigh (#ece6f0)
  * - ContainerShape = CornerExtraLarge (28px)
  * - ContainerElevation = Level3
@@ -450,13 +450,13 @@ declare const DP_CLASSES: {
  */
 
 /**
- * Modal Date Picker dialog với MD3 Expressive spring animations.
+ * Modal Date Picker dialog with 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).
+ * Reuses `<Dialog>` (Root) and `<DialogPortal>` (AnimatePresence + Portal lifecycle)
+ * while managing Overlay and Content to preserve MD3 Date Picker layout specs.
  *
  * @example
+
  * ```tsx
  * const state = useDatePickerState();
  * const [open, setOpen] = React.useState(false);
@@ -482,27 +482,27 @@ 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.
+ * Text input mode for Date Picker — manual entry in MM/DD/YYYY format.
+ * Uses library TextField component.
  *
  * @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.
+ * Text input for Date Picker with MM/DD/YYYY format.
+ * Validates realtime, commits on blur or 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.
+ * DateRangePicker — calendar UI for date range selection.
+ * Equivalent to `DateRangePicker` composable in 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"
+ * Differences from DatePicker:
+ * - Highlights range between start and end (SecondaryContainer)
+ * - Headline displays "Start date → End date"
  * - Default title: "Select dates" (plural)
  *
  * @see https://m3.material.io/components/date-pickers/overview
@@ -526,13 +526,13 @@ 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.
+ * Core state hook for DatePicker — hoisted state pattern.
+ * Equivalent to `rememberDatePickerState()` in Android Compose Material3.
  *
  * @example
  * ```tsx
  * const state = useDatePickerState({
- *   locale: { locale: 'vi-VN', weekStartsOn: 1 },
+ *   locale: { locale: 'en-US', weekStartsOn: 1 },
  *   selectableDates: {
  *     isSelectableDate: (ms) => new Date(ms).getUTCDay() !== 0,
  *     isSelectableYear: (year) => year >= 2020,
@@ -545,24 +545,24 @@ declare const DateRangePicker: React.FC<DateRangePickerProps>;
  */
 
 /**
- * Hook quản lý state cho DatePicker.
+ * Hook for managing state of DatePicker.
  *
- * @param options - Cấu hình ban đầu cho state
- * @returns `DatePickerState` object với các actions
+ * @param options - Initial state configuration
+ * @returns `DatePickerState` object with state and 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.
+ * Core state hook for DateRangePicker — hoisted state pattern.
+ * Equivalent to `rememberDateRangePickerState()` in Android Compose Material3.
  *
- * Logic chọn range:
+ * Range selection logic:
  * - 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
+ * - If both start and end exist: reset, set start = ms
  *
  * @example
  * ```tsx
@@ -574,36 +574,36 @@ declare const useDatePickerState: (options?: UseDatePickerStateOptions) => DateP
  */
 
 /**
- * Hook quản lý state cho DateRangePicker.
+ * Hook for managing state of DateRangePicker.
  *
- * @param options - Cấu hình ban đầu
- * @returns `DateRangePickerState` object với các actions
+ * @param options - Initial configuration
+ * @returns `DateRangePickerState` object with state and 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.
+ * TypeScript interfaces and types for Time Picker component system.
+ * Ported from `TimePickerState` interface in 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.
+ * Indicates which part of time is currently selected — hour or minute.
+ * Equivalent to `TimePickerSelectionMode` enum in 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.
+ * State object for TimePicker — hoisted state pattern.
+ * Equivalent to `TimePickerState` interface in 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).
+ * Separates `hour`/`minute` (always valid) and `hourInput`/`minuteInput`
+ * (raw input, can be invalid mid-typing in TimeInput mode).
  *
  * @example
  * ```tsx
@@ -614,69 +614,69 @@ type TimePickerLayout = "auto" | "vertical" | "horizontal";
  * ```
  */
 interface TimePickerState {
-    /** Giờ hiện tại (0-23). Luôn valid. */
+    /** Current hour (0-23). Always valid. */
     readonly hour: number;
-    /** Phút hiện tại (0-59). Luôn valid. */
+    /** Current minute (0-59). Always 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`.
+     * Raw input for hour — bound to UI element.
+     * Can be invalid during typing (e.g. typing "1" before "2").
+     * Automatically updates `hour` when valid.
      */
     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`.
+     * Raw input for minute — bound to UI element.
+     * Can be invalid during typing.
+     * Automatically updates `minute` when valid.
      */
     readonly minuteInput: number;
-    /** Sử dụng định dạng 24h (`true`) hay 12h AM/PM (`false`). */
+    /** Format: `true` for 24h format, `false` for 12h AM/PM. */
     readonly is24hour: boolean;
-    /** Phần nào đang được chọn (hour hoặc minute). */
+    /** Currently active selection mode ('hour' or 'minute'). */
     readonly selection: TimePickerSelectionMode;
-    /** `true` nếu cả hourInput và minuteInput đều valid. */
+    /** `true` if both hourInput and minuteInput are valid. */
     readonly isInputValid: boolean;
-    /** `true` nếu hourInput là valid hour (0-23 với 24h, 1-12 với 12h). */
+    /** `true` if hourInput is a valid hour (0-23 for 24h, 1-12 for 12h). */
     readonly isHourInputValid: boolean;
-    /** `true` nếu minuteInput là valid minute (0-59). */
+    /** `true` if minuteInput is a valid minute (0-59). */
     readonly isMinuteInputValid: boolean;
-    /** `true` nếu giờ hiện tại là PM (hour >= 12). */
+    /** `true` if current hour is 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.
+     * Sets valid hour (0-23). Also updates hourInput.
+     * Used for 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.
+     * Sets valid minute (0-59). Also updates minuteInput.
+     * Used for 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.
+     * Sets raw hour input (can be invalid).
+     * Used for TimeInput text field.
+     * Only updates `hour` when value is 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.
+     * Sets raw minute input (can be invalid).
+     * Used for TimeInput text field.
+     * Only updates `minute` when value is valid.
      */
     setMinuteInput(m: number): void;
-    /** Đổi selection giữa 'hour' và 'minute'. */
+    /** Switches selection mode between 'hour' and 'minute'. */
     setSelection(mode: TimePickerSelectionMode): void;
     /**
      * Toggle AM/PM.
-     * Tự động convert giờ (vd: 7 AM → 19, 15 PM → 3 AM).
+     * Automatically converts internal hour (e.g. 7 AM → 19, 15 PM → 3 AM).
      */
     setIsPm(pm: boolean): void;
-    /** Reset về trạng thái ban đầu. */
+    /** Resets to initial state. */
     reset(): void;
 }
 /**
- * Options cho `useTimePickerState` hook.
- * Tương đương parameters của `rememberTimePickerState()` trong Compose.
+ * Options for `useTimePickerState` hook.
+ * Equivalent to `rememberTimePickerState()` parameters in Compose.
  *
  * @example
  * ```tsx
@@ -689,27 +689,27 @@ interface TimePickerState {
  */
 interface UseTimePickerStateOptions {
     /**
-     * Giờ ban đầu (0-23).
+     * Initial hour (0-23).
      * @default 0
      */
     initialHour?: number;
     /**
-     * Phút ban đầu (0-59).
+     * Initial minute (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)
+     * Format: 24h format (`true`) or 12h AM/PM (`false`).
+     * @default false (12h format with AM/PM selector)
      */
     is24hour?: boolean;
 }
 /**
- * Props cho `TimePicker` component (dial/clock mode).
- * Tương đương `TimePicker` composable trong Android Compose.
+ * Props for `TimePicker` component (dial/clock mode).
+ * Equivalent to `TimePicker` composable in Android Compose.
  */
 interface TimePickerProps {
-    /** Hoisted state từ `useTimePickerState()`. */
+    /** Hoisted state from `useTimePickerState()`. */
     state: TimePickerState;
     /**
      * Arrangement of the clock header and dial.
@@ -718,58 +718,57 @@ interface TimePickerProps {
      * @default "auto"
      */
     layout?: TimePickerLayout;
-    /** CSS class bổ sung cho container. */
+    /** Additional CSS class for container. */
     className?: string;
 }
 /**
- * Props cho `TimeInput` component (text input mode).
- * Tương đương `TimeInput` composable trong Android Compose.
+ * Props for `TimeInput` component (text input mode).
+ * Equivalent to `TimeInput` composable in Android Compose.
  */
 interface TimeInputProps {
-    /** Hoisted state từ `useTimePickerState()`. */
+    /** Hoisted state from `useTimePickerState()`. */
     state: TimePickerState;
-    /** CSS class bổ sung cho container. */
+    /** Additional CSS class for container. */
     className?: string;
 }
 /**
- * Props cho `TimePickerDialog` component.
- * Tương đương `TimePickerDialog` composable trong Android Compose.
+ * Props for `TimePickerDialog` component.
+ * Equivalent to `TimePickerDialog` composable in Android Compose.
  */
 interface TimePickerDialogProps {
-    /** Trạng thái mở/đóng dialog. */
+    /** Open/close state of the dialog. */
     open: boolean;
-    /** Callback khi dialog cần đóng (click scrim, Escape). */
+    /** Callback when dialog requests dismissal (scrim click, 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ý.
+     * Confirm button element rendered by caller (e.g. Button "OK").
      */
     confirmButton: React.ReactNode;
     /**
-     * Nút hủy — optional.
+     * Optional cancel/dismiss button element.
      * @default null
      */
     dismissButton?: React.ReactNode;
     /**
-     * Nút toggle giữa Dial và Input mode — optional.
-     * Hiển thị ở bottom-left của footer.
+     * Optional mode toggle button between Dial and Input mode.
+     * Positioned at bottom-left of footer.
      */
     modeToggleButton?: React.ReactNode;
     /**
-     * Title hiển thị trên dialog (accessible).
+     * Accessible title displayed on dialog header.
      * @default "Select time"
      */
     title?: string;
-    /** Content — thường là `<TimePicker>` hoặc `<TimeInput>`. */
+    /** Content — typically `<TimePicker>` or `<TimeInput>`. */
     children: React.ReactNode;
-    /** CSS class bổ sung cho dialog panel. */
+    /** Additional CSS class for dialog panel. */
     className?: string;
 }
 
 /**
  * @file time-picker/time-input.tsx
  *
- * TimeInput — text input mode cho time entry.
+ * TimeInput — text input mode for time entry.
  *
  * Layout:
  * ```
@@ -782,12 +781,12 @@ interface TimePickerDialogProps {
  * ```
  *
  * 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)
+ * - Two `<input>` fields for hour and minute
+ * - Auto-advance: entering 2 valid digits automatically focuses next field
+ * - Validation: error state when value is out of range
+ * - AM/PM toggle on right (hidden when is24hour)
  *
- * Port từ `TimeInputImpl` trong TimePicker.kt.
+ * Ported from `TimeInputImpl` in TimePicker.kt.
  *
  * @see docs/m3/date-and-time-pickers/time-pickers/TimePicker.kt (TimeInputImpl)
  */
@@ -795,7 +794,7 @@ interface TimePickerDialogProps {
 /**
  * TimeInput — text input mode.
  *
- * Dùng cùng với `useTimePickerState`:
+ * Used with `useTimePickerState`:
  *
  * @example
  * ```tsx
@@ -828,8 +827,8 @@ declare const TimePicker: React.FC<TimePickerProps>;
 /**
  * @file time-picker/time-picker.tokens.ts
  *
- * MD3 Design tokens cho Time Picker component system.
- * Verified mapping từ:
+ * MD3 Design tokens for Time Picker component system.
+ * Verified mapping from:
  *   - TimePickerTokens.kt → ClockDial, TimeSelector, PeriodSelector (Picker mode)
  *   - TimeInputTokens.kt  → TimeField, PeriodSelector (Input mode)
  *
@@ -840,8 +839,8 @@ declare const TimePicker: React.FC<TimePickerProps>;
  * @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).
+ * Color tokens for Time Picker — mapped from TimePickerTokens.kt + TimeInputTokens.kt.
+ * Uses CSS custom properties from MD3 theme (packages/tokens/src/colors.css).
  */
 declare const TP_COLORS: {
     /** Dial background — SurfaceContainerHighest */
@@ -892,9 +891,9 @@ declare const TP_COLORS: {
     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).
+ * Tailwind utility class strings for Time Picker elements.
+ * Used with `cn()` function.
+ * Mapped from packages/tailwind/src/index.css (--color-m3-* tokens).
  */
 declare const TP_CLASSES: {
     /** Main picker/input container */
@@ -921,10 +920,10 @@ declare const TP_CLASSES: {
     readonly selectorPrimary: "fill-m3-primary stroke-m3-primary";
 };
 /**
- * Shape tokens — corner radii từ MD3 shape scale.
- * Map từ ShapeKeyTokens trong TimePickerTokens.kt + TimeInputTokens.kt.
+ * Shape tokens — corner radii from MD3 shape scale.
+ * Mapped from ShapeKeyTokens in TimePickerTokens.kt + TimeInputTokens.kt.
  *
- * Sử dụng Tailwind class names từ packages/tailwind/src/index.css.
+ * Uses Tailwind class names from packages/tailwind/src/index.css.
  */
 declare const TP_SHAPE: {
     /** Dialog container — CornerExtraLarge = 28px */
@@ -939,8 +938,8 @@ declare const TP_SHAPE: {
     readonly timeField: "rounded-m3-sm";
 };
 /**
- * Fixed dimension tokens từ TimePickerTokens.kt + TimeInputTokens.kt.
- * Đơn vị: px (đã convert từ dp).
+ * Fixed dimension tokens from TimePickerTokens.kt + TimeInputTokens.kt.
+ * Unit: px (converted from dp).
  */
 declare const TP_SIZE: {
     /** ClockDialContainerSize = 256dp */
@@ -978,38 +977,37 @@ declare const TP_SIZE: {
 /**
  * @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.
+ * TimePickerDialog — modal container for TimePicker and TimeInput.
+ * Reuses Dialog + DialogPortal primitives matching DatePickerDialog pattern.
  *
  * Layout:
  * ```
  *   ┌─────────────────────┐
- *   │  [Content]          │  ← TimePicker hoặc TimeInput
+ *   │  [Content]          │  ← TimePicker or TimeInput
  *   │─────────────────────│
  *   │ 🎹  [Cancel] [OK]   │  ← footer: modeToggle + spacer + dismiss + confirm
  *   └─────────────────────┘
  * ```
  *
- * Tokens từ TimePickerDialog.kt (dùng chung với DatePickerDialog):
+ * Tokens from TimePickerDialog.kt (shared with DatePickerDialog):
  * - ContainerColor = SurfaceContainerHigh
  * - ContainerShape = CornerExtraLarge (28px)
  * - ContainerElevation = Level3
  *
- * Port từ `TimePickerDialog.kt` và pattern `DatePickerDialog`.
+ * Ported from `TimePickerDialog.kt` and `DatePickerDialog` pattern.
  *
  * @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.
+ * TimePickerDialog — modal dialog container for 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.
+ * Reuses `<Dialog>` (Root) and `<DialogPortal>` (AnimatePresence + Portal)
+ * while managing Overlay and Content to preserve MD3 Time Picker specs.
  *
  * @example Basic usage
+
  * ```tsx
  * const state = useTimePickerState({ initialHour: 7 });
  * const [open, setOpen] = React.useState(false);
@@ -1041,11 +1039,11 @@ 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.
+ * Core state hook for TimePicker — hoisted state pattern.
+ * Ported from `rememberTimePickerState()` in 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.
+ * Separates `hour`/`minute` (always valid) and `hourInput`/`minuteInput`
+ * (raw input, can be invalid mid-typing) — preserving Kotlin semantics.
  *
  * @see docs/m3/date-and-time-pickers/time-pickers/TimePickerState.md
  *
@@ -1063,11 +1061,11 @@ declare const TimePickerDialog: React.FC<TimePickerDialogProps>;
  */
 
 /**
- * Hook quản lý state cho TimePicker và TimeInput.
- * Tương đương `rememberTimePickerState()` trong Android Compose.
+ * State management hook for TimePicker and TimeInput.
+ * Equivalent to `rememberTimePickerState()` in Android Compose.
  *
- * @param options - Cấu hình ban đầu
- * @returns `TimePickerState` object với actions
+ * @param options - Initial configuration options
+ * @returns `TimePickerState` object with state and actions
  */
 declare const useTimePickerState: (options?: UseTimePickerStateOptions) => TimePickerState;