@atlaskit/top-layer 4.4.5 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,46 @@
 # @atlaskit/top-layer
 
+## 5.0.0
+
+### Major Changes
+
+- [`a7ec100f7d560`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/a7ec100f7d560) -
+  **Breaking:** `useAnchorPosition`, `useAnchorPositionAtPoint` and `useWidthFromAnchor` are
+  replaced by `useAnchoredPopover` and `useAnchoredPopoverAtPoint`, which own positioning and
+  anchor-relative sizing together. The `./use-anchor-position`, `./use-anchor-position-at-point` and
+  `./use-width-from-anchor` entry points are removed with no aliases; `./use-anchored-popover` and
+  `./use-anchored-popover-at-point` are added. Every consumer in the monorepo is migrated: the
+  `platform/packages/design-system` components, and kitsune's idea-select menu portal.
+
+  ```tsx
+  import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
+
+  useAnchoredPopover({
+  	anchorRef: triggerRef,
+  	popoverRef,
+  	placement,
+  	isOpen,
+  	// `useWidthFromAnchor`'s `mode`, now per axis:
+  	// 'content' | 'match-anchor' | 'min-anchor' | 'max-available'
+  	inlineSize: 'match-anchor',
+  	blockSize: 'max-available',
+  });
+  ```
+
+  `useAnchoredPopoverAtPoint` takes `getPoint: () => { x, y } | null` in place of `anchorRef`. Both
+  axes are now always capped to the viewport, and asking either axis to fit also applies a minimum
+  size of up to 150px along the placement axis, so the popover flips to a roomier side rather than
+  shrinking in place. Rationale and rejected alternatives: `notes/decisions/fit-available-space.md`.
+
+  The `anchor-name` the hook mints is still `--anchor-{useId()}`. A host that hydrates several React
+  roots from the same markup must give each a distinct `identifierPrefix`, as it already must for
+  every other id the design system mints; the hook's JSDoc now says so.
+
+### Patch Changes
+
+- [`50733a142e6d4`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/50733a142e6d4) -
+  Narrow the `aria-haspopup` type returned by `getAriaForTrigger` to the supplied popover role.
+
 ## 4.4.5
 
 ### Patch Changes

package/README.md

@@ -8,7 +8,8 @@ Low-level top-layer primitives using the native
 
 The primary primitive: a `<div>` with the `popover` attribute, plus a small lifecycle (animations,
 role-based focus management, light-dismiss, nested-focus restoration). It does **not** know about
-placement — compose it with the `useAnchorPosition` hook when you need anchor-positioned content.
+placement or size — compose it with the `useAnchoredPopover` hook when you need anchor-positioned
+content.
 
 ```tsx
 import { useRef } from 'react';
@@ -16,17 +17,18 @@ import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
 import { Popover } from '@atlaskit/top-layer/popover';
 import { PopoverSurface } from '@atlaskit/top-layer/popover-surface';
 import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
-import { useAnchorPosition } from '@atlaskit/top-layer/use-anchor-position';
+import { useAnchoredPopover } from '@atlaskit/top-layer/use-anchored-popover';
 
 function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void }) {
 	const triggerRef = useRef<HTMLButtonElement>(null);
 	const popoverRef = useRef<HTMLDivElement>(null);
 	const popoverId = usePopoverId();
 
-	useAnchorPosition({
+	useAnchoredPopover({
 		anchorRef: triggerRef,
 		popoverRef,
 		placement: { axis: 'block', edge: 'end', align: 'start' },
+		isOpen,
 	});
 
 	return (
@@ -59,7 +61,14 @@ function MyPopup({ isOpen, onClose }: { isOpen: boolean; onClose: () => void })
 - For default overlay styling (background, shadow, border-radius), wrap content in `PopoverSurface`
   from `@atlaskit/top-layer/popover-surface`.
 - For trigger-less or custom-positioned UI (flag, tooltip, react-select menu portal), use `Popover`
-  on its own without `useAnchorPosition`.
+  on its own without `useAnchoredPopover`, or pass `isEnabled: false` to turn positioning off.
+- `useAnchoredPopover` also owns anchor-relative sizing via `inlineSize` / `blockSize`
+  (`'content' | 'match-anchor' | 'min-anchor' | 'max-available'`, both defaulting to `'content'`). A
+  viewport cap is written on both axes whatever you pass, and only a placement-axis minimum can beat
+  it. A `'content'` inline axis is the content's natural width, so a popover too wide for the space
+  beside its anchor slides to a roomier side rather than wrapping; `shouldPreserveInlineSize` opts
+  an element you own and have styled out of that write. See the hook's JSDoc and
+  [`notes/decisions/fit-available-space.md`](notes/decisions/fit-available-space.md).
 
 ## Dialog
 

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

@@ -28,9 +28,11 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
 //
 // KEEP IN SYNC with the identical `surfaceResetStyles` in `popover/popover.tsx`
 // (ADS forbids sharing styles across files, so it is co-located and duplicated).
+// The `satisfies` check below fails the build if either copy drifts.
 var surfaceResetStyles = {
   root: "_lcxv1wug _o5724jg8 _1nmz4jg8 _1i4q4jg8 _y3gnv2br _azhwidpf _1p1dglyw"
 };
+true;
 var dialogStyles = {
   root: "_19itglyw _19pk1wug _2hwx1wug _otyr1wug _18u01wug _1q51ze3t _y4tize3t _85i5ze3t _bozgze3t _p12fglyw _c71lglyw _bfhk1j28",
   motion: "_k8m011k7 _1oeci9qs _1s9z1a5r _1o511hrf _bl8aglyw _156y147i",

package/dist/cjs/entry-points/use-popover-id.js

@@ -6,18 +6,13 @@ Object.defineProperty(exports, "__esModule", {
 exports.usePopoverId = usePopoverId;
 var _useId = require("@atlaskit/ds-lib/use-id");
 /**
- * Returns a stable HTML `id` used to wire a trigger element to its popover
- * via ARIA (`aria-controls`) and the Popover API (`popovertarget`).
+ * A stable `id` for wiring a trigger to its popover: the popover's `id`, and the
+ * trigger's matching `aria-controls` / `popovertarget`.
  *
- * The returned value is intended for the `id` attribute on the popover and
- * for the matching `aria-controls` / `popovertarget` references on the
- * trigger. It is NOT a CSS `anchor-name` value: CSS anchor positioning is
- * handled internally by `useAnchorPosition`, which mints and applies its
- * own `anchor-name` on the trigger element.
+ * NOT a CSS `anchor-name` - `useAnchoredPopover` mints and writes its own.
  */
 function usePopoverId() {
-  // `@atlaskit/ds-lib/use-id` already strips characters that React's
-  // `useId` produces (`:`, `«`, `»`) which are invalid in HTML ID
-  // tokens. The `popover-` prefix is purely for DOM debug clarity.
+  // `@atlaskit/ds-lib/use-id`, not React's `useId`: React's output contains
+  // `:`, `«` and `»`, which are invalid in an HTML id token.
   return "popover-".concat((0, _useId.useId)());
 }

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

@@ -0,0 +1,86 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.applyAnchorPositioning = applyAnchorPositioning;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
+var _setStyle = require("../set-style");
+var _crossAxisShiftMargins = require("./cross-axis-shift-margins");
+var _edgeMargin = require("./edge-margin");
+var _fitMargins = require("./fit-margins");
+var _getExistingAnchorName = require("./get-existing-anchor-name");
+var _placementToPositionArea = require("./placement-to-position-area");
+var _placementToTryFallbacks = require("./placement-to-try-fallbacks");
+/**
+ * The CSS Anchor Positioning path: `position-anchor`, `position-area`,
+ * `position-try-fallbacks` and the gap / shift margins, all declared on the
+ * popover so the browser owns placement and flipping. The twin of
+ * `../javascript-fallback/apply-javascript-fallback-positioning`.
+ */
+
+/**
+ * Returns the cleanup.
+ */
+function applyAnchorPositioning(_ref) {
+  var anchor = _ref.anchor,
+    popover = _ref.popover,
+    placement = _ref.placement,
+    sizeStyles = _ref.sizeStyles,
+    isFitting = _ref.isFitting,
+    fallbackAnchorName = _ref.fallbackAnchorName;
+  // Reuse rather than mint: another popover may already be anchored to it, or a
+  // CONSUMER may have set it on their own element, as `post-office` does.
+  var existingAnchorName = (0, _getExistingAnchorName.getExistingAnchorName)(anchor);
+  var anchorName = existingAnchorName !== null && existingAnchorName !== void 0 ? existingAnchorName : fallbackAnchorName;
+  var gap = (0, _edgeMargin.edgeMargin)({
+    placement: placement,
+    offset: placement.offset.gap
+  });
+  var crossAxisShift = (0, _crossAxisShiftMargins.crossAxisShiftMargins)({
+    placement: placement,
+    crossAxisShiftCssValue: placement.offset.crossAxisShift.value,
+    direction: placement.offset.crossAxisShift.direction
+  });
+  var popoverStyles = [{
+    property: 'position-anchor',
+    value: anchorName
+  }, {
+    property: 'position-area',
+    value: (0, _placementToPositionArea.placementToPositionArea)({
+      placement: placement
+    })
+  }, {
+    property: 'position-try-fallbacks',
+    value: (0, _placementToTryFallbacks.placementToTryFallbacks)({
+      placement: placement
+    })
+  },
+  // Reset browser default popover positioning that conflicts
+  // with anchor positioning (UA: `inset: 0; margin: auto;`)
+  {
+    property: 'margin',
+    value: '0'
+  }, {
+    property: 'inset',
+    value: 'auto'
+  }, gap].concat((0, _toConsumableArray2.default)(isFitting ? (0, _fitMargins.getFitMarginDeclarations)({
+    placement: placement,
+    crossAxisShiftMargins: crossAxisShift
+  }) : crossAxisShift), (0, _toConsumableArray2.default)(sizeStyles));
+
+  // Anchor names are never cleaned up: multiple popovers can share an anchor,
+  // and even with reference counting an async React update could remove the name
+  // while something else still uses it. See
+  // `notes/decisions/anchor-name-lifetime.md`. Only written when minted: a name
+  // from a stylesheet may be a list, which an inline copy of its first entry
+  // would collapse.
+  if (existingAnchorName === null) {
+    anchor.style.setProperty('anchor-name', anchorName);
+  }
+  return (0, _setStyle.setStyle)({
+    element: popover,
+    styles: popoverStyles
+  });
+}

package/dist/cjs/internal/anchor-positioning/cross-axis-shift-margins.js

@@ -0,0 +1,34 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.crossAxisShiftMargins = crossAxisShiftMargins;
+/**
+ * The cross-axis shift, written antisymmetrically on BOTH cross-axis sides rather
+ * than as one margin. Do not collapse it to one side: a single margin widens the
+ * margin box, so `anchor-center` displaces the border box by only half the value,
+ * a `<position-area>` fallback sliding across the cross axis drops it entirely,
+ * and the widened box changes where the popover is judged to overflow.
+ *
+ * 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 crossAxisShiftMargins(_ref) {
+  var placement = _ref.placement,
+    crossAxisShiftCssValue = _ref.crossAxisShiftCssValue,
+    direction = _ref.direction;
+  var crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  // `calc()` rather than JavaScript math, so opaque values such as design tokens
+  // negate correctly.
+  var negated = "calc(-1 * ".concat(crossAxisShiftCssValue, ")");
+  var isForwards = direction === 'forwards';
+  return [{
+    property: "margin-".concat(crossAxis, "-start"),
+    value: isForwards ? crossAxisShiftCssValue : negated
+  }, {
+    property: "margin-".concat(crossAxis, "-end"),
+    value: isForwards ? negated : crossAxisShiftCssValue
+  }];
+}

package/dist/cjs/internal/anchor-positioning/edge-margin.js

@@ -0,0 +1,21 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.edgeMargin = edgeMargin;
+/**
+ * The margin that creates the gap between the popover and its anchor.
+ */
+function edgeMargin(_ref) {
+  var placement = _ref.placement,
+    offset = _ref.offset;
+  var axis = placement.axis,
+    edge = placement.edge;
+  // The side FACING the anchor is always opposite the placement edge.
+  var anchorFacingEdge = edge === 'end' ? 'start' : 'end';
+  return {
+    property: "margin-".concat(axis, "-").concat(anchorFacingEdge),
+    value: offset
+  };
+}

package/dist/cjs/internal/anchor-positioning/fit-margins.js

@@ -0,0 +1,77 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getFitMarginDeclarations = getFitMarginDeclarations;
+var _toConsumableArray2 = _interopRequireDefault(require("@babel/runtime/helpers/toConsumableArray"));
+var _anchoredPopoverSize = require("../anchored-popover-size");
+/**
+ * Every logical margin property the fit recipe can write. Declared here and
+ * imported by `edge-margin.tsx` and `cross-axis-shift-margins.tsx`: two
+ * structurally identical declarations are interchangeable to the compiler, so a
+ * divergence would surface only as a silently-ignored property name at
+ * `setStyle`.
+ */
+
+/**
+ * The cross-axis sides that face the viewport rather than the anchor, and so take
+ * the reserved padding.
+ *
+ * A `span-*` cell aligns the popover's MARGIN box to the anchor's edge, so padding
+ * on the anchor-facing side does not reserve space at the viewport: it insets the
+ * border box from the edge the consumer asked it to line up with. A centred
+ * popover has no anchor-facing side, and padding both keeps the shift pair
+ * antisymmetric so `anchor-center` still centres.
+ *
+ * Known cost: the slide fallbacks do not swap the inline margins the way
+ * `flip-inline` does, so a slid popover keeps its padding on the anchor side (or,
+ * re-centred, sits 2.5px off centre). Alignment in the requested position wins.
+ */
+function viewportFacingCrossAxisSides(_ref) {
+  var align = _ref.align;
+  if (align === 'center') {
+    return ['start', 'end'];
+  }
+  // `align: 'start'` sits on the anchor's start edge and expands toward end.
+  return [align === 'start' ? 'end' : 'start'];
+}
+
+/**
+ * The margin half of the fit recipe. The caps reserve the viewport padding by
+ * subtracting it, but nothing makes the reservation land on the viewport side, so
+ * a capped popover packs flush against the edge it slid or flipped to.
+ *
+ * The padding buys visual clearance and nothing else: at the cap the margin box
+ * is exactly `100%` of the cell, so these margins never make
+ * `position-try-fallbacks` fire. Only the unclamped placement-axis floor does
+ * that; see `getPlacementAxisFloor`.
+ *
+ * The cross-axis sides are composed, not overwritten: they already carry the
+ * antisymmetric `crossAxisShift` pair.
+ */
+function getFitMarginDeclarations(_ref2) {
+  var placement = _ref2.placement,
+    crossAxisShiftMargins = _ref2.crossAxisShiftMargins;
+  var crossAxis = placement.axis === 'block' ? 'inline' : 'block';
+  var paddedProperties = new Set(viewportFacingCrossAxisSides({
+    align: placement.align
+  }).map(function (side) {
+    return "margin-".concat(crossAxis, "-").concat(side);
+  }));
+  return [{
+    property: "margin-".concat(placement.axis, "-").concat(placement.edge),
+    value: _anchoredPopoverSize.VIEWPORT_PADDING
+  }].concat((0, _toConsumableArray2.default)(crossAxisShiftMargins.map(function (_ref3) {
+    var property = _ref3.property,
+      value = _ref3.value;
+    return paddedProperties.has(property) ? {
+      property: property,
+      value: "calc(".concat(value, " + ").concat(_anchoredPopoverSize.VIEWPORT_PADDING, ")")
+    } : {
+      property: property,
+      value: value
+    };
+  })));
+}

package/dist/cjs/internal/anchor-positioning/get-existing-anchor-name.js

@@ -0,0 +1,18 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getExistingAnchorName = getExistingAnchorName;
+/**
+ * The `anchor-name` an element already carries, or `null`. Computed as well as
+ * inline, so a name set from a STYLESHEET is found: a minted inline name would
+ * otherwise override it for every other rule anchored to that element.
+ * `anchor-name` is a list and `position-anchor` takes one ident, so the first
+ * name is the one to anchor to.
+ */
+function getExistingAnchorName(element) {
+  var declared = element.style.getPropertyValue('anchor-name') || getComputedStyle(element).getPropertyValue('anchor-name');
+  var first = declared.split(',')[0].trim();
+  return first !== '' && first !== 'none' ? first : null;
+}

package/dist/cjs/internal/{placement-to-position-area.js → anchor-positioning/placement-to-position-area.js}

@@ -4,9 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.placementToPositionArea = placementToPositionArea;
-var _resolvePlacement2 = require("./resolve-placement");
 /**
- * Resolves placement options to CSS `position-area` syntax.
+ * Resolves a placement to CSS `position-area` syntax.
  *
  * The `align` field represents the *visual* alignment:
  * - `align: 'start'` means "aligned to the trigger's start edge" (left in LTR for block axis)
@@ -17,19 +16,20 @@ var _resolvePlacement2 = require("./resolve-placement");
  * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
  * This function handles the inversion internally.
  *
+ * Takes the RESOLVED placement, which the hook threads through positioning,
+ * sizing and margins alike, so nothing here can disagree with them.
+ *
  * @example
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'center' } }) // → 'block-end'
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'start' } }) // → 'block-end span-inline-end'
- * placementToPositionArea({ placement: { axis: 'block', edge: 'end', align: 'end' } })   // → 'block-end span-inline-start'
+ * // For a `block-end` placement, by `align`:
+ * // 'center' → 'block-end'
+ * // 'start'  → 'block-end span-inline-end'
+ * // 'end'    → 'block-end span-inline-start'
  */
 function placementToPositionArea(_ref) {
   var placement = _ref.placement;
-  var _resolvePlacement = (0, _resolvePlacement2.resolvePlacement)({
-      placement: placement
-    }),
-    axis = _resolvePlacement.axis,
-    edge = _resolvePlacement.edge,
-    align = _resolvePlacement.align;
+  var axis = placement.axis,
+    edge = placement.edge,
+    align = placement.align;
   var edgeValue = "".concat(axis, "-").concat(edge);
   if (align === 'center') {
     return edgeValue;

package/dist/cjs/internal/anchor-positioning/placement-to-try-fallbacks.js

@@ -0,0 +1,95 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.placementToTryFallbacks = placementToTryFallbacks;
+/**
+ * The placement axis joined to its edge, e.g. `block-end`.
+ */
+
+/**
+ * The cells to slide to along one edge, on the cross axis.
+ *
+ * A try option is only worth listing if its margin box can fit where an earlier
+ * one did not, and two options over the SAME cell have the same margin box and
+ * the same fit result. That rules out three cells for an aligned placement: the
+ * near span on the requested edge IS the base position-area, and on the opposite
+ * edge the near and far spans are where `flip-{A}` and the diagonal flip land.
+ *
+ * A centred placement has no near or far, so it slides to both spans on both
+ * edges.
+ */
+function slideOnEdge(_ref) {
+  var align = _ref.align,
+    edgeKey = _ref.edgeKey,
+    crossAxis = _ref.crossAxis,
+    isOppositeEdge = _ref.isOppositeEdge;
+  if (align === 'center') {
+    return ["".concat(edgeKey, " span-").concat(crossAxis, "-end"), "".concat(edgeKey, " span-").concat(crossAxis, "-start")];
+  }
+  if (isOppositeEdge) {
+    return [edgeKey];
+  }
+  // For `align: 'start'` the popover expands toward `end`, so the far span is
+  // `start`; `align: 'end'` mirrors this.
+  var far = align === 'start' ? 'start' : 'end';
+  return [edgeKey, "".concat(edgeKey, " span-").concat(crossAxis, "-").concat(far)];
+}
+function flipDiagonally(_ref2) {
+  var axis = _ref2.axis;
+  var flipOnMainAxis = axis === 'block' ? 'flip-block' : 'flip-inline';
+  var flipToCrossAxis = axis === 'block' ? 'flip-inline' : 'flip-block';
+  return "".concat(flipOnMainAxis, " ").concat(flipToCrossAxis);
+}
+
+/**
+ * Returns the `position-try-fallbacks` value for a RESOLVED placement. The
+ * browser tries the entries in order and uses the first one whose margin box
+ * fits, so an entry over a cell already tried can never be chosen; `slideOnEdge`
+ * explains which ones those are.
+ *
+ * Centred: slide along the requested edge to either span, flip to the opposite
+ * edge, then slide along that edge to either span.
+ *
+ * Start / end aligned: slide along the requested edge (re-centred, then the far
+ * span), flip to the opposite edge keeping the alignment, flip on the diagonal
+ * into the opposite corner, then re-centre on the opposite edge. The diagonal is
+ * the clean escape when the popover would land off screen on both axes: a flip
+ * keyword carries the gap and shift margins across, where a position-area slide
+ * leaves them on the original sides.
+ *
+ * @example
+ * // Centred on the block-end edge (the default placement):
+ * placementToTryFallbacks({ placement: resolvePlacement({ placement: {} }) });
+ * // => 'block-end span-inline-end, block-end span-inline-start, flip-block,
+ * //     block-start span-inline-end, block-start span-inline-start'
+ *
+ * // Start-aligned on the block-end edge:
+ * placementToTryFallbacks({ placement: resolvePlacement({ placement: { align: 'start' } }) });
+ * // => 'block-end, block-end span-inline-start, flip-block, flip-block flip-inline, block-start'
+ */
+function placementToTryFallbacks(_ref3) {
+  var placement = _ref3.placement;
+  var axis = placement.axis,
+    edge = placement.edge,
+    align = placement.align;
+  var crossAxis = axis === 'block' ? 'inline' : 'block';
+  var flippedEdge = edge === 'start' ? 'end' : 'start';
+  var sameEdgeArea = "".concat(axis, "-").concat(edge);
+  var oppositeEdgeArea = "".concat(axis, "-").concat(flippedEdge);
+  var flipOnMainAxis = axis === 'block' ? 'flip-block' : 'flip-inline';
+  return [slideOnEdge({
+    align: align,
+    edgeKey: sameEdgeArea,
+    crossAxis: crossAxis,
+    isOppositeEdge: false
+  }), flipOnMainAxis, align !== 'center' ? flipDiagonally({
+    axis: axis
+  }) : null, slideOnEdge({
+    align: align,
+    edgeKey: oppositeEdgeArea,
+    crossAxis: crossAxis,
+    isOppositeEdge: true
+  })].filter(Boolean).flat().join(', ');
+}