@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroDateTimePicker/FuroDateTimePickerContext.js

@@ -0,0 +1,840 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import DateTimePickerEmitPayload from './DateTimePickerEmitPayload.js'
+
+/**
+ * Furo-only parcel keys that are not forwarded to the composed date atom.
+ * The molecule owns these and derives the child parcels explicitly.
+ */
+export const FURO_DATE_TIME_PICKER_PARCEL_KEYS = new Set([
+  'value',
+  'invalid',
+  'placeholder',
+  'disabled',
+  'minValue',
+  'maxValue',
+  'timezone',
+  'granularity',
+  'step',
+  'timeFormat',
+])
+
+/**
+ * Default time part used to recombine when only a date is present but a complete
+ * value is requested. The molecule never fabricates this into an emit (Q2) — it is
+ * only the seconds-padding default for the wire format (Q4).
+ */
+const DEFAULT_TIME_SECONDS = '00'
+
+/**
+ * Time part fabricated the first time a date is selected without an existing time, so the
+ * combined value becomes complete immediately while the popover stays open for the user to
+ * refine the time (UAT decision: default to noon).
+ */
+const DEFAULT_TIME_PART = '12:00:00'
+
+/**
+ * Context class for managing FuroDateTimePicker molecule.
+ *
+ * Composes `FuroDatePicker` (calendar) and `FuroTimeField` (segmented time) into a
+ * single popover and exposes one combined `v-model:value` as a canonical
+ * `YYYY-MM-DDTHH:MM:SS` string (timezone-naive v1).
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroDateTimePickerContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroDateTimePickerContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroDateTimePickerContext ? X : never} T, X
+   * @override
+   * @param {FuroDateTimePickerContextFactoryParams} 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 {FuroDateTimePickerContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      rootElementRef: ref(null),
+      datePartRef: ref(null),
+      timePartRef: 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('./DateTimePickerEmitPayload.js').default) => void
+   *   'commit-value': (payload: import('./DateTimePickerEmitPayload.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 DateTimePickerEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return DateTimePickerEmitPayload
+  }
+
+  /**
+   * Split a combined ISO `YYYY-MM-DDTHH:MM:SS` string into its date and time parts.
+   * Returns `null` parts for any value that does not contain the matching segment.
+   *
+   * @param {{
+   *   value: string | null
+   * }} params - Parameters of this method.
+   * @returns {{
+   *   datePart: string | null
+   *   timePart: string | null
+   * }}
+   */
+  static splitValue ({
+    value,
+  }) {
+    if (!value) {
+      return {
+        datePart: null,
+        timePart: null,
+      }
+    }
+
+    const [
+      datePartRaw,
+      timePartRaw = null,
+    ] = value.split('T')
+
+    const datePart = this.blankToNull({ segment: datePartRaw })
+    const timePart = this.blankToNull({ segment: timePartRaw })
+
+    return {
+      datePart,
+      timePart,
+    }
+  }
+
+  /**
+   * Normalize a blank (empty / nullish) string segment to `null`.
+   *
+   * @param {{
+   *   segment: string | null
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  static blankToNull ({
+    segment,
+  }) {
+    if (!segment) {
+      return null
+    }
+
+    return segment
+  }
+
+  /**
+   * Combine a date part and a time part into a canonical `YYYY-MM-DDTHH:MM:SS` string.
+   * Returns `null` until BOTH parts are present (Q2 — never fabricates a default time).
+   * The time part is normalized to second precision (`HH:MM:SS`, seconds default `00` — Q4).
+   *
+   * @param {{
+   *   datePart: string | null
+   *   timePart: string | null
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  static combineValue ({
+    datePart,
+    timePart,
+  }) {
+    if (
+      !datePart
+      || !timePart
+    ) {
+      return null
+    }
+
+    const normalizedTime = this.normalizeTimeToSeconds({ timePart })
+
+    return `${datePart}T${normalizedTime}`
+  }
+
+  /**
+   * Pad a time part to second precision (`HH:MM` → `HH:MM:SS`).
+   *
+   * @param {{
+   *   timePart: string
+   * }} params - Parameters of this method.
+   * @returns {string}
+   */
+  static normalizeTimeToSeconds ({
+    timePart,
+  }) {
+    const segments = timePart.split(':')
+
+    const hour = segments[0] ?? '00'
+    const minute = segments[1] ?? '00'
+    const second = segments[2] ?? DEFAULT_TIME_SECONDS
+
+    return [
+      hour,
+      minute,
+      second,
+    ].join(':')
+  }
+
+  /**
+   * Get the constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroDateTimePickerContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroDateTimePickerContext} */ (this.constructor)
+  }
+
+  /**
+   * Get root element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get rootElementRef () {
+    return this.refHash.rootElementRef
+  }
+
+  /**
+   * Get the current date part ref (`YYYY-MM-DD` | `null`).
+   *
+   * @returns {import('vue').Ref<string | null>}
+   */
+  get datePartRef () {
+    return this.refHash.datePartRef
+  }
+
+  /**
+   * Get the current time part ref (`HH:MM:SS` | `null`).
+   *
+   * @returns {import('vue').Ref<string | null>}
+   */
+  get timePartRef () {
+    return this.refHash.timePartRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {Props['parcel']}
+   */
+  get parcel () {
+    return this.props.parcel
+      ?? null
+  }
+
+  /**
+   * Current date part (`YYYY-MM-DD` | `null`).
+   *
+   * @returns {string | null}
+   */
+  get datePart () {
+    return this.datePartRef.value
+      ?? null
+  }
+
+  /**
+   * Current time part (`HH:MM:SS` | `null`).
+   *
+   * @returns {string | null}
+   */
+  get timePart () {
+    return this.timePartRef.value
+      ?? null
+  }
+
+  /**
+   * Placeholder text.
+   *
+   * @returns {string}
+   */
+  get placeholder () {
+    return this.parcel?.placeholder
+      ?? ''
+  }
+
+  /**
+   * IANA timezone identifier forwarded to both atoms (naive v1; atoms own normalization).
+   *
+   * @returns {string | null}
+   */
+  get timezone () {
+    return this.parcel?.timezone
+      ?? null
+  }
+
+  /**
+   * Segment granularity forwarded to the time atom (`hour` | `minute` | `second`).
+   *
+   * @returns {string | null}
+   */
+  get granularity () {
+    return this.parcel?.granularity
+      ?? null
+  }
+
+  /**
+   * Step amount forwarded to the time atom's steppers.
+   *
+   * @returns {number | null}
+   */
+  get step () {
+    return this.parcel?.step
+      ?? null
+  }
+
+  /**
+   * Time format (12 or 24) forwarded to the time atom.
+   *
+   * @returns {number | null}
+   */
+  get timeFormat () {
+    return this.parcel?.timeFormat
+      ?? null
+  }
+
+  /**
+   * Combined minimum datetime (`YYYY-MM-DDTHH:MM:SS` | `null`).
+   *
+   * @returns {string | null}
+   */
+  get minValue () {
+    return this.parcel?.minValue
+      ?? null
+  }
+
+  /**
+   * Combined maximum datetime (`YYYY-MM-DDTHH:MM:SS` | `null`).
+   *
+   * @returns {string | null}
+   */
+  get maxValue () {
+    return this.parcel?.maxValue
+      ?? null
+  }
+
+  /**
+   * Whether the control is in an invalid state.
+   *
+   * @returns {boolean}
+   */
+  get isInvalid () {
+    return this.parcel?.invalid
+      ?? false
+  }
+
+  /**
+   * Whether the control is disabled.
+   *
+   * @returns {boolean}
+   */
+  get isDisabled () {
+    return this.parcel?.disabled
+      ?? false
+  }
+
+  /**
+   * Whether a date part is currently set.
+   *
+   * @returns {boolean}
+   */
+  get hasDate () {
+    return this.datePart !== null
+  }
+
+  /**
+   * Whether a time part is currently set.
+   *
+   * @returns {boolean}
+   */
+  get hasTime () {
+    return this.timePart !== null
+  }
+
+  /**
+   * Whether both date and time parts are set (a complete combined value exists — Q2).
+   *
+   * @returns {boolean}
+   */
+  get hasCompleteValue () {
+    return this.hasDate
+      && this.hasTime
+  }
+
+  /**
+   * Setup component — split the external combined value into date/time part refs.
+   *
+   * @template {X extends FuroDateTimePickerContext ? 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.syncFromExternalValue({ raw })
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Sync the internal date/time parts from an external combined value.
+   *
+   * Skips when the external value already equals what the current parts combine to. This
+   * preserves an in-progress part — e.g. a time picked before a date — from being wiped by
+   * the molecule's own `null` echo through the parent's `v-model` (Q2 emits `null` until both
+   * parts are set, so stepping the time before choosing a date would otherwise reset itself).
+   *
+   * @param {{
+   *   raw: string | null
+   * }} params - Parameters of this method.
+   */
+  syncFromExternalValue ({
+    raw,
+  }) {
+    const currentCombined = this.Ctor.combineValue({
+      datePart: this.datePart,
+      timePart: this.timePart,
+    })
+
+    if (raw === currentCombined) {
+      return
+    }
+
+    const {
+      datePart,
+      timePart,
+    } = this.Ctor.splitValue({ value: raw })
+
+    this.datePartRef.value = datePart
+    this.timePartRef.value = timePart
+  }
+
+  /**
+   * Derive the parcel forwarded to the composed `FuroDatePicker`.
+   * Strips molecule-only keys, then re-applies the date-scoped value and bounds.
+   * Optional value attributes are omitted when `null` (F-3 parity).
+   *
+   * `modal: true` is forced so the popover traps focus (reka renders `PopoverContentModal`
+   * → `FocusScope` with `trapped`). Without it the non-modal popover lets Tab escape the
+   * teleported content and jump to the inline time field in the trigger, breaking the
+   * calendar → time-field focus order.
+   *
+   * `closeOnSelect: false` keeps the popover open after a date is picked, so the user can set
+   * the time in the same session (the date atom defaults to closing on select).
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractDateParcel () {
+    const passthrough = this.stripFuroParcelKeys()
+
+    const entries = [
+      ['value', this.datePart],
+      ['placeholder', this.placeholder || null],
+      ['minValue', this.extractDateBound({ bound: this.minValue })],
+      ['maxValue', this.extractDateBound({ bound: this.maxValue })],
+      ['timezone', this.timezone],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return {
+      ...passthrough,
+      ...Object.fromEntries(entries),
+      invalid: this.isInvalid,
+      disabled: this.isDisabled,
+      modal: true,
+      closeOnSelect: false,
+    }
+  }
+
+  /**
+   * Derive the parcel forwarded to the composed `FuroTimeField`.
+   * Strips molecule-only keys, then re-applies the time-scoped value and cross-field bounds.
+   * Optional value attributes are omitted when `null` (F-3 parity).
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractTimeParcel () {
+    const passthrough = this.stripFuroParcelKeys()
+
+    const entries = [
+      ['value', this.timePart],
+      ['granularity', this.granularity],
+      ['step', this.step],
+      ['timeFormat', this.timeFormat],
+      ['timezone', this.timezone],
+      ['minValue', this.extractTimeMinBound()],
+      ['maxValue', this.extractTimeMaxBound()],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return {
+      ...passthrough,
+      ...Object.fromEntries(entries),
+      invalid: this.isInvalid,
+      disabled: this.isDisabled,
+    }
+  }
+
+  /**
+   * Strip Furo-only molecule parcel keys, leaving only consumer passthrough attributes.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  stripFuroParcelKeys () {
+    const { parcel } = this
+
+    if (!parcel) {
+      return {}
+    }
+
+    const entries = Object.entries(parcel)
+      .filter(([key]) => !FURO_DATE_TIME_PICKER_PARCEL_KEYS.has(key))
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Extract the date part of a combined datetime bound for the date atom.
+   *
+   * @param {{
+   *   bound: string | null
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  extractDateBound ({
+    bound,
+  }) {
+    return this.Ctor.splitValue({ value: bound })
+      .datePart
+  }
+
+  /**
+   * Cross-field minimum TIME bound (Q3): applies only when the selected date equals the
+   * minimum date; otherwise the full day is allowed (`null`).
+   *
+   * @returns {string | null}
+   */
+  extractTimeMinBound () {
+    return this.extractCrossFieldTimeBound({ bound: this.minValue })
+  }
+
+  /**
+   * Cross-field maximum TIME bound (Q3): applies only when the selected date equals the
+   * maximum date; otherwise the full day is allowed (`null`).
+   *
+   * @returns {string | null}
+   */
+  extractTimeMaxBound () {
+    return this.extractCrossFieldTimeBound({ bound: this.maxValue })
+  }
+
+  /**
+   * Resolve a cross-field time bound: the bound's time part applies only when the currently
+   * selected date equals the bound's date part (Q3). Returns `null` (full day) otherwise.
+   *
+   * @param {{
+   *   bound: string | null
+   * }} params - Parameters of this method.
+   * @returns {string | null}
+   */
+  extractCrossFieldTimeBound ({
+    bound,
+  }) {
+    const {
+      datePart: boundDatePart,
+      timePart: boundTimePart,
+    } = this.Ctor.splitValue({ value: bound })
+
+    if (
+      boundDatePart === null
+      || this.datePart !== boundDatePart
+    ) {
+      return null
+    }
+
+    return boundTimePart
+  }
+
+  /**
+   * Build a custom event carrying the combined value for the emit payload.
+   *
+   * @param {{
+   *   name: string
+   *   value: string | null
+   * }} params - Parameters of this method.
+   * @returns {CustomEvent<{
+   *   target: HTMLElement | null
+   *   value: string | null
+   *   datePart: string | null
+   *   timePart: string | null
+   * }>}
+   */
+  buildCustomEvent ({
+    name,
+    value,
+  }) {
+    return new CustomEvent(
+      name,
+      {
+        detail: {
+          target: this.rootElementRef.value,
+          value,
+          datePart: this.datePart,
+          timePart: this.timePart,
+        },
+      }
+    )
+  }
+
+  /**
+   * Respond to the composed date atom's `update:value`.
+   * Updates the date part, preserves the existing time part, and re-emits the trio.
+   *
+   * @param {{
+   *   value: string | null
+   * }} params - Parameters of this method.
+   */
+  onDateChange ({
+    value,
+  }) {
+    this.datePartRef.value = this.Ctor.blankToNull({ segment: value })
+
+    this.syncTimeWithDateSelection()
+
+    this.emitCombinedValue()
+  }
+
+  /**
+   * Reconcile the time part after a date change. Clearing the date (the footer Clear button,
+   * with `preventDeselect` on) also clears the time so the whole value resets; selecting a
+   * date fabricates the default time when none is set yet.
+   */
+  syncTimeWithDateSelection () {
+    if (this.datePart === null) {
+      this.timePartRef.value = null
+
+      return
+    }
+
+    this.applyDefaultTimeOnDateSelection()
+  }
+
+  /**
+   * Fabricate a default time (`12:00:00`) the first time a date is selected without an
+   * existing time, so the combined value becomes complete immediately while the popover stays
+   * open for the user to refine the time. No-op when no date is set or a time already exists.
+   */
+  applyDefaultTimeOnDateSelection () {
+    if (
+      this.datePart === null
+      || this.timePart !== null
+    ) {
+      return
+    }
+
+    this.timePartRef.value = DEFAULT_TIME_PART
+  }
+
+  /**
+   * Respond to the composed time atom's `update:value`.
+   * Updates the time part, preserves the existing date part, and re-emits the trio.
+   *
+   * @param {{
+   *   value: string | null
+   * }} params - Parameters of this method.
+   */
+  onTimeChange ({
+    value,
+  }) {
+    this.timePartRef.value = this.Ctor.blankToNull({ segment: value })
+
+    this.emitCombinedValue()
+  }
+
+  /**
+   * Recombine the current parts and emit `change-value`, `update:value`, `commit-value`.
+   * Emits `null` until both parts are present (Q2).
+   */
+  emitCombinedValue () {
+    const value = this.Ctor.combineValue({
+      datePart: this.datePart,
+      timePart: this.timePart,
+    })
+
+    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
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     rootElementRef: import('vue').Ref<HTMLElement | null>
+ *     datePartRef: import('vue').Ref<string | null>
+ *     timePartRef: import('vue').Ref<string | null>
+ *   }
+ * }} FuroDateTimePickerContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroDateTimePickerContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     rootElementRef: import('vue').Ref<HTMLElement | null>
+ *     datePartRef: import('vue').Ref<string | null>
+ *     timePartRef: import('vue').Ref<string | null>
+ *   }
+ * }} FuroDateTimePickerContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroDateTimePickerContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: DateTimePickerParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {
+ *   value?: string | null
+ *   invalid?: boolean
+ *   placeholder?: string | null
+ *   disabled?: boolean
+ *   minValue?: string | null
+ *   maxValue?: string | null
+ *   timezone?: string | null
+ *   granularity?: 'hour' | 'minute' | 'second' | null
+ *   step?: number | null
+ *   timeFormat?: number | null
+ * }} DateTimePickerParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroDateTimePickerEmitHash>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroDateTimePickerContext.EMIT_EVENT_HASH} FuroDateTimePickerEmitHash
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroDateTimePickerContext
+ * }} FuroDateTimePickerSetup
+ */