@atlaskit/top-layer 0.12.1 → 0.13.0

package/dist/es2019/internal/role-types.js

@@ -1,92 +0,0 @@
-/**
- * Valid values for the `aria-haspopup` attribute.
- *
- * Derived from the HTML spec - maps popover roles to what the trigger
- * announces. `undefined` means the attribute is omitted entirely (used for
- * non-popup roles like `tooltip`/`status`/`alert`/`note`/`log` where
- * `aria-haspopup` would be misleading).
- *
- * `true` is intentionally NOT in the union - the runtime only ever produces
- * the explicit string forms, so widening the type would invite consumers to
- * pass `true` and get an `aria-haspopup="true"` serialisation that the
- * runtime no longer emits.
- */
-
-/**
- * Roles that require an accessible name (`label` or `labelledBy`) per WCAG 4.1.2.
- * Without a name, assistive technology cannot identify these landmarks.
- */
-
-/**
- * Roles where the accessible name is derived from content or provided externally
- * (e.g. a combobox labels its listbox, tooltip content IS the accessible name).
- */
-
-// ── Shared ARIA role discrimination types ──
-//
-// These encode the WCAG 4.1.2 constraint: roles like `dialog`, `alertdialog`,
-// and `menu` MUST have an accessible name (either `label` or `labelledBy`).
-// TypeScript enforces this at compile time via discriminated unions.
-
-/**
- * ARIA role props where a role is always required.
- *
- * Used by `TPopupContentProps`. Popup content must always declare
- * its role so assistive technology can identify the layer.
- */
-
-/**
- * ARIA role props where a role is optional.
- *
- * Used by `TPopoverProps`. The low-level primitive allows omitting
- * the role for cases where it is set externally or not needed.
- */
-
-/**
- * Maps a popover content role to the correct `aria-haspopup` value
- * for its trigger element.
- *
- * Returns `undefined` for roles that are not popups in the ARIA sense
- * (`tooltip`, `note`, `status`, `alert`, `log`). Triggers for those roles
- * should not announce a popup at all - emitting `aria-haspopup="dialog"`
- * on a tooltip trigger would mislead assistive technology.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function roleToAriaHasPopup({
-  role
-}) {
-  if (role === 'menu') {
-    return 'menu';
-  }
-  if (role === 'listbox') {
-    return 'listbox';
-  }
-  if (role === 'tree') {
-    return 'tree';
-  }
-  if (role === 'grid') {
-    return 'grid';
-  }
-  if (role === 'dialog' || role === 'alertdialog') {
-    return 'dialog';
-  }
-  // Non-popup roles (tooltip, note, status, alert, log) and the
-  // no-role case: omit `aria-haspopup` entirely. React drops the
-  // attribute when the value is `undefined`.
-  return undefined;
-}
-const rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
-
-/**
- * Returns `true` when the given popover role moves focus into the popover
- * on open, and `false` otherwise (including when `role` is `undefined`).
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export function shouldFocusIntoPopover({
-  role
-}) {
-  if (!role) {
-    return false;
-  }
-  return rolesThatMoveFocus.has(role);
-}

package/dist/es2019/internal/should-focus-into-popover.js

@@ -0,0 +1,14 @@
+const rolesThatMoveFocus = new Set(['dialog', 'alertdialog', 'menu', 'listbox', 'tree', 'grid']);
+
+/**
+ * Returns `true` when the given popover role moves focus into the popover
+ * on open, and `false` otherwise (including when `role` is `undefined`).
+ */
+export function shouldFocusIntoPopover({
+  role
+}) {
+  if (!role) {
+    return false;
+  }
+  return rolesThatMoveFocus.has(role);
+}

package/dist/es2019/internal/slot.js

@@ -21,14 +21,14 @@ function isSlotChild(child) {
  * Merges props (including ref) onto a single React element child.
  *
  * A safer alternative to raw `cloneElement` that:
- * 1. Guards with `isValidElement` — non-element children (strings,
+ * 1. Guards with `isValidElement` - non-element children (strings,
  *    fragments, null) are returned as-is instead of crashing.
  * 2. Merges refs via `mergeRefs` so both the caller's ref and the
  *    child's existing ref are honoured.
  * 3. Spreads any additional props (ARIA attributes, event handlers, etc.)
  *    onto the child element.
  *
- * Event handlers (e.g. `onClick`) are **not** auto-merged — the caller's
+ * Event handlers (e.g. `onClick`) are **not** auto-merged - the caller's
  * handler replaces the child's. Compose handlers before passing them in.
  *
  * @example
@@ -43,7 +43,7 @@ export const Slot = /*#__PURE__*/forwardRef(function Slot(slotProps, ref) {
     children: rawChildren,
     ...props
   } = slotProps;
-  // `SlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
+  // `TSlotProps` intersects `Record<string, unknown>`, so `children` is typed as `unknown`.
   const children = rawChildren;
   if (!isSlotChild(children)) {
     return children;

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

@@ -0,0 +1,122 @@
+import { useLayoutEffect, useRef } from 'react';
+import { useAnchorPosition } from './use-anchor-position';
+
+/**
+ * A point in viewport coordinates (CSS pixels) at which the synthetic
+ * anchor should be placed.
+ *
+ * Axis-named (`x`/`y`) rather than edge-named (`left`/`top`) so the
+ * shape is unambiguous in RTL writing modes — there is no ambiguity
+ * about whether a coordinate is logical (`inline-start`/`block-start`)
+ * or physical (`left`/`top`). Viewport coordinates are always
+ * physical, so we name them with the physical axis labels.
+ */
+
+/**
+ * Styles the synthetic anchor as an invisible, zero-size point.
+ * Dynamic `inset-*` overrides are written by the positioning effect.
+ *
+ * Uses `Object.assign` rather than Compiled CSS (element is outside the React tree)
+ * or the internal `setStyle` helper (we own this element entirely — it is created
+ * and removed by this hook — so the snapshot/restore semantics `setStyle`
+ * provides for caller-owned elements would be dead work here).
+ */
+function applyStaticAnchorStyles(el) {
+  Object.assign(el.style, {
+    position: 'fixed',
+    // `top`/`left` rather than `inset-block-start`/`inset-inline-start`
+    // for consistency with the dynamic positioning effect below, which
+    // uses physical properties (see comment there for the rationale).
+    top: '0',
+    left: '0',
+    // Zero size — placement decides which side the popover sits on.
+    width: '0',
+    height: '0',
+    // Prevent the overlay from intercepting pointer events.
+    pointerEvents: 'none'
+  });
+}
+
+// `useAnchorPosition` requires a real DOM element. When the caller only
+// has a viewport coordinate (e.g. cursor at hover time), this hook
+// manages a hidden `<div>` at that point and delegates the rest.
+//
+// The `<div>` is appended directly to `document.body` to escape any
+// transformed ancestor, which would otherwise break `position: fixed`
+// viewport-relative resolution.
+
+/**
+ * Positions a popover at a consumer-supplied viewport coordinate using a
+ * hidden synthetic anchor.
+ *
+ * @example
+ * ```tsx
+ * function PointPositionedPopover({ popoverRef, placement, mousePos }) {
+ *   useAnchorPositionAtPoint({
+ *     popoverRef,
+ *     placement,
+ *     isEnabled: Boolean(mousePos),
+ *     getPoint: () => {
+ *       if (!mousePos) return null;
+ *       return { x: mousePos.clientX, y: mousePos.clientY };
+ *     },
+ *   });
+ *   return <Popover ref={popoverRef}>...</Popover>;
+ * }
+ * ```
+ */
+export function useAnchorPositionAtPoint({
+  popoverRef,
+  placement,
+  getPoint,
+  isEnabled = true
+}) {
+  const syntheticAnchorRef = useRef(null);
+
+  // `getPoint` is kept in a ref so the layout effect can call the
+  // latest version without listing it as a dep — that would re-fire
+  // on every render and re-latch the point.
+  const getPointRef = useRef(getPoint);
+  getPointRef.current = getPoint;
+
+  // Lazy element creation: the `<div>` is only created when both
+  // `isEnabled` is true AND `getPoint()` returns a non-null point.
+  // `useLayoutEffect` ensures the element exists before the inner
+  // `useAnchorPosition` (also a layout effect) reads the ref.
+  useLayoutEffect(() => {
+    if (!isEnabled) {
+      return;
+    }
+    const point = getPointRef.current();
+    if (!point) {
+      return;
+    }
+    const anchor = document.createElement('div');
+    anchor.setAttribute('aria-hidden', 'true');
+    applyStaticAnchorStyles(anchor);
+    // `point.x`/`y` are physical viewport coordinates (from
+    // `MouseEvent.clientX/Y`), so map directly onto physical
+    // `left`/`top`. This is RTL-safe: `position: fixed` + physical
+    // insets is direction-independent. Using logical
+    // `inset-inline-start` would need `viewportWidth - point.x` in
+    // RTL to land at the same physical pixel.
+    anchor.style.top = `${point.y}px`;
+    anchor.style.left = `${point.x}px`;
+    document.body.appendChild(anchor);
+    syntheticAnchorRef.current = anchor;
+    return function cleanup() {
+      anchor.remove();
+      syntheticAnchorRef.current = null;
+    };
+  }, [isEnabled]);
+
+  // Mirror `isEnabled` so both hooks stay in sync — when disabled,
+  // neither this hook nor the inner one touches the popover, leaving
+  // any other positioning the consumer has set up free to take effect.
+  useAnchorPosition({
+    anchorRef: syntheticAnchorRef,
+    popoverRef,
+    placement,
+    isEnabled
+  });
+}

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

@@ -28,13 +28,13 @@ import { setStyle } from './set-style';
 // from `./resolve-placement` so search-and-jump lands at the source of truth.
 
 /**
- * Module-scope no-op `ResizeObserver` used in non-DOM jest environments where
+ * Module-scope no-op `ResizeObserver` stub used in non-DOM jest environments where
  * `ResizeObserver` is `undefined`. Hoisted out of the effect to avoid
- * allocating a new class declaration on every run.
+ * re-allocating on every run.
  */
-const NoopResizeObserver = class {
-  observe() {}
-  unobserve() {}
+const noopResizeObserver = {
+  observe() {},
+  unobserve() {},
   disconnect() {}
 };
 
@@ -197,18 +197,21 @@ function useStablePlacement(placement) {
  * comparison is used internally so re-runs are skipped when the resolved
  * placement shape is unchanged.
  */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
 export function useAnchorPosition({
   anchorRef,
   popoverRef,
   placement = {},
-  forceFallbackPositioning = false
+  forceFallbackPositioning = false,
+  isEnabled = true
 }) {
   const id = useId();
   // Stabilize `placement` object so the same object literal
   // value returns an object with the same reference
   const stablePlacement = useStablePlacement(placement);
   useLayoutEffect(() => {
+    if (!isEnabled) {
+      return;
+    }
     const trigger = anchorRef.current;
     const popover = popoverRef.current;
     if (!trigger || !popover) {
@@ -329,7 +332,7 @@ export function useAnchorPosition({
       return undoPositioning;
     }
 
-    // ── JS fallback ──
+    // JS fallback
     // The popover is already in the browser's top layer via popover="auto",
     // so it does not need position:fixed. We only reset the UA defaults
     // (inset: 0; margin: auto) and set top/left based on measurements.
@@ -399,20 +402,17 @@ export function useAnchorPosition({
     // Self-disconnects after one valid measurement; ongoing
     // scroll/resize is handled by the window listeners below.
     // `ResizeObserver` is missing in some non-DOM jest environments
-    // (e.g. post-office's `node` environment). Fall back to a no-op
-    // observer there. The scroll/resize listeners below still keep
-    // the popover positioned in the rare case the consumer also
-    // polyfilled `showPopover` but not `ResizeObserver`. Real
-    // browsers always have it. The `NoopResizeObserver` class is
-    // hoisted to module scope (see top of file) so we do not allocate
-    // a new constructor on every effect run.
-    const ResizeObserverImpl = typeof ResizeObserver !== 'undefined' ? ResizeObserver : NoopResizeObserver;
-    const resizeObserver = new ResizeObserverImpl(() => {
+    // (e.g. post-office's `node` environment). Fall back to the
+    // module-scope `noopResizeObserver` stub there. The scroll/resize
+    // listeners below still keep the popover positioned in the rare
+    // case the consumer also polyfilled `showPopover` but not
+    // `ResizeObserver`. Real browsers always have it.
+    const resizeObserver = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(() => {
       if (popover.offsetWidth > 0 && popover.offsetHeight > 0) {
         update();
         resizeObserver.disconnect();
       }
-    });
+    }) : noopResizeObserver;
 
     // If the popover is already open by the time this effect runs (for
     // example, the parent `useAnchorPosition` effect runs after the child
@@ -459,5 +459,5 @@ export function useAnchorPosition({
       popover.style.removeProperty('opacity');
     });
     return undoPositioning;
-  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, id]);
+  }, [anchorRef, popoverRef, stablePlacement, forceFallbackPositioning, isEnabled, id]);
 }

package/dist/es2019/internal/use-animated-visibility.js

@@ -7,19 +7,19 @@ import { usePresetStyles } from './use-preset-styles';
  *
  * Used by both `Popover` and `Dialog` to share the same animation lifecycle
  * logic. Those components own their own show/hide mechanisms (showPopover /
- * hidePopover vs showModal / close) and event handling — this hook only
+ * hidePopover vs showModal / close) and event handling - this hook only
  * manages the relationship between `isOpen` and when children are rendered.
  *
  * ## Problem
  *
  * We want to delay the unmount of children until a CSS exit transition has
  * finished playing. If we unmount children the moment `isOpen` becomes
- * `false`, the exit animation is never visible — the content just disappears.
+ * `false`, the exit animation is never visible - the content just disappears.
  *
  * ## How it works
  *
  * `showChildren` tracks whether the consumer's children should be in the DOM.
- * It does not mirror `isOpen` exactly — it intentionally lags behind during
+ * It does not mirror `isOpen` exactly - it intentionally lags behind during
  * exit animations:
  *
  * ```
@@ -56,12 +56,12 @@ export function useAnimatedVisibility({
   // or the user has enabled the "prefers reduced motion" OS setting.
   const willAnimate = Boolean(animate) && !prefersReducedMotion();
 
-  // ── showChildren state ──
+  // showChildren state
   //
   // This is the core of the hook. `showChildren` controls whether the
   // consumer's children are in the DOM. The two `if` blocks below are
   // intentionally written as synchronous state updates during render
-  // (React supports this pattern — setState during render is treated as
+  // (React supports this pattern - setState during render is treated as
   // a synchronous re-render before the browser paints).
   //
   // Mount path:  isOpen went true but showChildren is still false → mount.
@@ -85,7 +85,7 @@ export function useAnimatedVisibility({
   const onExitFinishRef = useRef(onExitFinish);
   onExitFinishRef.current = onExitFinish;
 
-  // ── Animated entry effect ──
+  // Animated entry effect
   //
   // Fires `onEnterFinish` after the entry transition completes.
   // When there is no animation, fires it immediately via a separate effect.
@@ -134,7 +134,7 @@ export function useAnimatedVisibility({
     };
   }, [isOpen, showChildren, willAnimate, preset === null || preset === void 0 ? void 0 : preset.enterDurationMs, elementRef]);
 
-  // ── Non-animated entry callback ──
+  // Non-animated entry callback
   //
   // When there is no animation, fire `onEnterFinish` immediately on mount and after `isOpen` goes false->true.
   // The initial value is false to make sure it fires on mount if the current `isOpen` is true.
@@ -148,7 +148,7 @@ export function useAnimatedVisibility({
     }
   }, [isOpen, willAnimate]);
 
-  // ── Animated exit effect ──
+  // Animated exit effect
   //
   // Runs when all three conditions are true:
   //   • `isOpen` is false  (consumer wants to close)
@@ -211,10 +211,10 @@ export function useAnimatedVisibility({
     };
   }, [isOpen, showChildren, willAnimate, preset === null || preset === void 0 ? void 0 : preset.exitDurationMs, elementRef]);
 
-  // ── Non-animated exit callback ──
+  // Non-animated exit callback
   //
   // When there is no animation, children unmount synchronously (handled
-  // by the `if` block above). But `onExitFinish` still needs to fire —
+  // by the `if` block above). But `onExitFinish` still needs to fire -
   // we do that in a follow-up effect so the consumer can react to it.
   //
   // Uses a previous-value ref (`wasOpenRef`) to detect the exact

package/dist/es2019/internal/use-animation-preset.js

@@ -3,7 +3,7 @@ import { ensurePresetStyles } from './ensure-preset-styles';
 /**
  * Normalizes the `animate` prop to a preset (or null) and ensures its CSS
  * is injected once into document.head. Used by PopupContent, Popover, and
- * DialogContent so they don't duplicate this logic.
+ * DialogContent so they do not duplicate this logic.
  */
 export function useAnimationPreset(animate) {
   const preset = animate != null && animate !== false ? animate : null;

package/dist/es2019/internal/use-focus-wrap.js

@@ -1,6 +1,9 @@
 import { useEffect } from 'react';
 import { bind } from 'bind-event-listener';
-import { getFirstFocusable, getLastFocusable, getNextFocusable, isNestedLayerFocused } from '../focus/focus';
+import { getFirstFocusable } from '../focus/get-first-focusable';
+import { getLastFocusable } from '../focus/get-last-focusable';
+import { getNextFocusable } from '../focus/get-next-focusable';
+import { isNestedLayerFocused } from '../focus/is-nested-layer-focused';
 
 /**
  * Roles that require focus wrapping per WAI-ARIA APG.

package/dist/es2019/internal/use-initial-focus.js

@@ -1,5 +1,5 @@
 import { useEffect, useRef } from 'react';
-import { getFirstFocusable } from '../focus/focus';
+import { getFirstFocusable } from '../focus/get-first-focusable';
 
 /**
  * Determines the correct element to receive initial focus within a popover,

package/dist/es2019/internal/use-preset-styles.js

@@ -4,7 +4,7 @@ import { ensurePresetStyles } from './ensure-preset-styles';
  * Normalizes a preset prop to a value (or null) and ensures its CSS
  * is injected once into `document.head`.
  *
- * Works with any preset that has `{ css, name }` — animation presets
+ * Works with any preset that has `{ css, name }` - animation presets
  * (TAnimationPreset) satisfies this shape.
  */
 export function usePresetStyles({

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

@@ -4,8 +4,8 @@ import { setStyle } from './set-style';
 /**
  * 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,
+ * - `'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)
  *
@@ -31,7 +31,7 @@ export function useWidthFromAnchor({
     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
+      // `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) {
         return setStyle({
@@ -87,7 +87,7 @@ export function useWidthFromAnchor({
         });
       }
 
-      // No anchor available in JS fallback — still apply min-inline-size.
+      // No anchor available in JS fallback - still apply min-inline-size.
       return setStyle({
         el: node,
         styles: [minInlineSizeStyle]

package/dist/es2019/placement-map/index.js

@@ -1,4 +1,4 @@
-import { placementMapping } from './legacy-placements';
+import { placementMapping } from './placement-mapping';
 
 /**
  * Maps legacy Popper.js placement values to the new object-based

package/dist/es2019/placement-map/legacy-placements.js

@@ -5,103 +5,4 @@
  * to enumerate every placement (e.g. for a settings dropdown). New code
  * should use the object-based `TPlacementOptions` directly.
  */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export const LEGACY_PLACEMENTS = ['auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-center', 'top-end', 'bottom', 'bottom-start', 'bottom-center', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'];
-/**
- * The full mapping record. Internal - use `fromLegacyPlacement` from the
- * public entry-point so the offset-tuple translation is applied consistently.
- *
- * Note: `auto`, `auto-start`, `auto-end` map to `block-end` placements. This
- * is a reduction in expressiveness vs Popper.js (which picked the best
- * placement at runtime). CSS `position-try-fallbacks` flips at the edge but
- * the initial placement is fixed. Migration consumers who relied on Popper's
- * dynamic auto-flip should pick an explicit placement instead.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-export const placementMapping = {
-  top: {
-    axis: 'block',
-    edge: 'start',
-    align: 'center'
-  },
-  'top-start': {
-    axis: 'block',
-    edge: 'start',
-    align: 'start'
-  },
-  'top-center': {
-    axis: 'block',
-    edge: 'start',
-    align: 'center'
-  },
-  'top-end': {
-    axis: 'block',
-    edge: 'start',
-    align: 'end'
-  },
-  bottom: {
-    axis: 'block',
-    edge: 'end',
-    align: 'center'
-  },
-  'bottom-start': {
-    axis: 'block',
-    edge: 'end',
-    align: 'start'
-  },
-  'bottom-center': {
-    axis: 'block',
-    edge: 'end',
-    align: 'center'
-  },
-  'bottom-end': {
-    axis: 'block',
-    edge: 'end',
-    align: 'end'
-  },
-  right: {
-    axis: 'inline',
-    edge: 'end',
-    align: 'center'
-  },
-  'right-start': {
-    axis: 'inline',
-    edge: 'end',
-    align: 'start'
-  },
-  'right-end': {
-    axis: 'inline',
-    edge: 'end',
-    align: 'end'
-  },
-  left: {
-    axis: 'inline',
-    edge: 'start',
-    align: 'center'
-  },
-  'left-start': {
-    axis: 'inline',
-    edge: 'start',
-    align: 'start'
-  },
-  'left-end': {
-    axis: 'inline',
-    edge: 'start',
-    align: 'end'
-  },
-  auto: {
-    axis: 'block',
-    edge: 'end',
-    align: 'center'
-  },
-  'auto-start': {
-    axis: 'block',
-    edge: 'end',
-    align: 'start'
-  },
-  'auto-end': {
-    axis: 'block',
-    edge: 'end',
-    align: 'end'
-  }
-};
+export const LEGACY_PLACEMENTS = ['auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-center', 'top-end', 'bottom', 'bottom-start', 'bottom-center', 'bottom-end', 'right', 'right-start', 'right-end', 'left', 'left-start', 'left-end'];