@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroAutocompleteField/FuroAutocompleteFieldContext.js

@@ -0,0 +1,1525 @@
+import {
+  ref,
+} from 'vue'
+
+import TimerClerk from '../../../tools/TimerClerk.js'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import AutocompleteEmitPayload from './AutocompleteEmitPayload.js'
+
+/**
+ * Sentinel value for the select-all option (not stored in model).
+ */
+export const FURO_AUTOCOMPLETE_FIELD_SELECT_ALL_VALUE = '__furo_autocomplete_field_select_all__'
+
+/**
+ * Sentinel value for the create-option row (not stored in model).
+ */
+export const FURO_AUTOCOMPLETE_FIELD_CREATE_VALUE = '__furo_autocomplete_field_create__'
+
+/**
+ * Context class for managing FuroAutocompleteField component.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroAutocompleteFieldContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroAutocompleteFieldContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+
+    filterCollator,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+
+    this.filterCollator = filterCollator
+
+    this.updateSearchKeywordTimerClerk = null
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroAutocompleteFieldContext ? X : never} T, X
+   * @override
+   * @param {FuroAutocompleteFieldContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    refHash = this.buildRefHash(),
+
+    filterCollator,
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        refHash,
+
+        filterCollator,
+      })
+    )
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @override
+   * @returns {FuroAutocompleteFieldContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      triggerContentElementRef: ref(null),
+      internalValueRef: ref(null),
+      internalSearchKeywordRef: ref(''),
+      internalOpenPopoverRef: ref(false),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   CHANGE_VALUE: 'change-value'
+   *   COMMIT_VALUE: 'commit-value'
+   *   UPDATE_VALUE: 'update:value'
+   *   SEARCH_KEYWORD: 'search-keyword'
+   *   UPDATE_SEARCH_KEYWORD: 'update:search-keyword'
+   *   UPDATE_OPEN: 'update:open'
+   *   CREATE_OPTION: 'create-option'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      CHANGE_VALUE: 'change-value',
+      COMMIT_VALUE: 'commit-value',
+      UPDATE_VALUE: 'update:value',
+      SEARCH_KEYWORD: 'search-keyword',
+      UPDATE_SEARCH_KEYWORD: 'update:search-keyword',
+      UPDATE_OPEN: 'update:open',
+      CREATE_OPTION: 'create-option',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./AutocompleteEmitPayload.js').default) => void
+   *   'commit-value': (payload: import('./AutocompleteEmitPayload.js').default) => void
+   *   'update:value': (value: FuroAutocompleteOption | null) => void
+   *   'update:search-keyword': (searchKeyword: string) => void
+   *   'search-keyword': (payload: { searchKeyword: string }) => void
+   *   'update:open': (isOpen: boolean) => void
+   *   'create-option': (payload: import('./AutocompleteEmitPayload.js').default) => 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 => {},
+      [this.EMIT_EVENT_NAME.UPDATE_SEARCH_KEYWORD]: searchKeyword => {},
+      [this.EMIT_EVENT_NAME.SEARCH_KEYWORD]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_OPEN]: isOpen => {},
+      [this.EMIT_EVENT_NAME.CREATE_OPTION]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of `EmitPayload`.
+   *
+   * @returns {typeof AutocompleteEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return AutocompleteEmitPayload
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroAutocompleteFieldContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroAutocompleteFieldContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get anchor trigger-content element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get triggerContentElementRef () {
+    return this.refHash.triggerContentElementRef
+  }
+
+  /**
+   * Get internal value ref.
+   *
+   * @returns {import('vue').Ref<FuroAutocompleteOption | Array<FuroAutocompleteOption> | FuroAcceptableValue | Array<FuroAcceptableValue> | null>}
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Get internal search keyword ref.
+   *
+   * @returns {import('vue').Ref<string>}
+   */
+  get internalSearchKeywordRef () {
+    return this.refHash.internalSearchKeywordRef
+  }
+
+  /**
+   * Get internal open ref.
+   *
+   * @returns {import('vue').Ref<boolean>}
+   */
+  get internalOpenPopoverRef () {
+    return this.refHash.internalOpenPopoverRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {Props['parcel']}
+   */
+  get parcel () {
+    return {
+      showClear: true,
+      localCompare: true,
+      debounceMilliseconds: 300,
+      openOnClick: true,
+      showSelectAll: false,
+      emptyText: 'No options.',
+      selectAllText: 'Select All',
+      textDirection: 'toRight',
+      placeholder: 'Select an option',
+      creatable: false,
+      createOptionText: 'Create "{keyword}"',
+      chipOverflow: 'wrap',
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Get loading.
+   *
+   * @returns {boolean}
+   */
+  get loading () {
+    return this.parcel?.loading
+      ?? false
+  }
+
+  /**
+   * Whether the autocomplete is invalid.
+   *
+   * @returns {boolean}
+   */
+  get isInvalid () {
+    return this.parcel?.invalid
+      ?? false
+  }
+
+  /**
+   * Whether the autocomplete is disabled.
+   *
+   * @returns {boolean}
+   */
+  get isDisabled () {
+    return this.parcel?.disabled
+      ?? false
+  }
+
+  /**
+   * Whether the autocomplete is multiple.
+   *
+   * @returns {boolean}
+   */
+  get isMultiple () {
+    return this.parcel?.multiple
+      ?? false
+  }
+
+  /**
+   * Whether the autocomplete allows creating new options.
+   *
+   * @returns {boolean}
+   */
+  get creatable () {
+    return this.parcel?.creatable
+      ?? false
+  }
+
+  /**
+   * @returns {Array<FuroAutocompleteOption | FuroAcceptableValue>}
+   */
+  get options () {
+    return this.parcel?.options
+      ?? []
+  }
+
+  /**
+   * get: maximum number of chips to render before collapsing the rest into a
+   * `+{count}` indicator. Null means no cap (render every chip).
+   *
+   * @returns {number | null}
+   */
+  get maxVisibleChips () {
+    return this.parcel?.maxVisibleChips
+      ?? null
+  }
+
+  /**
+   * get: how chips behave when they exceed the trigger width — `'wrap'` (chips
+   * flow onto multiple lines) or `'ellipsis'` (single line, truncated).
+   *
+   * @returns {'wrap' | 'ellipsis'}
+   */
+  get chipOverflow () {
+    return this.parcel?.chipOverflow
+      ?? 'wrap'
+  }
+
+  /**
+   * Selected options currently held as chips (multiple mode).
+   *
+   * @returns {Array<FuroAutocompleteOption | FuroAcceptableValue>}
+   */
+  extractSelectedChips () {
+    if (!Array.isArray(this.internalValueRef.value)) {
+      return []
+    }
+
+    return this.internalValueRef.value
+  }
+
+  /**
+   * Chips to actually render — capped at `maxVisibleChips` when set.
+   *
+   * @returns {Array<FuroAutocompleteOption | FuroAcceptableValue>}
+   */
+  extractVisibleChips () {
+    const chips = this.extractSelectedChips()
+
+    if (this.maxVisibleChips === null) {
+      return chips
+    }
+
+    return chips.slice(0, this.maxVisibleChips)
+  }
+
+  /**
+   * Number of selected chips hidden by the `maxVisibleChips` cap.
+   *
+   * @returns {number}
+   */
+  extractHiddenChipCount () {
+    return this.extractSelectedChips().length
+      - this.extractVisibleChips().length
+  }
+
+  /**
+   * Whether the `+{count}` overflow indicator should be shown.
+   *
+   * @returns {boolean}
+   */
+  hasHiddenChips () {
+    return this.extractHiddenChipCount() > 0
+  }
+
+  /**
+   * Whether chips render on a single truncated line (`chipOverflow: 'ellipsis'`).
+   *
+   * @returns {boolean}
+   */
+  hasEllipsisChipOverflow () {
+    return this.chipOverflow === 'ellipsis'
+  }
+
+  /**
+   * get: how to derive an option's display label — a key name or a function.
+   *
+   * @returns {string | ((option: FuroAutocompleteOption | FuroAcceptableValue) => 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: FuroAutocompleteOption | FuroAcceptableValue) => FuroAcceptableValue) | 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). Primitive options fall
+   * through to the caller (returns null) unless a function is given.
+   *
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {string | null} Display label, or null for primitives without a function.
+   */
+  resolveOptionLabel ({
+    option,
+  }) {
+    if (typeof this.optionLabel === 'function') {
+      return this.optionLabel(option)
+    }
+
+    if (typeof option !== 'object' || option === null) {
+      return null
+    }
+
+    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 whole option (the historical default for FuroAutocompleteField).
+   *
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {*} Model value.
+   */
+  resolveOptionValue ({
+    option,
+  }) {
+    if (typeof this.optionValue === 'function') {
+      return this.optionValue(option)
+    }
+
+    if (typeof this.optionValue !== 'string') {
+      return option
+    }
+
+    if (typeof option !== 'object' || option === null) {
+      return null
+    }
+
+    return option[this.optionValue]
+      ?? null
+  }
+
+  /**
+   * Resolve the value emitted via `update:value` from the current internal
+   * selection, mapping each selected option through `resolveOptionValue`.
+   *
+   * @returns {*} Emitted value — an array in multiple mode, a single value otherwise.
+   */
+  resolveEmittedValue () {
+    const selected = this.internalValueRef.value
+
+    if (Array.isArray(selected)) {
+      return selected.map(option => this.resolveOptionValue({ option }))
+    }
+
+    return this.resolveOptionValue({
+      option: selected,
+    })
+  }
+
+  /**
+   * Find the option whose resolved model value equals the given value.
+   *
+   * @param {{
+   *   value: *
+   * }} params - Parameters of this method.
+   * @returns {FuroAutocompleteOption | FuroAcceptableValue | null} Matching option, or null.
+   */
+  findOptionByValue ({
+    value,
+  }) {
+    const flattenedOptions = this.options.flatMap(option => (
+      (option !== null && typeof option === 'object' && Array.isArray(option.options))
+        ? [
+          option,
+          ...option.options,
+        ]
+        : [option]
+    ))
+
+    const matchedOption = flattenedOptions.find(option =>
+      JSON.stringify(this.resolveOptionValue({ option })) === JSON.stringify(value)
+    )
+
+    return matchedOption
+      ?? null
+  }
+
+  /**
+   * Reverse the `optionValue` projection when ingesting a bound value.
+   *
+   * The internal model is kept in option space (the underlying combobox binds
+   * whole option objects), but `optionValue` makes `update:value` emit a
+   * projected value (e.g. an id). When the consumer feeds that projected value
+   * back via `parcel.value`, map it to the matching option so the selection is
+   * reflected. With no `optionValue` set, the bound value is already an option
+   * and passes through unchanged (backward compatible).
+   *
+   * @param {{
+   *   rawValue: *
+   * }} params - Parameters of this method.
+   * @returns {*} A value in option space (the raw value when unmatched).
+   */
+  resolveInternalValueFromRaw ({
+    rawValue,
+  }) {
+    if (this.optionValue === null) {
+      return rawValue
+    }
+
+    if (Array.isArray(rawValue)) {
+      return rawValue.map(value =>
+        this.resolveSingleInternalValue({ rawValue: value })
+      )
+    }
+
+    return this.resolveSingleInternalValue({ rawValue })
+  }
+
+  /**
+   * Reverse the `optionValue` projection for a single bound value.
+   *
+   * @param {{
+   *   rawValue: *
+   * }} params - Parameters of this method.
+   * @returns {*} The matching option, or the raw value when unmatched.
+   */
+  resolveSingleInternalValue ({
+    rawValue,
+  }) {
+    const matchedOption = this.findOptionByValue({ value: rawValue })
+
+    return matchedOption
+      ?? rawValue
+  }
+
+  /**
+   * Get attrs value.
+   *
+   * @returns {FuroAutocompleteOption | Array<FuroAutocompleteOption> | null}
+   */
+  get attrsValue () {
+    return /** @type {FuroAutocompleteOption | Array<FuroAutocompleteOption> | null} */ (
+      this.attrs?.value
+      ?? null
+    )
+  }
+
+  /**
+   * Get sentinel value for the select-all option.
+   *
+   * @returns {string}
+   */
+  get furoAutocompleteSelectAllValue () {
+    return FURO_AUTOCOMPLETE_FIELD_SELECT_ALL_VALUE
+  }
+
+  /**
+   * Get sentinel value for the create-option row.
+   *
+   * @returns {string}
+   */
+  get furoAutocompleteCreateValue () {
+    return FURO_AUTOCOMPLETE_FIELD_CREATE_VALUE
+  }
+
+  /**
+   * Whether the clear button should be shown.
+   *
+   * @returns {boolean}
+   */
+  get showClear () {
+    return this.parcel?.showClear
+      ?? false
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroAutocompleteFieldContext ? X : never} T, X
+   * @override
+   * @returns {T} - For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.updateSearchKeywordTimerClerk = TimerClerk.create({
+      onTick: ({ searchKeyword = '' }) => {
+        this.emit(this.EMIT_EVENT_NAME.SEARCH_KEYWORD, searchKeyword)
+      },
+      timeInMilliseconds: this.parcel?.debounceMilliseconds ?? 300,
+    })
+
+    this.watch(
+      () => this.parcel?.searchKeyword,
+      searchKeyword => {
+        if (searchKeyword === this.internalSearchKeywordRef.value) {
+          return
+        }
+
+        this.internalSearchKeywordRef.value = searchKeyword ?? ''
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    this.watch(
+      [
+        () => this.parcel?.value ?? this.attrsValue ?? null,
+        () => this.parcel?.multiple ?? false,
+      ],
+      ([selectedValue, multiple]) => {
+        const resolvedValue = this.resolveInternalValueFromRaw({
+          rawValue: selectedValue,
+        })
+
+        if (multiple) {
+          this.internalValueRef.value = Array.isArray(resolvedValue)
+            ? resolvedValue
+            : []
+        } else {
+          this.internalValueRef.value = resolvedValue ?? null
+        }
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * @param {{
+   *   searchKeyword: string
+   * }} params - Parameters of this method.
+   */
+  onUpdateSearchKeyword ({
+    searchKeyword,
+  }) {
+    this.internalSearchKeywordRef.value = searchKeyword
+
+    if (this.internalOpenPopoverRef.value) {
+      this.updateSearchKeywordTimerClerk?.startTimer({ searchKeyword })
+    }
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue | null
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  isGroupOption ({
+    option,
+  }) {
+    if (
+      typeof option !== 'object'
+      || option === null
+      || !('options' in option)
+    ) {
+      return false
+    }
+
+    return Array.isArray(option.options)
+      && option.options.length > 0
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {Array<FuroAutocompleteOption | FuroAcceptableValue>}
+   */
+  extractChildOptions ({
+    option,
+  }) {
+    if (
+      option
+      && typeof option === 'object'
+      && Array.isArray(option.options)
+    ) {
+      return option.options
+    }
+
+    return [option]
+  }
+
+  /**
+   * Whether the autocomplete has empty options.
+   *
+   * @returns {boolean}
+   */
+  hasEmptyOptions () {
+    return this.filteredOptions().length === 0
+      && !this.loading
+  }
+
+  /**
+   * Whether the clear button should be shown.
+   *
+   * @returns {boolean}
+   */
+  shouldShowClearButton () {
+    const hasValidState = !this.loading && !this.isDisabled
+    const hasSelectedValue = Array.isArray(this.internalValueRef.value)
+      ? this.internalValueRef.value.length > 0
+      : this.internalValueRef.value !== null
+
+    if (this.isMultiple) {
+      return this.showClear
+        && hasValidState
+        && hasSelectedValue
+    }
+
+    return this.showClear
+      && hasValidState
+      && hasSelectedValue
+  }
+
+  /**
+   * @param {{
+   *   isOpen: boolean
+   * }} params - Parameters of this method.
+   */
+  onUpdateOpenPopover ({
+    isOpen,
+  }) {
+    this.internalOpenPopoverRef.value = isOpen
+
+    if (isOpen) {
+      this.internalSearchKeywordRef.value = ''
+    }
+  }
+
+  /**
+   * Clear value.
+   *
+   * @param {{
+   *   rawEvent: PointerEvent
+   * }} params - Parameters of this method.
+   */
+  onClearValue ({
+    rawEvent,
+  }) {
+    if (this.isMultiple) {
+      this.internalValueRef.value = []
+    } else {
+      this.internalValueRef.value = null
+    }
+
+    this.internalSearchKeywordRef.value = ''
+
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent,
+    })
+
+    this.emit(this.EMIT_EVENT_NAME.UPDATE_VALUE, this.resolveEmittedValue())
+    this.emit(this.EMIT_EVENT_NAME.CHANGE_VALUE, payload)
+    this.emit(this.EMIT_EVENT_NAME.SEARCH_KEYWORD, '')
+  }
+
+  /**
+   * Extract display value.
+   *
+   * @param {{
+   *   option: FuroAutocompleteOption
+   * }} params - Parameters of this method.
+   * @returns {string}
+   */
+  extractDisplayValue ({
+    option,
+  }) {
+    if (typeof option === 'string') {
+      return option
+    }
+
+    return this.resolveOptionLabel({ option })
+      ?? ''
+  }
+
+  /**
+   * Whether the select all option should be shown.
+   *
+   * @returns {boolean}
+   */
+  shouldShowSelectAllOption () {
+    return Boolean(this.parcel?.showSelectAll)
+      && this.isMultiple
+      && !this.loading
+      && this.filteredOptions().length > 0
+  }
+
+  /**
+   * Compare two options. Returns true if the options are the same.
+   *
+   * @param {{
+   *   optionA: FuroAutocompleteOption | FuroAcceptableValue
+   *   optionB: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  compareOption ({
+    optionA,
+    optionB,
+  }) {
+    if (
+      optionA
+      && optionB
+      && typeof optionA === 'object'
+      && typeof optionB === 'object'
+      && 'value' in optionA
+      && 'value' in optionB
+    ) {
+      return JSON.stringify(optionA.value) === JSON.stringify(optionB.value)
+    }
+
+    return optionA === optionB
+  }
+
+  /**
+   * @param {{
+   *   parentOption: FuroAutocompleteOption | FuroAcceptableValue
+   *   childOption: FuroAutocompleteOption | FuroAcceptableValue
+   *   childIndex: number
+   *   parentIndex: number
+   * }} params - Parameters of this method.
+   * @returns {number}
+   */
+  extractOptionIndex ({
+    parentOption,
+    childOption,
+    childIndex,
+    parentIndex,
+  }) {
+    if (JSON.stringify(parentOption) === JSON.stringify(childOption)) {
+      return parentIndex
+    }
+
+    return childIndex
+  }
+
+  /**
+   * @param {{
+   *   parentOption: FuroAutocompleteOption | FuroAcceptableValue
+   *   childOption: FuroAutocompleteOption | FuroAcceptableValue
+   *   parentIndex: number
+   * }} params - Parameters of this method.
+   * @returns {number | null}
+   */
+  extractGroupOptionIndex ({
+    parentOption,
+    childOption,
+    parentIndex,
+  }) {
+    if (JSON.stringify(parentOption) !== JSON.stringify(childOption)) {
+      return parentIndex
+    }
+
+    return null
+  }
+
+  /**
+   * @param {{
+   *   rawEvent: Reka.SelectItemSelectEvent<FuroAutocompleteOption | FuroAcceptableValue> | null
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   *   selectedIndex: number
+   *   selectedGroupIndex: number | null
+   * }} params - Parameters of this method.
+   * @returns {AutocompleteRawEvent}
+   */
+  buildCustomEmitPayloadEvent ({
+    rawEvent,
+    option,
+    selectedIndex,
+    selectedGroupIndex,
+  }) {
+    return new CustomEvent(this.EMIT_EVENT_NAME.CHANGE_VALUE, {
+      detail: {
+        target: /** @type {HTMLElement} */ (rawEvent?.target ?? null),
+        selectedOption: option,
+        isMultiple: this.isMultiple,
+        searchKeyword: this.internalSearchKeywordRef.value,
+        selectedIndex,
+        selectedOptions: Array.isArray(this.internalValueRef.value)
+          ? this.internalValueRef.value
+          : [this.internalValueRef.value],
+        selectedGroupIndex,
+      },
+    })
+  }
+
+  /**
+   * @param {{
+   *   rawEvent: Reka.SelectItemSelectEvent<FuroAutocompleteOption | FuroAcceptableValue>
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   *   selectedIndex: number
+   *   selectedGroupIndex: number | null
+   * }} params - Parameters of this method.
+   */
+  onSelectOption ({
+    rawEvent,
+    option,
+    selectedIndex,
+    selectedGroupIndex,
+  }) {
+    if (
+      typeof option === 'object'
+      && option?.disabled
+    ) {
+      return
+    }
+
+    if (
+      this.isMultiple
+      && Array.isArray(this.internalValueRef.value)
+    ) {
+      const existingOption = this.internalValueRef.value.find(
+        it => this.compareOption({
+          optionA: it,
+          optionB: option,
+        })
+      )
+      const newOptions = existingOption
+        ? this.internalValueRef.value.filter(
+          it => !this.compareOption({
+            optionA: it,
+            optionB: option,
+          })
+        )
+        : [
+          ...this.internalValueRef.value,
+          option,
+        ]
+
+      this.internalValueRef.value = newOptions
+    } else {
+      this.internalValueRef.value = option
+    }
+
+    const customEvent = this.buildCustomEmitPayloadEvent({
+      rawEvent,
+      option,
+
+      selectedIndex,
+      selectedGroupIndex,
+    })
+    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, this.resolveEmittedValue())
+
+    if (this.internalSearchKeywordRef.value.length > 0) {
+      this.internalSearchKeywordRef.value = ''
+      this.onUpdateOpenPopover({
+        isOpen: false,
+      })
+    }
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption
+   * }} params - Parameters of this method.
+   */
+  onRemoveOption ({
+    option,
+  }) {
+    if (!Array.isArray(this.internalValueRef.value)) {
+      return
+    }
+
+    this.internalValueRef.value = this.internalValueRef.value.filter(
+      it => !this.compareOption({
+        optionA: it,
+        optionB: option,
+      })
+    )
+
+    const selectedGroupIndex = /** @type {Array<FuroAutocompleteOption>} */ (this.internalValueRef.value)
+      .findIndex(parentOption => parentOption.options && parentOption.options?.some(childOption => this.compareOption({
+        optionA: childOption,
+        optionB: option,
+      })))
+
+    this.emit(this.EMIT_EVENT_NAME.UPDATE_VALUE, this.resolveEmittedValue())
+    this.emit(this.EMIT_EVENT_NAME.CHANGE_VALUE, this.buildCustomEmitPayloadEvent({
+      rawEvent: null,
+      option,
+      selectedIndex: this.internalValueRef.value
+        .findIndex(it => this.compareOption({
+          optionA: it,
+          optionB: option,
+        })),
+      selectedGroupIndex: selectedGroupIndex > 0
+        ? selectedGroupIndex
+        : null,
+    }))
+  }
+
+  /**
+   * @param {{
+   *   rawEvent: CustomEvent<FuroAcceptableValue>
+   * }} params - Parameters of this method.
+   */
+  onSelectSelectAllOption ({
+    rawEvent,
+  }) {
+    if (!this.isMultiple) {
+      return
+    }
+
+    const objectOptions = /** @type {Array<FuroAutocompleteOption>} */ (
+      this.options.filter(it => it && typeof it === 'object')
+    )
+    const primitiveOptions = /** @type {Array<FuroAcceptableValue>} */ (
+      this.options.filter(it => it && typeof it !== 'object')
+    )
+
+    const allObjectOptions = /** @type {Array<FuroAutocompleteOption>} */ (objectOptions.flatMap(it => [it, ...(it?.options ?? [])]))
+      .filter(it => !it?.disabled)
+    const allOptions = [
+      ...allObjectOptions,
+      ...primitiveOptions,
+    ]
+
+    const hasSelectedAllOptions = allOptions.every(it => Array.isArray(this.internalValueRef.value)
+      && this.internalValueRef.value?.some(
+        selectedOption => this.compareOption({
+          optionA: selectedOption,
+          optionB: it,
+        })
+      )
+    )
+    const newOptions = hasSelectedAllOptions
+      ? []
+      : allOptions
+
+    this.internalValueRef.value = newOptions
+
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent,
+    })
+
+    this.emit(this.EMIT_EVENT_NAME.CHANGE_VALUE, payload)
+    this.emit(this.EMIT_EVENT_NAME.UPDATE_VALUE, this.resolveEmittedValue())
+
+    this.internalSearchKeywordRef.value = ''
+    this.onUpdateOpenPopover({
+      isOpen: false,
+    })
+  }
+
+  /**
+   * Generate the create-option row text with the typed keyword interpolated.
+   *
+   * @returns {string}
+   */
+  generateCreateOptionText () {
+    const template = this.parcel?.createOptionText
+      ?? 'Create "{keyword}"'
+    const trimmedSearchKeyword = this.internalSearchKeywordRef.value.trim()
+
+    return template.replace('{keyword}', trimmedSearchKeyword)
+  }
+
+  /**
+   * Whether the trimmed keyword exactly matches an existing option label or value.
+   *
+   * @returns {boolean}
+   */
+  hasExactOptionMatch () {
+    const trimmedSearchKeyword = this.internalSearchKeywordRef.value
+      .trim()
+      .toLowerCase()
+
+    if (!trimmedSearchKeyword) {
+      return false
+    }
+
+    const flattenedOptions = this.options.flatMap(option => (
+      (option !== null && typeof option === 'object' && Array.isArray(option.options))
+        ? [
+          option,
+          ...option.options,
+        ]
+        : [option]
+    ))
+
+    return flattenedOptions.some(option => {
+      const optionLabel = this.extractOptionDisplayValue({ option })
+      const optionValue = (option !== null && typeof option === 'object')
+        ? option.value
+        : option
+
+      const normalizedLabel = optionLabel.toLowerCase()
+      const normalizedValue = String(optionValue)
+        .toLowerCase()
+
+      return normalizedLabel === trimmedSearchKeyword
+        || normalizedValue === trimmedSearchKeyword
+    })
+  }
+
+  /**
+   * Whether the create-option row should be shown.
+   *
+   * @returns {boolean}
+   */
+  shouldShowCreateOption () {
+    return this.creatable
+      && this.internalSearchKeywordRef.value.trim().length > 0
+      && !this.hasExactOptionMatch()
+  }
+
+  /**
+   * Whether the empty row should be shown.
+   *
+   * @returns {boolean}
+   */
+  shouldShowEmpty () {
+    return this.hasEmptyOptions()
+      && !this.shouldShowCreateOption()
+  }
+
+  /**
+   * Emit the typed keyword so the parent can create and append a new option.
+   *
+   * @param {{
+   *   rawEvent: Reka.SelectItemSelectEvent<FuroAutocompleteOption | FuroAcceptableValue> | null
+   * }} params - Parameters of this method.
+   */
+  onCreateOption ({
+    rawEvent,
+  }) {
+    const trimmedSearchKeyword = this.internalSearchKeywordRef.value.trim()
+
+    if (!trimmedSearchKeyword) {
+      return
+    }
+
+    const customEvent = this.buildCustomEmitPayloadEvent({
+      rawEvent,
+      option: null,
+      selectedIndex: -1,
+      selectedGroupIndex: null,
+    })
+    const payload = this.Ctor.EmitPayloadCtor.create({
+      rawEvent: customEvent,
+    })
+
+    this.emit(this.EMIT_EVENT_NAME.CREATE_OPTION, payload)
+
+    this.internalSearchKeywordRef.value = ''
+    this.onUpdateOpenPopover({
+      isOpen: false,
+    })
+  }
+
+  /**
+   * @returns {FuroAcceptableValue | Array<FuroAcceptableValue> | null}
+   */
+  extractListboxModelValue () {
+    if (!Array.isArray(this.internalValueRef.value)) {
+      return this.internalValueRef.value
+        ?? null
+    }
+
+    return this.internalValueRef.value
+      ?? []
+  }
+
+  /**
+   * @returns {Array<FuroAutocompleteOption | FuroAcceptableValue>}
+   */
+  filteredOptions () {
+    if (this.loading) {
+      return []
+    }
+
+    if (!this.parcel?.localCompare) {
+      return this.options
+    }
+
+    const objectOptions = /** @type {Array<FuroAutocompleteOption>} */ (
+      this.options.filter(it => it && typeof it === 'object')
+    )
+    const primitiveOptions = /** @type {Array<FuroAcceptableValue>} */ (
+      this.options.filter(it => it && typeof it !== 'object')
+    )
+
+    const trimmedSearchKeyword = this.internalSearchKeywordRef.value.trim()
+
+    const objectFilteredOptions = objectOptions.filter(
+      it => /** @type {Array<FuroAutocompleteOption>} */ (it.options)
+        ?.some(childOption =>
+          this.filterCollator.contains(this.resolveOptionLabel({ option: childOption }) ?? '', trimmedSearchKeyword)
+          || this.filterCollator.contains(String(childOption.value), trimmedSearchKeyword)
+        )
+        || this.filterCollator.contains(this.resolveOptionLabel({ option: it }) ?? '', trimmedSearchKeyword)
+        || this.filterCollator.contains(String(it.value), trimmedSearchKeyword)
+    )
+
+    const primitiveFilteredOptions = primitiveOptions.filter(
+      it => this.filterCollator.contains(String(it), trimmedSearchKeyword)
+    )
+
+    return [
+      ...objectFilteredOptions,
+      ...primitiveFilteredOptions,
+    ]
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  shouldShowOptionIcon ({
+    option,
+  }) {
+    if (
+      typeof option !== 'object'
+      || option === null
+    ) {
+      return false
+    }
+
+    return Boolean(option.icon)
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  shouldShowSeparator ({
+    option,
+  }) {
+    if (
+      typeof option !== 'object'
+      || option === null
+    ) {
+      return false
+    }
+
+    return Boolean(option.separator)
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  shouldShowParentSeparator ({
+    option,
+  }) {
+    if (
+      typeof option !== 'object'
+      || option === null
+    ) {
+      return false
+    }
+
+    return Boolean(option.separator)
+      && Array.isArray(option.options)
+      && option.options.length > 0
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {boolean}
+   */
+  shouldDisableOption ({
+    option,
+  }) {
+    if (
+      typeof option !== 'object'
+      || option === null
+    ) {
+      return false
+    }
+
+    return Boolean(option?.disabled)
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {string}
+   */
+  extractOptionDisplayValue ({
+    option,
+  }) {
+    if (typeof option !== 'object') {
+      return String(option)
+    }
+
+    return String(this.resolveOptionLabel({ option }) ?? '')
+  }
+
+  /**
+   * @param {{
+   *   option: FuroAutocompleteOption | FuroAcceptableValue
+   * }} params - Parameters of this method.
+   * @returns {import('./AutocompleteEmitPayload.js').IconProps | null}
+   */
+  extractOptionIcon ({
+    option,
+  }) {
+    if (
+      typeof option !== 'object'
+      || option === null
+    ) {
+      return null
+    }
+
+    return /** @type {import('./AutocompleteEmitPayload.js').IconProps} */ (option.icon)
+  }
+
+  /**
+   * Extract empty text.
+   *
+   * @returns {string}
+   */
+  extractEmptyText () {
+    return this.parcel?.emptyText
+      ?? 'No options.'
+  }
+
+  /**
+   * Extract select all text.
+   *
+   * @returns {string}
+   */
+  extractSelectAllText () {
+    return this.parcel?.selectAllText
+      ?? 'Select All'
+  }
+
+  /**
+   * Extract text direction value.
+   *
+   * @returns {'ltr' | 'rtl'}
+   */
+  extractTextDirectionValue () {
+    if (!this.parcel?.textDirection) {
+      return 'ltr'
+    }
+
+    return this.parcel.textDirection === 'toRight'
+      ? 'ltr'
+      : 'rtl'
+  }
+
+  /**
+   * Extract placeholder text.
+   *
+   * @returns {string}
+   */
+  extractPlaceholderText () {
+    return this.parcel?.placeholder
+      ?? 'Select an option'
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     triggerContentElementRef: import('vue').Ref<HTMLElement | null>
+ *     internalValueRef: import('vue').Ref<FuroAutocompleteOption | null>
+ *     internalSearchKeywordRef: import('vue').Ref<string>
+ *     internalOpenPopoverRef: import('vue').Ref<boolean>
+ *   }
+ *   filterCollator: ReturnType<typeof import('reka-ui').useFilter>
+ * }} FuroAutocompleteFieldContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroAutocompleteFieldContextParams, 'refHash'> & {
+ *   refHash?: FuroAutocompleteFieldContextParams['refHash']
+ *   filterCollator: ReturnType<typeof import('reka-ui').useFilter>
+ * }} FuroAutocompleteFieldContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroAutocompleteFieldContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {string | number | bigint | Record<string, unknown> | null} FuroAcceptableValue
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroAutocompleteFieldParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroAutocompleteField>`.
+ * JSON-serializable only. Not an open passthrough to the internal combobox library.
+ *
+ * @typedef {{
+ *   value?: FuroAutocompleteOption | Array<FuroAutocompleteOption> | FuroAcceptableValue | Array<FuroAcceptableValue> | null
+ *   options?: Array<FuroAutocompleteOption | FuroAcceptableValue>
+ *   optionLabel?: string | ((option: FuroAutocompleteOption | FuroAcceptableValue) => string)
+ *   optionValue?: string | ((option: FuroAutocompleteOption | FuroAcceptableValue) => FuroAcceptableValue)
+ *   placeholder?: string | null
+ *   loading?: boolean
+ *   invalid?: boolean
+ *   disabled?: boolean
+ *   textDirection?: 'toRight' | 'toLeft'
+ *   multiple?: boolean
+ *   showClear?: boolean
+ *   searchKeyword?: string
+ *   localCompare?: boolean
+ *   debounceMilliseconds?: number
+ *   open?: boolean
+ *   openOnClick?: boolean
+ *   showSelectAll?: boolean
+ *   selectAllText?: string
+ *   emptyText?: string
+ *   creatable?: boolean
+ *   createOptionText?: string
+ *   maxVisibleChips?: number
+ *   chipOverflow?: 'wrap' | 'ellipsis'
+ * }} FuroAutocompleteFieldParcel
+ */
+
+/**
+ * @typedef {FuroAutocompleteFieldParcel} ExtraRootParcel
+ * @deprecated Use {@link FuroAutocompleteFieldParcel} instead.
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroAutocompleteFieldEmitHash, FuroAutocompleteFieldSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroAutocompleteFieldContext.EMIT_EVENT_HASH} FuroAutocompleteFieldEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   'trigger-content': {}
+ *   'trigger-left': {}
+ *   'trigger-right': {}
+ *   cancel: {}
+ *   'content-before': {}
+ *   'content-after': {}
+ *   'select-all': {
+ *     checked: boolean
+ *     indeterminate: boolean
+ *     disabled: boolean
+ *   }
+ *   'create-option': {
+ *     searchKeyword: string
+ *   }
+ *   group: {
+ *     group: FuroAutocompleteOption
+ *     groupIndex: number
+ *   }
+ *   'group-label': {
+ *     group: FuroAutocompleteOption
+ *     groupIndex: number
+ *   }
+ *   option: {
+ *     option: FuroAutocompleteOption
+ *     optionIndex: number
+ *     group?: FuroAutocompleteOption
+ *     groupIndex?: number
+ *   }
+ *   'option-text': {
+ *     option: FuroAutocompleteOption
+ *     optionIndex: number
+ *   }
+ *   'option-indicator': {
+ *     option: FuroAutocompleteOption
+ *     optionIndex: number
+ *   }
+ *   separator: {
+ *     option: FuroAutocompleteOption
+ *     optionIndex: number
+ *   }
+ *   empty: {
+ *     searchKeyword: string
+ *     loading: boolean
+ *   }
+ *   loading: {
+ *     searchKeyword: string
+ *   }
+ * }>} FuroAutocompleteFieldSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroAutocompleteFieldContext
+ * }} FuroAutocompleteFieldSetup
+ */
+
+/**
+ * @typedef {import('./AutocompleteEmitPayload.js').FuroAutocompleteOption} FuroAutocompleteOption
+ * @typedef {import('./AutocompleteEmitPayload.js').AutocompleteRawEvent} AutocompleteRawEvent
+ */
+
+/**
+ * @import * as Reka from 'reka-ui'
+ */