@atlaskit/top-layer 0.12.2 → 0.14.0

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

@@ -1,321 +0,0 @@
-import { type ReactElement, type ReactNode, type Ref, type RefObject } from 'react';
-import { type StrictXCSSProp } from '@atlaskit/css';
-import { type TAnimationPreset } from '../animations/types';
-import { type TPlacementOptions } from '../internal/resolve-placement';
-import { type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
-import { type TPopoverCloseReason, type TWidthFromAnchorMode } from '../popover/types';
-/**
- * Describes where to position a popover relative to its trigger. All fields
- * are optional. The default `{}` means "below the trigger, centered, with a
- * `space.100` token gap" (equivalent to Popper.js `'bottom'`).
- *
- * - `axis`: `'block'` (above/below, default) or `'inline'` (left/right)
- * - `edge`: `'start'` or `'end'` (default)
- * - `align`: `'start'`, `'center'` (default), or `'end'`
- * - `offset.gap`: distance from the trigger toward the popover (default `token('space.100', '8px')`, accepts number or CSS string)
- * - `offset.crossAxisShift.value`: cross-axis shift (default `0`)
- * - `offset.crossAxisShift.direction`: `'forwards'` (default) or `'backwards'`
- *
- * @example
- * ```ts
- * placement={{ align: 'start' }} // Below trigger, aligned to start
- * placement={{ axis: 'inline' }} // Right of trigger, centered
- * placement={{ offset: { gap: 4 } }} // Tooltip-like gap
- * placement={{ offset: { crossAxisShift: { value: 4, direction: 'backwards' } } }}
- * ```
- */
-export { type TPlacementOptions } from '../internal/resolve-placement';
-/**
- * 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;
-    /**
-     * Must contain `Popup.Trigger` and `Popup.Content`.
-     */
-    children: ReactNode;
-    /**
-     * 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;
-    /**
-     * 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;
-};
-/**
- * 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.
-     */
-    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>;
-    /**
-     * 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.
-     *
-     * - `'none'` (default): popover sizes to its content, ignoring the anchor width.
-     * - `'match-anchor'`: popover matches the anchor element's width exactly
-     *   via CSS `anchor-size(width)`. Falls back to a one-off measurement
-     *   of `anchorRef.current.offsetWidth` when CSS Anchor Positioning
-     *   is not supported.
-     * - `'min-anchor'`: popover is at least as wide as the anchor, but
-     *   can grow wider if content requires it. Uses `min-width: anchor-size(width)`.
-     *   Falls back to a one-off measurement of the anchor's width.
-     */
-    widthFromAnchor?: TWidthFromAnchorMode;
-    /**
-     * Applies additional CSS styles to the popover root element using
-     * design-system-safe xcss.
-     *
-     * @example
-     * ```tsx
-     * const styles = cssMap({ surface: { backgroundColor: token('elevation.surface.overlay') } });
-     * <Popup.Content xcss={styles.surface} ... />
-     * ```
-     */
-    xcss?: StrictXCSSProp<'backgroundColor', never>;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * 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;
-    /**
-     * Called after the entry animation completes (or immediately on open when
-     * there is no animation). Use this for lifecycle coordination that must
-     * happen after the popup has fully animated in.
-     */
-    onEnterFinish?: () => void;
-    /**
-     * Called after the exit animation completes (or immediately on close when
-     * there is no animation). Use this for lifecycle coordination that must
-     * happen after the popup has fully animated out.
-     */
-    onExitFinish?: () => void;
-};
-/**
- * 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;
-};

package/dist/types/popup/use-maybe-popup-context.d.ts

@@ -1,8 +0,0 @@
-import { type TPopupContextValue } from './popup-context';
-/**
- * Returns the popup context if available, or `null` when used outside `<Popup>`.
- *
- * Used by `PopupContent` to support standalone usage (e.g. tooltip)
- * where values are passed as props instead of coming from a compound component.
- */
-export declare function useMaybePopupContext(): TPopupContextValue | null;

package/dist/types/popup/use-popup-context.d.ts

@@ -1,7 +0,0 @@
-import { type TPopupContextValue } from './popup-context';
-/**
- * Returns the nearest `Popup` context value.
- *
- * Throws if called outside of a `<Popup>` compound component.
- */
-export declare function usePopupContext(): TPopupContextValue;

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

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

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

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

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

@@ -1,50 +0,0 @@
-/**
- * Focusable element selectors and navigation helpers.
- *
- * Uses CSS selectors to discover focusable elements within a container,
- * avoiding the need for a manual registration system. Disabled elements
- * (both HTML `disabled` attribute and `aria-disabled="true"`) and elements
- * with `tabindex="-1"` are excluded automatically.
- *
- * All public functions accept an optional `filter` callback to further
- * restrict which focusable elements are included.
- */
-/**
- * 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.
- */
-export type TFocusableFilter = (element: HTMLElement, container: HTMLElement) => boolean;
-/**
- * Returns the first focusable element within the container.
- */
-export declare function getFirstFocusable({ container, filter, }: {
-    container: HTMLElement;
-    filter?: TFocusableFilter;
-}): HTMLElement | null;
-/**
- * Returns the last focusable element within the container.
- */
-export declare function getLastFocusable({ container, filter, }: {
-    container: HTMLElement;
-    filter?: TFocusableFilter;
-}): HTMLElement | null;
-/**
- * Returns the next focusable element in the given direction relative to the
- * currently focused element within the container. Wraps around at both ends.
- *
- * Returns `null` if there is no focused element within the container or if
- * the focused element is not in the list of focusable elements.
- */
-export declare function getNextFocusable({ container, direction, filter, }: {
-    container: HTMLElement;
-    direction: 'forwards' | 'backwards';
-    filter?: TFocusableFilter;
-}): HTMLElement | null;

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

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

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

@@ -1,34 +0,0 @@
-import { PopupRoot } from './popup';
-import { PopupContent } from './popup-content';
-import { PopupSurface } from './popup-surface';
-import { PopupTrigger } from './popup-trigger';
-import { PopupTriggerFunction } from './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>
- * ```
- */
-declare const Popup: typeof PopupRoot & {
-    Trigger: typeof PopupTrigger;
-    TriggerFunction: typeof PopupTriggerFunction;
-    Content: typeof PopupContent;
-    Surface: typeof PopupSurface;
-};
-export { Popup };
-export type { TPlacementOptions, TPopupProps, TPopupContentProps, TPopupRole, TPopupSurfaceProps, TPopupTriggerProps, } from './types';
-export type { TTriggerFunctionRenderProps } from './popup-trigger-function';

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

@@ -1,14 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import React from 'react';
-import { type TPopupContentProps } from './types';
-/**
- * Thin context wrapper that composes `Popover` + `useAnchorPosition`.
- *
- * Used inside the `<Popup>` compound - reads triggerRef, placement, isOpen,
- * and onClose from context. For standalone usage (tooltip, spotlight, flag),
- * use `Popover` + `useAnchorPosition` directly.
- */
-export declare const PopupContent: React.ForwardRefExoticComponent<TPopupContentProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -1,96 +0,0 @@
-import React, { type MutableRefObject, type RefObject } from 'react';
-import { type TAriaHasPopupValue } from '../internal/role-types';
-import { type TPopoverCloseReason } from '../popover/types';
-import { type TPlacementOptions } from './types';
-/**
- * Represents the lifecycle state of the popup.
- *
- * - `'closed'`: fully closed, not visible, no animation playing.
- * - `'animating-open'`: entry animation is playing (popup is opening but not yet settled).
- * - `'open'`: fully open, browser popover is showing, entry animation complete.
- * - `'animating-closed'`: exit animation is playing (popup is closing but still visible).
- *
- * Used to derive `aria-expanded` on the trigger:
- * - `aria-expanded` is `true` in `'animating-open'`, `'open'`, and `'animating-closed'`.
- *
- * This avoids screen readers announcing the popup as closed while it is
- * still visually present on screen during animations, and prevents consumers
- * that conditionally show/hide trigger UI based on `aria-expanded` from hiding
- * the trigger (and thus the popup anchor) mid-animation.
- */
-export type TPopupState = 'closed' | 'animating-open' | 'open' | 'animating-closed';
-export type TPopupContextValue = {
-    /**
-     * Auto-generated ID for the popover content element (used for aria-controls).
-     */
-    popoverId: string;
-    /**
-     * Requested placement.
-     */
-    placement: TPlacementOptions;
-    /**
-     * Called when the popover is dismissed via light dismiss.
-     * `null` when mode is 'manual' (no light dismiss).
-     */
-    onClose: ((args: {
-        reason: TPopoverCloseReason;
-    }) => void) | null;
-    /**
-     * Mutable ref to the trigger element (set by Popup.Trigger / Popup.TriggerFunction).
-     */
-    triggerRef: MutableRefObject<HTMLElement | null>;
-    /**
-     * Ref to the popover content element (set by Popup.Content).
-     */
-    popoverRef: RefObject<HTMLDivElement | null>;
-    /**
-     * The full lifecycle state of the popup.
-     *
-     * See `TPopupState` for the full state machine description.
-     */
-    popupState: TPopupState;
-    /**
-     * Updates the popup lifecycle state. Called by `PopupContent` as animations
-     * begin and complete.
-     */
-    setPopupState: (state: TPopupState) => void;
-    /**
-     * Consumer's onOpenChange callback, forwarded to the Popover.
-     */
-    onOpenChange?: (args: {
-        isOpen: boolean;
-        element: HTMLDivElement;
-    }) => void;
-    /**
-     * Native popover mode. Flows from the Popup root to Content via context.
-     */
-    mode: 'auto' | 'hint' | 'manual';
-    /**
-     * The `aria-haspopup` value derived from the content's role.
-     *
-     * Set by `Popup.Content` via `setAriaHasPopup` when it renders.
-     * Read by `Popup.Trigger` / `Popup.TriggerFunction` to set
-     * the correct `aria-haspopup` on the trigger element.
-     *
-     * This flows the content's role to the trigger without requiring
-     * the consumer to specify the role in two places. The trigger
-     * renders with the default ('dialog') on first paint; Content's
-     * layout effect updates it before the browser paints.
-     */
-    ariaHasPopup: TAriaHasPopupValue;
-    /**
-     * Updates `ariaHasPopup` - called by Content on mount/role change.
-     */
-    setAriaHasPopup: (value: TAriaHasPopupValue) => void;
-    /**
-     * Test ID prefix.
-     */
-    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 declare const PopupContext: React.Context<TPopupContextValue | null>;

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

@@ -1,10 +0,0 @@
-import { type Provider } from 'react';
-import { type TPopupContextValue } from './popup-context';
-/**
- * __Popup provider__
- *
- * Provides shared popup state (placement, popoverId, triggerRef,
- * isOpen, onClose) to compound child components such as `Popup.Trigger` and
- * `Popup.Content`.
- */
-export declare const PopupProvider: Provider<TPopupContextValue | null>;

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

@@ -1,22 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import React from 'react';
-import { type TPopupSurfaceProps } from './types';
-/**
- * Optional styled wrapper for popup content.
- *
- * Adds default visual styling (background, border-radius, box-shadow)
- * using design tokens. Consumers who want fully custom styling
- * 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;