@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroDialog/FuroDialogContext.js

@@ -0,0 +1,535 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+/**
+ * Parcel keys handled explicitly or Furo-only — excluded from the v-bind spread to the root host.
+ * `open` and `disabled` are forwarded via dedicated bindings (not dropped).
+ * `title`, `description`, `closeText` are Furo-only display values with no root-primitive analog.
+ */
+const ROOT_SPREAD_EXCLUDED_PARCEL_KEYS = new Set([
+  'open',
+  'disabled',
+  'title',
+  'description',
+  'closeText',
+  'closeOnOutsideClick',
+  'closeOnEscape',
+  'size',
+  'busy',
+  'initialFocus',
+])
+
+const DEFAULT_CLOSE_TEXT = 'Close'
+
+/**
+ * Context class for FuroDialog organism.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroDialogContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroDialogContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroDialogContext ? X : never} T, X
+   * @override
+   * @param {FuroDialogContextFactoryParams} 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 {FuroDialogContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      openRef: ref(false),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   OPEN_CHANGE: 'open:change'
+   *   UPDATE_OPEN: 'update:open'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      OPEN_CHANGE: 'open:change',
+      UPDATE_OPEN: 'update:open',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'open:change': (payload: { open: boolean }) => void
+   *   'update:open': (open: boolean) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.OPEN_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_OPEN]: payload => {},
+    }
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroDialogContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroDialogContext} */ (
+      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 {NonNullable<Props['parcel']>}
+   */
+  get parcel () {
+    return {
+      open: null,
+      disabled: false,
+      modal: true,
+      title: null,
+      description: null,
+      closeText: DEFAULT_CLOSE_TEXT,
+      closeOnOutsideClick: true,
+      closeOnEscape: true,
+      size: 'default',
+      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
+  }
+
+  /**
+   * Whether the dialog renders as a modal (overlay + focus trap).
+   *
+   * @returns {boolean}
+   */
+  isModal () {
+    return this.parcel?.modal !== false
+  }
+
+  /**
+   * Resolve open state for the root host element.
+   *
+   * @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-dialog': true,
+      disabled: this.isDisabled(),
+    }
+  }
+
+  /**
+   * Extract attributes forwarded to the root host element.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const parcelEntries = Object.entries(this.parcel ?? {})
+
+    return Object.fromEntries(
+      parcelEntries.filter(([key]) => !ROOT_SPREAD_EXCLUDED_PARCEL_KEYS.has(key))
+    )
+  }
+
+  /**
+   * Resolve the content size variant.
+   *
+   * @returns {FuroDialogSize}
+   */
+  extractSize () {
+    return this.parcel?.size
+      ?? 'default'
+  }
+
+  /**
+   * Whether the dialog is in a busy state (blocks dismissal during async work).
+   *
+   * @returns {boolean}
+   */
+  isBusy () {
+    return this.parcel?.busy === true
+  }
+
+  /**
+   * Extract content class names (size variant + busy state).
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractContentClassNames () {
+    const size = this.extractSize()
+
+    const sizeClassEntries = size === 'default'
+      ? []
+      : [[size, true]]
+
+    return Object.fromEntries([
+      ['unit-dialog-content', true],
+      ...sizeClassEntries,
+      ['busy', this.isBusy()],
+    ])
+  }
+
+  /**
+   * CSS selector (scoped to dialog content) for the element to focus on open.
+   *
+   * @returns {string | null}
+   */
+  extractInitialFocusSelector () {
+    return this.parcel?.initialFocus
+      ?? null
+  }
+
+  /**
+   * Title text rendered in the dialog 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 dialog.
+   *
+   * @returns {boolean}
+   */
+  shouldCloseOnOutsideClick () {
+    return this.parcel?.closeOnOutsideClick !== false
+  }
+
+  /**
+   * Whether the Escape key dismisses the dialog.
+   *
+   * @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 dialog'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 dialog to close. Exposed to slots so action buttons can dismiss
+   * the dialog (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,
+      }
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     openRef: import('vue').Ref<boolean>
+ *   }
+ * }} FuroDialogContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroDialogContextParams, 'refHash'> & {
+ *   refHash?: FuroDialogContextParams['refHash']
+ * }} FuroDialogContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroDialogContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroDialogParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroDialog>`.
+ * JSON-serializable only. Not an open passthrough to the internal dialog library.
+ *
+ * @typedef {{
+ *   open?: boolean | null
+ *   disabled?: boolean
+ *   modal?: boolean
+ *   title?: string | null
+ *   description?: string | null
+ *   closeText?: string
+ *   closeOnOutsideClick?: boolean
+ *   closeOnEscape?: boolean
+ *   size?: FuroDialogSize
+ *   busy?: boolean
+ *   initialFocus?: string | null
+ * }} FuroDialogParcel
+ */
+
+/**
+ * @typedef {'sm' | 'default' | 'lg' | 'fullscreen'} FuroDialogSize
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroDialogEmitHash, FuroDialogSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroDialogContext.EMIT_EVENT_HASH} FuroDialogEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<{
+ *   trigger: {}
+ *   title: {}
+ *   description: {}
+ *   default: {
+ *     close: () => void
+ *   }
+ *   footer: {
+ *     close: () => void
+ *   }
+ *   close: {}
+ * }>} FuroDialogSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroDialogContext
+ * }} FuroDialogSetup
+ */