base-ui-vue 0.3.0 → 0.5.0

package/src/utils/usePopupAutoResize.ts

@@ -0,0 +1,254 @@
+import type { MaybeRefOrGetter } from 'vue'
+import type { TextDirection } from '../direction-provider/DirectionContext'
+import type { Dimensions } from '../floating-ui-vue/types'
+import type { Side } from './useAnchorPositioning'
+import { computed, nextTick, onBeforeUnmount, shallowRef, toValue, watch } from 'vue'
+import { EMPTY_OBJECT } from './constants'
+import { NOOP } from './empty'
+import { getCssDimensions } from './getCssDimensions'
+import { useAnimationFrame } from './useAnimationFrame'
+import { useAnimationsFinished } from './useAnimationsFinished'
+
+/**
+ * Allows the popup to resize based on changed content while preserving CSS transitions.
+ */
+export function usePopupAutoResize(parameters: UsePopupAutoResizeParameters) {
+  const popupElement = computed(() => toValue(parameters.popupElement) ?? null)
+  const positionerElement = computed(() => toValue(parameters.positionerElement) ?? null)
+  const mounted = computed(() => toValue(parameters.mounted))
+  const content = computed(() => toValue(parameters.content))
+  const side = computed(() => toValue(parameters.side) ?? 'top')
+  const direction = computed(() => toValue(parameters.direction) ?? 'ltr')
+
+  const runOnceAnimationsFinish = useAnimationsFinished(popupElement, true, false)
+  const animationFrame = useAnimationFrame()
+  const committedDimensions = shallowRef<Dimensions | null>(null)
+  const isInitialRender = shallowRef(true)
+
+  let restoreAnchoringStyles = NOOP
+
+  const anchoringStyles = computed(() => getAnchoringStyles(side.value, direction.value))
+
+  watch(
+    [
+      mounted,
+      popupElement,
+      positionerElement,
+      content,
+      anchoringStyles,
+    ],
+    ([isMounted, popup, positioner], _previous, onCleanup) => {
+      if (!isMounted) {
+        restoreAnchoringStyles()
+        restoreAnchoringStyles = NOOP
+        isInitialRender.value = true
+        committedDimensions.value = null
+        return
+      }
+
+      if (!popup || !positioner) {
+        return
+      }
+
+      restoreAnchoringStyles = applyElementStyles(popup, anchoringStyles.value)
+
+      setPopupCssSize(popup, 'auto')
+
+      const restorePopupPosition = overrideElementStyle(popup, 'position', 'static')
+      const restorePopupTransform = overrideElementStyle(popup, 'transform', 'none')
+      const restorePopupScale = overrideElementStyle(popup, 'scale', '1')
+      const restorePositionerAvailableSize = applyElementStyles(positioner, {
+        '--available-width': 'max-content',
+        '--available-height': 'max-content',
+      })
+
+      function restoreMeasurementOverrides() {
+        restorePopupPosition()
+        restorePopupTransform()
+        restorePositionerAvailableSize()
+      }
+
+      function restoreMeasurementOverridesIncludingScale() {
+        restoreMeasurementOverrides()
+        restorePopupScale()
+      }
+
+      parameters.onMeasureLayout?.()
+
+      if (isInitialRender.value || committedDimensions.value == null) {
+        setPositionerCssSize(positioner, 'max-content')
+
+        const dimensions = getCssDimensions(popup)
+
+        committedDimensions.value = dimensions
+
+        commitPositionerCssSize(positioner, dimensions)
+        restoreMeasurementOverridesIncludingScale()
+        parameters.onMeasureLayoutComplete?.(null, dimensions)
+
+        isInitialRender.value = false
+
+        onCleanup(() => {
+          restoreAnchoringStyles()
+          restoreAnchoringStyles = NOOP
+        })
+
+        return
+      }
+
+      setPositionerCssSize(positioner, 'max-content')
+
+      const previousDimensions = committedDimensions.value
+      const newDimensions = getCssDimensions(popup)
+
+      committedDimensions.value = newDimensions
+
+      setPopupCssSize(popup, previousDimensions)
+      restoreMeasurementOverridesIncludingScale()
+      parameters.onMeasureLayoutComplete?.(previousDimensions, newDimensions)
+
+      commitPositionerCssSize(positioner, newDimensions)
+
+      const abortController = new AbortController()
+
+      animationFrame.request(() => {
+        setPopupCssSize(popup, newDimensions)
+
+        runOnceAnimationsFinish(() => {
+          popup.style.setProperty('--popup-width', 'auto')
+          popup.style.setProperty('--popup-height', 'auto')
+        }, abortController.signal)
+      })
+
+      onCleanup(() => {
+        abortController.abort()
+        animationFrame.cancel()
+        restoreAnchoringStyles()
+        restoreAnchoringStyles = NOOP
+      })
+    },
+    { flush: 'post', immediate: true },
+  )
+
+  onBeforeUnmount(() => {
+    animationFrame.cancel()
+    restoreAnchoringStyles()
+    restoreAnchoringStyles = NOOP
+  })
+}
+
+interface UsePopupAutoResizeParameters {
+  /**
+   * Element to resize.
+   */
+  popupElement: MaybeRefOrGetter<HTMLElement | null | undefined>
+  /**
+   * Positioner element, the parent of the popup.
+   */
+  positionerElement: MaybeRefOrGetter<HTMLElement | null | undefined>
+  /**
+   * Whether the popup is mounted.
+   */
+  mounted: MaybeRefOrGetter<boolean>
+  /**
+   * Content value that should trigger a resize.
+   */
+  content: MaybeRefOrGetter<unknown>
+  /**
+   * Callback fired before measuring the new layout.
+   */
+  onMeasureLayout?: (() => void) | undefined
+  /**
+   * Callback fired after the new dimensions have been measured.
+   */
+  onMeasureLayoutComplete?:
+    | ((previousDimensions: Dimensions | null, newDimensions: Dimensions) => void)
+    | undefined
+  /**
+   * Current logical side of the popup.
+   */
+  side: MaybeRefOrGetter<Side | undefined>
+  /**
+   * Current text direction.
+   */
+  direction: MaybeRefOrGetter<TextDirection>
+}
+
+function getAnchoringStyles(side: Side, direction: TextDirection): Record<string, string> {
+  let isOriginSide = side === 'top'
+  let isPhysicalLeft = side === 'left'
+
+  if (direction === 'rtl') {
+    isOriginSide = isOriginSide || side === 'inline-end'
+    isPhysicalLeft = isPhysicalLeft || side === 'inline-end'
+  }
+  else {
+    isOriginSide = isOriginSide || side === 'inline-start'
+    isPhysicalLeft = isPhysicalLeft || side === 'inline-start'
+  }
+
+  if (!isOriginSide) {
+    return EMPTY_OBJECT as Record<string, string>
+  }
+
+  return {
+    position: 'absolute',
+    [side === 'top' ? 'bottom' : 'top']: '0',
+    [isPhysicalLeft ? 'right' : 'left']: '0',
+  }
+}
+
+function overrideElementStyle(element: HTMLElement, property: string, value: string) {
+  const originalValue = element.style.getPropertyValue(property)
+
+  element.style.setProperty(property, value)
+
+  return () => {
+    if (originalValue) {
+      element.style.setProperty(property, originalValue)
+    }
+    else {
+      element.style.removeProperty(property)
+    }
+  }
+}
+
+function applyElementStyles(element: HTMLElement, styles: Record<string, string>) {
+  const restorers: Array<() => void> = []
+
+  for (const [key, value] of Object.entries(styles)) {
+    restorers.push(overrideElementStyle(element, key, value))
+  }
+
+  return restorers.length
+    ? () => {
+        restorers.forEach(restore => restore())
+      }
+    : NOOP
+}
+
+function setPopupCssSize(popupElement: HTMLElement, size: Dimensions | 'auto') {
+  const width = size === 'auto' ? 'auto' : `${size.width}px`
+  const height = size === 'auto' ? 'auto' : `${size.height}px`
+
+  popupElement.style.setProperty('--popup-width', width)
+  popupElement.style.setProperty('--popup-height', height)
+}
+
+function setPositionerCssSize(positionerElement: HTMLElement, size: Dimensions | 'max-content') {
+  const width = size === 'max-content' ? 'max-content' : `${size.width}px`
+  const height = size === 'max-content' ? 'max-content' : `${size.height}px`
+
+  positionerElement.style.setProperty('--positioner-width', width)
+  positionerElement.style.setProperty('--positioner-height', height)
+}
+
+function commitPositionerCssSize(positionerElement: HTMLElement, size: Dimensions) {
+  setPositionerCssSize(positionerElement, size)
+
+  nextTick(() => {
+    if (positionerElement.isConnected) {
+      setPositionerCssSize(positionerElement, size)
+    }
+  })
+}

package/src/utils/usePopupViewport.ts

@@ -0,0 +1,398 @@
+import type { ComputedRef, MaybeRefOrGetter, ShallowRef } from 'vue'
+import type { TextDirection } from '../direction-provider/DirectionContext'
+import type { Dimensions } from '../floating-ui-vue/types'
+import type { Side } from './useAnchorPositioning'
+import { computed, nextTick, onBeforeUnmount, shallowRef, toValue, watch } from 'vue'
+import { TransitionStatusDataAttributes } from './stateAttributesMapping'
+import { useAnimationFrame } from './useAnimationFrame'
+import { useAnimationsFinished } from './useAnimationsFinished'
+import { usePopupAutoResize } from './usePopupAutoResize'
+
+export interface PopupViewportCssVars {
+  /**
+   * CSS variable name storing the popup width for the previous content snapshot.
+   */
+  popupWidth: string
+  /**
+   * CSS variable name storing the popup height for the previous content snapshot.
+   */
+  popupHeight: string
+}
+
+export interface PopupViewportState {
+  /**
+   * Direction from which the popup was activated, used for directional animations.
+   */
+  activationDirection: string | undefined
+  /**
+   * Whether the viewport is currently transitioning between contents.
+   */
+  transitioning: boolean
+}
+
+export interface UsePopupViewportParameters {
+  /**
+   * The trigger currently associated with the open popup.
+   */
+  activeTriggerElement: MaybeRefOrGetter<Element | null | undefined>
+  /**
+   * ID of the active trigger.
+   */
+  activeTriggerId: MaybeRefOrGetter<string | null | undefined>
+  /**
+   * Whether the popup is open.
+   */
+  open: MaybeRefOrGetter<boolean>
+  /**
+   * Whether the popup is mounted.
+   */
+  mounted: MaybeRefOrGetter<boolean>
+  /**
+   * Element to resize.
+   */
+  popupElement: MaybeRefOrGetter<HTMLElement | null | undefined>
+  /**
+   * Positioner element, the parent of the popup.
+   */
+  positionerElement: MaybeRefOrGetter<HTMLElement | null | undefined>
+  /**
+   * Current logical side of the popup.
+   */
+  side: MaybeRefOrGetter<Side | undefined>
+  /**
+   * Current text direction.
+   */
+  direction: MaybeRefOrGetter<TextDirection>
+  /**
+   * Trigger payload used to render the current content.
+   */
+  payload: MaybeRefOrGetter<unknown>
+  /**
+   * CSS variable names used for sizing the previous content snapshot.
+   */
+  cssVars: PopupViewportCssVars
+}
+
+export interface UsePopupViewportResult {
+  /**
+   * Ref for the current content container.
+   */
+  currentContainerRef: ShallowRef<HTMLDivElement | null>
+  /**
+   * Ref for the previous content snapshot container.
+   */
+  previousContainerRef: ShallowRef<HTMLDivElement | null>
+  /**
+   * Key that remounts current content when triggers or delayed payloads change.
+   */
+  currentContentKey: ComputedRef<string>
+  /**
+   * Props for the current content container.
+   */
+  currentContainerProps: ComputedRef<Record<string, unknown>>
+  /**
+   * Props for the previous content snapshot container.
+   */
+  previousContainerProps: ComputedRef<Record<string, unknown>>
+  /**
+   * Whether the previous content snapshot should be rendered.
+   */
+  transitioning: ComputedRef<boolean>
+  /**
+   * Viewport state used for data attributes and render prop styling.
+   */
+  state: ComputedRef<PopupViewportState>
+}
+
+/**
+ * Builds morphing viewport containers for popups that animate between trigger-based content.
+ * Vue renders the new content normally and keeps a cloned DOM snapshot of the previous content
+ * around until the current container's animations finish.
+ */
+export function usePopupViewport(parameters: UsePopupViewportParameters): UsePopupViewportResult {
+  const activeTriggerElement = computed(() => toValue(parameters.activeTriggerElement) ?? null)
+  const activeTriggerId = computed(() => toValue(parameters.activeTriggerId) ?? null)
+  const open = computed(() => toValue(parameters.open))
+  const mounted = computed(() => toValue(parameters.mounted))
+  const payload = computed(() => toValue(parameters.payload))
+
+  const currentContainerRef = shallowRef<HTMLDivElement | null>(null)
+  const previousContainerRef = shallowRef<HTMLDivElement | null>(null)
+  const previousContentNode = shallowRef<HTMLDivElement | null>(null)
+  const previousContentDimensions = shallowRef<{ width: number, height: number } | null>(null)
+  const newTriggerOffset = shallowRef<Offset | null>(null)
+  const showStartingStyleAttribute = shallowRef(false)
+  const lastHandledTrigger = shallowRef<Element | null>(null)
+
+  const cleanupFrame = useAnimationFrame()
+  const onAnimationsFinished = useAnimationsFinished(currentContainerRef, true, false)
+  let animationAbortController: AbortController | null = null
+
+  const currentContentKey = usePopupContentKey(activeTriggerId, payload)
+
+  function abortPendingAnimationCleanup() {
+    animationAbortController?.abort()
+    animationAbortController = null
+  }
+
+  function clearPreviousContent() {
+    previousContentNode.value = null
+    previousContentDimensions.value = null
+  }
+
+  watch(
+    activeTriggerElement,
+    (nextTrigger, previousTrigger) => {
+      if (
+        !open.value
+        || !nextTrigger
+        || !previousTrigger
+        || nextTrigger === previousTrigger
+        || lastHandledTrigger.value === nextTrigger
+        || !currentContainerRef.value
+      ) {
+        return
+      }
+
+      abortPendingAnimationCleanup()
+
+      previousContentNode.value = cloneContent(currentContainerRef.value)
+      previousContentDimensions.value = measureElement(currentContainerRef.value)
+      showStartingStyleAttribute.value = true
+      newTriggerOffset.value = calculateRelativePosition(previousTrigger, nextTrigger)
+      const currentAnimationAbortController = new AbortController()
+      animationAbortController = currentAnimationAbortController
+
+      cleanupFrame.request(() => {
+        showStartingStyleAttribute.value = false
+
+        nextTick(() => {
+          onAnimationsFinished(() => {
+            if (currentAnimationAbortController.signal.aborted) {
+              return
+            }
+
+            if (animationAbortController === currentAnimationAbortController) {
+              animationAbortController = null
+            }
+
+            clearPreviousContent()
+          }, currentAnimationAbortController.signal)
+        })
+      })
+
+      lastHandledTrigger.value = nextTrigger
+    },
+    { flush: 'pre' },
+  )
+
+  watch(open, (isOpen) => {
+    if (!isOpen) {
+      abortPendingAnimationCleanup()
+      clearPreviousContent()
+      newTriggerOffset.value = null
+      lastHandledTrigger.value = null
+    }
+  })
+
+  watch(
+    [previousContainerRef, previousContentNode],
+    async ([container, previousNode]) => {
+      if (!container || !previousNode) {
+        return
+      }
+
+      await nextTick()
+
+      container.replaceChildren(
+        ...Array.from(previousNode.childNodes).map(node => node.cloneNode(true)),
+      )
+    },
+    { flush: 'post' },
+  )
+
+  onBeforeUnmount(() => {
+    abortPendingAnimationCleanup()
+    cleanupFrame.cancel()
+  })
+
+  function handleMeasureLayout() {
+    currentContainerRef.value?.style.setProperty('animation', 'none')
+    currentContainerRef.value?.style.setProperty('transition', 'none')
+
+    previousContainerRef.value?.style.setProperty('display', 'none')
+  }
+
+  function handleMeasureLayoutComplete(previousDimensions: Dimensions | null) {
+    currentContainerRef.value?.style.removeProperty('animation')
+    currentContainerRef.value?.style.removeProperty('transition')
+
+    previousContainerRef.value?.style.removeProperty('display')
+
+    if (previousDimensions && (previousDimensions.width > 0 || previousDimensions.height > 0)) {
+      previousContentDimensions.value = previousDimensions
+    }
+  }
+
+  usePopupAutoResize({
+    popupElement: parameters.popupElement,
+    positionerElement: parameters.positionerElement,
+    mounted,
+    content: payload,
+    onMeasureLayout: handleMeasureLayout,
+    onMeasureLayoutComplete: handleMeasureLayoutComplete,
+    side: parameters.side,
+    direction: parameters.direction,
+  })
+
+  const transitioning = computed(() => previousContentNode.value != null)
+
+  const currentContainerProps = computed(() => ({
+    'data-current': '',
+    [TransitionStatusDataAttributes.startingStyle]: showStartingStyleAttribute.value
+      ? ''
+      : undefined,
+  }))
+
+  const previousContainerProps = computed(() => ({
+    'data-previous': '',
+    'inert': '',
+    [TransitionStatusDataAttributes.endingStyle]: showStartingStyleAttribute.value
+      ? undefined
+      : '',
+    'style': {
+      ...(previousContentDimensions.value
+        ? {
+            [parameters.cssVars.popupWidth]: `${previousContentDimensions.value.width}px`,
+            [parameters.cssVars.popupHeight]: `${previousContentDimensions.value.height}px`,
+          }
+        : null),
+      position: 'absolute',
+    },
+  }))
+
+  const state = computed<PopupViewportState>(() => ({
+    activationDirection: getActivationDirection(newTriggerOffset.value),
+    transitioning: transitioning.value,
+  }))
+
+  return {
+    currentContainerRef,
+    previousContainerRef,
+    currentContentKey,
+    currentContainerProps,
+    previousContainerProps,
+    transitioning,
+    state,
+  }
+}
+
+interface Offset {
+  horizontal: number
+  vertical: number
+}
+
+function cloneContent(source: HTMLElement) {
+  const wrapper = source.ownerDocument.createElement('div')
+
+  for (const child of Array.from(source.childNodes)) {
+    wrapper.appendChild(child.cloneNode(true))
+  }
+
+  return wrapper
+}
+
+function measureElement(element: HTMLElement) {
+  const rect = element.getBoundingClientRect()
+
+  return {
+    width: rect.width,
+    height: rect.height,
+  }
+}
+
+/**
+ * Returns a string describing both the horizontal and vertical offset.
+ */
+function getActivationDirection(offset: Offset | null): string | undefined {
+  if (!offset) {
+    return undefined
+  }
+
+  return `${getValueWithTolerance(offset.horizontal, 5, 'right', 'left')} ${getValueWithTolerance(offset.vertical, 5, 'down', 'up')}`
+}
+
+function getValueWithTolerance(
+  value: number,
+  tolerance: number,
+  positiveLabel: string,
+  negativeLabel: string,
+) {
+  if (value > tolerance) {
+    return positiveLabel
+  }
+
+  if (value < -tolerance) {
+    return negativeLabel
+  }
+
+  return ''
+}
+
+/**
+ * Calculates the relative position between centers of two elements.
+ */
+function calculateRelativePosition(from: Element, to: Element): Offset {
+  const fromRect = from.getBoundingClientRect()
+  const toRect = to.getBoundingClientRect()
+
+  const fromCenter = {
+    x: fromRect.left + fromRect.width / 2,
+    y: fromRect.top + fromRect.height / 2,
+  }
+  const toCenter = {
+    x: toRect.left + toRect.width / 2,
+    y: toRect.top + toRect.height / 2,
+  }
+
+  return {
+    horizontal: toCenter.x - fromCenter.x,
+    vertical: toCenter.y - fromCenter.y,
+  }
+}
+
+/**
+ * Returns a key that forces remounting content when triggers change or a payload is updated.
+ */
+function usePopupContentKey(
+  activeTriggerId: ComputedRef<string | null>,
+  payload: ComputedRef<unknown>,
+): ComputedRef<string> {
+  const contentKey = shallowRef(0)
+  const previousActiveTriggerId = shallowRef(activeTriggerId.value)
+  const previousPayload = shallowRef(payload.value)
+  const pendingPayloadUpdate = shallowRef(false)
+
+  watch(
+    [activeTriggerId, payload],
+    ([nextActiveTriggerId, nextPayload]) => {
+      const triggerIdChanged = nextActiveTriggerId !== previousActiveTriggerId.value
+      const payloadChanged = nextPayload !== previousPayload.value
+
+      if (triggerIdChanged) {
+        contentKey.value += 1
+        pendingPayloadUpdate.value = !payloadChanged
+      }
+      else if (pendingPayloadUpdate.value && payloadChanged) {
+        contentKey.value += 1
+        pendingPayloadUpdate.value = false
+      }
+
+      previousActiveTriggerId.value = nextActiveTriggerId
+      previousPayload.value = nextPayload
+    },
+    { flush: 'pre' },
+  )
+
+  return computed(() => `${activeTriggerId.value ?? 'current'}-${contentKey.value}`)
+}

package/src/utils/usePositioner.ts

@@ -0,0 +1,61 @@
+import type { ComputedRef, MaybeRefOrGetter, Ref, StyleValue } from 'vue'
+import type { RenderRef, UseRenderElementComponentProps } from './useRenderElement'
+import type { TransitionStatus } from './useTransitionStatus'
+import { computed, toValue } from 'vue'
+import { mergeProps } from '../merge-props/mergeProps'
+import { getDisabledMountTransitionStyles } from './getDisabledMountTransitionStyles'
+import { popupStateMapping } from './popupStateMapping'
+import { useRenderElement } from './useRenderElement'
+
+interface UsePositionerOptions {
+  styles: MaybeRefOrGetter<StyleValue>
+  transitionStatus: MaybeRefOrGetter<TransitionStatus>
+  props?: MaybeRefOrGetter<Record<string, any> | undefined>
+  refs?: RenderRef | undefined
+  hidden?: MaybeRefOrGetter<boolean | undefined>
+  inert?: MaybeRefOrGetter<boolean | undefined>
+}
+
+/**
+ * Renders the shared outer Positioner element used by popup components.
+ * Applies the common role, hidden state, transition styles, state attributes, and optional inert styling.
+ */
+export function usePositioner<State extends Record<string, any>>(
+  componentProps: UseRenderElementComponentProps<State>,
+  state: ComputedRef<State> | Ref<State>,
+  {
+    styles,
+    transitionStatus,
+    props,
+    refs,
+    hidden,
+    inert = false,
+  }: UsePositionerOptions,
+) {
+  const positionerProps = computed(() => {
+    const isInert = toValue(inert) ?? false
+
+    return mergeProps(
+      {
+        role: 'presentation',
+        hidden: toValue(hidden) ? '' : undefined,
+        inert: isInert ? '' : undefined,
+        style: [
+          toValue(styles),
+          isInert ? { pointerEvents: 'none' } : undefined,
+        ],
+      },
+      getDisabledMountTransitionStyles(toValue(transitionStatus)),
+      toValue(props),
+    )
+  })
+
+  return useRenderElement({
+    componentProps,
+    state,
+    props: positionerProps,
+    stateAttributesMapping: popupStateMapping,
+    defaultTagName: 'div',
+    ref: refs,
+  })
+}