@atlaskit/top-layer 0.1.0

package/dist/types/popup/types.d.ts

@@ -0,0 +1,289 @@
+import { type ReactElement, type ReactNode, type Ref, type RefObject } from 'react';
+import { type TAnimationPreset } from '../animations/types';
+import { type TArrowPreset } from '../arrow/types';
+import { type TPlacement } from '../internal/resolve-placement';
+import { type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
+import { type TPopoverCloseReason } from '../popover/types';
+/**
+ * Describes where to position a popover relative to its trigger.
+ *
+ * - `axis` — which axis the popover appears along (`'block'` = above/below, `'inline'` = left/right).
+ *   Defaults to `'block'`.
+ * - `edge` — which end of the axis (`'start'` = above/left in LTR, `'end'` = below/right in LTR).
+ *   Defaults to `'end'`.
+ * - `align` — where to align on the cross-axis (`'start'`, `'center'`, `'end'`).
+ *   Defaults to `'center'`. Can be written explicitly for clarity.
+ *
+ * All fields are optional. The default `{}` means "below the trigger, centered"
+ * (equivalent to Popper.js `'bottom'`).
+ *
+ * @example
+ * ```ts
+ * // Below trigger, centered (all defaults)
+ * placement={{}}
+ * placement={{ axis: 'block', edge: 'end', align: 'center' }}
+ *
+ * // Below trigger, aligned to the start (left in LTR)
+ * placement={{ align: 'start' }}
+ *
+ * // Above trigger, aligned to the end (right in LTR)
+ * placement={{ edge: 'start', align: 'end' }}
+ *
+ * // Right of trigger, centered
+ * placement={{ axis: 'inline' }}
+ * ```
+ */
+export type TPlacementOptions = Partial<TPlacement>;
+export type TPopupProps = {
+    /**
+     * Position of the popup relative to the trigger. Only the Popup compound uses
+     * placement; the low-level Popover primitive does not.
+     */
+    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.
+     *
+     * Receives the new open state and a reference to the popover element,
+     * which is useful for focus management (e.g. focusing the first interactive
+     * child on open via `getFirstFocusable` from `@atlaskit/top-layer/focus`).
+     *
+     * @example
+     * ```tsx
+     * <Popup
+     *   onOpenChange={({ isOpen, element }) => {
+     *     if (isOpen) {
+     *       getFirstFocusable({ container: element })?.focus();
+     *     }
+     *   }}
+     * />
+     * ```
+     */
+    onOpenChange?: (args: {
+        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.
+     */
+    testId?: string;
+    /**
+     * 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;
+};
+export type TPopupTriggerProps = {
+    /**
+     * The trigger element. Must accept a ref.
+     */
+    children: ReactElement;
+};
+/**
+ * All ARIA roles supported for popover content.
+ * Add new roles to the appropriate category in `internal/role-types.tsx` as needed.
+ */
+export type TPopupRole = TRoleRequiringAccessibleName | TRoleWithImplicitName;
+/**
+ * Props shared across all popover role variants.
+ *
+ * When inside the `<Popup>` compound component, `isOpen` is provided automatically
+ * via context (the browser manages visibility through `togglePopover()`).
+ *
+ * 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.
+ */
+type TPopupContentBaseProps = {
+    children: ReactNode;
+    /**
+     * Ref to the underlying `<div popover>` element.
+     */
+    ref?: Ref<HTMLDivElement>;
+    /**
+     * Controls the width of the popover.
+     *
+     * - `'content'` (default): popover sizes to its content.
+     * - `'trigger'`: popover matches the trigger element's width exactly
+     *   via CSS `anchor-size(width)`. Falls back to a one-off measurement
+     *   of `triggerRef.current.offsetWidth` when CSS Anchor Positioning
+     *   is not supported.
+     * - `'min-trigger'`: popover is at least as wide as the trigger, but
+     *   can grow wider if content requires it. Uses `min-width: anchor-size(width)`.
+     *   Falls back to a one-off measurement of the trigger's width.
+     */
+    width?: 'content' | 'trigger' | 'min-trigger';
+    /**
+     * Ref to the trigger element for anchor positioning.
+     * When absent, anchor positioning is skipped (consumer handles positioning).
+     */
+    triggerRef?: RefObject<HTMLElement | null>;
+    /**
+     * Position of the popover relative to the trigger.
+     */
+    placement?: TPlacementOptions;
+    /**
+     * Called when the popover is dismissed via light dismiss (Escape, click outside).
+     * When an animation preset is provided, `onClose` is called after the exit
+     * animation completes.
+     *
+     * 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;
+    /**
+     * Test ID applied to the popover content element.
+     */
+    testId?: string;
+    /**
+     * Gap between the popover and its trigger, in pixels.
+     * Defaults to 8 (design token `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, renders CSS arrows that automatically flip when the
+     * popover flips via `@position-try` fallbacks. The arrows inherit
+     * their background color from the popover element.
+     *
+     * @example
+     * ```tsx
+     * import { arrow } from '@atlaskit/top-layer/arrow';
+     *
+     * const myArrow = arrow();
+     * <Popup.Content arrow={myArrow} />
+     * ```
+     *
+     * Constraints:
+     * - `box-shadow` is disabled on the popover (incompatible with the
+     *   `clip-path: inset() margin-box` technique)
+     * - `::before` and `::after` pseudo-elements are consumed by the arrows
+     * - Only works with CSS Anchor Positioning; no arrow in the JS fallback
+     */
+    arrow?: false | TArrowPreset;
+    /**
+     * 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. When the browser does not support `popover="hint"`, the component automatically falls back to `popover="auto"`; this fallback is transparent to the consumer.
+     * - `'manual'`: no light dismiss; the consumer controls show/hide entirely (e.g. Flag). Escape and click-outside do not close the popover.
+     */
+    mode?: 'auto' | 'hint' | 'manual';
+    /**
+     * Animation preset for entry/exit transitions.
+     *
+     * - `TAnimationPreset`: a preset object (e.g. from `@atlaskit/top-layer/animations`).
+     *   Entry animation plays via `@starting-style`, exit via `allow-discrete`.
+     * - `undefined` / `false`: no animation.
+     *
+     * When used standalone (outside `<Popup>` compound), pair with `isOpen` for exit
+     * animations to work correctly. Inside the compound, `isOpen` is provided via context.
+     *
+     * Animations use `@starting-style` and `allow-discrete` for progressive
+     * enhancement: browsers without support show/hide instantly.
+     */
+    animate?: false | TAnimationPreset;
+    /**
+     * Whether the popover is open.
+     *
+     * Controls `showPopover()` / `hidePopover()` on the underlying element.
+     * 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
+     * when `animate` is set, so the exit animation lifecycle works correctly.
+     *
+     * @example
+     * ```tsx
+     * <Popup.Content
+     *   role="tooltip"
+     *   isOpen={isVisible}
+     *   animate={slideAndFade()}
+     * >
+     *   Tooltip content
+     * </Popup.Content>
+     * ```
+     */
+    isOpen?: boolean;
+};
+/**
+ * Popup content props.
+ *
+ * Roles like `'dialog'`, `'alertdialog'`, and `'menu'` require an accessible
+ * name. Provide either `label` (aria-label) or `labelledBy` (aria-labelledby).
+ * TypeScript enforces this at compile time.
+ */
+export type TPopupContentProps = TPopupContentBaseProps & (({
+    /**
+     * ARIA role for the popover. Roles that are ARIA landmarks (`dialog`,
+     * `alertdialog`, `menu`) require an accessible name.
+     */
+    role: TRoleRequiringAccessibleName;
+} & ({
+    /**
+     * Accessible name via `aria-label`.
+     */
+    label: string;
+    /**
+     * Accessible name via `aria-labelledby`.
+     */
+    labelledBy?: string;
+} | {
+    /**
+     * Accessible name via `aria-label`.
+     */
+    label?: string;
+    /**
+     * Accessible name via `aria-labelledby`.
+     */
+    labelledBy: string;
+})) | {
+    /**
+     * ARIA role for the popover.
+     */
+    role: TRoleWithImplicitName;
+    /**
+     * Accessible name via `aria-label`.
+     */
+    label?: string;
+    /**
+     * Accessible name via `aria-labelledby`.
+     */
+    labelledBy?: string;
+});
+export type TPopupSurfaceProps = {
+    children: ReactNode;
+};
+export {};

package/dist/types/use-arrow-navigation/index.d.ts

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

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

@@ -0,0 +1,136 @@
+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.
+ *
+ * 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 a child level and should be excluded.
+ *
+ * Supports two container patterns:
+ *
+ * **1. Container has `role="menu"` directly** (preferred — used by avatar-group):
+ *   ```
+ *   <div ref={containerRef} role="menu">
+ *     <button role="menuitem" />   ← isAtCurrentMenuLevel → true
+ *     <div role="menu">            ← nested sub-menu
+ *       <button role="menuitem" /> ← isAtCurrentMenuLevel → false
+ *     </div>
+ *   </div>
+ *   ```
+ *   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):
+ *   ```
+ *   <div ref={containerRef}>         ← wrapper (no role="menu")
+ *     <MenuGroup role="menu">
+ *       <button role="menuitem" />   ← isAtCurrentMenuLevel → true
+ *       <div role="menu">            ← nested sub-menu
+ *         <button role="menuitem" /> ← isAtCurrentMenuLevel → false
+ *       </div>
+ *     </MenuGroup>
+ *   </div>
+ *   ```
+ *   Falls back to walking the DOM to check that the element's closest
+ *   `role="menu"` is the container's own menu (not doubly nested).
+ *
+ * Ideally all consumers should use pattern 1 (place the ref directly on the
+ * `role="menu"` element). Pattern 2 exists because `@atlaskit/menu`'s
+ * `MenuGroup` does not currently accept a ref. If `MenuGroup` gains ref
+ * support in the future, dropdown-menu should switch to pattern 1 and the
+ * fallback path can be removed.
+ *
+ * Used both as a `TFocusableFilter` (to scope getNextFocusable etc.) and as
+ * a guard to prevent parent menu handlers from acting on events that
+ * belong to a nested menu.
+ */
+export declare function isAtCurrentMenuLevel(element: Element, container: HTMLElement): boolean;
+export type TUseArrowNavigationArgs = {
+    /**
+     * Ref to the container element that holds the focusable items.
+     */
+    containerRef: RefObject<HTMLElement | null>;
+    /**
+     * Called when ArrowRight is pressed on a focused element with `aria-haspopup`.
+     *
+     * This follows the WAI-ARIA menu pattern: ArrowRight on a menu item that
+     * controls a submenu should open that submenu. The consumer decides *how*
+     * to open it (e.g. `trigger.click()`, imperative state update, etc.).
+     *
+     * Only fires when `filter` (if provided) confirms the focused element
+     * belongs to the current menu level.
+     */
+    onNestedOpen?: ({ trigger }: {
+        trigger: HTMLElement;
+    }) => void;
+    /**
+     * Called when ArrowLeft is pressed and the current menu is nested
+     * (i.e. the container is inside another `role="menu"`).
+     *
+     * This follows the WAI-ARIA menu pattern: ArrowLeft in a submenu
+     * should close it and return to the parent menu. The consumer
+     * decides *how* to close (e.g. calling their close handler).
+     */
+    onNestedClose?: () => void;
+    /**
+     * Called when the user presses Tab to exit the menu.
+     */
+    onClose: () => void;
+    /**
+     * When false, the keydown listener is not attached.
+     * Defaults to true.
+     */
+    isEnabled?: boolean;
+    /**
+     * Optional filter to restrict which focusable elements are navigated.
+     * 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.
+     * This prevents parent menu handlers from acting on events that belong
+     * to a nested menu.
+     *
+     * A common filter is `isAtCurrentMenuLevel` which excludes items inside
+     * nested `role="menu"` sub-containers.
+     */
+    filter?: TFocusableFilter;
+};
+/**
+ * Provides arrow key navigation for menu containers.
+ *
+ * Uses the focusable helpers from `@atlaskit/top-layer/focus` to manage
+ * DOM-based focus movement within a container.
+ *
+ * - **ArrowDown / ArrowUp**: Move focus to the next/previous item (wraps).
+ * - **Home / End**: Move focus to the first/last item.
+ * - **Tab**: Calls `onClose` to exit the menu.
+ *
+ * When a `filter` is provided, it is used both for scoping focusable
+ * elements and as a guard to prevent parent menu handlers from acting
+ * on events that belong to a nested menu.
+ *
+ * @example Basic usage
+ * ```tsx
+ * useArrowNavigation({
+ *   containerRef: menuRef,
+ *   onClose: () => setIsOpen(false),
+ *   isEnabled: isOpen,
+ * });
+ * ```
+ *
+ * @example With nested menu filter
+ * ```tsx
+ * import { useArrowNavigation, isAtCurrentMenuLevel } from '@atlaskit/top-layer/use-arrow-navigation';
+ *
+ * useArrowNavigation({
+ *   containerRef: menuRef,
+ *   onClose: () => setIsOpen(false),
+ *   isEnabled: isOpen,
+ *   filter: isAtCurrentMenuLevel,
+ * });
+ * ```
+ */
+export declare function useArrowNavigation({ containerRef, onClose, onNestedOpen, onNestedClose, isEnabled, filter, }: TUseArrowNavigationArgs): void;

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

@@ -0,0 +1,45 @@
+import { type RefObject } from 'react';
+import { type TPopoverCloseReason } from '../popover/types';
+type TUseSimpleLightDismissOptions = {
+    /**
+     * Ref to the popover element. Clicks inside this element will not trigger dismiss.
+     */
+    popoverRef: RefObject<HTMLElement | null>;
+    /**
+     * Whether the popover is currently open.
+     * Listeners are only bound when `isOpen` is `true`.
+     */
+    isOpen: boolean;
+    /**
+     * Called when a light-dismiss event occurs.
+     *
+     * - `reason: 'escape'` — the user pressed the Escape key.
+     * - `reason: 'light-dismiss'` — the user clicked outside the popover.
+     *
+     * **Note:** This hook provides simple, standalone light dismiss that does not
+     * participate in the browser's `popover="auto"` dismiss stack. Every active
+     * instance will fire independently — if multiple popovers use this hook,
+     * they will all receive dismiss events.
+     */
+    onClose: (args: {
+        reason: TPopoverCloseReason;
+    }) => void;
+};
+/**
+ * Simple light-dismiss hook for `popover="manual"` elements.
+ *
+ * Provides Escape-to-close and click-outside-to-close behavior without
+ * relying on the browser's `popover="auto"` light-dismiss stack.
+ *
+ * **No stacking awareness:** This hook does not track a popover stack.
+ * If multiple manual popovers are open and all use this hook, a single
+ * Escape press or outside click will dismiss **all of them simultaneously**.
+ * This is by design — the hook is intentionally simple for cases where
+ * only one manual popover is open at a time.
+ *
+ * For stacked/nested popovers that should dismiss one-at-a-time, use
+ * `popover="auto"` mode instead, which provides native stack-aware
+ * light dismiss via the browser's top-layer stack.
+ */
+export declare function useSimpleLightDismiss({ popoverRef, isOpen, onClose, }: TUseSimpleLightDismissOptions): void;
+export type { TUseSimpleLightDismissOptions };

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

@@ -0,0 +1,94 @@
+import { type TAnimationPreset } from './types';
+type TSlideAndFadeOptions = {
+    /**
+     * Slide distance in pixels. Defaults to `4`.
+     */
+    distance?: number;
+};
+/**
+ * Directional slide + opacity animation.
+ *
+ * The popover slides in from the direction opposite its placement edge
+ * (e.g. a `block-end` popover slides down from above).
+ *
+ * @param options.distance - Slide distance in pixels. Defaults to `4`.
+ *
+ * @example
+ * ```tsx
+ * import { slideAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * // Default 4px slide (tooltip)
+ * <Popup.Content animate={slideAndFade()} />
+ *
+ * // Custom 8px slide (popup / dropdown)
+ * <Popup.Content animate={slideAndFade({ distance: 8 })} />
+ * ```
+ */
+export declare function slideAndFade(options?: TSlideAndFadeOptions): TAnimationPreset;
+/**
+ * Simple opacity transition, no transform.
+ *
+ * Suitable for popup dialogs or content that does not need directional motion.
+ *
+ * @example
+ * ```tsx
+ * import { fade } from '@atlaskit/top-layer/animations';
+ *
+ * <Popup.Content animate={fade()} />
+ * ```
+ */
+export declare function fade(): TAnimationPreset;
+/**
+ * Scale from 0.95 + opacity transition.
+ *
+ * Suitable for menus, dropdowns, and select options.
+ *
+ * @example
+ * ```tsx
+ * import { scaleAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * <Popup.Content animate={scaleAndFade()} />
+ * ```
+ */
+export declare function scaleAndFade(): TAnimationPreset;
+type TDialogSlideUpAndFadeOptions = {
+    /**
+     * Slide distance in pixels. Defaults to `12`.
+     */
+    distance?: number;
+};
+/**
+ * Slide up + opacity animation for dialogs.
+ *
+ * Entry slides up from below; exit slides up and out (asymmetric).
+ * Includes backdrop fade animation.
+ *
+ * @param options.distance - Slide distance in pixels. Defaults to `12`.
+ *
+ * @example
+ * ```tsx
+ * import { dialogSlideUpAndFade } from '@atlaskit/top-layer/animations';
+ *
+ * const animation = dialogSlideUpAndFade();
+ * <Dialog animate={animation} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+export declare function dialogSlideUpAndFade(options?: TDialogSlideUpAndFadeOptions): TAnimationPreset;
+/**
+ * Simple opacity transition for dialogs, no transform.
+ *
+ * Includes backdrop fade animation.
+ *
+ * @example
+ * ```tsx
+ * import { dialogFade } from '@atlaskit/top-layer/animations';
+ *
+ * <Dialog animate={dialogFade()} isOpen={isOpen} onClose={handleClose} label="...">
+ *   ...
+ * </Dialog>
+ * ```
+ */
+export declare function dialogFade(): TAnimationPreset;
+export {};

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

@@ -0,0 +1,42 @@
+import { type TPlacementOptions } from '../popup/types';
+/**
+ * A self-contained animation preset for top-layer elements (popovers and dialogs).
+ *
+ * Contains the CSS rules (injected once into `<head>`), a data-attribute name
+ * for CSS targeting, optional per-placement custom properties, and the exit
+ * duration used for a `transitionend` fallback timeout.
+ *
+ * Entry animation uses `@starting-style`.
+ * Exit animation uses `allow-discrete` on `display`/`overlay` to keep the
+ * element visible in the top layer while CSS transitions play.
+ */
+export type TAnimationPreset = {
+    /**
+     * CSS to inject once into `document.head`, scoped via a data attribute
+     * (e.g. `[data-ds-popover-{name}]` or `[data-ds-dialog-{name}]`).
+     */
+    css: string;
+    /**
+     * Data attribute suffix for CSS targeting (e.g. `'slide-and-fade'`).
+     */
+    name: string;
+    /**
+     * Per-placement CSS custom properties (e.g. directional offset for
+     * `slideAndFade`). Only used by popover presets that vary by placement.
+     */
+    getProperties?: (args: {
+        placement: TPlacementOptions;
+    }) => Record<string, string>;
+    /**
+     * Exit duration in ms (for `transitionend` fallback timeout).
+     */
+    exitDurationMs: number;
+};
+/**
+ * @deprecated Use `TAnimationPreset` instead.
+ */
+export type TPopoverAnimationPreset = TAnimationPreset;
+/**
+ * @deprecated Use `TAnimationPreset` instead.
+ */
+export type TDialogAnimationPreset = TAnimationPreset;

package/dist/types-ts4.5/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
+ * don't use arrows pay no bundle cost.
+ *
+ * The arrows inherit their background from the popover element.
+ * When `arrow` is active, `PopoverContent` does not reset `background`
+ * to `transparent`, allowing the UA default (`canvas`) or a consumer-set
+ * background to show through.
+ *
+ * @example
+ * ```tsx
+ * import { arrow } from '@atlaskit/top-layer/arrow';
+ *
+ * const myArrow = arrow();
+ *
+ * <Popup.Content arrow={myArrow} />
+ * ```
+ */
+export declare const arrow: () => TArrowPreset;
+export type { TArrowPreset } from './types';

package/dist/types-ts4.5/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 don't 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-ts4.5/dialog/create-close-event.d.ts

@@ -0,0 +1,24 @@
+import { type TDialogCloseReason } from './types';
+/**
+ * Creates a synthetic DOM event from a `TDialogCloseReason`.
+ *
+ * Useful when bridging the Dialog primitive's `onClose({ reason })` callback
+ * to a legacy API that expects a `KeyboardEvent` or `MouseEvent` — for example,
+ * `@atlaskit/modal-dialog`'s `onClose(event, analyticsEvent)` contract.
+ *
+ * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
+ * - `'overlay-click'` → `MouseEvent('click')`
+ *
+ * @example
+ * ```tsx
+ * import { createCloseEvent } from '@atlaskit/top-layer/create-close-event';
+ * import { type TDialogCloseReason } from '@atlaskit/top-layer/dialog';
+ *
+ * function onDialogClose({ reason }: { reason: TDialogCloseReason }) {
+ *   legacyOnClose(createCloseEvent({ reason }));
+ * }
+ * ```
+ */
+export declare function createCloseEvent({ reason, }: {
+    reason: TDialogCloseReason;
+}): KeyboardEvent | MouseEvent;