@atlaskit/top-layer 4.2.3 → 4.2.4

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @atlaskit/top-layer
 
+## 4.2.4
+
+### Patch Changes
+
+- [`41f64e5df21c7`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/41f64e5df21c7) -
+  `useWidthFromAnchor` now sizes against `anchor-size(self-inline)` rather than
+  `anchor-size(width)`, so an anchor-relative popover width is measured on the same axis as the
+  property it is set on. No change in a horizontal writing mode.
+
 ## 4.2.3
 
 ### Patch Changes

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

@@ -20,6 +20,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.

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

@@ -12,10 +12,15 @@ var _resolveCssLength = require("./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/cjs/internal/set-style.js

@@ -4,6 +4,15 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.setStyle = setStyle;
+/**
+ * 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).

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

@@ -83,7 +83,11 @@ var supportsAnchorPositioning = (0, _once.default)(function () {
 });
 
 /**
- * A single inline style declaration, as consumed by `setStyle`.
+ * 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.
  */
 
 /**
@@ -93,6 +97,11 @@ var supportsAnchorPositioning = (0, _once.default)(function () {
  * 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 }`.
  */
 var CROSS_AXIS_SHIFT_CUSTOM_PROPERTY = {
   'margin-inline-start': '--ds-cross-axis-shift-margin-start',
@@ -119,34 +128,12 @@ function edgeMargin(_ref) {
     offset = _ref.offset;
   var axis = placement.axis,
     edge = placement.edge;
-  var value = offset;
-  if (axis === 'block' && edge === 'end') {
-    return {
-      property: 'margin-block-start',
-      value: value
-    };
-  }
-  if (axis === 'block' && edge === 'start') {
-    return {
-      property: 'margin-block-end',
-      value: value
-    };
-  }
-  if (axis === 'inline' && edge === 'end') {
-    return {
-      property: 'margin-inline-start',
-      value: value
-    };
-  }
-  if (axis === 'inline' && edge === 'start') {
-    return {
-      property: 'margin-inline-end',
-      value: value
-    };
-  }
+  // The gap sits on the side FACING the anchor, which is always the side
+  // opposite the placement edge.
+  var anchorFacingEdge = edge === 'end' ? 'start' : 'end';
   return {
-    property: 'margin-block-start',
-    value: value
+    property: "margin-".concat(axis, "-").concat(anchorFacingEdge),
+    value: offset
   };
 }
 
@@ -312,10 +299,7 @@ function useAnchorPosition(_ref3) {
       }, {
         property: 'inset',
         value: 'auto'
-      }, {
-        property: gap.property,
-        value: gap.value
-      }].concat((0, _toConsumableArray2.default)(crossAxisShift), (0, _toConsumableArray2.default)(ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES), (0, _toConsumableArray2.default)(crossAxisShift.map(function (_ref4) {
+      }, gap].concat((0, _toConsumableArray2.default)(crossAxisShift), (0, _toConsumableArray2.default)(ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES), (0, _toConsumableArray2.default)(crossAxisShift.map(function (_ref4) {
         var property = _ref4.property,
           value = _ref4.value;
         return {

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

@@ -1,88 +1,95 @@
 "use strict";
 
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.useWidthFromAnchor = useWidthFromAnchor;
 var _react = require("react");
+var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
 var _setStyle = require("./set-style");
+/**
+ * Probes anchor SIZING, separately from `anchor-name` (see
+ * `supportsAnchorPositioning`): some browsers have positioning but not sizing.
+ * `once()` for SSR safety.
+ */
+var supportsAnchorSize = (0, _once.default)(function () {
+  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(_ref) {
+  var anchor = _ref.anchor,
+    popover = _ref.popover;
+  // `String()` because not every test environment implements `writing-mode`.
+  var writingMode = String(getComputedStyle(popover).writingMode);
+  var 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-inline-size: anchor-size(width)` - popover is at least as wide as the
- *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
- *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
- *   the popover at its own content width.
- * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
- *   popover's own content width (default behaviour)
- *
- * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
- * one-off measurement of `anchor.offsetWidth`.
+ * - `'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)
  *
- * 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`.
  */
-function useWidthFromAnchor(_ref) {
-  var mode = _ref.mode,
-    popoverRef = _ref.popoverRef,
-    anchorRef = _ref.anchorRef,
-    isOpen = _ref.isOpen;
+function useWidthFromAnchor(_ref2) {
+  var mode = _ref2.mode,
+    popoverRef = _ref2.popoverRef,
+    anchorRef = _ref2.anchorRef,
+    isOpen = _ref2.isOpen;
   (0, _react.useLayoutEffect)(function () {
     var node = popoverRef.current;
     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.
-    var 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 (0, _setStyle.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.
       var anchor = anchorRef.current;
       if (anchor) {
         return (0, _setStyle.setStyle)({
           element: node,
           styles: [{
-            property: 'width',
-            value: "".concat(anchor.offsetWidth, "px")
+            property: 'inline-size',
+            value: "".concat(getFallbackAnchorInlineSize({
+              anchor: anchor,
+              popover: node
+            }), "px")
           }]
         });
       }
       return;
     }
     if (mode === 'min-anchor') {
-      // One declaration, one floor: the anchor width, as a lower bound and not an
-      // exact size, which is what separates 'min-anchor' from 'match-anchor'.
-      //
-      // This mode deliberately does NOT also floor the popover at its own content
-      // width. Mode 'none' does, to make a too-narrow span overflow and drive
-      // `position-try-fallbacks`, but that floor can only be expressed on
-      // `min-inline-size` or on `width`, and both collide with the anchor floor here:
-      // `min-inline-size` IS `min-width` in a horizontal writing mode, and `width` is
-      // an exact size, so it would cap the popover and override a consumer width.
-      // The anchor floor already guarantees a usable width for this mode, so the
-      // popover is allowed to wrap down to it. See
-      // `notes/decisions/width-from-anchor-floors.md`.
-      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 (0, _setStyle.setStyle)({
           element: node,
           styles: [{
             property: 'min-inline-size',
-            value: 'anchor-size(width)'
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
@@ -92,18 +99,20 @@ function useWidthFromAnchor(_ref) {
           element: node,
           styles: [{
             property: 'min-inline-size',
-            value: "".concat(_anchor.offsetWidth, "px")
+            value: "".concat(getFallbackAnchorInlineSize({
+              anchor: _anchor,
+              popover: node
+            }), "px")
           }]
         });
       }
 
-      // No anchor to measure in the JS fallback, so there is no floor to apply.
+      // Nothing to measure, so no floor.
       return;
     }
 
-    // 'none' has no anchor floor to collide with, so it can carry the content floor.
-    // `@atlaskit/popper` depends on the property: its fit-to-viewport mode neutralises
-    // this floor with `min-inline-size: 0`.
+    // 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 (0, _setStyle.setStyle)({
       element: node,
       styles: [{

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

@@ -10,6 +10,19 @@
  * 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.

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

@@ -7,10 +7,15 @@ import { toCssLengthString } from './resolve-css-length';
  */
 const 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/es2019/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).

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

@@ -63,7 +63,11 @@ const supportsAnchorPositioning = once(() => {
 });
 
 /**
- * A single inline style declaration, as consumed by `setStyle`.
+ * 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.
  */
 
 /**
@@ -73,6 +77,11 @@ const supportsAnchorPositioning = once(() => {
  * 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',
@@ -100,34 +109,12 @@ 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
   };
 }
 
@@ -290,10 +277,7 @@ export function useAnchorPosition({
       }, {
         property: 'inset',
         value: 'auto'
-      }, {
-        property: gap.property,
-        value: gap.value
-      }, ...crossAxisShift,
+      }, 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(({

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

@@ -1,21 +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-inline-size: anchor-size(width)` - popover is at least as wide as the
- *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
- *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
- *   the popover at its own content width.
- * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
- *   popover's own content width (default behaviour)
- *
- * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
- * one-off measurement of `anchor.offsetWidth`.
+ * - `'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)
  *
- * 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,
@@ -28,57 +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;
     }
     if (mode === 'min-anchor') {
-      // One declaration, one floor: the anchor width, as a lower bound and not an
-      // exact size, which is what separates 'min-anchor' from 'match-anchor'.
-      //
-      // This mode deliberately does NOT also floor the popover at its own content
-      // width. Mode 'none' does, to make a too-narrow span overflow and drive
-      // `position-try-fallbacks`, but that floor can only be expressed on
-      // `min-inline-size` or on `width`, and both collide with the anchor floor here:
-      // `min-inline-size` IS `min-width` in a horizontal writing mode, and `width` is
-      // an exact size, so it would cap the popover and override a consumer width.
-      // The anchor floor already guarantees a usable width for this mode, so the
-      // popover is allowed to wrap down to it. See
-      // `notes/decisions/width-from-anchor-floors.md`.
-      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: [{
             property: 'min-inline-size',
-            value: 'anchor-size(width)'
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
@@ -88,18 +95,20 @@ export function useWidthFromAnchor({
           element: node,
           styles: [{
             property: 'min-inline-size',
-            value: `${anchor.offsetWidth}px`
+            value: `${getFallbackAnchorInlineSize({
+              anchor,
+              popover: node
+            })}px`
           }]
         });
       }
 
-      // No anchor to measure in the JS fallback, so there is no floor to apply.
+      // Nothing to measure, so no floor.
       return;
     }
 
-    // 'none' has no anchor floor to collide with, so it can carry the content floor.
-    // `@atlaskit/popper` depends on the property: its fit-to-viewport mode neutralises
-    // this floor with `min-inline-size: 0`.
+    // 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: [{

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.

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).

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

@@ -76,7 +76,11 @@ var supportsAnchorPositioning = once(function () {
 });
 
 /**
- * A single inline style declaration, as consumed by `setStyle`.
+ * 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.
  */
 
 /**
@@ -86,6 +90,11 @@ var supportsAnchorPositioning = once(function () {
  * 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 }`.
  */
 var CROSS_AXIS_SHIFT_CUSTOM_PROPERTY = {
   'margin-inline-start': '--ds-cross-axis-shift-margin-start',
@@ -112,34 +121,12 @@ function edgeMargin(_ref) {
     offset = _ref.offset;
   var axis = placement.axis,
     edge = placement.edge;
-  var value = offset;
-  if (axis === 'block' && edge === 'end') {
-    return {
-      property: 'margin-block-start',
-      value: value
-    };
-  }
-  if (axis === 'block' && edge === 'start') {
-    return {
-      property: 'margin-block-end',
-      value: value
-    };
-  }
-  if (axis === 'inline' && edge === 'end') {
-    return {
-      property: 'margin-inline-start',
-      value: value
-    };
-  }
-  if (axis === 'inline' && edge === 'start') {
-    return {
-      property: 'margin-inline-end',
-      value: value
-    };
-  }
+  // The gap sits on the side FACING the anchor, which is always the side
+  // opposite the placement edge.
+  var anchorFacingEdge = edge === 'end' ? 'start' : 'end';
   return {
-    property: 'margin-block-start',
-    value: value
+    property: "margin-".concat(axis, "-").concat(anchorFacingEdge),
+    value: offset
   };
 }
 
@@ -305,10 +292,7 @@ export function useAnchorPosition(_ref3) {
       }, {
         property: 'inset',
         value: 'auto'
-      }, {
-        property: gap.property,
-        value: gap.value
-      }].concat(_toConsumableArray(crossAxisShift), _toConsumableArray(ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES), _toConsumableArray(crossAxisShift.map(function (_ref4) {
+      }, gap].concat(_toConsumableArray(crossAxisShift), _toConsumableArray(ZEROED_CROSS_AXIS_SHIFT_CUSTOM_PROPERTIES), _toConsumableArray(crossAxisShift.map(function (_ref4) {
         var property = _ref4.property,
           value = _ref4.value;
         return {

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

@@ -1,83 +1,89 @@
 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.
+ */
+var supportsAnchorSize = once(function () {
+  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(_ref) {
+  var anchor = _ref.anchor,
+    popover = _ref.popover;
+  // `String()` because not every test environment implements `writing-mode`.
+  var writingMode = String(getComputedStyle(popover).writingMode);
+  var 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-inline-size: anchor-size(width)` - popover is at least as wide as the
- *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
- *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
- *   the popover at its own content width.
- * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
- *   popover's own content width (default behaviour)
- *
- * Uses CSS `anchor-size(width)` when the browser supports it, falling back to a
- * one-off measurement of `anchor.offsetWidth`.
+ * - `'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)
  *
- * 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(_ref) {
-  var mode = _ref.mode,
-    popoverRef = _ref.popoverRef,
-    anchorRef = _ref.anchorRef,
-    isOpen = _ref.isOpen;
+export function useWidthFromAnchor(_ref2) {
+  var mode = _ref2.mode,
+    popoverRef = _ref2.popoverRef,
+    anchorRef = _ref2.anchorRef,
+    isOpen = _ref2.isOpen;
   useLayoutEffect(function () {
     var node = popoverRef.current;
     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.
-    var 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.
       var anchor = anchorRef.current;
       if (anchor) {
         return setStyle({
           element: node,
           styles: [{
-            property: 'width',
-            value: "".concat(anchor.offsetWidth, "px")
+            property: 'inline-size',
+            value: "".concat(getFallbackAnchorInlineSize({
+              anchor: anchor,
+              popover: node
+            }), "px")
           }]
         });
       }
       return;
     }
     if (mode === 'min-anchor') {
-      // One declaration, one floor: the anchor width, as a lower bound and not an
-      // exact size, which is what separates 'min-anchor' from 'match-anchor'.
-      //
-      // This mode deliberately does NOT also floor the popover at its own content
-      // width. Mode 'none' does, to make a too-narrow span overflow and drive
-      // `position-try-fallbacks`, but that floor can only be expressed on
-      // `min-inline-size` or on `width`, and both collide with the anchor floor here:
-      // `min-inline-size` IS `min-width` in a horizontal writing mode, and `width` is
-      // an exact size, so it would cap the popover and override a consumer width.
-      // The anchor floor already guarantees a usable width for this mode, so the
-      // popover is allowed to wrap down to it. See
-      // `notes/decisions/width-from-anchor-floors.md`.
-      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: [{
             property: 'min-inline-size',
-            value: 'anchor-size(width)'
+            value: 'anchor-size(self-inline)'
           }]
         });
       }
@@ -87,18 +93,20 @@ export function useWidthFromAnchor(_ref) {
           element: node,
           styles: [{
             property: 'min-inline-size',
-            value: "".concat(_anchor.offsetWidth, "px")
+            value: "".concat(getFallbackAnchorInlineSize({
+              anchor: _anchor,
+              popover: node
+            }), "px")
           }]
         });
       }
 
-      // No anchor to measure in the JS fallback, so there is no floor to apply.
+      // Nothing to measure, so no floor.
       return;
     }
 
-    // 'none' has no anchor floor to collide with, so it can carry the content floor.
-    // `@atlaskit/popper` depends on the property: its fit-to-viewport mode neutralises
-    // this floor with `min-inline-size: 0`.
+    // 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: [{

package/dist/types/internal/anchor-positioning-fallback.d.ts

@@ -1,4 +1,34 @@
-import { type TPlacement } from './resolve-placement';
+import { type TCrossAxisShiftDirection, type TPlacement } from './resolve-placement';
+/**
+ * JS fallback positioning math. Used only when the browser does not
+ * support CSS Anchor Positioning (less than 6% of users).
+ *
+ * Consumer-supplied `offset.gap` and `offset.crossAxisShift` are
+ * honored: the caller (`useAnchorPosition`) resolves CSS length strings
+ * (tokens, calc, var, etc) to pixels via a DOM probe before passing them
+ * in. The caller also keeps the popover hidden (`opacity: 0`) until the
+ * first measurement completes, so the popover never paints at the wrong
+ * position.
+ */
+/**
+ * A viewport-relative position, in pixels. Physical rather than logical
+ * because it is written straight to `top` / `left`.
+ */
+type TPosition = {
+    top: number;
+    left: number;
+};
+/**
+ * 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.
+ */
+type TResolvedCrossAxisShift = {
+    value: number;
+    direction: TCrossAxisShiftDirection;
+};
 /**
  * Computes popover position from trigger rect and viewport, flipping to
  * the side with more space when needed. Re-runs on scroll/resize.
@@ -16,11 +46,6 @@ export declare function computeFallbackPosition({ triggerRect, popoverEl, placem
         height: number;
     };
     gap: number;
-    crossAxisShift: {
-        value: number;
-        direction: 'forwards' | 'backwards';
-    };
-}): {
-    top: number;
-    left: number;
-};
+    crossAxisShift: TResolvedCrossAxisShift;
+}): TPosition;
+export {};

package/dist/types/internal/resolve-placement.d.ts

@@ -1,14 +1,20 @@
+/**
+ * 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`.
+ */
+export type TCrossAxisShiftDirection = 'forwards' | 'backwards';
 /**
  * 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`).
  */
 export type TCrossAxisShiftOffset = {
     value: string;
-    direction: 'forwards' | 'backwards';
+    direction: TCrossAxisShiftDirection;
 };
 export type TPlacementAxis = 'block' | 'inline';
 export type TPlacementEdge = 'start' | 'end';
+export type TPlacementAlign = 'start' | 'center' | 'end';
 /**
  * Fully-resolved placement (internal). Use `resolvePlacement` for partial input.
  * `offset.gap` and `offset.crossAxisShift.value` are always CSS
@@ -17,13 +23,10 @@ export type TPlacementEdge = 'start' | 'end';
 export type TPlacement = {
     axis: TPlacementAxis;
     edge: TPlacementEdge;
-    align: 'start' | 'center' | 'end';
+    align: TPlacementAlign;
     offset: {
         gap: string;
-        crossAxisShift: {
-            value: string;
-            direction: 'forwards' | 'backwards';
-        };
+        crossAxisShift: TCrossAxisShiftOffset;
     };
 };
 /**
@@ -36,14 +39,14 @@ export type TPlacement = {
  *   - `crossAxisShift`  - nudge along the trigger edge (perpendicular to the placement axis)
  */
 export type TPlacementOptions = {
-    axis?: 'block' | 'inline';
-    edge?: 'start' | 'end';
-    align?: 'start' | 'center' | 'end';
+    axis?: TPlacementAxis;
+    edge?: TPlacementEdge;
+    align?: TPlacementAlign;
     offset?: {
         gap?: number | string;
         crossAxisShift?: {
             value?: number | string;
-            direction?: 'forwards' | 'backwards';
+            direction?: TCrossAxisShiftDirection;
         };
     };
 };

package/dist/types/internal/set-style.d.ts

@@ -1,11 +1,20 @@
+/**
+ * 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.
+ */
+export type TStyleDeclaration<TProperty extends string = string> = {
+    property: TProperty;
+    value: string;
+};
 /**
  * Sets inline styles on an element and returns a cleanup function that
  * restores the prior inline values (so we do not stomp consumer styles).
  */
 export declare function setStyle({ element, styles, }: {
     element: HTMLElement;
-    styles: Array<{
-        property: string;
-        value: string;
-    }>;
+    styles: TStyleDeclaration[];
 }): () => void;

package/dist/types/internal/use-width-from-anchor.d.ts

@@ -3,18 +3,13 @@ import type { TWidthFromAnchorMode } from '../popover/types';
 /**
  * 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-inline-size: anchor-size(width)` - popover is at least as wide as the
- *   anchor, and can grow wider if its content requires it. The anchor width is the ONLY floor: see
- *   `notes/decisions/width-from-anchor-floors.md` for why this mode deliberately does not also floor
- *   the popover at its own content width.
- * - `'none'`         → `min-inline-size: max-content` - no anchor-relative width, but floored at the
- *   popover's own content width (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 declare function useWidthFromAnchor({ mode, popoverRef, anchorRef, isOpen, }: {
     mode: TWidthFromAnchorMode;

package/dist/types/popover/types.d.ts

@@ -166,12 +166,12 @@ export type TPopoverProps = TPopoverBaseProps & TAriaRoleRequired & ({
  *
  * - `'none'` (default): popover sizes to its content, ignoring the anchor width.
  * - `'match-anchor'`: popover matches the anchor element's width exactly
- *   via CSS `anchor-size(width)`. Falls back to a one-off measurement
- *   of `anchorRef.current.offsetWidth` when CSS Anchor Positioning
- *   is not supported.
+ *   via CSS `inline-size: anchor-size(self-inline)`. Falls back to a
+ *   one-off measurement of `anchorRef.current.offsetWidth` when CSS
+ *   Anchor Positioning is not supported.
  * - `'min-anchor'`: popover is at least as wide as the anchor, but
  *   can grow wider if content requires it. Uses
- *   `min-inline-size: anchor-size(width)`. Falls back to a one-off
+ *   `min-inline-size: anchor-size(self-inline)`. Falls back to a one-off
  *   measurement of the anchor's width.
  */
 export type TWidthFromAnchorMode = 'none' | 'match-anchor' | 'min-anchor';

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "4.2.3",
+	"version": "4.2.4",
 	"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",