timepicker-ui 4.1.6 → 4.2.0

package/dist/index.d.ts

@@ -15,6 +15,13 @@ type ConfirmEventData = {
   hour?: string;
   minutes?: string;
   type?: string;
+  /** When true, this confirm was triggered by commitOnScroll (auto-commit) */
+  autoCommit?: boolean;
+};
+
+/** Payload when user clears time */
+type ClearEventData = {
+  previousValue: string | null;
 };
 
 /** Payload when modal shows */
@@ -87,6 +94,18 @@ type RangeGetDisabledTimeEventData = Record<string, never>;
 
 type RangeUpdateDisabledEventData = Record<string, never>;
 
+/** Payload when wheel scroll starts on a column */
+type WheelScrollStartEventData = {
+  column: 'hours' | 'minutes' | 'ampm';
+};
+
+/** Payload when wheel scroll ends and snaps to a value */
+type WheelScrollEndEventData = {
+  column: 'hours' | 'minutes' | 'ampm';
+  value: string;
+  previousValue: string | null;
+};
+
 /** Payload when validation error occurs */
 type ErrorEventData = {
   error: string;
@@ -102,6 +121,8 @@ type ErrorEventData = {
 type TimepickerEventCallback<T = unknown> = (eventData: T) => void;
 
 type OptionTypes = {
+  /** Picker mode: clock, wheel, or compact-wheel @default "clock" */
+  mode?: 'clock' | 'wheel' | 'compact-wheel';
   /** AM label text @default "AM" */
   amLabel?: string;
   /** Enable animations @default true */
@@ -235,6 +256,7 @@ interface TimepickerEventMap {
     open: OpenEventData;
     cancel: CancelEventData;
     confirm: ConfirmEventData;
+    clear: ClearEventData;
     show: ShowEventData;
     hide: HideEventData;
     update: UpdateEventData;
@@ -250,6 +272,8 @@ interface TimepickerEventMap {
     'range:minute:commit': RangeMinuteCommitEventData;
     'range:get-disabled-time': RangeGetDisabledTimeEventData;
     'range:update-disabled': RangeUpdateDisabledEventData;
+    'wheel:scroll:start': WheelScrollStartEventData;
+    'wheel:scroll:end': WheelScrollEndEventData;
     'animation:clock': Record<string, never>;
     'animation:start': Record<string, never>;
     'animation:end': Record<string, never>;
@@ -350,6 +374,12 @@ interface ClockOptions {
  * UI appearance and behavior configuration
  */
 interface UIOptions {
+  /**
+   * @description Picker mode: analog clock face, scroll wheel spinner, or compact wheel (no header)
+   * @default "clock"
+   */
+  mode?: 'clock' | 'wheel' | 'compact-wheel';
+
   /**
    * @description Theme for the timepicker
    * @default "basic"
@@ -408,6 +438,12 @@ interface UIOptions {
    */
   cssClass?: string;
 
+  /**
+   * @description Show clear button to reset time selection
+   * @default false
+   */
+  clearButton?: boolean;
+
   /**
    * @description Selector where to append modal (default: body)
    * @default ""
@@ -495,6 +531,12 @@ interface LabelsOptions {
    * @default "Minute"
    */
   mobileMinute?: string;
+
+  /**
+   * @description "Clear" button text
+   * @default "Clear"
+   */
+  clear?: string;
 }
 
 /**
@@ -558,6 +600,58 @@ interface TimezoneOptions {
   label?: string;
 }
 
+/**
+ * Wheel / compact-wheel mode configuration
+ * @example
+ * wheel: {
+ *   placement: 'auto',
+ *   hideFooter: true,
+ *   commitOnScroll: true
+ * }
+ */
+interface WheelOptions {
+  /**
+   * @description Popover placement relative to input in compact-wheel mode.
+   * 'auto' opens below if space allows, otherwise above.
+   * Defaults to 'auto' in compact-wheel mode.
+   * Can be overridden to 'top' or 'bottom' for fixed positioning.
+   * @default 'auto' (compact-wheel) | undefined (wheel)
+   */
+  placement?: 'auto' | 'top' | 'bottom';
+
+  /**
+   * @description When true, the footer (OK/Cancel/Clear buttons + switch icon)
+   * is not rendered in the DOM at all. Only works in compact-wheel mode.
+   * Useful when commitOnScroll is enabled and buttons are unnecessary.
+   * @default false
+   */
+  hideFooter?: boolean;
+
+  /**
+   * @description When enabled, the timepicker automatically commits the selected time
+   * at the end of wheel scrolling, updating the input value and emitting a change event
+   * without requiring the user to press OK. Only applies to wheel and compact-wheel modes.
+   * @default false
+   */
+  commitOnScroll?: boolean;
+
+  /**
+   * @description When true, disabled hours/minutes are completely removed from the wheel list
+   * instead of being dimmed. Only applies to wheel and compact-wheel modes.
+   * Useful when many values are disabled (e.g., business hours only).
+   * @default false
+   */
+  hideDisabled?: boolean;
+
+  /**
+   * @description When true, clicking outside the picker area does not close it.
+   * Only applies to wheel and compact-wheel modes (popover and modal).
+   * The user must explicitly press OK or Cancel to close the picker.
+   * @default false
+   */
+  ignoreOutsideClick?: boolean;
+}
+
 /**
  * Range mode configuration (opt-in)
  */
@@ -659,6 +753,22 @@ interface CallbacksOptions {
    * @description Triggered on range validation (range mode only)
    */
   onRangeValidation?: TimepickerEventCallback<RangeValidationEventData>;
+
+  /**
+   * @description Triggered when clear button is clicked
+   */
+  onClear?: TimepickerEventCallback<ClearEventData>;
+}
+
+/**
+ * Clear button behavior configuration
+ */
+interface ClearBehaviorOptions {
+  /**
+   * @description Whether clicking clear also empties the input field value
+   * @default true
+   */
+  clearInput?: boolean;
 }
 
 /**
@@ -672,6 +782,8 @@ interface TimepickerOptions {
   callbacks?: CallbacksOptions;
   timezone?: TimezoneOptions;
   range?: RangeOptions;
+  wheel?: WheelOptions;
+  clearBehavior?: ClearBehaviorOptions;
 }
 
 type Callback = () => void;
@@ -736,6 +848,10 @@ declare class TimepickerUI {
      * @param updateInput - If true, the input field will be updated with the new time value. Default is true.
      */
     setValue(time: string, updateInput?: boolean): void;
+    private parseTimeString;
+    private applyParsedTime;
+    private syncPeriodIndicator;
+    private syncClockVisual;
     /**
      * Get the root element of the timepicker instance.
      * @returns - The HTMLElement that serves as the root of the timepicker instance.
@@ -792,21 +908,21 @@ declare class TimepickerUI {
      * @param handler - The function to handle the event.
      * @returns - void
      */
-    on<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
+    on<K extends keyof TimepickerEventMap>(event: K, handler: () => void): void;
     /**
      * Subscribe to a timepicker event with a handler function that will be called only once.
      * @param event - The name of the event to subscribe to.
      * @param handler - The function to handle the event.
      * @returns - void
      */
-    once<K extends keyof TimepickerEventMap>(event: K, handler: (data: TimepickerEventMap[K]) => void): void;
+    once<K extends keyof TimepickerEventMap>(event: K, handler: () => void): void;
     /**
      * Unsubscribe from a timepicker event. If a handler is provided, only that handler will be removed. If no handler is provided, all handlers for the event will be removed.
      * @param event - The name of the event to unsubscribe from.
      * @param handler - The function to handle the event.
      * @returns - void
      */
-    off<K extends keyof TimepickerEventMap>(event: K, handler?: (data: TimepickerEventMap[K]) => void): void;
+    off<K extends keyof TimepickerEventMap>(event: K, handler?: () => void): void;
     private resolveInputElement;
     private createWrapperElement;
     /**
@@ -851,6 +967,7 @@ interface CoreStateData {
     } | null;
     readonly cloned: Node | null;
     readonly isModalRemove: boolean;
+    readonly isOpen: boolean;
     readonly isInitialized: boolean;
     readonly customId?: string;
     readonly eventHandlersRegistered: boolean;
@@ -869,6 +986,7 @@ declare class CoreState {
     get disabledTime(): CoreStateData['disabledTime'];
     get cloned(): Node | null;
     get isModalRemove(): boolean;
+    get isOpen(): boolean;
     get isInitialized(): boolean;
     get customId(): string | undefined;
     get eventHandlersRegistered(): boolean;
@@ -881,6 +999,7 @@ declare class CoreState {
     setDisabledTime(value: CoreStateData['disabledTime']): void;
     setCloned(value: Node | null): void;
     setIsModalRemove(value: boolean): void;
+    setIsOpen(value: boolean): void;
     setIsInitialized(value: boolean): void;
     setEventHandlersRegistered(value: boolean): void;
     setIsDestroyed(value: boolean): void;
@@ -925,14 +1044,9 @@ interface Plugin {
     factory: PluginFactory;
     optionsExtender?: (options: Record<string, unknown>) => void;
 }
-interface PluginInput {
-    name: string;
-    factory: (core: never, emitter: never) => PluginManager;
-    optionsExtender?: (options: Record<string, unknown>) => void;
-}
 declare class PluginRegistryClass {
     private plugins;
-    register(plugin: Plugin | PluginInput): void;
+    register(plugin: Plugin): void;
     getAll(): Plugin[];
     has(name: string): boolean;
     get(name: string): Plugin | undefined;
@@ -940,4 +1054,4 @@ declare class PluginRegistryClass {
 declare const PluginRegistry: PluginRegistryClass;
 
 export { CoreState, EventEmitter, PluginRegistry, TimepickerUI, TimepickerUI as default };
-export type { BehaviorOptions, CallbacksOptions, CancelEventData, ClockOptions, ConfirmEventData, ErrorEventData, HideEventData, LabelsOptions, OpenEventData, OptionTypes, Plugin, PluginFactory, PluginManager, RangeConfirmEventData, RangeOptions, RangeSwitchEventData, RangeValidationEventData, SelectAMEventData, SelectHourEventData, SelectMinuteEventData, SelectPMEventData, ShowEventData, SwitchViewEventData, TimepickerEventMap, TimepickerOptions, TimezoneChangeEventData, TimezoneOptions, UIOptions, UpdateEventData };
+export type { BehaviorOptions, CallbacksOptions, CancelEventData, ClearBehaviorOptions, ClearEventData, ClockOptions, ConfirmEventData, ErrorEventData, HideEventData, LabelsOptions, OpenEventData, OptionTypes, Plugin, PluginFactory, PluginManager, RangeConfirmEventData, RangeOptions, RangeSwitchEventData, RangeValidationEventData, SelectAMEventData, SelectHourEventData, SelectMinuteEventData, SelectPMEventData, ShowEventData, SwitchViewEventData, TimepickerEventMap, TimepickerOptions, TimezoneChangeEventData, TimezoneOptions, UIOptions, UpdateEventData, WheelScrollEndEventData, WheelScrollStartEventData };