@primer/react/dist/AnchoredOverlay/AnchoredOverlay.d.ts

An implementation of GitHub's Primer Design System using React

import { IconButtonProps } from "../Button/types.js";
import { ResponsiveValue } from "../hooks/useResponsiveValue.js";
import { FocusTrapHookSettings } from "../hooks/useFocusTrap.js";
import { FocusZoneHookSettings } from "../hooks/useFocusZone.js";
import { OverlayProps } from "../Overlay/Overlay.js";
import React, { JSX } from "react";
import { AnchorPosition, PositionSettings } from "@primer/behaviors";

//#region src/AnchoredOverlay/AnchoredOverlay.d.ts
interface AnchoredOverlayPropsWithAnchor {
  /**
   * A custom function component used to render the anchor element.
   * Will receive the selected text as `children` prop when an item is activated.
   */
  renderAnchor: <T extends Omit<React.HTMLAttributes<HTMLElement>, 'aria-label' | 'aria-labelledby'>>(props: T) => JSX.Element;
  /**
   * An override to the internal ref that will be spread on to the renderAnchor
   */
  anchorRef?: React.RefObject<HTMLElement | null>;
  /**
   * An override to the internal id that will be spread on to the renderAnchor
   */
  anchorId?: string;
}
interface AnchoredOverlayPropsWithoutAnchor {
  /**
   * A custom function component used to render the anchor element.
   * When renderAnchor is null, an anchorRef is required.
   */
  renderAnchor: null;
  /**
   * An override to the internal renderAnchor ref that will be used to position the overlay.
   * When renderAnchor is null this can be used to make an anchor that is detached from ActionMenu.
   */
  anchorRef: React.RefObject<HTMLElement | null>;
  /**
   * An override to the internal id that will be spread on to the renderAnchor
   */
  anchorId?: string;
}
type AnchoredOverlayWrapperAnchorProps = Partial<AnchoredOverlayPropsWithAnchor> | AnchoredOverlayPropsWithoutAnchor;
interface AnchoredOverlayBaseProps extends Pick<OverlayProps, 'height' | 'width'> {
  /**
   * Determines whether the overlay portion of the component should be shown or not
   */
  open: boolean;
  /**
   * A callback which is called whenever the overlay is currently closed and an "open gesture" is detected.
   */
  onOpen?: (gesture: 'anchor-click' | 'anchor-key-press', event?: React.KeyboardEvent<HTMLElement>) => unknown;
  /**
   * A callback which is called whenever the overlay is currently open and a "close gesture" is detected.
   */
  onClose?: (gesture: 'anchor-click' | 'click-outside' | 'escape' | 'close') => unknown;
  /**
   * Props to be spread on the internal `Overlay` component.
   */
  overlayProps?: Partial<OverlayProps>;
  /**
   * Settings to apply to the Focus Zone on the internal `Overlay` component.
   */
  focusTrapSettings?: Partial<FocusTrapHookSettings>;
  /**
   * Settings to apply to the Focus Zone on the internal `Overlay` component.
   */
  focusZoneSettings?: Partial<FocusZoneHookSettings>;
  /**
   * Optional className to be added to the overlay component.
   */
  className?: string;
  /**
   * preventOverflow Optional. The Overlay width will be adjusted responsively if there is not enough space to display the Overlay.
   * If `preventOverflow` is `true`, the width of the `Overlay` will not be adjusted.
   */
  preventOverflow?: boolean;
  /**
   * If true, the overlay will attempt to prevent position shifting when sitting at the top of the anchor.
   */
  pinPosition?: boolean;
  /**
   * Optional prop to set variant for narrow screen sizes
   */
  variant?: ResponsiveValue<'anchored', 'anchored' | 'fullscreen'>;
  /**
   * An override to the internal position that will be used to position the overlay.
   */
  onPositionChange?: ({
    position
  }: {
    position: AnchorPosition;
  }) => void;
  /**
   * Optional prop to display a close button in the overlay.
   */
  displayCloseButton?: boolean;
  /**
   * Props to be spread on the close button in the overlay.
   */
  closeButtonProps?: Partial<IconButtonProps>;
  /**
   * When `"popover"`, uses the Popover API only if the CSS anchor positioning feature flag is enabled
   * and the browser supports native CSS anchor positioning. Has no effect otherwise. Defaults to `"portal"`.
   */
  renderAs?: 'portal' | 'popover';
  /**
   * Settings for CSS anchor positioning behavior when CSS anchor positioning is active.
   *
   * `fallbackStrategy` controls CSS fallback behavior:
   * - `"default"`: use built-in CSS fallback rules.
   * - `"none"`: keep the requested side with no CSS fallbacks.
   * - `"opposite-side"`: only allow fallback to the opposite side.
   *
   * `disable`: When `true`, opts this overlay out of native CSS anchor positioning (and the Popover API)
   *   even if `primer_react_css_anchor_positioning` is enabled and the browser supports it.
   */
  cssAnchorPositioningSettings?: {
    fallbackStrategy?: 'default' | 'none' | 'opposite-side';
    disable?: boolean;
  };
}
type AnchoredOverlayProps = AnchoredOverlayBaseProps & (AnchoredOverlayPropsWithAnchor | AnchoredOverlayPropsWithoutAnchor) & Partial<Pick<PositionSettings, 'align' | 'side' | 'anchorOffset' | 'alignmentOffset' | 'displayInViewport'>>;
/**
 * An `AnchoredOverlay` provides an anchor that will open a floating overlay positioned relative to the anchor.
 * The overlay can be opened and navigated using keyboard or mouse.
 */
declare const AnchoredOverlay: React.FC<React.PropsWithChildren<AnchoredOverlayProps>>;
//#endregion
export { AnchoredOverlay, AnchoredOverlayProps, AnchoredOverlayWrapperAnchorProps };