@oslokommune/punkt-react 16.6.1 → 16.7.0

package/src/components/timepicker/Timepicker.test.tsx

@@ -0,0 +1,336 @@
+import '@testing-library/jest-dom'
+
+import { fireEvent, render, screen, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { useForm } from 'react-hook-form'
+import { axe, toHaveNoViolations } from 'jest-axe'
+import { vi } from 'vitest'
+
+import { PktButton } from '../button/Button'
+import { PktTimepicker } from './Timepicker'
+
+expect.extend(toHaveNoViolations)
+
+const id = 'test-timepicker'
+const label = 'Test Timepicker'
+
+describe('PktTimepicker', () => {
+  describe('Rendering', () => {
+    test('renders without errors', () => {
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} />)
+      expect(container.querySelector('.pkt-timepicker')).toBeInTheDocument()
+    })
+
+    test('renders spinbutton inputs and separator', () => {
+      render(<PktTimepicker id={id} name="t" label={label} />)
+      const spinbuttons = screen.getAllByRole('spinbutton')
+      expect(spinbuttons).toHaveLength(2)
+      expect(spinbuttons[0]).toHaveAttribute('id', `${id}-hours`)
+      expect(spinbuttons[1]).toHaveAttribute('id', `${id}-minutes`)
+    })
+
+    test('adds stepper modifier when stepArrows is set', () => {
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} stepArrows />,
+      )
+      expect(container.querySelector('.pkt-timepicker--stepper')).toBeInTheDocument()
+    })
+
+    test('adds fullwidth modifier when fullwidth is set', () => {
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} fullwidth />,
+      )
+      expect(container.querySelector('.pkt-timepicker--fullwidth')).toBeInTheDocument()
+    })
+
+    test('renders clock button when picker is visible', () => {
+      render(<PktTimepicker id={id} name="t" label={label} />)
+      expect(
+        screen.getByRole('button', { name: /åpne tidspunkt-velger/i }),
+      ).toBeInTheDocument()
+    })
+
+    test('hides clock button when hidePicker is set', () => {
+      render(<PktTimepicker id={id} name="t" label={label} hidePicker />)
+      expect(
+        screen.queryByRole('button', { name: /åpne tidspunkt-velger/i }),
+      ).not.toBeInTheDocument()
+    })
+
+    test('renders decorative clock icon when hidePicker is set', () => {
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} hidePicker />)
+      expect(container.querySelector('.pkt-timepicker__icon')).toBeInTheDocument()
+    })
+
+    test('does not render popup when hidePicker is set', () => {
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} hidePicker />)
+      expect(container.querySelector('.pkt-timepicker-popup')).not.toBeInTheDocument()
+    })
+
+    test('does not render popup when stepArrows is set', () => {
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} stepArrows />)
+      expect(container.querySelector('.pkt-timepicker-popup')).not.toBeInTheDocument()
+    })
+
+    test('renders prev/next buttons when stepArrows is set', () => {
+      render(<PktTimepicker id={id} name="t" label={label} stepArrows />)
+      expect(screen.getByRole('button', { name: /forrige tidspunkt/i })).toBeInTheDocument()
+      expect(screen.getByRole('button', { name: /neste tidspunkt/i })).toBeInTheDocument()
+    })
+
+    test('popup is hidden by default', () => {
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} />)
+      const popup = container.querySelector('.pkt-timepicker-popup')
+      expect(popup).toBeInTheDocument()
+      expect(popup).toHaveAttribute('hidden')
+    })
+  })
+
+  describe('Properties', () => {
+    test('value sets display inputs', () => {
+      render(<PktTimepicker id={id} name="t" label={label} value="09:30" />)
+      const spinbuttons = screen.getAllByRole('spinbutton')
+      expect(spinbuttons[0]).toHaveValue('09')
+      expect(spinbuttons[1]).toHaveValue('30')
+    })
+
+    test('empty value renders empty display inputs', () => {
+      render(<PktTimepicker id={id} name="t" label={label} />)
+      const spinbuttons = screen.getAllByRole('spinbutton')
+      expect(spinbuttons[0]).toHaveValue('')
+      expect(spinbuttons[1]).toHaveValue('')
+    })
+
+    test('disabled disables inputs and clock button', () => {
+      render(<PktTimepicker id={id} name="t" label={label} disabled />)
+      const spinbuttons = screen.getAllByRole('spinbutton')
+      expect(spinbuttons[0]).toBeDisabled()
+      expect(spinbuttons[1]).toBeDisabled()
+      expect(screen.getByRole('button', { name: /åpne tidspunkt-velger/i })).toBeDisabled()
+    })
+
+    test('min/max/step are not on hidden input (constraints use setCustomValidity on hours for native form validation)', () => {
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} min="08:00" max="17:00" step={300} />,
+      )
+      const hidden = container.querySelector<HTMLInputElement>(`#${id}-input`)
+      expect(hidden?.hasAttribute('min')).toBe(false)
+      expect(hidden?.hasAttribute('max')).toBe(false)
+      expect(hidden?.hasAttribute('step')).toBe(false)
+      expect(hidden?.hasAttribute('required')).toBe(false)
+    })
+
+    test('hidden input reflects value', () => {
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} value="09:30" />,
+      )
+      const hidden = container.querySelector<HTMLInputElement>(`#${id}-input`)
+      expect(hidden?.value).toBe('09:30')
+    })
+
+    test('native form submit flushes spinbutton digits into the named hidden input before validation', async () => {
+      const user = userEvent.setup()
+      const onSubmit = vi.fn()
+      render(
+        <form
+          onSubmit={(e) => {
+            e.preventDefault()
+            onSubmit(Object.fromEntries(new FormData(e.currentTarget).entries()))
+          }}
+        >
+          <PktTimepicker id={id} name="tid" label={label} required requiredTag />
+          <button type="submit">Send</button>
+        </form>,
+      )
+      const [hoursEl, minutesEl] = screen.getAllByRole('spinbutton')
+      await user.click(hoursEl)
+      await user.keyboard('01')
+      await user.click(minutesEl)
+      await user.keyboard('02')
+      await user.click(screen.getByRole('button', { name: /^send$/i }))
+      expect(onSubmit).toHaveBeenCalledWith({ tid: '01:02' })
+    })
+  })
+
+  describe('Popup', () => {
+    test('clock button opens popup', async () => {
+      const user = userEvent.setup()
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} />)
+      await user.click(screen.getByRole('button', { name: /åpne tidspunkt-velger/i }))
+      const popup = container.querySelector('.pkt-timepicker-popup')
+      expect(popup).not.toHaveAttribute('hidden')
+    })
+
+    test('Escape closes popup', async () => {
+      const user = userEvent.setup()
+      render(<PktTimepicker id={id} name="t" label={label} />)
+      const btn = screen.getByRole('button', { name: /åpne tidspunkt-velger/i })
+      await user.click(btn)
+      await waitFor(() => expect(btn).toHaveAttribute('aria-expanded', 'true'))
+      await user.keyboard('{Escape}')
+      await waitFor(() => expect(btn).toHaveAttribute('aria-expanded', 'false'))
+    })
+
+    test('popup renders hour and minute columns', async () => {
+      const user = userEvent.setup()
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} />)
+      await user.click(screen.getByRole('button', { name: /åpne tidspunkt-velger/i }))
+      const cols = container.querySelectorAll('.pkt-timepicker-popup__col')
+      expect(cols).toHaveLength(2)
+    })
+  })
+
+  describe('Stepper', () => {
+    test('next button increments by one minute step', async () => {
+      const user = userEvent.setup()
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} stepArrows defaultValue="09:00" />,
+      )
+      await user.click(screen.getByRole('button', { name: /neste tidspunkt/i }))
+      const hidden = container.querySelector<HTMLInputElement>(`#${id}-input`)
+      expect(hidden?.value).toBe('09:01')
+    })
+
+    test('prev button decrements by step (5 min)', async () => {
+      const user = userEvent.setup()
+      const { container } = render(
+        <PktTimepicker
+          id={id}
+          name="t"
+          label={label}
+          stepArrows
+          step={300}
+          defaultValue="09:05"
+        />,
+      )
+      await user.click(screen.getByRole('button', { name: /forrige tidspunkt/i }))
+      const hidden = container.querySelector<HTMLInputElement>(`#${id}-input`)
+      expect(hidden?.value).toBe('09:00')
+    })
+
+    test('next button at 59 minutes rolls over to next hour', async () => {
+      const user = userEvent.setup()
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} stepArrows defaultValue="09:59" />,
+      )
+      await user.click(screen.getByRole('button', { name: /neste tidspunkt/i }))
+      const hidden = container.querySelector<HTMLInputElement>(`#${id}-input`)
+      expect(hidden?.value).toBe('10:00')
+    })
+  })
+
+  describe('Events', () => {
+    test('onFocus fires when a spinbutton is focused (focus must bubble to root handler)', async () => {
+      const user = userEvent.setup()
+      const onFocus = vi.fn()
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} onFocus={onFocus} />,
+      )
+      const hoursInput = container.querySelector<HTMLInputElement>(`#${id}-hours`)!
+      await user.click(hoursInput)
+      expect(onFocus).toHaveBeenCalledTimes(1)
+    })
+
+    test('Backspace removes digits in hours and updates hidden value (controlled inputs)', async () => {
+      const user = userEvent.setup()
+      const { container } = render(
+        <PktTimepicker id={id} name="t" label={label} defaultValue="09:30" />,
+      )
+      const hoursInput = container.querySelector<HTMLInputElement>(`#${id}-hours`)!
+      const hidden = container.querySelector<HTMLInputElement>(`#${id}-input`)
+      hoursInput.focus()
+      await user.keyboard('{Backspace}')
+      expect(hoursInput).toHaveValue('0')
+      expect(hidden?.value).toBe('00:30')
+      await user.keyboard('{Backspace}')
+      expect(hoursInput).toHaveValue('')
+      expect(hidden?.value).toBe('')
+    })
+
+    test('onValueChange fires when hours change via ArrowUp', async () => {
+      const handleValueChange = vi.fn()
+      const { container } = render(
+        <PktTimepicker
+          id={id}
+          name="t"
+          label={label}
+          defaultValue="09:30"
+          onValueChange={handleValueChange}
+        />,
+      )
+      const hoursInput = container.querySelector<HTMLInputElement>(`#${id}-hours`)!
+      fireEvent.keyDown(hoursInput, { key: 'ArrowUp' })
+      await waitFor(() => {
+        expect(handleValueChange).toHaveBeenCalledWith('10:30')
+      })
+    })
+  })
+
+  describe('Accessibility', () => {
+    test('passes axe in default state', async () => {
+      const { container } = render(<PktTimepicker id={id} name="t" label={label} />)
+      await window.customElements.whenDefined('pkt-icon')
+      const results = await axe(container)
+      expect(results).toHaveNoViolations()
+    })
+
+    test('hours input has spinbutton role and bounds', () => {
+      render(<PktTimepicker id={id} name="t" label={label} value="09:30" />)
+      const hours = screen.getAllByRole('spinbutton')[0]
+      expect(hours).toHaveAttribute('role', 'spinbutton')
+      expect(hours).toHaveAttribute('aria-valuemin', '0')
+      expect(hours).toHaveAttribute('aria-valuemax', '23')
+      expect(hours).toHaveAttribute('aria-valuenow', '9')
+    })
+  })
+})
+
+describe('PktTimepicker + React Hook Form', () => {
+  function WatchForm() {
+    const { register, watch } = useForm<{ tid: string }>({
+      defaultValues: { tid: '09:30' },
+    })
+    const values = watch()
+    return (
+      <form>
+        <PktTimepicker id="tp-rhf-watch" label="Tid" {...register('tid')} />
+        <span data-testid="watched">{values.tid ?? ''}</span>
+      </form>
+    )
+  }
+
+  test('register() defaultValues are reflected in watch()', async () => {
+    render(<WatchForm />)
+    await waitFor(() => {
+      expect(screen.getByTestId('watched')).toHaveTextContent('09:30')
+    })
+  })
+
+  function SubmitForm({
+    onSubmit,
+  }: {
+    onSubmit: (data: { tid: string }) => void
+  }) {
+    const { register, handleSubmit } = useForm<{ tid: string }>({
+      defaultValues: { tid: '14:45' },
+    })
+    return (
+      <form onSubmit={handleSubmit(onSubmit)}>
+        <PktTimepicker id="tp-rhf-submit" label="Tid" {...register('tid')} />
+        <PktButton type="submit">Send</PktButton>
+      </form>
+    )
+  }
+
+  test('submit sends current time value from register()', async () => {
+    const user = userEvent.setup()
+    const onSubmit = vi.fn()
+    render(<SubmitForm onSubmit={onSubmit} />)
+
+    await user.click(screen.getByRole('button', { name: /send/i }))
+
+    await waitFor(() => {
+      expect(onSubmit).toHaveBeenCalledWith({ tid: '14:45' }, expect.anything())
+    })
+  })
+})

package/src/components/timepicker/Timepicker.tsx

@@ -0,0 +1,244 @@
+'use client'
+
+import { forwardRef } from 'react'
+
+import { PktIcon } from '../icon/Icon'
+import { PktInputWrapper } from '../inputwrapper/InputWrapper'
+import { useTimepickerState } from './useTimepickerState'
+import type { IPktTimepicker } from './types'
+
+export type { IPktTimepicker } from './types'
+
+export const PktTimepicker = forwardRef<HTMLDivElement, IPktTimepicker>((props, ref) => {
+  const { onChange, onInput } = props
+  const state = useTimepickerState(props, ref)
+
+  const hoursLabel = state.strings.hours
+  const minutesLabel = state.strings.minutes
+  const hoursAriaLabel = state.label ? `${hoursLabel}, ${state.label}` : hoursLabel
+  const minutesAriaLabel = state.label ? `${minutesLabel}, ${state.label}` : minutesLabel
+
+  const renderOption = (optionValue: number, type: 'hour' | 'minute') => {
+    const strVal = String(optionValue).padStart(2, '0')
+    const currentVal =
+      type === 'hour'
+        ? state.hours !== ''
+          ? parseInt(state.hours, 10)
+          : NaN
+        : state.minutes !== ''
+          ? parseInt(state.minutes, 10)
+          : NaN
+    const isSelected = optionValue === currentVal
+    return (
+      <button
+        key={`${type}-${optionValue}`}
+        type="button"
+        className={[
+          'pkt-btn',
+          'pkt-btn--tertiary',
+          'pkt-btn--small',
+          'pkt-btn--label-only',
+          'pkt-timepicker-popup__option',
+          isSelected ? 'pkt-timepicker-popup__option--selected' : '',
+        ]
+          .filter(Boolean)
+          .join(' ')}
+        role="option"
+        aria-selected={isSelected ? 'true' : 'false'}
+        tabIndex={isSelected ? 0 : -1}
+        data-type={type}
+        data-value={optionValue}
+        onClick={(e) => {
+          e.stopPropagation()
+          state.handleOptionClick(optionValue, type)
+        }}
+      >
+        <span className="pkt-btn__text pkt-txt-14-light">{strVal}</span>
+      </button>
+    )
+  }
+
+  const renderPopup = () => (
+    <div
+      ref={state.popupRef}
+      className="pkt-timepicker-popup"
+      id={state.popupId}
+      hidden={!state.isOpen}
+      role="group"
+      aria-label={state.strings.selectTime}
+      onKeyDown={state.handlePopupKeydown}
+      onBlur={state.handlePopupFocusOut}
+    >
+      <div className="pkt-timepicker-popup__col" role="listbox" aria-label={hoursLabel} aria-orientation="vertical">
+        {state.hourOptions.map((h) => renderOption(h, 'hour'))}
+      </div>
+      <div className="pkt-timepicker-popup__col" role="listbox" aria-label={minutesLabel} aria-orientation="vertical">
+        {state.minuteOptions.map((m) => renderOption(m, 'minute'))}
+      </div>
+    </div>
+  )
+
+  const renderContainer = () => (
+    <div className="pkt-input__container">
+      {state.stepArrows && (
+        <button
+          type="button"
+          className="pkt-input-icon pkt-btn pkt-btn--icon-only pkt-btn--tertiary pkt-timepicker__button pkt-timepicker__button--prev"
+          aria-label={state.strings.prevTime}
+          disabled={state.disabled}
+          onClick={() => state.stepTimeDelta(-1)}
+        >
+          <PktIcon name="chevron-thin-left" />
+          <span className="pkt-btn__text">{state.strings.prevTime}</span>
+        </button>
+      )}
+      <input
+        ref={state.hoursInputRef}
+        type="text"
+        inputMode="numeric"
+        maxLength={2}
+        size={2}
+        className="pkt-input pkt-timepicker__input"
+        id={state.hoursId}
+        data-min="0"
+        data-max="23"
+        value={state.hours}
+        placeholder="––"
+        aria-label={hoursAriaLabel}
+        role="spinbutton"
+        aria-invalid={state.hasError || state.isInvalid || undefined}
+        aria-valuemin={0}
+        aria-valuemax={23}
+        aria-valuenow={state.hours !== '' ? parseInt(state.hours, 10) : undefined}
+        aria-valuetext={state.hours !== '' ? `${state.hours} ${hoursLabel.toLowerCase()}` : undefined}
+        autoComplete="off"
+        disabled={state.disabled}
+        onKeyDown={state.handleHoursKeydown}
+        onBlur={state.handleHoursBlur}
+        onFocus={(e) => {
+          e.currentTarget.select()
+        }}
+        onChange={() => {
+          /* value is driven by keydown handlers */
+        }}
+        onPaste={(e) => e.preventDefault()}
+      />
+      <span className="pkt-timepicker__separator">:</span>
+      <input
+        ref={state.minutesInputRef}
+        type="text"
+        inputMode="numeric"
+        maxLength={2}
+        size={2}
+        className="pkt-input pkt-timepicker__input"
+        id={state.minutesId}
+        data-min="0"
+        data-max="59"
+        value={state.minutes}
+        placeholder="––"
+        aria-label={minutesAriaLabel}
+        role="spinbutton"
+        aria-invalid={state.hasError || state.isInvalid || undefined}
+        aria-valuemin={0}
+        aria-valuemax={59}
+        aria-valuenow={state.minutes !== '' ? parseInt(state.minutes, 10) : undefined}
+        aria-valuetext={state.minutes !== '' ? `${state.minutes} ${minutesLabel.toLowerCase()}` : undefined}
+        autoComplete="off"
+        disabled={state.disabled}
+        onKeyDown={state.handleMinutesKeydown}
+        onBlur={state.handleMinutesBlur}
+        onFocus={(e) => {
+          e.currentTarget.select()
+        }}
+        onChange={() => {
+          /* value is driven by keydown handlers */
+        }}
+        onPaste={(e) => e.preventDefault()}
+      />
+      {state.hidePicker && !state.stepArrows && (
+        <PktIcon className="pkt-input-icon pkt-timepicker__icon" name="clock" aria-hidden={true} />
+      )}
+      {!state.hidePicker && !state.stepArrows && (
+        <button
+          ref={state.buttonRef}
+          type="button"
+          className="pkt-input-icon pkt-btn pkt-btn--icon-only pkt-btn--tertiary pkt-timepicker__button"
+          aria-label={state.strings.openPicker}
+          aria-haspopup="listbox"
+          aria-expanded={state.isOpen}
+          aria-controls={state.popupId}
+          disabled={state.disabled}
+          onClick={state.handleClockButtonClick}
+        >
+          <PktIcon name="clock" />
+          <span className="pkt-btn__text">{state.strings.openPicker}</span>
+        </button>
+      )}
+      {state.stepArrows && (
+        <button
+          type="button"
+          className="pkt-input-icon pkt-btn pkt-btn--icon-only pkt-btn--tertiary pkt-timepicker__button pkt-timepicker__button--next"
+          aria-label={state.strings.nextTime}
+          disabled={state.disabled}
+          onClick={() => state.stepTimeDelta(1)}
+        >
+          <PktIcon name="chevron-thin-right" />
+          <span className="pkt-btn__text">{state.strings.nextTime}</span>
+        </button>
+      )}
+      {/* Native constraints are reported on the hours spinbutton (setCustomValidity), not here — avoids
+          "invalid form control is not focusable" for this hidden type="time" input. */}
+      <input
+        ref={state.changeInputRef}
+        type="time"
+        hidden
+        name={state.name}
+        id={state.hiddenInputId}
+        disabled={state.disabled}
+        tabIndex={-1}
+        aria-hidden={true}
+        onChange={onChange}
+        onInput={onInput}
+      />
+    </div>
+  )
+
+  return (
+    <div
+      ref={state.containerRef}
+      className={state.outerClasses}
+      onFocus={state.handleFocusIn}
+      onBlur={state.handleFocusOut}
+    >
+      <PktInputWrapper
+        forId={state.hoursId}
+        label={state.label}
+        disabled={state.disabled}
+        hasError={state.hasError}
+        inline={state.inline}
+        optionalTag={state.optionalTag}
+        optionalText={state.optionalText}
+        requiredTag={state.requiredTag}
+        requiredText={state.requiredText}
+        useWrapper={state.useWrapper}
+        ariaDescribedby={state.ariaDescribedby}
+        errorMessage={state.errorMessage}
+        helptext={state.helptext}
+        helptextDropdown={state.helptextDropdown}
+        helptextDropdownButton={state.helptextDropdownButton}
+        tagText={state.tagText}
+      >
+        {!state.hidePicker && !state.stepArrows ? (
+          <div className="pkt-timepicker__anchor">
+            {renderContainer()}
+            {renderPopup()}
+          </div>
+        ) : (
+          renderContainer()
+        )}
+      </PktInputWrapper>
+    </div>
+  )
+})
+
+PktTimepicker.displayName = 'PktTimepicker'

package/src/components/timepicker/types.ts

@@ -0,0 +1,118 @@
+import type { ChangeEvent, FocusEvent, InputHTMLAttributes, ReactNode } from 'react'
+import type { ITimepickerStrings } from 'shared-types/timepicker'
+
+/**
+ * Props for {@link PktTimepicker}: a React time picker with `HH:MM`, aligned with Elements `pkt-timepicker`.
+ *
+ * The value is submitted via a hidden `input type="time"`; hour/minute fields are the editing UI. Use `value`
+ * or `defaultValue` for controlled vs. uncontrolled mode.
+ */
+export interface IPktTimepicker
+  extends Omit<
+    InputHTMLAttributes<HTMLInputElement>,
+    'value' | 'onChange' | 'min' | 'max' | 'step' | 'onFocus' | 'onBlur'
+  > {
+  /** Unique id; used for hour, minute, popup, and hidden input ids. */
+  id: string
+
+  /** Visible label (InputWrapper). */
+  label: string
+
+  /** Controlled value (`HH:MM`). */
+  value?: string
+
+  /** Initial value when the component is uncontrolled. */
+  defaultValue?: string
+
+  /**
+   * Earliest valid time (`HH:MM`). May be a number or string (HTML attribute / RHF).
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/time}
+   */
+  min?: string | number
+
+  /**
+   * Latest valid time (`HH:MM`). May be a number or string (HTML attribute / RHF).
+   */
+  max?: string | number
+
+  /**
+   * Step in **seconds** (e.g. `60` = 1 min, `300` = 5 min). Must be a valid multiple (same rules as Elements).
+   * @default 60
+   */
+  step?: number
+
+  /** Hides the clock button and popup; shows a static clock icon. */
+  hidePicker?: boolean
+
+  /** Shows previous/next step buttons instead of the popup. */
+  stepArrows?: boolean
+
+  /** Full width (`pkt-timepicker--fullwidth`). */
+  fullwidth?: boolean
+
+  /** Form field name on the hidden `input`; falls back to `id` if omitted. */
+  name?: string
+
+  /** Help text above the field. */
+  helptext?: string | ReactNode
+
+  /** Expandable help text (dropdown). */
+  helptextDropdown?: string | ReactNode
+
+  /** Button label for expandable help text. */
+  helptextDropdownButton?: string
+
+  /** Forces error state on the wrapper. */
+  hasError?: boolean
+
+  /** Error message below the field. */
+  errorMessage?: string | ReactNode
+
+  /** Shows an "optional" tag. */
+  optionalTag?: boolean
+
+  /** Label text for the optional tag. */
+  optionalText?: string
+
+  /** Shows a "required" tag. */
+  requiredTag?: boolean
+
+  /** Label text for the required tag. */
+  requiredText?: string
+
+  /** Extra tag next to the label. */
+  tagText?: string | null
+
+  /** Inline layout in InputWrapper. */
+  inline?: boolean
+
+  /** Show visible label and help text (`false` = screen-reader-only label). */
+  useWrapper?: boolean
+
+  /** Passed through to InputWrapper as `aria-describedby`. */
+  ariaDescribedby?: string
+
+  /** Copy for hours, minutes, buttons, and popup. */
+  strings?: ITimepickerStrings
+
+  /** Change event from the hidden input (`e.target.value` is `HH:MM`). */
+  onChange?: (e: ChangeEvent<HTMLInputElement>) => void
+
+  /** Input events while typing or using spinners. */
+  onInput?: (e: ChangeEvent<HTMLInputElement>) => void
+
+  /** Callback with the committed `HH:MM` string. */
+  onValueChange?: (value: string) => void
+
+  /**
+   * Fires when focus enters this control from outside (not when moving only between hour and minute).
+   * Implemented on the root wrapper; spinbuttons must allow focus to bubble so this runs.
+   */
+  onFocus?: (e: FocusEvent<Element>) => void
+
+  /** Focus leaves the whole component. */
+  onBlur?: (e: FocusEvent<Element>) => void
+
+  /** Extra class names on the root (`pkt-timepicker`). */
+  className?: string
+}