@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroSelect/FuroSelectContext.js

@@ -0,0 +1,743 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import SelectEmitPayload from './SelectEmitPayload.js'
+
+/**
+ * Context class for managing FuroSelect component.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroSelectContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroSelectContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroSelectContext ? X : never} T, X
+   * @override
+   * @param {FuroSelectContextFactoryParams} 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 {FuroSelectContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      triggerElementRef: ref(null),
+      internalValueRef: ref(null),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @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 options.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./SelectEmitPayload.js').default) => void
+   *   'commit-value': (payload: import('./SelectEmitPayload.js').default) => void
+   *   'update:value': (value: FuroSelectValue | Array<FuroSelectValue> | 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: Constructor of `EmitPayload`.
+   *
+   * @returns {typeof SelectEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return SelectEmitPayload
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroSelectContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroSelectContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get trigger element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get triggerElementRef () {
+    return this.refHash.triggerElementRef
+  }
+
+  /**
+   * Get internal value ref.
+   *
+   * @returns {import('vue').Ref<FuroSelectValue | Array<FuroSelectValue>>}
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {Props['parcel']}
+   */
+  get parcel () {
+    return this.props.parcel
+      ?? null
+  }
+
+  /**
+   * Get trigger attributes.
+   *
+   * @returns {Props['triggerParcel']}
+   */
+  get triggerParcel () {
+    return this.props.triggerParcel
+      ?? null
+  }
+
+  /**
+   * Get portal attributes.
+   *
+   * @returns {Props['portalParcel']}
+   */
+  get portalParcel () {
+    return this.props.portalParcel
+      ?? null
+  }
+
+  /**
+   * Get content attributes.
+   *
+   * @returns {Props['contentParcel']}
+   */
+  get contentParcel () {
+    return this.props.contentParcel
+      ?? null
+  }
+
+  /**
+   * Get loading.
+   *
+   * @returns {boolean}
+   */
+  get loading () {
+    return this.parcel?.loading
+      ?? false
+  }
+
+  /**
+   * Whether the select is invalid.
+   *
+   * @returns {boolean}
+   */
+  get isInvalid () {
+    return this.parcel?.invalid
+      ?? false
+  }
+
+  /**
+   * Whether the select is multiple.
+   *
+   * @returns {boolean}
+   */
+  get isMultiple () {
+    return this.parcel?.multiple
+      ?? false
+  }
+
+  /**
+   * @returns {Array<import('./SelectEmitPayload.js').FuroSelectOption>}
+   */
+  get options () {
+    return this.parcel?.options
+      ?? []
+  }
+
+  /**
+   * get: how to derive an option's display label — a key name or a function.
+   *
+   * @returns {string | ((option: FuroSelectOption) => string) | null}
+   */
+  get optionLabel () {
+    return this.parcel?.optionLabel
+      ?? null
+  }
+
+  /**
+   * get: how to derive an option's model value — a key name or a function.
+   *
+   * @returns {string | ((option: FuroSelectOption) => FuroSelectValue) | null}
+   */
+  get optionValue () {
+    return this.parcel?.optionValue
+      ?? null
+  }
+
+  /**
+   * Resolve an option's display label.
+   *
+   * Uses `optionLabel` when set (function or key name); otherwise falls back to
+   * the option's own `label` (the historical default).
+   *
+   * @param {{
+   *   option: FuroSelectOption
+   * }} params - Parameters of this method.
+   * @returns {string | null} Display label.
+   */
+  resolveOptionLabel ({
+    option,
+  }) {
+    if (typeof this.optionLabel === 'function') {
+      return this.optionLabel(option)
+    }
+
+    if (typeof this.optionLabel === 'string') {
+      return option?.[this.optionLabel]
+        ?? null
+    }
+
+    return option?.label
+      ?? null
+  }
+
+  /**
+   * Resolve an option's model value.
+   *
+   * Uses `optionValue` when set (function or key name); otherwise falls back to
+   * the option's own `value` (the historical default for FuroSelect).
+   *
+   * @param {{
+   *   option: FuroSelectOption
+   * }} params - Parameters of this method.
+   * @returns {FuroSelectValue} Model value.
+   */
+  resolveOptionValue ({
+    option,
+  }) {
+    if (typeof this.optionValue === 'function') {
+      return this.optionValue(option)
+    }
+
+    if (typeof this.optionValue === 'string') {
+      return option?.[this.optionValue]
+        ?? null
+    }
+
+    return option?.value
+      ?? null
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroSelectContext ? X : never} T, X
+   * @override
+   * @returns {T} - For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.watch(
+      [
+        () => this.parcel?.value,
+        () => this.attrs?.value ?? null,
+        () => this.parcel?.multiple ?? false,
+      ],
+      ([parcelSelectValue, attrsSelectValue, multiple]) => {
+        const nextValue = parcelSelectValue
+          ?? attrsSelectValue
+
+        if (multiple) {
+          this.internalValueRef.value = Array.isArray(nextValue)
+            ? nextValue
+            : []
+
+          return
+        }
+
+        this.internalValueRef.value = nextValue
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Extract root attributes.
+   *
+   * @returns {Props['parcel']}
+   */
+  extractRootAttributes () {
+    /** @type {Record<string, FuroSelectTextDirectionValue>} */
+    const textDirectionMap = {
+      toRight: 'ltr',
+      toLeft: 'rtl',
+    }
+    const textDirection = this.parcel?.textDirection ?? 'toRight'
+    const dir = textDirectionMap[textDirection] ?? 'ltr'
+
+    const {
+      optionLabel,
+      optionValue,
+      ...restParcel
+    } = this.parcel ?? {}
+
+    return {
+      ...this.attrs,
+      ...restParcel,
+      modelValue: this.internalValueRef.value,
+      dir,
+    }
+  }
+
+  /**
+   * Extract trigger attributes.
+   *
+   * @returns {Props['triggerParcel']}
+   */
+  extractTriggerAttributes () {
+    return this.triggerParcel
+  }
+
+  /**
+   * Extract content attributes.
+   *
+   * @returns {Props['contentParcel']}
+   */
+  extractContentAttributes () {
+    return this.contentParcel
+  }
+
+  /**
+   * Extract placeholder.
+   *
+   * @returns {string}
+   */
+  extractPlaceholder () {
+    return this.parcel?.placeholder
+      ?? ''
+  }
+
+  /**
+   * Whether to show the group option.
+   *
+   * @param {{
+   *   option: FuroSelectOption | null
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  shouldShowGroupOption ({
+    option,
+  }) {
+    if (!option?.options) {
+      return false
+    }
+
+    return option.options.length > 0
+  }
+
+  /**
+   * Whether the select has empty options.
+   *
+   * @returns {boolean}
+   */
+  hasEmptyOptions () {
+    return !this.parcel?.options?.length
+      && !this.parcel?.loading
+  }
+
+  /**
+   * Extract group options.
+   *
+   * @param {{
+   *   option: FuroSelectOption | null
+   * }} params - Parameters of this method.
+   * @returns {Array<import('./SelectEmitPayload.js').FuroSelectOption>}
+   */
+  extractGroupOptions ({
+    option,
+  }) {
+    if (!option?.options) {
+      return []
+    }
+
+    return option.options
+  }
+
+  /**
+   * Build a custom event for emit payload construction.
+   *
+   * @param {{
+   *   name: string
+   *   selectedOption: FuroSelectOption | null
+   *   selectedOptions: Array<FuroSelectOption> | null
+   *   selectedIndex: number | null
+   *   selectedGroupIndex: number | null
+   *   selectedIndices: Array<number | null>
+   *   selectedGroupIndices: Array<number | null>
+   * }} params - Parameters of this method.
+   * @returns {CustomEvent<{
+   *   target: HTMLElement | null
+   *   selectedOption: FuroSelectOption | null
+   *   selectedOptions: Array<FuroSelectOption> | null
+   *   selectedIndex: number | null
+   *   selectedGroupIndex: number | null
+   *   selectedIndices: Array<number | null>
+   *   selectedGroupIndices: Array<number | null>
+   * }>}
+   */
+  buildCustomEvent ({
+    name,
+    selectedOption,
+    selectedOptions,
+    selectedIndex,
+    selectedGroupIndex,
+    selectedIndices,
+    selectedGroupIndices,
+  }) {
+    return new CustomEvent(
+      name,
+      {
+        detail: {
+          target: this.triggerElementRef.value,
+          selectedOption,
+          selectedOptions,
+          selectedIndex,
+          selectedGroupIndex,
+          selectedIndices,
+          selectedGroupIndices,
+        },
+      }
+    )
+  }
+
+  /**
+   * @param {{
+   *   options?: Array<FuroSelectOption>
+   * }} params - Parameters of this method.
+   * @returns {Array<FuroSelectOption & {
+   *   groupIndex: number | null
+   *   optionIndex: number
+   * }>}
+   */
+  generateFlattenedOptions ({
+    options = this.options,
+  } = {}) {
+    return options.flatMap(
+      (group, groupIndex) => [group, ...(group?.options ?? [])]
+        .map((option, optionIndex) => ({
+          ...option,
+          groupIndex: group?.options
+            ? groupIndex
+            : null,
+          optionIndex: group?.options
+            ? optionIndex
+            : groupIndex,
+        }))
+    )
+  }
+
+  /**
+   * Handle `update:model-value` from Reka `SelectRoot`.
+   *
+   * @param {{
+   *   selectedValue: FuroSelectValue | Array<FuroSelectValue>
+   * }} params - Parameters of this method.
+   */
+  onChangeValue ({
+    selectedValue,
+  }) {
+    const flattenedOptions = this.generateFlattenedOptions()
+
+    const selectedOption = flattenedOptions.find(
+      it => (Array.isArray(selectedValue)
+        ? selectedValue.some(value => JSON.stringify(this.resolveOptionValue({ option: it })) === JSON.stringify(value))
+        : JSON.stringify(this.resolveOptionValue({ option: it })) === JSON.stringify(selectedValue))
+    ) ?? null
+    const selectedOptions = flattenedOptions.filter(
+      it => Array.isArray(selectedValue) && selectedValue.some(
+        value => JSON.stringify(this.resolveOptionValue({ option: it })) === JSON.stringify(value))
+    )
+
+    const customEvent = this.buildCustomEvent({
+      name: this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      selectedOption,
+      selectedOptions,
+      selectedIndex: selectedOption?.optionIndex ?? null,
+      selectedGroupIndex: selectedOption?.groupIndex ?? null,
+      selectedIndices: selectedOptions.map(it => it?.optionIndex),
+      selectedGroupIndices: selectedOptions.map(it => it?.groupIndex),
+    })
+
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent: customEvent,
+    })
+
+    this.internalValueRef.value = selectedValue
+
+    this.emit(
+      this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      payload
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.COMMIT_VALUE,
+      payload
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_VALUE,
+      this.extractUpdateValue({
+        selectedValue,
+        selectedOption,
+      })
+    )
+  }
+
+  /**
+   * Resolve the value emitted via `update:value`.
+   *
+   * In multiple mode this is the full array of selected model values (the
+   * underlying model array, already in `optionValue` space); otherwise it is the
+   * single resolved value of the matched option.
+   *
+   * @param {{
+   *   selectedValue: FuroSelectValue | Array<FuroSelectValue>
+   *   selectedOption: FuroSelectOption | null
+   * }} params - Parameters of this method.
+   * @returns {FuroSelectValue | Array<FuroSelectValue>}
+   */
+  extractUpdateValue ({
+    selectedValue,
+    selectedOption,
+  }) {
+    if (!this.isMultiple) {
+      return this.resolveOptionValue({
+        option: selectedOption,
+      })
+    }
+
+    return Array.isArray(selectedValue)
+      ? selectedValue
+      : []
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     triggerElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<FuroSelectValue | Array<FuroSelectValue>>
+ *   }
+ * }} FuroSelectContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroSelectContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     triggerElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<FuroSelectValue>
+ *   }
+ * }} FuroSelectContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroSelectContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * A value FuroSelect can bind — a primitive, a whole option object, or null.
+ * Self-defined so the public value contract does not depend on the internal
+ * headless library.
+ *
+ * @typedef {string | number | bigint | Record<string, unknown> | null} FuroSelectValue
+ */
+
+/**
+ * Text-flow direction resolved for the control.
+ *
+ * @typedef {'ltr' | 'rtl'} FuroSelectTextDirectionValue
+ */
+
+/*
+ * --- Internal headless-library type adapter ---
+ * The ONLY place in FuroSelect that references the underlying headless library
+ * (`Reka`). Every other type below uses the Furo-named aliases here, so swapping
+ * the library later means editing only this block.
+ */
+
+/**
+ * @typedef {Reka.SelectRootProps} FuroSelectRootParcelBase
+ */
+
+/**
+ * @typedef {Reka.SelectTriggerProps} FuroSelectTriggerParcel
+ */
+
+/**
+ * @typedef {Reka.SelectPortalProps} FuroSelectPortalParcel
+ */
+
+/**
+ * @typedef {Reka.SelectContentProps} FuroSelectContentParcel
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroSelectRootParcelBase & ExtraRootParcel | null
+ *   triggerParcel?: FuroSelectTriggerParcel | null
+ *   portalParcel?: FuroSelectPortalParcel | null
+ *   contentParcel?: FuroSelectContentParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {Record<string, unknown> & {
+ *   placeholder?: string | null
+ *   loading?: boolean
+ *   invalid?: boolean
+ *   textDirection?: 'toRight' | 'toLeft'
+ *   options?: Array<FuroSelectOption>
+ *   optionLabel?: string | ((option: FuroSelectOption) => string)
+ *   optionValue?: string | ((option: FuroSelectOption) => FuroSelectValue)
+ * }} ExtraRootParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroSelectEmitHash, FuroSelectSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   'trigger-content': {}
+ *   'trigger-text': {}
+ *   'trigger-icon': {}
+ *   'trigger-loading-icon': {}
+ *   'scroll-up-button': {}
+ *   'scroll-down-button': {}
+ *   'content-before': {}
+ *   'content-after': {}
+ *   group: {
+ *     group: FuroSelectOption
+ *     groupIndex: number
+ *   }
+ *   'group-label': {
+ *     group: FuroSelectOption
+ *     groupIndex: number
+ *   }
+ *   option: {
+ *     option: FuroSelectOption
+ *     optionIndex: number
+ *     group?: FuroSelectOption
+ *     groupIndex?: number
+ *   }
+ *   'option-text': {
+ *     option: FuroSelectOption
+ *     optionIndex: number
+ *   }
+ *   'option-indicator': {
+ *     option: FuroSelectOption
+ *     optionIndex: number
+ *   }
+ *   'separator': {
+ *     option: FuroSelectOption
+ *     optionIndex: number
+ *   }
+ *   empty: {
+ *     loading: boolean
+ *   }
+ * }>} FuroSelectSlots
+ */
+
+/**
+ * @typedef {typeof FuroSelectContext.EMIT_EVENT_HASH} FuroSelectEmitHash
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroSelectContext
+ * }} FuroSelectSetup
+ */
+
+/**
+ * @typedef {import('./SelectEmitPayload.js').FuroSelectOption} FuroSelectOption
+ */
+
+/**
+ * @import * as Reka from 'reka-ui'
+ */