@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroDrawer/FuroDrawerContext.js

@@ -0,0 +1,676 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+const DEFAULT_CLOSE_TEXT = 'Close'
+
+const DEFAULT_SIDE = 'right'
+
+/**
+ * Maps the value-oriented `side` (the edge the panel docks to) onto the
+ * underlying primitive's swipe-to-dismiss direction.
+ */
+const SIDE_TO_SWIPE_DIRECTION = {
+  left: 'left',
+  right: 'right',
+  top: 'up',
+  bottom: 'down',
+}
+
+/**
+ * Context class for FuroDrawer organism.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroDrawerContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroDrawerContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroDrawerContext ? X : never} T, X
+   * @override
+   * @param {FuroDrawerContextFactoryParams} 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 {FuroDrawerContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      openRef: ref(false),
+      snapPointRef: ref(null),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   OPEN_CHANGE: 'open:change'
+   *   UPDATE_OPEN: 'update:open'
+   *   SNAP_CHANGE: 'snap:change'
+   *   UPDATE_ACTIVE_SNAP_POINT: 'update:activeSnapPoint'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      OPEN_CHANGE: 'open:change',
+      UPDATE_OPEN: 'update:open',
+      SNAP_CHANGE: 'snap:change',
+      UPDATE_ACTIVE_SNAP_POINT: 'update:activeSnapPoint',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'open:change': (payload: { open: boolean }) => void
+   *   'update:open': (open: boolean) => void
+   *   'snap:change': (payload: { snapPoint: number | string | null }) => void
+   *   'update:activeSnapPoint': (snapPoint: number | string | null) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.OPEN_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_OPEN]: payload => {},
+      [this.EMIT_EVENT_NAME.SNAP_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_ACTIVE_SNAP_POINT]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroDrawerContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroDrawerContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal open ref.
+   *
+   * @returns {import('vue').Ref<boolean>}
+   */
+  get openRef () {
+    return this.refHash.openRef
+  }
+
+  /**
+   * Get internal active snap point ref.
+   *
+   * @returns {import('vue').Ref<number | string | null>}
+   */
+  get snapPointRef () {
+    return this.refHash.snapPointRef
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {NonNullable<Props['parcel']>}
+   */
+  get parcel () {
+    return {
+      open: null,
+      disabled: false,
+      modal: true,
+      title: null,
+      description: null,
+      closeText: DEFAULT_CLOSE_TEXT,
+      closeOnOutsideClick: true,
+      closeOnEscape: true,
+      side: DEFAULT_SIDE,
+      size: 'default',
+      snapPoints: null,
+      activeSnapPoint: null,
+      sequentialSnap: false,
+      swipeToOpen: false,
+      dragHandle: false,
+      busy: false,
+      initialFocus: null,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Whether open state is controlled via parcel.
+   *
+   * @returns {boolean}
+   */
+  isOpenControlled () {
+    return (this.parcel?.open ?? null) !== null
+  }
+
+  /**
+   * Whether the trigger is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    const disabledByParcel = Boolean(this.parcel?.disabled)
+    const disabledByAttrs = this.hasBooleanAttribute({ name: 'disabled' })
+
+    return disabledByParcel || disabledByAttrs
+  }
+
+  /**
+   * Resolve the modality of the drawer (`true` | `'trap-focus'` | `false`).
+   *
+   * @returns {boolean | 'trap-focus'}
+   */
+  extractModal () {
+    return this.parcel?.modal
+      ?? true
+  }
+
+  /**
+   * Resolve open state for the root host element.
+   *
+   * @returns {boolean}
+   */
+  extractOpenValue () {
+    if (this.isOpenControlled()) {
+      return Boolean(this.parcel?.open)
+    }
+
+    return this.openRef.value
+  }
+
+  /**
+   * Resolve the edge the drawer docks to and slides in from.
+   *
+   * @returns {FuroDrawerSide}
+   */
+  extractSide () {
+    return this.parcel?.side
+      ?? DEFAULT_SIDE
+  }
+
+  /**
+   * Resolve the underlying swipe-to-dismiss direction from the docking side.
+   *
+   * @returns {'left' | 'right' | 'up' | 'down'}
+   */
+  extractSwipeDirection () {
+    const side = this.extractSide()
+
+    return SIDE_TO_SWIPE_DIRECTION[side]
+      ?? 'down'
+  }
+
+  /**
+   * Resolve the content size variant.
+   *
+   * @returns {FuroDrawerSize}
+   */
+  extractSize () {
+    return this.parcel?.size
+      ?? 'default'
+  }
+
+  /**
+   * Resolve the preset snap positions.
+   *
+   * @returns {Array<number | string> | null}
+   */
+  extractSnapPoints () {
+    return this.parcel?.snapPoints
+      ?? null
+  }
+
+  /**
+   * Whether snap points are configured.
+   *
+   * @returns {boolean}
+   */
+  hasSnapPoints () {
+    const snapPoints = this.extractSnapPoints()
+
+    return Array.isArray(snapPoints)
+      && snapPoints.length > 0
+  }
+
+  /**
+   * Whether snapping advances one sequential point at a time.
+   *
+   * @returns {boolean}
+   */
+  isSequentialSnap () {
+    return this.parcel?.sequentialSnap === true
+  }
+
+  /**
+   * Whether the active snap point is controlled via parcel.
+   *
+   * @returns {boolean}
+   */
+  isActiveSnapPointControlled () {
+    return (this.parcel?.activeSnapPoint ?? null) !== null
+  }
+
+  /**
+   * Resolve the active snap point for the root host element.
+   *
+   * @returns {number | string | null}
+   */
+  extractActiveSnapPointValue () {
+    if (this.isActiveSnapPointControlled()) {
+      return this.parcel?.activeSnapPoint
+        ?? null
+    }
+
+    return this.snapPointRef.value
+  }
+
+  /**
+   * Whether the panel may be swiped open from its closed state.
+   *
+   * @returns {boolean}
+   */
+  shouldEnableSwipeToOpen () {
+    return this.parcel?.swipeToOpen === true
+  }
+
+  /**
+   * Whether to render the drag handle.
+   *
+   * @returns {boolean}
+   */
+  shouldShowDragHandle () {
+    return this.parcel?.dragHandle === true
+  }
+
+  /**
+   * Whether the drawer is in a busy state (blocks dismissal during async work).
+   *
+   * @returns {boolean}
+   */
+  isBusy () {
+    return this.parcel?.busy === true
+  }
+
+  /**
+   * Extract root class names.
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractRootClassNames () {
+    return {
+      'unit-drawer': true,
+      disabled: this.isDisabled(),
+    }
+  }
+
+  /**
+   * Extract content class names (side + size variant + busy state).
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractContentClassNames () {
+    const side = this.extractSide()
+    const size = this.extractSize()
+
+    const sizeClassEntries = size === 'default'
+      ? []
+      : [[size, true]]
+
+    return Object.fromEntries([
+      ['unit-drawer-content', true],
+      [side, true],
+      ...sizeClassEntries,
+      ['busy', this.isBusy()],
+    ])
+  }
+
+  /**
+   * CSS selector (scoped to drawer content) for the element to focus on open.
+   *
+   * @returns {string | null}
+   */
+  extractInitialFocusSelector () {
+    return this.parcel?.initialFocus
+      ?? null
+  }
+
+  /**
+   * Title text rendered in the drawer heading.
+   *
+   * @returns {string | null}
+   */
+  extractTitle () {
+    return this.parcel?.title
+      ?? null
+  }
+
+  /**
+   * Description text rendered below the heading.
+   *
+   * @returns {string | null}
+   */
+  extractDescription () {
+    return this.parcel?.description
+      ?? null
+  }
+
+  /**
+   * Whether a description region should render (parcel text or `description` slot).
+   *
+   * @returns {boolean}
+   */
+  hasDescription () {
+    const hasDescriptionText = this.extractDescription() !== null
+    const hasDescriptionSlot = Boolean(this.componentContext.slots?.description)
+
+    return hasDescriptionText || hasDescriptionSlot
+  }
+
+  /**
+   * Accessible label for the built-in close button.
+   *
+   * @returns {string}
+   */
+  extractCloseText () {
+    return this.parcel?.closeText
+      ?? DEFAULT_CLOSE_TEXT
+  }
+
+  /**
+   * Whether an outside click (overlay / outside interaction) dismisses the drawer.
+   *
+   * @returns {boolean}
+   */
+  shouldCloseOnOutsideClick () {
+    return this.parcel?.closeOnOutsideClick !== false
+  }
+
+  /**
+   * Whether the Escape key dismisses the drawer.
+   *
+   * @returns {boolean}
+   */
+  shouldCloseOnEscape () {
+    return this.parcel?.closeOnEscape !== false
+  }
+
+  /**
+   * Handle outside interaction — veto dismissal when disabled.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   */
+  onInteractOutside ({
+    rawEvent,
+  }) {
+    if (
+      this.shouldCloseOnOutsideClick()
+      && !this.isBusy()
+    ) {
+      return
+    }
+
+    rawEvent.preventDefault()
+  }
+
+  /**
+   * Handle Escape key — veto dismissal when disabled.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   */
+  onEscapeKeyDown ({
+    rawEvent,
+  }) {
+    if (
+      this.shouldCloseOnEscape()
+      && !this.isBusy()
+    ) {
+      return
+    }
+
+    rawEvent.preventDefault()
+  }
+
+  /**
+   * Handle the drawer's initial-focus moment — focus a custom element when configured.
+   *
+   * @param {{
+   *   rawEvent: Event
+   * }} params
+   */
+  onOpenAutoFocus ({
+    rawEvent,
+  }) {
+    const selector = this.extractInitialFocusSelector()
+
+    if (selector === null) {
+      return
+    }
+
+    const root = /** @type {Element | null} */ (rawEvent.currentTarget)
+    const target = /** @type {HTMLElement | null} */ (
+      root?.querySelector(selector)
+      ?? null
+    )
+
+    if (target === null) {
+      return
+    }
+
+    rawEvent.preventDefault()
+
+    target.focus()
+  }
+
+  /**
+   * Request the drawer to close. Exposed to slots so action buttons can dismiss
+   * the drawer (works for both controlled and uncontrolled open state).
+   */
+  requestClose () {
+    this.onOpenChange({
+      isOpen: false,
+    })
+  }
+
+  /**
+   * Handle open state updates from the root host element.
+   *
+   * @param {{
+   *   isOpen: boolean
+   * }} params
+   */
+  onOpenChange ({
+    isOpen,
+  }) {
+    if (
+      this.isBusy()
+      && !isOpen
+    ) {
+      return
+    }
+
+    if (!this.isOpenControlled()) {
+      this.openRef.value = isOpen
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_OPEN,
+      isOpen
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.OPEN_CHANGE,
+      {
+        open: isOpen,
+      }
+    )
+  }
+
+  /**
+   * Handle active snap point updates from the root host element.
+   *
+   * @param {{
+   *   snapPoint: number | string | null
+   * }} params
+   */
+  onSnapPointChange ({
+    snapPoint,
+  }) {
+    if (!this.isActiveSnapPointControlled()) {
+      this.snapPointRef.value = snapPoint
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_ACTIVE_SNAP_POINT,
+      snapPoint
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.SNAP_CHANGE,
+      {
+        snapPoint,
+      }
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     openRef: import('vue').Ref<boolean>
+ *     snapPointRef: import('vue').Ref<number | string | null>
+ *   }
+ * }} FuroDrawerContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroDrawerContextParams, 'refHash'> & {
+ *   refHash?: FuroDrawerContextParams['refHash']
+ * }} FuroDrawerContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroDrawerContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroDrawerParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroDrawer>`.
+ * JSON-serializable only. Not an open passthrough to the internal drawer library.
+ *
+ * @typedef {{
+ *   open?: boolean | null
+ *   disabled?: boolean
+ *   modal?: boolean | 'trap-focus'
+ *   title?: string | null
+ *   description?: string | null
+ *   closeText?: string
+ *   closeOnOutsideClick?: boolean
+ *   closeOnEscape?: boolean
+ *   side?: FuroDrawerSide
+ *   size?: FuroDrawerSize
+ *   snapPoints?: Array<number | string> | null
+ *   activeSnapPoint?: number | string | null
+ *   sequentialSnap?: boolean
+ *   swipeToOpen?: boolean
+ *   dragHandle?: boolean
+ *   busy?: boolean
+ *   initialFocus?: string | null
+ * }} FuroDrawerParcel
+ */
+
+/**
+ * @typedef {'left' | 'right' | 'top' | 'bottom'} FuroDrawerSide
+ */
+
+/**
+ * @typedef {'sm' | 'default' | 'lg' | 'fullscreen'} FuroDrawerSize
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroDrawerEmitHash, FuroDrawerSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroDrawerContext.EMIT_EVENT_HASH} FuroDrawerEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   trigger: {}
+ *   title: {}
+ *   description: {}
+ *   default: {
+ *     close: () => void
+ *   }
+ *   footer: {
+ *     close: () => void
+ *   }
+ *   close: {}
+ * }>} FuroDrawerSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroDrawerContext
+ * }} FuroDrawerSetup
+ */