@atlaskit/top-layer 0.1.0

package/dist/types/entry-points/create-close-event.d.ts

@@ -0,0 +1,4 @@
+export { createCloseEvent } from '../dialog';
+export { createPopoverCloseEvent } from '../popover/create-close-event';
+export type { TDialogCloseReason } from '../dialog';
+export type { TPopoverCloseReason } from '../popover';

package/dist/types/entry-points/dialog-scroll-lock.d.ts

@@ -0,0 +1 @@
+export { DialogScrollLock } from '../dialog-scroll-lock';

package/dist/types/entry-points/dialog.d.ts

@@ -0,0 +1,2 @@
+export { Dialog } from '../dialog';
+export type { TDialogCloseReason, TDialogProps } from '../dialog';

package/dist/types/entry-points/focus.d.ts

@@ -0,0 +1,2 @@
+export { getFirstFocusable, getLastFocusable, getNextFocusable } from '../focus';
+export type { TFocusableFilter } from '../focus';

package/dist/types/entry-points/placement-map.d.ts

@@ -0,0 +1,2 @@
+export { fromLegacyPlacement, placementMapping } from '../placement-map';
+export type { TLegacyPlacement, TPlacementOptions } from '../placement-map';

package/dist/types/entry-points/popover.d.ts

@@ -0,0 +1,2 @@
+export { Popover } from '../popover';
+export type { TPopoverProps, TPopoverCloseReason } from '../popover';

package/dist/types/entry-points/popup-surface.d.ts

@@ -0,0 +1,2 @@
+export { PopupSurface } from '../popup/popup-surface';
+export type { TPopupSurfaceProps } from '../popup/types';

package/dist/types/entry-points/popup.d.ts

@@ -0,0 +1,2 @@
+export { Popup } from '../popup';
+export type { TPlacementOptions, TPopupProps, TPopupContentProps, TPopupRole, TPopupTriggerProps, TTriggerFunctionRenderProps, } from '../popup';

package/dist/types/entry-points/use-anchor-position.d.ts

@@ -0,0 +1 @@
+export { useAnchorPosition } from '../internal/use-anchor-positioning';

package/dist/types/entry-points/use-arrow-navigation.d.ts

@@ -0,0 +1,2 @@
+export { useArrowNavigation, isAtCurrentMenuLevel } from '../use-arrow-navigation';
+export type { TUseArrowNavigationArgs } from '../use-arrow-navigation';

package/dist/types/entry-points/use-simple-light-dismiss.d.ts

@@ -0,0 +1,2 @@
+export { useSimpleLightDismiss } from '../use-simple-light-dismiss';
+export type { TUseSimpleLightDismissOptions } from '../use-simple-light-dismiss';

package/dist/types/focus/focus.d.ts

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+/**
+ * An optional callback to restrict which focusable elements are included.
+ * Return `true` to include the element, `false` to skip it.
+ */
+export type TFocusableFilter = (element: HTMLElement, container: HTMLElement) => boolean;
+/**
+ * Returns the first focusable element within the container.
+ */
+export declare function getFirstFocusable({ container, filter, }: {
+    container: HTMLElement;
+    filter?: TFocusableFilter;
+}): HTMLElement | null;
+/**
+ * Returns the last focusable element within the container.
+ */
+export declare function getLastFocusable({ container, filter, }: {
+    container: HTMLElement;
+    filter?: TFocusableFilter;
+}): HTMLElement | 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.
+ */
+export declare function getNextFocusable({ container, direction, filter, }: {
+    container: HTMLElement;
+    direction: 'forwards' | 'backwards';
+    filter?: TFocusableFilter;
+}): HTMLElement | null;

package/dist/types/focus/index.d.ts

@@ -0,0 +1,2 @@
+export { getFirstFocusable, getLastFocusable, getNextFocusable } from './focus';
+export type { TFocusableFilter } from './focus';

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

@@ -0,0 +1,24 @@
+import { type TPlacement } from './resolve-placement';
+/**
+ * JS fallback: compute popover position from trigger rect and viewport.
+ *
+ * Placement algorithm (from the document):
+ * - "block" placement: show above/below, picking the side with more space if flipping needed
+ * - "inline" placement: show left/right, picking the side with more space if flipping needed
+ * - "auto" placement: show on the edge with the most available space
+ *
+ * Re-runs on scroll (capture on window) and resize events.
+ */
+export declare function computeFallbackPosition({ triggerRect, popoverEl, placement, viewport, offset, }: {
+    triggerRect: DOMRect;
+    popoverEl: HTMLElement;
+    placement: TPlacement;
+    viewport: {
+        width: number;
+        height: number;
+    };
+    offset: number;
+}): {
+    top: number;
+    left: number;
+};

package/dist/types/internal/combine.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Combine multiple cleanup functions into a single cleanup function.
+ *
+ * @example
+ * ```ts
+ * useEffect(() => {
+ *   return combine(
+ *     bind(window, { type: 'resize', listener: onResize }),
+ *     bind(window, { type: 'scroll', listener: onScroll, options: { capture: true } }),
+ *   );
+ * }, []);
+ * ```
+ */
+export declare function combine(...cleanupFns: ((() => void) | undefined)[]): () => void;

package/dist/types/internal/ensure-preset-styles.d.ts

@@ -0,0 +1,6 @@
+export declare function ensurePresetStyles({ preset }: {
+    preset: {
+        css: string;
+        name: string;
+    };
+}): void;

package/dist/types/internal/reduced-motion.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns `true` when the user prefers reduced motion.
+ *
+ * Safe for SSR (returns `false` when `window` is unavailable).
+ *
+ * The result is cached after the first call via `once`. This avoids
+ * calling `matchMedia` on every render. The trade-off is that if a user
+ * toggles the OS reduced-motion setting mid-session, the change won't
+ * take effect until the next page load. This is acceptable because
+ * toggling this system-level preference mid-session is extremely rare,
+ * and a page refresh is a reasonable expectation for system accessibility
+ * settings to take effect.
+ */
+export declare const prefersReducedMotion: () => boolean;

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

@@ -0,0 +1,16 @@
+/**
+ * Fully-resolved placement (internal). All fields are required.
+ * Use getPlacement({ placement: partial }) to obtain from partial input.
+ */
+export type TPlacement = {
+    axis: 'block' | 'inline';
+    edge: 'start' | 'end';
+    align: 'start' | 'center' | 'end';
+};
+/**
+ * Resolves a partial placement to its fully-specified form.
+ * Defaults: `axis: 'block'`, `edge: 'end'`, `align: 'center'`.
+ */
+export declare function getPlacement({ placement }: {
+    placement: Partial<TPlacement>;
+}): TPlacement;

package/dist/types/internal/role-types.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Valid values for the `aria-haspopup` attribute.
+ * Derived from the HTML spec — maps popover roles to what the trigger announces.
+ */
+export type TAriaHasPopupValue = 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true;
+/**
+ * Roles that require an accessible name (`label` or `labelledBy`) per WCAG 4.1.2.
+ * Without a name, assistive technology cannot identify these landmarks.
+ */
+export type TRoleRequiringAccessibleName = 'dialog' | 'alertdialog' | 'menu';
+/**
+ * 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).
+ */
+export type TRoleWithImplicitName = 'tooltip' | 'listbox' | 'tree' | 'grid' | 'note' | 'status' | 'alert' | 'log';
+type TAccessibleNameRequired = {
+    /**
+     * Accessible name via `aria-label`.
+     */
+    label: string;
+    labelledBy?: string;
+} | {
+    label?: string;
+    /**
+     * Accessible name via `aria-labelledby`.
+     */
+    labelledBy: string;
+};
+type TAccessibleNameOptional = {
+    label?: string;
+    labelledBy?: string;
+};
+/**
+ * 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.
+ */
+export type TAriaRoleRequired = ({
+    role: TRoleRequiringAccessibleName;
+} & TAccessibleNameRequired) | ({
+    role: TRoleWithImplicitName;
+} & TAccessibleNameOptional);
+/**
+ * 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.
+ */
+export type TAriaRoleOptional = ({
+    role: TRoleRequiringAccessibleName;
+} & TAccessibleNameRequired) | ({
+    role?: TRoleWithImplicitName;
+} & TAccessibleNameOptional);
+/**
+ * Maps a popover content role to the correct `aria-haspopup` value
+ * for its trigger element.
+ */
+export declare function roleToAriaHasPopup({ role, }: {
+    role: TRoleRequiringAccessibleName | TRoleWithImplicitName | undefined;
+}): TAriaHasPopupValue;
+export {};

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

@@ -0,0 +1,28 @@
+/**
+ * Sets inline styles on an element and returns a cleanup function
+ * that removes only the styles that were applied.
+ *
+ * Uses `style.setProperty()` / `style.removeProperty()` so that
+ * hyphenated CSS property names (e.g. `position-area`, `anchor-name`)
+ * work correctly. These newer properties do not have camelCase
+ * mappings in `CSSStyleDeclaration` yet.
+ *
+ * @example
+ * ```ts
+ * const cleanup = setStyle({ el: popover, styles: [
+ *   { property: 'position-anchor', value: '--my-anchor' },
+ *   { property: 'position-area', value: 'block-end' },
+ *   { property: 'margin', value: '0' },
+ * ] });
+ *
+ * // Later: removes all three properties
+ * cleanup();
+ * ```
+ */
+export declare function setStyle({ el, styles, }: {
+    el: HTMLElement;
+    styles: Array<{
+        property: string;
+        value: string;
+    }>;
+}): () => void;

package/dist/types/internal/slot.d.ts

@@ -0,0 +1,29 @@
+import { type ForwardRefExoticComponent, type ReactNode, type RefAttributes } from 'react';
+/**
+ * Extra DOM/event props are passed through to the cloned child.
+ */
+export type SlotProps = {
+    children: ReactNode;
+} & Record<string, unknown>;
+/**
+ * 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,
+ *    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
+ * handler replaces the child's. Compose handlers before passing them in.
+ *
+ * @example
+ * ```tsx
+ * <Slot ref={triggerRef} onClick={handleClick} aria-expanded={isOpen}>
+ *   <button>Open</button>
+ * </Slot>
+ * ```
+ */
+export declare const Slot: ForwardRefExoticComponent<SlotProps & RefAttributes<HTMLElement>>;

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

@@ -0,0 +1,95 @@
+import { type RefObject } from 'react';
+import { type TArrowPreset } from '../arrow/types';
+import { type TPlacementOptions } from '../popup/types';
+export { getPlacement } from './resolve-placement';
+/**
+ * Resolves placement options 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)
+ * - `align: 'end'` means "aligned to the trigger's end edge"
+ * - `align: 'center'` means centered (single-axis position-area)
+ *
+ * CSS `position-area` uses `span-*` keywords which indicate the *expansion direction*.
+ * Visual start-alignment requires `span-{cross-axis}-end` (expand toward end = start-aligned).
+ * This function handles the inversion internally.
+ *
+ * @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'
+ */
+export declare function placementToPositionArea({ placement }: {
+    placement: TPlacementOptions;
+}): string;
+/**
+ * Returns `position-try-fallbacks` value based on placement.
+ *
+ * For centered placements, includes cross-axis aligned position-area
+ * values so the browser can shift the popover along the cross-axis
+ * when the centered position would overflow the viewport edge.
+ *
+ * Fallback order for centered placements (e.g. `block-end`):
+ * 1. Same edge, start-aligned (shift for near-edge overflow)
+ * 2. Same edge, end-aligned (shift for far-edge overflow)
+ * 3. Flipped edge, centered
+ * 4. Flipped edge, start-aligned
+ * 5. Flipped edge, end-aligned
+ *
+ * For aligned placements (start/end), includes the same-edge centered
+ * position as fallbacks so the browser can try centering when the aligned
+ * position would overflow, before flipping to the opposite edge.
+ */
+export declare function placementToTryFallbacks({ placement }: {
+    placement: TPlacementOptions;
+}): string;
+/**
+ * Hook that positions an element relative to an anchor element using
+ * CSS Anchor Positioning (with a JS fallback for older browsers).
+ *
+ * This hook is the positioning primitive — it has no knowledge of popovers,
+ * visibility, or animation. Compose it with `Popover` for anchor-positioned
+ * top-layer content.
+ *
+ * When CSS Anchor Positioning is supported, it sets CSS properties
+ * (`anchor-name`, `position-anchor`, `position-area`, `position-try-fallbacks`)
+ * directly on the elements via `el.style.setProperty()`.
+ *
+ * When not supported, it falls back to JavaScript-based positioning using
+ * `position: fixed` with measured coordinates, re-running on scroll (capture)
+ * and resize events.
+ */
+export declare function useAnchorPosition({ anchorRef, popoverRef, placement, offset, forceFallbackPositioning, arrow, }: {
+    /**
+     * Element to position relative to.
+     */
+    anchorRef: RefObject<HTMLElement | null>;
+    /**
+     * Element being positioned (typically a popover).
+     */
+    popoverRef: RefObject<HTMLElement | null>;
+    /**
+     * Where to place the element relative to the anchor.
+     */
+    placement: TPlacementOptions;
+    /**
+     * Gap between the positioned element and the anchor, in pixels.
+     * Defaults to 8 (`space.100`). Tooltip uses 4.
+     */
+    offset?: number;
+    /**
+     * Forces the JavaScript positioning fallback even when the browser
+     * supports CSS Anchor Positioning. Useful for testing fallback
+     * behavior in any environment, including production.
+     */
+    forceFallbackPositioning?: boolean;
+    /**
+     * Arrow preset from `@atlaskit/top-layer/arrow`. When provided, uses
+     * the preset's named `@position-try` rules (which update both
+     * `position-area` and `margin` on flip) and sets `--ds-arrow-size`.
+     *
+     * Pass `null` to disable. Has no effect in the JS fallback path —
+     * arrows are CSS-only.
+     */
+    arrow?: TArrowPreset | null;
+}): void;

package/dist/types/internal/use-animated-visibility.d.ts

@@ -0,0 +1,74 @@
+import { type RefObject } from 'react';
+import { type TAnimationPreset } from '../animations/types';
+type TUseAnimatedVisibilityArgs = {
+    /**
+     * Whether the element is logically open.
+     */
+    isOpen: boolean;
+    /**
+     * Animation preset for entry/exit transitions.
+     * Pass `false` or `undefined` to disable animation.
+     */
+    animate: TAnimationPreset | false | undefined;
+    /**
+     * Ref to the DOM element that plays the exit transition.
+     * Used to listen for `transitionend`.
+     */
+    elementRef: RefObject<HTMLElement | null>;
+    /**
+     * Called after the exit animation completes (or immediately on close
+     * when there is no animation or reduced motion is active).
+     */
+    onExitFinish?: () => void;
+};
+type TUseAnimatedVisibilityResult = {
+    /**
+     * Whether children should be rendered. Stays `true` during exit
+     * animations so content remains visible while transitioning out.
+     */
+    showChildren: boolean;
+    /**
+     * Resolved animation preset (with CSS injected), or `null` if
+     * animation is disabled.
+     */
+    preset: TAnimationPreset | null;
+};
+/**
+ * Manages the children mount/unmount lifecycle around CSS exit transitions.
+ *
+ * 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
+ * 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.
+ *
+ * ## 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
+ * exit animations:
+ *
+ * ```
+ * isOpen:        true ──────────────── false
+ * showChildren:  true ──────────────── true ─── (exit animation) ─── false
+ * ```
+ *
+ * Two close paths exist:
+ *
+ * 1. **Animated close** (`willAnimate === true`):
+ *    `isOpen` goes `false` → `showChildren` stays `true` → the CSS exit
+ *    transition plays → `transitionend` fires → `showChildren` → `false`
+ *    → `onExitFinish` fires. A timeout fallback ensures we still unmount
+ *    if `transitionend` never fires (e.g. browser quirks, zero-duration).
+ *
+ * 2. **Non-animated close** (`willAnimate === false`):
+ *    `isOpen` goes `false` → `showChildren` → `false` synchronously during
+ *    the same render → `onExitFinish` fires in a follow-up effect.
+ */
+export declare function useAnimatedVisibility({ isOpen, animate, elementRef, onExitFinish, }: TUseAnimatedVisibilityArgs): TUseAnimatedVisibilityResult;
+export {};

package/dist/types/internal/use-animation-preset.d.ts

@@ -0,0 +1,11 @@
+type TPresetWithCssAndName = {
+    css: string;
+    name: string;
+};
+/**
+ * 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.
+ */
+export declare function useAnimationPreset<T extends TPresetWithCssAndName>(animate: T | false | null | undefined): T | null;
+export {};

package/dist/types/internal/use-focus-wrap.d.ts

@@ -0,0 +1,20 @@
+import { type RefObject } from 'react';
+/**
+ * Wraps Tab/Shift+Tab focus within a popover element when its role
+ * semantically requires it (dialog, alertdialog).
+ *
+ * While the popover is open, Tab and Shift+Tab are intercepted
+ * (via `preventDefault`) and remapped to cycle through focusable
+ * elements within the container using wrapping navigation.
+ *
+ * Light dismiss (Escape, click outside) continues to work natively
+ * via `popover="auto"` — this hook only intercepts Tab.
+ *
+ * Always call this hook unconditionally. The listener is only
+ * attached when the role requires focus wrapping, and is cleaned
+ * up and re-evaluated when the role changes.
+ */
+export declare function useFocusWrap({ elementRef, role, }: {
+    elementRef: RefObject<HTMLElement | null>;
+    role: string | undefined;
+}): void;

package/dist/types/internal/use-initial-focus.d.ts

@@ -0,0 +1,21 @@
+import { type RefObject } from 'react';
+/**
+ * Moves focus into a popover element when it opens, based on its ARIA role.
+ *
+ * This implements WCAG 2.4.3 (Focus Order) initial focus placement:
+ * - `dialog` / `alertdialog` → focus first focusable (or `[autofocus]`)
+ * - `menu` → focus first menu item
+ * - `listbox` → focus selected or first option
+ * - `tooltip` / no role → no focus movement
+ *
+ * The role is read from the element's `role` attribute (not passed as a prop),
+ * following the same pattern as `useFocusWrap`.
+ *
+ * Always call this hook unconditionally. Focus is only moved when `isOpen`
+ * transitions to `true` and the role requires it.
+ */
+export declare function useInitialFocus({ elementRef, isOpen, role, }: {
+    elementRef: RefObject<HTMLElement | null>;
+    isOpen: boolean;
+    role: string | undefined;
+}): void;

package/dist/types/internal/use-preset-styles.d.ts

@@ -0,0 +1,15 @@
+type TPresetWithCssAndName = {
+    css: string;
+    name: string;
+};
+/**
+ * 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
+ * (TAnimationPreset) and arrow presets (TArrowPreset) both satisfy this shape.
+ */
+export declare function usePresetStyles<T extends TPresetWithCssAndName>({ preset, }: {
+    preset: T | false | null | undefined;
+}): T | null;
+export {};

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

@@ -0,0 +1,55 @@
+import { type TPlacement } from '../internal/resolve-placement';
+import { type TPlacementOptions } from '../popup/types';
+/**
+ * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
+ * `@atlaskit/tooltip`, etc.).
+ */
+export type TLegacyPlacement = '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';
+/**
+ * Maps legacy Popper.js placement values to the new object-based
+ * `Placement` values used by `@atlaskit/top-layer/popover`.
+ *
+ * **Mapping logic:**
+ *
+ * | Legacy (Popper.js)  | New (Placement object)                              |
+ * | ------------------- | --------------------------------------------------- |
+ * | `top`               | `{ axis: 'block', edge: 'start', align: 'center' }`  |
+ * | `top-start`         | `{ axis: 'block', edge: 'start', align: 'start' }`   |
+ * | `top-end`           | `{ axis: 'block', edge: 'start', align: 'end' }`     |
+ * | `bottom`            | `{ axis: 'block', edge: 'end', align: 'center' }`    |
+ * | `bottom-start`      | `{ axis: 'block', edge: 'end', align: 'start' }`     |
+ * | `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' }`       |
+ *
+ * The `position-try-fallbacks` CSS property handles flipping automatically.
+ *
+ * @example
+ * ```ts
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ *
+ * // In a migration from @atlaskit/popup:
+ * const oldPlacement: TLegacyPlacement = 'bottom-start';
+ * const newPlacement: TPlacementOptions = fromLegacyPlacement({ legacy: oldPlacement });
+ * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
+ * ```
+ */
+declare const placementMapping: Record<TLegacyPlacement, TPlacement>;
+/**
+ * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ */
+export declare function fromLegacyPlacement({ legacy }: {
+    legacy: TLegacyPlacement;
+}): TPlacementOptions;
+/**
+ * The full mapping record, exposed for consumers that need to iterate or introspect.
+ */
+export { placementMapping };
+export type { TPlacementOptions };

package/dist/types/popover/create-close-event.d.ts

@@ -0,0 +1,26 @@
+import { type TPopoverCloseReason } from './types';
+/**
+ * Creates a synthetic DOM event from a `TPopoverCloseReason`.
+ *
+ * Useful when bridging the Popover primitive's `onClose({ reason })` callback
+ * to a legacy API that expects a native DOM event — for example,
+ * `@atlaskit/inline-dialog`'s `onClose(event)` contract.
+ *
+ * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
+ * - `'light-dismiss'` → `MouseEvent('click')`
+ *
+ * For any other reason, a generic `Event('close')` is returned as a fallback.
+ *
+ * @example
+ * ```tsx
+ * import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
+ * import { type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
+ *
+ * function onPopoverClose({ reason }: { reason: TPopoverCloseReason }) {
+ *   legacyOnClose(createPopoverCloseEvent({ reason }));
+ * }
+ * ```
+ */
+export declare function createPopoverCloseEvent({ reason, }: {
+    reason: TPopoverCloseReason;
+}): KeyboardEvent | MouseEvent | Event;

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import React from 'react';
+import { type TPopoverForwardedProps } from './types';
+/**
+ * Unopinionated top-layer primitive.
+ *
+ * Manages only visibility (isOpen) and animation (animate). Has no knowledge
+ * of positioning — compose with `useAnchorPosition` for anchor positioning.
+ *
+ * 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.
+ */
+export declare const Popover: React.ForwardRefExoticComponent<TPopoverForwardedProps & React.RefAttributes<HTMLDivElement>>;