@atlaskit/top-layer 0.9.0 → 0.10.0

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

@@ -0,0 +1,39 @@
+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-ts4.5/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>>;

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

@@ -1,7 +1,7 @@
 import { type ReactNode } from 'react';
 import { type StrictXCSSProp } from '@atlaskit/css';
 import { type TAnimationPreset } from '../animations/types';
-import { type TAriaRoleOptional, type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
+import { type TAriaRoleRequired, type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
 import { type TPlacementOptions } from '../popup/types';
 /**
  * The reason a popover was closed.
@@ -31,13 +31,6 @@ export type TPopoverForwardedProps = TPopoverBaseProps & {
     label?: string;
     labelledBy?: string;
 };
-/**
- * Alias for TPopoverForwardedProps.
- *
- * Used internally by PopupContent to forward props to Popover without
- * re-proving the discriminated union at each call site.
- */
-export type TPopoverInternalProps = TPopoverForwardedProps;
 type TPopoverBaseProps = {
     children: ReactNode;
     /**
@@ -70,12 +63,12 @@ type TPopoverBaseProps = {
      *   animation plays (via `allow-discrete`) before the popover becomes logically closed.
      *   Otherwise hides instantly.
      *
-     * The element stays mounted in the DOM at all times — the consumer does not
+     * The element stays mounted in the DOM at all times. The consumer does not
      * conditionally render it. Visibility is driven by this prop.
      *
      * **Important:** For `mode="auto"` popovers, the browser can dismiss the popover
      * via light dismiss (Escape, click outside) independently of this prop. When that
-     * happens, `onClose` is called — the consumer should respond by setting `isOpen`
+     * happens, `onClose` is called and the consumer should respond by setting `isOpen`
      * to `false`. If `isOpen` remains `true` after a browser dismiss, the DOM and
      * React state will be out of sync (the popover will be hidden despite `isOpen={true}`).
      */
@@ -109,14 +102,14 @@ type TPopoverBaseProps = {
      * called to set CSS custom properties (like `--ds-popover-tx`, `--ds-popover-ty`)
      * that control the slide direction. Has no effect without `animate`.
      *
-     * This does NOT control positioning — use `useAnchorPosition` for that.
+     * This does NOT control positioning. Use `useAnchorPosition` for that.
      */
     placement?: TPlacementOptions;
     /**
      * 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. notifying a manager
+     * Use this for external lifecycle coordination, e.g. notifying a manager
      * that the hide sequence is finished, or firing an `onCloseComplete` callback.
      */
     onExitFinish?: () => void;
@@ -124,7 +117,7 @@ type TPopoverBaseProps = {
 /**
  * Unopinionated top-layer primitive.
  *
- * `Popover` manages only top-layer visibility and animation — it has no
+ * `Popover` manages only top-layer visibility and animation. It has no
  * knowledge of positioning. For anchor positioning, compose with the
  * `useAnchorPosition` hook separately.
  *
@@ -135,22 +128,29 @@ type TPopoverBaseProps = {
  * Dismiss behavior:
  * - `'auto'` (default): Escape to close, click-outside to close, focus restoration,
  *   automatic nesting, mutual exclusivity.
- * - `'hint'`: ephemeral UI (e.g. tooltips) that doesn't close other `auto` popovers.
- *   Falls back to `'auto'` in browsers without `popover="hint"` support.
+ * - `'hint'`: ephemeral UI (e.g. tooltips) that does not close other `auto`
+ *   popovers. Falls back silently to `auto` semantics in browsers without
+ *   `popover='hint'` support, meaning the hint will close any other `auto`
+ *   popovers in those browsers. If cross-browser uniformity matters more
+ *   than the no-close behaviour, pass `auto` explicitly.
  * - `'manual'`: no light dismiss. Consumer controls show/hide entirely. Only
  *   appropriate for persistent UI (e.g. flags, banners).
  */
-export type TPopoverProps = TPopoverBaseProps & TAriaRoleOptional & ({
+export type TPopoverProps = TPopoverBaseProps & TAriaRoleRequired & ({
     mode?: 'auto' | 'hint';
     /**
      * Called when the popover is dismissed via light dismiss
      * (Escape, click outside).
      *
+     * Required for `auto` and `hint` modes - without it, browser
+     * dismissals leave the consumer's `isOpen` stuck at `true` while
+     * the DOM is hidden, producing a stale-open state.
+     *
      * The `reason` field indicates how the dismiss occurred:
      * - `'escape'`: the user pressed the Escape key.
      * - `'light-dismiss'`: the user clicked outside (or another auto-dismiss).
      */
-    onClose?: (args: {
+    onClose: (args: {
         reason: TPopoverCloseReason;
     }) => void;
 } | {

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

@@ -12,5 +12,11 @@ import { type TPopupSurfaceProps } from './types';
  * should use `Popup.Content` without wrapping in `PopupSurface`.
  *
  * Exposed as `Popup.Surface` on the compound component.
+ *
+ * **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
+ * `Popup.Content` instead - `PopupSurface` is the no-config "give me the
+ * default ADS overlay look" surface, nothing more.
  */
 export declare function PopupSurface({ children }: TPopupSurfaceProps): React.ReactElement;

package/dist/types-ts4.5/popup/popup-trigger-function.d.ts

@@ -38,10 +38,14 @@ export type TTriggerFunctionRenderProps = {
      *
      * **Note on `aria-haspopup`:** When the content's role maps to a specific
      * popup type (`'menu'`, `'dialog'`, `'listbox'`, etc.), the corresponding
-     * string value is used. For unmapped roles, the value is `true` (boolean).
-     * React serialises `aria-haspopup={true}` as `aria-haspopup="true"` in the
-     * DOM, which is the correct default per the HTML spec. The values can be
-     * spread directly onto trigger elements without conversion.
+     * string value is emitted. For non-popup roles (`tooltip`, `note`,
+     * `status`, `alert`, `log`) the value is `undefined`, so React drops the
+     * attribute entirely - these triggers should not announce a popup.
+     *
+     * The value type (`TAriaHasPopupValue`) is internal and may narrow further
+     * in future minor versions. Do **not** extract it via `Parameters<…>`.
+     * Spread `ariaAttributes` directly onto the trigger; do not destructure
+     * and re-type.
      */
     ariaAttributes: {
         'aria-expanded': boolean;
@@ -53,7 +57,7 @@ type TPopupTriggerFunctionProps = {
     /**
      * Render-prop function that receives trigger props.
      *
-     * Unlike `Popup.Trigger`, this does not use `cloneElement` — the consumer
+     * Unlike `Popup.Trigger`, this does not use `cloneElement`. The consumer
      * is responsible for spreading ref, ARIA attributes, and attaching `toggle`
      * to the appropriate event(s).
      *
@@ -77,7 +81,7 @@ type TPopupTriggerFunctionProps = {
 /**
  * Render-prop alternative to `Popup.Trigger`.
  *
- * Use when you need full control over the trigger element — for example,
+ * Use when you need full control over the trigger element. For example,
  * to compose your own trigger with custom event handlers, wrap a third-party
  * component, or build a trigger from multiple elements.
  *

package/dist/types-ts4.5/popup/popup-trigger.d.ts

@@ -1,23 +1,14 @@
 import { type ReactNode } from 'react';
 import { type TPopupTriggerProps } from './types';
 /**
- * Wraps the trigger element. Attaches aria attributes and handles
- * click to toggle the popover. Sets the anchor-name on the trigger
- * for CSS Anchor Positioning.
+ * Wraps a single trigger element via `cloneElement`. Attaches aria
+ * attributes, the toggle handler, and the anchor-name. `aria-haspopup`
+ * is derived from `Popup.Content`'s role via context.
  *
- * `aria-haspopup` is derived from the content's role via context
- * (set by `Popup.Content`). This ensures the trigger always matches
- * the content's semantic role without the consumer specifying it
- * in two places.
- *
- * **Limitation:** Uses `cloneElement` internally (via `Slot`), which is
- * incompatible with Compiled's `css` prop on the direct child element.
- * The `@jsx jsx` pragma transforms the child before `cloneElement` can
- * inject `onClick` and `ref` onto the DOM node, preventing the popover
- * from opening.
- *
- * If you need Compiled `css` on the trigger, use `Popup.TriggerFunction`
- * instead - it hands you raw props via a render-prop and avoids
- * `cloneElement` entirely.
+ * Child constraints: must be a single ref-forwarding element. The child's
+ * `onClick` is composed (runs after); other event handlers are NOT.
+ * Children using Compiled's `css` prop swallow injected props - use
+ * `Popup.TriggerFunction` for these cases or any time you need handler
+ * composition.
  */
 export declare function PopupTrigger({ children }: TPopupTriggerProps): ReactNode;

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

@@ -1,10 +1,10 @@
 import React from 'react';
 import { type TPopupProps } from './types';
 /**
- * Popup compound — trigger + popover content.
+ * Popup compound: trigger + popover content.
  *
  * Use when a button opens anchored content (dropdown, menu, dialog).
- * The browser manages visibility via `togglePopover()` — the consumer
+ * The browser manages visibility via `togglePopover()`; the consumer
  * never manages `isOpen`. For custom trigger lifecycles (hover, timers,
  * external state), use `Popover` directly instead.
  *

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

@@ -25,26 +25,27 @@ import { type TPopoverCloseReason, type TWidthFromAnchorMode } from '../popover/
  * ```
  */
 export { type TPlacementOptions } from '../internal/resolve-placement';
-export type TPopupProps = {
+/**
+ * Props shared across all `Popup` modes.
+ *
+ * Mode-specific behaviour for `onClose` is encoded in the discriminated
+ * union below: `'auto'` and `'hint'` modes accept an `onClose` handler
+ * (called on light dismiss); `'manual'` mode forbids it (no light dismiss
+ * exists, so a handler would be dead code).
+ */
+type TPopupBaseProps = {
     /**
      * Position of the popup relative to the trigger. Only the Popup compound uses
      * placement; the low-level Popover primitive does not.
+     *
+     * Defaults to `{}` which means "below the trigger, centered, with a
+     * `space.100` token gap".
      */
-    placement: TPlacementOptions;
+    placement?: TPlacementOptions;
     /**
      * Must contain `Popup.Trigger` and `Popup.Content`.
      */
     children: ReactNode;
-    /**
-     * Called when the popup is dismissed via light dismiss.
-     *
-     * The `reason` field indicates how the dismiss occurred:
-     * - `'escape'`: the user pressed the Escape key.
-     * - `'light-dismiss'`: the user clicked outside (or another auto-dismiss).
-     */
-    onClose: (args: {
-        reason: TPopoverCloseReason;
-    }) => void;
     /**
      * Called when the popup's open state changes.
      *
@@ -67,14 +68,6 @@ export type TPopupProps = {
         isOpen: boolean;
         element: HTMLDivElement;
     }) => void;
-    /**
-     * Native popover attribute value. Default is `'auto'`.
-     *
-     * - `'auto'`: light dismiss (Escape, click-outside). Only one `popover="auto"` can be open at a time; opening another closes the previous.
-     * - `'hint'`: allows ephemeral UI (e.g. tooltips) to open without closing other `popover="auto"` popovers. Falls back to `popover="auto"` when unsupported.
-     * - `'manual'`: no light dismiss; the consumer controls show/hide entirely. Escape and click-outside do not close the popover.
-     */
-    mode?: 'auto' | 'hint' | 'manual';
     /**
      * Test ID applied to the popup content element.
      */
@@ -86,6 +79,49 @@ export type TPopupProps = {
      */
     forceFallbackPositioning?: boolean;
 };
+/**
+ * Props for the `Popup` compound.
+ *
+ * Discriminated on `mode`:
+ * - `'auto'` (default) and `'hint'`: light dismiss is enabled; `onClose` is
+ *   optional and is called when the browser dismisses the popover.
+ * - `'manual'`: no light dismiss; `onClose` is `never` since the consumer
+ *   owns show/hide entirely and there is no dismiss event to handle.
+ */
+export type TPopupProps = TPopupBaseProps & ({
+    /**
+     * Native popover attribute value. Default is `'auto'`.
+     *
+     * - `'auto'`: light dismiss (Escape, click-outside). Only one
+     *   `popover="auto"` can be open at a time; opening another closes
+     *   the previous.
+     * - `'hint'`: allows ephemeral UI (e.g. tooltips) to open without
+     *   closing other `popover="auto"` popovers. Falls back to
+     *   `popover="auto"` when unsupported.
+     */
+    mode?: 'auto' | 'hint';
+    /**
+     * Called when the popup is dismissed via light dismiss.
+     *
+     * The `reason` field indicates how the dismiss occurred:
+     * - `'escape'`: the user pressed the Escape key.
+     * - `'light-dismiss'`: the user clicked outside (or another auto-dismiss).
+     */
+    onClose?: (args: {
+        reason: TPopoverCloseReason;
+    }) => void;
+} | {
+    /**
+     * `'manual'`: no light dismiss; the consumer controls show/hide
+     * entirely. Escape and click-outside do not close the popover.
+     */
+    mode: 'manual';
+    /**
+     * Manual mode has no dismiss event, so `onClose` is forbidden.
+     * The consumer owns show/hide via their own state.
+     */
+    onClose?: never;
+});
 export type TPopupTriggerProps = {
     /**
      * The trigger element. Must accept a ref.
@@ -105,7 +141,7 @@ export type TPopupRole = TRoleRequiringAccessibleName | TRoleWithImplicitName;
  *
  * When used standalone (e.g. tooltip, spotlight), the consumer must provide `isOpen`
  * to control visibility. If `animate` is provided, `isOpen` is required at the type
- * level — this ensures exit animations always have a controlled lifecycle.
+ * level. This ensures exit animations always have a controlled lifecycle.
  */
 type TPopupContentBaseProps = {
     children: ReactNode;
@@ -113,6 +149,16 @@ type TPopupContentBaseProps = {
      * Ref to the underlying `<div popover>` element.
      */
     ref?: Ref<HTMLDivElement>;
+    /**
+     * HTML `id` attribute for the popover element.
+     *
+     * Provide this when using `Popup.Content` standalone (outside the
+     * `<Popup>` compound). The consumer is responsible for wiring
+     * `aria-controls` on their own trigger to this same id. Inside the
+     * `<Popup>` compound, the id flows from context - passing it here is
+     * unnecessary.
+     */
+    id?: string;
     /**
      * Controls the width of the popover relative to its anchor element.
      *
@@ -197,7 +243,7 @@ type TPopupContentBaseProps = {
      * Inside the `<Popup>` compound, `isOpen` is provided automatically via context
      * (the browser manages state through `togglePopover()`).
      *
-     * For standalone usage, provide `isOpen` to control visibility — especially
+     * For standalone usage, provide `isOpen` to control visibility, especially
      * when `animate` is set, so the exit animation lifecycle works correctly.
      *
      * @example

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

@@ -2,16 +2,16 @@ import { type RefObject } from 'react';
 import { type TFocusableFilter } from '../focus';
 /**
  * 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
@@ -23,7 +23,7 @@ import { type TFocusableFilter } from '../focus';
  *   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">
@@ -48,6 +48,20 @@ import { type TFocusableFilter } from '../focus';
  * belong to a nested menu.
  */
 export declare function isAtCurrentMenuLevel(element: Element, container: HTMLElement): boolean;
+/**
+ * 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.
+ */
 export type TUseArrowNavigationArgs = {
     /**
      * Ref to the container element that holds the focusable items.
@@ -89,7 +103,7 @@ export type TUseArrowNavigationArgs = {
      * When provided, only elements that pass the filter will be focused.
      *
      * The filter is also used as a guard on the currently focused element:
-     * if the focused element doesn't pass the filter, the handler bails out.
+     * if the focused element does not pass the filter, the handler bails out.
      * This prevents parent menu handlers from acting on events that belong
      * to a nested menu.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.9.0",
+	"version": "0.10.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",

package/popover/create-close-event/package.json

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