@openreachtech/furo-vue 1.3.1

package/lib/components/molecules/FuroAccordion/FuroAccordionContext.js

@@ -0,0 +1,547 @@
+import {
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+import AccordionEmitPayload from './AccordionEmitPayload.js'
+
+/**
+ * Furo-owned parcel keys (not forwarded to the underlying primitive root).
+ */
+const FURO_ACCORDION_PARCEL_KEYS = new Set([
+  'value',
+  'selectionMode',
+  'options',
+  'collapsible',
+  'disabled',
+  'orientation',
+])
+
+/**
+ * Context class for managing FuroAccordion molecule.
+ *
+ * Multi-section collapse: a vertical stack of headers, each toggling its own
+ * content region. `single` mode keeps at most one section open; `multiple`
+ * mode allows several. The public value (`v-model:value`, `parcel.value`) is a
+ * single value in `single` mode and an array in `multiple` mode.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroAccordionContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroAccordionContextParams} params
+   */
+  constructor ({
+    props,
+    componentContext,
+    refHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroAccordionContext ? X : never} T, X
+   * @override
+   * @param {FuroAccordionContextFactoryParams} 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
+   */
+  static buildRefHash () {
+    return {
+      internalValueRef: ref(null),
+      accordionRootElementRef: ref(null),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   CHANGE_VALUE: 'change-value'
+   *   UPDATE_VALUE: 'update:value'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      CHANGE_VALUE: 'change-value',
+      UPDATE_VALUE: 'update:value',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'change-value': (payload: import('./AccordionEmitPayload.js').default) => void
+   *   'update:value': (value: FuroAccordionValue) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.CHANGE_VALUE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_VALUE]: value => {},
+    }
+  }
+
+  /**
+   * get: Constructor of `EmitPayload`.
+   *
+   * @returns {typeof AccordionEmitPayload}
+   */
+  static get EmitPayloadCtor () {
+    return AccordionEmitPayload
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroAccordionContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroAccordionContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal value ref (synced expansion model).
+   *
+   * @returns {import('vue').Ref<FuroAccordionValue>}
+   */
+  get internalValueRef () {
+    return this.refHash.internalValueRef
+  }
+
+  /**
+   * Get accordion root element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get accordionRootElementRef () {
+    return this.refHash.accordionRootElementRef
+  }
+
+  /**
+   * Parcel passed from parent via props (merged with defaults).
+   *
+   * @override
+   * @returns {FuroAccordionParcel}
+   */
+  get parcel () {
+    return {
+      selectionMode: 'single',
+      options: [],
+      collapsible: true,
+      disabled: false,
+      orientation: 'vertical',
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Get the section options.
+   *
+   * @returns {Array<FuroAccordionOption>}
+   */
+  get options () {
+    return this.parcel.options
+      ?? []
+  }
+
+  /**
+   * Resolve the selection mode (maps to the primitive's type prop).
+   *
+   * @returns {FuroAccordionSelectionMode}
+   */
+  resolveSelectionMode () {
+    return this.parcel.selectionMode
+      ?? 'single'
+  }
+
+  /**
+   * Resolve the layout orientation.
+   *
+   * @returns {FuroAccordionOrientation}
+   */
+  resolveOrientation () {
+    return this.parcel.orientation
+      ?? 'vertical'
+  }
+
+  /**
+   * Whether multiple sections can be open at once.
+   *
+   * @returns {boolean}
+   */
+  isMultiple () {
+    return this.resolveSelectionMode() === 'multiple'
+  }
+
+  /**
+   * Whether an open section can be closed by clicking its header.
+   * Only meaningful in `single` mode; `multiple` mode is always collapsible.
+   *
+   * @returns {boolean}
+   */
+  isCollapsible () {
+    if (this.isMultiple()) {
+      return true
+    }
+
+    return Boolean(this.parcel.collapsible)
+  }
+
+  /**
+   * Resolve the default empty expansion for the current selection mode.
+   *
+   * @returns {FuroAccordionValue}
+   */
+  resolveDefaultValue () {
+    if (this.isMultiple()) {
+      return []
+    }
+
+    return null
+  }
+
+  /**
+   * Whether the parent controls `parcel.value`.
+   *
+   * @returns {boolean}
+   */
+  isControlled () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'value')
+  }
+
+  /**
+   * Resolve synced expansion value from parcel or fallthrough attrs.
+   *
+   * @returns {FuroAccordionValue}
+   */
+  resolveSyncedValue () {
+    const { parcel: parcelSource } = this.props
+
+    const hasParcelValue = parcelSource !== null
+      && Object.hasOwn(parcelSource, 'value')
+
+    if (hasParcelValue) {
+      return parcelSource.value
+        ?? this.resolveDefaultValue()
+    }
+
+    const { value: attrsValue } = this.attrs ?? {}
+
+    if (attrsValue !== undefined) {
+      return /** @type {FuroAccordionValue} */ (attrsValue)
+    }
+
+    return this.resolveDefaultValue()
+  }
+
+  /**
+   * Whether the accordion is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    return Boolean(this.parcel.disabled)
+      || this.hasBooleanAttribute({ name: 'disabled' })
+  }
+
+  /**
+   * Whether a single section is disabled.
+   *
+   * @param {{
+   *   option: FuroAccordionOption
+   * }} params - Parameters.
+   * @returns {boolean}
+   */
+  isOptionDisabled ({
+    option,
+  }) {
+    return this.isDisabled()
+      || Boolean(option.disabled)
+  }
+
+  /**
+   * Whether the given section value is currently expanded.
+   *
+   * @param {{
+   *   value: string
+   * }} params - Parameters.
+   * @returns {boolean}
+   */
+  isExpanded ({
+    value,
+  }) {
+    const expandedValue = this.internalValueRef.value
+
+    if (Array.isArray(expandedValue)) {
+      return expandedValue.includes(value)
+    }
+
+    return expandedValue === value
+  }
+
+  /**
+   * Extract the display label for a section.
+   *
+   * @param {{
+   *   option: FuroAccordionOption
+   * }} params - Parameters.
+   * @returns {string}
+   */
+  extractOptionLabel ({
+    option,
+  }) {
+    return option.label
+      ?? option.value
+  }
+
+  /**
+   * Extract CSS class map for the accordion root.
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractRootClassNames () {
+    const orientation = this.resolveOrientation()
+
+    return Object.fromEntries([
+      ['unit-accordion', true],
+      [orientation, true],
+      ['disabled', this.isDisabled()],
+    ])
+  }
+
+  /**
+   * Extract CSS class map for a single accordion item.
+   *
+   * @param {{
+   *   option: FuroAccordionOption
+   * }} params - Parameters.
+   * @returns {Record<string, boolean>}
+   */
+  extractItemClassNames ({
+    option,
+  }) {
+    return Object.fromEntries([
+      ['unit-accordion-item', true],
+      ['disabled', this.isOptionDisabled({ option })],
+    ])
+  }
+
+  /**
+   * Extract root attributes forwarded to the underlying primitive.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const parcelEntries = Object.entries(this.parcel)
+
+    return Object.fromEntries(
+      parcelEntries.filter(([key]) => !FURO_ACCORDION_PARCEL_KEYS.has(key))
+    )
+  }
+
+  /**
+   * Build a custom event for expansion changes.
+   *
+   * @param {{
+   *   name: string
+   *   value: FuroAccordionValue
+   * }} params - Parameters.
+   * @returns {import('./AccordionEmitPayload.js').AccordionRawEvent}
+   */
+  buildCustomEvent ({
+    name,
+    value,
+  }) {
+    return new CustomEvent(
+      name,
+      {
+        detail: {
+          target: this.accordionRootElementRef.value,
+          value,
+        },
+      }
+    )
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroAccordionContext ? X : never} T, X
+   * @override
+   * @returns {T} - For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    this.watch(
+      () => this.resolveSyncedValue(),
+      syncedValue => {
+        if (!this.isControlled()) {
+          return
+        }
+
+        this.internalValueRef.value = syncedValue
+      },
+      {
+        immediate: true,
+      }
+    )
+
+    return this
+  }
+
+  /**
+   * Handle expansion update emitted by the underlying primitive.
+   *
+   * @param {{
+   *   rawValue: FuroAccordionValue
+   * }} params - Parameters.
+   */
+  onChangeValue ({
+    rawValue,
+  }) {
+    const value = rawValue
+      ?? this.resolveDefaultValue()
+
+    this.internalValueRef.value = value
+
+    const customEvent = this.buildCustomEvent({
+      name: this.EMIT_EVENT_NAME.CHANGE_VALUE,
+      value,
+    })
+
+    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,
+      value
+    )
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     internalValueRef: import('vue').Ref<FuroAccordionValue>
+ *     accordionRootElementRef: import('vue').Ref<HTMLElement | null>
+ *   }
+ * }} FuroAccordionContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroAccordionContextParams, 'refHash'> & {
+ *   refHash?: {
+ *     internalValueRef: import('vue').Ref<FuroAccordionValue>
+ *     accordionRootElementRef: import('vue').Ref<HTMLElement | null>
+ *   }
+ * }} FuroAccordionContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroAccordionContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * Public expansion model (`v-model:value`, `parcel.value`).
+ * A single value in `single` mode, an array in `multiple` mode.
+ *
+ * @typedef {string | Array<string> | null} FuroAccordionValue
+ */
+
+/**
+ * @typedef {'single' | 'multiple'} FuroAccordionSelectionMode
+ */
+
+/**
+ * @typedef {'vertical' | 'horizontal'} FuroAccordionOrientation
+ */
+
+/**
+ * @typedef {{
+ *   value: string
+ *   label?: string
+ *   disabled?: boolean
+ * }} FuroAccordionOption
+ */
+
+/**
+ * @typedef {{
+ *   parcel?: FuroAccordionParcel | null
+ * }} Props
+ */
+
+/**
+ * @typedef {{
+ *   value?: FuroAccordionValue
+ *   selectionMode?: FuroAccordionSelectionMode
+ *   options?: Array<FuroAccordionOption>
+ *   collapsible?: boolean
+ *   disabled?: boolean
+ *   orientation?: FuroAccordionOrientation
+ * }} FuroAccordionParcel
+ */
+
+/**
+ * @typedef {typeof FuroAccordionContext.EMIT_EVENT_HASH} FuroAccordionEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroAccordionEmitHash>} ComponentContext
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroAccordionContext
+ * }} FuroAccordionSetup
+ */