@openreachtech/furo-vue 1.3.1

package/lib/components/organisms/FuroTabs/FuroTabsContext.js

@@ -0,0 +1,846 @@
+import {
+  onBeforeUnmount,
+  onMounted,
+  reactive,
+  ref,
+} from 'vue'
+
+import BaseFuroContext from '../../../contexts/BaseFuroContext.js'
+
+const DEFAULT_ORIENTATION = 'horizontal'
+const DEFAULT_VARIANT = 'line'
+const DEFAULT_SCROLL_PREVIOUS_LABEL = 'Scroll to previous tabs'
+const DEFAULT_SCROLL_NEXT_LABEL = 'Scroll to next tabs'
+const SCROLL_RATIO = 0.75
+const SCROLL_THRESHOLD = 1
+
+/**
+ * Trigger attributes the component owns, dropped from a tab's `attrs` bag.
+ * They carry the trigger-panel pairing, the element shape and the active state.
+ */
+const OWNED_TRIGGER_ATTRIBUTE_NAMES = new Set([
+  'value',
+  'disabled',
+  'as',
+  'asChild',
+  'as-child',
+  'id',
+  'role',
+  'type',
+  'aria-selected',
+  'aria-controls',
+  'data-state',
+  'data-disabled',
+  'data-orientation',
+])
+
+/**
+ * Context class for FuroTabs organism.
+ *
+ * @extends {BaseFuroContext<null, Props, EmitEventName>}
+ */
+export default class FuroTabsContext extends BaseFuroContext {
+  /**
+   * Constructor.
+   *
+   * @param {FuroTabsContextParams} params - Parameters of this constructor.
+   */
+  constructor ({
+    props,
+    componentContext,
+
+    refHash,
+    reactiveHash,
+  }) {
+    super({
+      props,
+      componentContext,
+    })
+
+    this.refHash = refHash
+    this.reactiveHash = reactiveHash
+  }
+
+  /**
+   * Factory method.
+   *
+   * @template {X extends typeof FuroTabsContext ? X : never} T, X
+   * @override
+   * @param {FuroTabsContextFactoryParams} params - Parameters of this factory method.
+   * @returns {InstanceType<T>} An instance of this class.
+   * @this {T}
+   */
+  static create ({
+    props,
+    componentContext,
+
+    refHash = this.buildRefHash(),
+    reactiveHash = this.buildReactiveHash(),
+  }) {
+    return /** @type {InstanceType<T>} */ (
+      new this({
+        props,
+        componentContext,
+
+        refHash,
+        reactiveHash,
+      })
+    )
+  }
+
+  /**
+   * Build ref hash.
+   *
+   * @override
+   * @returns {FuroTabsContextParams['refHash']}
+   */
+  static buildRefHash () {
+    return {
+      activeValueRef: ref(null),
+      viewportElementRef: ref(null),
+      resizeObserverRef: ref(null),
+    }
+  }
+
+  /**
+   * Build reactive hash.
+   *
+   * @override
+   * @returns {FuroTabsContextParams['reactiveHash']}
+   */
+  static buildReactiveHash () {
+    return {
+      scrollStateReactive: reactive({
+        canScrollPrevious: false,
+        canScrollNext: false,
+      }),
+    }
+  }
+
+  /**
+   * Get emit event name.
+   *
+   * @override
+   * @returns {Readonly<{
+   *   TAB_CHANGE: 'tab:change'
+   *   UPDATE_VALUE: 'update:value'
+   * }>}
+   */
+  static get EMIT_EVENT_NAME () {
+    return {
+      TAB_CHANGE: 'tab:change',
+      UPDATE_VALUE: 'update:value',
+    }
+  }
+
+  /**
+   * Get emit options.
+   *
+   * @returns {{
+   *   'tab:change': (payload: {
+   *     value: string
+   *   }) => void
+   *   'update:value': (value: string) => void
+   * }}
+   */
+  static get EMIT_EVENT_HASH () {
+    return {
+      [this.EMIT_EVENT_NAME.TAB_CHANGE]: payload => {},
+      [this.EMIT_EVENT_NAME.UPDATE_VALUE]: payload => {},
+    }
+  }
+
+  /**
+   * get: ResizeObserverCtor
+   *
+   * @returns {typeof ResizeObserver | null}
+   */
+  static get ResizeObserverCtor () {
+    return globalThis.ResizeObserver
+      ?? null
+  }
+
+  /**
+   * get: Constructor of this class.
+   *
+   * @override
+   * @returns {typeof FuroTabsContext}
+   */
+  get Ctor () {
+    return /** @type {typeof FuroTabsContext} */ (
+      this.constructor
+    )
+  }
+
+  /**
+   * Get internal active value ref (uncontrolled mode).
+   *
+   * @returns {import('vue').Ref<string | null>}
+   */
+  get activeValueRef () {
+    return this.refHash.activeValueRef
+  }
+
+  /**
+   * Get the scrollable viewport element ref.
+   *
+   * @returns {import('vue').Ref<HTMLElement | null>}
+   */
+  get viewportElementRef () {
+    return this.refHash.viewportElementRef
+  }
+
+  /**
+   * get: resizeObserverRef
+   *
+   * @returns {import('vue').Ref<ResizeObserver | null>}
+   */
+  get resizeObserverRef () {
+    return this.refHash.resizeObserverRef
+  }
+
+  /**
+   * Get the scroll button state.
+   *
+   * @returns {import('vue').Reactive<{
+   *   canScrollPrevious: boolean
+   *   canScrollNext: boolean
+   * }>}
+   */
+  get scrollStateReactive () {
+    return this.reactiveHash.scrollStateReactive
+  }
+
+  /**
+   * Parcel passed from parent via props.
+   *
+   * @override
+   * @returns {NonNullable<Props['parcel']>}
+   */
+  get parcel () {
+    return {
+      tabs: [],
+      orientation: DEFAULT_ORIENTATION,
+      variant: DEFAULT_VARIANT,
+      scrollable: false,
+      showPanels: true,
+      showIndicator: true,
+      disabled: false,
+      scrollPreviousLabel: DEFAULT_SCROLL_PREVIOUS_LABEL,
+      scrollNextLabel: DEFAULT_SCROLL_NEXT_LABEL,
+      ...this.props.parcel,
+    }
+  }
+
+  /**
+   * Normalized per-tab entries for rendering.
+   *
+   * @returns {Array<TabEntry>}
+   */
+  get tabEntries () {
+    return (this.parcel?.tabs ?? [])
+      .map(it => ({
+        value: it.value,
+        label: it.label,
+        disabled: Boolean(it.disabled),
+        panelSlotName: it.slotName ?? it.value,
+        triggerSlotName: `label-${it.value}`,
+        attrs: it.attrs ?? null,
+        className: it.class ?? null,
+      }))
+  }
+
+  /**
+   * Whether the active tab is controlled via `parcel.value`.
+   *
+   * @returns {boolean}
+   */
+  isControlled () {
+    const { parcel } = this.props
+
+    return parcel !== null
+      && Object.hasOwn(parcel, 'value')
+  }
+
+  /**
+   * Whether the whole tab set is disabled.
+   *
+   * @returns {boolean}
+   */
+  isDisabled () {
+    const disabledByParcel = Boolean(this.parcel?.disabled)
+    const disabledByAttrs = this.hasBooleanAttribute({ name: 'disabled' })
+
+    return disabledByParcel || disabledByAttrs
+  }
+
+  /**
+   * Whether the tab set lays out vertically.
+   *
+   * @returns {boolean}
+   */
+  isVertical () {
+    return this.extractOrientation() === 'vertical'
+  }
+
+  /**
+   * Whether the underline `line` variant is active.
+   *
+   * @returns {boolean}
+   */
+  isLineVariant () {
+    return this.extractVariant() === 'line'
+  }
+
+  /**
+   * Whether the segmented `solid` variant is active.
+   *
+   * @returns {boolean}
+   */
+  isSolidVariant () {
+    return this.extractVariant() === 'solid'
+  }
+
+  /**
+   * Whether the trigger row scrolls with navigation buttons.
+   *
+   * @returns {boolean}
+   */
+  isScrollable () {
+    return this.parcel?.scrollable === true
+  }
+
+  /**
+   * Whether tab panels render. When false, the component is a navigation menu
+   * only (e.g. the active value drives an external `router-view`).
+   *
+   * @returns {boolean}
+   */
+  shouldShowPanels () {
+    return this.parcel?.showPanels !== false
+  }
+
+  /**
+   * Whether the animated active-tab indicator renders.
+   * The indicator is exclusive to the `line` variant; the `solid` variant marks
+   * the active tab with a static background instead.
+   *
+   * @returns {boolean}
+   */
+  shouldShowIndicator () {
+    return this.isLineVariant()
+      && this.parcel?.showIndicator !== false
+  }
+
+  /**
+   * Resolve the visual variant.
+   *
+   * @returns {'line' | 'solid'}
+   */
+  extractVariant () {
+    return this.parcel?.variant
+      ?? DEFAULT_VARIANT
+  }
+
+  /**
+   * Resolve the layout orientation.
+   *
+   * @returns {'horizontal' | 'vertical'}
+   */
+  extractOrientation () {
+    return this.parcel?.orientation
+      ?? DEFAULT_ORIENTATION
+  }
+
+  /**
+   * Resolve the icon name for the scroll-toward-start button.
+   *
+   * @returns {string}
+   */
+  extractScrollPreviousIcon () {
+    return this.isVertical()
+      ? 'ph:caret-up'
+      : 'ph:caret-left'
+  }
+
+  /**
+   * Resolve the icon name for the scroll-toward-end button.
+   *
+   * @returns {string}
+   */
+  extractScrollNextIcon () {
+    return this.isVertical()
+      ? 'ph:caret-down'
+      : 'ph:caret-right'
+  }
+
+  /**
+   * Resolve the accessible name of the scroll-toward-start button.
+   *
+   * @returns {string}
+   */
+  extractScrollPreviousLabel () {
+    return this.parcel?.scrollPreviousLabel
+      ?? DEFAULT_SCROLL_PREVIOUS_LABEL
+  }
+
+  /**
+   * Resolve the accessible name of the scroll-toward-end button.
+   *
+   * @returns {string}
+   */
+  extractScrollNextLabel () {
+    return this.parcel?.scrollNextLabel
+      ?? DEFAULT_SCROLL_NEXT_LABEL
+  }
+
+  /**
+   * Resolve the value of the first tab, if any.
+   *
+   * @returns {string | null}
+   */
+  extractFirstTabValue () {
+    return this.tabEntries[0]?.value
+      ?? null
+  }
+
+  /**
+   * Resolve the active tab value for the root host element.
+   * `parcel.value` takes precedence; otherwise the internal ref,
+   * falling back to the first tab.
+   *
+   * @returns {string | null}
+   */
+  extractActiveValue () {
+    if (this.isControlled()) {
+      return this.parcel?.value
+        ?? null
+    }
+
+    return this.activeValueRef.value
+      ?? this.extractFirstTabValue()
+  }
+
+  /**
+   * Extract attributes for the root host element.
+   * The `model-value` key is only included when an active value exists, so the
+   * primitive (whose `model-value` is `string`, never `null`) stays uncontrolled
+   * when there is no active tab.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  extractRootAttributes () {
+    const optionalAttributes = this.buildOptionalRootAttributes()
+
+    return {
+      orientation: this.extractOrientation(),
+      ...optionalAttributes,
+    }
+  }
+
+  /**
+   * Build the optional root attributes that are only included when present.
+   *
+   * @returns {Record<string, unknown>}
+   */
+  buildOptionalRootAttributes () {
+    const entries = [
+      ['modelValue', this.extractActiveValue()],
+    ]
+      .filter(([, attributeValue]) => attributeValue !== null)
+
+    return Object.fromEntries(entries)
+  }
+
+  /**
+   * Extract root class names.
+   *
+   * @returns {Record<string, boolean>}
+   */
+  extractRootClassNames () {
+    return {
+      'unit-tabs': true,
+      line: this.isLineVariant(),
+      solid: this.isSolidVariant(),
+      vertical: this.isVertical(),
+      scrollable: this.isScrollable(),
+      disabled: this.isDisabled(),
+    }
+  }
+
+  /**
+   * Build attributes of a single trigger. The component-owned attributes win:
+   * the bag loses every one of them before the tab's own values are applied.
+   *
+   * @param {{
+   *   entry: TabEntry
+   * }} params - Parameters.
+   * @returns {Record<string, *>} Attributes of the trigger.
+   */
+  buildTriggerAttributes ({
+    entry,
+  }) {
+    const bagEntries = Object.entries(entry.attrs ?? {})
+      .filter(([attributeName]) => !OWNED_TRIGGER_ATTRIBUTE_NAMES.has(attributeName))
+
+    return {
+      ...Object.fromEntries(bagEntries),
+      value: entry.value,
+      disabled: entry.disabled,
+    }
+  }
+
+  /**
+   * Build class names of a single trigger.
+   *
+   * @param {{
+   *   entry: TabEntry
+   * }} params - Parameters.
+   * @returns {Array<string | null>} Class names of the trigger.
+   */
+  buildTriggerClassNames ({
+    entry,
+  }) {
+    return [
+      'tab',
+      entry.className,
+    ]
+  }
+
+  /**
+   * Whether a given tab is the active one.
+   *
+   * @param {{
+   *   value: string
+   * }} params
+   * @returns {boolean}
+   */
+  isActiveTab ({
+    value,
+  }) {
+    return this.extractActiveValue() === value
+  }
+
+  /**
+   * Handle active-tab changes from the root host element.
+   *
+   * @param {{
+   *   value: string
+   * }} params
+   */
+  onTabChange ({
+    value,
+  }) {
+    if (!this.isControlled()) {
+      this.activeValueRef.value = value
+    }
+
+    this.emit(
+      this.EMIT_EVENT_NAME.UPDATE_VALUE,
+      value
+    )
+
+    this.emit(
+      this.EMIT_EVENT_NAME.TAB_CHANGE,
+      {
+        value,
+      }
+    )
+  }
+
+  /**
+   * Setup component context.
+   *
+   * @template {X extends FuroTabsContext ? X : never} T, X
+   * @override
+   * @returns {T} For method chaining.
+   * @this {T}
+   */
+  setupComponent () {
+    onMounted(() => {
+      this.setupScrollObservation()
+      this.updateScrollState()
+    })
+
+    onBeforeUnmount(() => {
+      this.teardownScrollObservation()
+    })
+
+    return this
+  }
+
+  /**
+   * Observe the viewport size to recompute scroll button state.
+   */
+  setupScrollObservation () {
+    const element = this.viewportElementRef.value
+    const observer = this.createResizeObserver()
+
+    if (!element || !observer) {
+      return
+    }
+
+    observer.observe(element)
+
+    this.resizeObserverRef.value = observer
+  }
+
+  /**
+   * Create the observer that recomputes scroll button state on a size change.
+   *
+   * @returns {ResizeObserver | null}
+   */
+  createResizeObserver () {
+    const {
+      ResizeObserverCtor,
+    } = this.Ctor
+
+    if (!ResizeObserverCtor) {
+      return null
+    }
+
+    return new ResizeObserverCtor(() => {
+      this.updateScrollState()
+    })
+  }
+
+  /**
+   * Disconnect the viewport size observer.
+   */
+  teardownScrollObservation () {
+    if (!this.resizeObserverRef.value) {
+      return
+    }
+
+    this.resizeObserverRef.value.disconnect()
+
+    this.resizeObserverRef.value = null
+  }
+
+  /**
+   * Recompute whether the viewport can scroll in either direction.
+   */
+  onScroll () {
+    this.updateScrollState()
+  }
+
+  /**
+   * Extract the current scroll position, viewport size, and total size
+   * along the active axis.
+   *
+   * @returns {{
+   *   position: number
+   *   size: number
+   *   total: number
+   * }}
+   */
+  extractScrollMetrics () {
+    const element = this.viewportElementRef.value
+
+    if (!element) {
+      return {
+        position: 0,
+        size: 0,
+        total: 0,
+      }
+    }
+
+    if (this.isVertical()) {
+      return {
+        position: element.scrollTop,
+        size: element.clientHeight,
+        total: element.scrollHeight,
+      }
+    }
+
+    return {
+      position: element.scrollLeft,
+      size: element.clientWidth,
+      total: element.scrollWidth,
+    }
+  }
+
+  /**
+   * Update the scroll button enabled state from the viewport metrics.
+   */
+  updateScrollState () {
+    const {
+      position,
+      size,
+      total,
+    } = this.extractScrollMetrics()
+
+    this.scrollStateReactive.canScrollPrevious = position > SCROLL_THRESHOLD
+    this.scrollStateReactive.canScrollNext = position + size < total - SCROLL_THRESHOLD
+  }
+
+  /**
+   * Scroll the viewport by a fraction of its size.
+   *
+   * @param {{
+   *   direction: number
+   * }} params - `-1` scrolls toward the start, `1` toward the end.
+   */
+  scrollByViewport ({
+    direction,
+  }) {
+    const element = this.viewportElementRef.value
+
+    if (!element) {
+      return
+    }
+
+    const {
+      size,
+    } = this.extractScrollMetrics()
+
+    const distance = direction * size * SCROLL_RATIO
+    const axis = this.isVertical()
+      ? 'top'
+      : 'left'
+
+    element.scrollBy({
+      [axis]: distance,
+      behavior: 'smooth',
+    })
+  }
+
+  /**
+   * Scroll the viewport toward the start.
+   */
+  onScrollPrevious () {
+    this.scrollByViewport({
+      direction: -1,
+    })
+  }
+
+  /**
+   * Scroll the viewport toward the end.
+   */
+  onScrollNext () {
+    this.scrollByViewport({
+      direction: 1,
+    })
+  }
+
+  /**
+   * Whether the viewport can scroll toward the start.
+   *
+   * @returns {boolean}
+   */
+  canScrollPrevious () {
+    return this.scrollStateReactive.canScrollPrevious
+  }
+
+  /**
+   * Whether the viewport can scroll toward the end.
+   *
+   * @returns {boolean}
+   */
+  canScrollNext () {
+    return this.scrollStateReactive.canScrollNext
+  }
+}
+
+/**
+ * @typedef {import('../../../contexts/BaseFuroContext.js').BaseFuroContextParams & {
+ *   props: Props
+ *   componentContext: ComponentContext
+ *   refHash: {
+ *     activeValueRef: import('vue').Ref<string | null>
+ *     viewportElementRef: import('vue').Ref<HTMLElement | null>
+ *     resizeObserverRef: import('vue').Ref<ResizeObserver | null>
+ *   }
+ *   reactiveHash: {
+ *     scrollStateReactive: import('vue').Reactive<{
+ *       canScrollPrevious: boolean
+ *       canScrollNext: boolean
+ *     }>
+ *   }
+ * }} FuroTabsContextParams
+ */
+
+/**
+ * @typedef {Omit<FuroTabsContextParams, 'refHash' | 'reactiveHash'> & {
+ *   refHash?: FuroTabsContextParams['refHash']
+ *   reactiveHash?: FuroTabsContextParams['reactiveHash']
+ * }} FuroTabsContextFactoryParams
+ */
+
+/**
+ * @typedef {keyof typeof FuroTabsContext.EMIT_EVENT_NAME} EmitEventName
+ */
+
+/**
+ * @typedef {import('vue').HTMLAttributes & {
+ *   parcel?: FuroTabsParcel | null
+ * }} Props
+ */
+
+/**
+ * Closed-set Furo behavior for `<FuroTabs>`.
+ * JSON-serializable only. Not an open passthrough to the internal tabs primitive.
+ *
+ * @typedef {{
+ *   tabs?: Array<FuroTabsTab>
+ *   value?: string | null
+ *   orientation?: 'horizontal' | 'vertical'
+ *   variant?: 'line' | 'solid'
+ *   scrollable?: boolean
+ *   showPanels?: boolean
+ *   showIndicator?: boolean
+ *   disabled?: boolean
+ *   scrollPreviousLabel?: string
+ *   scrollNextLabel?: string
+ * }} FuroTabsParcel
+ */
+
+/**
+ * A single tab. `value` reaches the DOM inside the trigger and panel element ids,
+ * so pass a token that is valid in an id rather than raw server data.
+ *
+ * @typedef {{
+ *   value: string
+ *   label: string
+ *   slotName?: string
+ *   disabled?: boolean
+ *   attrs?: Record<string, string | number | boolean>
+ *   class?: string
+ * }} FuroTabsTab
+ */
+
+/**
+ * @typedef {{
+ *   value: string
+ *   label: string
+ *   disabled: boolean
+ *   panelSlotName: string
+ *   triggerSlotName: string
+ *   attrs: Record<string, string | number | boolean> | null
+ *   className: string | null
+ * }} TabEntry
+ */
+
+/**
+ * @typedef {import('vue').SetupContext<FuroTabsEmitHash, FuroTabsSlots>} ComponentContext
+ */
+
+/**
+ * @typedef {typeof FuroTabsContext.EMIT_EVENT_HASH} FuroTabsEmitHash
+ */
+
+/**
+ * @typedef {import('vue').SlotsType<Record<string, {
+ *   value: string
+ *   label?: string
+ * }>>} FuroTabsSlots
+ */
+
+/**
+ * @typedef {(
+ *   props: Props,
+ *   componentContext: ComponentContext
+ * ) => {
+ *   context: FuroTabsContext
+ * }} FuroTabsSetup
+ */