@atlaskit/top-layer 0.1.0

package/dist/types-ts4.5/internal/use-initial-focus.d.ts

@@ -0,0 +1,21 @@
+import { type RefObject } from 'react';
+/**
+ * Moves focus into a popover element when it opens, based on its ARIA role.
+ *
+ * This implements WCAG 2.4.3 (Focus Order) initial focus placement:
+ * - `dialog` / `alertdialog` → focus first focusable (or `[autofocus]`)
+ * - `menu` → focus first menu item
+ * - `listbox` → focus selected or first option
+ * - `tooltip` / no role → no focus movement
+ *
+ * The role is read from the element's `role` attribute (not passed as a prop),
+ * following the same pattern as `useFocusWrap`.
+ *
+ * Always call this hook unconditionally. Focus is only moved when `isOpen`
+ * transitions to `true` and the role requires it.
+ */
+export declare function useInitialFocus({ elementRef, isOpen, role, }: {
+    elementRef: RefObject<HTMLElement | null>;
+    isOpen: boolean;
+    role: string | undefined;
+}): void;

package/dist/types-ts4.5/internal/use-preset-styles.d.ts

@@ -0,0 +1,15 @@
+type TPresetWithCssAndName = {
+    css: string;
+    name: string;
+};
+/**
+ * Normalizes a preset prop to a value (or null) and ensures its CSS
+ * is injected once into `document.head`.
+ *
+ * Works with any preset that has `{ css, name }` — animation presets
+ * (TAnimationPreset) and arrow presets (TArrowPreset) both satisfy this shape.
+ */
+export declare function usePresetStyles<T extends TPresetWithCssAndName>({ preset, }: {
+    preset: T | false | null | undefined;
+}): T | null;
+export {};

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

@@ -0,0 +1,55 @@
+import { type TPlacement } from '../internal/resolve-placement';
+import { type TPlacementOptions } from '../popup/types';
+/**
+ * Legacy Popper.js placement values (used by `@atlaskit/popper`, `@atlaskit/popup`,
+ * `@atlaskit/tooltip`, etc.).
+ */
+export type TLegacyPlacement = 'auto' | 'auto-start' | 'auto-end' | 'top' | 'top-start' | 'top-center' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-center' | 'bottom-end' | 'right' | 'right-start' | 'right-end' | 'left' | 'left-start' | 'left-end';
+/**
+ * Maps legacy Popper.js placement values to the new object-based
+ * `Placement` values used by `@atlaskit/top-layer/popover`.
+ *
+ * **Mapping logic:**
+ *
+ * | Legacy (Popper.js)  | New (Placement object)                              |
+ * | ------------------- | --------------------------------------------------- |
+ * | `top`               | `{ axis: 'block', edge: 'start', align: 'center' }`  |
+ * | `top-start`         | `{ axis: 'block', edge: 'start', align: 'start' }`   |
+ * | `top-end`           | `{ axis: 'block', edge: 'start', align: 'end' }`     |
+ * | `bottom`            | `{ axis: 'block', edge: 'end', align: 'center' }`    |
+ * | `bottom-start`      | `{ axis: 'block', edge: 'end', align: 'start' }`     |
+ * | `bottom-end`        | `{ axis: 'block', edge: 'end', align: 'end' }`       |
+ * | `right`             | `{ axis: 'inline', edge: 'end', align: 'center' }`   |
+ * | `right-start`       | `{ axis: 'inline', edge: 'end', align: 'start' }`    |
+ * | `right-end`         | `{ axis: 'inline', edge: 'end', align: 'end' }`      |
+ * | `left`              | `{ axis: 'inline', edge: 'start', align: 'center' }` |
+ * | `left-start`        | `{ axis: 'inline', edge: 'start', align: 'start' }`  |
+ * | `left-end`          | `{ axis: 'inline', edge: 'start', align: 'end' }`    |
+ * | `auto`              | `{ axis: 'block', edge: 'end', align: 'center' }`    |
+ * | `auto-start`        | `{ axis: 'block', edge: 'end', align: 'start' }`     |
+ * | `auto-end`          | `{ axis: 'block', edge: 'end', align: 'end' }`       |
+ *
+ * The `position-try-fallbacks` CSS property handles flipping automatically.
+ *
+ * @example
+ * ```ts
+ * import { fromLegacyPlacement } from '@atlaskit/top-layer/placement-map';
+ *
+ * // In a migration from @atlaskit/popup:
+ * const oldPlacement: TLegacyPlacement = 'bottom-start';
+ * const newPlacement: TPlacementOptions = fromLegacyPlacement({ legacy: oldPlacement });
+ * // newPlacement === { axis: 'block', edge: 'end', align: 'start' }
+ * ```
+ */
+declare const placementMapping: Record<TLegacyPlacement, TPlacement>;
+/**
+ * Convert a legacy Popper.js placement to the new CSS `position-area`-based Placement.
+ */
+export declare function fromLegacyPlacement({ legacy }: {
+    legacy: TLegacyPlacement;
+}): TPlacementOptions;
+/**
+ * The full mapping record, exposed for consumers that need to iterate or introspect.
+ */
+export { placementMapping };
+export type { TPlacementOptions };

package/dist/types-ts4.5/popover/create-close-event.d.ts

@@ -0,0 +1,26 @@
+import { type TPopoverCloseReason } from './types';
+/**
+ * Creates a synthetic DOM event from a `TPopoverCloseReason`.
+ *
+ * Useful when bridging the Popover primitive's `onClose({ reason })` callback
+ * to a legacy API that expects a native DOM event — for example,
+ * `@atlaskit/inline-dialog`'s `onClose(event)` contract.
+ *
+ * - `'escape'` → `KeyboardEvent('keydown', { key: 'Escape' })`
+ * - `'light-dismiss'` → `MouseEvent('click')`
+ *
+ * For any other reason, a generic `Event('close')` is returned as a fallback.
+ *
+ * @example
+ * ```tsx
+ * import { createPopoverCloseEvent } from '@atlaskit/top-layer/create-close-event';
+ * import { type TPopoverCloseReason } from '@atlaskit/top-layer/popover';
+ *
+ * function onPopoverClose({ reason }: { reason: TPopoverCloseReason }) {
+ *   legacyOnClose(createPopoverCloseEvent({ reason }));
+ * }
+ * ```
+ */
+export declare function createPopoverCloseEvent({ reason, }: {
+    reason: TPopoverCloseReason;
+}): KeyboardEvent | MouseEvent | Event;

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

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

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

@@ -0,0 +1,22 @@
+/**
+ * @jsxRuntime classic
+ * @jsx jsx
+ */
+import React from 'react';
+import { type TPopoverForwardedProps } from './types';
+/**
+ * Unopinionated top-layer primitive.
+ *
+ * Manages only visibility (isOpen) and animation (animate). Has no knowledge
+ * of positioning — compose with `useAnchorPosition` for anchor positioning.
+ *
+ * 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.
+ */
+export declare const Popover: React.ForwardRefExoticComponent<TPopoverForwardedProps & React.RefAttributes<HTMLDivElement>>;

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

@@ -0,0 +1,153 @@
+import { type ReactNode } from 'react';
+import { type TAnimationPreset } from '../animations/types';
+import { type TAriaRoleOptional, type TRoleRequiringAccessibleName, type TRoleWithImplicitName } from '../internal/role-types';
+import { type TPlacementOptions } from '../popup/types';
+/**
+ * The reason a popover was dismissed via light dismiss.
+ *
+ * - `'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).
+ */
+export type TPopoverCloseReason = 'escape' | 'light-dismiss';
+/**
+ * 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;
+};
+/**
+ * Alias for TPopoverForwardedProps.
+ *
+ * Used internally by PopupContent to forward props to Popover without
+ * re-proving the discriminated union at each call site.
+ */
+export type TPopoverInternalProps = TPopoverForwardedProps;
+type TPopoverBaseProps = {
+    children: ReactNode;
+    /**
+     * 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. The `<Popup>` compound passes its context ID
+     * so that `Popup.Trigger` can reference it via `aria-controls` / `popovertarget`.
+     */
+    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 element stays mounted in the DOM at all times — the consumer does not
+     * conditionally render it. Visibility is driven by this prop.
+     *
+     * **Important:** For `mode="auto"` popovers, the browser can dismiss the popover
+     * via light dismiss (Escape, click outside) independently of this prop. When that
+     * happens, `onClose` is called — the consumer should respond by setting `isOpen`
+     * 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 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 doesn't close other `auto` popovers.
+ *   Falls back to `'auto'` in browsers without `popover="hint"` support.
+ * - `'manual'`: no light dismiss. Consumer controls show/hide entirely. Only
+ *   appropriate for persistent UI (e.g. flags, banners).
+ */
+export type TPopoverProps = TPopoverBaseProps & TAriaRoleOptional & ({
+    mode?: 'auto' | 'hint';
+    /**
+     * Called when the popover is dismissed via light dismiss
+     * (Escape, click outside).
+     *
+     * 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;
+});
+export {};

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

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,14 @@
+/**
+ * @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

@@ -0,0 +1,96 @@
+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';
+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>;
+    /**
+     * Whether the popover is currently open.
+     */
+    isOpen: boolean;
+    /**
+     * Set the open state (internal context sync).
+     */
+    setIsOpen: (open: boolean) => 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;
+};
+/**
+ * __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: React.Provider<TPopupContextValue | null>;
+/**
+ * Returns the nearest `Popup` context value.
+ *
+ * Throws if called outside of a `<Popup>` compound component.
+ */
+export declare function usePopupContext(): TPopupContextValue;
+/**
+ * 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-ts4.5/popup/popup-surface.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @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.
+ */
+export declare function PopupSurface({ children }: TPopupSurfaceProps): React.ReactElement;

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

@@ -0,0 +1,108 @@
+import React, { type ReactNode, type RefCallback } from 'react';
+import { type TAriaHasPopupValue } from '../internal/role-types';
+/**
+ * Props passed to the `TriggerFunction` render-prop child.
+ */
+export type TTriggerFunctionRenderProps = {
+    /**
+     * Ref callback to attach to the trigger element. Sets `triggerRef` in
+     * popup context for anchor positioning and `togglePopover`.
+     */
+    ref: RefCallback<HTMLElement>;
+    /**
+     * Whether the popover content is currently visible.
+     * Use for `aria-expanded` and conditional styling.
+     */
+    isOpen: boolean;
+    /**
+     * ID of the popover content element. Use for `aria-controls`.
+     */
+    popoverId: string;
+    /**
+     * Toggle the popover open/closed via the native Popover API.
+     *
+     * Calling `toggle()` invokes `popoverEl.togglePopover()` on the
+     * underlying content element. This hides the imperative DOM API
+     * behind a stable function reference.
+     */
+    toggle: () => void;
+    /**
+     * Pre-composed ARIA attributes for the trigger element.
+     *
+     * Spread these onto your trigger: `{...ariaAttributes}`.
+     *
+     * Contains:
+     * - `aria-expanded`: whether the popover is open
+     * - `aria-controls`: ID of the popover content
+     * - `aria-haspopup`: derived from the content's ARIA role via context
+     *
+     * **Note on `aria-haspopup`:** When the content's role maps to a specific
+     * popup type (`'menu'`, `'dialog'`, `'listbox'`, etc.), the corresponding
+     * string value is used. For unmapped roles, the value is `true` (boolean).
+     * React serialises `aria-haspopup={true}` as `aria-haspopup="true"` in the
+     * DOM, which is the correct default per the HTML spec. The values can be
+     * spread directly onto trigger elements without conversion.
+     */
+    ariaAttributes: {
+        'aria-expanded': boolean;
+        'aria-controls': string;
+        'aria-haspopup': TAriaHasPopupValue;
+    };
+};
+type TPopupTriggerFunctionProps = {
+    /**
+     * Render-prop function that receives trigger props.
+     *
+     * Unlike `Popup.Trigger`, this does not use `cloneElement` — the consumer
+     * is responsible for spreading ref, ARIA attributes, and attaching `toggle`
+     * to the appropriate event(s).
+     *
+     * @example
+     * ```tsx
+     * <Popup.TriggerFunction>
+     *   {({ ref, toggle, ariaAttributes }) => (
+     *     <button ref={ref} onClick={toggle} {...ariaAttributes}>
+     *       Open menu
+     *     </button>
+     *   )}
+     * </Popup.TriggerFunction>
+     * ```
+     *
+     * **Note:** This sub-component uses a render-prop pattern and is not
+     * compatible with React Server Components (RSC). It must be used
+     * inside a client component boundary (`'use client'`).
+     */
+    children: (props: TTriggerFunctionRenderProps) => ReactNode;
+};
+/**
+ * Render-prop alternative to `Popup.Trigger`.
+ *
+ * Use when you need full control over the trigger element — for example,
+ * to compose your own trigger with custom event handlers, wrap a third-party
+ * component, or build a trigger from multiple elements.
+ *
+ * `Popup.Trigger` uses `cloneElement` internally, which limits composability.
+ * `Popup.TriggerFunction` hands you the raw props and lets you wire them up.
+ *
+ * **Note:** This sub-component uses a render-prop pattern and is not
+ * compatible with React Server Components (RSC). It must be used inside
+ * a client component boundary (`'use client'`).
+ *
+ * @example
+ * ```tsx
+ * <Popup placement={{ edge: 'end' }} onClose={handleClose}>
+ *   <Popup.TriggerFunction>
+ *     {({ ref, toggle, ariaAttributes }) => (
+ *       <button ref={ref} onClick={toggle} {...ariaAttributes}>
+ *         Open
+ *       </button>
+ *     )}
+ *   </Popup.TriggerFunction>
+ *   <Popup.Content role="dialog" label="My popup">
+ *     Content
+ *   </Popup.Content>
+ * </Popup>
+ * ```
+ */
+export declare function PopupTriggerFunction({ children }: TPopupTriggerFunctionProps): React.ReactNode;
+export {};

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

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

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

@@ -0,0 +1,14 @@
+import React from 'react';
+import { type TPopupProps } from './types';
+/**
+ * Popup compound — trigger + popover content.
+ *
+ * Use when a button opens anchored content (dropdown, menu, dialog).
+ * The browser manages visibility via `togglePopover()` — the consumer
+ * never manages `isOpen`. For custom trigger lifecycles (hover, timers,
+ * external state), use `Popover` directly instead.
+ *
+ * Provides context (triggerRef, placement, isOpen, onClose, mode) that
+ * `Popup.Content` reads and forwards to the underlying `Popover`.
+ */
+export declare function PopupRoot(props: TPopupProps): React.ReactElement;