@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroDatePicker/FuroDatePickerContext.js

@@ -0,0 +1,1038 @@
+import {
+  ref,
+} from 'vue'
+
+import {
+  CalendarDate,
+  getLocalTimeZone,
+  parseDate,
+  today,
+} from '@internationalized/date'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import DatePickerEmitPayload from './DatePickerEmitPayload.js'
+
+/** @type {{ value: number, label: string }[]} */
+const CALENDAR_MONTHS = [
+  { value: 1, label: 'January' },
+  { value: 2, label: 'February' },
+  { value: 3, label: 'March' },
+  { value: 4, label: 'April' },
+  { value: 5, label: 'May' },
+  { value: 6, label: 'June' },
+  { value: 7, label: 'July' },
+  { value: 8, label: 'August' },
+  { value: 9, label: 'September' },
+  { value: 10, label: 'October' },
+  { value: 11, label: 'November' },
+  { value: 12, label: 'December' },
+]
+
+/**
+ * Furo-only parcel keys that are not forwarded to Reka `DatePickerRoot`.
+ * These are stripped from the Reka v-bind spread.
+ */
+export const FURO_DATE_PICKER_PARCEL_KEYS = new Set([
+  'invalid',
+  'placeholder',
+  'disabled',
+  'minValue',
+  'maxValue',
+  'displayFormat',
+  'timezone',
+  'clearButtonText',
+  'todayButtonText',
+])
+
+/**
+ * Default footer button labels. A consumer overrides them via parcel; passing `null` hides
+ * the corresponding button.
+ */
+const DEFAULT_TODAY_BUTTON_TEXT = 'Today'
+
+const DEFAULT_CLEAR_BUTTON_TEXT = 'Clear'
+
+/**
+ * Context class for managing FuroDatePicker atom.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroDatePickerContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroDatePickerContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroDatePickerContext ? X : never} T, X
+   * @override
+   * @param {FuroDatePickerContextFactoryParams} 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 {FuroDatePickerContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      triggerElementRef: ref(null),
+      internalValueRef: ref(null),
+      placeholderRef: ref(null),
+    }
+  }
+
+  /**
+   * 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('./DatePickerEmitPayload.js').default) => void
+   *   'commit-value': (payload: import('./DatePickerEmitPayload.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 DatePickerEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return DatePickerEmitPayload
+  }
+
+  /**
+   * Get the constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroDatePickerContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroDatePickerContext} */ (this.constructor)
+  }
+
+  /**
+   * Get trigger element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get triggerElementRef () {
+    return this.refHash.triggerElementRef
+  }
+
+  /**
+   * Get internal CalendarDate value ref.
+   *
+   * @returns {import('vue').Ref<import('@internationalized/date').CalendarDate | null>}
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Get calendar view placeholder ref (controls which month/year the calendar shows).
+   *
+   * @returns {import('vue').Ref<import('@internationalized/date').CalendarDate | null>}
+   */
+  get placeholderRef () {
+    return this.refHash.placeholderRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {Props['parcel']}
+   */
+  get parcel () {
+    return this.props.parcel
+      ?? null
+  }
+
+  /**
+   * Get trigger parcel.
+   *
+   * @returns {Props['triggerParcel']}
+   */
+  get triggerParcel () {
+    return this.props.triggerParcel
+      ?? null
+  }
+
+  /**
+   * Get content parcel.
+   *
+   * @returns {Props['contentParcel']}
+   */
+  get contentParcel () {
+    return this.props.contentParcel
+      ?? null
+  }
+
+  /**
+   * Whether the date picker is in an invalid state.
+   *
+   * @returns {boolean}
+   */
+  get isInvalid () {
+    return this.parcel?.invalid
+      ?? false
+  }
+
+  /**
+   * Whether the date picker is disabled.
+   *
+   * @returns {boolean}
+   */
+  get isDisabled () {
+    return this.parcel?.disabled
+      ?? false
+  }
+
+  /**
+   * Placeholder text.
+   *
+   * @returns {string}
+   */
+  get placeholder () {
+    return this.parcel?.placeholder
+      ?? ''
+  }
+
+  /**
+   * IANA timezone identifier for Date object normalization (e.g. `'Asia/Tokyo'`).
+   * When `null`, normalization falls back to local date parts (timezone-naive).
+   *
+   * @returns {string | null}
+   */
+  get timezone () {
+    return this.parcel?.timezone
+      ?? null
+  }
+
+  /**
+   * Footer "Today" button label. Defaults to `'Today'`; `null` hides the button.
+   *
+   * @returns {string | null}
+   */
+  get todayButtonText () {
+    if (
+      !this.parcel
+      || !('todayButtonText' in this.parcel)
+    ) {
+      return DEFAULT_TODAY_BUTTON_TEXT
+    }
+
+    return this.parcel.todayButtonText ?? null
+  }
+
+  /**
+   * Footer "Clear" button label. Defaults to `'Clear'`; `null` hides the button.
+   *
+   * @returns {string | null}
+   */
+  get clearButtonText () {
+    if (
+      !this.parcel
+      || !('clearButtonText' in this.parcel)
+    ) {
+      return DEFAULT_CLEAR_BUTTON_TEXT
+    }
+
+    return this.parcel.clearButtonText ?? null
+  }
+
+  /**
+   * Setup component — sync external value into internal CalendarDate ref.
+   *
+   * @template {X extends FuroDatePickerContext ? 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.normalizeToCalendarDate({ raw })
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Normalize an external value to `CalendarDate | null`.
+   * Accepts `YYYY-MM-DD` strings, `Date` objects, `CalendarDate` instances, or `null`.
+   *
+   * @param {{
+   *   raw: string | Date | import('@internationalized/date').CalendarDate | null
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').CalendarDate | null}
+   */
+  normalizeToCalendarDate ({
+    raw,
+  }) {
+    if (!raw) {
+      return null
+    }
+
+    if (typeof raw === 'string') {
+      return this.normalizeStringToCalendarDate({ raw })
+    }
+
+    if (raw instanceof Date) {
+      return this.normalizeDateToCalendarDate({ raw })
+    }
+
+    // Already a CalendarDate-like object
+    return /** @type {import('@internationalized/date').CalendarDate} */ (raw)
+  }
+
+  /**
+   * Parse an ISO `YYYY-MM-DD` string into a `CalendarDate`.
+   *
+   * @param {{
+   *   raw: string
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').CalendarDate | null}
+   */
+  normalizeStringToCalendarDate ({
+    raw,
+  }) {
+    if (!raw) {
+      return null
+    }
+
+    try {
+      return parseDate(raw)
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Convert a `Date` object to `CalendarDate`.
+   * When `parcel.timezone` is set, date parts are extracted in that IANA timezone.
+   * Otherwise falls back to local date parts (timezone-naive).
+   *
+   * @param {{
+   *   raw: Date
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').CalendarDate | null}
+   */
+  normalizeDateToCalendarDate ({
+    raw,
+  }) {
+    if (
+      !raw
+      || isNaN(raw.getTime())
+    ) {
+      return null
+    }
+
+    const { timezone } = this
+
+    if (timezone) {
+      return this.normalizeDateToCalendarDateInTimezone({ raw, timezone })
+    }
+
+    const yearString = String(raw.getFullYear())
+      .padStart(4, '0')
+    const monthString = String(raw.getMonth() + 1)
+      .padStart(2, '0')
+    const dayString = String(raw.getDate())
+      .padStart(2, '0')
+
+    const isoString = [
+      yearString,
+      monthString,
+      dayString,
+    ].join('-')
+
+    return this.normalizeStringToCalendarDate({ raw: isoString })
+  }
+
+  /**
+   * Convert a `Date` object to `CalendarDate` 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').CalendarDate | null}
+   */
+  normalizeDateToCalendarDateInTimezone ({
+    raw,
+    timezone,
+  }) {
+    try {
+      const { year, month, day } = this.Ctor.extractDatePartsInTimezone({ raw, timezone })
+
+      if (
+        year === null
+        || month === null
+        || day === null
+      ) {
+        return null
+      }
+
+      const isoString = [
+        year,
+        month,
+        day,
+      ].join('-')
+
+      return this.normalizeStringToCalendarDate({ raw: isoString })
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Extract year / month / day string parts from a `Date` object in a specific IANA timezone
+   * via `Intl.DateTimeFormat`. Year is zero-padded to 4 digits to satisfy ISO 8601.
+   *
+   * @param {{
+   *   raw: Date
+   *   timezone: string
+   * }} params - Parameters of this method.
+   * @returns {{ year: string | null, month: string | null, day: string | null }}
+   */
+  static extractDatePartsInTimezone ({
+    raw,
+    timezone,
+  }) {
+    const formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone: timezone,
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+    })
+
+    const parts = formatter.formatToParts(raw)
+
+    const year = parts.find(part => part.type === 'year')
+      ?.value
+      ?.padStart(4, '0')
+      ?? null
+    const month = parts.find(part => part.type === 'month')
+      ?.value
+      ?? null
+    const day = parts.find(part => part.type === 'day')
+      ?.value
+      ?? null
+
+    return {
+      year,
+      month,
+      day,
+    }
+  }
+
+  /**
+   * Detect the browser's locale string. Returns `'en'` when `navigator` is unavailable
+   * (e.g. server-side render).
+   *
+   * @returns {string}
+   */
+  static detectBrowserLocale () {
+    if (!navigator) {
+      return 'en'
+    }
+
+    return navigator.language
+      ?? 'en'
+  }
+
+  /**
+   * Whether the footer actions row should be rendered (at least one button is visible).
+   *
+   * @returns {boolean}
+   */
+  hasFooterButtons () {
+    return this.hasTodayButton()
+      || this.hasClearButton()
+  }
+
+  /**
+   * Whether the Today button is visible.
+   *
+   * @returns {boolean}
+   */
+  hasTodayButton () {
+    return this.todayButtonText !== null
+  }
+
+  /**
+   * Whether the Clear button is visible.
+   *
+   * @returns {boolean}
+   */
+  hasClearButton () {
+    return this.clearButtonText !== null
+  }
+
+  /**
+   * Normalize a `CalendarDate` to an ISO `YYYY-MM-DD` string or `null`.
+   *
+   * @param {{
+   *   calendarDate: import('@internationalized/date').CalendarDate | null
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  normalizeToIsoString ({
+    calendarDate,
+  }) {
+    return calendarDate?.toString() ?? null
+  }
+
+  /**
+   * Normalize the parcel `minValue` to a `CalendarDate`.
+   *
+   * @returns {import('@internationalized/date').CalendarDate | null}
+   */
+  normalizeMinValue () {
+    const raw = this.parcel?.minValue ?? null
+
+    return this.normalizeToCalendarDate({ raw })
+  }
+
+  /**
+   * Normalize the parcel `maxValue` to a `CalendarDate`.
+   *
+   * @returns {import('@internationalized/date').CalendarDate | null}
+   */
+  normalizeMaxValue () {
+    const raw = this.parcel?.maxValue ?? null
+
+    return this.normalizeToCalendarDate({ raw })
+  }
+
+  /**
+   * Resolve the calendar placeholder, which drives both the displayed month/year and the
+   * empty segment placeholders. Falls back to an explicit placeholder, then the current
+   * value, then today clamped into the `[minValue, maxValue]` window — so the year segment
+   * auto-fills within range when bounds are set but no value exists yet.
+   *
+   * @returns {import('@internationalized/date').CalendarDate | null}
+   */
+  resolveCalendarPlaceholder () {
+    const explicit = this.placeholderRef.value
+      ?? this.internalValueRef.value
+
+    if (explicit !== null) {
+      return explicit
+    }
+
+    return this.clampDateToBounds({
+      date: today(getLocalTimeZone()),
+    })
+  }
+
+  /**
+   * Clamp a `CalendarDate` into the `[minValue, maxValue]` window.
+   * Returns the bound when out of range, otherwise the original date.
+   *
+   * @param {{
+   *   date: import('@internationalized/date').CalendarDate
+   * }} params - Parameters of this method.
+   * @returns {import('@internationalized/date').CalendarDate}
+   */
+  clampDateToBounds ({
+    date,
+  }) {
+    const minValue = this.normalizeMinValue()
+    const maxValue = this.normalizeMaxValue()
+
+    if (
+      minValue !== null
+      && date.compare(minValue) < 0
+    ) {
+      return minValue
+    }
+
+    if (
+      maxValue !== null
+      && date.compare(maxValue) > 0
+    ) {
+      return maxValue
+    }
+
+    return date
+  }
+
+  /**
+   * Resolve whether the calendar popover closes when a date is selected.
+   * Defaults to `true` (single-date close-on-select UX). A consumer — e.g. the
+   * `FuroDateTimePicker` molecule — passes `closeOnSelect: false` to keep the popover open
+   * so a time can also be chosen in the same session.
+   *
+   * @returns {boolean}
+   */
+  resolveCloseOnSelect () {
+    return this.parcel?.closeOnSelect
+      ?? true
+  }
+
+  /**
+   * Resolve whether re-selecting the already-selected date is prevented from clearing it.
+   * Defaults to `true` (re-clicking a selected date keeps it), with `parcel.preventDeselect`
+   * as an explicit override.
+   *
+   * @returns {boolean}
+   */
+  resolvePreventDeselect () {
+    return this.parcel?.preventDeselect
+      ?? true
+  }
+
+  /**
+   * Resolve the locale that drives the date field's segment order and formatting.
+   * Defaults to the browser locale so the segment order follows the user's locale
+   * (e.g. `dd/mm/yyyy`), with `parcel.locale` as an explicit override.
+   *
+   * @returns {string}
+   */
+  resolveLocale () {
+    return this.parcel?.locale
+      ?? this.Ctor.detectBrowserLocale()
+  }
+
+  /**
+   * Extract attributes for Reka `DatePickerRoot`.
+   * Strips all Furo-only keys and re-applies normalized Reka props.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const strippedParcel = this.stripFuroParcelKeys()
+
+    const minValue = this.normalizeMinValue()
+    const maxValue = this.normalizeMaxValue()
+    const placeholder = this.resolveCalendarPlaceholder()
+
+    return {
+      ...this.attrs,
+      ...strippedParcel,
+      modelValue: this.internalValueRef.value,
+      granularity: 'day',
+      closeOnSelect: this.resolveCloseOnSelect(),
+      preventDeselect: this.resolvePreventDeselect(),
+      locale: this.resolveLocale(),
+      disabled: this.isDisabled,
+      ...(placeholder === null
+        ? {}
+        : { placeholder }),
+      ...(minValue === null
+        ? {}
+        : { minValue }),
+      ...(maxValue === null
+        ? {}
+        : { maxValue }),
+    }
+  }
+
+  /**
+   * 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_DATE_PICKER_PARCEL_KEYS.has(key))
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Extract attributes for Reka `DatePickerField` / `DatePickerTrigger`.
+   *
+   * @returns {Props['triggerParcel']}
+   */
+  extractTriggerAttributes () {
+    return this.triggerParcel
+  }
+
+  /**
+   * Extract attributes for Reka `DatePickerContent`.
+   *
+   * @returns {Props['contentParcel']}
+   */
+  extractContentAttributes () {
+    return this.contentParcel
+  }
+
+  /**
+   * 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.triggerElementRef.value,
+          value,
+        },
+      }
+    )
+  }
+
+  /**
+   * Respond to `update:modelValue` from Reka `DatePickerRoot`.
+   * Emits `change-value`, `update:value`, and `commit-value`.
+   *
+   * @param {{
+   *   calendarDate?: import('@internationalized/date').DateValue | null
+   * }} params - Parameters of this method.
+   */
+  onChangeValue ({
+    calendarDate = null,
+  }) {
+    const normalized = this.normalizeToCalendarDate({
+      raw: /** @type {import('@internationalized/date').CalendarDate | null} */ (calendarDate ?? null),
+    })
+
+    this.internalValueRef.value = normalized
+
+    const value = this.normalizeToIsoString({ calendarDate: 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
+    )
+  }
+
+  /**
+   * Sync calendar view placeholder when Reka navigates (prev/next buttons).
+   *
+   * @param {{
+   *   calendarDate: import('@internationalized/date').DateValue | null
+   * }} params - Parameters of this method.
+   */
+  onPlaceholderChange ({
+    calendarDate,
+  }) {
+    this.placeholderRef.value = this.normalizeToCalendarDate({
+      raw: /** @type {import('@internationalized/date').CalendarDate | null} */ (calendarDate ?? null),
+    })
+  }
+
+  /**
+   * Navigate the calendar view to a specific month, keeping the current year.
+   *
+   * @param {{
+   *   changeEvent: Event
+   *   currentYear: number
+   * }} params - Parameters of this method.
+   */
+  onMonthChange ({
+    changeEvent,
+    currentYear,
+  }) {
+    const month = /** @type {HTMLSelectElement} */ (changeEvent.target)?.value
+
+    this.placeholderRef.value = new CalendarDate(Number(currentYear), Number(month), 1)
+  }
+
+  /**
+   * Navigate the calendar view to a specific year, keeping the current month.
+   *
+   * @param {{
+   *   changeEvent: Event
+   *   currentMonth: number
+   * }} params - Parameters of this method.
+   */
+  onYearChange ({
+    changeEvent,
+    currentMonth,
+  }) {
+    const year = /** @type {HTMLSelectElement} */ (changeEvent.target)?.value
+
+    this.placeholderRef.value = new CalendarDate(Number(year), Number(currentMonth), 1)
+  }
+
+  /**
+   * Select today's date (clamped into the `[minValue, maxValue]` window) from the footer
+   * "Today" button, navigating the calendar view to it and emitting the change trio.
+   */
+  onSelectToday () {
+    const todayDate = this.clampDateToBounds({
+      date: today(getLocalTimeZone()),
+    })
+
+    this.placeholderRef.value = todayDate
+
+    this.onChangeValue({
+      calendarDate: todayDate,
+    })
+  }
+
+  /**
+   * Clear the selected value from the footer "Clear" button, emitting the change trio with
+   * `null`.
+   */
+  onClearValue () {
+    this.onChangeValue({
+      calendarDate: null,
+    })
+  }
+
+  /**
+   * Extract the 12 calendar months for the month dropdown.
+   *
+   * @returns {{ value: number, label: string }[]}
+   */
+  extractCalendarMonths () {
+    return CALENDAR_MONTHS
+  }
+
+  /**
+   * Extract the year range for the year dropdown.
+   * Respects `minValue`/`maxValue` parcel constraints; defaults to ±100/+50 from today.
+   *
+   * @returns {{ value: number }[]}
+   */
+  extractCalendarYears () {
+    const currentYear = new Date()
+      .getFullYear()
+
+    const minYear = this.normalizeMinValue()?.year ?? (currentYear - 100)
+    const maxYear = this.normalizeMaxValue()?.year ?? (currentYear + 50)
+
+    const count = maxYear - minYear + 1
+
+    return Array.from(
+      { length: count },
+      (_, index) => ({ value: minYear + index })
+    )
+  }
+
+  /**
+   * Whether the part is a slash character part.
+   *
+   * @param {{ part: import('reka-ui').SegmentPart }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  isSlashCharacterPart ({
+    part,
+  }) {
+    return part === 'literal'
+  }
+
+  /**
+   * Format a date field segment value for display. Day and month segments are zero-padded to
+   * two digits (e.g. `3` → `03`, `5` → `05`) so the field always shows `dd`/`mm`; placeholder
+   * text, the year, and literals pass through unchanged. The underlying primitive renders
+   * filled day/month segments with single-digit (`numeric`) formatting, so this restores the
+   * 2-digit display.
+   *
+   * @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 (day or month).
+   *
+   * @param {{ part: import('reka-ui').SegmentPart }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  isTwoDigitSegmentPart ({
+    part,
+  }) {
+    return [
+      'day',
+      'month',
+    ]
+      .includes(part)
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     triggerElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<import('@internationalized/date').CalendarDate | null>
+ *     placeholderRef: import('vue').Ref<import('@internationalized/date').CalendarDate | null>
+ *   }
+ * }} FuroDatePickerContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroDatePickerContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     triggerElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<import('@internationalized/date').CalendarDate | null>
+ *     placeholderRef: import('vue').Ref<import('@internationalized/date').CalendarDate | null>
+ *   }
+ * }} FuroDatePickerContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroDatePickerContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: DatePickerParcel | null
+ *   triggerParcel?: Record<string, unknown> | null
+ *   contentParcel?: Record<string, unknown> | null
+ * }} Props
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {
+ *   value?: string | null
+ *   invalid?: boolean
+ *   placeholder?: string | null
+ *   disabled?: boolean
+ *   minValue?: string | null
+ *   maxValue?: string | null
+ *   displayFormat?: string | null
+ *   timezone?: string | null
+ *   closeOnSelect?: boolean | null
+ *   preventDeselect?: boolean | null
+ *   locale?: string | null
+ *   todayButtonText?: string | null
+ *   clearButtonText?: string | null
+ * }} DatePickerParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroDatePickerEmitHash>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroDatePickerContext.EMIT_EVENT_HASH} FuroDatePickerEmitHash
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroDatePickerContext
+ * }} FuroDatePickerSetup
+ */