### Glassmorphic Theme Example Source: https://timepicker-ui.vercel.app/docs/features/themes Example of initializing Timepicker UI with the Glassmorphic theme, enabling backdrop and animation. ```typescript import 'timepicker-ui/main.css'; import 'timepicker-ui/theme-glassmorphic.css'; const picker = new TimepickerUI(input, { ui: { theme: 'glassmorphic', backdrop: true, animation: true } }); ``` -------------------------------- ### Cyberpunk Theme Example Source: https://timepicker-ui.vercel.app/docs/features/themes Example of initializing Timepicker UI with the Cyberpunk theme, enabling animation and backdrop. ```typescript import 'timepicker-ui/main.css'; import 'timepicker-ui/theme-cyberpunk.css'; const picker = new TimepickerUI(input, { ui: { theme: 'cyberpunk', animation: true, backdrop: true }, clock: { type: '24h' } }); ``` -------------------------------- ### Blueprint Theme Example Source: https://timepicker-ui.vercel.app/docs/features/themes Example of initializing Timepicker UI with the Blueprint theme. The dark sibling `blueprint-dark` can be imported and used similarly. ```typescript import 'timepicker-ui/main.css'; import 'timepicker-ui/theme-blueprint.css'; const picker = new TimepickerUI(input, { ui: { theme: 'blueprint', animation: true } }); // Dark sibling // import 'timepicker-ui/theme-blueprint-dark.css'; // ui: { theme: 'blueprint-dark' } ``` -------------------------------- ### Install Timepicker-UI with npm, yarn, or pnpm Source: https://timepicker-ui.vercel.app/docs/installation Choose your preferred package manager to install the Timepicker-UI library. ```bash npm install timepicker-ui ``` ```bash yarn add timepicker-ui ``` ```bash pnpm add timepicker-ui ``` -------------------------------- ### Material Design 3 Theme Example Source: https://timepicker-ui.vercel.app/docs/features/themes Example of initializing Timepicker UI with the Material Design 3 green theme. ```typescript import 'timepicker-ui/main.css'; import 'timepicker-ui/theme-m3-green.css'; const picker = new TimepickerUI(input, { ui: { theme: 'm3-green', animation: true }, clock: { type: '12h' } }); ``` -------------------------------- ### Install Timepicker UI with TypeScript Source: https://timepicker-ui.vercel.app/docs/api/typescript Install the package using npm. TypeScript definitions are included automatically, making types available for import. ```bash npm install timepicker-ui ``` ```typescript // Types are automatically available import { TimepickerUI } from 'timepicker-ui'; import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui'; ``` -------------------------------- ### Basic Mobile Setup for Timepicker-UI Source: https://timepicker-ui.vercel.app/docs/features/mobile Enable mobile optimizations, smooth animations, and a full backdrop on small screens when initializing Timepicker-UI. ```typescript const picker = new TimepickerUI(input, { ui: { mobile: true, // Enable mobile optimizations animation: true, // Smooth animations backdrop: true // Full backdrop on small screens } }); picker.create(); ``` -------------------------------- ### Portuguese Locale Configuration Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example configuration for Portuguese locale using a 24-hour format with custom 'Confirmar' and 'Cancelar' labels. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h' }, labels: { ok: 'Confirmar', cancel: 'Cancelar' } }); ``` -------------------------------- ### Italian Locale Configuration Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example configuration for Italian locale using a 24-hour format with custom 'OK' and 'Annulla' labels. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h' }, labels: { ok: 'OK', cancel: 'Annulla' } }); ``` -------------------------------- ### Timepicker UI v3.x Initialization Source: https://timepicker-ui.vercel.app/docs/whats-new Example of initializing Timepicker UI with options in version 3.x. This shows the older, flat structure for configuration. ```typescript const picker = new TimepickerUI(input, { clockType: '12h', theme: 'dark', mobile: true, animation: true, incrementMinutes: 5, okLabel: 'Confirm', cancelLabel: 'Close' }); ``` -------------------------------- ### Basic Timepicker Setup (v4.0.0) Source: https://timepicker-ui.vercel.app/docs/migration-guide Initializes a Timepicker UI instance with a 12-hour clock. Ensure the target element '#input' exists in your HTML. ```typescript 1// v4.0.0 2const timepicker = new TimepickerUI('#input', { 3 clock: { type: '12h' }, }); ``` -------------------------------- ### Japanese Locale Configuration Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example configuration for Japanese locale using a 24-hour format with custom 'OK' and 'Cancel' labels. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h' }, labels: { ok: '確認', cancel: 'キャンセル' } }); ``` -------------------------------- ### Spanish Localization Example Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example of how to set Spanish labels directly when initializing Timepicker UI. Ensure the 'input' element is defined in your HTML. ```typescript 1const picker = new TimepickerUI(input, { 2 labels: { 3 ok: 'Aceptar', 4 cancel: 'Cancelar', 5 am: 'AM', 6 pm: 'PM' 7 } 8}); 9 10picker.create(); ``` -------------------------------- ### French Localization Example Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example of how to set French labels directly when initializing Timepicker UI. Ensure the 'input' element is defined in your HTML. ```typescript 1const picker = new TimepickerUI(input, { 2 labels: { 3 ok: 'Valider', 4 cancel: 'Annuler', 5 am: 'AM', 6 pm: 'PM' 7 } 8}); 9 10picker.create(); ``` -------------------------------- ### German Localization Example Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example of how to set German labels directly when initializing Timepicker UI. Ensure the 'input' element is defined in your HTML. ```typescript 1const picker = new TimepickerUI(input, { 2 labels: { 3 ok: 'OK', 4 cancel: 'Abbrechen', 5 am: 'AM', 6 pm: 'PM' 7 } 8}); 9 10picker.create(); ``` -------------------------------- ### v3.x Flat API Structure Source: https://timepicker-ui.vercel.app/docs/migration-guide Example of the old flat API structure used in v3.x. This configuration will not work with v4.0.0. ```typescript const timepicker = new TimepickerUI('#input', { clockType: '12h', amLabel: 'AM', pmLabel: 'PM', okLabel: 'OK', cancelLabel: 'Cancel', timeLabel: 'Select time', animation: true, backdrop: true, theme: 'basic', incrementHours: 1, incrementMinutes: 5, focusTrap: true, delayHandler: 300, mobile: false, editable: false, onOpen: (event) => console.log('opened', event), onConfirm: (event) => console.log('confirmed', event), }); ``` -------------------------------- ### Complete Timepicker Validation Example Source: https://timepicker-ui.vercel.app/docs/features/validation Integrates HTML structure, CSS for styling, and JavaScript for client-side validation logic. This example demonstrates how to provide immediate feedback on time input validity. ```html
``` -------------------------------- ### Arabic Locale Configuration Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example configuration for Arabic locale using a 12-hour format with custom labels for OK, Cancel, AM, and PM. ```typescript const picker = new TimepickerUI(input, { clock: { type: '12h' }, labels: { ok: 'موافق', cancel: 'إلغاء', am: 'ص', pm: 'م' } }); ``` -------------------------------- ### Russian Locale Configuration Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example configuration for Russian locale using a 24-hour format with custom 'OK' and 'Cancel' labels. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h' }, labels: { ok: 'ОК', cancel: 'Отмена' } }); ``` -------------------------------- ### Create, Get, and Destroy Timepicker Instances Source: https://timepicker-ui.vercel.app/docs/legacy-migration Demonstrates how to create multiple Timepicker UI instances with unique IDs, retrieve an instance by its ID, and destroy all instances simultaneously using static methods. ```javascript const picker1 = new TimepickerUI('#input1', { id: 'picker1' }); const picker2 = new TimepickerUI('#input2', { id: 'picker2' }); const instance = TimepickerUI.getById('picker1'); TimepickerUI.destroyAll(); ``` -------------------------------- ### Chinese Simplified Locale Configuration Source: https://timepicker-ui.vercel.app/docs/advanced/localization Example configuration for Simplified Chinese locale using a 24-hour format with custom 'OK' and 'Cancel' labels. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h' }, labels: { ok: '确定', cancel: '取消' } }); ``` -------------------------------- ### Register Multiple Plugins for Timepicker UI Source: https://timepicker-ui.vercel.app/docs/features/plugins Register all required plugins once at application startup before creating TimepickerUI instances. This example shows registering Range, Timezone, and Wheel plugins. ```javascript import { TimepickerUI, PluginRegistry } from 'timepicker-ui'; import { RangePlugin } from 'timepicker-ui/plugins/range'; import { TimezonePlugin } from 'timepicker-ui/plugins/timezone'; import { WheelPlugin } from 'timepicker-ui/plugins/wheel'; import 'timepicker-ui/main.css'; // Register plugins once at startup PluginRegistry.register(RangePlugin); PluginRegistry.register(TimezonePlugin); PluginRegistry.register(WheelPlugin); // Range + Timezone picker const rangePicker = new TimepickerUI(input1, { range: { enabled: true }, timezone: { enabled: true } }); rangePicker.create(); // Wheel picker const wheelPicker = new TimepickerUI(input2, { ui: { mode: 'wheel' } }); wheelPicker.create(); ``` -------------------------------- ### Advanced Timepicker Setup (v4.0.0) Source: https://timepicker-ui.vercel.app/docs/migration-guide Configures Timepicker UI with a 24-hour clock, custom minute increments, disabled times, theme, UI animations, and behavior options. Callbacks for open, confirm, and cancel events are included. ```typescript 1// v4.0.0 2const timepicker = new TimepickerUI('#input', { 3 clock: { 4 type: '24h', 5 incrementMinutes: 15, 6 disabledTime: { 7 hours: [0, 1, 2, 23], 8 interval: ['00:00 - 06:00', '22:00 - 23:59'], 9 }, 10 }, 11 ui: { 12 theme: 'm3-green', 13 animation: true, 14 backdrop: true, 15 mobile: false, 16 editable: true, 17 }, 18 labels: { 19 time: 'Pick a time', 20 ok: 'Confirm', 21 cancel: 'Dismiss', 22 }, 23 behavior: { 24 focusTrap: true, 25 delayHandler: 300, 26 focusInputAfterClose: true, 27 }, 28 callbacks: { 29 onOpen: () => console.log('Opened'), 30 onConfirm: (data) => console.log('Time selected:', data), 31 onCancel: () => console.log('Cancelled'), 32 }, 33}); ``` -------------------------------- ### v4.0.0 Grouped API Structure Source: https://timepicker-ui.vercel.app/docs/migration-guide Example of the new grouped API structure in v4.0.0. All v3.x configurations must be updated to this format. ```typescript const timepicker = new TimepickerUI('#input', { clock: { type: '12h', incrementHours: 1, incrementMinutes: 5, }, ui: { animation: true, backdrop: true, theme: 'basic', mobile: false, editable: false, }, labels: { am: 'AM', pm: 'PM', ok: 'OK', cancel: 'Cancel', time: 'Select time', }, behavior: { focusTrap: true, delayHandler: 300, }, callbacks: { onOpen: (event) => console.log('opened', event), onConfirm: (event) => console.log('confirmed', event), }, }); ``` -------------------------------- ### Subscribe to 'open' event once Source: https://timepicker-ui.vercel.app/docs/api/events Use the `once` method to subscribe to an event that will only fire the first time it occurs. This is useful for one-time setup or logging. ```typescript picker.once('open', () => { console.log('Opened for the first time'); }); ``` -------------------------------- ### Migrate Timepicker UI Options from v3.x to v4.0.0 Source: https://timepicker-ui.vercel.app/docs/whats-new Compares the old options structure of Timepicker UI v3.x with the new structure in v4.0.0. Use this example to understand how to update your configuration when migrating. ```typescript 1// v3.x 2const picker = new TimepickerUI(input, { clockType: '24h', theme: 'dark', mobile: true, animation: true, incrementMinutes: 15, okLabel: 'Confirm', cancelLabel: 'Close', focusTrap: true }); 12 13// v4.0.0 14const picker = new TimepickerUI(input, { 15 clock: { 16 type: '24h', 17 incrementMinutes: 15 18 }, 19 ui: { 20 theme: 'dark', 21 mobile: true, 22 animation: true 23 }, 24 labels: { 25 ok: 'Confirm', 26 cancel: 'Close' 27 }, 28 behavior: { 29 focusTrap: true 30 } 31}); ``` -------------------------------- ### Timepicker UI v4.0.0 Initialization with Grouped Options Source: https://timepicker-ui.vercel.app/docs/whats-new Example of initializing Timepicker UI with the new grouped options architecture in version 4.0.0. Options are now organized into 'clock', 'ui', and 'labels' for better maintainability. ```typescript const picker = new TimepickerUI(input, { clock: { type: '12h', incrementMinutes: 5 }, ui: { theme: 'dark', mobile: true, animation: true }, labels: { ok: 'Confirm', cancel: 'Close' } }); ``` -------------------------------- ### Inline Mode Timepicker Setup (v4.0.0) Source: https://timepicker-ui.vercel.app/docs/migration-guide Sets up Timepicker UI in inline mode, specifying a container and disabling focus trap. Ensure the 'timepicker-container' ID exists in your HTML. ```typescript 1// v4.0.0 2const timepicker = new TimepickerUI('#input', { 3 ui: { 4 inline: { 5 enabled: true, 6 containerId: 'timepicker-container', 7 showButtons: false, 8 autoUpdate: true, 9 }, 10 }, 11 behavior: { 12 focusTrap: false, // Automatically set if not specified 13 }, 14}); ``` -------------------------------- ### Customize Timepicker-UI with Options Source: https://timepicker-ui.vercel.app/docs/quick-start Configure Timepicker-UI with custom options for UI theme, clock type, and confirmation callbacks. This example uses a dark theme and 24-hour clock format. ```typescript const picker = new TimepickerUI(input, { ui: { theme: 'dark', animation: true, backdrop: true }, clock: { type: '24h' }, callbacks: { onConfirm: (data) => { console.log('Selected time:', data); } } }); picker.create(); ``` -------------------------------- ### wheel:scroll:start Event Source: https://timepicker-ui.vercel.app/docs/api/events Triggered when a wheel column starts scrolling in wheel mode. ```APIDOC ## `wheel:scroll:start` Event ### Description Triggered when a wheel column starts scrolling (wheel mode only). ### Event Name `wheel:scroll:start` ### Data Payload - **column** (string) - The column that started scrolling ('hours', 'minutes', or 'ampm'). ### Example ```javascript picker.on('wheel:scroll:start', (data) => { console.log('Scroll started on column:', data.column); }); ``` ``` -------------------------------- ### Custom Minutes per Hour Source: https://timepicker-ui.vercel.app/docs/features/disabled-time Define specific minutes that are allowed or disallowed for each hour. This example disables all hours except 9 AM to 7 PM and then further restricts the minutes within those hours to only quarter-hour marks. ```typescript const picker = new TimepickerUI(input, { clock: { disabledTime: { hours: [0, 1, 2, 3, 4, 5, 6, 7, 8, 20, 21, 22, 23], minutes: [5, 10, 20, 25, 35, 40, 50, 55] } } }); // Only allows minutes: 0, 15, 30, 45 during hours 9-19 ``` -------------------------------- ### Combine Hour and Minute Restrictions Source: https://timepicker-ui.vercel.app/docs/features/disabled-time Apply both hour and minute restrictions simultaneously for precise time control. This example disables specific hours and also disables a lunch interval within the allowed hours. ```typescript const picker = new TimepickerUI(input, { clock: { disabledTime: { hours: [0, 1, 2, 3, 4, 5, 6, 7, 8, 18, 19, 20, 21, 22, 23], interval: '12:00 PM - 1:00 PM' } } }); picker.create(); // Result: 9:00-17:59 is selectable, with the 12:00-1:00 PM lunch break disabled ``` -------------------------------- ### Complete Timepicker UI Initialization Source: https://timepicker-ui.vercel.app/docs/api/options Demonstrates the full initialization of Timepicker UI with all available options configured for clock, UI, wheel, labels, behavior, and callbacks. Use this as a reference for comprehensive customization. ```typescript const picker = new TimepickerUI(input, { // Clock options clock: { type: '24h', incrementHours: 1, incrementMinutes: 5, autoSwitchToMinutes: true, disabledTime: { hours: [0, 1, 2, 3], interval: '10:00 - 12:00' }, currentTime: { updateInput: true, time: new Date() } }, // UI options ui: { theme: 'dark', animation: true, backdrop: true, mobile: false, enableScrollbar: false, enableSwitchIcon: false, editable: false, cssClass: 'custom-picker', appendModalSelector: '#timepicker-container' }, // Wheel options wheel: { placement: 'bottom', hideFooter: true, commitOnScroll: true, hideDisabled: true, ignoreOutsideClick: false }, // Labels options labels: { ok: 'Confirm', cancel: 'Close', time: 'Choose Time', am: 'AM', pm: 'PM', mobileTime: 'Enter Time', mobileHour: 'Hour', mobileMinute: 'Minute' }, // Behavior options behavior: { focusTrap: true, focusInputAfterClose: false, delayHandler: 300, id: 'my-timepicker' }, // Callbacks options callbacks: { onConfirm: (data) => console.log('Confirmed:', data), onCancel: () => console.log('Cancelled'), onOpen: () => console.log('Opened'), onUpdate: (data) => console.log('Updated:', data), onSelectHour: (data) => console.log('Hour selected:', data.hour), onSelectMinute: (data) => console.log('Minute selected:', data.minutes), onError: (data) => console.error('Error:', data.error) } }); ``` -------------------------------- ### Import All Themes Source: https://timepicker-ui.vercel.app/docs/features/themes Import all available themes to include all styles. This results in the largest bundle size. ```typescript import 'timepicker-ui/index.css'; ``` -------------------------------- ### Initialize Timepicker UI with Configuration Source: https://timepicker-ui.vercel.app/docs/configuration Configure Timepicker UI with options for clock settings, UI theme, wheel behavior, labels, interaction behavior, and callback functions. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h', incrementHours: 1, incrementMinutes: 5, autoSwitchToMinutes: false, disabledTime: { hours: [0, 1, 2, 3], interval: ['12:00 PM - 1:00 PM'] } }, ui: { theme: 'dark', animation: true, backdrop: true, mobile: false, editable: false, enableScrollbar: false, enableSwitchIcon: true, }, wheel: { placement: 'bottom', hideFooter: true, commitOnScroll: true }, labels: { ok: 'Confirm', cancel: 'Close', time: 'Choose Time' }, behavior: { focusTrap: true, focusInputAfterClose: false, delayHandler: 300 }, callbacks: { onConfirm: (data) => console.log('Confirmed:', data), onCancel: () => console.log('Cancelled'), onUpdate: (data) => console.log('Updated:', data) } }); ``` -------------------------------- ### Enable Blueprint Theme Source: https://timepicker-ui.vercel.app/docs/whats-new Enable the new 'blueprint' theme for a light precision-instrument look. This theme is tree-shakeable. ```javascript ui.theme: 'blueprint' ``` -------------------------------- ### Detect wheel:scroll:start Event Source: https://timepicker-ui.vercel.app/docs/api/events This event is triggered when a wheel column begins scrolling in wheel mode. It provides the name of the column that started scrolling. ```typescript picker.on('wheel:scroll:start', (data) => { console.log('Scroll started on column:', data.column); // data.column: 'hours' | 'minutes' | 'ampm' }); ``` -------------------------------- ### Get All Timepicker Instances Source: https://timepicker-ui.vercel.app/docs/api/methods Retrieves an array containing all currently active TimepickerUI instances on the page. ```typescript const allPickers = TimepickerUI.getAllInstances(); console.log(allPickers.length); ``` -------------------------------- ### v3 Timepicker UI Initialization with Callbacks and EventEmitter Source: https://timepicker-ui.vercel.app/docs/legacy-migration Demonstrates initializing Timepicker UI in version 3 using a modern callback-based API for 'onOpen', 'onConfirm', and 'onCancel' events. It also shows how to use the recommended EventEmitter API for 'confirm' and 'once' events. ```javascript import { TimepickerUI } from 'timepicker-ui'; import 'timepicker-ui/main.css'; // Required in v3 const input = document.querySelector('#myInput'); // v3 initialization with callbacks const picker = new TimepickerUI(input, { clockType: '12h', theme: 'basic', // Modern callback-based API onOpen: () => { console.log('Opened'); }, onConfirm: (data) => { console.log('Time selected:', data); }, onCancel: () => { console.log('Cancelled'); }, }); // Or use EventEmitter API (recommended) picker.on('confirm', (data) => { console.log('Confirmed:', data); }); picker.once('open', () => { console.log('First open only'); }); ``` -------------------------------- ### Get Root Wrapper Element Source: https://timepicker-ui.vercel.app/docs/api/methods Retrieves the root DOM element that wraps the timepicker component. ```typescript const wrapper = picker.getElement(); ``` -------------------------------- ### create() Source: https://timepicker-ui.vercel.app/docs/api/methods Initializes the timepicker. This method must be called before using any other methods on the instance. ```APIDOC ## `create()` ### Description Initialize the timepicker. Must be called before using other methods. ### Method `create()` ### Example ```typescript const picker = new TimepickerUI(input); picker.create(); ``` ``` -------------------------------- ### Updated Event Names in v3 Source: https://timepicker-ui.vercel.app/docs/legacy-migration In v3, event names are prefixed with 'timepicker:'. This example shows the new event names. ```javascript input.addEventListener('timepicker:open', (e) => { console.log('Opened'); }); input.addEventListener('timepicker:confirm', (e) => { console.log('Confirmed:', e.detail); }); input.addEventListener('timepicker:cancel', (e) => { console.log('Cancelled'); }); ``` -------------------------------- ### v3 Recommended Callbacks API Source: https://timepicker-ui.vercel.app/docs/legacy-migration The recommended v3 API uses callbacks like onConfirm, onCancel, and onOpen for a cleaner interface. ```javascript const picker = new TimepickerUI(input, { onConfirm: (data) => { console.log('Time:', data); }, onCancel: (data) => { console.log('Cancelled'); }, onOpen: () => { console.log('Opened'); }, }); ``` -------------------------------- ### Get Timepicker Instance by ID Source: https://timepicker-ui.vercel.app/docs/api/methods Retrieves a specific TimepickerUI instance using its unique ID. This is useful for managing multiple instances. ```typescript const picker = new TimepickerUI(input, { id: 'my-picker' }); picker.create(); const instance = TimepickerUI.getById('my-picker'); ``` -------------------------------- ### Configure Compact Wheel Mode Source: https://timepicker-ui.vercel.app/docs/whats-new Use compact-wheel mode for a headerless picker and control popover placement with options like 'auto', 'top', or 'bottom'. ```javascript compact-wheel mode ui.placement: 'auto' ``` -------------------------------- ### v2 Timepicker UI Initialization and Events Source: https://timepicker-ui.vercel.app/docs/legacy-migration This snippet shows the initialization of Timepicker UI in version 2, including configuration options like clock type and theme. It also demonstrates how to listen for 'show', 'accept', and 'cancel' events using event listeners. ```javascript import { TimepickerUI } from 'timepicker-ui'; const input = document.querySelector('#myInput'); // v2 initialization const picker = new TimepickerUI(input, { clockType: '12h', theme: 'basic', }); // v2 events input.addEventListener('show', () => { console.log('Opened'); }); input.addEventListener('accept', (e) => { console.log('Time selected:', e.detail); }); input.addEventListener('cancel', () => { console.log('Cancelled'); }); ``` -------------------------------- ### Event Names Prefixed in v3 Source: https://timepicker-ui.vercel.app/docs/legacy-migration All event names in v3 are prefixed with 'timepicker:' to avoid conflicts. This example shows the v2 event names. ```javascript input.addEventListener('show', (e) => { console.log('Opened'); }); input.addEventListener('accept', (e) => { console.log('Confirmed:', e.detail); }); input.addEventListener('cancel', (e) => { console.log('Cancelled'); }); ``` -------------------------------- ### switch:view Source: https://timepicker-ui.vercel.app/docs/api/events Triggered when switching between the clock and keyboard views. ```APIDOC ## switch:view ### Description Triggered when switching between clock and keyboard view. The payload is empty. ### Event Name `switch:view` ### Payload Empty ### Request Example ```typescript picker.on('switch:view', () => { console.log('View switched'); }); ``` ``` -------------------------------- ### Create a Custom Theme with CSS Variables Source: https://timepicker-ui.vercel.app/docs/advanced/styling Define a custom theme by applying the 'custom' class to the wrapper and overriding specific CSS variables. This allows for unique branding. ```css /* Override CSS variables in the custom theme wrapper */ .tp-ui-wrapper.custom { --tp-bg: #ffffff; --tp-text: #000000; --tp-primary: #6200ee; --tp-on-primary: #ffffff; --tp-surface: #e0e0e0; --tp-surface-hover: #ece0fd; --tp-input-bg: #e4e4e4; --tp-border: #d6d6d6; --tp-hover-bg: #d6d6d6; --tp-text-secondary: #a9a9a9; --tp-text-type-time: #787878; --tp-text-icon: #4e545a; --tp-text-disabled: rgba(156, 155, 155, 0.6); --tp-shadow: 0 10px 35px 0 rgba(0, 0, 0, 0.25); --tp-border-radius: 4px; --tp-font-family: 'Roboto', sans-serif; } ``` -------------------------------- ### Get Value from 24-Hour Format Source: https://timepicker-ui.vercel.app/docs/features/clock-format Retrieves the current time value from the Timepicker UI when configured in 24-hour format. The output has an empty type field. ```typescript const value = picker.getValue(); console.log(value); // Output: { hour: '14', minutes: '30', type: '', time: '14:30', degreesHours: 30, degreesMinutes: 180 } ``` -------------------------------- ### Get Value from 12-Hour Format Source: https://timepicker-ui.vercel.app/docs/features/clock-format Retrieves the current time value from the Timepicker UI when configured in 12-hour format. The output includes AM/PM type. ```typescript const value = picker.getValue(); console.log(value); // Output: { hour: '10', minutes: '30', type: 'AM', time: '10:30 AM', degreesHours: 30, degreesMinutes: 180 } ``` -------------------------------- ### Apply a Theme Source: https://timepicker-ui.vercel.app/docs/features/themes Apply a theme by setting the `theme` option during TimepickerUI initialization. ```typescript const picker = new TimepickerUI(input, { ui: { theme: 'cyberpunk' } }); picker.create(); ``` -------------------------------- ### Handle 'range:confirm' event Source: https://timepicker-ui.vercel.app/docs/api/events This event is for the range mode and is triggered when a time range is confirmed. The payload includes the start and end times, and the duration in minutes. ```typescript picker.on('range:confirm', (data) => { console.log('From:', data.from, 'To:', data.to); console.log('Duration (minutes):', data.duration); }); ``` -------------------------------- ### Validate Time Range Source: https://timepicker-ui.vercel.app/docs/features/validation Checks if a selected time falls within a specified start and end time. Utilizes the `timeToMinutes` helper function for accurate comparisons. ```typescript function isTimeInRange(time, startTime, endTime) { const selected = timeToMinutes(time); const start = timeToMinutes(startTime); const end = timeToMinutes(endTime); return selected >= start && selected <= end; } function timeToMinutes(time) { const [hours, minutes] = time.split(':').map(Number); return hours * 60 + minutes; } // Validate on accept input.addEventListener('accept', (event) => { const time = event.detail.hour + ':' + event.detail.minutes; if (!isTimeInRange(time, '09:00', '17:00')) { showError('Please select a time between 9:00 AM and 5:00 PM'); return; } submitTime(time); }); ``` -------------------------------- ### TypeScript Error Handling Source: https://timepicker-ui.vercel.app/docs/api/typescript Configure Timepicker UI to handle errors gracefully using the `onError` callback. This example shows logging the error and alerting the user. ```typescript import type { ConfirmEventData, ErrorEventData } from 'timepicker-ui'; import { TimepickerUI } from 'timepicker-ui'; const picker = new TimepickerUI('#timepicker', { callbacks: { onError: (data: ErrorEventData) => { console.error('Timepicker error:', data.error); alert(`Invalid time format: ${data.error}`); }, onConfirm: (data: ConfirmEventData) => { console.log('Time confirmed:', `${data.hour}:${data.minutes}`); } } }); ``` -------------------------------- ### Handle Range Confirmation with onRangeConfirm Callback Source: https://timepicker-ui.vercel.app/docs/api/events This callback option is triggered when a range is confirmed in range mode. It provides the start and end times of the range, along with the duration. ```typescript new TimepickerUI(input, { callbacks: { onRangeConfirm: (data) => { console.log('Range:', data.from, '-', data.to, data.duration); } } }); ``` -------------------------------- ### Import Timepicker-UI Styles Source: https://timepicker-ui.vercel.app/docs/installation Import the library's main CSS file into your project's entry point. ```typescript import "timepicker-ui/main.css"; ``` -------------------------------- ### Extending TypeScript Types Source: https://timepicker-ui.vercel.app/docs/api/typescript Create a custom wrapper class that extends Timepicker UI's functionality and types. This example adds analytics tracking to the confirmation callback. ```typescript import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui'; import { TimepickerUI } from 'timepicker-ui'; // Extend options with custom properties interface CustomTimepickerOptions extends TimepickerOptions { analyticsEnabled?: boolean; } // Create wrapper with custom logic class CustomTimepicker { private picker: TimepickerUI; private analyticsEnabled: boolean; constructor( input: HTMLInputElement, options: CustomTimepickerOptions ) { const { analyticsEnabled, ...pickerOptions } = options; this.analyticsEnabled = analyticsEnabled ?? false; const finalOptions: TimepickerOptions = { ...pickerOptions, callbacks: { ...pickerOptions.callbacks, onConfirm: (data: ConfirmEventData) => { if (this.analyticsEnabled) { this.trackEvent('time_confirmed', data); } pickerOptions.callbacks?.onConfirm?.(data); } } }; this.picker = new TimepickerUI(input, finalOptions); } private trackEvent(event: string, data: ConfirmEventData) { console.log('Analytics:', event, data); } create() { this.picker.create(); } destroy() { this.picker.destroy(); } } ``` -------------------------------- ### Set Timepicker UI Theme Source: https://timepicker-ui.vercel.app/docs/api/options Configure the visual theme of the Timepicker UI by setting the 'theme' option within the 'ui' object. This example sets the theme to 'cyberpunk'. ```typescript const picker = new TimepickerUI(input, { ui: { theme: 'cyberpunk' } }); ``` -------------------------------- ### open Source: https://timepicker-ui.vercel.app/docs/api/events Triggered when the timepicker opens. Provides details about the initial time and degrees. ```APIDOC ## open ### Description Triggered when the picker opens. The payload includes initial time and degree information. ### Event Name `open` ### Payload * **data** (object) * **hour** (number) - The initial hour. * **minutes** (number) - The initial minutes. * **type** (string) - 'AM' or 'PM' (in 12-hour mode). * **degreesHours** (number) - The initial hour in degrees. * **degreesMinutes** (number) - The initial minutes in degrees. ### Request Example ```typescript picker.on('open', (data) => { console.log('Picker opened'); console.log(data.hour, data.minutes, data.type); console.log(data.degreesHours, data.degreesMinutes); }); ``` ``` -------------------------------- ### Get Current Time Value Source: https://timepicker-ui.vercel.app/docs/api/methods Retrieves the currently selected time value from the timepicker. The returned object contains detailed time components and their corresponding degree values. ```typescript const value = picker.getValue(); { hour: '10', minutes: '30', type: 'AM', time: '10:30 AM', degreesHours: 300, degreesMinutes: 180 } ``` -------------------------------- ### Initialize Timepicker-UI with Default Settings Source: https://timepicker-ui.vercel.app/docs/quick-start Basic JavaScript initialization of Timepicker-UI on an HTML input element. Ensure the 'timepicker-ui' package is imported. ```typescript import { TimepickerUI } from 'timepicker-ui'; const input = document.querySelector('#timepicker'); const picker = new TimepickerUI(input); picker.create(); ``` -------------------------------- ### Implement Live Region for Screen Reader Announcements Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility Use a `role="status"` div with `aria-live="polite"` and `aria-atomic="true"` to provide real-time announcements for time changes, AM/PM selection, and other updates to screen readers. ```html 1 2
10 11 12
13 14 ``` -------------------------------- ### Register and Use Wheel Plugin (Full and Compact Modes) Source: https://timepicker-ui.vercel.app/docs/features/plugins Replaces the analog clock with a touch-friendly scroll-spinner. Supports 'wheel' mode with a header or 'compact-wheel' mode as a headerless popover. Configure placement and auto-commit on scroll. ```javascript import { TimepickerUI, PluginRegistry } from 'timepicker-ui'; import { WheelPlugin } from 'timepicker-ui/plugins/wheel'; import 'timepicker-ui/main.css'; PluginRegistry.register(WheelPlugin); // Full wheel mode (with header) const picker = new TimepickerUI(input, { ui: { mode: 'wheel' } }); picker.create(); // Compact-wheel popover (headerless, anchored to input) const popoverPicker = new TimepickerUI(input2, { ui: { mode: 'compact-wheel' }, wheel: { placement: 'auto', // 'auto', 'top', or 'bottom' commitOnScroll: true, // auto-confirm on scroll stop ignoreOutsideClick: false } }); popoverPicker.create(); ``` -------------------------------- ### Keyboard Navigation Testing with @testing-library Source: https://timepicker-ui.vercel.app/docs/advanced/accessibility Tests keyboard interactions for navigating and interacting with the timepicker component. Ensures that users can open the picker, trigger actions with Enter, and navigate options using arrow keys. ```javascript import { render, screen } from '@testing-library/react'; import userEvent from '@testing-library/user-event'; test('can navigate with keyboard', async () => { const user = userEvent.setup(); render(); const input = screen.getByRole('textbox'); await user.click(input); await user.keyboard('{Enter}'); // Verify modal opened expect(screen.getByRole('dialog')).toBeInTheDocument(); // Test arrow key navigation await user.keyboard('{ArrowUp}'); await user.keyboard('{Enter}'); }); ``` -------------------------------- ### Configure Inline Timepicker with Disabled Hours and Minutes Source: https://timepicker-ui.vercel.app/docs/features/inline-mode This example demonstrates how to restrict time selection in an inline timepicker by disabling specific hours (0-5 and 22-23) and minutes (15, 30, 45). ```typescript const picker = new TimepickerUI(input, { ui: { enableSwitchIcon: false }, clock: { disabledTime: { hours: [0, 1, 2, 3, 4, 5, 22, 23], minutes: [15, 30, 45] } } }); picker.create(); ``` -------------------------------- ### Get and Set Timepicker Values Source: https://timepicker-ui.vercel.app/docs/legacy-migration Shows how to programmatically retrieve the current time value from a Timepicker UI instance and how to set a new time value, including support for different time formats. ```javascript const picker = new TimepickerUI('#input'); const currentTime = picker.getValue(); console.log(currentTime); // "14:30" picker.setValue('09:15'); picker.setValue('3:45 PM'); ``` -------------------------------- ### Basic TypeScript Initialization Source: https://timepicker-ui.vercel.app/docs/api/typescript Initialize Timepicker UI with custom options for theme, clock type, and confirmation callbacks. Ensure the target input element exists in the DOM. ```typescript import { TimepickerUI } from 'timepicker-ui'; import type { TimepickerOptions, ConfirmEventData } from 'timepicker-ui'; const options: TimepickerOptions = { ui: { theme: 'dark' }, clock: { type: '24h' }, callbacks: { onConfirm: (data: ConfirmEventData) => { console.log(`Time: ${data.hour}:${data.minutes}`); } } }; const input = document.querySelector('#timepicker'); if (input) { const picker = new TimepickerUI(input, options); picker.create(); } ``` -------------------------------- ### Dynamic Theme Switching Source: https://timepicker-ui.vercel.app/docs/features/themes Change themes at runtime using the `update` method. Ensure `create: true` is set to re-render the picker with the new theme. ```typescript // Initialize with basic theme const picker = new TimepickerUI(input, { ui: { theme: 'basic' } }); picker.create(); // Switch to dark theme picker.update({ options: { ui: { theme: 'dark' } }, create: true }); // Switch to cyberpunk theme picker.update({ options: { ui: { theme: 'cyberpunk' } }, create: true }); ``` -------------------------------- ### Configure Wheel Mode Source: https://timepicker-ui.vercel.app/docs/api/options Set the UI mode to 'wheel' or 'compact-wheel'. Configures popover placement, hides the footer, and enables committing values on scroll end. ```typescript const picker = new TimepickerUI(input, { ui: { mode: 'wheel' }, wheel: { placement: 'bottom', // Popover placement (compact-wheel only) hideFooter: true, // Hide OK/Cancel footer commitOnScroll: true // Commit value on scroll end } }); ``` -------------------------------- ### Clock Options Source: https://timepicker-ui.vercel.app/docs/api/options Configure the behavior and time settings of the clock interface. ```APIDOC ## Clock Options Clock behavior and time configuration options: | Option | Type | Default | Description | |---|---|---|---| | `type` | "12h" | "12h" | Clock format type | | `incrementHours` | number | 1 | Hour increment step (1, 2, 3, etc.) | | `incrementMinutes` | number | 1 | Minute increment step (1, 5, 10, 15, etc.) | | `autoSwitchToMinutes` | boolean | true | Auto-switch to minutes after hour selection | | `disabledTime` | DisabledTime | undefined | Disable specific hours, minutes, or intervals | | `smoothHourSnap` | boolean | true | Enable smooth hour dragging with snap animation | | `currentTime` | CurrentTime | undefined | Set current time configuration | ``` -------------------------------- ### Import Base and Specific Theme Source: https://timepicker-ui.vercel.app/docs/features/themes Import the base styles along with a specific theme's CSS file. This is the recommended approach for reducing bundle size while using a custom theme. ```typescript import 'timepicker-ui/main.css'; import 'timepicker-ui/theme-cyberpunk.css'; ``` -------------------------------- ### Using Language Configs with Timepicker UI Source: https://timepicker-ui.vercel.app/docs/advanced/localization Demonstrates how to use a pre-defined language configuration object (Spanish in this case) when initializing Timepicker UI. This approach promotes code reusability and consistency. Ensure the 'input' element is defined and the locale file is correctly imported. ```typescript import TimepickerUI from 'timepicker-ui'; import { esLocale } from './locales/es'; const picker = new TimepickerUI(input, { ...esLocale, clock: { type: '24h' } }); picker.create(); ``` -------------------------------- ### Use Timepicker-UI via CDN Source: https://timepicker-ui.vercel.app/docs/installation For rapid prototyping, include the Timepicker-UI CSS and JavaScript from a CDN. The UMD build exposes the TimepickerUI class globally. ```html ``` -------------------------------- ### TimepickerUI.getAllInstances() Source: https://timepicker-ui.vercel.app/docs/api/methods Retrieves all currently active TimepickerUI instances. ```APIDOC ## `TimepickerUI.getAllInstances()` ### Description Get all currently active TimepickerUI instances. ### Method `TimepickerUI.getAllInstances()` ### Example ```typescript const allPickers = TimepickerUI.getAllInstances(); console.log(allPickers.length); ``` ``` -------------------------------- ### Timepicker UI Options Structure Update Source: https://timepicker-ui.vercel.app/docs/changelog Demonstrates the change in the options structure from a flat format in v3.x to a grouped format in v4.0.0. This reorganization improves clarity and maintainability of configurations. ```javascript // v3.x (flat - DEPRECATED): { - clockType: '24h', - theme: 'dark', - animation: true, - amLabel: 'AM', - onConfirm: (data) => {} -} // v4.0.0 (grouped - NEW): { + clock: { + type: '24h' + }, + ui: { + theme: 'dark', + animation: true + }, + labels: { + am: 'AM' + }, + callbacks: { + onConfirm: (data) => {} + } } ``` -------------------------------- ### Touch-Friendly Input Configuration Source: https://timepicker-ui.vercel.app/docs/features/mobile Configure an input element for touch interaction by setting `inputmode="none"` and `readonly` to prevent the native keyboard and typing. ```html ``` -------------------------------- ### Configure 24-hour Format Source: https://timepicker-ui.vercel.app/docs/advanced/localization Use this configuration for regions that use the 24-hour time format, such as Europe and Asia. Custom labels for OK and Cancel are included. ```typescript const picker = new TimepickerUI(input, { clock: { type: '24h' }, labels: { ok: 'OK', cancel: 'Annuler' } // No am/pm labels needed for 24h format }); ```