/**
 * @file useLayer.tsx
 * @input Uses React hooks, Popover API, CSS anchor positioning, typography tokens
 * @output Exports useLayer hook for layer positioning and visibility
 * @position Core layer utility; used by useHoverCard, useTooltip, etc.
 *
 * SYNC: When modified, update:
 * - /packages/core/src/Layer/useLayer.doc.mjs
 * - /packages/core/src/Layer/useLayer.test.tsx
 * - /packages/core/src/Layer/index.ts
 */
import React, { type ReactNode, type RefCallback } from 'react';
import type { StyleXStyles } from '@stylexjs/stylex';
/**
 * Position placement relative to anchor.
 * Logical: start/end resolve against the popover's own inherited direction
 * via CSS (RTL contexts mirror automatically, no JS involved).
 */
export type LayerPlacement = 'above' | 'below' | 'start' | 'end';
/**
 * Alignment along the placement axis
 */
export type LayerAlignment = 'start' | 'center' | 'end';
/**
 * Render props for context mode (anchor positioning)
 */
export interface ContextRenderProps {
    /**
     * Who authors the layer's position styles.
     *
     * `'anchor'` (default): the hook derives CSS anchor-positioning styles —
     * `position-area` and `position-try-fallbacks` — from the logical
     * `placement`/`alignment`.
     *
     * `'custom'`: the consumer authors its own position styles via `style`
     * (e.g. explicit `anchor()` insets or an `anchor-size()` cover). The hook
     * keeps the popover behavior and the `position-anchor` wiring but emits no
     * placement-derived styles, so direction handling becomes the consumer's
     * responsibility. `placement`/`alignment` are ignored.
     *
     * @default 'anchor'
     */
    positioning?: 'anchor' | 'custom';
    /**
     * Logical placement relative to the anchor. Ignored when `positioning`
     * is `'custom'`.
     */
    placement?: LayerPlacement;
    /**
     * Alignment along the placement axis. Ignored when `positioning`
     * is `'custom'`.
     */
    alignment?: LayerAlignment;
    /**
     * Clearance between the layer and its anchor, as a CSS length (a number is
     * treated as `px`). Applied along the placement axis and flip-safe, so the
     * gap survives a `position-try-fallbacks` flip to the opposite side.
     *
     * Layers sit flush by default: the hook zeroes the UA margins so anchor
     * positioning has a clean box, and clearance is a deliberate choice per
     * surface. `var(--spacing-1)` is the system's standard clearance.
     *
     * Ignored when `positioning` is `'custom'` — that mode owns its own insets.
     *
     * @default 0
     */
    offset?: number | string;
    /**
     * ARIA role applied to the popover container (e.g. `'tooltip'`). Lets
     * consumers complete the ARIA pattern and gives test tooling a stable,
     * non-hashed selector for the layer.
     */
    role?: string;
    /**
     * Accessible name applied to the popover container via `aria-label`.
     * Pair with `role` so layers with a named role (e.g. `'dialog'`) expose a
     * proper name to assistive technology.
     */
    'aria-label'?: string;
    /**
     * StyleX styles for the popover container.
     */
    xstyle?: StyleXStyles;
    /**
     * Additional CSS class name(s) for the popover container.
     * Use with themeProps() for theme targeting when reflecting visual props.
     */
    className?: string;
    /**
     * Inline styles for the popover container.
     * Merged after StyleX and anchor positioning styles.
     */
    style?: React.CSSProperties;
    /**
     * HTML tag to render the popover container as.
     *
     * Defaults to `'div'`. Context layers render an inert `<template>` marker at
     * the JSX position. The marker's parent is checked before the requested
     * container mounts there or portals outside ancestors that cannot safely
     * contain it. The marker remains available to detect a new parent if the
     * render call moves. With `lazyMount`, the first check waits until `show()`.
     *
     * @default 'div'
     */
    as?: 'div' | 'span';
    /**
     * Pointer-enter handler attached to the popover container itself. Lets a
     * consumer keep a hover-driven layer open while the pointer is over the
     * surface (e.g. Tooltip/HoverCard "hoverable" behavior — WCAG 1.4.13).
     */
    onMouseEnter?: React.MouseEventHandler<HTMLElement>;
    /**
     * Pointer-leave handler attached to the popover container itself.
     */
    onMouseLeave?: React.MouseEventHandler<HTMLElement>;
}
/**
 * Render props for fixed mode (manual coordinates)
 */
export interface FixedRenderProps {
    x: number;
    y: number;
    /**
     * StyleX styles for the popover container.
     */
    xstyle?: StyleXStyles;
    /**
     * Additional CSS class name(s) for the popover container.
     * Use with themeProps() for theme targeting when reflecting visual props.
     */
    className?: string;
    /**
     * Inline styles for the popover container.
     * Merged after StyleX and position styles.
     */
    style?: React.CSSProperties;
}
/**
 * Base options shared by both modes
 */
interface BaseLayerOptions {
    /**
     * Callback fired when layer is shown.
     * Wrap in useCallback for stable identity.
     */
    onShow?: () => void;
    /**
     * Callback fired when layer is hidden.
     * Wrap in useCallback for stable identity.
     */
    onHide?: () => void;
    /**
     * Whether clicking outside should dismiss the layer.
     * When true, uses popover="auto" for native light-dismiss behavior.
     * @default false
     */
    lightDismiss?: boolean;
}
/**
 * Options for context mode (CSS anchor positioning)
 */
export interface ContextLayerOptions extends BaseLayerOptions {
    mode: 'context';
    /**
     * Defer mounting the final layer and resolving its inline/portal position
     * until `show()` is requested. Hiding unmounts it while the inert marker
     * remains at the JSX position. Use this when rich content must never enter
     * an unsafe ancestor, even briefly, and does not need to exist while closed.
     *
     * @default false
     */
    lazyMount?: boolean;
}
/**
 * Options for fixed mode (manual positioning)
 */
export interface FixedLayerOptions extends BaseLayerOptions {
    mode: 'fixed';
}
/**
 * Return type for context mode
 */
export interface ContextLayerReturn {
    /**
     * Ref to attach to trigger element.
     * Injects anchorName style for CSS anchor positioning.
     */
    ref: RefCallback<HTMLElement>;
    /**
     * The CSS anchor name to use for positioning.
     * Use this when you need to set anchorName manually (e.g., display:contents wrapper).
     */
    anchorId: string;
    /**
     * Show the layer
     */
    show: () => void;
    /**
     * Hide the layer
     */
    hide: () => void;
    /**
     * Whether the layer is currently open
     */
    isOpen: boolean;
    /**
     * Unique ID for aria-describedby
     */
    id: string;
    /**
     * Render function for layer content.
     * Pass placement and alignment for anchor positioning.
     */
    render: (children: ReactNode, props?: ContextRenderProps) => ReactNode;
}
/**
 * Return type for fixed mode
 */
export interface FixedLayerReturn {
    /**
     * Ref is undefined in fixed mode (no anchor element needed)
     */
    ref: undefined;
    /**
     * Show the layer
     */
    show: () => void;
    /**
     * Hide the layer
     */
    hide: () => void;
    /**
     * Whether the layer is currently open
     */
    isOpen: boolean;
    /**
     * Unique ID for aria-describedby
     */
    id: string;
    /**
     * Render function for layer content.
     * Pass x and y coordinates for fixed positioning.
     */
    render: (children: ReactNode, props: FixedRenderProps) => ReactNode;
}
/**
 * Compute the `position-try-fallbacks` list for a placement/alignment pair.
 *
 * Flips alone cannot rescue a centered layer — flipping along the alignment
 * axis maps center → center, so overflow on that axis renders clipped
 * (#3671). Centered alignments therefore append span-based fallbacks letting
 * the browser slide the layer along the alignment axis as a last resort
 * (same-side spans first). Flips already resolve non-centered alignments.
 */
export declare function getPositionTryFallbacks(placement?: LayerPlacement, alignment?: LayerAlignment): string;
/**
 * Core layer hook that handles popover behavior and positioning.
 *
 * Supports two positioning modes with type-safe render props:
 * - `context`: CSS anchor positioning relative to a trigger element
 * - `fixed`: Fixed positioning at specified coordinates
 *
 * @example
 * ```
 * const layer = useLayer({ mode: 'context' });
 * <button ref={layer.ref}>Trigger</button>
 * {layer.render(<Content />, { placement: 'above', alignment: 'center' })}
 * ```
 */
export declare function useLayer(options: ContextLayerOptions): ContextLayerReturn;
export declare function useLayer(options: FixedLayerOptions): FixedLayerReturn;
export {};
//# sourceMappingURL=useLayer.d.ts.map