@atlaskit/top-layer 4.2.2 → 4.2.4

package/dist/es2019/internal/use-anchor-position.js

@@ -62,6 +62,38 @@ const supportsAnchorPositioning = once(() => {
   return CSS.supports('anchor-name', '--a');
 });
 
+/**
+ * Every logical margin property this module can write: one per axis, per side.
+ *
+ * Deriving the union from `TPlacementAxis` and `TPlacementEdge` rather than
+ * writing the four names out keeps it in step with the placement model, and
+ * makes `CROSS_AXIS_SHIFT_CUSTOM_PROPERTY` below exhaustive by construction.
+ */
+
+/**
+ * The custom property mirroring each cross-axis shift margin.
+ *
+ * These are written for the planned named arrow `@position-try` rules. Nothing
+ * reads them yet, and the shift no longer depends on them: the antisymmetric
+ * margins written by `crossAxisShiftMargins` survive a cross-axis slide on
+ * their own.
+ *
+ * Keyed on `TLogicalMarginProperty` and not on `string`, so a margin property
+ * that has no custom property (or a custom property whose margin no longer
+ * exists) is a compile error rather than an `undefined` lookup that reaches
+ * `setStyle` as `{ property: undefined, value }`.
+ */
+const CROSS_AXIS_SHIFT_CUSTOM_PROPERTY = {
+  'margin-inline-start': '--ds-cross-axis-shift-margin-start',
+  'margin-inline-end': '--ds-cross-axis-shift-margin-end',
+  'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
+  'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
+};
+const ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES = Object.values(CROSS_AXIS_SHIFT_CUSTOM_PROPERTY).map(property => ({
+  property,
+  value: '0px'
+}));
+
 /**
  * Returns the CSS margin declaration that creates a gap between the
  * popover and its trigger on the side facing the anchor.
@@ -77,65 +109,65 @@ function edgeMargin({
     axis,
     edge
   } = placement;
-  const value = offset;
-  if (axis === 'block' && edge === 'end') {
-    return {
-      property: 'margin-block-start',
-      value
-    };
-  }
-  if (axis === 'block' && edge === 'start') {
-    return {
-      property: 'margin-block-end',
-      value
-    };
-  }
-  if (axis === 'inline' && edge === 'end') {
-    return {
-      property: 'margin-inline-start',
-      value
-    };
-  }
-  if (axis === 'inline' && edge === 'start') {
-    return {
-      property: 'margin-inline-end',
-      value
-    };
-  }
+  // The gap sits on the side FACING the anchor, which is always the side
+  // opposite the placement edge.
+  const anchorFacingEdge = edge === 'end' ? 'start' : 'end';
   return {
-    property: 'margin-block-start',
-    value
+    property: `margin-${axis}-${anchorFacingEdge}`,
+    value: offset
   };
 }
 
 /**
- * Cross-axis shift margin. Margin side matches the popover's anchored
- * cross-axis edge: `align: 'start'` uses the START margin, `align: 'end'`
- * uses the END margin with the sign inverted (so `forwards` is always
- * positive), `align: 'center'` uses START. Margin on the un-anchored side
- * has no effect under CSS Anchor Positioning.
+ * **The cross-axis shift margins.**
+ *
+ * The shift is written antisymmetrically on BOTH cross-axis sides
+ * (`start: +value`, `end: -value`) rather than as a single margin on the side
+ * picked from `align`. Two separate behaviours require it:
+ *
+ * 1. **`align: 'center'` is centered with `anchor-center`, which centers the
+ *    popover's MARGIN box on the anchor.** A single-sided margin widens the
+ *    margin box, so it displaces the border box by only half its value. An
+ *    antisymmetric pair leaves the margin box width unchanged (`+value` and
+ *    `-value` sum to zero) while moving its center by the full value.
+ * 2. **`position-try-fallbacks` can slide the popover onto the opposite
+ *    cross-axis side.** A `<position-area>` fallback keeps the base style's
+ *    margins, and margin on the un-anchored side has no effect, so a
+ *    single-sided margin is silently dropped once the browser slides across the
+ *    cross axis. With both sides written, whichever side ends up anchored moves
+ *    the popover the same physical direction.
+ *
+ * Leaving the margin box width unchanged also means the shift does not move
+ * the point at which `position-try-fallbacks` decides the popover overflows.
+ *
+ * A `<try-tactic>` fallback (`flip-block`, `flip-inline`) behaves differently to
+ * a `<position-area>` one: it SWAPS the start and end margins rather than
+ * keeping them, which is what preserves the gap through a flip. So a flip across
+ * the cross axis mirrors the shift along with the rest of the placement, rather
+ * than preserving its physical direction. Only the diagonal fallback does that,
+ * and only for `align: 'start' | 'end'`. See `placementToTryFallbacks`.
+ *
+ * A positive value always moves the popover toward the cross-axis END, so
+ * `direction: 'forwards'` means the same thing for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
  */
-function crossAxisShiftMargin({
+function crossAxisShiftMargins({
   placement,
   crossAxisShiftCssValue,
   direction
 }) {
-  const {
-    axis,
-    align
-  } = placement;
-  const directionSign = direction === 'forwards' ? 1 : -1;
-  const crossAxis = axis === 'block' ? 'inline' : 'block';
-  const useEndSide = align === 'end';
-  const side = useEndSide ? 'end' : 'start';
-  const sideSign = useEndSide ? -1 : 1;
-  const finalSign = directionSign * sideSign;
-  // Wrap any string in calc() with the sign factor. CSS handles the math.
-  const value = finalSign === 1 ? crossAxisShiftCssValue : `calc(-1 * ${crossAxisShiftCssValue})`;
-  return {
-    property: `margin-${crossAxis}-${side}`,
-    value
-  };
+  const crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  // Wrap any string in calc() with the sign factor. CSS handles the math,
+  // so opaque values such as design tokens negate correctly.
+  const negated = `calc(-1 * ${crossAxisShiftCssValue})`;
+  const isForwards = direction === 'forwards';
+  return [{
+    property: `margin-${crossAxis}-start`,
+    value: isForwards ? crossAxisShiftCssValue : negated
+  }, {
+    property: `margin-${crossAxis}-end`,
+    value: isForwards ? negated : crossAxisShiftCssValue
+  }];
 }
 
 /**
@@ -216,10 +248,9 @@ export function useAnchorPosition({
         placement: stablePlacement,
         offset: gapCssValue
       });
-      // Computed once; reused below to populate the active
-      // `--ds-cross-axis-shift-margin-*` custom property for the
-      // named arrow @position-try rules.
-      const crossAxisShift = crossAxisShiftMargin({
+      // Computed once; also mirrored into the
+      // `--ds-cross-axis-shift-margin-*` custom properties below.
+      const crossAxisShift = crossAxisShiftMargins({
         placement: stablePlacement,
         crossAxisShiftCssValue,
         direction: stablePlacement.offset.crossAxisShift.direction
@@ -246,48 +277,16 @@ export function useAnchorPosition({
       }, {
         property: 'inset',
         value: 'auto'
-      }, {
-        property: gap.property,
-        value: gap.value
-      }, {
-        property: crossAxisShift.property,
-        value: crossAxisShift.value
-      }];
-
-      // Expose the active cross-axis shift via custom properties so each
-      // named arrow @position-try rule can re-apply it after a flip.
-      // One of the four (cross-axis, side) properties is non-zero at a time.
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-end',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-start',
-        value: '0px'
-      });
-      popoverStyles.push({
-        property: '--ds-cross-axis-shift-margin-block-end',
-        value: '0px'
-      });
-      // `crossAxisShift` IS the active margin; reuse instead of recomputing.
-      const crossAxisShiftActive = crossAxisShift;
-      const customPropertyByMarginProperty = {
-        'margin-inline-start': '--ds-cross-axis-shift-margin-start',
-        'margin-inline-end': '--ds-cross-axis-shift-margin-end',
-        'margin-block-start': '--ds-cross-axis-shift-margin-block-start',
-        'margin-block-end': '--ds-cross-axis-shift-margin-block-end'
-      };
-      const crossAxisShiftCustomProperty = customPropertyByMarginProperty[crossAxisShiftActive.property];
-      if (crossAxisShiftCustomProperty) {
-        popoverStyles.push({
-          property: crossAxisShiftCustomProperty,
-          value: crossAxisShiftActive.value
-        });
-      }
+      }, gap, ...crossAxisShift,
+      // Zero every side first so the two sides that are NOT on the
+      // active cross axis do not keep a value from a previous placement.
+      ...ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES, ...crossAxisShift.map(({
+        property,
+        value
+      }) => ({
+        property: CROSS_AXIS_SHIFT_CUSTOM_PROPERTY[property],
+        value
+      }))];
 
       /**
        * **We are never cleaning up anchor names**

package/dist/es2019/internal/use-width-from-anchor.js

@@ -1,18 +1,44 @@
 import { useLayoutEffect } from 'react';
+import once from '@atlaskit/ds-lib/once';
 import { setStyle } from './set-style';
 
+/**
+ * Probes anchor SIZING, separately from `anchor-name` (see
+ * `supportsAnchorPositioning`): some browsers have positioning but not sizing.
+ * `once()` for SSR safety.
+ */
+const supportsAnchorSize = once(() => {
+  if (typeof window === 'undefined' || typeof CSS === 'undefined' || typeof CSS.supports !== 'function') {
+    return false;
+  }
+  return CSS.supports('min-inline-size', 'anchor-size(self-inline)');
+});
+
+/**
+ * The JS fallback's stand-in for `anchor-size(self-inline)`. `offsetWidth` / `offsetHeight` are
+ * physical, so the axis is picked from the popover's `writing-mode`. Anything not horizontal is
+ * treated as vertical, and an unknown or empty value falls back to `offsetWidth`.
+ */
+function getFallbackAnchorInlineSize({
+  anchor,
+  popover
+}) {
+  // `String()` because not every test environment implements `writing-mode`.
+  const writingMode = String(getComputedStyle(popover).writingMode);
+  const isVertical = writingMode.startsWith('vertical') || writingMode.startsWith('sideways');
+  return isVertical ? anchor.offsetHeight : anchor.offsetWidth;
+}
+
 /**
  * Sets the width of a popover element relative to its anchor element.
  *
- * - `'match-anchor'` → `width: anchor-size(width)` - popover matches anchor width exactly.
- * - `'min-anchor'`   → `min-width: anchor-size(width)` - popover is at least as wide as anchor,
- *   but can grow wider.
- * - `'none'`         → no explicit width is set (default behaviour)
+ * - `'match-anchor'` → `inline-size: anchor-size(self-inline)`, exact
+ * - `'min-anchor'`   → `min-inline-size: anchor-size(self-inline)`, floor only
+ * - `'none'`         → `min-inline-size: max-content`, content floor (default)
  *
- * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
- * one-off measurement of `anchor.offsetWidth`.
- *
- * Designed to be composed alongside `useAnchorPosition` for top-layer popovers.
+ * `self-inline` is the inline axis of the element USING the function (the popover), never the
+ * anchor, so it matches the axis `inline-size` constrains. See
+ * `notes/decisions/width-from-anchor-floors.md`.
  */
 export function useWidthFromAnchor({
   mode,
@@ -25,55 +51,41 @@ export function useWidthFromAnchor({
     if (!node) {
       return;
     }
-
-    // Feature-detect `anchor-size()` specifically (not just `anchor-name`)
-    // so the JS fallback fires correctly in browsers that support anchor
-    // positioning but not anchor sizing.
-    const supportsAnchorSize = typeof CSS !== 'undefined' && typeof CSS.supports === 'function' && CSS.supports('width', 'anchor-size(width)');
     if (mode === 'match-anchor') {
-      // Set an exact width matching the anchor.
-      // `min-inline-size` is intentionally NOT set here - it would override the
-      // explicit width constraint, allowing the popover to grow past the anchor's width.
-      if (supportsAnchorSize) {
+      // No floor here: it would let the popover grow past the anchor.
+      if (supportsAnchorSize()) {
         return setStyle({
           element: node,
           styles: [{
-            property: 'width',
-            value: 'anchor-size(width)'
+            property: 'inline-size',
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
-
-      // JS fallback: one-off read of the anchor's width.
       const anchor = anchorRef.current;
       if (anchor) {
         return setStyle({
           element: node,
           styles: [{
-            property: 'width',
-            value: `${anchor.offsetWidth}px`
+            property: 'inline-size',
+            value: `${getFallbackAnchorInlineSize({
+              anchor,
+              popover: node
+            })}px`
           }]
         });
       }
       return;
     }
-
-    // For 'min-anchor' and 'none', apply `min-inline-size: max-content` to ensure
-    // correct position-try-fallbacks behaviour (popover margin box overflows the
-    // viewport when its span region is too narrow, rather than wrapping content).
-    const minInlineSizeStyle = {
-      property: 'min-inline-size',
-      value: 'max-content'
-    };
     if (mode === 'min-anchor') {
-      // Set a minimum width matching the anchor. The popover can grow wider
-      // if its content requires it.
-      if (supportsAnchorSize) {
+      // One floor only. The content floor from mode 'none' deliberately does not also apply
+      // here, and cannot: it would need this same property. See the decision note.
+      if (supportsAnchorSize()) {
         return setStyle({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
-            value: 'anchor-size(width)'
+          styles: [{
+            property: 'min-inline-size',
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
@@ -81,24 +93,28 @@ export function useWidthFromAnchor({
       if (anchor) {
         return setStyle({
           element: node,
-          styles: [minInlineSizeStyle, {
-            property: 'min-width',
-            value: `${anchor.offsetWidth}px`
+          styles: [{
+            property: 'min-inline-size',
+            value: `${getFallbackAnchorInlineSize({
+              anchor,
+              popover: node
+            })}px`
           }]
         });
       }
 
-      // No anchor available in JS fallback - still apply min-inline-size.
-      return setStyle({
-        element: node,
-        styles: [minInlineSizeStyle]
-      });
+      // Nothing to measure, so no floor.
+      return;
     }
 
-    // 'none' mode: no explicit width, but still apply `min-inline-size: max-content`.
+    // Makes a too-narrow span overflow and drive `position-try-fallbacks` instead of wrapping.
+    // `@atlaskit/popper` resets this exact property to `0` for its fit-to-viewport mode.
     return setStyle({
       element: node,
-      styles: [minInlineSizeStyle]
+      styles: [{
+        property: 'min-inline-size',
+        value: 'max-content'
+      }]
     });
   }, [mode, popoverRef, anchorRef, isOpen]);
 }

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

@@ -13,6 +13,19 @@ function _objectSpread(e) { for (var r = 1; r < arguments.length; r++) { var t =
  * position.
  */
 
+/**
+ * A viewport-relative position, in pixels. Physical rather than logical
+ * because it is written straight to `top` / `left`.
+ */
+
+/**
+ * The cross-axis shift with its length already resolved to pixels.
+ *
+ * Mirrors `TCrossAxisShiftOffset`, whose `value` is an unresolved CSS length
+ * string. Only this module needs the pixel form, because only this module does
+ * the arithmetic itself.
+ */
+
 /**
  * Computes the base {top, left} position based on the primary edge,
  * flipping to the opposite side when there is not enough space.
@@ -123,23 +136,26 @@ function applyAlignment(_ref2) {
 /**
  * Applies the cross-axis shift offset.
  *
- * The sign mirrors the CSS path (see `crossAxisShiftMargin` in
- * `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.
+ * `forwards` always moves the popover toward the cross-axis END and
+ * `backwards` toward the START, for every `align` value. See
+ * `notes/decisions/placement-offset.md`.
+ *
+ * This is a coordinate, so the direction is the sign and nothing else. There
+ * is deliberately no per-`align` sign inversion here: the CSS path inverts the
+ * sign only because a margin on the END side pushes a box the opposite way to
+ * a margin on the START side, which is a property of margins rather than of
+ * the shift. Applying that inversion to a coordinate moved `align: 'end'`
+ * popovers the wrong way.
  */
 function applyCrossAxisShift(_ref3) {
   var position = _ref3.position,
     axis = _ref3.axis,
-    align = _ref3.align,
     crossAxisShift = _ref3.crossAxisShift;
   if (crossAxisShift.value === 0) {
     return position;
   }
   var directionSign = crossAxisShift.direction === 'forwards' ? 1 : -1;
-  var sideSign = align === 'end' ? -1 : 1;
-  var delta = crossAxisShift.value * directionSign * sideSign;
+  var delta = crossAxisShift.value * directionSign;
 
   // Cross-axis is the OPPOSITE of the placement axis.
   if (axis === 'block') {
@@ -195,7 +211,6 @@ export function computeFallbackPosition(_ref4) {
   var shiftedPosition = applyCrossAxisShift({
     position: alignedPosition,
     axis: axis,
-    align: align,
     crossAxisShift: crossAxisShift
   });
 

package/dist/esm/internal/get-aria-for-trigger.js

@@ -44,8 +44,9 @@ var roleToAriaHasPopup = {
  *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
  *   the value is `undefined`.
  * - `aria-expanded` - reflects the current open state.
- * - `aria-controls` - references the popover element by its id while the
- *   popover is open, and is omitted while the popover is closed and unmounted.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
  *
  * **This function is for click/keyboard-activated popovers only.** For
  * hover-driven tooltips, the trigger should use `aria-describedby` instead.

package/dist/esm/internal/resolve-placement.js

@@ -7,10 +7,15 @@ import { toCssLengthString } from './resolve-css-length';
  */
 var DEFAULT_GAP = "var(--ds-space-100, 8px)";
 
+/**
+ * Which way along the cross axis a shift moves the popover. `'forwards'` is
+ * always toward the cross-axis END and `'backwards'` toward the START, for
+ * every `align` value. See `notes/decisions/placement-offset.md`.
+ */
+
 /**
  * Cross-axis shift. `value` is a CSS length string (consumer numbers are
- * normalized to `${n}px`). `direction` is `'forwards'` (toward end) or
- * `'backwards'` (toward start).
+ * normalized to `${n}px`).
  */
 
 /**

package/dist/esm/internal/set-style.js

@@ -1,3 +1,12 @@
+/**
+ * A single inline style declaration.
+ *
+ * `TProperty` narrows the property name for callers that write a known, closed
+ * set of properties. Narrowing it lets a record keyed on those same names be
+ * checked for exhaustiveness at compile time, rather than silently resolving to
+ * `undefined` for a name that was never mapped.
+ */
+
 /**
  * Sets inline styles on an element and returns a cleanup function that
  * restores the prior inline values (so we do not stomp consumer styles).