Accessibility

1const picker = new TimepickerUI(input, {
2  // Keyboard navigation is enabled by default
3  // All interactive elements are focusable
4});
5
6picker.create();
7
8// Arrow keys work on the time fields and on the clock face
9// - Hour/minute/second fields: Up/Down step by 1 hour, or by
10//   clock.incrementMinutes / clock.incrementSeconds
11// - Clock face: Up/Right and Down/Left step the active face the same way
12// - Disabled times are automatically skipped
13
14// AM and PM are buttons: Tab to one and press Enter or Space

1const picker = new TimepickerUI(input, {
2  labels: {
3    // Visible button text (also announced by screen readers)
4    ok: 'Confirm',
5    cancel: 'Cancel',
6
7    // Accessible names for the picker controls
8    clock: 'Clock',
9    period: 'Period',
10    timeFields: 'Select appointment time',
11
12    // Field caption, accessible name and announcement prefix in one key
13    hour: 'Hour',
14    minute: 'Minute'
15  }
16});
17
18// Add a custom aria-label / hint directly on the input element
19<input
20  type="text"
21  id="timepicker"
22  aria-label="Select appointment time"
23  aria-describedby="time-help"
24/>
25<span id="time-help" class="sr-only">
26  Press Enter or Space to open the time picker.
27</span>

1<!-- Live region for screen reader announcements -->
2<!-- Rendered as the last child of .tp-ui-modal; sr-only hides it visually -->
3<div
4  class="timepicker-announcer sr-only"
5  role="status"
6  aria-live="polite"
7  aria-atomic="true"
8>
9  <!-- Dynamically updated by the timepicker -->
10  <!-- Announces: "Hour: 14", "Minute: 30", etc. -->
11</div>
12
13<script>
14// Timepicker automatically announces changes via live region
15// No manual setup required
16
17// Example announcements with the default labels:
18// - "Hour: 14"
19// - "Minute: 30"   (said "Minutes: 30" before 4.7.0)
20// - "Second: 15"
21// - "AM selected"
22// - "PM selected"
23// - "Time cleared"
24
25// Live region updates happen on:
26// - Clock hand drag
27// - Clock number click
28// - Arrow keys, Home/End and PageUp/PageDown on the time fields
29// - Enter/Space on the clock face (announces the new face and its value)
30// - Wheel column scroll (wheel and compact-wheel modes)
31// - AM/PM toggle
32// - Clear
33
34// Arrow steps on the focused clock face are not announced here: the
35// clock face is a slider, so the screen reader reads its new value itself
36</script>

1<label for="meeting-time" class="form-label">
2  Meeting Time
3  <span class="text-muted">(Required)</span>
4</label>
5<input
6  type="text"
7  id="meeting-time"
8  required
9  aria-required="true"
10  aria-describedby="meeting-time-hint"
11/>
12<div id="meeting-time-hint" class="form-hint">
13  Select a time between 9:00 AM and 5:00 PM
14</div>

1.tp-ui-wrapper {
2  --tp-size-hand-circle: 48px;
3
4  --tp-size-input-height: 96px;
5  --tp-size-am-pm-height: 48px;
6  --tp-size-am-pm-height-landscape: 48px;
7}

1// Focus is automatically trapped within the modal
2// Users cannot tab outside the timepicker when open
3
4const picker = new TimepickerUI(input, {
5  behavior: {
6    // Modal automatically manages focus
7    focusTrap: true, // Default behavior
8    returnFocus: true // Recommended, default: false (true in 5.0)
9  }
10});
11
12picker.create();
13
14// When modal opens:
15// 1. Focus moves to the wrapper element
16// 2. Tab cycles through all focusable elements in order:
17//    - Hour input
18//    - Minute input
19//    - Second input (when clock.showSeconds is true)
20//    - AM/PM radio group, one stop on the checked one (in 12h mode)
21//    - Clock face (one Tab stop for the whole dial)
22//    - Cancel button
23//    - OK button
24// 3. Shift+Tab cycles backwards
25// 4. When last element is focused and Tab is pressed, focus returns to first element
26// 5. Cannot tab to elements behind modal
27
28// When modal closes:
29// - Focus returns to the input field that triggered the modal
30//   when behavior.returnFocus is true (default: false)
31
32// Note: The numbers on the clock face are not in the Tab order. The clock
33// face itself works like a slider: the arrow keys change the active value.

1/* Built-in focus ring (simplified) */
2.tp-ui-ok-btn:focus-visible,
3.tp-ui-cancel-btn:focus-visible,
4.tp-ui-clear-btn:focus-visible,
5.tp-ui-keyboard-icon:focus-visible {
6  outline: 3px solid var(--tp-focus-ring, var(--tp-primary));
7  outline-offset: 2px;
8  box-shadow: var(--tp-shadow-focus-ring, none);
9}
10
11/* AM/PM, the time fields and the clock face draw the ring inside their edge */
12.tp-ui-hour:focus-visible,
13.tp-ui-minutes:focus-visible,
14.tp-ui-seconds:focus-visible,
15.tp-ui-am:focus-visible,
16.tp-ui-pm:focus-visible,
17.tp-ui-clock-face:focus-visible {
18  outline-offset: -3px;
19}
20
21/* Thicker ring when the user asks for more contrast */
22@media (prefers-contrast: more) {
23  .tp-ui-ok-btn:focus-visible,
24  .tp-ui-cancel-btn:focus-visible {
25    outline-width: 4px;
26  }
27}
28
29/* The ring shows only for keyboard focus, not after a mouse click or tap */
30/* Set --tp-focus-ring to change its color */

1// Disabled times are properly marked and skipped
2
3// Lists: disable specific hours / minutes
4const picker = new TimepickerUI(input, {
5  clock: {
6    type: '24h',
7    disabledTime: {
8      hours: [0, 1, 2],
9      minutes: [15, 45]
10    }
11  }
12});
13
14// Ranges: disable one or more time ranges (string or array of strings).
15// When ranges is set, the hours, minutes and seconds lists are ignored
16const rangesPicker = new TimepickerUI(input, {
17  clock: {
18    disabledTime: {
19      ranges: ['9:00 AM - 12:00 PM', '6:00 PM - 11:59 PM']
20    }
21  }
22});
23
24// On the clock face, disabled numbers:
25// - are dimmed and can't be picked by click or drag
26// - are skipped by the arrow keys, Home/End and PageUp/PageDown
27// - have no aria-disabled, because the numbers are aria-hidden and not
28//   focusable (the clock face itself is the focusable slider)
29
30// In wheel and compact-wheel modes, disabled items get aria-disabled="true",
31// or are left out with wheel.hideDisabled: true
32
33// OK gets aria-disabled="true" while the shown time is disabled
34
35// The keyboard skips disabled values in the time fields too
36// If the ranges cover every minute of an hour, that hour is also skipped

1/* High contrast accessible override (CSS variables use the --tp- prefix) */
2.tp-ui-modal[data-theme="dark"] {
3  --tp-bg: #000000;
4  --tp-text: #ffffff;
5  --tp-primary: #ffff00;
6  --tp-border: #ffffff;
7
8  /* Ensure all text meets 7:1 contrast ratio */
9}
10
11/* Respect user's contrast preference */
12@media (prefers-contrast: more) {
13  .tp-ui-wrapper {
14    border: 2px solid currentColor;
15  }
16
17  .tp-ui-clock-face {
18    border: 2px solid currentColor;
19  }
20}
21
22@media (prefers-contrast: more) {
23  /* Higher contrast for users who ask for it */
24  .tp-ui-wrapper {
25    background: #000000;
26    color: #ffffff;
27  }
28}

1/* CSS: Respect prefers-reduced-motion */
2@media (prefers-reduced-motion: reduce) {
3  .tp-ui-wrapper {
4    animation: none !important;
5    transition: none !important;
6  }
7
8  .tp-ui-clock-hand {
9    transition: none !important;
10  }
11
12  .tp-ui-modal {
13    animation: none !important;
14  }
15}
16
17// JavaScript: Detect user preference
18const prefersReducedMotion = window.matchMedia(
19  '(prefers-reduced-motion: reduce)'
20).matches;
21
22const picker = new TimepickerUI(input, {
23  ui: {
24    animation: !prefersReducedMotion
25  }
26});
27
28picker.create();

1// Using axe-core for accessibility testing
2import { axe } from 'jest-axe';
3
4test('timepicker should have no accessibility violations', async () => {
5  const { container } = render(
6    <TimepickerComponent />
7  );
8
9  const results = await axe(container);
10  expect(results).toHaveNoViolations();
11});
12
13// Using @testing-library for keyboard testing
14import { render, screen } from '@testing-library/react';
15import userEvent from '@testing-library/user-event';
16
17test('can navigate with keyboard', async () => {
18  const user = userEvent.setup();
19  render(<TimepickerComponent />);
20
21  const input = screen.getByRole('textbox');
22  await user.click(input);
23  await user.keyboard('{Enter}');
24
25  // Verify modal opened
26  expect(screen.getByRole('dialog')).toBeInTheDocument();
27
28  // Test arrow key navigation
29  await user.keyboard('{ArrowUp}');
30  await user.keyboard('{Enter}');
31});