@atlaskit/top-layer 0.12.2 → 0.14.0

package/dist/types-ts4.5/internal/use-anchor-position-at-point.d.ts

@@ -0,0 +1,62 @@
+import { type RefObject } from 'react';
+import { type TPlacementOptions } from './resolve-placement';
+/**
+ * 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.
+ */
+export type TAnchorPoint = {
+    x: number;
+    y: number;
+};
+/**
+ * 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 declare function useAnchorPositionAtPoint({ popoverRef, placement, getPoint, isEnabled, }: {
+    /**
+     * Element being positioned. Passed to `useAnchorPosition`.
+     */
+    popoverRef: RefObject<HTMLElement | null>;
+    /**
+     * Where the popover sits relative to the anchor.
+     */
+    placement: TPlacementOptions;
+    /**
+     * Lazy callback returning the viewport coordinate to anchor at.
+     * Called once per activation (every `isEnabled: false → true`
+     * transition); the result is latched and not re-read.
+     *
+     * Return `null` to signal "no point yet" — the hook stays in a
+     * no-DOM state so another positioning strategy can own the popover.
+     *
+     * Read from a ref, so it does not need to be memoized.
+     */
+    getPoint: () => TAnchorPoint | null;
+    /**
+     * When `false`, the hook is a no-op: no synthetic anchor is created
+     * and no positioning is applied. Defaults to `true`.
+     */
+    isEnabled?: boolean;
+}): void;

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

@@ -34,7 +34,7 @@ import { type TPlacementOptions } from '../internal/resolve-placement';
  * comparison is used internally so re-runs are skipped when the resolved
  * placement shape is unchanged.
  */
-export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, }: {
+export declare function useAnchorPosition({ anchorRef, popoverRef, placement, forceFallbackPositioning, isEnabled, }: {
     /**
      * Element to position relative to.
      */
@@ -70,4 +70,9 @@ export declare function useAnchorPosition({ anchorRef, popoverRef, placement, fo
      * behavior in any environment, including production.
      */
     forceFallbackPositioning?: boolean;
+    /**
+     * When `false`, the hook is a no-op and applies no positioning.
+     * Defaults to `true`.
+     */
+    isEnabled?: boolean;
 }): void;

package/dist/types-ts4.5/placement-map/index.d.ts

@@ -1,5 +1,5 @@
 import { type TPlacementOptions } from '../internal/resolve-placement';
-import { type TLegacyPlacement } from './legacy-placements';
+import type { TLegacyPlacement } from './legacy-placements';
 /**
  * Maps legacy Popper.js placement values to the new object-based
  * `Placement` values used by `@atlaskit/top-layer/popover`.

package/dist/types-ts4.5/placement-map/legacy-placements.d.ts

@@ -1,4 +1,3 @@
-import { type TPlacementOptions } from '../internal/resolve-placement';
 /**
  * Legacy Popper.js placement values (used by `@atlaskit/popper`,
  * `@atlaskit/popup`, `@atlaskit/tooltip`, etc.). Re-exported from
@@ -26,14 +25,3 @@ export declare const LEGACY_PLACEMENTS: readonly [
     "left-end"
 ];
 export type TLegacyPlacement = (typeof LEGACY_PLACEMENTS)[number];
-/**
- * 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.
- */
-export declare const placementMapping: Record<TLegacyPlacement, TPlacementOptions>;

package/dist/types-ts4.5/placement-map/placement-mapping.d.ts

@@ -0,0 +1,13 @@
+import { type TPlacementOptions } from '../internal/resolve-placement';
+import type { TLegacyPlacement } from './legacy-placements';
+/**
+ * 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.
+ */
+export declare const placementMapping: Record<TLegacyPlacement, TPlacementOptions>;

package/dist/types-ts4.5/popover/index.d.ts

@@ -1,3 +1,3 @@
 export { Popover } from './popover';
 export { createPopoverCloseEvent } from './create-close-event';
-export type { TPopoverCloseReason, TPopoverProps } from './types';
+export type { TPopoverCloseReason, TPopoverProps, TPlacementOptions } from './types';

package/dist/types-ts4.5/popover/popover.d.ts

@@ -5,20 +5,13 @@
 import React from 'react';
 import { type TPopoverForwardedProps } from './types';
 /**
- * Unopinionated top-layer primitive.
+ * Unopinionated top-layer primitive. Manages visibility and animation only;
+ * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
  *
- * Manages only visibility (isOpen) and animation (animate). Has no knowledge
- * of positioning - compose with `useAnchorPosition` for anchor positioning
- * and optionally `useWidthFromAnchor` for setting the width of a popover element
- * relative to its anchor trigger.
+ * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
+ * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
  *
- * Visibility is driven by the `isOpen` prop:
- * - `isOpen={true}` → `showPopover()`, entry animation via `@starting-style`
- * - `isOpen={false}` → `hidePopover()`, exit animation via `allow-discrete`
- *
- * For `mode="auto"`, the browser can dismiss the popover via light dismiss
- * (Escape, click outside). When that happens, `onClose` is called and the
- * consumer must set `isOpen` to `false`. The DOM owns the dismiss; React
- * must follow.
+ * In `mode="auto"`, the browser can light-dismiss (Escape, click outside).
+ * `onClose` fires; the consumer must then set `isOpen` to `false`.
  */
 export declare const Popover: React.ForwardRefExoticComponent<TPopoverForwardedProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types-ts4.5/popover/types.d.ts

@@ -1,8 +1,8 @@
 import { type ReactNode } from 'react';
 import { type StrictXCSSProp } from '@atlaskit/css';
 import { type TAnimationPreset } from '../animations/types';
+import { type TPlacementOptions } from '../internal/resolve-placement';
 import { type TAriaRoleRequired, type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
-import { type TPlacementOptions } from '../popup/types';
 /**
  * The reason a popover was closed.
  *
@@ -31,6 +31,7 @@ export type TPopoverForwardedProps = TPopoverBaseProps & {
     label?: string;
     labelledBy?: string;
 };
+export type { TPlacementOptions };
 type TPopoverBaseProps = {
     children: ReactNode;
     /**
@@ -51,8 +52,9 @@ type TPopoverBaseProps = {
     testId?: string;
     /**
      * HTML `id` attribute for the popover element. When omitted, a unique ID
-     * is generated automatically. The `<Popup>` compound passes its context ID
-     * so that `Popup.Trigger` can reference it via `aria-controls` / `popovertarget`.
+     * is generated automatically. Pair the trigger with this ID via `aria-controls`
+     * and the popover with `popovertarget`. Use `usePopoverId()` to generate a
+     * stable, CSS-safe id.
      */
     id?: string;
     /**
@@ -109,7 +111,7 @@ type TPopoverBaseProps = {
      * Called after the entry animation completes (or immediately on open when
      * there is no animation or reduced motion is active).
      *
-     * Use this for external lifecycle coordination — e.g. notifying a manager
+     * Use this for external lifecycle coordination - e.g. notifying a manager
      * that the show sequence is finished.
      */
     onEnterFinish?: () => void;
@@ -178,4 +180,3 @@ export type TPopoverProps = TPopoverBaseProps & TAriaRoleRequired & ({
  *   Falls back to a one-off measurement of the anchor's width.
  */
 export type TWidthFromAnchorMode = 'none' | 'match-anchor' | 'min-anchor';
-export {};

package/dist/types-ts4.5/popover-surface/index.d.ts

@@ -0,0 +1,2 @@
+export { PopoverSurface } from './popover-surface';
+export type { TPopoverSurfaceProps } from './popover-surface';

package/dist/types-ts4.5/popover-surface/popover-surface.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import React, { type ReactNode } from 'react';
+export type TPopoverSurfaceProps = {
+    children: ReactNode;
+};
+/**
+ * Optional styled wrapper for popover content.
+ *
+ * Adds default visual styling (background, border-radius, box-shadow)
+ * using design tokens.
+ *
+ * Presentational primitive - `children`-only by design. This component
+ * intentionally exposes no `style`, `className`, `xcss`, `id`, or `ref`
+ * props. If you need any of those, render your own wrapper element inside
+ * `Popover` instead. `PopoverSurface` is the no-config "give me the default
+ * ADS overlay look" surface, nothing more.
+ */
+export declare function PopoverSurface({ children }: TPopoverSurfaceProps): React.ReactElement;

package/dist/types-ts4.5/use-arrow-navigation/use-arrow-navigation.d.ts

@@ -1,5 +1,5 @@
 import { type RefObject } from 'react';
-import { type TFocusableFilter } from '../focus';
+import { type TFocusableFilter } from '../focus/types';
 /**
  * Args for `useArrowNavigation`.
  *

package/get-aria-for-trigger/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/top-layer/get-aria-for-trigger",
+  "main": "../dist/cjs/entry-points/get-aria-for-trigger.js",
+  "module": "../dist/esm/entry-points/get-aria-for-trigger.js",
+  "module:es2019": "../dist/es2019/entry-points/get-aria-for-trigger.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../dist/types/entry-points/get-aria-for-trigger.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/entry-points/get-aria-for-trigger.d.ts"
+      ]
+    }
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.12.2",
+	"version": "0.14.0",
 	"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",
@@ -37,8 +37,8 @@
 		"@atlaskit/browser-apis": "^0.0.2",
 		"@atlaskit/css": "^0.19.0",
 		"@atlaskit/ds-lib": "^7.0.0",
-		"@atlaskit/layering": "^3.7.0",
-		"@atlaskit/tokens": "^13.1.0",
+		"@atlaskit/layering": "^3.8.0",
+		"@atlaskit/tokens": "^13.3.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"bind-event-listener": "^3.0.0",

package/popover-surface/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/top-layer/popover-surface",
+  "main": "../dist/cjs/entry-points/popover-surface.js",
+  "module": "../dist/esm/entry-points/popover-surface.js",
+  "module:es2019": "../dist/es2019/entry-points/popover-surface.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../dist/types/entry-points/popover-surface.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/entry-points/popover-surface.d.ts"
+      ]
+    }
+  }
+}

package/use-anchor-position-at-point/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/top-layer/use-anchor-position-at-point",
+  "main": "../dist/cjs/entry-points/use-anchor-position-at-point.js",
+  "module": "../dist/esm/entry-points/use-anchor-position-at-point.js",
+  "module:es2019": "../dist/es2019/entry-points/use-anchor-position-at-point.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../dist/types/entry-points/use-anchor-position-at-point.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/entry-points/use-anchor-position-at-point.d.ts"
+      ]
+    }
+  }
+}

package/use-popover-id/package.json

@@ -0,0 +1,17 @@
+{
+  "name": "@atlaskit/top-layer/use-popover-id",
+  "main": "../dist/cjs/entry-points/use-popover-id.js",
+  "module": "../dist/esm/entry-points/use-popover-id.js",
+  "module:es2019": "../dist/es2019/entry-points/use-popover-id.js",
+  "sideEffects": [
+    "*.compiled.css"
+  ],
+  "types": "../dist/types/entry-points/use-popover-id.d.ts",
+  "typesVersions": {
+    ">=4.5 <5.9": {
+      "*": [
+        "../dist/types-ts4.5/entry-points/use-popover-id.d.ts"
+      ]
+    }
+  }
+}

package/dist/cjs/entry-points/popup-surface.js

@@ -1,12 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "PopupSurface", {
-  enumerable: true,
-  get: function get() {
-    return _popupSurface.PopupSurface;
-  }
-});
-var _popupSurface = require("../popup/popup-surface");

package/dist/cjs/entry-points/popup.js

@@ -1,12 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "Popup", {
-  enumerable: true,
-  get: function get() {
-    return _popup.Popup;
-  }
-});
-var _popup = require("../popup");

package/dist/cjs/focus/focus.js

@@ -1,169 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.getFirstFocusable = getFirstFocusable;
-exports.getLastFocusable = getLastFocusable;
-exports.getNextFocusable = getNextFocusable;
-exports.isNestedLayerFocused = isNestedLayerFocused;
-var _browserApis = require("@atlaskit/browser-apis");
-/**
- * Focusable element selectors and navigation helpers.
- *
- * Uses CSS selectors to discover focusable elements within a container,
- * avoiding the need for a manual registration system. Disabled elements
- * (both HTML `disabled` attribute and `aria-disabled="true"`) and elements
- * with `tabindex="-1"` are excluded automatically.
- *
- * All public functions accept an optional `filter` callback to further
- * restrict which focusable elements are included.
- */
-
-var selectors = function () {
-  // Common exclusion filter applied to every selector.
-  var not = ':not([tabindex="-1"]):not([aria-disabled="true"]):not([aria-hidden="true"])';
-  var notDisabled = ":not([disabled])".concat(not);
-  var focusable = ["a[href]".concat(not), "area[href]".concat(not), "input".concat(notDisabled, ":not([type=\"hidden\"])"), "select".concat(notDisabled), "textarea".concat(notDisabled), "button".concat(notDisabled), "iframe".concat(not), "audio[controls]".concat(not), "video[controls]".concat(not), "[contenteditable]:not([contenteditable=\"false\"])".concat(not), "[tabindex]".concat(notDisabled).concat(not)];
-  return {
-    focusable: focusable.join(','),
-    // Build the `:focus` selector
-    focused: focusable.map(function (selector) {
-      return "".concat(selector, ":focus");
-    }).join(',')
-  };
-}();
-var topLayerSelector = '[popover], dialog, [role="dialog"], [role="alertdialog"]';
-
-/**
- * Returns true when `element` and `container` resolve to the same nearest
- * top-layer host (or both resolve to `null`, meaning the document layer).
- */
-function isInSameLayer(_ref) {
-  var element = _ref.element,
-    container = _ref.container;
-  var elementLayer = element.closest(topLayerSelector);
-  var containerLayer = container.closest(topLayerSelector);
-  // Both elements are in the "document" layer
-  if (!elementLayer && !containerLayer) {
-    return true;
-  }
-  return elementLayer === containerLayer;
-}
-
-/**
- * Returns `true` when `document.activeElement` is inside a nested top-layer
- * descendant of `container` (a `[popover]`, `<dialog>`, `[role="dialog"]` or
- * `[role="alertdialog"]` that is itself a descendant of `container`).
- */
-function isNestedLayerFocused(_ref2) {
-  var _getDocument;
-  var container = _ref2.container;
-  var focused = (_getDocument = (0, _browserApis.getDocument)()) === null || _getDocument === void 0 ? void 0 : _getDocument.activeElement;
-  if (!(focused instanceof HTMLElement)) {
-    return false;
-  }
-
-  // Cannot be in a nested layer if it is not in the container
-  if (!container.contains(focused)) {
-    return false;
-  }
-
-  // If not in the same layer, must be in a nested layer
-  return !isInSameLayer({
-    element: focused,
-    container: container
-  });
-}
-
-/**
- * An optional callback to restrict which focusable elements are included.
- * Return `true` to include the element, `false` to skip it.
- */
-
-/**
- * Returns all focusable HTMLElements within the container, optionally filtered.
- *
- * Focusables that belong to a nested top-layer scope (a `[popover]` or
- * `<dialog>` descendant of the container) are excluded - those elements
- * are owned by the inner layer's focus management. The container itself
- * is allowed to be a popover/dialog; only nested ones are filtered.
- */
-function getFocusables(_ref3) {
-  var container = _ref3.container,
-    filter = _ref3.filter;
-  return Array.from(container.querySelectorAll(selectors.focusable)).filter(function (element) {
-    return element instanceof HTMLElement;
-  }).filter(function (element) {
-    return isInSameLayer({
-      element: element,
-      container: container
-    });
-  }).filter(function (element) {
-    return !filter || filter(element, container);
-  });
-}
-
-/**
- * Returns the first focusable element within the container.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-function getFirstFocusable(_ref4) {
-  var container = _ref4.container,
-    filter = _ref4.filter;
-  var items = getFocusables({
-    container: container,
-    filter: filter
-  });
-  return items.length > 0 ? items[0] : null;
-}
-
-/**
- * Returns the last focusable element within the container.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-function getLastFocusable(_ref5) {
-  var container = _ref5.container,
-    filter = _ref5.filter;
-  var items = getFocusables({
-    container: container,
-    filter: filter
-  });
-  return items.length > 0 ? items[items.length - 1] : null;
-}
-
-/**
- * Returns the next focusable element in the given direction relative to the
- * currently focused element within the container. Wraps around at both ends.
- *
- * Returns `null` if there is no focused element within the container or if
- * the focused element is not in the list of focusable elements.
- */
-// eslint-disable-next-line @atlaskit/volt-strict-mode/no-multiple-exports
-function getNextFocusable(_ref6) {
-  var _all$nextIndex;
-  var container = _ref6.container,
-    direction = _ref6.direction,
-    filter = _ref6.filter;
-  var all = getFocusables({
-    container: container,
-    filter: filter
-  });
-  var current = container.querySelector(selectors.focused);
-  if (!(current instanceof HTMLElement)) {
-    return null;
-  }
-  var index = all.indexOf(current);
-  if (index === -1) {
-    return null;
-  }
-  var nextIndex = function () {
-    if (direction === 'forwards') {
-      return (index + 1) % all.length;
-    }
-    var proposed = index - 1;
-    // if going into negative numbers, loop back to the last item
-    return proposed < 0 ? all.length - 1 : proposed;
-  }();
-  return (_all$nextIndex = all[nextIndex]) !== null && _all$nextIndex !== void 0 ? _all$nextIndex : null;
-}

package/dist/cjs/focus/index.js

@@ -1,24 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-Object.defineProperty(exports, "getFirstFocusable", {
-  enumerable: true,
-  get: function get() {
-    return _focus.getFirstFocusable;
-  }
-});
-Object.defineProperty(exports, "getLastFocusable", {
-  enumerable: true,
-  get: function get() {
-    return _focus.getLastFocusable;
-  }
-});
-Object.defineProperty(exports, "getNextFocusable", {
-  enumerable: true,
-  get: function get() {
-    return _focus.getNextFocusable;
-  }
-});
-var _focus = require("./focus");

package/dist/cjs/popup/index.js

@@ -1,37 +0,0 @@
-"use strict";
-
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
-exports.Popup = void 0;
-var _popup = require("./popup");
-var _popupContent = require("./popup-content");
-var _popupSurface = require("./popup-surface");
-var _popupTrigger = require("./popup-trigger");
-var _popupTriggerFunction = require("./popup-trigger-function");
-/**
- * Compound component for rendering content in the browser's top layer
- * using the native Popover API (`popover="auto"`).
- * Placement is owned by this compound: root provides it via context, Content applies it
- * (CSS Anchor Positioning or JS fallback).
- *
- * For default overlay styling (background, shadow, border-radius), see `PopupSurface` in the package examples.
- *
- * @example
- * ```tsx
- * <Popup placement={{ edge: 'end' }} onClose={handleClose}>
- *   <Popup.Trigger>
- *     <button>Open</button>
- *   </Popup.Trigger>
- *   <Popup.Content role="dialog" label="My popup">
- *     Content goes here
- *   </Popup.Content>
- * </Popup>
- * ```
- */
-var Popup = exports.Popup = Object.assign(_popup.PopupRoot, {
-  Trigger: _popupTrigger.PopupTrigger,
-  TriggerFunction: _popupTriggerFunction.PopupTriggerFunction,
-  Content: _popupContent.PopupContent,
-  Surface: _popupSurface.PopupSurface
-});