@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroDropdownMenu/FuroDropdownMenuContext.js

@@ -0,0 +1,714 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import DropdownMenuOptionSelectEmitPayload from './DropdownMenuOptionSelectEmitPayload.js'
+
+/**
+ * Parcel keys handled explicitly or Furo-only — excluded from the v-bind spread to DropdownMenuRoot.
+ * `open` and `disabled` are forwarded via dedicated bindings (not dropped).
+ * `side`, `align`, `sideOffset` are forwarded to DropdownMenuContent instead.
+ * `options` is Furo-only with no Reka analog.
+ */
+const ROOT_SPREAD_EXCLUDED_PARCEL_KEYS = new Set([
+  'open',
+  'disabled',
+  'side',
+  'align',
+  'sideOffset',
+  'options',
+])
+
+/**
+ * Trigger parcel keys handled explicitly or Furo-only — excluded from the v-bind spread to Reka Trigger.
+ */
+const TRIGGER_SPREAD_EXCLUDED_PARCEL_KEYS = new Set([
+  'variant',
+  'size',
+  'loading',
+  'asChild',
+  'disabled',
+])
+
+/**
+ * Context class for FuroDropdownMenu molecule.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroDropdownMenuContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroDropdownMenuContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroDropdownMenuContext ? X : never} T, X
+   * @override
+   * @param {FuroDropdownMenuContextFactoryParams} 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 {FuroDropdownMenuContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      openRef: ref(false),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   OPEN_CHANGE: 'open:change'
+   *   OPTION_SELECT: 'option:select'
+   *   OPTION_CHECKED_CHANGE: 'option:checked-change'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      OPEN_CHANGE: 'open:change',
+      OPTION_SELECT: 'option:select',
+      OPTION_CHECKED_CHANGE: 'option:checked-change',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'open:change': (payload: { open: boolean }) => void
+   *   'option:select': (payload: import('./DropdownMenuOptionSelectEmitPayload.js').default) => void
+   *   'option:checked-change': (payload: {
+   *     option: FuroDropdownMenuOption
+   *     checked: boolean
+   *   }) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.OPEN_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.OPTION_SELECT]: payload => {},
+      [this.EMIT_EVENT_NAME.OPTION_CHECKED_CHANGE]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of select `EmitPayload`.
+   *
+   * @returns {typeof DropdownMenuOptionSelectEmitPayload}
+   */
+  static get OptionSelectEmitPayloadCtor () {
+    return DropdownMenuOptionSelectEmitPayload
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroDropdownMenuContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroDropdownMenuContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal open ref.
+   *
+   * @returns {import('vue').Ref<boolean>}
+   */
+  get openRef () {
+    return this.refHash.openRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {Props['parcel']}
+   */
+  get parcel () {
+    return {
+      open: undefined,
+      disabled: false,
+      side: 'bottom',
+      align: 'start',
+      sideOffset: 4,
+      options: [],
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Trigger parcel tokens (FuroButton-compatible variant / size).
+   *
+   * @returns {NonNullable<Props['triggerParcel']>}
+   */
+  get triggerParcel () {
+    return {
+      variant: 'outline',
+      size: 'default',
+      ...this.props.triggerParcel,
+    }
+  }
+
+  /**
+   * Whether open state is controlled via parcel.
+   *
+   * @returns {boolean}
+   */
+  isOpenControlled () {
+    return this.parcel?.open !== undefined
+  }
+
+  /**
+   * Whether the menu is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    const disabledByParcel = Boolean(this.parcel?.disabled)
+    const disabledByAttrs = this.hasBooleanAttribute({ name: 'disabled' })
+
+    return disabledByParcel || disabledByAttrs
+  }
+
+  /**
+   * Resolve open state for DropdownMenuRoot.
+   *
+   * @returns {boolean}
+   */
+  extractOpenValue () {
+    if (this.isOpenControlled()) {
+      return Boolean(this.parcel?.open)
+    }
+
+    return this.openRef.value
+  }
+
+  /**
+   * Extract root class names.
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractRootClassNames () {
+    return {
+      'unit-dropdown-menu': true,
+      disabled: this.isDisabled(),
+    }
+  }
+
+  /**
+   * Extract attributes forwarded to DropdownMenuRoot.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const parcelEntries = Object.entries(this.parcel ?? {})
+
+    return Object.fromEntries(
+      parcelEntries.filter(([key]) => !ROOT_SPREAD_EXCLUDED_PARCEL_KEYS.has(key))
+    )
+  }
+
+  /**
+   * Extract content positioning props.
+   *
+   * @returns {{
+   *   side: FuroDropdownMenuSide
+   *   align: FuroDropdownMenuAlign
+   *   sideOffset: number
+   * }}
+   */
+  extractContentAttributes () {
+    const {
+      side = 'bottom',
+      align = 'start',
+      sideOffset = 4,
+    } = this.parcel ?? {}
+
+    return {
+      side,
+      align,
+      sideOffset,
+    }
+  }
+
+  /**
+   * Whether the trigger slot's own element becomes the trigger (Reka `asChild`),
+   * so no wrapper `<button>` and no forced `.unit-button` styling are applied.
+   *
+   * @returns {boolean}
+   */
+  shouldRenderTriggerAsChild () {
+    return Boolean(this.triggerParcel?.asChild)
+  }
+
+  /**
+   * Extract CSS class map for native DropdownMenuTrigger (FuroButton-compatible).
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractTriggerClassNames () {
+    if (this.shouldRenderTriggerAsChild()) {
+      return {}
+    }
+
+    const {
+      variant = 'outline',
+      size = 'default',
+      loading,
+    } = this.triggerParcel ?? {}
+
+    const sizeClassEntries = size === 'default'
+      ? []
+      : [[`size-${size}`, true]]
+
+    const isLoading = Boolean(loading)
+    const isDisabled = this.isDisabled()
+
+    return Object.fromEntries([
+      ['unit-button', true],
+      [variant, true],
+      ...sizeClassEntries,
+      ['disabled', isDisabled],
+      ['loading', isLoading],
+    ])
+  }
+
+  /**
+   * Extract attributes forwarded to Reka DropdownMenuTrigger.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractTriggerAttributes () {
+    const parcelEntries = Object.entries(this.triggerParcel ?? {})
+
+    return Object.fromEntries(
+      parcelEntries.filter(([key]) => !TRIGGER_SPREAD_EXCLUDED_PARCEL_KEYS.has(key))
+    )
+  }
+
+  /**
+   * Extract menu options from parcel.
+   *
+   * @returns {Array<FuroDropdownMenuOption>}
+   */
+  extractMenuOptions () {
+    return this.parcel?.options
+      ?? []
+  }
+
+  /**
+   * Whether the option row is a separator.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   * }} params
+   * @returns {boolean}
+   */
+  isSeparatorOption ({
+    option,
+  }) {
+    return Boolean(option.separator)
+  }
+
+  /**
+   * Whether the option row is a submenu.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   * }} params
+   * @returns {boolean}
+   */
+  isSubmenuOption ({
+    option,
+  }) {
+    return option.type === 'submenu'
+      && Array.isArray(option.options)
+  }
+
+  /**
+   * Whether the option row uses destructive styling.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   * }} params
+   * @returns {boolean}
+   */
+  isDestructiveOption ({
+    option,
+  }) {
+    return option.variant === 'destructive'
+  }
+
+  /**
+   * Whether the option row is a checkbox.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   * }} params
+   * @returns {boolean}
+   */
+  isCheckboxOption ({
+    option,
+  }) {
+    return option.type === 'checkbox'
+  }
+
+  /**
+   * Extract nested submenu options.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   * }} params
+   * @returns {Array<FuroDropdownMenuOption>}
+   */
+  extractSubmenuOptions ({
+    option,
+  }) {
+    return option.options
+      ?? []
+  }
+
+  /**
+   * Extract checked value for checkbox option rows.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   * }} params
+   * @returns {boolean}
+   */
+  extractCheckboxCheckedValue ({
+    option,
+  }) {
+    return Boolean(option.checked)
+  }
+
+  /**
+   * Build stable key for option row rendering.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   *   index: number
+   *   parentKey?: string
+   * }} params
+   * @returns {string}
+   */
+  buildOptionStableKey ({
+    option,
+    index,
+    parentKey = 'root',
+  }) {
+    const valuePart = option.value
+      ?? 'row'
+
+    return `${parentKey}-${index}-${valuePart}`
+  }
+
+  /**
+   * Handle open state updates from Reka root.
+   *
+   * @param {{
+   *   isOpen: boolean
+   * }} params
+   */
+  onOpenChange ({
+    isOpen,
+  }) {
+    if (!this.isOpenControlled()) {
+      this.openRef.value = isOpen
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.OPEN_CHANGE,
+      {
+        open: isOpen,
+      }
+    )
+  }
+
+  /**
+   * Whether dismiss-outside should be ignored for nested portaled menu content.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   * @returns {boolean}
+   */
+  shouldIgnoreDismissOutsideEvent ({
+    rawEvent,
+  }) {
+    const customEvent = /** @type {CustomEvent<{ originalEvent?: Event }>} */ (rawEvent)
+    const originalTarget = customEvent.detail?.originalEvent?.target
+      ?? rawEvent.target
+
+    if (!(originalTarget instanceof Element)) {
+      return false
+    }
+
+    return Boolean(originalTarget.closest('[data-reka-menu-content]'))
+  }
+
+  /**
+   * Keep root menu open when pointer down occurs inside portaled submenu content.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   */
+  onRootContentPointerDownOutside ({
+    rawEvent,
+  }) {
+    if (!this.shouldIgnoreDismissOutsideEvent({
+      rawEvent,
+    })) {
+      return
+    }
+
+    rawEvent.preventDefault()
+  }
+
+  /**
+   * Keep root menu open when focus moves into portaled submenu content.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   */
+  onRootContentFocusOutside ({
+    rawEvent,
+  }) {
+    if (!this.shouldIgnoreDismissOutsideEvent({
+      rawEvent,
+    })) {
+      return
+    }
+
+    rawEvent.preventDefault()
+  }
+
+  /**
+   * Keep focus where the option handler left it (e.g. a text editor) instead of
+   * returning it to the trigger when the parcel opts in via `preventCloseAutoFocus`.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   */
+  onRootContentCloseAutoFocus ({
+    rawEvent,
+  }) {
+    if (!this.parcel?.preventCloseAutoFocus) {
+      return
+    }
+
+    rawEvent.preventDefault()
+  }
+
+  /**
+   * Handle menu action option selection.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   *   rawEvent: Event
+   * }} params
+   */
+  onOptionSelect ({
+    option,
+    rawEvent,
+  }) {
+    if (option.disabled) {
+      return
+    }
+
+    if (option.keepOpen) {
+      rawEvent.preventDefault()
+    }
+
+    const payload = this.Ctor.OptionSelectEmitPayloadCtor.create({
+      rawEvent,
+      option,
+    })
+
+    this.emit(
+      this.EMIT_EVENT_NAME.OPTION_SELECT,
+      payload
+    )
+  }
+
+  /**
+   * Keep menu open when a checkbox row is selected (Reka MenuItem close guard).
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   *   rawEvent: Event
+   * }} params
+   */
+  onCheckboxOptionSelect ({
+    option,
+    rawEvent,
+  }) {
+    if (option.disabled) {
+      return
+    }
+
+    rawEvent.preventDefault()
+  }
+
+  /**
+   * Handle checkbox option checked-state changes.
+   *
+   * @param {{
+   *   option: FuroDropdownMenuOption
+   *   checked: boolean
+   * }} params
+   */
+  onCheckboxCheckedChange ({
+    option,
+    checked,
+  }) {
+    if (option.disabled) {
+      return
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.OPTION_CHECKED_CHANGE,
+      {
+        option,
+        checked,
+      }
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     openRef: import('vue').Ref<boolean>
+ *   }
+ * }} FuroDropdownMenuContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroDropdownMenuContextParams, 'refHash'> & {
+ *   refHash?: FuroDropdownMenuContextParams['refHash']
+ * }} FuroDropdownMenuContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroDropdownMenuContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {'top' | 'right' | 'bottom' | 'left'} FuroDropdownMenuSide
+ */
+
+/**
+ * @typedef {'start' | 'center' | 'end'} FuroDropdownMenuAlign
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroDropdownMenuParcel | null
+ *   triggerParcel?: import('../../atoms/FuroButton/FuroButtonContext.js').FuroButtonParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroDropdownMenu>`.
+ * JSON-serializable only. Not an open passthrough to the internal dropdown library.
+ *
+ * @typedef {{
+ *   open?: boolean
+ *   disabled?: boolean
+ *   side?: FuroDropdownMenuSide
+ *   align?: FuroDropdownMenuAlign
+ *   sideOffset?: number
+ *   preventCloseAutoFocus?: boolean
+ *   options?: Array<FuroDropdownMenuOption>
+ * }} FuroDropdownMenuParcel
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroDropdownMenuEmitHash, FuroDropdownMenuSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroDropdownMenuContext.EMIT_EVENT_HASH} FuroDropdownMenuEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   trigger: {}
+ *   default: {}
+ *   'option-label': {
+ *     option: FuroDropdownMenuOption
+ *     index: number
+ *   }
+ * }>} FuroDropdownMenuSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroDropdownMenuContext
+ * }} FuroDropdownMenuSetup
+ */
+
+/**
+ * @typedef {import('./DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOption} FuroDropdownMenuOption
+ */
+
+/**
+ * @typedef {import('./DropdownMenuOptionSelectEmitPayload.js').FuroDropdownMenuOptionType} FuroDropdownMenuOptionType
+ */
+
+/**
+ * @import * as Reka from 'reka-ui'
+ */