@tale-ui/react 0.0.3

package/utils/useOpenChangeComplete.d.ts

@@ -0,0 +1,27 @@
+import * as React from 'react';
+/**
+ * Calls the provided function when the CSS open/close animation or transition completes.
+ */
+export declare function useOpenChangeComplete(parameters: useOpenChangeComplete.Parameters): void;
+export interface UseOpenChangeCompleteParameters {
+  /**
+   * Whether the hook is enabled.
+   * @default true
+   */
+  enabled?: boolean | undefined;
+  /**
+   * Whether the element is open.
+   */
+  open?: boolean | undefined;
+  /**
+   * Ref to the element being closed.
+   */
+  ref: React.RefObject<HTMLElement | null>;
+  /**
+   * Function to call when the animation completes (or there is no animation).
+   */
+  onComplete: () => void;
+}
+export declare namespace useOpenChangeComplete {
+  type Parameters = UseOpenChangeCompleteParameters;
+}

package/utils/useOpenChangeComplete.js

@@ -0,0 +1,34 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useOpenChangeComplete = useOpenChangeComplete;
+var React = _interopRequireWildcard(require("react"));
+var _useStableCallback = require("@tale-ui/utils/useStableCallback");
+var _useAnimationsFinished = require("./useAnimationsFinished");
+/**
+ * Calls the provided function when the CSS open/close animation or transition completes.
+ */
+function useOpenChangeComplete(parameters) {
+  const {
+    enabled = true,
+    open,
+    ref,
+    onComplete: onCompleteParam
+  } = parameters;
+  const onComplete = (0, _useStableCallback.useStableCallback)(onCompleteParam);
+  const runOnceAnimationsFinish = (0, _useAnimationsFinished.useAnimationsFinished)(ref, open, false);
+  React.useEffect(() => {
+    if (!enabled) {
+      return undefined;
+    }
+    const abortController = new AbortController();
+    runOnceAnimationsFinish(onComplete, abortController.signal);
+    return () => {
+      abortController.abort();
+    };
+  }, [enabled, open, onComplete, runOnceAnimationsFinish]);
+}

package/utils/useOpenInteractionType.d.ts

@@ -0,0 +1,15 @@
+import * as React from 'react';
+import { InteractionType } from '@tale-ui/utils/useEnhancedClickHandler';
+/**
+ * Determines the interaction type (keyboard, mouse, touch, etc.) that opened the component.
+ *
+ * @param open The open state of the component.
+ */
+export declare function useOpenInteractionType(open: boolean): {
+  openMethod: InteractionType | null;
+  reset: () => void;
+  triggerProps: {
+    onClick: (event: React.MouseEvent | React.PointerEvent) => void;
+    onPointerDown: (event: React.PointerEvent) => void;
+  };
+};

package/utils/useOpenInteractionType.js

@@ -0,0 +1,44 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useOpenInteractionType = useOpenInteractionType;
+var React = _interopRequireWildcard(require("react"));
+var _useStableCallback = require("@tale-ui/utils/useStableCallback");
+var _useEnhancedClickHandler = require("@tale-ui/utils/useEnhancedClickHandler");
+var _detectBrowser = require("@tale-ui/utils/detectBrowser");
+/**
+ * Determines the interaction type (keyboard, mouse, touch, etc.) that opened the component.
+ *
+ * @param open The open state of the component.
+ */
+function useOpenInteractionType(open) {
+  const [openMethod, setOpenMethod] = React.useState(null);
+  const handleTriggerClick = (0, _useStableCallback.useStableCallback)((_, interactionType) => {
+    if (!open) {
+      setOpenMethod(interactionType || (
+      // On iOS Safari, the hitslop around touch targets means tapping outside an element's
+      // bounds does not fire `pointerdown` but does fire `mousedown`. The `interactionType`
+      // will be "" in that case.
+      _detectBrowser.isIOS ? 'touch' : ''));
+    }
+  });
+  const reset = React.useCallback(() => {
+    setOpenMethod(null);
+  }, []);
+  const {
+    onClick,
+    onPointerDown
+  } = (0, _useEnhancedClickHandler.useEnhancedClickHandler)(handleTriggerClick);
+  return React.useMemo(() => ({
+    openMethod,
+    reset,
+    triggerProps: {
+      onClick,
+      onPointerDown
+    }
+  }), [openMethod, reset, onClick, onPointerDown]);
+}

package/utils/usePopupAutoResize.d.ts

@@ -0,0 +1,36 @@
+import { Dimensions } from "../floating-ui-react/types.js";
+import { Side } from "./useAnchorPositioning.js";
+/**
+ * Allows the element to automatically resize based on its content while supporting animations.
+ */
+export declare function usePopupAutoResize(parameters: UsePopupAutoResizeParameters): void;
+interface UsePopupAutoResizeParameters {
+  /**
+   * Element to resize.
+   */
+  popupElement: HTMLElement | null;
+  positionerElement: HTMLElement | null;
+  /**
+   * Whether the popup is mounted.
+   */
+  mounted: boolean;
+  content: unknown;
+  /**
+   * Whether the auto-resize is enabled. This function runs in an effect and can safely access refs.
+   */
+  enabled?: (() => boolean) | undefined;
+  /**
+   * Callback fired immediately before measuring the dimensions of the new content.
+   */
+  onMeasureLayout?: (() => void) | undefined;
+  /**
+   * Callback fired after the new dimensions have been measured.
+   *
+   * @param previousDimensions Dimensions before the change, or `null` if this is the first measurement.
+   * @param newDimensions Newly measured dimensions.
+   */
+  onMeasureLayoutComplete?: ((previousDimensions: Dimensions | null, newDimensions: Dimensions) => void) | undefined;
+  side: Side;
+  direction: 'ltr' | 'rtl';
+}
+export {};

package/utils/usePopupAutoResize.js

@@ -0,0 +1,188 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePopupAutoResize = usePopupAutoResize;
+var React = _interopRequireWildcard(require("react"));
+var _useAnimationFrame = require("@tale-ui/utils/useAnimationFrame");
+var _useIsoLayoutEffect = require("@tale-ui/utils/useIsoLayoutEffect");
+var _useStableCallback = require("@tale-ui/utils/useStableCallback");
+var _empty = require("@tale-ui/utils/empty");
+var _useAnimationsFinished = require("./useAnimationsFinished");
+var _getCssDimensions = require("./getCssDimensions");
+var _constants = require("./constants");
+const supportsResizeObserver = typeof ResizeObserver !== 'undefined';
+const DEFAULT_ENABLED = () => true;
+
+/**
+ * Allows the element to automatically resize based on its content while supporting animations.
+ */
+function usePopupAutoResize(parameters) {
+  const {
+    popupElement,
+    positionerElement,
+    content,
+    mounted,
+    enabled = DEFAULT_ENABLED,
+    onMeasureLayout: onMeasureLayoutParam,
+    onMeasureLayoutComplete: onMeasureLayoutCompleteParam,
+    side,
+    direction
+  } = parameters;
+  const runOnceAnimationsFinish = (0, _useAnimationsFinished.useAnimationsFinished)(popupElement, true, false);
+  const animationFrame = (0, _useAnimationFrame.useAnimationFrame)();
+  const committedDimensionsRef = React.useRef(null);
+  const liveDimensionsRef = React.useRef(null);
+  const isInitialRenderRef = React.useRef(true);
+  const restoreAnchoringStylesRef = React.useRef(_empty.NOOP);
+  const onMeasureLayout = (0, _useStableCallback.useStableCallback)(onMeasureLayoutParam);
+  const onMeasureLayoutComplete = (0, _useStableCallback.useStableCallback)(onMeasureLayoutCompleteParam);
+  const anchoringStyles = React.useMemo(() => {
+    // Ensure popup size transitions correctly when anchored to `bottom` (side=top) or `right` (side=left).
+    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';
+    }
+    return isOriginSide ? {
+      position: 'absolute',
+      [side === 'top' ? 'bottom' : 'top']: '0',
+      [isPhysicalLeft ? 'right' : 'left']: '0'
+    } : _constants.EMPTY_OBJECT;
+  }, [side, direction]);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    // Reset the state when the popup is closed.
+    if (!mounted || !enabled() || !supportsResizeObserver) {
+      restoreAnchoringStylesRef.current = _empty.NOOP;
+      isInitialRenderRef.current = true;
+      committedDimensionsRef.current = null;
+      liveDimensionsRef.current = null;
+      return undefined;
+    }
+    if (!popupElement || !positionerElement) {
+      return undefined;
+    }
+    restoreAnchoringStylesRef.current = applyElementStyles(popupElement, anchoringStyles);
+    const observer = new ResizeObserver(entries => {
+      const entry = entries[0];
+      if (entry) {
+        liveDimensionsRef.current = {
+          width: Math.ceil(entry.borderBoxSize[0].inlineSize),
+          height: Math.ceil(entry.borderBoxSize[0].blockSize)
+        };
+      }
+    });
+    observer.observe(popupElement);
+
+    // Measure the rendered size to enable transitions:
+    setPopupCssSize(popupElement, 'auto');
+    const restorePopupPosition = overrideElementStyle(popupElement, 'position', 'static');
+    const restorePopupTransform = overrideElementStyle(popupElement, 'transform', 'none');
+    const restorePopupScale = overrideElementStyle(popupElement, 'scale', '1');
+    const restorePositionerAvailableSize = applyElementStyles(positionerElement, {
+      '--available-width': 'max-content',
+      '--available-height': 'max-content'
+    });
+    function restoreMeasurementOverrides() {
+      restorePopupPosition();
+      restorePopupTransform();
+      restorePositionerAvailableSize();
+    }
+    function restoreMeasurementOverridesIncludingScale() {
+      restoreMeasurementOverrides();
+      restorePopupScale();
+    }
+    onMeasureLayout?.();
+
+    // Initial render (for each time the popup opens).
+    if (isInitialRenderRef.current || committedDimensionsRef.current === null) {
+      setPositionerCssSize(positionerElement, 'max-content');
+      const dimensions = (0, _getCssDimensions.getCssDimensions)(popupElement);
+      committedDimensionsRef.current = dimensions;
+      setPositionerCssSize(positionerElement, dimensions);
+      restoreMeasurementOverridesIncludingScale();
+      onMeasureLayoutComplete?.(null, dimensions);
+      isInitialRenderRef.current = false;
+      return () => {
+        observer.disconnect();
+        restoreAnchoringStylesRef.current();
+        restoreAnchoringStylesRef.current = _empty.NOOP;
+      };
+    }
+
+    // Subsequent renders while open (when `content` changes).
+    setPopupCssSize(popupElement, 'auto');
+    setPositionerCssSize(positionerElement, 'max-content');
+    const previousDimensions = committedDimensionsRef.current ?? liveDimensionsRef.current;
+    const newDimensions = (0, _getCssDimensions.getCssDimensions)(popupElement);
+
+    // Commit immediately so future content changes have a stable previous size, even if
+    // ResizeObserver runs after this point.
+    committedDimensionsRef.current = newDimensions;
+    if (!previousDimensions) {
+      setPositionerCssSize(positionerElement, newDimensions);
+      restoreMeasurementOverridesIncludingScale();
+      onMeasureLayoutComplete?.(null, newDimensions);
+      return () => {
+        observer.disconnect();
+        animationFrame.cancel();
+        restoreAnchoringStylesRef.current();
+        restoreAnchoringStylesRef.current = _empty.NOOP;
+      };
+    }
+    setPopupCssSize(popupElement, previousDimensions);
+    restoreMeasurementOverridesIncludingScale();
+    onMeasureLayoutComplete?.(previousDimensions, newDimensions);
+    setPositionerCssSize(positionerElement, newDimensions);
+    const abortController = new AbortController();
+    animationFrame.request(() => {
+      setPopupCssSize(popupElement, newDimensions);
+      runOnceAnimationsFinish(() => {
+        popupElement.style.setProperty('--popup-width', 'auto');
+        popupElement.style.setProperty('--popup-height', 'auto');
+      }, abortController.signal);
+    });
+    return () => {
+      observer.disconnect();
+      abortController.abort();
+      animationFrame.cancel();
+      restoreAnchoringStylesRef.current();
+      restoreAnchoringStylesRef.current = _empty.NOOP;
+    };
+  }, [content, popupElement, positionerElement, runOnceAnimationsFinish, animationFrame, enabled, mounted, onMeasureLayout, onMeasureLayoutComplete, anchoringStyles]);
+}
+function overrideElementStyle(element, property, value) {
+  const originalValue = element.style.getPropertyValue(property);
+  element.style.setProperty(property, value);
+  return () => {
+    element.style.setProperty(property, originalValue);
+  };
+}
+function applyElementStyles(element, styles) {
+  const restorers = [];
+  for (const [key, value] of Object.entries(styles)) {
+    restorers.push(overrideElementStyle(element, key, value));
+  }
+  return restorers.length ? () => {
+    restorers.forEach(restore => restore());
+  } : _empty.NOOP;
+}
+function setPopupCssSize(popupElement, size) {
+  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, size) {
+  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);
+}

package/utils/usePopupViewport.d.ts

@@ -0,0 +1,58 @@
+import * as React from 'react';
+import type { ReactStore } from '@tale-ui/utils/store';
+import { Side } from "./useAnchorPositioning.js";
+export type 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;
+}
+type PopupViewportStore = Pick<ReactStore<any, any, any>, 'useState' | 'set'>;
+export interface UsePopupViewportParameters {
+  /**
+   * Popup store instance for accessing shared popup state.
+   */
+  store: PopupViewportStore;
+  /**
+   * Side of the positioner relative to the trigger.
+   */
+  side: Side;
+  /**
+   * CSS variable names used for sizing the previous content snapshot.
+   */
+  cssVars: PopupViewportCssVars;
+  /**
+   * Viewport children to render in the current container.
+   */
+  children?: React.ReactNode;
+}
+export interface UsePopupViewportResult {
+  /**
+   * The viewport children wrapped in current/previous containers as needed.
+   */
+  children: React.ReactNode;
+  /**
+   * Viewport state used for data attributes and render prop styling.
+   */
+  state: PopupViewportState;
+}
+/**
+ * Builds morphing viewport containers for popups that animate between trigger-based content.
+ * Handles previous-content snapshots, auto-resize, and state attributes for transitions.
+ */
+export declare function usePopupViewport(parameters: UsePopupViewportParameters): UsePopupViewportResult;
+export {};

package/utils/usePopupViewport.js

@@ -0,0 +1,253 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.usePopupViewport = usePopupViewport;
+var React = _interopRequireWildcard(require("react"));
+var _inertValue = require("@tale-ui/utils/inertValue");
+var _useAnimationFrame = require("@tale-ui/utils/useAnimationFrame");
+var _usePreviousValue = require("@tale-ui/utils/usePreviousValue");
+var _useIsoLayoutEffect = require("@tale-ui/utils/useIsoLayoutEffect");
+var _useStableCallback = require("@tale-ui/utils/useStableCallback");
+var _useAnimationsFinished = require("./useAnimationsFinished");
+var _usePopupAutoResize = require("./usePopupAutoResize");
+var _directionProvider = require("../direction-provider");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * Builds morphing viewport containers for popups that animate between trigger-based content.
+ * Handles previous-content snapshots, auto-resize, and state attributes for transitions.
+ */
+function usePopupViewport(parameters) {
+  const {
+    store,
+    side,
+    cssVars,
+    children
+  } = parameters;
+  const direction = (0, _directionProvider.useDirection)();
+  const activeTrigger = store.useState('activeTriggerElement');
+  const activeTriggerId = store.useState('activeTriggerId');
+  const open = store.useState('open');
+  const payload = store.useState('payload');
+  const mounted = store.useState('mounted');
+  const popupElement = store.useState('popupElement');
+  const positionerElement = store.useState('positionerElement');
+  const previousActiveTrigger = (0, _usePreviousValue.usePreviousValue)(open ? activeTrigger : null);
+  // Remount current content on trigger changes (and once more when payload lags) to avoid DOM reuse flashes.
+  // The key bumps immediately on trigger switches, then again if the payload arrives on a later render.
+  const currentContentKey = usePopupContentKey(activeTriggerId, payload);
+  const capturedNodeRef = React.useRef(null);
+  const [previousContentNode, setPreviousContentNode] = React.useState(null);
+  const [newTriggerOffset, setNewTriggerOffset] = React.useState(null);
+  const currentContainerRef = React.useRef(null);
+  const previousContainerRef = React.useRef(null);
+  const onAnimationsFinished = (0, _useAnimationsFinished.useAnimationsFinished)(currentContainerRef, true, false);
+  const cleanupFrame = (0, _useAnimationFrame.useAnimationFrame)();
+  const [previousContentDimensions, setPreviousContentDimensions] = React.useState(null);
+  const [showStartingStyleAttribute, setShowStartingStyleAttribute] = React.useState(false);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    store.set('hasViewport', true);
+    return () => {
+      store.set('hasViewport', false);
+    };
+  }, [store]);
+  const handleMeasureLayout = (0, _useStableCallback.useStableCallback)(() => {
+    currentContainerRef.current?.style.setProperty('animation', 'none');
+    currentContainerRef.current?.style.setProperty('transition', 'none');
+    previousContainerRef.current?.style.setProperty('display', 'none');
+  });
+  const handleMeasureLayoutComplete = (0, _useStableCallback.useStableCallback)(previousDimensions => {
+    currentContainerRef.current?.style.removeProperty('animation');
+    currentContainerRef.current?.style.removeProperty('transition');
+    previousContainerRef.current?.style.removeProperty('display');
+    if (previousDimensions) {
+      setPreviousContentDimensions(previousDimensions);
+    }
+  });
+  const lastHandledTriggerRef = React.useRef(null);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    // When a trigger changes, set the captured children HTML to state,
+    // so we can render both new and old content.
+    if (activeTrigger && previousActiveTrigger && activeTrigger !== previousActiveTrigger && lastHandledTriggerRef.current !== activeTrigger && capturedNodeRef.current) {
+      setPreviousContentNode(capturedNodeRef.current);
+      setShowStartingStyleAttribute(true);
+
+      // Calculate the relative position between the previous and new trigger,
+      // so we can pass it to the style hook for animation purposes.
+      const offset = calculateRelativePosition(previousActiveTrigger, activeTrigger);
+      setNewTriggerOffset(offset);
+      cleanupFrame.request(() => {
+        cleanupFrame.request(() => {
+          setShowStartingStyleAttribute(false);
+          onAnimationsFinished(() => {
+            setPreviousContentNode(null);
+            setPreviousContentDimensions(null);
+            capturedNodeRef.current = null;
+          });
+        });
+      });
+      lastHandledTriggerRef.current = activeTrigger;
+    }
+  }, [activeTrigger, previousActiveTrigger, previousContentNode, onAnimationsFinished, cleanupFrame]);
+
+  // Capture a clone of the current content DOM subtree when not transitioning.
+  // We can't store previous React nodes as they may be stateful; instead we capture DOM clones for visual continuity.
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    // When a transition is in progress, we store the next content in capturedNodeRef.
+    // This handles the case where the trigger changes multiple times before the transition finishes.
+    // We want to always capture the latest content for the previous snapshot.
+    // So clicking quickly on T1, T2, T3 will result in the following sequence:
+    // 1. T1 -> T2: previousContent = T1, currentContent = T2
+    // 2. T2 -> T3: previousContent = T2, currentContent = T3
+    const source = currentContainerRef.current;
+    if (!source) {
+      return;
+    }
+    const wrapper = document.createElement('div');
+    for (const child of Array.from(source.childNodes)) {
+      wrapper.appendChild(child.cloneNode(true));
+    }
+    capturedNodeRef.current = wrapper;
+  });
+  const isTransitioning = previousContentNode != null;
+  let childrenToRender;
+  if (!isTransitioning) {
+    childrenToRender = /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+      "data-current": true,
+      ref: currentContainerRef,
+      children: children
+    }, currentContentKey);
+  } else {
+    childrenToRender = /*#__PURE__*/(0, _jsxRuntime.jsxs)(React.Fragment, {
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        "data-previous": true,
+        inert: (0, _inertValue.inertValue)(true),
+        ref: previousContainerRef,
+        style: {
+          [cssVars.popupWidth]: `${previousContentDimensions?.width}px`,
+          [cssVars.popupHeight]: `${previousContentDimensions?.height}px`,
+          position: 'absolute'
+        },
+        "data-ending-style": showStartingStyleAttribute ? undefined : ''
+      }, "previous"), /*#__PURE__*/(0, _jsxRuntime.jsx)("div", {
+        "data-current": true,
+        ref: currentContainerRef,
+        "data-starting-style": showStartingStyleAttribute ? '' : undefined,
+        children: children
+      }, currentContentKey)]
+    });
+  }
+
+  // When previousContentNode is present, imperatively populate the previous container with the cloned children.
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    const container = previousContainerRef.current;
+    if (!container || !previousContentNode) {
+      return;
+    }
+    container.replaceChildren(...Array.from(previousContentNode.childNodes));
+  }, [previousContentNode]);
+  (0, _usePopupAutoResize.usePopupAutoResize)({
+    popupElement,
+    positionerElement,
+    mounted,
+    content: payload,
+    onMeasureLayout: handleMeasureLayout,
+    onMeasureLayoutComplete: handleMeasureLayoutComplete,
+    side,
+    direction
+  });
+  const state = {
+    activationDirection: getActivationDirection(newTriggerOffset),
+    transitioning: isTransitioning
+  };
+  return {
+    children: childrenToRender,
+    state
+  };
+}
+/**
+ * Returns a string describing the provided offset.
+ * It describes both the horizontal and vertical offset, separated by a space.
+ *
+ * @param offset
+ */
+function getActivationDirection(offset) {
+  if (!offset) {
+    return undefined;
+  }
+  return `${getValueWithTolerance(offset.horizontal, 5, 'right', 'left')} ${getValueWithTolerance(offset.vertical, 5, 'down', 'up')}`;
+}
+
+/**
+ * Returns a label describing the value (positive/negative) treating values
+ * within tolerance as zero.
+ *
+ * @param value Value to check
+ * @param tolerance Tolerance to treat the value as zero.
+ * @param positiveLabel
+ * @param negativeLabel
+ * @returns If 0 < abs(value) < tolerance, returns an empty string. Otherwise returns positiveLabel or negativeLabel.
+ */
+function getValueWithTolerance(value, tolerance, positiveLabel, negativeLabel) {
+  if (value > tolerance) {
+    return positiveLabel;
+  }
+  if (value < -tolerance) {
+    return negativeLabel;
+  }
+  return '';
+}
+
+/**
+ * Calculates the relative position between centers of two elements.
+ */
+function calculateRelativePosition(from, to) {
+  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, payload) {
+  const [contentKey, setContentKey] = React.useState(0);
+  const previousActiveTriggerIdRef = React.useRef(activeTriggerId);
+  const previousPayloadRef = React.useRef(payload);
+  const pendingPayloadUpdateRef = React.useRef(false);
+  (0, _useIsoLayoutEffect.useIsoLayoutEffect)(() => {
+    // Compare against the last committed values to decide whether we need a new DOM subtree.
+    const previousActiveTriggerId = previousActiveTriggerIdRef.current;
+    const previousPayload = previousPayloadRef.current;
+    const triggerIdChanged = activeTriggerId !== previousActiveTriggerId;
+    const payloadChanged = payload !== previousPayload;
+    if (triggerIdChanged) {
+      // Remount immediately on trigger change; remember if payload hasn't caught up yet.
+      setContentKey(value => value + 1);
+      pendingPayloadUpdateRef.current = !payloadChanged;
+    } else if (pendingPayloadUpdateRef.current && payloadChanged) {
+      // Payload arrived a render later, so remount once more to avoid reusing the old <img>.
+      setContentKey(value => value + 1);
+      pendingPayloadUpdateRef.current = false;
+    }
+
+    // Persist current values for the next render's comparison.
+    previousActiveTriggerIdRef.current = activeTriggerId;
+    previousPayloadRef.current = payload;
+  }, [activeTriggerId, payload]);
+  return `${activeTriggerId ?? 'current'}-${contentKey}`;
+}