@atlaskit/top-layer 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,44 @@
+# @atlaskit/top-layer
+
+## 0.1.0
+
+### Minor Changes
+
+- [`f0bc04c9aec75`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f0bc04c9aec75) -
+  Creation of `@atlaskit/top-layer` — low-level layering primitives built on native browser APIs.
+
+  Provides three core building blocks for layered UI:
+  - **`Popover`** — Wraps the native Popover API (`popover="auto"`). Manages visibility, animation,
+    focus wrapping, and initial focus.
+  - **`Dialog`** — Wraps the native `<dialog>` element. Manages `showModal()`/`close()`, animation,
+    focus trapping, Escape handling, and backdrop click detection.
+  - **`Popup`** — Compound component (`Popup` + `Popup.Trigger` + `Popup.Content` + `Popup.Surface`)
+    composing Popover with CSS Anchor Positioning, trigger wiring, and automatic ARIA attributes.
+
+  Key design decisions:
+  - Browser-native first: Popover API and `<dialog>` instead of portals, z-index, and custom
+    layering
+  - CSS-first positioning: CSS Anchor Positioning with a JS fallback for older browsers
+  - CSS-first animation: `@starting-style` for entry, `transition-behavior: allow-discrete` for exit
+  - Accessibility by construction: TypeScript discriminated unions enforce WCAG 4.1.2 at compile
+    time
+  - Entry-point friendly for Volt: each primitive available via its own entry point
+
+### Patch Changes
+
+- [`f0bc04c9aec75`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f0bc04c9aec75) -
+  Fix JS fallback positioning in Firefox: defer position calculation to requestAnimationFrame in the
+  toggle event handler, since Firefox fires the toggle event synchronously during showPopover()
+  before layout runs, causing offsetWidth/offsetHeight to be 0. Also remove the unnecessary initial
+  update() call that ran while the popover was still hidden. Fix VR tests to actually open the popup
+  before taking snapshots (they were previously only capturing the closed trigger button). Add
+  additional JS fallback VR tests for align-end and inline-end alignment variants.
+- [`f0bc04c9aec75`](https://bitbucket.org/atlassian/atlassian-frontend-monorepo/commits/f0bc04c9aec75) -
+  Defer useAnchorPosition cleanup via queueMicrotask to prevent one-frame position jump during exit
+  animations
+
+## 0.0.1
+
+### Patch Changes
+
+- Initial release of `@atlaskit/top-layer`.

package/README.md

@@ -0,0 +1,151 @@
+# @atlaskit/top-layer
+
+Low-level top-layer primitives using the native
+[Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API) (`popover="auto"`) and
+[`<dialog>`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dialog) element.
+
+## Popup
+
+Compound component for rendering content in the browser's top layer with CSS Anchor Positioning.
+Placement is owned by this compound: root provides it via context, Content applies it (CSS Anchor
+Positioning or JS fallback).
+
+```tsx
+<Popup placement="block-end" onClose={handleClose}>
+	<Popup.Trigger>
+		<button>Open</button>
+	</Popup.Trigger>
+	<Popup.Content role="dialog" label="My popup">
+		Content here
+	</Popup.Content>
+</Popup>
+```
+
+For default overlay styling (background, shadow, border-radius), see `PopupSurface` in the package examples (not currently a public API; we may expose it in a future release).
+
+## Popover
+
+Low-level primitive: a `<div>` with the `popover` attribute and show/hide lifecycle only. No
+placement, no trigger wiring — use it when you need top-layer rendering with **fixed or
+custom positioning** (e.g. Flag uses `Popover mode="manual"`). For anchor-positioned content
+next to a trigger, use **Popup** instead.
+
+## Dialog
+
+Compound component for modal dialogs using the native `<dialog>` element with `.showModal()`.
+
+```tsx
+{
+	isOpen && (
+		<Dialog onClose={handleClose} width="medium">
+			<Dialog.Content>
+				<Dialog.Surface>
+					<Dialog.Header>
+						<Dialog.Title>Heading</Dialog.Title>
+						<Dialog.CloseButton />
+					</Dialog.Header>
+					<Dialog.Body>Content</Dialog.Body>
+					<Dialog.Footer>Actions</Dialog.Footer>
+				</Dialog.Surface>
+			</Dialog.Content>
+		</Dialog>
+	);
+}
+```
+
+## Animations
+
+Both Popup (and the low-level Popover) and Dialog support CSS-based entry/exit animations via the
+`animate` prop. Animations
+use [`@starting-style`](https://developer.mozilla.org/en-US/docs/Web/CSS/@starting-style) for entry
+and [`allow-discrete`](https://developer.mozilla.org/en-US/docs/Web/CSS/transition-behavior) on
+`display`/`overlay` for exit — no JavaScript animation coordination required.
+
+Presets are available from `@atlaskit/top-layer/animations`:
+
+```tsx
+import {
+	// Popover presets
+	slideAndFade,
+	fade,
+	scaleAndFade,
+	// Dialog presets
+	dialogSlideUpAndFade,
+	dialogFade,
+} from '@atlaskit/top-layer/animations';
+```
+
+### Popup animation
+
+Pass a preset to `Popup.Content` (or to `Popover` when using the low-level primitive without
+placement):
+
+```tsx
+import { slideAndFade } from '@atlaskit/top-layer/animations';
+
+const animation = slideAndFade();
+
+<Popup.Content animate={animation} role="dialog" label="My popup">
+	Content
+</Popup.Content>;
+```
+
+For overlay styling (background, shadow, border-radius), see the `PopupSurface` usage in the package examples.
+
+Available popover presets:
+
+- `slideAndFade({ distance? })` — directional slide + opacity (default for tooltip)
+- `fade` — simple opacity transition
+- `scaleAndFade` — scale from 0.95 + opacity (suitable for menus/dropdowns)
+
+### Dialog animation
+
+Pass a preset to `Dialog.Content`:
+
+```tsx
+import { dialogSlideUpAndFade } from '@atlaskit/top-layer/animations';
+
+const animation = dialogSlideUpAndFade();
+
+<Dialog.Content animate={animation}>
+	<Dialog.Surface>...</Dialog.Surface>
+</Dialog.Content>;
+```
+
+Available dialog presets:
+
+- `dialogSlideUpAndFade({ distance? })` — slide up + opacity with backdrop fade (matches legacy
+  modal entrance)
+- `dialogFade` — simple opacity + backdrop fade
+
+### Progressive enhancement
+
+Browsers without `@starting-style` support will show/hide elements instantly — no broken state. The
+`prefers-reduced-motion: reduce` media query sets all transition durations to `0s`.
+
+## Accessibility
+
+Browser tests in `__tests__/playwright/` verify the following WCAG 2.2 success criteria. See
+[`notes/goals/accessibility-criteria.md`](notes/goals/accessibility-criteria.md) and
+[`notes/audits/accessibility-audit-report.md`](notes/audits/accessibility-audit-report.md) for
+details.
+
+| A11y criterion                        | Browser test |
+| ------------------------------------- | ------------ |
+| 1.3.1 Info and Relationships          | ✓            |
+| 1.3.2 Meaningful Sequence             | ✓            |
+| 2.1.1 Keyboard                        | ✓            |
+| 2.1.2 No Keyboard Trap                | ✓            |
+| 2.4.3 Focus Order                     | ✓            |
+| 2.4.7 Focus Visible                   | ✓            |
+| 2.4.11 Focus Not Obscured            | ✓            |
+| 3.2.1 On Focus                        | ✓            |
+| 4.1.2 Name, Role, Value              | ✓            |
+| 4.1.3 Status Messages                 | ✓            |
+| Background inertness (modal dialogs)  | ✓            |
+| Close reasons (Dialog)                | ✓            |
+
+## Documentation
+
+See [`notes/`](notes/) for project documentation, architecture decisions, migration records, and
+audit reports. The [`notes/README.md`](notes/README.md) provides a full index.

package/animations/package.json

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

package/arrow/package.json

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

package/create-close-event/package.json

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

package/dialog/package.json

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

package/dialog-scroll-lock/package.json

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

package/dist/cjs/animations/presets.js

@@ -0,0 +1,199 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.dialogFade = dialogFade;
+exports.dialogSlideUpAndFade = dialogSlideUpAndFade;
+exports.fade = fade;
+exports.scaleAndFade = scaleAndFade;
+exports.slideAndFade = slideAndFade;
+var _useAnchorPositioning = require("../internal/use-anchor-positioning");
+// ── slideAndFade ──
+
+function getSlideAndFadeProperties(_ref) {
+  var placement = _ref.placement,
+    distance = _ref.distance;
+  var pos = "".concat(distance, "px");
+  var neg = "-".concat(distance, "px");
+  var _getPlacement = (0, _useAnchorPositioning.getPlacement)({
+      placement: placement
+    }),
+    axis = _getPlacement.axis,
+    edge = _getPlacement.edge;
+  if (axis === 'block' && edge === 'start') {
+    return {
+      '--ds-popover-tx': '0',
+      '--ds-popover-ty': pos
+    };
+  }
+  if (axis === 'block' && edge === 'end') {
+    return {
+      '--ds-popover-tx': '0',
+      '--ds-popover-ty': neg
+    };
+  }
+  if (axis === 'inline' && edge === 'start') {
+    return {
+      '--ds-popover-tx': pos,
+      '--ds-popover-ty': '0'
+    };
+  }
+  if (axis === 'inline' && edge === 'end') {
+    return {
+      '--ds-popover-tx': neg,
+      '--ds-popover-ty': '0'
+    };
+  }
+  return {
+    '--ds-popover-tx': '0',
+    '--ds-popover-ty': neg
+  };
+}
+var SLIDE_AND_FADE_CSS = "\n[data-ds-popover-slide-and-fade] {\n  opacity: 0;\n  transform: translate3d(var(--ds-popover-tx, 0), var(--ds-popover-ty, 0), 0);\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-popover-slide-and-fade]:popover-open {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-popover-slide-and-fade]:popover-open {\n    opacity: 0;\n    transform: translate3d(var(--ds-popover-tx, 0), var(--ds-popover-ty, 0), 0);\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-popover-slide-and-fade],\n  [data-ds-popover-slide-and-fade]:popover-open {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Directional slide + opacity animation.
+ *
+ * The popover slides in from the direction opposite its placement edge
+ * (e.g. a `block-end` popover slides down from above).
+ *
+ * @param options.distance - Slide distance in pixels. Defaults to `4`.
+ *
+ * @example
+ * ```tsx
+ * import { slideAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * // Default 4px slide (tooltip)
+ * <Popup.Content animate={slideAndFade()} />
+ *
+ * // Custom 8px slide (popup / dropdown)
+ * <Popup.Content animate={slideAndFade({ distance: 8 })} />
+ * ```
+ */
+function slideAndFade(options) {
+  var _options$distance;
+  var distance = (_options$distance = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance !== void 0 ? _options$distance : 4;
+  return {
+    name: 'slide-and-fade',
+    css: SLIDE_AND_FADE_CSS,
+    getProperties: function getProperties(_ref2) {
+      var placement = _ref2.placement;
+      return getSlideAndFadeProperties({
+        placement: placement,
+        distance: distance
+      });
+    },
+    exitDurationMs: 175
+  };
+}
+
+// ── fade ──
+
+var FADE_CSS = "\n[data-ds-popover-fade] {\n  opacity: 0;\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-popover-fade]:popover-open {\n  opacity: 1;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-popover-fade]:popover-open {\n    opacity: 0;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-popover-fade],\n  [data-ds-popover-fade]:popover-open {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Simple opacity transition, no transform.
+ *
+ * Suitable for popup dialogs or content that does not need directional motion.
+ *
+ * @example
+ * ```tsx
+ * import { fade } from '@atlaskit/top-layer/animations';
+ *
+ * <Popup.Content animate={fade()} />
+ * ```
+ */
+function fade() {
+  return {
+    name: 'fade',
+    css: FADE_CSS,
+    exitDurationMs: 175
+  };
+}
+
+// ── scaleAndFade ──
+
+var SCALE_AND_FADE_CSS = "\n[data-ds-popover-scale-and-fade] {\n  opacity: 0;\n  transform: scale(0.95);\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-popover-scale-and-fade]:popover-open {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-popover-scale-and-fade]:popover-open {\n    opacity: 0;\n    transform: scale(0.95);\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-popover-scale-and-fade],\n  [data-ds-popover-scale-and-fade]:popover-open {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Scale from 0.95 + opacity transition.
+ *
+ * Suitable for menus, dropdowns, and select options.
+ *
+ * @example
+ * ```tsx
+ * import { scaleAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * <Popup.Content animate={scaleAndFade()} />
+ * ```
+ */
+function scaleAndFade() {
+  return {
+    name: 'scale-and-fade',
+    css: SCALE_AND_FADE_CSS,
+    exitDurationMs: 175
+  };
+}
+
+// ══════════════════════════════════════════════════════════════════════════════
+// Dialog presets
+// ══════════════════════════════════════════════════════════════════════════════
+
+// ── dialogSlideUpAndFade ──
+
+var DIALOG_SLIDE_UP_AND_FADE_CSS = "\n[data-ds-dialog-slide-up-and-fade] {\n  opacity: 0;\n  transform: translateY(calc(-1 * var(--ds-dialog-ty, 12px)));\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    transform 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-slide-up-and-fade][open] {\n  opacity: 1;\n  transform: none;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-slide-up-and-fade][open] {\n    opacity: 0;\n    transform: translateY(var(--ds-dialog-ty, 12px));\n  }\n}\n\n[data-ds-dialog-slide-up-and-fade]::backdrop {\n  background-color: transparent;\n  transition:\n    background-color 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-slide-up-and-fade][open]::backdrop {\n  background-color: var(--ds-blanket, #050C1F75);\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-slide-up-and-fade][open]::backdrop {\n    background-color: transparent;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-dialog-slide-up-and-fade],\n  [data-ds-dialog-slide-up-and-fade][open],\n  [data-ds-dialog-slide-up-and-fade]::backdrop,\n  [data-ds-dialog-slide-up-and-fade][open]::backdrop {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Slide up + opacity animation for dialogs.
+ *
+ * Entry slides up from below; exit slides up and out (asymmetric).
+ * Includes backdrop fade animation.
+ *
+ * @param options.distance - Slide distance in pixels. Defaults to `12`.
+ *
+ * @example
+ * ```tsx
+ * import { dialogSlideUpAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * const animation = dialogSlideUpAndFade();
+ * <Dialog animate={animation} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+function dialogSlideUpAndFade(options) {
+  var _options$distance2;
+  var distance = (_options$distance2 = options === null || options === void 0 ? void 0 : options.distance) !== null && _options$distance2 !== void 0 ? _options$distance2 : 12;
+  return {
+    name: distance === 12 ? 'dialog-slide-up-and-fade' : "dialog-slide-up-and-fade-".concat(distance),
+    css: distance === 12 ? DIALOG_SLIDE_UP_AND_FADE_CSS : DIALOG_SLIDE_UP_AND_FADE_CSS.replace(/12px/g, "".concat(distance, "px")),
+    exitDurationMs: 175
+  };
+}
+
+// ── dialogFade ──
+
+var DIALOG_FADE_CSS = "\n[data-ds-dialog-fade] {\n  opacity: 0;\n  transition:\n    opacity 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-fade][open] {\n  opacity: 1;\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-fade][open] {\n    opacity: 0;\n  }\n}\n\n[data-ds-dialog-fade]::backdrop {\n  background-color: transparent;\n  transition:\n    background-color 175ms cubic-bezier(0.15, 1, 0.3, 1),\n    overlay 175ms allow-discrete,\n    display 175ms allow-discrete;\n}\n\n[data-ds-dialog-fade][open]::backdrop {\n  background-color: var(--ds-blanket, #050C1F75);\n  transition-duration: 350ms;\n}\n\n@starting-style {\n  [data-ds-dialog-fade][open]::backdrop {\n    background-color: transparent;\n  }\n}\n\n@media (prefers-reduced-motion: reduce) {\n  [data-ds-dialog-fade],\n  [data-ds-dialog-fade][open],\n  [data-ds-dialog-fade]::backdrop,\n  [data-ds-dialog-fade][open]::backdrop {\n    transition-duration: 0s;\n  }\n}\n";
+
+/**
+ * Simple opacity transition for dialogs, no transform.
+ *
+ * Includes backdrop fade animation.
+ *
+ * @example
+ * ```tsx
+ * import { dialogFade } from '@atlaskit/top-layer/animations';
+ *
+ * <Dialog animate={dialogFade()} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+function dialogFade() {
+  return {
+    name: 'dialog-fade',
+    css: DIALOG_FADE_CSS,
+    exitDurationMs: 175
+  };
+}

package/dist/cjs/animations/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/arrow/index.js

@@ -0,0 +1,130 @@
+"use strict";
+
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault");
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.arrow = void 0;
+var _once = _interopRequireDefault(require("@atlaskit/ds-lib/once"));
+var _useAnchorPositioning = require("../internal/use-anchor-positioning");
+/**
+ * CSS for popover arrows using the `clip-path: inset() margin-box` technique.
+ *
+ * How it works:
+ * 1. Four arrow shapes exist simultaneously as `::before` (top/bottom) and
+ *    `::after` (left/right) hexagonal pseudo-elements.
+ * 2. `clip-path: inset(1px) margin-box` clips the popover to its margin-box.
+ * 3. Margin on the anchor-facing side pushes the popover away, creating space
+ *    where one arrow "escapes" the clip boundary and becomes visible.
+ * 4. `@position-try` rules change both `position-area` and `margin` when
+ *    flipping, ensuring the correct arrow is always shown.
+ *
+ * Constraints:
+ * - `box-shadow` must be `none` (interferes with `clip-path: inset() margin-box`)
+ * - `::before` and `::after` are consumed — consumers cannot use them
+ * - Arrow pseudo-elements use `background: inherit` from the popover element
+ *
+ * @see https://goulet.dev/posts/tooltip-with-popover-and-anchor-positioning/
+ */
+var ARROW_CSS = "\n[data-ds-popover-arrow] {\n  clip-path: inset(var(--ds-arrow-offset, 1px)) margin-box;\n  box-shadow: none;\n}\n\n/* Top and Bottom arrows (vertical hexagon) */\n[data-ds-popover-arrow]::before {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  left: 50%;\n  transform: translateX(-50%);\n  width: calc(var(--ds-arrow-size, 8px) * 2);\n  height: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  top: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    0 var(--ds-arrow-size, 8px),\n    50% 0,\n    100% var(--ds-arrow-size, 8px),\n    100% calc(100% - var(--ds-arrow-size, 8px)),\n    50% 100%,\n    0 calc(100% - var(--ds-arrow-size, 8px))\n  );\n}\n\n/* Left and Right arrows (horizontal hexagon) */\n[data-ds-popover-arrow]::after {\n  content: \"\";\n  position: absolute;\n  z-index: -1;\n  background: inherit;\n  top: 50%;\n  transform: translateY(-50%);\n  height: calc(var(--ds-arrow-size, 8px) * 2);\n  width: calc(100% + var(--ds-arrow-size, 8px) * 2);\n  left: calc(var(--ds-arrow-size, 8px) * -1);\n  clip-path: polygon(\n    var(--ds-arrow-size, 8px) 0,\n    calc(100% - var(--ds-arrow-size, 8px)) 0,\n    100% 50%,\n    calc(100% - var(--ds-arrow-size, 8px)) 100%,\n    var(--ds-arrow-size, 8px) 100%,\n    0 50%\n  );\n}\n\n/* \u2500\u2500 @position-try rules \u2500\u2500\n * One rule per possible position-area value.\n * Each sets the position-area and the correct margin direction\n * so the arrow on the anchor-facing side is revealed.\n *\n * Margin direction per edge:\n *   block-start  (above anchor) \u2192 margin-block-end   (bottom, facing anchor)\n *   block-end    (below anchor) \u2192 margin-block-start  (top, facing anchor)\n *   inline-start (left of anchor) \u2192 margin-inline-end (right, facing anchor)\n *   inline-end   (right of anchor) \u2192 margin-inline-start (left, facing anchor)\n */\n\n/* Single-axis centered */\n@position-try --ds-arrow-block-start {\n  position-area: block-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-end {\n  position-area: block-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-start {\n  position-area: inline-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-end {\n  position-area: inline-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n}\n\n/* Block edge + inline span */\n@position-try --ds-arrow-block-start-span-inline-start {\n  position-area: block-start span-inline-start;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-start-span-inline-end {\n  position-area: block-start span-inline-end;\n  margin: 0;\n  margin-block-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-end-span-inline-start {\n  position-area: block-end span-inline-start;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-block-end-span-inline-end {\n  position-area: block-end span-inline-end;\n  margin: 0;\n  margin-block-start: var(--ds-arrow-size, 8px);\n}\n\n/* Inline edge + block span */\n@position-try --ds-arrow-inline-start-span-block-start {\n  position-area: inline-start span-block-start;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-start-span-block-end {\n  position-area: inline-start span-block-end;\n  margin: 0;\n  margin-inline-end: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-end-span-block-start {\n  position-area: inline-end span-block-start;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n}\n@position-try --ds-arrow-inline-end-span-block-end {\n  position-area: inline-end span-block-end;\n  margin: 0;\n  margin-inline-start: var(--ds-arrow-size, 8px);\n}\n";
+
+// ── Placement utilities ──
+
+/**
+ * Converts a `position-area` value to a CSS rule name by replacing spaces with hyphens
+ * and prepending `--ds-arrow-`.
+ *
+ * @example positionAreaToRuleName('block-end span-inline-start') → '--ds-arrow-block-end-span-inline-start'
+ */
+function positionAreaToRuleName(_ref) {
+  var positionArea = _ref.positionArea;
+  return "--ds-arrow-".concat(positionArea.replace(/ /g, '-'));
+}
+
+/**
+ * Returns `position-try-fallbacks` using named `@position-try` rules
+ * that change both `position-area` and `margin` when flipping.
+ *
+ * This is required for the arrow technique because built-in keywords
+ * (`flip-block`, `flip-inline`) only flip `position-area` — they do
+ * not update the margin direction needed to reveal the correct arrow.
+ */
+function getTryFallbacks(_ref2) {
+  var placement = _ref2.placement;
+  var _getPlacement = (0, _useAnchorPositioning.getPlacement)({
+      placement: placement
+    }),
+    axis = _getPlacement.axis,
+    edge = _getPlacement.edge,
+    align = _getPlacement.align;
+  if (align === 'center') {
+    // Single-axis: only flip the edge
+    var _flippedEdge = edge === 'start' ? 'end' : 'start';
+    return positionAreaToRuleName({
+      positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+        placement: {
+          axis: axis,
+          edge: _flippedEdge
+        }
+      })
+    });
+  }
+
+  // Compound placement: try flipping edge, alignment, and both
+  var flippedEdge = edge === 'start' ? 'end' : 'start';
+  var flippedAlign = align === 'start' ? 'end' : 'start';
+  return [positionAreaToRuleName({
+    positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+      placement: {
+        axis: axis,
+        edge: flippedEdge,
+        align: align
+      }
+    })
+  }), positionAreaToRuleName({
+    positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+      placement: {
+        axis: axis,
+        edge: edge,
+        align: flippedAlign
+      }
+    })
+  }), positionAreaToRuleName({
+    positionArea: (0, _useAnchorPositioning.placementToPositionArea)({
+      placement: {
+        axis: axis,
+        edge: flippedEdge,
+        align: flippedAlign
+      }
+    })
+  })].join(', ');
+}
+
+/**
+ * Creates an arrow preset for popover content.
+ *
+ * The returned object is passed to `PopoverContent`'s `arrow` prop.
+ * It carries the CSS string and fallback logic so that consumers who
+ * don't use arrows pay no bundle cost.
+ *
+ * The arrows inherit their background from the popover element.
+ * When `arrow` is active, `PopoverContent` does not reset `background`
+ * to `transparent`, allowing the UA default (`canvas`) or a consumer-set
+ * background to show through.
+ *
+ * @example
+ * ```tsx
+ * import { arrow } from '@atlaskit/top-layer/arrow';
+ *
+ * const myArrow = arrow();
+ *
+ * <Popup.Content arrow={myArrow} />
+ * ```
+ */
+var arrow = exports.arrow = (0, _once.default)(function () {
+  return {
+    name: 'arrow',
+    css: ARROW_CSS,
+    getTryFallbacks: getTryFallbacks
+  };
+});

package/dist/cjs/arrow/types.js

@@ -0,0 +1,5 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});

package/dist/cjs/dialog/create-close-event.js

@@ -0,0 +1,39 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createCloseEvent = createCloseEvent;
+/**
+ * Creates a synthetic DOM event from a `TDialogCloseReason`.
+ *
+ * Useful when bridging the Dialog primitive's `onClose({ reason })` callback
+ * to a legacy API that expects a `KeyboardEvent` or `MouseEvent` — for example,
+ * `@atlaskit/modal-dialog`'s `onClose(event, analyticsEvent)` contract.
+ *
+ * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
+ * - `'overlay-click'` → `MouseEvent('click')`
+ *
+ * @example
+ * ```tsx
+ * import { createCloseEvent } from '@atlaskit/top-layer/create-close-event';
+ * import { type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
+ *
+ * function onDialogClose({ reason }: { reason: TDialogCloseReason }) {
+ *   legacyOnClose(createCloseEvent({ reason }));
+ * }
+ * ```
+ */
+function createCloseEvent(_ref) {
+  var reason = _ref.reason;
+  if (reason === 'escape') {
+    return new KeyboardEvent('keydown', {
+      key: 'Escape',
+      bubbles: true
+    });
+  }
+  return new MouseEvent('click', {
+    bubbles: true,
+    cancelable: true
+  });
+}