/**
 * Anchor positioning — positions a popover/panel relative to an anchor
 * element. Uses native CSS Anchor Positioning when supported (Chrome
 * 125+), falls back to a JS implementation (`getBoundingClientRect()` +
 * `position: fixed`) otherwise.
 *
 * Works with the Popover API: the popover renders in the top layer via
 * `showPopover()` on a `popover="manual"` or `popover="auto"` element,
 * and the position is wired with either `anchor()` + `position-area` or
 * manual coords.
 *
 * Runtime exports mirror `core/anchor.js`. `.d.ts` authored in v0.5.6
 * §191 to close the §178 audit-script baseline missing-sibling gap.
 *
 * @see ./anchor.js (runtime SoT)
 * @see ../USAGE.md (consumer guide)
 */

/**
 * Placement vocabulary for {@link anchorPopover}. Mirrors a subset of
 * the floating-ui / Popper conventions. `-start` aligns the popover's
 * leading edge to the anchor's leading edge along the perpendicular
 * axis; `-end` aligns the trailing edges; bare (no suffix) centers.
 */
export type Placement =
  | 'bottom'
  | 'bottom-start'
  | 'bottom-end'
  | 'top'
  | 'top-start'
  | 'top-end'
  | 'left'
  | 'left-start'
  | 'left-end'
  | 'right'
  | 'right-start'
  | 'right-end';

/**
 * Options for {@link anchorPopover}.
 */
export interface AnchorOptions {
  /** Where to place the popover relative to its anchor. Default: `bottom-start`. */
  placement?: Placement;
  /** Pixel gap on the main (anchor-adjacent) axis. Default: 4. */
  gap?: number;
  /**
   * When true, the popover's `width` is constrained to match the
   * anchor's width — useful for combobox-style listboxes.
   */
  matchWidth?: boolean;
}

/**
 * `true` when the current browser supports the CSS Anchor Positioning
 * primitives the native path uses (`anchor-name`, `position-area`).
 * `false` otherwise (browser falls back to the JS positioning path).
 */
export const supportsAnchorCSS: boolean;

/**
 * Position `popover` relative to `anchor`. Picks the native CSS Anchor
 * Positioning path when available, otherwise the JS fallback. Returns a
 * cleanup function — call it to detach listeners / restore inline
 * styles.
 */
export function anchorPopover(
  anchor: Element,
  popover: HTMLElement,
  options?: AnchorOptions,
): () => void;
