@atlaskit/top-layer 0.9.0 → 0.11.0

package/dist/esm/use-arrow-navigation/use-arrow-navigation.js

@@ -7,16 +7,16 @@ var menuScope = '[role="menu"]';
 
 /**
  * Returns true if the element belongs to the current menu level of the
- * container — i.e. it is NOT inside a nested `role="menu"` sub-container.
+ * container, i.e. it is NOT inside a nested `role="menu"` sub-container.
  *
  * Uses `element.closest('[role="menu"]')` to determine the nearest menu
  * scope. If the nearest scope is the container's own `role="menu"` element,
- * the element belongs to this level. If it's a different (nested) menu,
+ * the element belongs to this level. If it is a different (nested) menu,
  * the element belongs to a child level and should be excluded.
  *
  * Supports two container patterns:
  *
- * **1. Container has `role="menu"` directly** (preferred — used by avatar-group):
+ * **1. Container has `role="menu"` directly** (preferred, used by avatar-group):
  *   ```
  *   <div ref={containerRef} role="menu">
  *     <button role="menuitem" />   ← isAtCurrentMenuLevel → true
@@ -28,7 +28,7 @@ var menuScope = '[role="menu"]';
  *   Uses the simple check: `element.closest('[role="menu"]') === container`
  *
  * **2. Container is a wrapper without `role="menu"`** (used by dropdown-menu,
- *   where `MenuGroup` owns `role="menu"` but doesn't accept a ref):
+ *   where `MenuGroup` owns `role="menu"` but does not accept a ref):
  *   ```
  *   <div ref={containerRef}>         ← wrapper (no role="menu")
  *     <MenuGroup role="menu">
@@ -55,7 +55,7 @@ var menuScope = '[role="menu"]';
 export function isAtCurrentMenuLevel(element, container) {
   var closestMenu = element.closest(menuScope);
 
-  // Container itself has role="menu" — element belongs to this level
+  // Container itself has role="menu". Element belongs to this level
   // if its closest menu is the container.
   if (container.getAttribute('role') === 'menu') {
     return closestMenu === container;
@@ -64,18 +64,18 @@ export function isAtCurrentMenuLevel(element, container) {
   // Container is a wrapper without role="menu" (e.g. dropdown-menu
   // wraps a MenuGroup). The element belongs to the top level if its
   // closest role="menu" ancestor is a direct child of the container,
-  // i.e. there's no nested role="menu" between them.
+  // i.e. there is no nested role="menu" between them.
   if (closestMenu === null) {
     return true;
   }
 
-  // Walk up from the closest menu to see if it's "owned" by this
+  // Walk up from the closest menu to see if it is "owned" by this
   // container without passing through another role="menu" first.
   var parent = closestMenu.parentElement;
   while (parent && parent !== container) {
     if (parent.getAttribute('role') === 'menu') {
-      // There's a parent menu between the closest menu and the
-      // container — the element is in a nested sub-menu.
+      // There is a parent menu between the closest menu and the
+      // container, so the element is in a nested sub-menu.
       return false;
     }
     parent = parent.parentElement;
@@ -84,6 +84,22 @@ export function isAtCurrentMenuLevel(element, container) {
   // The closest menu is directly inside the container (no nesting).
   return parent === container;
 }
+
+/**
+ * Args for `useArrowNavigation`.
+ *
+ * Keyboard contract:
+ * - `ArrowDown` / `ArrowUp` move within the current menu level.
+ * - `Home` / `End` jump to first / last.
+ * - `ArrowRight` / `ArrowLeft` opens / closes nested submenus.
+ * - `Tab` / `Shift+Tab` dismiss the menu (matching the ARIA APG menu pattern,
+ *   plus Radix UI / Headless UI / React Aria / Floating UI conventions).
+ *   Symmetric in both directions: there is no special-case for the last
+ *   item that lets Tab leave the menu without dismissing it.
+ * - `Page Up` / `Page Down`: NOT handled - extend via your own listener if
+ *   your menu needs page-style scrolling.
+ */
+
 /**
  * Provides arrow key navigation for menu containers.
  *
@@ -215,7 +231,7 @@ export function useArrowNavigation(_ref) {
       if (onNestedClose) {
         var _container$parentElem;
         // Only close if this container is inside another role="menu"
-        // (i.e. it's a submenu, not the top-level menu).
+        // (i.e. it is a submenu, not the top-level menu).
         // Walk up from the parent to avoid matching the container itself.
         var isNested = ((_container$parentElem = container.parentElement) === null || _container$parentElem === void 0 ? void 0 : _container$parentElem.closest(menuScope)) !== null;
         if (isNested) {

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

@@ -0,0 +1,24 @@
+import { type TArrowPreset } from './types';
+/**
+ * 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
+ * do not 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} />
+ * ```
+ */
+export declare const arrow: () => TArrowPreset;
+export type { TArrowPreset } from './types';

package/dist/types/arrow/types.d.ts

@@ -0,0 +1,29 @@
+import type { TPlacementOptions } from '../popup/types';
+/**
+ * A self-contained arrow preset for PopoverContent.
+ *
+ * Contains the CSS rules (injected once into `<head>`), a data-attribute name
+ * for CSS targeting, and a function to compute `position-try-fallbacks` values
+ * that change both `position-area` and `margin` when the popover flips.
+ *
+ * Imported from `@atlaskit/top-layer/arrow` so that consumers who do not use
+ * arrows pay no bundle cost for the CSS string or fallback logic.
+ */
+export type TArrowPreset = {
+    /**
+     * CSS to inject once into `document.head`, scoped to `[data-ds-popover-{name}]`.
+     */
+    css: string;
+    /**
+     * Data attribute suffix for CSS targeting (e.g. `'arrow'`).
+     */
+    name: string;
+    /**
+     * Returns the `position-try-fallbacks` value for a given placement.
+     * Uses named `@position-try` rules that update both `position-area`
+     * and `margin` so the correct arrow is revealed after a flip.
+     */
+    getTryFallbacks: (args: {
+        placement: TPlacementOptions;
+    }) => string;
+};

package/dist/types/dialog/dialog-content.d.ts

@@ -5,7 +5,7 @@
 import React from 'react';
 import { type TDialogProps } from './types';
 /**
- * Low-level `<dialog>` primitive. No visual opinions — no width, height,
+ * Low-level `<dialog>` primitive. No visual opinions - no width, height,
  * background, border-radius, or layout. Consumers provide their own styling.
  *
  * Visibility is controlled declaratively via `isOpen`:
@@ -16,5 +16,9 @@ import { type TDialogProps } from './types';
  *
  * Close flow: we never call `dialog.close()` from event handlers. We always call
  * `onClose`; the consumer decides whether to set `isOpen={false}`.
+ *
+ * Accessibility: render at least one focusable element (typically a close
+ * button) when `isOpen` becomes `true`. Tab is always trapped inside the
+ * dialog, so keyboard users need somewhere to land.
  */
 export declare const Dialog: React.ForwardRefExoticComponent<TDialogProps & React.RefAttributes<HTMLDialogElement>>;

package/dist/types/dialog/types.d.ts

@@ -3,23 +3,21 @@ import { type TAnimationPreset } from '../animations/types';
 /**
  * Close reasons produced by the Dialog primitive.
  *
- * - `'escape'` — user pressed Escape (native `cancel` event on `<dialog>`).
- * - `'overlay-click'` — user clicked the backdrop / overlay area.
+ * - `'escape'`: user pressed Escape (native `cancel` event on `<dialog>`).
+ * - `'overlay-click'`: user clicked the backdrop / overlay area.
  *
  * Consumer-initiated ("programmatic") close is not a reason the primitive
- * produces — the consumer simply sets `isOpen={false}`.
+ * produces. The consumer simply sets `isOpen={false}`.
  */
 export type TDialogCloseReason = 'escape' | 'overlay-click';
 /**
- * Props for the `Dialog` primitive.
+ * Props shared across `TDialogProps` variants.
  *
- * Low-level wrapper around the native `<dialog>` element.
- * Manages visibility (`showModal()` / `close()`), animation, Escape handling,
- * and backdrop-click detection. Has no visual opinions — no width, height,
- * background, border-radius, or layout. Consumers (e.g. `@atlaskit/modal-dialog`)
- * provide their own visual styling.
+ * The accessible-name requirement (one of `label` or `labelledBy`) is encoded
+ * in the discriminated union below - WCAG 4.1.2 violations are caught at
+ * compile time instead of in production audit reports.
  */
-export type TDialogProps = {
+type TDialogBaseProps = {
     children: ReactNode;
     /**
      * Whether the dialog is open.
@@ -28,13 +26,13 @@ export type TDialogProps = {
      * - `false`: calls `close()`. When an `animate` preset is provided, the exit
      *   animation plays (via `allow-discrete`) before the dialog becomes logically closed.
      *
-     * The element stays mounted in the DOM — visibility is controlled declaratively.
+     * The element stays mounted in the DOM. Visibility is controlled declaratively.
      */
     isOpen: boolean;
     /**
      * Called when the user triggers close via Escape or backdrop click.
      *
-     * The dialog does **not** close itself — the consumer decides whether to
+     * The dialog does **not** close itself. The consumer decides whether to
      * set `isOpen={false}` (e.g. gate by reason).
      */
     onClose: (args: {
@@ -61,32 +59,60 @@ export type TDialogProps = {
      * HTML `id` attribute for the `<dialog>` element.
      */
     id?: string;
+    /**
+     * When true, the `::backdrop` pseudo-element is rendered transparent.
+     *
+     * Useful for stacked dialogs where only the foreground dialog should
+     * show a visible backdrop, or when the consumer wants no overlay.
+     */
+    shouldHideBackdrop?: boolean;
+    /**
+     * Called after the exit animation completes (or immediately on close when
+     * there is no animation or reduced motion is active).
+     *
+     * Use this for external lifecycle coordination, e.g. firing an
+     * `onCloseComplete` callback or notifying ExitingPersistence.
+     */
+    onExitFinish?: () => void;
+};
+/**
+ * Props for the `Dialog` primitive.
+ *
+ * Low-level wrapper around the native `<dialog>` element.
+ * Manages visibility (`showModal()` / `close()`), animation, Escape handling,
+ * and backdrop-click detection. Has no visual opinions - no width, height,
+ * background, border-radius, or layout. Consumers (e.g. `@atlaskit/modal-dialog`)
+ * provide their own visual styling.
+ *
+ * Discriminated on the accessible-name source: at least one of `label`
+ * (aria-label) or `labelledBy` (aria-labelledby) must be provided. This
+ * enforces WCAG 4.1.2 at the type level - an unlabelled dialog landmark
+ * is not constructible. Mirrors the pattern used by `TPopupContentProps`.
+ */
+export type TDialogProps = TDialogBaseProps & ({
     /**
      * Accessible label (`aria-label`).
      *
      * When provided, `aria-labelledby` is not set.
      * Use when there is no visible title element to reference.
      */
-    label?: string;
+    label: string;
     /**
      * ID of the element that labels the dialog (`aria-labelledby`).
      *
      * Ignored when `label` is provided.
      */
     labelledBy?: string;
+} | {
     /**
-     * When true, the `::backdrop` pseudo-element is rendered transparent.
+     * Accessible label (`aria-label`).
      *
-     * Useful for stacked dialogs where only the foreground dialog should
-     * show a visible backdrop, or when the consumer wants no overlay.
+     * Optional when `labelledBy` is provided.
      */
-    shouldHideBackdrop?: boolean;
+    label?: string;
     /**
-     * Called after the exit animation completes (or immediately on close when
-     * there is no animation or reduced motion is active).
-     *
-     * Use this for external lifecycle coordination — e.g. firing an
-     * `onCloseComplete` callback or notifying ExitingPersistence.
+     * ID of the element that labels the dialog (`aria-labelledby`).
      */
-    onExitFinish?: () => void;
-};
+    labelledBy: string;
+});
+export {};

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

@@ -1,3 +1,10 @@
+/**
+ * @deprecated Combined entry-point retained for backwards-compatibility.
+ * Prefer the disjoint subpaths so that bundle analysis attributes the cost
+ * to the right consumer:
+ *   - `@atlaskit/top-layer/dialog/create-close-event` for `createCloseEvent`
+ *   - `@atlaskit/top-layer/popover/create-close-event` for `createPopoverCloseEvent`
+ */
 export { createCloseEvent } from '../dialog';
 export { createPopoverCloseEvent } from '../popover/create-close-event';
 export type { TDialogCloseReason } from '../dialog';

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

@@ -0,0 +1,2 @@
+export { createCloseEvent } from '../../dialog/create-close-event';
+export type { TDialogCloseReason } from '../../dialog/types';

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

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

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

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

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

@@ -9,6 +9,14 @@
  * All public functions accept an optional `filter` callback to further
  * restrict which focusable elements are included.
  */
+/**
+ * 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`).
+ */
+export declare function isNestedLayerFocused({ container }: {
+    container: HTMLElement;
+}): boolean;
 /**
  * An optional callback to restrict which focusable elements are included.
  * Return `true` to include the element, `false` to skip it.

package/dist/types/internal/resolve-css-length-to-pixels.d.ts

@@ -8,13 +8,11 @@
  * the browser do the math.
  *
  * The probe is appended to `container` so it inherits the same containing
- * block, font size, and custom-property scope as the popover. We use `width`
- * because it accepts any CSS length, including negative `calc()` results
- * (negative widths are clamped to 0 — see note below).
+ * block, font size, and custom-property scope as the popover.
  *
- * Cost: one synchronous reflow per call. The fallback only resolves on
- * placement/offset changes, not on every scroll/resize update, so this is
- * not a hot path.
+ * Cost: one synchronous reflow on first cacheable resolution per
+ * (container, value) pair, then a `WeakMap` lookup. Resolutions involving
+ * `var(` are intentionally not cached.
  */
 export declare function resolveCssLengthToPixels({ value, container, }: {
     value: number | string;

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

@@ -1,8 +1,17 @@
 /**
  * Valid values for the `aria-haspopup` attribute.
- * Derived from the HTML spec — maps popover roles to what the trigger announces.
+ *
+ * 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.
  */
-export type TAriaHasPopupValue = 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | true;
+export type TAriaHasPopupValue = 'dialog' | 'menu' | 'listbox' | 'tree' | 'grid' | undefined;
 /**
  * Roles that require an accessible name (`label` or `labelledBy`) per WCAG 4.1.2.
  * Without a name, assistive technology cannot identify these landmarks.
@@ -33,7 +42,7 @@ type TAccessibleNameOptional = {
 /**
  * ARIA role props where a role is always required.
  *
- * Used by `TPopupContentProps` — popup content must always declare
+ * Used by `TPopupContentProps`. Popup content must always declare
  * its role so assistive technology can identify the layer.
  */
 export type TAriaRoleRequired = ({
@@ -44,7 +53,7 @@ export type TAriaRoleRequired = ({
 /**
  * ARIA role props where a role is optional.
  *
- * Used by `TPopoverProps` — the low-level primitive allows omitting
+ * Used by `TPopoverProps`. The low-level primitive allows omitting
  * the role for cases where it is set externally or not needed.
  */
 export type TAriaRoleOptional = ({
@@ -55,8 +64,20 @@ export type TAriaRoleOptional = ({
 /**
  * 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.
  */
 export declare function roleToAriaHasPopup({ role, }: {
     role: TRoleRequiringAccessibleName | TRoleWithImplicitName | undefined;
 }): TAriaHasPopupValue;
+/**
+ * Returns `true` when the given popover role moves focus into the popover
+ * on open, and `false` otherwise (including when `role` is `undefined`).
+ */
+export declare function shouldFocusIntoPopover({ role, }: {
+    role: TRoleRequiringAccessibleName | TRoleWithImplicitName | undefined;
+}): boolean;
 export {};

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

@@ -1,23 +1,6 @@
 /**
- * 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();
- * ```
+ * Sets inline styles on an element and returns a cleanup function that
+ * restores the prior inline values (so we do not stomp consumer styles).
  */
 export declare function setStyle({ el, styles, }: {
     el: HTMLElement;

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

@@ -14,7 +14,6 @@
  */
 import { type RefObject } from 'react';
 import { type TPlacementOptions } from '../internal/resolve-placement';
-export { getPlacement } from './resolve-placement';
 /**
  * Resolves placement options to CSS `position-area` syntax.
  *
@@ -59,7 +58,7 @@ export declare function placementToPositionArea({ placement }: {
  * top-right), flipping only the primary axis (`flip-inline`) moves the popup
  * to the left but keeps the same cross-axis span direction (e.g. upward),
  * which is still off-screen. The combined keyword `flip-inline flip-block`
- * mirrors the popup diagonally — it flips BOTH the position-area AND both
+ * mirrors the popup diagonally. It flips BOTH the position-area AND both
  * inline and block margins simultaneously, placing the popup at the
  * diagonally opposite corner where there is always space.
  *
@@ -74,7 +73,7 @@ export declare function placementToTryFallbacks({ placement }: {
  * 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,
+ * 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.
  *

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

@@ -2,14 +2,15 @@ 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:
+ * Follows the WAI-ARIA APG initial-focus patterns for each role:
  * - `dialog` / `alertdialog` → focus first focusable (or `[autofocus]`)
  * - `menu` → focus first menu item
  * - `listbox` → focus selected or first option
- * - `tooltip` / no role → no focus movement
+ * - `tooltip` / no role → no focus movement (focus must remain on trigger;
+ *   moving focus into the tooltip would dismiss it)
  *
- * The role is read from the element's `role` attribute (not passed as a prop),
- * following the same pattern as `useFocusWrap`.
+ * Role is taken from the typed `role` prop - this is the consumer's contract
+ * and is not subject to drift from a directly-mutated DOM attribute.
  *
  * Always call this hook unconditionally. Focus is only moved when `isOpen`
  * transitions to `true` and the role requires it.

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

@@ -1,9 +1,5 @@
 import { type TPlacementOptions } from '../internal/resolve-placement';
-/**
- * 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';
+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`.
@@ -14,9 +10,11 @@ export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top
  * | ------------------- | --------------------------------------------------- |
  * | `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' }`    |
@@ -28,7 +26,10 @@ export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top
  * | `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.
+ * `auto*` is mapped to `block-end` (a reduction in expressiveness vs Popper's
+ * runtime auto-flip). CSS `position-try-fallbacks` provides flipping at the
+ * edge - but the initial placement is fixed. If migrating away from Popper's
+ * dynamic auto, prefer an explicit placement.
  *
  * @example
  * ```ts
@@ -40,22 +41,8 @@ export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top
  * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
  * ```
  */
-declare const placementMapping: Record<TLegacyPlacement, TPlacementOptions>;
-/**
- * Convert a legacy Popper.js placement to the new `position-area`-based Placement.
- * Optional `offset` is the legacy Popper `[along, away]` tuple (also known as
- * `[skidding, distance]`); negative `along` becomes `direction: 'backwards'`.
- *
- * The tuple keeps the historical popper names so call sites that already pass
- * `[along, away]` migrate without thinking; the new internal field names
- * (`gap` / `crossAxisShift`) are produced inside this adapter.
- */
 export declare function fromLegacyPlacement({ legacy, offset, }: {
     legacy: TLegacyPlacement;
     offset?: [along: number, away: number];
 }): TPlacementOptions;
-/**
- * The full mapping record, exposed for consumers that need to iterate or introspect.
- */
-export { placementMapping };
-export type { TPlacementOptions };
+export type { TLegacyPlacement, TPlacementOptions };

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

@@ -0,0 +1,21 @@
+import { type TPlacementOptions } from '../internal/resolve-placement';
+/**
+ * Legacy Popper.js placement values (used by `@atlaskit/popper`,
+ * `@atlaskit/popup`, `@atlaskit/tooltip`, etc.). Re-exported from
+ * `@atlaskit/top-layer/placement-map` for migration consumers that need
+ * to enumerate every placement (e.g. for a settings dropdown). New code
+ * should use the object-based `TPlacementOptions` directly.
+ */
+export declare const LEGACY_PLACEMENTS: readonly ["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"];
+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/popover/popover.d.ts

@@ -18,7 +18,7 @@ import { type TPopoverForwardedProps } from './types';
  *
  * 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
+ * consumer must set `isOpen` to `false`. The DOM owns the dismiss; React
  * must follow.
  */
 export declare const Popover: React.ForwardRefExoticComponent<TPopoverForwardedProps & React.RefAttributes<HTMLDivElement>>;