@atlaskit/top-layer 0.13.0 → 0.14.0

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

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

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

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

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

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

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

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

package/dist/types-ts4.5/animations/presets.d.ts

@@ -18,10 +18,10 @@ type TSlideAndFadeOptions = {
  * import { slideAndFade } from '@atlaskit/top-layer/animations';
  *
  * // Default 4px slide (tooltip)
- * <Popup.Content animate={slideAndFade()} />
+ * <Popover animate={slideAndFade()} />
  *
  * // Custom 8px slide (popup / dropdown)
- * <Popup.Content animate={slideAndFade({ distance: 8 })} />
+ * <Popover animate={slideAndFade({ distance: 8 })} />
  * ```
  */
 export declare function slideAndFade(options?: TSlideAndFadeOptions): TAnimationPreset;
@@ -34,7 +34,7 @@ export declare function slideAndFade(options?: TSlideAndFadeOptions): TAnimation
  * ```tsx
  * import { fade } from '@atlaskit/top-layer/animations';
  *
- * <Popup.Content animate={fade()} />
+ * <Popover animate={fade()} />
  * ```
  */
 export declare function fade(): TAnimationPreset;
@@ -47,7 +47,7 @@ export declare function fade(): TAnimationPreset;
  * ```tsx
  * import { scaleAndFade } from '@atlaskit/top-layer/animations';
  *
- * <Popup.Content animate={scaleAndFade()} />
+ * <Popover animate={scaleAndFade()} />
  * ```
  */
 export declare function scaleAndFade(): TAnimationPreset;

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

@@ -1,4 +1,4 @@
-import type { TPlacementOptions } from '../popup/types';
+import type { TPlacementOptions } from '../internal/resolve-placement';
 /**
  * A self-contained animation preset for top-layer elements (popovers and dialogs).
  *

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

@@ -49,14 +49,6 @@ type TDialogBaseProps = {
      * Additional inline styles applied to the `<dialog>` element.
      *
      * Use for custom width, height, transform, or other overrides.
-     *
-     * Rule deviation: the house rules ban unbounded `style` props on
-     * components. `Dialog` is a low-level primitive that intentionally has
-     * no visual opinions of its own; consumers such as `@atlaskit/modal-dialog`
-     * must be able to set width, height, and transforms on the native
-     * `<dialog>` element. Removing this prop would be a breaking change
-     * and is tracked separately. Keep until an xcss-based replacement
-     * exists on the primitive.
      */
     style?: CSSProperties;
     /**

package/dist/types-ts4.5/entry-points/get-aria-for-trigger.d.ts

@@ -0,0 +1 @@
+export { getAriaForTrigger } from '../internal/get-aria-for-trigger';

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

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

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

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

package/dist/types-ts4.5/entry-points/use-popover-id.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Returns a stable HTML `id` used to wire a trigger element to its popover
+ * via ARIA (`aria-controls`) and the Popover API (`popovertarget`).
+ *
+ * The returned value is intended for the `id` attribute on the popover and
+ * for the matching `aria-controls` / `popovertarget` references on the
+ * trigger. It is NOT a CSS `anchor-name` value: CSS anchor positioning is
+ * handled internally by `useAnchorPosition`, which mints and applies its
+ * own `anchor-name` on the trigger element.
+ */
+export declare function usePopoverId(): string;

package/dist/types-ts4.5/internal/get-aria-for-trigger.d.ts

@@ -0,0 +1,86 @@
+import { type TAriaHasPopupValue, type TRoleRequiringAccessibleName } from './role-types';
+/**
+ * Roles accepted by `getAriaForTrigger`.
+ *
+ * Excludes tooltip-family roles (`tooltip`, `note`, `status`, `alert`, `log`)
+ * because the correct trigger wiring for those is `aria-describedby`, not
+ * `aria-haspopup` / `aria-expanded` / `aria-controls`. Use `aria-describedby`
+ * manually for tooltip triggers.
+ */
+type TAriaForTriggerRole = TRoleRequiringAccessibleName | 'listbox' | 'tree' | 'grid';
+type TGetAriaForTriggerOptions = {
+    /**
+     * The `role` that will be set on the `<Popover>` element. Used to derive
+     * the correct `aria-haspopup` value for the trigger.
+     */
+    role: TAriaForTriggerRole;
+    /**
+     * Whether the popover is currently open. Drives `aria-expanded`.
+     */
+    isOpen: boolean;
+    /**
+     * The popover identifier - the value returned by `usePopoverId()`,
+     * passed as `id` to `<Popover>` and referenced here via `aria-controls`.
+     */
+    popoverId: string;
+};
+/**
+ * Non-undefined subset of `TAriaHasPopupValue`. Every role accepted by
+ * `getAriaForTrigger` maps to a concrete `aria-haspopup` string, so the
+ * trigger always receives a defined attribute value.
+ */
+type TAriaHasPopupForTrigger = Exclude<TAriaHasPopupValue, undefined>;
+type TAriaForTrigger = {
+    'aria-haspopup': TAriaHasPopupForTrigger;
+    'aria-expanded': boolean;
+    'aria-controls': string;
+};
+/**
+ * Returns the ARIA attributes to spread onto a click-activated popover trigger.
+ *
+ * Centralises three attributes that are easy to forget or get wrong individually:
+ *
+ * - `aria-haspopup` - derived from the popover's role (e.g. `dialog → "dialog"`,
+ *   `menu → "menu"`, `tooltip → undefined`). React omits the attribute when
+ *   the value is `undefined`.
+ * - `aria-expanded` - reflects the current open state.
+ * - `aria-controls` - references the popover element by its id, even
+ *   while the popover is closed. The relationship is stable; `aria-expanded`
+ *   carries the current visibility state.
+ *
+ * **This function is for click/keyboard-activated popovers only.** For
+ * hover-driven tooltips, the trigger should use `aria-describedby` instead.
+ *
+ * @example
+ * ```tsx
+ * import { getAriaForTrigger } from '@atlaskit/top-layer/get-aria-for-trigger';
+ * import { usePopoverId } from '@atlaskit/top-layer/use-popover-id';
+ *
+ * const popoverId = usePopoverId();
+ * const [isOpen, setIsOpen] = useState(false);
+ *
+ * return (
+ *   <>
+ *     <button
+ *       ref={triggerRef}
+ *       onClick={() => setIsOpen((previous) => !previous)}
+ *       {...getAriaForTrigger({ role: 'dialog', isOpen, popoverId })}
+ *     >
+ *       Open
+ *     </button>
+ *     <Popover
+ *       id={popoverId}
+ *       role="dialog"
+ *       label="My dialog"
+ *       isOpen={isOpen}
+ *       triggerRef={triggerRef}
+ *       onClose={() => setIsOpen(false)}
+ *     >
+ *       …
+ *     </Popover>
+ *   </>
+ * );
+ * ```
+ */
+export declare function getAriaForTrigger({ role, isOpen, popoverId, }: TGetAriaForTriggerOptions): TAriaForTrigger;
+export {};

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

@@ -61,4 +61,11 @@ export type TAriaRoleOptional = ({
 } & TAccessibleNameRequired) | ({
     role?: TRoleWithImplicitName;
 } & TAccessibleNameOptional);
+/**
+ * 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-ts4.5/internal/slot.d.ts

@@ -2,7 +2,7 @@ import { type ForwardRefExoticComponent, type ReactNode, type RefAttributes } fr
 /**
  * Extra DOM/event props are passed through to the cloned child.
  */
-export type TSlotProps = {
+export type SlotProps = {
     children: ReactNode;
 } & Record<string, unknown>;
 /**
@@ -26,4 +26,4 @@ export type TSlotProps = {
  * </Slot>
  * ```
  */
-export declare const Slot: ForwardRefExoticComponent<TSlotProps & RefAttributes<HTMLElement>>;
+export declare const Slot: ForwardRefExoticComponent<SlotProps & RefAttributes<HTMLElement>>;

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

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

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

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

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

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

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

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

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@atlaskit/top-layer",
-	"version": "0.13.0",
+	"version": "0.14.0",
 	"description": "Low-level layering primitives based on popover and dialog",
 	"homepage": "https://atlassian.design/components/top-layer",
 	"repository": "https://bitbucket.org/atlassian/atlassian-frontend-mirror",
@@ -37,8 +37,8 @@
 		"@atlaskit/browser-apis": "^0.0.2",
 		"@atlaskit/css": "^0.19.0",
 		"@atlaskit/ds-lib": "^7.0.0",
-		"@atlaskit/layering": "^3.7.0",
-		"@atlaskit/tokens": "^13.1.0",
+		"@atlaskit/layering": "^3.8.0",
+		"@atlaskit/tokens": "^13.3.0",
 		"@babel/runtime": "^7.0.0",
 		"@compiled/react": "^0.20.0",
 		"bind-event-listener": "^3.0.0",

package/popover-surface/package.json

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

package/use-popover-id/package.json

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

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

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

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

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

package/dist/cjs/popup/index.js

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