@atlaskit/top-layer 0.4.0 → 0.5.1

package/CHANGELOG.md

@@ -1,5 +1,24 @@
 # @atlaskit/top-layer
 
+## 0.5.1
+
+### Patch Changes
+
+- [`693551fc3e8c4`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/693551fc3e8c4) -
+  useAnchorPosition no longer re-runs its positioning effect when a fresh placement object reference
+  with the same resolved shape is passed (eg an inline literal on every render). The hook
+  structurally compares the resolved placement and reuses the previous reference when the shape is
+  unchanged.
+
+## 0.5.0
+
+### Minor Changes
+
+- [`6e656fce5ceee`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/6e656fce5ceee) -
+  Fix anchor positioning so multiple popovers can share the same trigger element. Previously the
+  second `useAnchorPosition` call on the same trigger would overwrite the first call's `anchor-name`
+  style, leaving the first popover unpositioned.
+
 ## 0.4.0
 
 ### Minor Changes

package/dist/cjs/animations/presets.js

@@ -8,7 +8,7 @@ exports.dialogSlideUpAndFade = dialogSlideUpAndFade;
 exports.fade = fade;
 exports.scaleAndFade = scaleAndFade;
 exports.slideAndFade = slideAndFade;
-var _useAnchorPositioning = require("../internal/use-anchor-positioning");
+var _useAnchorPosition = require("../internal/use-anchor-position");
 // ── slideAndFade ──
 
 function getSlideAndFadeProperties(_ref) {
@@ -16,7 +16,7 @@ function getSlideAndFadeProperties(_ref) {
     distance = _ref.distance;
   var pos = "".concat(distance, "px");
   var neg = "-".concat(distance, "px");
-  var _getPlacement = (0, _useAnchorPositioning.getPlacement)({
+  var _getPlacement = (0, _useAnchorPosition.getPlacement)({
       placement: placement
     }),
     axis = _getPlacement.axis,

package/dist/cjs/arrow/index.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 });
 exports.arrow = void 0;
 var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
-var _useAnchorPositioning = require("../internal/use-anchor-positioning");
+var _useAnchorPosition = require("../internal/use-anchor-position");
 /**
  * CSS for popover arrows using the `clip-path: inset() margin-box` technique.
  *
@@ -51,7 +51,7 @@ function positionAreaToRuleName(_ref) {
  */
 function getTryFallbacks(_ref2) {
   var placement = _ref2.placement;
-  var _getPlacement = (0, _useAnchorPositioning.getPlacement)({
+  var _getPlacement = (0, _useAnchorPosition.getPlacement)({
       placement: placement
     }),
     axis = _getPlacement.axis,
@@ -61,7 +61,7 @@ function getTryFallbacks(_ref2) {
     // Single-axis: only flip the edge
     var _flippedEdge = edge === 'start' ? 'end' : 'start';
     return positionAreaToRuleName({
-      positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+      positionArea: (0, _useAnchorPosition.placementToPositionArea)({
         placement: {
           axis: axis,
           edge: _flippedEdge
@@ -74,7 +74,7 @@ function getTryFallbacks(_ref2) {
   var flippedEdge = edge === 'start' ? 'end' : 'start';
   var flippedAlign = align === 'start' ? 'end' : 'start';
   return [positionAreaToRuleName({
-    positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+    positionArea: (0, _useAnchorPosition.placementToPositionArea)({
       placement: {
         axis: axis,
         edge: flippedEdge,
@@ -82,7 +82,7 @@ function getTryFallbacks(_ref2) {
       }
     })
   }), positionAreaToRuleName({
-    positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+    positionArea: (0, _useAnchorPosition.placementToPositionArea)({
       placement: {
         axis: axis,
         edge: edge,
@@ -90,7 +90,7 @@ function getTryFallbacks(_ref2) {
       }
     })
   }), positionAreaToRuleName({
-    positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+    positionArea: (0, _useAnchorPosition.placementToPositionArea)({
       placement: {
         axis: axis,
         edge: flippedEdge,

package/dist/cjs/entry-points/use-anchor-position.js

@@ -6,7 +6,7 @@ Object.defineProperty(exports, "__esModule", {
 Object.defineProperty(exports, "useAnchorPosition", {
   enumerable: true,
   get: function get() {
-    return _useAnchorPositioning.useAnchorPosition;
+    return _useAnchorPosition.useAnchorPosition;
   }
 });
-var _useAnchorPositioning = require("../internal/use-anchor-positioning");
+var _useAnchorPosition = require("../internal/use-anchor-position");

package/dist/cjs/internal/anchor-positioning-fallback.js

@@ -131,7 +131,7 @@ function applyAlignment(_ref2) {
  * Applies the cross-axis shift offset.
  *
  * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `use-anchor-positioning.tsx`):
+ * `use-anchor-position.tsx`):
  *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
  *   - `align: 'end'`              + `forwards`  → push toward start (negative)
  *   - `backwards` flips the sign in both cases.

package/dist/cjs/internal/{use-anchor-positioning.js → use-anchor-position.js}

@@ -210,6 +210,30 @@ function crossAxisShiftMargin(_ref4) {
   };
 }
 
+/**
+ * Returns a referentially-stable, fully-resolved `TPlacement`: the same
+ * reference is preserved across renders as long as the resolved shape
+ * does not change.
+ */
+function useStablePlacement(placement) {
+  var resolved = (0, _resolvePlacement.getPlacement)({
+    placement: placement
+  });
+  var stableRef = (0, _react.useRef)(resolved);
+  if (!isResolvedPlacementEqual(stableRef.current, resolved)) {
+    stableRef.current = resolved;
+  }
+  return stableRef.current;
+}
+
+/**
+ * Shallow-equals two fully-resolved placements. Avoids `JSON.stringify` so
+ * the comparison cost stays proportional to the number of fields.
+ */
+function isResolvedPlacementEqual(a, b) {
+  return a.axis === b.axis && a.edge === b.edge && a.align === b.align && a.offset.gap === b.offset.gap && a.offset.crossAxisShift.value === b.offset.crossAxisShift.value && a.offset.crossAxisShift.direction === b.offset.crossAxisShift.direction;
+}
+
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).
@@ -225,37 +249,44 @@ function crossAxisShiftMargin(_ref4) {
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
+ *
+ * `placement` may be a fresh inline object on every render: a structural
+ * comparison is used internally so re-runs are skipped when the resolved
+ * placement shape is unchanged.
  */
 function useAnchorPosition(_ref5) {
   var anchorRef = _ref5.anchorRef,
     popoverRef = _ref5.popoverRef,
-    placement = _ref5.placement,
+    _ref5$placement = _ref5.placement,
+    placement = _ref5$placement === void 0 ? {} : _ref5$placement,
     _ref5$forceFallbackPo = _ref5.forceFallbackPositioning,
     forceFallbackPositioning = _ref5$forceFallbackPo === void 0 ? false : _ref5$forceFallbackPo,
     arrow = _ref5.arrow;
   var id = (0, _react.useId)();
-  var anchorName = "--anchor-".concat(id.replace(/:/g, ''));
+  // Stabilize `placement` object so the same object literal
+  // value returns an object with the same reference
+  var stablePlacement = useStablePlacement(placement);
   (0, _react.useLayoutEffect)(function () {
     var trigger = anchorRef.current;
     var popover = popoverRef.current;
     if (!trigger || !popover) {
       return;
     }
-    var resolvedPlacement = (0, _resolvePlacement.getPlacement)({
-      placement: placement
-    });
-    var gapCssValue = resolvedPlacement.offset.gap;
-    var crossAxisShiftCssValue = resolvedPlacement.offset.crossAxisShift.value;
+    var gapCssValue = stablePlacement.offset.gap;
+    var crossAxisShiftCssValue = stablePlacement.offset.crossAxisShift.value;
     var shouldForceFallback = Boolean(forceFallbackPositioning);
     if (supportsAnchorPositioning() && !shouldForceFallback) {
+      // Reuse an existing `anchor-name` if the element already has one.
+      // Another popover might already be anchored to the old name.
+      var anchorName = trigger.style.getPropertyValue('anchor-name') || "--anchor-".concat(id.replace(/:/g, ''));
       var gap = edgeMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         offset: gapCssValue
       });
       var crossAxisShift = crossAxisShiftMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
-        direction: resolvedPlacement.offset.crossAxisShift.direction
+        direction: stablePlacement.offset.crossAxisShift.direction
       });
       var popoverStyles = [{
         property: 'position-anchor',
@@ -263,14 +294,14 @@ function useAnchorPosition(_ref5) {
       }, {
         property: 'position-area',
         value: placementToPositionArea({
-          placement: resolvedPlacement
+          placement: stablePlacement
         })
       }, {
         property: 'position-try-fallbacks',
         value: arrow ? arrow.getTryFallbacks({
-          placement: resolvedPlacement
+          placement: stablePlacement
         }) : placementToTryFallbacks({
-          placement: resolvedPlacement
+          placement: stablePlacement
         })
       },
       // Reset browser default popover positioning that conflicts
@@ -314,9 +345,9 @@ function useAnchorPosition(_ref5) {
         value: '0px'
       });
       var crossAxisShiftActive = crossAxisShiftMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
-        direction: resolvedPlacement.offset.crossAxisShift.direction
+        direction: stablePlacement.offset.crossAxisShift.direction
       });
       // Map margin property to its corresponding custom property name.
       var customPropertyByMarginProperty = {
@@ -345,13 +376,26 @@ function useAnchorPosition(_ref5) {
         // because that's where useAnchorPosition sets the margin gap.
         popover.setAttribute('data-ds-popover-arrow', '');
       }
+
+      /**
+       * **We are never cleaning up anchor names**
+       *
+       * _Rationale_
+       *
+       * - Multiple popovers can share the same anchor element.
+       * - Sometimes the `useAnchorPosition` hook and `Popover`
+       *   are not in the same component.
+       * - There can be times when, even with reference counting, we
+       *   could remove the anchor-name while it's still being used
+       *   by something else - especially with async react updates
+       *   which can cause tearing
+       *
+       * _More_
+       *
+       * See `notes/decisions/anchor-name-lifetime.md`
+       */
+      trigger.style.setProperty('anchor-name', anchorName);
       var _undoPositioning = (0, _combine.combine)((0, _setStyle.setStyle)({
-        el: trigger,
-        styles: [{
-          property: 'anchor-name',
-          value: anchorName
-        }]
-      }), (0, _setStyle.setStyle)({
         el: popover,
         styles: popoverStyles
       }), arrow ? function () {
@@ -403,12 +447,12 @@ function useAnchorPosition(_ref5) {
       var _computeFallbackPosit = (0, _anchorPositioningFallback.computeFallbackPosition)({
           triggerRect: triggerRect,
           popoverEl: popover,
-          placement: resolvedPlacement,
+          placement: stablePlacement,
           viewport: viewport,
           gap: gapPx,
           crossAxisShift: {
             value: crossAxisShiftPx,
-            direction: resolvedPlacement.offset.crossAxisShift.direction
+            direction: stablePlacement.offset.crossAxisShift.direction
           }
         }),
         top = _computeFallbackPosit.top,
@@ -483,5 +527,5 @@ function useAnchorPosition(_ref5) {
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, placement, anchorName, forceFallbackPositioning, arrow]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, arrow, id]);
 }

package/dist/cjs/popup/popup-content.js

@@ -12,7 +12,7 @@ var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends")
 var _react = _interopRequireWildcard(require("react"));
 var _mergeRefs = _interopRequireDefault(require("@atlaskit/ds-lib/merge-refs"));
 var _roleTypes = require("../internal/role-types");
-var _useAnchorPositioning = require("../internal/use-anchor-positioning");
+var _useAnchorPosition = require("../internal/use-anchor-position");
 var _usePresetStyles = require("../internal/use-preset-styles");
 var _popover = require("../popover/popover");
 var _popupContext = require("./popup-context");
@@ -131,7 +131,7 @@ var PopupContent = exports.PopupContent = /*#__PURE__*/(0, _react.forwardRef)(fu
   var arrowPreset = (0, _usePresetStyles.usePresetStyles)({
     preset: arrow
   });
-  (0, _useAnchorPositioning.useAnchorPosition)({
+  (0, _useAnchorPosition.useAnchorPosition)({
     anchorRef: triggerRef !== null && triggerRef !== void 0 ? triggerRef : {
       current: null
     },

package/dist/cjs/testing/polyfill.js

@@ -17,7 +17,7 @@ var _bindEventListener = require("bind-event-listener");
  *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
  *    outside the open chain, and dismiss the topmost on Escape.
  *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
  *    visible in jsdom, where layout-driven RO callbacks never fire.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.
@@ -251,7 +251,7 @@ function stackForMode(_ref9) {
 
 // Polyfill-only. Real browsers reveal the popover once `ResizeObserver`
 // callbacks fire after the first layout pass. jsdom has no layout, so we clear
-// any inline `opacity: 0` (set by callers like `use-anchor-positioning`) once
+// any inline `opacity: 0` (set by callers like `use-anchor-position`) once
 // the open toggle has fired.
 function clearOpacityOnOpenToggle(_ref0) {
   var element = _ref0.element;

package/dist/es2019/animations/presets.js

@@ -1,4 +1,4 @@
-import { getPlacement } from '../internal/use-anchor-positioning';
+import { getPlacement } from '../internal/use-anchor-position';
 
 // ── slideAndFade ──
 

package/dist/es2019/arrow/index.js

@@ -1,5 +1,5 @@
 import once from '@atlaskit/ds-lib/once';
-import { getPlacement, placementToPositionArea } from '../internal/use-anchor-positioning';
+import { getPlacement, placementToPositionArea } from '../internal/use-anchor-position';
 /**
  * CSS for popover arrows using the `clip-path: inset() margin-box` technique.
  *

package/dist/es2019/entry-points/use-anchor-position.js

@@ -1 +1 @@
-export { useAnchorPosition } from '../internal/use-anchor-positioning';
+export { useAnchorPosition } from '../internal/use-anchor-position';

package/dist/es2019/internal/anchor-positioning-fallback.js

@@ -127,7 +127,7 @@ function applyAlignment({
  * Applies the cross-axis shift offset.
  *
  * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `use-anchor-positioning.tsx`):
+ * `use-anchor-position.tsx`):
  *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
  *   - `align: 'end'`              + `forwards`  → push toward start (negative)
  *   - `backwards` flips the sign in both cases.

package/dist/es2019/internal/{use-anchor-positioning.js → use-anchor-position.js}

@@ -12,7 +12,7 @@
  * popover with `opacity: 0` until the first measurement completes, so it
  * is never painted at the wrong location.
  */
-import { useId, useLayoutEffect } from 'react';
+import { useId, useLayoutEffect, useRef } from 'react';
 import { bind } from 'bind-event-listener';
 import rafSchedule from 'raf-schd';
 import once from '@atlaskit/ds-lib/once';
@@ -206,6 +206,30 @@ function crossAxisShiftMargin({
   };
 }
 
+/**
+ * Returns a referentially-stable, fully-resolved `TPlacement`: the same
+ * reference is preserved across renders as long as the resolved shape
+ * does not change.
+ */
+function useStablePlacement(placement) {
+  const resolved = getPlacement({
+    placement
+  });
+  const stableRef = useRef(resolved);
+  if (!isResolvedPlacementEqual(stableRef.current, resolved)) {
+    stableRef.current = resolved;
+  }
+  return stableRef.current;
+}
+
+/**
+ * Shallow-equals two fully-resolved placements. Avoids `JSON.stringify` so
+ * the comparison cost stays proportional to the number of fields.
+ */
+function isResolvedPlacementEqual(a, b) {
+  return a.axis === b.axis && a.edge === b.edge && a.align === b.align && a.offset.gap === b.offset.gap && a.offset.crossAxisShift.value === b.offset.crossAxisShift.value && a.offset.crossAxisShift.direction === b.offset.crossAxisShift.direction;
+}
+
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).
@@ -221,37 +245,43 @@ function crossAxisShiftMargin({
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
+ *
+ * `placement` may be a fresh inline object on every render: a structural
+ * comparison is used internally so re-runs are skipped when the resolved
+ * placement shape is unchanged.
  */
 export function useAnchorPosition({
   anchorRef,
   popoverRef,
-  placement,
+  placement = {},
   forceFallbackPositioning = false,
   arrow
 }) {
   const id = useId();
-  const anchorName = `--anchor-${id.replace(/:/g, '')}`;
+  // Stabilize `placement` object so the same object literal
+  // value returns an object with the same reference
+  const stablePlacement = useStablePlacement(placement);
   useLayoutEffect(() => {
     const trigger = anchorRef.current;
     const popover = popoverRef.current;
     if (!trigger || !popover) {
       return;
     }
-    const resolvedPlacement = getPlacement({
-      placement
-    });
-    const gapCssValue = resolvedPlacement.offset.gap;
-    const crossAxisShiftCssValue = resolvedPlacement.offset.crossAxisShift.value;
+    const gapCssValue = stablePlacement.offset.gap;
+    const crossAxisShiftCssValue = stablePlacement.offset.crossAxisShift.value;
     const shouldForceFallback = Boolean(forceFallbackPositioning);
     if (supportsAnchorPositioning() && !shouldForceFallback) {
+      // Reuse an existing `anchor-name` if the element already has one.
+      // Another popover might already be anchored to the old name.
+      const anchorName = trigger.style.getPropertyValue('anchor-name') || `--anchor-${id.replace(/:/g, '')}`;
       const gap = edgeMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         offset: gapCssValue
       });
       const crossAxisShift = crossAxisShiftMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         crossAxisShiftCssValue,
-        direction: resolvedPlacement.offset.crossAxisShift.direction
+        direction: stablePlacement.offset.crossAxisShift.direction
       });
       const popoverStyles = [{
         property: 'position-anchor',
@@ -259,14 +289,14 @@ export function useAnchorPosition({
       }, {
         property: 'position-area',
         value: placementToPositionArea({
-          placement: resolvedPlacement
+          placement: stablePlacement
         })
       }, {
         property: 'position-try-fallbacks',
         value: arrow ? arrow.getTryFallbacks({
-          placement: resolvedPlacement
+          placement: stablePlacement
         }) : placementToTryFallbacks({
-          placement: resolvedPlacement
+          placement: stablePlacement
         })
       },
       // Reset browser default popover positioning that conflicts
@@ -310,9 +340,9 @@ export function useAnchorPosition({
         value: '0px'
       });
       const crossAxisShiftActive = crossAxisShiftMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         crossAxisShiftCssValue,
-        direction: resolvedPlacement.offset.crossAxisShift.direction
+        direction: stablePlacement.offset.crossAxisShift.direction
       });
       // Map margin property to its corresponding custom property name.
       const customPropertyByMarginProperty = {
@@ -341,13 +371,26 @@ export function useAnchorPosition({
         // because that's where useAnchorPosition sets the margin gap.
         popover.setAttribute('data-ds-popover-arrow', '');
       }
+
+      /**
+       * **We are never cleaning up anchor names**
+       *
+       * _Rationale_
+       *
+       * - Multiple popovers can share the same anchor element.
+       * - Sometimes the `useAnchorPosition` hook and `Popover`
+       *   are not in the same component.
+       * - There can be times when, even with reference counting, we
+       *   could remove the anchor-name while it's still being used
+       *   by something else - especially with async react updates
+       *   which can cause tearing
+       *
+       * _More_
+       *
+       * See `notes/decisions/anchor-name-lifetime.md`
+       */
+      trigger.style.setProperty('anchor-name', anchorName);
       const undoPositioning = combine(setStyle({
-        el: trigger,
-        styles: [{
-          property: 'anchor-name',
-          value: anchorName
-        }]
-      }), setStyle({
         el: popover,
         styles: popoverStyles
       }), arrow ? () => popover.removeAttribute('data-ds-popover-arrow') : () => {});
@@ -400,12 +443,12 @@ export function useAnchorPosition({
       } = computeFallbackPosition({
         triggerRect,
         popoverEl: popover,
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         viewport,
         gap: gapPx,
         crossAxisShift: {
           value: crossAxisShiftPx,
-          direction: resolvedPlacement.offset.crossAxisShift.direction
+          direction: stablePlacement.offset.crossAxisShift.direction
         }
       });
       popover.style.setProperty('top', `${top}px`);
@@ -476,5 +519,5 @@ export function useAnchorPosition({
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, placement, anchorName, forceFallbackPositioning, arrow]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, arrow, id]);
 }

package/dist/es2019/popup/popup-content.js

@@ -4,7 +4,7 @@ import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useLayoutEffect, useRef } from 'react';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import { roleToAriaHasPopup } from '../internal/role-types';
-import { useAnchorPosition } from '../internal/use-anchor-positioning';
+import { useAnchorPosition } from '../internal/use-anchor-position';
 import { usePresetStyles } from '../internal/use-preset-styles';
 import { Popover } from '../popover/popover';
 import { useMaybePopupContext } from './popup-context';

package/dist/es2019/testing/polyfill.js

@@ -14,7 +14,7 @@
  *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
  *    outside the open chain, and dismiss the topmost on Escape.
  *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
  *    visible in jsdom, where layout-driven RO callbacks never fire.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.
@@ -258,7 +258,7 @@ function stackForMode({
 
 // Polyfill-only. Real browsers reveal the popover once `ResizeObserver`
 // callbacks fire after the first layout pass. jsdom has no layout, so we clear
-// any inline `opacity: 0` (set by callers like `use-anchor-positioning`) once
+// any inline `opacity: 0` (set by callers like `use-anchor-position`) once
 // the open toggle has fired.
 function clearOpacityOnOpenToggle({
   element

package/dist/esm/animations/presets.js

@@ -1,4 +1,4 @@
-import { getPlacement } from '../internal/use-anchor-positioning';
+import { getPlacement } from '../internal/use-anchor-position';
 
 // ── slideAndFade ──
 

package/dist/esm/arrow/index.js

@@ -1,5 +1,5 @@
 import once from '@atlaskit/ds-lib/once';
-import { getPlacement, placementToPositionArea } from '../internal/use-anchor-positioning';
+import { getPlacement, placementToPositionArea } from '../internal/use-anchor-position';
 /**
  * CSS for popover arrows using the `clip-path: inset() margin-box` technique.
  *

package/dist/esm/entry-points/use-anchor-position.js

@@ -1 +1 @@
-export { useAnchorPosition } from '../internal/use-anchor-positioning';
+export { useAnchorPosition } from '../internal/use-anchor-position';

package/dist/esm/internal/anchor-positioning-fallback.js

@@ -124,7 +124,7 @@ function applyAlignment(_ref2) {
  * Applies the cross-axis shift offset.
  *
  * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `use-anchor-positioning.tsx`):
+ * `use-anchor-position.tsx`):
  *   - `align: 'start' | 'center'` + `forwards`  → push toward end (positive)
  *   - `align: 'end'`              + `forwards`  → push toward start (negative)
  *   - `backwards` flips the sign in both cases.

package/dist/esm/internal/{use-anchor-positioning.js → use-anchor-position.js}

@@ -12,7 +12,7 @@
  * popover with `opacity: 0` until the first measurement completes, so it
  * is never painted at the wrong location.
  */
-import { useId, useLayoutEffect } from 'react';
+import { useId, useLayoutEffect, useRef } from 'react';
 import { bind } from 'bind-event-listener';
 import rafSchedule from 'raf-schd';
 import once from '@atlaskit/ds-lib/once';
@@ -196,6 +196,30 @@ function crossAxisShiftMargin(_ref4) {
   };
 }
 
+/**
+ * Returns a referentially-stable, fully-resolved `TPlacement`: the same
+ * reference is preserved across renders as long as the resolved shape
+ * does not change.
+ */
+function useStablePlacement(placement) {
+  var resolved = getPlacement({
+    placement: placement
+  });
+  var stableRef = useRef(resolved);
+  if (!isResolvedPlacementEqual(stableRef.current, resolved)) {
+    stableRef.current = resolved;
+  }
+  return stableRef.current;
+}
+
+/**
+ * Shallow-equals two fully-resolved placements. Avoids `JSON.stringify` so
+ * the comparison cost stays proportional to the number of fields.
+ */
+function isResolvedPlacementEqual(a, b) {
+  return a.axis === b.axis && a.edge === b.edge && a.align === b.align && a.offset.gap === b.offset.gap && a.offset.crossAxisShift.value === b.offset.crossAxisShift.value && a.offset.crossAxisShift.direction === b.offset.crossAxisShift.direction;
+}
+
 /**
  * Hook that positions an element relative to an anchor element using
  * CSS Anchor Positioning (with a JS fallback for older browsers).
@@ -211,37 +235,44 @@ function crossAxisShiftMargin(_ref4) {
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
+ *
+ * `placement` may be a fresh inline object on every render: a structural
+ * comparison is used internally so re-runs are skipped when the resolved
+ * placement shape is unchanged.
  */
 export function useAnchorPosition(_ref5) {
   var anchorRef = _ref5.anchorRef,
     popoverRef = _ref5.popoverRef,
-    placement = _ref5.placement,
+    _ref5$placement = _ref5.placement,
+    placement = _ref5$placement === void 0 ? {} : _ref5$placement,
     _ref5$forceFallbackPo = _ref5.forceFallbackPositioning,
     forceFallbackPositioning = _ref5$forceFallbackPo === void 0 ? false : _ref5$forceFallbackPo,
     arrow = _ref5.arrow;
   var id = useId();
-  var anchorName = "--anchor-".concat(id.replace(/:/g, ''));
+  // Stabilize `placement` object so the same object literal
+  // value returns an object with the same reference
+  var stablePlacement = useStablePlacement(placement);
   useLayoutEffect(function () {
     var trigger = anchorRef.current;
     var popover = popoverRef.current;
     if (!trigger || !popover) {
       return;
     }
-    var resolvedPlacement = getPlacement({
-      placement: placement
-    });
-    var gapCssValue = resolvedPlacement.offset.gap;
-    var crossAxisShiftCssValue = resolvedPlacement.offset.crossAxisShift.value;
+    var gapCssValue = stablePlacement.offset.gap;
+    var crossAxisShiftCssValue = stablePlacement.offset.crossAxisShift.value;
     var shouldForceFallback = Boolean(forceFallbackPositioning);
     if (supportsAnchorPositioning() && !shouldForceFallback) {
+      // Reuse an existing `anchor-name` if the element already has one.
+      // Another popover might already be anchored to the old name.
+      var anchorName = trigger.style.getPropertyValue('anchor-name') || "--anchor-".concat(id.replace(/:/g, ''));
       var gap = edgeMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         offset: gapCssValue
       });
       var crossAxisShift = crossAxisShiftMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
-        direction: resolvedPlacement.offset.crossAxisShift.direction
+        direction: stablePlacement.offset.crossAxisShift.direction
       });
       var popoverStyles = [{
         property: 'position-anchor',
@@ -249,14 +280,14 @@ export function useAnchorPosition(_ref5) {
       }, {
         property: 'position-area',
         value: placementToPositionArea({
-          placement: resolvedPlacement
+          placement: stablePlacement
         })
       }, {
         property: 'position-try-fallbacks',
         value: arrow ? arrow.getTryFallbacks({
-          placement: resolvedPlacement
+          placement: stablePlacement
         }) : placementToTryFallbacks({
-          placement: resolvedPlacement
+          placement: stablePlacement
         })
       },
       // Reset browser default popover positioning that conflicts
@@ -300,9 +331,9 @@ export function useAnchorPosition(_ref5) {
         value: '0px'
       });
       var crossAxisShiftActive = crossAxisShiftMargin({
-        placement: resolvedPlacement,
+        placement: stablePlacement,
         crossAxisShiftCssValue: crossAxisShiftCssValue,
-        direction: resolvedPlacement.offset.crossAxisShift.direction
+        direction: stablePlacement.offset.crossAxisShift.direction
       });
       // Map margin property to its corresponding custom property name.
       var customPropertyByMarginProperty = {
@@ -331,13 +362,26 @@ export function useAnchorPosition(_ref5) {
         // because that's where useAnchorPosition sets the margin gap.
         popover.setAttribute('data-ds-popover-arrow', '');
       }
+
+      /**
+       * **We are never cleaning up anchor names**
+       *
+       * _Rationale_
+       *
+       * - Multiple popovers can share the same anchor element.
+       * - Sometimes the `useAnchorPosition` hook and `Popover`
+       *   are not in the same component.
+       * - There can be times when, even with reference counting, we
+       *   could remove the anchor-name while it's still being used
+       *   by something else - especially with async react updates
+       *   which can cause tearing
+       *
+       * _More_
+       *
+       * See `notes/decisions/anchor-name-lifetime.md`
+       */
+      trigger.style.setProperty('anchor-name', anchorName);
       var _undoPositioning = combine(setStyle({
-        el: trigger,
-        styles: [{
-          property: 'anchor-name',
-          value: anchorName
-        }]
-      }), setStyle({
         el: popover,
         styles: popoverStyles
       }), arrow ? function () {
@@ -389,12 +433,12 @@ export function useAnchorPosition(_ref5) {
       var _computeFallbackPosit = computeFallbackPosition({
           triggerRect: triggerRect,
           popoverEl: popover,
-          placement: resolvedPlacement,
+          placement: stablePlacement,
           viewport: viewport,
           gap: gapPx,
           crossAxisShift: {
             value: crossAxisShiftPx,
-            direction: resolvedPlacement.offset.crossAxisShift.direction
+            direction: stablePlacement.offset.crossAxisShift.direction
           }
         }),
         top = _computeFallbackPosit.top,
@@ -469,5 +513,5 @@ export function useAnchorPosition(_ref5) {
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, placement, anchorName, forceFallbackPositioning, arrow]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, arrow, id]);
 }

package/dist/esm/popup/popup-content.js

@@ -4,7 +4,7 @@ import { ax, ix } from "@compiled/react/runtime";
 import React, { forwardRef, useCallback, useLayoutEffect, useRef } from 'react';
 import mergeRefs from '@atlaskit/ds-lib/merge-refs';
 import { roleToAriaHasPopup } from '../internal/role-types';
-import { useAnchorPosition } from '../internal/use-anchor-positioning';
+import { useAnchorPosition } from '../internal/use-anchor-position';
 import { usePresetStyles } from '../internal/use-preset-styles';
 import { Popover } from '../popover/popover';
 import { useMaybePopupContext } from './popup-context';

package/dist/esm/testing/polyfill.js

@@ -14,7 +14,7 @@
  *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
  *    outside the open chain, and dismiss the topmost on Escape.
  *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
  *    visible in jsdom, where layout-driven RO callbacks never fire.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.
@@ -249,7 +249,7 @@ function stackForMode(_ref9) {
 
 // Polyfill-only. Real browsers reveal the popover once `ResizeObserver`
 // callbacks fire after the first layout pass. jsdom has no layout, so we clear
-// any inline `opacity: 0` (set by callers like `use-anchor-positioning`) once
+// any inline `opacity: 0` (set by callers like `use-anchor-position`) once
 // the open toggle has fired.
 function clearOpacityOnOpenToggle(_ref0) {
   var element = _ref0.element;

package/dist/types/entry-points/use-anchor-position.d.ts

@@ -1 +1 @@
-export { useAnchorPosition } from '../internal/use-anchor-positioning';
+export { useAnchorPosition } from '../internal/use-anchor-position';

package/dist/{types-ts4.5/internal/use-anchor-positioning.d.ts → types/internal/use-anchor-position.d.ts}

@@ -72,6 +72,10 @@ export declare function placementToTryFallbacks({ placement }: {
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
+ *
+ * `placement` may be a fresh inline object on every render: a structural
+ * comparison is used internally so re-runs are skipped when the resolved
+ * placement shape is unchanged.
  */
 export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, arrow, }: {
     /**
@@ -86,8 +90,23 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, fo
      * Where to place the element relative to the anchor.
      * `offset.gap` and `offset.crossAxisShift` are part of the
      * placement object.
+     *
+     * All fields are optional. Omitted fields fall back to:
+     *   - `axis`: `'block'`
+     *   - `edge`: `'end'`
+     *   - `align`: `'center'`
+     *   - `offset.gap`: `token('space.100', '8px')`
+     *   - `offset.crossAxisShift.value`: `'0px'`
+     *   - `offset.crossAxisShift.direction`: `'forwards'`
+     *
+     * The full default placement (`{}`) renders the popover centered
+     * below the trigger with one `space.100` of gap and no cross-axis
+     * shift.
+     *
+     * `offset.gap` and `offset.crossAxisShift.value` accept either a
+     * number (pixels) or a CSS length string (eg `token('space.200')`).
      */
-    placement: TPlacementOptions;
+    placement?: TPlacementOptions;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback

package/dist/types/testing/polyfill.d.ts

@@ -13,7 +13,7 @@
  *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
  *    outside the open chain, and dismiss the topmost on Escape.
  *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
  *    visible in jsdom, where layout-driven RO callbacks never fire.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.

package/dist/types-ts4.5/entry-points/use-anchor-position.d.ts

@@ -1 +1 @@
-export { useAnchorPosition } from '../internal/use-anchor-positioning';
+export { useAnchorPosition } from '../internal/use-anchor-position';

package/dist/{types/internal/use-anchor-positioning.d.ts → types-ts4.5/internal/use-anchor-position.d.ts}

@@ -72,6 +72,10 @@ export declare function placementToTryFallbacks({ placement }: {
  * When not supported, it falls back to JavaScript-based positioning using
  * `position: fixed` with measured coordinates, re-running on scroll (capture)
  * and resize events.
+ *
+ * `placement` may be a fresh inline object on every render: a structural
+ * comparison is used internally so re-runs are skipped when the resolved
+ * placement shape is unchanged.
  */
 export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, arrow, }: {
     /**
@@ -86,8 +90,23 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, fo
      * Where to place the element relative to the anchor.
      * `offset.gap` and `offset.crossAxisShift` are part of the
      * placement object.
+     *
+     * All fields are optional. Omitted fields fall back to:
+     *   - `axis`: `'block'`
+     *   - `edge`: `'end'`
+     *   - `align`: `'center'`
+     *   - `offset.gap`: `token('space.100', '8px')`
+     *   - `offset.crossAxisShift.value`: `'0px'`
+     *   - `offset.crossAxisShift.direction`: `'forwards'`
+     *
+     * The full default placement (`{}`) renders the popover centered
+     * below the trigger with one `space.100` of gap and no cross-axis
+     * shift.
+     *
+     * `offset.gap` and `offset.crossAxisShift.value` accept either a
+     * number (pixels) or a CSS length string (eg `token('space.200')`).
      */
-    placement: TPlacementOptions;
+    placement?: TPlacementOptions;
     /**
      * Forces the JavaScript positioning fallback even when the browser
      * supports CSS Anchor Positioning. Useful for testing fallback

package/dist/types-ts4.5/testing/polyfill.d.ts

@@ -13,7 +13,7 @@
  *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
  *    outside the open chain, and dismiss the topmost on Escape.
  *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-positioning`) become
+ *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
  *    visible in jsdom, where layout-driven RO callbacks never fire.
  *
  * Companion `toBeVisible` patch lives at `./to-be-visible`.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.4.0",
+	"version": "0.5.1",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",