timepicker-ui 3.2.0 → 4.0.1

package/dist/index.d.ts

@@ -1,92 +1,97 @@
-/**
- * @description Callback data type for timepicker events
- */
-type CallbackData = {
-  hour?: string | null;
-  minutes?: string | null;
-  type?: string | null;
-  degreesHours?: number | null;
-  degreesMinutes?: number | null;
-  hourNotAccepted?: string | null;
-  minutesNotAccepted?: string | null;
-  eventType?: 'accept' | 'cancel' | 'click' | 'change' | null;
-  error?: string;
-  currentHour?: string | number;
-  currentMin?: string | number;
-  currentType?: string;
-  currentLength?: string | number;
+/** Payload when timepicker opens */
+type OpenEventData = {
+  hour: string;
+  minutes: string;
+  type?: string;
+  degreesHours: number | null;
+  degreesMinutes: number | null;
 };
 
-/**
- * @description Callback function type for timepicker events
- */
-type TimepickerEventCallback = (eventData: CallbackData) => void;
+/** Payload when user cancels */
+type CancelEventData = Record<string, never>;
+
+/** Payload when user confirms time */
+type ConfirmEventData = {
+  hour?: string;
+  minutes?: string;
+  type?: string;
+};
+
+/** Payload when modal shows */
+type ShowEventData = Record<string, never>;
+
+/** Payload when modal hides */
+type HideEventData = Record<string, never>;
+
+/** Payload for real-time updates */
+type UpdateEventData = {
+  hour: string;
+  minutes: string;
+  type?: string;
+};
+
+/** Payload when hour mode activated */
+type SelectHourEventData = {
+  hour: string;
+};
+
+/** Payload when minute mode activated */
+type SelectMinuteEventData = {
+  minutes: string;
+};
+
+/** Payload when AM selected */
+type SelectAMEventData = Record<string, never>;
+
+/** Payload when PM selected */
+type SelectPMEventData = Record<string, never>;
+
+/** Payload when switching view */
+type SwitchViewEventData = Record<string, never>;
+
+/** Payload when validation error occurs */
+type ErrorEventData = {
+  error: string;
+  rejectedHour?: string;
+  rejectedMinute?: string;
+  inputHour?: string | number;
+  inputMinute?: string | number;
+  inputType?: string;
+  inputLength?: string | number;
+};
+
+/** Callback function for timepicker events */
+type TimepickerEventCallback<T = unknown> = (eventData: T) => void;
 
 type OptionTypes = {
-  /**
-   * @description Set custom text to AM label
-   * @default "AM"
-   */
+  /** AM label text @default "AM" */
   amLabel?: string;
-  /**
-   * @description Turn on/off animations on picker on start/close
-   * @default true
-   */
+  /** Enable animations @default true */
   animation?: boolean;
   /**
    * @description Set default selector to append timepicker inside it. Timepicker default append to `body`
    * @default ""
    */
   appendModalSelector?: string;
-  /**
-   * @description Turn on/off backdrop
-   * @default true
-   */
+  /** Enable backdrop @default true */
   backdrop?: boolean;
-  /**
-   * @description Set custom text to cancel button
-   * @default "Cancel"
-   */
+  /** Cancel button text @default "Cancel" */
   cancelLabel?: string;
-  /**
-   * @description Edit hour/minutes on the web mode.
-   * @default false
-   */
+  /** Edit hour/minutes in web mode @default false */
   editable?: boolean;
-  /**
-   * @description Turn on/off scroll if timepicker is open
-   * @default false
-   */
+  /** Enable scroll when open @default false */
   enableScrollbar?: boolean;
-  /**
-   * @description Turn on/off icon to switch desktop/mobile
-   * @default false
-   */
+  /** Icon to switch desktop/mobile @default false */
   enableSwitchIcon?: boolean;
-  /**
-   * @description Set custom text to time label on mobile version
-   * @default "Enter Time"
-   */
+  /** Mobile time label @default "Enter Time" */
   mobileTimeLabel?: string;
-  /**
-   * @description Turn on/off focus to input after close modal
-   * @default false
-   */
+  /** Focus input after close @default false */
   focusInputAfterCloseModal?: boolean;
-  /**
-   * @description Set custom text to hour label on mobile version
-   * @default "Hour"
-   */
+  /** Mobile hour label @default "Hour" */
   hourMobileLabel?: string;
-  /**
-   * @description Set default template to switch desktop.This options is using by default material design icon
-   * @default "<i class='material-icons timepicker-ui-keyboard-icon'> keyboard </i>"
-   */
+  /** Desktop icon template */
   iconTemplate?: string;
-  /**
-   * @description Set default template to switch mobile. This options is using by default material design icon
-   * @default "<i class='material-icons timepicker-ui-keyboard-icon'> schedule </i>"
-   */
+  /** Mobile icon template */
   iconTemplateMobile?: string;
   /**
    * @description Set increment hour by `1`, `2`, `3` hour
@@ -113,30 +118,13 @@ type OptionTypes = {
    * @default "OK"
    */
   okLabel?: string;
-  /**
-   * @description Set custom text to pm label
-   * @default "PM"
-   */
+  /** PM label @default "PM" */
   pmLabel?: string;
-  /**
-   * @description Set custom text to time label on desktop version
-   * @default "Select time"
-   */
+  /** Time label (desktop) @default "Select time" */
   timeLabel?: string;
-  /**
-   * @description Turn on/off switch to minutes by select hour
-   * @default true
-   */
+  /** Auto-switch to minutes @default true */
   autoSwitchToMinutes?: boolean;
-  /**
-   * @description Set theme to timepicker. Available options: `basic`, `crane`, `crane-straight`, `m3-green`, `m2`, `dark`, `glassmorphic`, `pastel`, `ai`, `cyberpunk`, `custom`.
-   *
-   * The `custom` theme allows you to create your own styling by overriding CSS variables.
-   * The offical version of Material Design 3 is still not avaialbe for the WEB version.Theme `m3` has been added
-   * based on the design what you can find [here](https://m3.material.io/components/time-pickers/overview).
-   * If new version M3 will be released this design will get improve.
-   * @default "basic"
-   */
+  /** Theme @default "basic" */
   theme?:
     | 'basic'
     | 'crane'
@@ -147,91 +135,245 @@ type OptionTypes = {
     | 'glassmorphic'
     | 'pastel'
     | 'ai'
-    | 'cyberpunk'
-    | 'custom';
+    | 'cyberpunk';
+  /** Clock type: 12h or 24h @default "12h" */
+  clockType?: '12h' | '24h';
+  /** Disable specific times (hours/minutes/intervals) */
+  disabledTime?: {
+    minutes?: Array<string | number>;
+    hours?: Array<string | number>;
+    interval?: string | string[];
+  };
+  /** Current time config */
+  /** Current time config */
+  currentTime?:
+    | {
+        time?: Date;
+        updateInput?: boolean;
+        locales?: string | string[];
+        preventClockType?: boolean;
+      }
+    | boolean;
+
+  /** Focus trap on modal @default true */
+  focusTrap?: boolean;
+  /** Delay for clickable elements (ms) @default 300 */
+  delayHandler?: number;
+  /** Custom ID for instance */
+  id?: string;
+  /** Inline mode config */
+  inline?: {
+    enabled: boolean;
+    containerId: string;
+    /** @default false */
+    showButtons?: boolean;
+    /** @default true */
+    autoUpdate?: boolean;
+  };
+  /** Additional CSS class */
+  cssClass?: string;
+  /** Callback when picker opens */
+  onOpen?: TimepickerEventCallback<OpenEventData>;
+  /** Callback when user cancels */
+  onCancel?: TimepickerEventCallback<CancelEventData>;
+  /** Callback when user confirms */
+  onConfirm?: TimepickerEventCallback<ConfirmEventData>;
+  /** Callback during interaction */
+  onUpdate?: TimepickerEventCallback<UpdateEventData>;
+  /** Callback when hour mode activated */
+  onSelectHour?: TimepickerEventCallback<SelectHourEventData>;
+  /** Callback when minute mode activated */
+  onSelectMinute?: TimepickerEventCallback<SelectMinuteEventData>;
+  /** Callback when AM selected */
+  onSelectAM?: TimepickerEventCallback<SelectAMEventData>;
+  /** Callback when PM selected */
+  onSelectPM?: TimepickerEventCallback<SelectPMEventData>;
+  /** Callback on validation error */
+  onError?: TimepickerEventCallback<ErrorEventData>;
+};
+
+type EventHandler<T = unknown> = (data: T) => void;
+interface TimepickerEventMap {
+    open: OpenEventData;
+    cancel: CancelEventData;
+    confirm: ConfirmEventData;
+    show: ShowEventData;
+    hide: HideEventData;
+    update: UpdateEventData;
+    'select:hour': SelectHourEventData;
+    'select:minute': SelectMinuteEventData;
+    'select:am': SelectAMEventData;
+    'select:pm': SelectPMEventData;
+    'switch:view': SwitchViewEventData;
+    'animation:clock': Record<string, never>;
+    error: ErrorEventData;
+    [key: string]: unknown;
+}
+declare class EventEmitter<EventMap extends Record<string, unknown> = TimepickerEventMap> {
+    private events;
+    on<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): void;
+    once<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): void;
+    off<K extends keyof EventMap>(event: K, handler?: EventHandler<EventMap[K]>): void;
+    emit<K extends keyof EventMap>(event: K, data?: EventMap[K]): void;
+    clear(): void;
+    hasListeners<K extends keyof EventMap>(event: K): boolean;
+}
+
+/**
+ * Grouped options structure for Timepicker UI v4.0.0
+ *
+ * BREAKING CHANGE from v3.x:
+ * Options are now organized into logical groups for better clarity and maintainability.
+ */
+
+
+
+/**
+ * Clock behavior configuration
+ */
+interface ClockOptions {
   /**
-   * @description Set type of clock, it contains 2 versions: `12h` and `24h`.
+   * @description Set type of clock: `12h` or `24h`
+   * @default "12h"
+   */
+  type?: '12h' | '24h';
+
+  /**
+   * @description Set increment for hours (1, 2, 3, etc.)
+   * @default 1
+   */
+  incrementHours?: number;
+
+  /**
+   * @description Set increment for minutes (1, 5, 10, 15, etc.)
+   * @default 1
+   */
+  incrementMinutes?: number;
+
+  /**
+   * @description Automatically switch to minutes after selecting hour
    * @default false
    */
-  clockType?: '12h' | '24h';
+  autoSwitchToMinutes?: boolean;
+
   /**
-   * @description - The `hours` and `minutes` are arrays which accept strings and numbers to block select hours/minutes.
-   * - The `interval` key can accept string or string[] to block select time intervals.
-   * - If the interval key is set, the hours/minutes keys are `ignored`.
+   * @description Disable specific hours/minutes or time intervals
    * @example
-    disabledTime: {
-      minutes: [1,2,4,5,55,23,"22","38"],
-      hours: [1,"3","5", 8],
-      interval: "10:00 AM - 12:00 PM" | ["10:00 AM - 12:00 PM", "5:00 PM - 8:00 PM"],
-    }
-   * @default  undefined
+   * disabledTime: {
+   *   minutes: [1, 2, 4, 5, 55, 23, "22", "38"],
+   *   hours: [1, "3", "5", 8],
+   *   interval: "10:00 AM - 12:00 PM" | ["10:00 AM - 12:00 PM", "5:00 PM - 8:00 PM"]
+   * }
    */
   disabledTime?: {
     minutes?: Array<string | number>;
     hours?: Array<string | number>;
     interval?: string | string[];
   };
+
   /**
-   * @description Set current time to the input and timepicker.\
-   * If this options is set to `true` it's gonna update picker with toLocaleTimeString() and input with value based on your location.
-   * This option also allows to put object with properties.
+   * @description Set current time to the input and timepicker
    * @example
-      currentTime: {
-        time: new Date(),
-        updateInput: true,
-        locales: "en-US",
-        preventClockType: false
-      };
+   * currentTime: {
+   *   time: new Date(),
+   *   updateInput: true,
+   *   locales: "en-US",
+   *   preventClockType: false
+   * }
    * @example currentTime: true
-   * @default  undefined
    */
   currentTime?:
     | {
-        /**
-         * The `time` key allows to put any valid date to update picker.
-         * @requires
-         * If the `updateInput` is set to `false/undefined` and the default value from the input not exist, the `time` key value will be displayed in the picker.
-         *
-         * If the `updateInput` is set to `false/undefined` but the default value from the input exist, the `time` key will be ignored.
-         */
         time?: Date;
-        /**
-         * The `updateInput` key is set to `true` it's going update input value with set time key.
-         */
         updateInput?: boolean;
-        /**
-         * The `locales` key can change language from `toLocaleTimeString()`.
-         */
         locales?: string | string[];
-        /**
-         * The `preventClockType` key if is set to `true` it's `force` the clockType option to set value "12h" or "24h" based on your location
-         * with current time and `locales` key value is ignored.
-         */
         preventClockType?: boolean;
       }
     | boolean;
+}
+
+/**
+ * UI appearance and behavior configuration
+ */
+interface UIOptions {
+  /**
+   * @description Theme for the timepicker
+   * @default "basic"
+   */
+  theme?:
+    | 'basic'
+    | 'crane'
+    | 'crane-straight'
+    | 'm2'
+    | 'm3-green'
+    | 'dark'
+    | 'glassmorphic'
+    | 'pastel'
+    | 'ai'
+    | 'cyberpunk';
 
   /**
-   * @description Set focus trap to the modal element to all elements with tabindex in the picker
+   * @description Enable/disable animations
    * @default true
    */
-  focusTrap?: boolean;
+  animation?: boolean;
+
   /**
-   * @description Set delay to clickable elements like button "OK", "Cancel" etc. The value has to be set in milliseconds.
-   * @default 300
+   * @description Show backdrop when timepicker is open
+   * @default true
    */
-  delayHandler?: number;
+  backdrop?: boolean;
+
   /**
-   * @description Custom ID for the timepicker instance. Useful for identifying specific instances when using multiple timepickers.
-   * If not provided, a random UUID will be generated.
-   * @example id: "my-timepicker-1"
-   * @default undefined
+   * @description Force mobile mode
+   * @default false
    */
-  id?: string;
+  mobile?: boolean;
+
+  /**
+   * @description Enable switch icon (mobile ↔ desktop)
+   * @default false
+   */
+  enableSwitchIcon?: boolean;
+
+  /**
+   * @description Allow editing hour/minutes directly
+   * @default false
+   */
+  editable?: boolean;
+
+  /**
+   * @description Enable scrollbar when timepicker is open
+   * @default false
+   */
+  enableScrollbar?: boolean;
+
   /**
-   * @description Enable inline mode for always-visible timepicker
-   * If enabled is true, containerId must be provided and the timepicker will be rendered inside the specified container instead of as a modal.
-   * The timepicker will not open on input click and will be always visible.
+   * @description Additional CSS class for the wrapper
+   * @example cssClass: "my-custom-timepicker"
+   */
+  cssClass?: string;
+
+  /**
+   * @description Selector where to append modal (default: body)
+   * @default ""
+   */
+  appendModalSelector?: string;
+
+  /**
+   * @description Custom keyboard icon template (desktop → mobile)
+   * @default Material Icons template
+   */
+  iconTemplate?: string;
+
+  /**
+   * @description Custom schedule icon template (mobile → desktop)
+   * @default Material Icons template
+   */
+  iconTemplateMobile?: string;
+
+  /**
+   * @description Inline mode configuration
    * @example
    * inline: {
    *   enabled: true,
@@ -239,481 +381,178 @@ type OptionTypes = {
    *   showButtons: false,
    *   autoUpdate: true
    * }
-   * @default undefined
    */
   inline?: {
-    /**
-     * @description Enable or disable inline mode
-     */
     enabled: boolean;
-    /**
-     * @description ID of the container element where the timepicker should be rendered (required when enabled is true)
-     */
     containerId: string;
-    /**
-     * @description Show or hide OK/Cancel buttons in inline mode
-     * @default false
-     */
     showButtons?: boolean;
-    /**
-     * @description Automatically update input value when time changes (real-time updates)
-     * @default true
-     */
     autoUpdate?: boolean;
   };
+}
+
+/**
+ * Text labels configuration
+ */
+interface LabelsOptions {
   /**
-   * @description Add additional custom CSS class to the timepicker wrapper element. The default 'timepicker-ui' class is always added.
-   * This allows multiple timepickers on the same page to have additional custom classes for styling or targeting.
-   * @example cssClass: "my-custom-timepicker"
-   * @default undefined
+   * @description "AM" label text
+   * @default "AM"
    */
-  cssClass?: string;
+  am?: string;
+
   /**
-   * @description Callback triggered when the timepicker opens
-   * @example onOpen: (data) => console.log('Picker opened!', data)
+   * @description "PM" label text
+   * @default "PM"
    */
-  onOpen?: TimepickerEventCallback;
+  pm?: string;
+
   /**
-   * @description Callback triggered when user cancels the timepicker
-   * @example onCancel: (data) => console.log('Cancelled', data)
+   * @description "OK" button text
+   * @default "OK"
    */
-  onCancel?: TimepickerEventCallback;
+  ok?: string;
+
   /**
-   * @description Callback triggered when user confirms the time selection (clicks OK)
-   * @example onConfirm: (data) => console.log('Time confirmed', data)
+   * @description "Cancel" button text
+   * @default "Cancel"
    */
-  onConfirm?: TimepickerEventCallback;
+  cancel?: string;
+
   /**
-   * @description Callback triggered during interaction with the clock (real-time updates)
-   * @example onUpdate: (data) => console.log('Time updated', data)
+   * @description Time label on desktop
+   * @default "Select time"
    */
-  onUpdate?: TimepickerEventCallback;
+  time?: string;
+
   /**
-   * @description Callback triggered when hour selection mode is activated
-   * @example onSelectHour: (data) => console.log('Hour mode selected', data)
+   * @description Time label on mobile
+   * @default "Enter Time"
    */
-  onSelectHour?: TimepickerEventCallback;
+  mobileTime?: string;
+
   /**
-   * @description Callback triggered when minute selection mode is activated
-   * @example onSelectMinute: (data) => console.log('Minute mode selected', data)
+   * @description Hour label on mobile
+   * @default "Hour"
    */
-  onSelectMinute?: TimepickerEventCallback;
+  mobileHour?: string;
+
   /**
-   * @description Callback triggered when AM is selected
-   * @example onSelectAM: (data) => console.log('AM selected', data)
+   * @description Minute label on mobile
+   * @default "Minute"
    */
-  onSelectAM?: TimepickerEventCallback;
+  mobileMinute?: string;
+}
+
+/**
+ * Behavior configuration
+ */
+interface BehaviorOptions {
   /**
-   * @description Callback triggered when PM is selected
-   * @example onSelectPM: (data) => console.log('PM selected', data)
+   * @description Focus input after closing modal
+   * @default false
    */
-  onSelectPM?: TimepickerEventCallback;
+  focusInputAfterClose?: boolean;
+
   /**
-   * @description Callback triggered when invalid time format is detected in input
-   * @example onError: (data) => console.log('Invalid format:', data.error)
+   * @description Enable focus trap in modal
+   * @default true
    */
-  onError?: TimepickerEventCallback;
-};
-
-declare class DOMUpdateBatcher {
-    private updates;
-    private rafId;
-    schedule(update: () => void): void;
-    private flush;
-    destroy(): void;
-}
-
-type InputValueResult = {
-    hour: string;
-    minutes: string;
-    type?: string;
-    error?: string;
-    currentHour?: string | number;
-    currentMin?: string | number;
-    currentType?: string;
-    currentLength?: number;
-};
-
-declare class ConfigManager {
-    private timepicker;
-    private debouncedHandler?;
-    private timeoutManager;
-    private viewSwitcher;
-    private mobileToggler;
-    private initManager;
-    constructor(timepicker: ITimepickerUI);
-    preventClockTypeByCurrentTime: () => void;
-    updateInputValueWithCurrentTimeOnStart: () => void;
-    checkMobileOption(): void;
-    getDisableTime(): void;
-    getInputValueOnOpenAndSet: () => void;
-    toggleMobileClockFace: () => void;
-    getInputValue: (el: HTMLInputElement, clockType?: string, currentTime?: OptionTypes["currentTime"], updateOptions?: boolean) => InputValueResult;
-    destroy(): void;
-}
-
-declare class ThemeManager {
-    private timepicker;
-    constructor(timepicker: ITimepickerUI);
-    /** @internal */
-    setTheme: () => void;
-    /** @internal */
-    setInputClassToInputElement: () => void;
-    /** @internal */
-    setDataOpenToInputIfDoesntExistInWrapper: () => void;
-    /** @internal */
-    setClassTopOpenElement: () => void;
-    /** @internal */
-    setTimepickerClassToElement: () => void;
-    destroy(): void;
-}
-
-declare class ValidationManager {
-    private timepicker;
-    constructor(timepicker: ITimepickerUI);
-    /** @internal */
-    setErrorHandler(): boolean | undefined;
-    /** @internal */
-    removeErrorHandler(): void;
-    /** @internal */
-    checkDisabledValuesOnStart(): void;
-    destroy(): void;
-}
-
-declare class ClockManager {
-    private timepicker;
-    private clockSystem;
-    constructor(timepicker: ITimepickerUI);
-    initializeClockSystem(): void;
-    private convertDisabledTime;
-    private getAmPmValue;
-    destroyClockSystem(): void;
-    removeCircleClockClasses24h(): void;
-    setCircleClockClasses24h(): void;
-    setOnStartCSSClassesIfClockType24h(): void;
-    setBgColorToCircleWithMinutesTips: () => void;
-    removeBgColorToCirleWithMinutesTips: () => void;
-    setClassActiveToHourOnOpen: () => void;
-    setMinutesToClock: (value: string | null) => void;
-    setHoursToClock: (value: string | null) => void;
-    setTransformToCircleWithSwitchesHour: (val: string | null) => void;
-    setTransformToCircleWithSwitchesMinutes: (val: string | null) => void;
-    updateAmPm: () => void;
-    toggleClassActiveToValueTips: (value: string | number | null) => void;
-}
-
-declare class AnimationManager {
-    private timepicker;
-    private timeouts;
-    constructor(timepicker: ITimepickerUI);
-    private runWithAnimation;
-    private clearAllTimeouts;
-    /** @internal */
-    setAnimationToOpen(): void;
-    /** @internal */
-    removeAnimationToClose(): void;
-    /** @internal */
-    handleAnimationClock(): void;
-    /** @internal */
-    handleAnimationSwitchTipsMode(): void;
-    /** @internal */
-    destroy(): void;
-}
-
-declare class ModalManager {
-    private timepicker;
-    private timeouts;
-    private originalOverflow?;
-    private originalPaddingRight?;
-    constructor(timepicker: ITimepickerUI);
-    private runWithTimeout;
-    private clearAllTimeouts;
-    private clearExistingModal;
-    /** @internal */
-    setModalTemplate: () => void;
-    /** @internal */
-    setScrollbarOrNot: () => void;
-    /** @internal */
-    removeBackdrop: () => void;
-    /** @internal */
-    setNormalizeClass: () => void;
-    /** @internal */
-    setShowClassToBackdrop: () => void;
-    /** @internal */
-    setFlexEndToFooterIfNoKeyboardIcon: () => void;
-    destroy(): void;
-}
-
-declare class EventManager {
-    private _cleanupHandlers;
-    private buttonHandlers;
-    private typeModeHandlers;
-    private inputHandlers;
-    private miscHandlers;
-    private inlineHandlers;
-    constructor(timepicker: ITimepickerUI);
-    destroy(): void;
-    handleOpenOnClick: () => void;
-    handleOpenOnEnterFocus: () => void;
-    handleCancelButton: () => void;
-    handleOkButton: () => void;
-    handleBackdropClick: () => void;
-    handleAmClick: () => void;
-    handlePmClick: () => void;
-    handleHourEvents: () => void;
-    handleMinutesEvents: () => void;
-    handleClickOnHourMobile: () => void;
-    handlerClickHourMinutes: (event: Event) => Promise<void>;
-    handleIconChangeView: () => Promise<void>;
-    handleEscClick: () => void;
-    focusTrapHandler: () => void;
-    handleInlineAutoUpdate: () => void;
-    handleMoveHand: () => void;
-    handleEventToMoveHand: (event: TouchEvent) => void;
-    get _isDragging(): boolean;
-    get _animationFrameId(): number | null;
-    _onDragStart: (event: MouseEvent | TouchEvent) => void;
-    _onDragMove: (event: MouseEvent | TouchEvent) => void;
-    _onDragEnd: (event: MouseEvent | TouchEvent) => void;
-}
-
-type EventHandler<T = CallbackData> = (data: T) => void;
-interface TimepickerEventMap {
-    open: CallbackData;
-    cancel: CallbackData;
-    confirm: CallbackData;
-    show: CallbackData;
-    hide: CallbackData;
-    update: CallbackData;
-    'select:hour': CallbackData;
-    'select:minute': CallbackData;
-    'select:am': CallbackData;
-    'select:pm': CallbackData;
-    error: CallbackData;
-}
-declare class EventEmitter<EventMap extends Record<string, any> = TimepickerEventMap> {
-    private events;
-    on<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): void;
-    once<K extends keyof EventMap>(event: K, handler: EventHandler<EventMap[K]>): void;
-    off<K extends keyof EventMap>(event: K, handler?: EventHandler<EventMap[K]>): void;
-    emit<K extends keyof EventMap>(event: K, data?: EventMap[K]): void;
-    clear(): void;
-    hasListeners<K extends keyof EventMap>(event: K): boolean;
-}
-
-interface ITimepickerUI {
-  _degreesHours: number | null;
-  _degreesMinutes: number | null;
-  _eventsBundle: () => void;
-  _options: OptionTypes;
-  _eventsClickMobile: (event: Event) => Promise<void>;
-  _eventsClickMobileHandler: EventListenerOrEventListenerObject;
-  _mutliEventsMove: (event: Event) => void;
-  _mutliEventsMoveHandler: EventListenerOrEventListenerObject;
-  _clickTouchEvents: string[];
-  _element: HTMLElement;
-  _instanceId: string;
-  _isMobileView: boolean | null;
-  _isTouchMouseMove: boolean | null;
-  _disabledTime: {
-    value?: {
-      isInterval?: boolean;
-      intervals?: string[];
-      clockType?: string;
-      hours?: string[];
-      minutes?: string[];
-    };
-  } | null;
-  _cloned: Node | null;
-  _inputEvents: string[];
-  _isModalRemove?: boolean;
-  _isInitialized: boolean;
-  _customId?: string;
-
-  readonly modalTemplate: string;
-  readonly modalElement: HTMLDivElement;
-  readonly clockFace: HTMLDivElement;
-  readonly input: HTMLInputElement;
-  readonly clockHand: HTMLDivElement;
-  readonly circle: HTMLDivElement;
-  readonly tipsWrapper: HTMLDivElement;
-  readonly tipsWrapperFor24h: HTMLDivElement;
-  readonly minutes: HTMLInputElement;
-  readonly hour: HTMLInputElement;
-  readonly AM: HTMLDivElement;
-  readonly PM: HTMLDivElement;
-  readonly hourText: HTMLDivElement;
-  readonly minutesText: HTMLDivElement;
-  readonly inputWrappers: NodeListOf<Element>;
-  readonly dots: HTMLDivElement;
-  readonly header: HTMLDivElement;
-  readonly minutesTips: HTMLDivElement;
-  readonly hourTips: HTMLDivElement;
-  readonly allValueTips: readonly HTMLDivElement[];
-  readonly openElementData: string[] | null;
-  readonly openElement: NodeListOf<Element> | readonly [HTMLInputElement];
-  readonly cancelButton: HTMLButtonElement;
-  readonly okButton: HTMLButtonElement;
-  readonly activeTypeMode: HTMLButtonElement;
-  readonly keyboardClockIcon: HTMLButtonElement;
-  readonly footer: HTMLDivElement;
-  readonly wrapper: HTMLDivElement;
-
-  create(): void;
-  open(callback?: () => void): void;
-  close(): (...args: (boolean | (() => void))[]) => void;
-  destroy(options?: { keepInputValue?: boolean; callback?: () => void } | (() => void)): void;
-  update(value: { options: OptionTypes; create?: boolean }, callback?: () => void): void;
-  getElement(): HTMLElement;
-  getValue(): {
-    hour: string;
-    minutes: string;
-    type?: string;
-    time: string;
-    degreesHours: number | null;
-    degreesMinutes: number | null;
-  };
-  setValue(time: string, updateInput?: boolean): void;
-  setTheme(themeConfig: {
-    primaryColor?: string;
-    backgroundColor?: string;
-    surfaceColor?: string;
-    surfaceHoverColor?: string;
-    textColor?: string;
-    secondaryTextColor?: string;
-    disabledTextColor?: string;
-    onPrimaryColor?: string;
-    borderColor?: string;
-    shadow?: string;
-    borderRadius?: string;
-    fontFamily?: string;
-  }): void;
-
-  on<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
-  once<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
-  off<K extends keyof TimepickerEventMap>(event: K, handler?: (data: TimepickerEventMap[K]) => void): void;
-
-  /** @internal */
-  emit?<K extends keyof TimepickerEventMap>(event: K, data?: TimepickerEventMap[K]): void;
-
-  eventManager?: EventManager;
-  modalManager?: ModalManager;
-  animationManager?: AnimationManager;
-  clockManager?: ClockManager;
-  validationManager?: ValidationManager;
-  themeManager?: ThemeManager;
-  configManager?: ConfigManager;
-  domBatcher: DOMUpdateBatcher;
-}
-
-declare class TimepickerCore {
-    _degreesHours: number | null;
-    _degreesMinutes: number | null;
-    _options: OptionTypes;
-    _eventsClickMobile: (event: Event) => Promise<void>;
-    _eventsClickMobileHandler: EventListenerOrEventListenerObject;
-    _mutliEventsMove: (event: Event) => void;
-    _mutliEventsMoveHandler: EventListenerOrEventListenerObject;
-    _clickTouchEvents: string[];
-    _element: HTMLElement;
-    _instanceId: string;
-    _isMobileView: boolean | null;
-    _isTouchMouseMove: boolean | null;
-    _disabledTime: {
-        value?: {
-            isInterval?: boolean;
-            intervals?: string[];
-            clockType?: string;
-            hours?: string[];
-            minutes?: string[];
-        };
-    } | null;
-    _cloned: Node | null;
-    _inputEvents: string[];
-    _isModalRemove?: boolean;
-    _isInitialized: boolean;
-    _customId?: string;
-    _eventHandlersRegistered: boolean;
-    _isDestroyed: boolean;
-    _pendingThemeConfig?: {
-        primaryColor?: string;
-        backgroundColor?: string;
-        surfaceColor?: string;
-        surfaceHoverColor?: string;
-        textColor?: string;
-        secondaryTextColor?: string;
-        disabledTextColor?: string;
-        onPrimaryColor?: string;
-        borderColor?: string;
-        shadow?: string;
-        borderRadius?: string;
-        fontFamily?: string;
-    };
-    eventManager: EventManager;
-    modalManager: ModalManager;
-    animationManager: AnimationManager;
-    clockManager: ClockManager;
-    validationManager: ValidationManager;
-    themeManager: ThemeManager;
-    configManager: ConfigManager;
-    domBatcher: DOMUpdateBatcher;
-    private _eventEmitter;
-    constructor(selectorOrElement: string | HTMLElement, options?: OptionTypes);
-    get modalTemplate(): string;
-    get modalElement(): HTMLDivElement;
-    get clockFace(): HTMLDivElement;
-    get input(): HTMLInputElement;
-    get clockHand(): HTMLDivElement;
-    get circle(): HTMLDivElement;
-    get tipsWrapper(): HTMLDivElement;
-    get tipsWrapperFor24h(): HTMLDivElement;
-    get minutes(): HTMLInputElement;
-    get hour(): HTMLInputElement;
-    get AM(): HTMLDivElement;
-    get PM(): HTMLDivElement;
-    get hourText(): HTMLDivElement;
-    get minutesText(): HTMLDivElement;
-    get header(): HTMLDivElement;
-    get inputWrappers(): NodeListOf<Element>;
-    get dots(): HTMLDivElement;
-    get minutesTips(): HTMLDivElement;
-    get hourTips(): HTMLDivElement;
-    get allValueTips(): HTMLDivElement[];
-    get openElementData(): string[] | null;
-    get openElement(): NodeListOf<Element> | readonly [HTMLInputElement];
-    get cancelButton(): HTMLButtonElement;
-    get okButton(): HTMLButtonElement;
-    get activeTypeMode(): HTMLButtonElement;
-    get keyboardClockIcon(): HTMLButtonElement;
-    get footer(): HTMLDivElement;
-    get wrapper(): HTMLDivElement;
-    getElement(): HTMLElement;
-    on<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
-    once<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
-    off<K extends keyof TimepickerEventMap>(event: K, handler?: (data: TimepickerEventMap[K]) => void): void;
-    /** @internal */
-    emit<K extends keyof TimepickerEventMap>(event: K, data?: TimepickerEventMap[K]): void;
-    protected _applyThemeToWrapper(wrapper: HTMLElement): void;
-    private _resolveInputElement;
-    private _createWrapperElement;
+  focusTrap?: boolean;
+
+  /**
+   * @description Delay for clickable elements (ms)
+   * @default 300
+   */
+  delayHandler?: number;
+
+  /**
+   * @description Custom ID for the timepicker instance
+   * @example id: "my-timepicker-1"
+   */
+  id?: string;
+}
+
+/**
+ * Event callbacks configuration
+ */
+interface CallbacksOptions {
+  /**
+   * @description Triggered when timepicker opens
+   */
+  onOpen?: TimepickerEventCallback<OpenEventData>;
+
+  /**
+   * @description Triggered when user cancels
+   */
+  onCancel?: TimepickerEventCallback<CancelEventData>;
+
+  /**
+   * @description Triggered when user confirms time
+   */
+  onConfirm?: TimepickerEventCallback<ConfirmEventData>;
+
+  /**
+   * @description Triggered during interaction (real-time)
+   */
+  onUpdate?: TimepickerEventCallback<UpdateEventData>;
+
+  /**
+   * @description Triggered when hour mode is selected
+   */
+  onSelectHour?: TimepickerEventCallback<SelectHourEventData>;
+
+  /**
+   * @description Triggered when minute mode is selected
+   */
+  onSelectMinute?: TimepickerEventCallback<SelectMinuteEventData>;
+
+  /**
+   * @description Triggered when AM is selected
+   */
+  onSelectAM?: TimepickerEventCallback<SelectAMEventData>;
+
+  /**
+   * @description Triggered when PM is selected
+   */
+  onSelectPM?: TimepickerEventCallback<SelectPMEventData>;
+
+  /**
+   * @description Triggered on invalid time format
+   */
+  onError?: TimepickerEventCallback<ErrorEventData>;
+}
+
+/**
+ * Main options type with grouped structure (v4.0.0)
+ */
+interface TimepickerOptions {
+  clock?: ClockOptions;
+  ui?: UIOptions;
+  labels?: LabelsOptions;
+  behavior?: BehaviorOptions;
+  callbacks?: CallbacksOptions;
 }
 
-type TypeFunction$1 = () => void;
-declare class TimepickerLifecycle extends TimepickerCore {
-    create: () => void;
-    open: (callback?: () => void) => void;
-    close: () => (...args: (boolean | TypeFunction$1)[]) => void;
-    destroy: (options?: {
+type Callback = () => void;
+declare class TimepickerUI {
+    private readonly core;
+    private readonly managers;
+    private readonly lifecycle;
+    private readonly emitter;
+    constructor(selectorOrElement: string | HTMLElement, options?: TimepickerOptions);
+    private setupInternalEventListeners;
+    create(): void;
+    open(callback?: Callback): void;
+    close(update?: boolean, callback?: Callback): void;
+    destroy(options?: {
         keepInputValue?: boolean;
-        callback?: TypeFunction$1;
-    } | TypeFunction$1) => void;
-    protected onDestroy?: () => void;
-    _eventsBundle: () => void;
-}
-
-type TypeFunction = () => void;
-declare class TimepickerAPI extends TimepickerLifecycle {
-    getValue: () => {
+        callback?: Callback;
+    } | Callback): void;
+    update(value: {
+        options: TimepickerOptions;
+        create?: boolean;
+    }, callback?: Callback): void;
+    getValue(): {
         hour: string;
         minutes: string;
         type?: string;
@@ -721,33 +560,26 @@ declare class TimepickerAPI extends TimepickerLifecycle {
         degreesHours: number | null;
         degreesMinutes: number | null;
     };
-    setValue: (time: string, updateInput?: boolean) => void;
-    update: (value: {
-        options: OptionTypes;
-        create?: boolean;
-    }, callback?: TypeFunction) => void;
-    setTheme(themeConfig: {
-        primaryColor?: string;
-        backgroundColor?: string;
-        surfaceColor?: string;
-        surfaceHoverColor?: string;
-        textColor?: string;
-        secondaryTextColor?: string;
-        disabledTextColor?: string;
-        onPrimaryColor?: string;
-        borderColor?: string;
-        shadow?: string;
-        borderRadius?: string;
-        fontFamily?: string;
-    }): void;
-}
-
-declare class TimepickerUI extends TimepickerAPI implements ITimepickerUI {
-    constructor(selectorOrElement: string | HTMLElement, options?: OptionTypes);
+    setValue(time: string, updateInput?: boolean): void;
+    getElement(): HTMLElement;
+    get instanceId(): string;
+    get options(): Required<TimepickerOptions>;
+    get isInitialized(): boolean;
+    get isDestroyed(): boolean;
+    get hour(): HTMLInputElement | null;
+    get minutes(): HTMLInputElement | null;
+    get okButton(): HTMLButtonElement | null;
+    get cancelButton(): HTMLButtonElement | null;
+    get clockHand(): HTMLDivElement | null;
+    on<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
+    once<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
+    off<K extends keyof TimepickerEventMap>(event: K, handler?: (data: TimepickerEventMap[K]) => void): void;
+    private resolveInputElement;
+    private createWrapperElement;
     static getById(id: string): TimepickerUI | undefined;
     static getAllInstances(): TimepickerUI[];
     static isAvailable(selectorOrElement: string | HTMLElement): boolean;
     static destroyAll(): void;
 }
 
-export { type CallbackData, EventEmitter, type OptionTypes, TimepickerUI, TimepickerUI as default };
+export { type CancelEventData, type ConfirmEventData, type ErrorEventData, EventEmitter, type HideEventData, type OpenEventData, type OptionTypes, type SelectAMEventData, type SelectHourEventData, type SelectMinuteEventData, type SelectPMEventData, type ShowEventData, type SwitchViewEventData, TimepickerUI, type UpdateEventData, TimepickerUI as default };