@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroTimeField/FuroTimeFieldContext.js

@@ -0,0 +1,1138 @@
+import {
+  ref,
+} from 'vue'
+
+import {
+  Time,
+  parseTime,
+} from '@internationalized/date'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import TimeFieldEmitPayload from './TimeFieldEmitPayload.js'
+
+/**
+ * Furo-only parcel keys that are not forwarded to Reka `TimeFieldRoot`.
+ * These are stripped from the Reka v-bind spread.
+ */
+export const FURO_TIME_FIELD_PARCEL_KEYS = new Set([
+  'invalid',
+  'placeholder',
+  'disabled',
+  'readonly',
+  'minValue',
+  'maxValue',
+  'timeFormat',
+  'granularity',
+  'timezone',
+  'step',
+  'stepSnapping',
+  'decrementLabel',
+  'incrementLabel',
+])
+
+const DEFAULT_DECREMENT_LABEL = 'Decrement time'
+const DEFAULT_INCREMENT_LABEL = 'Increment time'
+
+/**
+ * Context class for managing FuroTimeField atom.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroTimeFieldContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroTimeFieldContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroTimeFieldContext ? X : never} T, X
+   * @override
+   * @param {FuroTimeFieldContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+    refHash = this.buildRefHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+        refHash,
+      })
+    )
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @override
+   * @returns {FuroTimeFieldContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      rootElementRef: ref(null),
+      internalValueRef: ref(null),
+    }
+  }
+
+  /**
+   * Build a zero `Time` (`00:00:00`) used as a fallback start for stepper edits.
+   *
+   * @returns {import('@internationalized/date').Time}
+   */
+  static buildZeroTime () {
+    return new Time(0, 0, 0)
+  }
+
+  /**
+   * Get emit event names.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   CHANGE_VALUE: 'change-value'
+   *   COMMIT_VALUE: 'commit-value'
+   *   UPDATE_VALUE: 'update:value'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      CHANGE_VALUE: 'change-value',
+      COMMIT_VALUE: 'commit-value',
+      UPDATE_VALUE: 'update:value',
+    }
+  }
+
+  /**
+   * Get emit event hash.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./TimeFieldEmitPayload.js').default) => void
+   *   'commit-value': (payload: import('./TimeFieldEmitPayload.js').default) => void
+   *   'update:value': (value: string | null) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.CHANGE_VALUE]: payload => {},
+      [this.EMIT_EVENT_NAME.COMMIT_VALUE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_VALUE]: value => {},
+    }
+  }
+
+  /**
+   * Get the EmitPayload constructor.
+   *
+   * @returns {typeof TimeFieldEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return TimeFieldEmitPayload
+  }
+
+  /**
+   * Map a time segment part (`hour` | `minute` | `second`) to the `Time.add` /
+   * `Time.subtract` duration unit key. Shared by focused-segment and granularity stepping.
+   *
+   * @returns {Readonly<{
+   *   hour: 'hours'
+   *   minute: 'minutes'
+   *   second: 'seconds'
+   * }>}
+   */
+  static get SEGMENT_UNIT_HASH () {
+    return {
+      hour: 'hours',
+      minute: 'minutes',
+      second: 'seconds',
+    }
+  }
+
+  /**
+   * Get the constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroTimeFieldContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroTimeFieldContext} */ (this.constructor)
+  }
+
+  /**
+   * Get root element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get rootElementRef () {
+    return this.refHash.rootElementRef
+  }
+
+  /**
+   * Get internal Time value ref.
+   *
+   * @returns {import('vue').Ref<import('@internationalized/date').Time | null>}
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {Props['parcel']}
+   */
+  get parcel () {
+    return this.props.parcel
+      ?? null
+  }
+
+  /**
+   * Whether the time field is in an externally-flagged invalid state.
+   *
+   * @returns {boolean}
+   */
+  get isInvalid () {
+    return this.parcel?.invalid
+      ?? false
+  }
+
+  /**
+   * Whether the time field is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    return Boolean(this.parcel?.disabled)
+      || this.hasBooleanAttribute({ name: 'disabled' })
+  }
+
+  /**
+   * Whether the time field is read-only.
+   *
+   * @returns {boolean}
+   */
+  isReadonly () {
+    return Boolean(this.parcel?.readonly)
+      || this.hasBooleanAttribute({ name: 'readonly' })
+  }
+
+  /**
+   * Placeholder text.
+   *
+   * @returns {string}
+   */
+  get placeholder () {
+    return this.parcel?.placeholder
+      ?? ''
+  }
+
+  /**
+   * Time format (12 or 24). `null` when unset (locale default applies).
+   *
+   * @returns {number | null}
+   */
+  get timeFormat () {
+    return this.parcel?.timeFormat
+      ?? null
+  }
+
+  /**
+   * Segment granularity (`hour` | `minute` | `second`). `null` when unset (Reka defaults to `minute`).
+   *
+   * @returns {string | null}
+   */
+  get granularity () {
+    return this.parcel?.granularity
+      ?? null
+  }
+
+  /**
+   * IANA timezone identifier for `Date` object normalization (e.g. `'Asia/Tokyo'`).
+   * When `null`, normalization falls back to local time parts (timezone-naive).
+   * Furo-only — never forwarded to Reka.
+   *
+   * @returns {string | null}
+   */
+  get timezone () {
+    return this.parcel?.timezone
+      ?? null
+  }
+
+  /**
+   * Accessible name of the decrement button.
+   *
+   * @returns {string}
+   */
+  get decrementLabel () {
+    return this.parcel?.decrementLabel
+      ?? DEFAULT_DECREMENT_LABEL
+  }
+
+  /**
+   * Accessible name of the increment button.
+   *
+   * @returns {string}
+   */
+  get incrementLabel () {
+    return this.parcel?.incrementLabel
+      ?? DEFAULT_INCREMENT_LABEL
+  }
+
+  /**
+   * Whether the increment button can step the value up.
+   * `false` when disabled/readonly, or when the next step would exceed `maxValue`.
+   * When no value has been entered yet, returns `true` — the first press seeds a
+   * starting value (see `extractIncrementSeed()`).
+   *
+   * @returns {boolean}
+   */
+  canIncrement () {
+    if (
+      this.isDisabled()
+      || this.isReadonly()
+    ) {
+      return false
+    }
+
+    const current = this.internalValueRef.value
+
+    if (current === null) {
+      return true
+    }
+
+    const maxValue = this.normalizeMaxValue()
+
+    if (maxValue === null) {
+      return true
+    }
+
+    return current.compare(maxValue) < 0
+  }
+
+  /**
+   * Whether the decrement button can step the value down.
+   * `false` when disabled/readonly, or when the previous step would fall below `minValue`.
+   * When no value has been entered yet, returns `true` — the first press seeds a
+   * starting value (see `extractDecrementSeed()`).
+   *
+   * @returns {boolean}
+   */
+  canDecrement () {
+    if (
+      this.isDisabled()
+      || this.isReadonly()
+    ) {
+      return false
+    }
+
+    const current = this.internalValueRef.value
+
+    if (current === null) {
+      return true
+    }
+
+    const minValue = this.normalizeMinValue()
+
+    if (minValue === null) {
+      return true
+    }
+
+    return current.compare(minValue) > 0
+  }
+
+  /**
+   * Setup component — sync external value into internal Time ref.
+   *
+   * @template {X extends FuroTimeFieldContext ? X : never} T, X
+   * @override
+   * @returns {T} - For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.watch(
+      [
+        () => this.parcel?.value,
+        () => this.attrs?.value ?? null,
+      ],
+      ([parcelValue, attrsValue]) => {
+        const raw = /** @type {string | null} */ (parcelValue ?? attrsValue ?? null)
+
+        this.internalValueRef.value = this.normalizeToTime({ raw })
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Normalize an external value to `Time | null`.
+   * Accepts `HH:MM` / `HH:MM:SS` strings, `Date` objects, `Time` instances, or `null`.
+   *
+   * @param {{
+   *   raw: string | Date | import('reka-ui').TimeValue | null
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').Time | null}
+   */
+  normalizeToTime ({
+    raw,
+  }) {
+    if (!raw) {
+      return null
+    }
+
+    if (typeof raw === 'string') {
+      return this.normalizeStringToTime({ raw })
+    }
+
+    if (raw instanceof Date) {
+      return this.normalizeDateToTime({ raw })
+    }
+
+    // Already a Time-like object
+    return /** @type {import('@internationalized/date').Time} */ (raw)
+  }
+
+  /**
+   * Parse an `HH:MM` or `HH:MM:SS` string into a `Time`.
+   *
+   * @param {{
+   *   raw: string
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').Time | null}
+   */
+  normalizeStringToTime ({
+    raw,
+  }) {
+    if (!raw) {
+      return null
+    }
+
+    try {
+      return parseTime(raw)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Convert a `Date` object to `Time`.
+   * When `parcel.timezone` is set, time parts are extracted in that IANA timezone.
+   * Otherwise falls back to local wall-clock parts (timezone-naive).
+   *
+   * @param {{
+   *   raw: Date
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').Time | null}
+   */
+  normalizeDateToTime ({
+    raw,
+  }) {
+    if (
+      !raw
+      || isNaN(raw.getTime())
+    ) {
+      return null
+    }
+
+    const { timezone } = this
+
+    if (timezone) {
+      return this.normalizeDateToTimeInTimezone({ raw, timezone })
+    }
+
+    return new Time(
+      raw.getHours(),
+      raw.getMinutes(),
+      raw.getSeconds()
+    )
+  }
+
+  /**
+   * Convert a `Date` object to `Time` using a specific IANA timezone.
+   * Returns `null` when the timezone identifier is invalid.
+   *
+   * @param {{
+   *   raw: Date
+   *   timezone: string
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').Time | null}
+   */
+  normalizeDateToTimeInTimezone ({
+    raw,
+    timezone,
+  }) {
+    try {
+      const { hour, minute, second } = this.Ctor.extractTimePartsInTimezone({ raw, timezone })
+
+      if (
+        hour === null
+        || minute === null
+        || second === null
+      ) {
+        return null
+      }
+
+      const isoString = [
+        hour,
+        minute,
+        second,
+      ].join(':')
+
+      return this.normalizeStringToTime({ raw: isoString })
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Extract hour / minute / second string parts from a `Date` object in a specific IANA
+   * timezone via `Intl.DateTimeFormat`. Each part is zero-padded to 2 digits so the
+   * assembled `HH:MM:SS` string parses cleanly (generalizes the year-pad lesson).
+   *
+   * @param {{
+   *   raw: Date
+   *   timezone: string
+   * }} params - Parameters of this method.
+   * @returns {{ hour: string | null, minute: string | null, second: string | null }}
+   */
+  static extractTimePartsInTimezone ({
+    raw,
+    timezone,
+  }) {
+    const formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone,
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+      hourCycle: 'h23',
+    })
+
+    const parts = formatter.formatToParts(raw)
+
+    const hour = this.extractPaddedTimePart({ parts, type: 'hour' })
+    const minute = this.extractPaddedTimePart({ parts, type: 'minute' })
+    const second = this.extractPaddedTimePart({ parts, type: 'second' })
+
+    return {
+      hour,
+      minute,
+      second,
+    }
+  }
+
+  /**
+   * Extract the DOM element that currently has focus, or `null` when the document is
+   * unavailable (e.g. SSR). Isolated as a static hook so tests can stub the active element.
+   *
+   * @returns {Element | null}
+   */
+  static extractActiveElement () {
+    if (!globalThis.document) {
+      return null
+    }
+
+    return document.activeElement
+  }
+
+  /**
+   * Find a single formatted time part by type and zero-pad it to 2 digits.
+   *
+   * @param {{
+   *   parts: Array<Intl.DateTimeFormatPart>
+   *   type: string
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  static extractPaddedTimePart ({
+    parts,
+    type,
+  }) {
+    return parts.find(part => part.type === type)
+      ?.value
+      ?.padStart(2, '0')
+      ?? null
+  }
+
+  /**
+   * Normalize a `Time` to an `HH:MM:SS` string or `null`.
+   * Always serializes via `time.toString()` (zero-pads), never manual segment assembly.
+   *
+   * @param {{
+   *   time: import('@internationalized/date').Time | null
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  normalizeToIsoString ({
+    time,
+  }) {
+    return time?.toString() ?? null
+  }
+
+  /**
+   * Normalize the parcel `minValue` to a `Time`.
+   *
+   * @returns {import('@internationalized/date').Time | null}
+   */
+  normalizeMinValue () {
+    const raw = this.parcel?.minValue ?? null
+
+    return this.normalizeToTime({ raw })
+  }
+
+  /**
+   * Normalize the parcel `maxValue` to a `Time`.
+   *
+   * @returns {import('@internationalized/date').Time | null}
+   */
+  normalizeMaxValue () {
+    const raw = this.parcel?.maxValue ?? null
+
+    return this.normalizeToTime({ raw })
+  }
+
+  /**
+   * Normalize the parcel `step` amount applied to the smallest visible segment (per
+   * `granularity`) for the increment/decrement buttons. A non-positive or non-numeric
+   * step falls back to `1`.
+   *
+   * @returns {number}
+   */
+  normalizeStep () {
+    const rawStep = this.parcel?.step
+      ?? null
+
+    if (
+      typeof rawStep !== 'number'
+      || rawStep <= 0
+    ) {
+      return 1
+    }
+
+    return rawStep
+  }
+
+  /**
+   * Extract attributes for Reka `TimeFieldRoot`.
+   * Strips all Furo-only keys and re-applies normalized Reka props.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const strippedParcel = this.stripFuroParcelKeys()
+
+    const optionalAttributes = this.buildOptionalRootAttributes()
+
+    const {
+      value,
+      ...passthroughAttrs
+    } = this.attrs ?? {}
+
+    return {
+      ...passthroughAttrs,
+      ...strippedParcel,
+      modelValue: this.internalValueRef.value,
+      disabled: this.isDisabled(),
+      readonly: this.isReadonly(),
+      step: this.normalizeStep(),
+      ...optionalAttributes,
+    }
+  }
+
+  /**
+   * Build the optional Reka root attributes that are only included when present.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  buildOptionalRootAttributes () {
+    const entries = [
+      ['stepSnapping', this.parcel?.stepSnapping ?? null],
+      ['hourCycle', this.timeFormat],
+      ['granularity', this.granularity],
+      ['minValue', this.normalizeMinValue()],
+      ['maxValue', this.normalizeMaxValue()],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Strip Furo-only parcel keys from the parcel object.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  stripFuroParcelKeys () {
+    const { parcel } = this
+
+    if (!parcel) {
+      return {}
+    }
+
+    const entries = Object.entries(parcel)
+      .filter(([key]) => !FURO_TIME_FIELD_PARCEL_KEYS.has(key))
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Build a custom event for the emit payload.
+   *
+   * @param {{
+   *   name: string
+   *   value: string | null
+   * }} params - Parameters of this method.
+   * @returns {CustomEvent<{
+   *   target: HTMLElement | null
+   *   value: string | null
+   * }>}
+   */
+  buildCustomEvent ({
+    name,
+    value,
+  }) {
+    return new CustomEvent(
+      name,
+      {
+        detail: {
+          target: this.rootElementRef.value,
+          value,
+        },
+      }
+    )
+  }
+
+  /**
+   * Respond to `update:modelValue` from Reka `TimeFieldRoot`.
+   * Emits `change-value`, `update:value`, and `commit-value`.
+   *
+   * @param {{
+   *   time?: import('reka-ui').TimeValue | null
+   * }} params - Parameters of this method.
+   */
+  onChangeValue ({
+    time = null,
+  }) {
+    const normalized = this.normalizeToTime({
+      raw: time,
+    })
+
+    this.internalValueRef.value = normalized
+
+    const value = this.normalizeToIsoString({ time: normalized })
+
+    const customEvent = this.buildCustomEvent({
+      name: this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      value,
+    })
+
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent: customEvent,
+    })
+
+    this.emit(
+      this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      payload
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_VALUE,
+      value
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.COMMIT_VALUE,
+      payload
+    )
+  }
+
+  /**
+   * Step the value up by `step` of the smallest visible segment, clamped to
+   * `[minValue, maxValue]`, then route through the same emit path as segment edits.
+   * When no value has been entered yet, the first press seeds the increment start
+   * value (`minValue ?? 00:00`) instead of stepping.
+   */
+  onIncrementValue () {
+    if (!this.canIncrement()) {
+      return
+    }
+
+    const current = this.internalValueRef.value
+
+    if (current === null) {
+      this.onChangeValue({ time: this.extractIncrementSeed() })
+
+      return
+    }
+
+    const next = current.add(this.extractStepDuration())
+
+    if (next.compare(current) < 0) {
+      this.onIncrementWrap({ next })
+
+      return
+    }
+
+    const clamped = this.clampTime({ time: next })
+
+    this.onChangeValue({ time: clamped })
+  }
+
+  /**
+   * Handle a forward step that wrapped past midnight (`23:58 + 5 → 00:03`).
+   * Pins to `maxValue` when set; otherwise loops the wrapped value around (cyclic,
+   * since the field is unbounded above).
+   *
+   * @param {{
+   *   next: import('@internationalized/date').Time
+   * }} params - Parameters of this method.
+   */
+  onIncrementWrap ({
+    next,
+  }) {
+    const maxValue = this.normalizeMaxValue()
+
+    if (maxValue === null) {
+      this.onChangeValue({ time: next })
+
+      return
+    }
+
+    this.onChangeValue({ time: maxValue })
+  }
+
+  /**
+   * Step the value down by `step` of the smallest visible segment, clamped to
+   * `[minValue, maxValue]`, then route through the same emit path as segment edits.
+   * When no value has been entered yet, the first press seeds the decrement start
+   * value (`maxValue ?? 00:00`) instead of stepping.
+   */
+  onDecrementValue () {
+    if (!this.canDecrement()) {
+      return
+    }
+
+    const current = this.internalValueRef.value
+
+    if (current === null) {
+      this.onChangeValue({ time: this.extractDecrementSeed() })
+
+      return
+    }
+
+    const next = current.subtract(this.extractStepDuration())
+
+    if (next.compare(current) > 0) {
+      this.onDecrementWrap({ next })
+
+      return
+    }
+
+    const clamped = this.clampTime({ time: next })
+
+    this.onChangeValue({ time: clamped })
+  }
+
+  /**
+   * Handle a backward step that wrapped past midnight (`00:02 - 5 → 23:57`).
+   * Pins to `minValue` when set; otherwise loops the wrapped value around (cyclic,
+   * since the field is unbounded below).
+   *
+   * @param {{
+   *   next: import('@internationalized/date').Time
+   * }} params - Parameters of this method.
+   */
+  onDecrementWrap ({
+    next,
+  }) {
+    const minValue = this.normalizeMinValue()
+
+    if (minValue === null) {
+      this.onChangeValue({ time: next })
+
+      return
+    }
+
+    this.onChangeValue({ time: minValue })
+  }
+
+  /**
+   * Build the starting value for the first increment press on an empty field.
+   * Begins at `minValue` when set, otherwise `00:00`, clamped into `[minValue, maxValue]`.
+   *
+   * @returns {import('@internationalized/date').Time}
+   */
+  extractIncrementSeed () {
+    const seed = this.normalizeMinValue()
+      ?? this.Ctor.buildZeroTime()
+
+    return this.clampTime({ time: seed })
+  }
+
+  /**
+   * Build the starting value for the first decrement press on an empty field.
+   * Begins at `maxValue` when set, otherwise the end of the day (per `granularity`,
+   * e.g. `23:59`) so subsequent decrements keep stepping down instead of landing on
+   * `00:00` where they cannot cross midnight. Clamped into `[minValue, maxValue]`.
+   *
+   * @returns {import('@internationalized/date').Time}
+   */
+  extractDecrementSeed () {
+    const seed = this.normalizeMaxValue()
+      ?? this.buildEndOfDayTime()
+
+    return this.clampTime({ time: seed })
+  }
+
+  /**
+   * Build the end-of-day `Time` for the current `granularity`: `23:00` for hours,
+   * `23:59:59` for seconds, otherwise `23:59`. Used as the unbounded decrement seed.
+   *
+   * @returns {import('@internationalized/date').Time}
+   */
+  buildEndOfDayTime () {
+    const partsHash = {
+      hours: [23, 0, 0],
+      minutes: [23, 59, 0],
+      seconds: [23, 59, 59],
+    }
+
+    const [hour, minute, second] = partsHash[this.extractGranularityUnit()]
+
+    return new Time(hour, minute, second)
+  }
+
+  /**
+   * Build the duration object passed to `Time.add` / `Time.subtract` for one stepper press.
+   * The unit prioritizes the currently focused segment (`hour` / `minute` / `second`); when no
+   * segment is focused it falls back to `granularity` (the smallest visible segment), defaulting
+   * to minutes. The amount is always `step`.
+   *
+   * @returns {{
+   *   hours?: number
+   *   minutes?: number
+   *   seconds?: number
+   * }}
+   */
+  extractStepDuration () {
+    const unit = this.extractFocusedSegmentUnit()
+      ?? this.extractGranularityUnit()
+
+    return {
+      [unit]: this.normalizeStep(),
+    }
+  }
+
+  /**
+   * Map the currently focused time segment to a duration unit key, or `null` when no
+   * steppable segment (`hour` / `minute` / `second`) is focused.
+   *
+   * @returns {'hours' | 'minutes' | 'seconds' | null}
+   */
+  extractFocusedSegmentUnit () {
+    const part = this.extractFocusedSegmentPart()
+
+    return this.Ctor.SEGMENT_UNIT_HASH[/** @type {keyof typeof FuroTimeFieldContext.SEGMENT_UNIT_HASH} */ (part)]
+      ?? null
+  }
+
+  /**
+   * Map the `granularity` (smallest visible segment) to a duration unit key.
+   * Defaults to minutes when granularity is unset or unrecognized.
+   *
+   * @returns {'hours' | 'minutes' | 'seconds'}
+   */
+  extractGranularityUnit () {
+    return this.Ctor.SEGMENT_UNIT_HASH[/** @type {keyof typeof FuroTimeFieldContext.SEGMENT_UNIT_HASH} */ (this.granularity)]
+      ?? 'minutes'
+  }
+
+  /**
+   * Extract the currently focused time segment part (`hour` | `minute` | `second` | `dayPeriod`)
+   * from the active element, or `null` when no time segment is focused. Reads the
+   * `data-reka-time-field-segment` attribute the underlying primitive stamps on each segment.
+   *
+   * @returns {string | null}
+   */
+  extractFocusedSegmentPart () {
+    const activeElement = this.Ctor.extractActiveElement()
+
+    return activeElement?.getAttribute('data-reka-time-field-segment')
+      ?? null
+  }
+
+  /**
+   * Clamp a `Time` into the `[minValue, maxValue]` window.
+   * Returns the bound when out of range, otherwise the original time.
+   *
+   * @param {{
+   *   time: import('@internationalized/date').Time
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').Time}
+   */
+  clampTime ({
+    time,
+  }) {
+    const minValue = this.normalizeMinValue()
+    const maxValue = this.normalizeMaxValue()
+
+    if (
+      minValue !== null
+      && time.compare(minValue) < 0
+    ) {
+      return minValue
+    }
+
+    if (
+      maxValue !== null
+      && time.compare(maxValue) > 0
+    ) {
+      return maxValue
+    }
+
+    return time
+  }
+
+  /**
+   * Whether the segment part is a literal separator (e.g. `:` between segments).
+   *
+   * @param {{ part: import('reka-ui').SegmentPart }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  isLiteralPart ({
+    part,
+  }) {
+    return part === 'literal'
+  }
+
+  /**
+   * Format a time segment value for display. Hour, minute, and second segments are zero-padded
+   * to two digits (e.g. `9` → `09`) so the field width stays constant as the value changes;
+   * the day period (AM/PM) and literals pass through unchanged. The underlying primitive
+   * renders filled segments with single-digit (`numeric`) formatting, so this — together with
+   * `tabular-nums` — keeps the trigger from resizing and shifting the popover.
+   *
+   * @param {{
+   *   part: import('reka-ui').SegmentPart
+   *   value: string
+   * }} params - Parameters of this method.
+   * @returns {string}
+   */
+  formatSegmentValue ({
+    part,
+    value,
+  }) {
+    if (!this.isTwoDigitSegmentPart({ part })) {
+      return value
+    }
+
+    if (!/^\d{1,2}$/u.test(value)) {
+      return value
+    }
+
+    return value.padStart(2, '0')
+  }
+
+  /**
+   * Whether a segment part should display zero-padded to two digits (hour, minute, second).
+   *
+   * @param {{ part: import('reka-ui').SegmentPart }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  isTwoDigitSegmentPart ({
+    part,
+  }) {
+    return [
+      'hour',
+      'minute',
+      'second',
+    ]
+      .includes(part)
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     rootElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<import('@internationalized/date').Time | null>
+ *   }
+ * }} FuroTimeFieldContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroTimeFieldContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     rootElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<import('@internationalized/date').Time | null>
+ *   }
+ * }} FuroTimeFieldContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroTimeFieldContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: TimeFieldParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {
+ *   value?: string | null
+ *   invalid?: boolean
+ *   placeholder?: string | null
+ *   disabled?: boolean
+ *   readonly?: boolean
+ *   minValue?: string | null
+ *   maxValue?: string | null
+ *   timeFormat?: number | null
+ *   granularity?: 'hour' | 'minute' | 'second' | null
+ *   step?: number | null
+ *   stepSnapping?: boolean | null
+ *   timezone?: string | null
+ *   decrementLabel?: string
+ *   incrementLabel?: string
+ * }} TimeFieldParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroTimeFieldEmitHash>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroTimeFieldContext.EMIT_EVENT_HASH} FuroTimeFieldEmitHash
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroTimeFieldContext
+ * }} FuroTimeFieldSetup
+ */