@toptal/picasso-timepicker 100.0.3 → 100.1.0

package/src/TimePicker/use-time-picker-popover.ts

@@ -0,0 +1,120 @@
+import type React from 'react'
+import { useEffect, useRef, useState } from 'react'
+
+import type { HourCycle } from './utils'
+
+interface Options {
+  enabled: boolean
+  getHourCycle: () => HourCycle
+}
+
+// The shortcuts a browser uses to open the native time picker
+const isOpenShortcut = (event: React.KeyboardEvent) =>
+  event.key === ' ' || (event.key === 'ArrowDown' && event.altKey)
+
+export const useTimePickerPopover = ({ enabled, getHourCycle }: Options) => {
+  const [isOpen, setIsOpen] = useState(false)
+  const [focusList, setFocusList] = useState(false)
+  const [hourCycle, setHourCycle] = useState<HourCycle>(24)
+  const anchorRef = useRef<HTMLElement>(null)
+  const listRef = useRef<HTMLDivElement>(null)
+
+  const focusField = () =>
+    anchorRef.current
+      ?.querySelector<HTMLInputElement>('input:not([readonly])')
+      ?.focus()
+
+  const open = ({ focusList: shouldFocusList }: { focusList: boolean }) => {
+    setFocusList(shouldFocusList)
+    setHourCycle(getHourCycle())
+    setIsOpen(true)
+  }
+
+  const close = () => setIsOpen(false)
+
+  useEffect(() => {
+    if (!enabled) {
+      close()
+    }
+  }, [enabled])
+
+  const closeAndFocusField = () => {
+    close()
+    focusField()
+  }
+
+  const handleTriggerClick = () => {
+    if (isOpen) {
+      closeAndFocusField()
+
+      return
+    }
+
+    open({ focusList: false })
+    focusField()
+  }
+
+  const handleClickAway = (event: React.MouseEvent) => {
+    if (!anchorRef.current?.contains(event.target as Node)) {
+      close()
+    }
+  }
+
+  const isFocusChangeWithinList = (event: React.FocusEvent) =>
+    event.relatedTarget instanceof Node &&
+    Boolean(listRef.current?.contains(event.relatedTarget))
+
+  const handleFieldFocus = () => {
+    // Focus is back in the field, so the next shortcut must be able to move it
+    // into the list again
+    setFocusList(false)
+  }
+
+  const handleFieldKeyDown = (event: React.KeyboardEvent<HTMLInputElement>) => {
+    if (!isOpen) {
+      if (enabled && isOpenShortcut(event)) {
+        event.preventDefault()
+        open({ focusList: true })
+      }
+
+      return
+    }
+
+    if (isOpenShortcut(event)) {
+      // Keeps the browser from opening its own time picker over the list
+      event.preventDefault()
+      setFocusList(true)
+
+      return
+    }
+
+    switch (event.key) {
+      case 'Escape':
+        // Keeps a surrounding Modal or Drawer open while the list closes
+        event.stopPropagation()
+        close()
+        break
+      case 'Enter':
+        event.preventDefault()
+        close()
+        break
+      case 'Tab':
+        close()
+        break
+    }
+  }
+
+  return {
+    isOpen,
+    hourCycle,
+    anchorRef,
+    listRef,
+    focusList,
+    isFocusChangeWithinList,
+    handleTriggerClick,
+    handleClickAway,
+    closeAndFocusField,
+    handleFieldFocus,
+    handleFieldKeyDown,
+  }
+}

package/src/TimePicker/utils/get-hour-cycle.test.ts

@@ -0,0 +1,76 @@
+import { getHourCycle } from './get-hour-cycle'
+
+const PROBE_HEIGHT = 100
+
+const mockNativeFieldLayout = (renderedSegments: string[]) => {
+  const appendChild = document.body.appendChild.bind(document.body)
+
+  jest.spyOn(document.body, 'appendChild').mockImplementation(node => {
+    if (node instanceof HTMLElement) {
+      const testId = node.getAttribute('data-testid')
+      const isStretched = renderedSegments.some(
+        segment => testId === `time-picker-probe-${segment}`
+      )
+
+      Object.defineProperty(node, 'offsetHeight', {
+        value: isStretched ? PROBE_HEIGHT : 17,
+      })
+    }
+
+    return appendChild(node)
+  })
+}
+
+describe('getHourCycle', () => {
+  afterEach(() => {
+    jest.restoreAllMocks()
+  })
+
+  describe('when the native time field renders an AM/PM segment', () => {
+    beforeEach(() => {
+      mockNativeFieldLayout(['hour', 'ampm'])
+    })
+
+    it('leaves no probe elements in the document', () => {
+      getHourCycle('de-DE')
+
+      expect(document.querySelector('input')).not.toBeInTheDocument()
+    })
+
+    describe('when the locale uses a 24-hour clock', () => {
+      it('returns 12', () => {
+        expect(getHourCycle('de-DE')).toBe(12)
+      })
+    })
+  })
+
+  describe('when the native time field renders no AM/PM segment', () => {
+    beforeEach(() => {
+      mockNativeFieldLayout(['hour'])
+    })
+
+    describe('when the locale uses a 12-hour clock', () => {
+      it('returns 24', () => {
+        expect(getHourCycle('en-US')).toBe(24)
+      })
+    })
+  })
+
+  describe('when the browser does not expose the segments of the native field', () => {
+    beforeEach(() => {
+      mockNativeFieldLayout([])
+    })
+
+    describe('when the locale uses a 12-hour clock', () => {
+      it('returns 12', () => {
+        expect(getHourCycle('en-US')).toBe(12)
+      })
+    })
+
+    describe('when the locale uses a 24-hour clock', () => {
+      it('returns 24', () => {
+        expect(getHourCycle('de-DE')).toBe(24)
+      })
+    })
+  })
+})

package/src/TimePicker/utils/get-hour-cycle.ts

@@ -0,0 +1,63 @@
+export type HourCycle = 12 | 24
+
+type Segment = 'hour' | 'ampm'
+
+const PROBE_CLASS_NAME =
+  'fixed top-0 left-0 invisible pointer-events-none h-auto p-0 border-0'
+
+// Blink calls the AM/PM segment `ampm-field`, WebKit calls it `meridiem-field`
+const SEGMENT_CLASS_NAMES: Record<Segment, string> = {
+  hour: '[&::-webkit-datetime-edit-hour-field]:inline-block [&::-webkit-datetime-edit-hour-field]:h-screen',
+  ampm: '[&::-webkit-datetime-edit-ampm-field]:inline-block [&::-webkit-datetime-edit-ampm-field]:h-screen [&::-webkit-datetime-edit-meridiem-field]:inline-block [&::-webkit-datetime-edit-meridiem-field]:h-screen',
+}
+
+const measureProbe = (segment?: Segment) => {
+  const probe = document.createElement('input')
+
+  probe.type = 'time'
+  probe.tabIndex = -1
+  probe.setAttribute('aria-hidden', 'true')
+  probe.className = PROBE_CLASS_NAME
+
+  if (segment) {
+    probe.className += ` ${SEGMENT_CLASS_NAMES[segment]}`
+    probe.setAttribute('data-testid', `time-picker-probe-${segment}`)
+  }
+
+  document.body.appendChild(probe)
+
+  const height = probe.offsetHeight
+
+  probe.remove()
+
+  return height
+}
+
+// The native field follows the operating system's 12/24-hour setting, which
+// `Intl` does not see, so the field itself is the only reliable source
+const getNativeFieldHourCycle = (): HourCycle | undefined => {
+  if (typeof document === 'undefined') {
+    return undefined
+  }
+
+  const stretchedHeight = measureProbe() * 2
+  const rendersSegment = (segment: Segment) =>
+    measureProbe(segment) > stretchedHeight
+
+  if (!rendersSegment('hour')) {
+    return undefined
+  }
+
+  return rendersSegment('ampm') ? 12 : 24
+}
+
+const getLocaleHourCycle = (locale?: string): HourCycle => {
+  const { hour12 } = new Intl.DateTimeFormat(locale, {
+    hour: 'numeric',
+  }).resolvedOptions()
+
+  return hour12 ? 12 : 24
+}
+
+export const getHourCycle = (locale?: string): HourCycle =>
+  getNativeFieldHourCycle() ?? getLocaleHourCycle(locale)

package/src/TimePicker/utils/index.ts

@@ -0,0 +1,10 @@
+export { getHourCycle } from './get-hour-cycle'
+export type { HourCycle } from './get-hour-cycle'
+export {
+  VALID_TIME_REGEX,
+  getCurrentTime,
+  getNearestOptionIndex,
+  getTimeOptions,
+  parseTime,
+} from './time'
+export type { Time, TimeOption } from './time'

package/src/TimePicker/utils/time.test.ts

@@ -0,0 +1,143 @@
+import {
+  VALID_TIME_REGEX,
+  formatTime,
+  getCurrentTime,
+  getNearestOptionIndex,
+  getTimeOptions,
+  parseTime,
+} from './time'
+
+describe('VALID_TIME_REGEX', () => {
+  it.each(['00:00', '09:05', '12:30', '19:59', '23:59'])(
+    'accepts %s',
+    value => {
+      expect(VALID_TIME_REGEX.test(value)).toBe(true)
+    }
+  )
+
+  it.each([
+    ['24:00', 'the hour is out of range'],
+    ['12:60', 'the minute is out of range'],
+    ['9:30', 'the hour is not padded'],
+    ['12:3', 'the minute is not padded'],
+    ['12:30:00', 'seconds are included'],
+    ['12.30', 'the separator is not a colon'],
+    [' 12:30', 'there is surrounding whitespace'],
+    ['', 'the value is empty'],
+  ])('rejects "%s" because %s', value => {
+    expect(VALID_TIME_REGEX.test(value)).toBe(false)
+  })
+})
+
+describe('parseTime', () => {
+  describe('when the value is a valid time', () => {
+    it('returns the hours and minutes as numbers', () => {
+      expect(parseTime('09:05')).toEqual({ hours: 9, minutes: 5 })
+      expect(parseTime('23:59')).toEqual({ hours: 23, minutes: 59 })
+    })
+  })
+
+  describe('when the value is not a valid time', () => {
+    it('returns undefined', () => {
+      expect(parseTime('24:00')).toBeUndefined()
+      expect(parseTime('9:05')).toBeUndefined()
+    })
+  })
+
+  describe('when the value is missing', () => {
+    it('returns undefined', () => {
+      expect(parseTime()).toBeUndefined()
+      expect(parseTime('')).toBeUndefined()
+    })
+  })
+})
+
+describe('formatTime', () => {
+  it('pads hours and minutes to two digits', () => {
+    expect(formatTime({ hours: 0, minutes: 0 })).toBe('00:00')
+    expect(formatTime({ hours: 9, minutes: 5 })).toBe('09:05')
+    expect(formatTime({ hours: 23, minutes: 59 })).toBe('23:59')
+  })
+})
+
+describe('getCurrentTime', () => {
+  beforeEach(() => {
+    jest.useFakeTimers().setSystemTime(new Date(2026, 0, 1, 14, 7))
+  })
+
+  afterEach(() => {
+    jest.useRealTimers()
+  })
+
+  it('returns the local hours and minutes of now', () => {
+    expect(getCurrentTime()).toEqual({ hours: 14, minutes: 7 })
+  })
+})
+
+describe('getTimeOptions', () => {
+  it('offers one option per step across the whole day', () => {
+    expect(getTimeOptions(60, 24)).toHaveLength(24)
+    expect(getTimeOptions(30, 24)).toHaveLength(48)
+    expect(getTimeOptions(15, 24)).toHaveLength(96)
+  })
+
+  it('keeps values in 24-hour HH:mm format regardless of the hour cycle', () => {
+    const values = (hourCycle: 12 | 24) =>
+      getTimeOptions(30, hourCycle).map(option => option.value)
+
+    expect(values(12)).toEqual(values(24))
+    expect(values(24).slice(0, 3)).toEqual(['00:00', '00:30', '01:00'])
+    expect(values(24).slice(-1)).toEqual(['23:30'])
+  })
+
+  describe('when the hour cycle is 24', () => {
+    it('labels the options with the 24-hour time', () => {
+      const labels = getTimeOptions(30, 24).map(option => option.label)
+
+      expect(labels).toContain('00:00')
+      expect(labels).toContain('12:30')
+      expect(labels).toContain('13:00')
+      expect(labels).toContain('23:30')
+      expect(labels.some(label => /AM|PM/.test(label))).toBe(false)
+    })
+  })
+
+  describe('when the hour cycle is 12', () => {
+    it('labels the options with a 12-hour time and a period', () => {
+      const labelOf = (value: string) =>
+        getTimeOptions(30, 12).find(option => option.value === value)?.label
+
+      expect(labelOf('00:00')).toBe('12:00 AM')
+      expect(labelOf('00:30')).toBe('12:30 AM')
+      expect(labelOf('01:00')).toBe('01:00 AM')
+      expect(labelOf('11:30')).toBe('11:30 AM')
+      expect(labelOf('12:00')).toBe('12:00 PM')
+      expect(labelOf('13:00')).toBe('01:00 PM')
+      expect(labelOf('23:30')).toBe('11:30 PM')
+    })
+  })
+})
+
+describe('getNearestOptionIndex', () => {
+  describe('when the time falls on an option', () => {
+    it('returns the index of that option', () => {
+      expect(getNearestOptionIndex({ hours: 0, minutes: 0 }, 15)).toBe(0)
+      expect(getNearestOptionIndex({ hours: 10, minutes: 0 }, 15)).toBe(40)
+      expect(getNearestOptionIndex({ hours: 23, minutes: 45 }, 15)).toBe(95)
+    })
+  })
+
+  describe('when the time falls between options', () => {
+    it('returns the index of the closest option', () => {
+      expect(getNearestOptionIndex({ hours: 10, minutes: 7 }, 15)).toBe(40)
+      expect(getNearestOptionIndex({ hours: 10, minutes: 8 }, 15)).toBe(41)
+    })
+  })
+
+  describe('when the time is closer to midnight than to the last option', () => {
+    it('returns the index of the last option', () => {
+      expect(getNearestOptionIndex({ hours: 23, minutes: 59 }, 15)).toBe(95)
+      expect(getNearestOptionIndex({ hours: 23, minutes: 50 }, 60)).toBe(23)
+    })
+  })
+})

package/src/TimePicker/utils/time.ts

@@ -0,0 +1,76 @@
+import type { HourCycle } from './get-hour-cycle'
+
+export interface Time {
+  hours: number
+  minutes: number
+}
+
+export interface TimeOption {
+  value: string
+  label: string
+}
+
+export const VALID_TIME_REGEX = /^([0-1][0-9]|2[0-3]):[0-5][0-9]$/
+
+const MINUTES_IN_HOUR = 60
+const MINUTES_IN_DAY = 24 * MINUTES_IN_HOUR
+const HALF_DAY = 12
+
+const padTimePart = (part: number) => String(part).padStart(2, '0')
+
+export const parseTime = (value?: string): Time | undefined => {
+  if (!value || !VALID_TIME_REGEX.test(value)) {
+    return undefined
+  }
+
+  const [hours, minutes] = value.split(':').map(Number)
+
+  return { hours, minutes }
+}
+
+export const formatTime = ({ hours, minutes }: Time) =>
+  `${padTimePart(hours)}:${padTimePart(minutes)}`
+
+export const getCurrentTime = (): Time => {
+  const now = new Date()
+
+  return { hours: now.getHours(), minutes: now.getMinutes() }
+}
+
+const formatLabel = (time: Time, hourCycle: HourCycle) => {
+  if (hourCycle === 24) {
+    return formatTime(time)
+  }
+
+  const hours = time.hours % HALF_DAY || HALF_DAY
+  const period = time.hours < HALF_DAY ? 'AM' : 'PM'
+
+  return `${formatTime({ hours, minutes: time.minutes })} ${period}`
+}
+
+export const getTimeOptions = (
+  minuteStep: number,
+  hourCycle: HourCycle
+): TimeOption[] => {
+  const options: TimeOption[] = []
+
+  for (let minutes = 0; minutes < MINUTES_IN_DAY; minutes += minuteStep) {
+    const time = {
+      hours: Math.floor(minutes / MINUTES_IN_HOUR),
+      minutes: minutes % MINUTES_IN_HOUR,
+    }
+
+    options.push({
+      value: formatTime(time),
+      label: formatLabel(time, hourCycle),
+    })
+  }
+
+  return options
+}
+
+export const getNearestOptionIndex = (time: Time, minuteStep: number) =>
+  Math.min(
+    Math.round((time.hours * MINUTES_IN_HOUR + time.minutes) / minuteStep),
+    Math.ceil(MINUTES_IN_DAY / minuteStep) - 1
+  )

package/src/TimePickerDropdown/TimePickerDropdown.tsx

@@ -0,0 +1,45 @@
+import React, { forwardRef } from 'react'
+import { Popper } from '@toptal/picasso-popper'
+import { ClickAwayListener } from '@toptal/picasso-utils'
+
+import { TimePickerList } from '../TimePickerList'
+import type { TimePickerListProps } from '../TimePickerList'
+
+export interface Props extends TimePickerListProps {
+  /** Whether the dropdown is shown */
+  open: boolean
+  /** Element the dropdown is positioned under */
+  anchorEl: HTMLElement | null
+  /** Called when a click lands outside of the dropdown */
+  onClickAway: (event: React.MouseEvent) => void
+}
+
+export const TimePickerDropdown = forwardRef<HTMLDivElement, Props>(
+  function TimePickerDropdown(
+    { open, anchorEl, onClickAway, ...rest }: Props,
+    ref
+  ): React.ReactElement | null {
+    if (!open || !anchorEl) {
+      return null
+    }
+
+    return (
+      <Popper
+        open
+        role='presentation'
+        anchorEl={anchorEl}
+        placement='bottom-start'
+      >
+        <ClickAwayListener onClickAway={onClickAway}>
+          <div ref={ref}>
+            <TimePickerList {...rest} />
+          </div>
+        </ClickAwayListener>
+      </Popper>
+    )
+  }
+)
+
+TimePickerDropdown.displayName = 'TimePickerDropdown'
+
+export default TimePickerDropdown

package/src/TimePickerDropdown/index.ts

@@ -0,0 +1 @@
+export { default as TimePickerDropdown } from './TimePickerDropdown'