import React from "react";
import {
  XmOverlay as XmOverlayElement,
  CustomEvent,
} from "../lit/components/overlay/index.js";

/**
 * A generic type for strongly typing custom events with their targets
 * @template T - The type of the event target (extends EventTarget)
 * @template D - The type of the detail payload for the custom event
 */
type TypedEvent<T extends EventTarget, E = Event> = E & {
  target: T;
};
/** `XmOverlay` component event */
export type XmOverlayElementEvent<E = Event> = TypedEvent<XmOverlayElement, E>;

export type { XmOverlayElement, CustomEvent };

export interface XmOverlayProps extends Pick<
  React.AllHTMLAttributes<HTMLElement>,
  | "children"
  | "dir"
  | "hidden"
  | "id"
  | "lang"
  | "slot"
  | "style"
  | "title"
  | "translate"
  | "onClick"
  | "onFocus"
  | "onBlur"
> {
  /** undefined */
  open?: boolean;

  /** Non-modal dropdowns: size the surface's border box to exactly the anchor's
width, so a width-matching listbox aligns border-to-border with its trigger
(ADR 0025). The consumer stops sizing the panel content to the anchor. */
  matchAnchorWidth?: boolean;

  /** Non-modal overlays: weld a small pointer to the surface edge facing the
anchor. It tracks the anchor's centre — when the surface is clamped at a
viewport edge the pointer slides along that edge and keeps pointing at the
trigger (ADR 0033). Opt-in, so menus and dialogs are unaffected. */
  arrow?: boolean;

  /** undefined */
  mode?: XmOverlayElement["mode"];

  /** undefined */
  tier?: XmOverlayElement["tier"];

  /** undefined */
  placement?: XmOverlayElement["placement"];

  /** undefined */
  label?: XmOverlayElement["label"];

  /** A space-separated list of the classes of the element. Classes allows CSS and JavaScript to select and access specific elements via the class selectors or functions like the method `Document.getElementsByClassName()`. */
  className?: string;

  /** Contains a space-separated list of the part names of the element that should be exposed on the host element. */
  exportparts?: string;

  /** Used for labels to link them with their inputs (using input id). */
  htmlFor?: string;

  /** Used to help React identify which items have changed, are added, or are removed within a list. */
  key?: number | string;

  /** Contains a space-separated list of the part names of the element. Part names allows CSS to select and style specific elements in a shadow tree via the ::part pseudo-element. */
  part?: string;

  /** A mutable ref object whose `.current` property is initialized to the passed argument (`initialValue`). The returned object will persist for the full lifetime of the component. */
  ref?: React.Ref<XmOverlayElement>;

  /** Allows developers to make HTML elements focusable, allow or prevent them from being sequentially focusable (usually with the `Tab` key, hence the name) and determine their relative ordering for sequential focus navigation. */
  tabIndex?: number;

  /** Trigger element to anchor a non-modal overlay against (CSS anchor()).
A property, not an attribute — it is an element reference, possibly from
another shadow root. Reactive, so re-anchoring an ALREADY-OPEN overlay
re-pins it (a delegated tooltip moving between targets, ADR 0033). */
  anchor?: XmOverlayElement["anchor"];

  /** Element focus is restored to on close. Defaults to `anchor`, else the
document's deepest activeElement at open time. */
  opener?: XmOverlayElement["opener"];

  /** Fired when the overlay opens. */
  onXmOverlayOpen?: (event: XmOverlayElementEvent) => void;

  /** Fired when the overlay closes. */
  onXmOverlayClose?: (event: XmOverlayElementEvent) => void;
}

/**
 *
 *
 * ## Attributes & Properties
 *
 * Component attributes and properties that can be applied to the element or by using JavaScript.
 *
 * - `open`: undefined
 * - `mode`: undefined
 * - `tier`: undefined
 * - `placement`: undefined
 * - `label`: undefined
 * - `match-anchor-width`/`matchAnchorWidth`: Non-modal dropdowns: size the surface's border box to exactly the anchor's
 * width, so a width-matching listbox aligns border-to-border with its trigger
 * (ADR 0025). The consumer stops sizing the panel content to the anchor.
 * - `arrow`: Non-modal overlays: weld a small pointer to the surface edge facing the
 * anchor. It tracks the anchor's centre — when the surface is clamped at a
 * viewport edge the pointer slides along that edge and keeps pointing at the
 * trigger (ADR 0033). Opt-in, so menus and dialogs are unaffected.
 * - `anchor`: Trigger element to anchor a non-modal overlay against (CSS anchor()).
 * A property, not an attribute — it is an element reference, possibly from
 * another shadow root. Reactive, so re-anchoring an ALREADY-OPEN overlay
 * re-pins it (a delegated tooltip moving between targets, ADR 0033). (property only)
 * - `opener`: Element focus is restored to on close. Defaults to `anchor`, else the
 * document's deepest activeElement at open time. (property only)
 *
 * ## Events
 *
 * Events that will be emitted by the component.
 *
 * - `xm-overlay-open`: Fired when the overlay opens.
 * - `xm-overlay-close`: Fired when the overlay closes.
 *
 * ## Methods
 *
 * Methods that can be called to access component functionality.
 *
 * - `show() => void`: undefined
 * - `hide(reason: OverlayCloseReason = "api") => void`: undefined
 * - `toggle() => void`: undefined
 */
export const XmOverlay: React.ForwardRefExoticComponent<XmOverlayProps>;