@atlaskit/top-layer 0.16.0 → 0.18.0

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

@@ -1,17 +0,0 @@
-/**
- * @jsxRuntime classic
- * @jsx jsx
- */
-import React from 'react';
-import { type TPopoverForwardedProps } from './types';
-/**
- * Unopinionated top-layer primitive. Manages visibility and animation only;
- * compose with `useAnchorPosition` / `useWidthFromAnchor` for positioning.
- *
- * `isOpen={true}` calls `showPopover()` (entry via `@starting-style`);
- * `isOpen={false}` calls `hidePopover()` (exit via `allow-discrete`).
- *
- * 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,193 +0,0 @@
-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';
-/**
- * The reason a popover was closed.
- *
- * - `'escape'`: The user pressed the Escape key.
- * - `'light-dismiss'`: The user clicked outside the popover (or the browser
- *   dismissed it for another auto-mode reason).
- * - `'programmatic'`: The popover was closed programmatically.
- */
-export type TPopoverCloseReason = 'escape' | 'light-dismiss' | 'programmatic';
-/**
- * Flat (non-discriminated) props accepted by the Popover component internally.
- *
- * TypeScript limitation: when PopupContent destructures props from a
- * discriminated union (role, label, labelledBy) and re-passes them individually
- * to Popover, TypeScript cannot prove the individual fields still satisfy the
- * union constraint. This flat type accepts all role/label combinations without
- * the union, since ARIA correctness is enforced at the TPopupContentProps
- * boundary where consumers interact.
- */
-export type TPopoverForwardedProps = TPopoverBaseProps & {
-    mode?: 'auto' | 'hint' | 'manual';
-    onClose?: (args: {
-        reason: TPopoverCloseReason;
-    }) => void;
-    role?: TRoleRequiringAccessibleName | TRoleWithImplicitName;
-    label?: string;
-    labelledBy?: string;
-};
-export type { TPlacementOptions };
-type TPopoverBaseProps = {
-    children: ReactNode;
-    /**
-     * Additional CSS styles applied to the popover root element.
-     * Use to set `backgroundColor` to match the popup surface colour.
-     */
-    xcss?: StrictXCSSProp<'backgroundColor', never>;
-    /**
-     * Animation preset for entry/exit transitions.
-     *
-     * Animations use `@starting-style` and `allow-discrete` for progressive
-     * enhancement: browsers without support show/hide instantly.
-     */
-    animate?: false | TAnimationPreset;
-    /**
-     * Test ID applied to the popover element.
-     */
-    testId?: string;
-    /**
-     * HTML `id` attribute for the popover element. When omitted, a unique ID
-     * 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;
-    /**
-     * Whether the popover is open.
-     *
-     * - **`true`:** show the popover (calls `showPopover()`, entry animation plays via `@starting-style`).
-     * - **`false`:** hide the popover. When an `animate` preset is provided, the exit
-     *   animation plays (via `allow-discrete`) before the popover becomes logically closed.
-     *   Otherwise hides instantly.
-     *
-     * The consumer does not conditionally render the `Popover` — visibility is driven
-     * by this prop.
-     *
-     * **Lifecycle observable to consumers:**
-     *
-     * - The host element is in the DOM only while the popover is open or its exit
-     *   animation is playing. After exit completes the element is unmounted so it
-     *   does not leave an empty `role` / `popover` element in the accessibility tree.
-     *   The exact unmount timing is private and may change.
-     * - The `id` (supplied or generated via `usePopoverId()`) is stable across opens.
-     * - The `ref` is populated only while the host element is rendered. Consumers
-     *   that read from the ref outside of `onOpenChange` / `onEnterFinish` should
-     *   gate the read on `isOpen` being `true`.
-     *
-     * **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 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}`).
-     */
-    isOpen: boolean;
-    /**
-     * Called when the popover's open state changes via browser toggle events.
-     *
-     * 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
-     * <Popover
-     *   onOpenChange={({ isOpen, element }) => {
-     *     if (isOpen) {
-     *       getFirstFocusable({ container: element })?.focus();
-     *     }
-     *   }}
-     * />
-     * ```
-     */
-    onOpenChange?: (args: {
-        isOpen: boolean;
-        element: HTMLDivElement;
-    }) => void;
-    /**
-     * Placement hint for directional animations (e.g. `slideAndFade`).
-     *
-     * When `animate` is provided, the preset's `getProperties(placement)` is
-     * 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.
-     */
-    placement?: TPlacementOptions;
-    /**
-     * 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
-     * that the show sequence is finished.
-     */
-    onEnterFinish?: () => void;
-    /**
-     * 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
-     * that the hide sequence is finished, or firing an `onCloseComplete` callback.
-     */
-    onExitFinish?: () => void;
-};
-/**
- * Unopinionated top-layer primitive.
- *
- * `Popover` manages only top-layer visibility and animation. It has no
- * knowledge of positioning. For anchor positioning, compose with the
- * `useAnchorPosition` hook separately.
- *
- * Use `Popover` directly for custom trigger lifecycles (hover, timers,
- * external state) or trigger-less UI (flags, toasts). For the common
- * button-opens-content pattern, use the `Popup` compound instead.
- *
- * Dismiss behavior:
- * - `'auto'` (default): Escape to close, click-outside to close, focus restoration,
- *   automatic nesting, mutual exclusivity.
- * - `'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 & 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: {
-        reason: TPopoverCloseReason;
-    }) => void;
-} | {
-    mode: 'manual';
-    onClose?: never;
-});
-/**
- * The width mode 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.
- */
-export type TWidthFromAnchorMode = 'none' | 'match-anchor' | 'min-anchor';

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

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

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

@@ -1,21 +0,0 @@
-/**
- * @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/testing/polyfill.d.ts

@@ -1,25 +0,0 @@
-/**
- * Popover API & HTMLDialogElement polyfills for jsdom.
- *
- * jsdom does not implement the Popover API or the HTMLDialogElement methods
- * (showModal, show, close). This polyfill provides faithful implementations,
- * including timing semantics validated against Chromium via Playwright.
- *
- * Behaviour:
- *  - beforetoggle: sync, cancelable on popover show only. toggle: async task, never cancelable.
- *  - Rapid show/hide coalesces into one toggle event (originalOldState to finalNewState).
- *  - Dialog: showModal/show fire beforetoggle+toggle. close fires toggle then close event.
- *  - Popover open state tracked via `data-popover-open` (no `:popover-open` in jsdom).
- *  - Auto popovers: maintain an open stack, perform light-dismiss on document mousedown
- *    outside the open chain, and dismiss the topmost on Escape.
- *  - On open, removes any inline `opacity: 0` from the popover element so callers that
- *    rely on a `ResizeObserver` reveal callback (e.g. `use-anchor-position`) become
- *    visible in jsdom, where layout-driven RO callbacks never fire.
- *
- * Companion `toBeVisible` patch lives at `./to-be-visible`.
- *
- * Importing this module has the side-effect of patching the relevant
- * prototypes. It is safe to import multiple times; each branch is guarded
- * to avoid overwriting native implementations or re-patching.
- */
-export {};

package/dist/types-ts4.5/testing/to-be-visible.d.ts

@@ -1,23 +0,0 @@
-/**
- * Patches `toBeVisible()` to understand popover and dialog visibility.
- *
- * jest-dom's `toBeVisible()` does not know about the Popover API. In real
- * browsers the UA stylesheet hides `[popover]` with `display: none`, but
- * jsdom has no such stylesheet - so closed popovers incorrectly appear visible.
- *
- * Raw jest-dom results in jsdom:
- *
- *   closed popover / child  → true  (WRONG - should be false)
- *   open popover / child    → true  (correct)
- *   closed dialog / child   → false (correct - jsdom natively hides <dialog>)
- *   open dialog / child     → true  (correct)
- *
- * We correct both false positives and false negatives:
- *   1. Delegate to the original first.
- *   2. If it says "visible" → check for closed top-layer hosts (false positive).
- *   3. If it says "not visible" → check for open top-layer hosts (false negative).
- *
- * Must load via `setupFilesAfterEnv` (after jest-dom registers its matchers).
- * Polyfills live in `./polyfill` (loaded via `setupFiles`).
- */
-export {};

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

@@ -1,3 +0,0 @@
-export { useArrowNavigation } from './use-arrow-navigation';
-export type { TUseArrowNavigationArgs } from './use-arrow-navigation';
-export { isAtCurrentMenuLevel } from './is-at-current-menu-level';

package/dist/types-ts4.5/use-arrow-navigation/is-at-current-menu-level.d.ts

@@ -1,48 +0,0 @@
-/**
- * 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 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):
- *   ```
- *   <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 does not 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;

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

@@ -1,102 +0,0 @@
-import { type RefObject } from 'react';
-import { type TFocusableFilter } from '../focus/types';
-/**
- * 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.
-     */
-    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 does not 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-ts4.5/use-simple-light-dismiss/index.d.ts

@@ -1,45 +0,0 @@
-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 };