UNPKG

8.28 kBTypeScriptView Raw
1import * as React from "react";
2import { AbstractPureComponent2 } from "../../common";
3import { Props } from "../../common/props";
4export declare type OverlayableProps = IOverlayableProps;
5/** @deprecated use OverlayableProps */
6export interface IOverlayableProps extends IOverlayLifecycleProps {
7 /**
8 * Whether the overlay should acquire application focus when it first opens.
9 *
10 * @default true
11 */
12 autoFocus?: boolean;
13 /**
14 * Whether pressing the `esc` key should invoke `onClose`.
15 *
16 * @default true
17 */
18 canEscapeKeyClose?: boolean;
19 /**
20 * Whether the overlay should prevent focus from leaving itself. That is, if the user attempts
21 * to focus an element outside the overlay and this prop is enabled, then the overlay will
22 * immediately bring focus back to itself. If you are nesting overlay components, either disable
23 * this prop on the "outermost" overlays or mark the nested ones `usePortal={false}`.
24 *
25 * @default true
26 */
27 enforceFocus?: boolean;
28 /**
29 * If `true` and `usePortal={true}`, the `Portal` containing the children is created and attached
30 * to the DOM when the overlay is opened for the first time; otherwise this happens when the
31 * component mounts. Lazy mounting provides noticeable performance improvements if you have lots
32 * of overlays at once, such as on each row of a table.
33 *
34 * @default true
35 */
36 lazy?: boolean;
37 /**
38 * Whether the application should return focus to the last active element in the
39 * document after this overlay closes.
40 *
41 * @default true
42 */
43 shouldReturnFocusOnClose?: boolean;
44 /**
45 * Indicates how long (in milliseconds) the overlay's enter/leave transition takes.
46 * This is used by React `CSSTransition` to know when a transition completes and must match
47 * the duration of the animation in CSS. Only set this prop if you override Blueprint's default
48 * transitions with new transitions of a different length.
49 *
50 * @default 300
51 */
52 transitionDuration?: number;
53 /**
54 * Whether the overlay should be wrapped in a `Portal`, which renders its contents in a new
55 * element attached to `portalContainer` prop.
56 *
57 * This prop essentially determines which element is covered by the backdrop: if `false`,
58 * then only its parent is covered; otherwise, the entire page is covered (because the parent
59 * of the `Portal` is the `<body>` itself).
60 *
61 * Set this prop to `false` on nested overlays (such as `Dialog` or `Popover`) to ensure that they
62 * are rendered above their parents.
63 *
64 * @default true
65 */
66 usePortal?: boolean;
67 /**
68 * Space-delimited string of class names applied to the `Portal` element if
69 * `usePortal={true}`.
70 */
71 portalClassName?: string;
72 /**
73 * The container element into which the overlay renders its contents, when `usePortal` is `true`.
74 * This prop is ignored if `usePortal` is `false`.
75 *
76 * @default document.body
77 */
78 portalContainer?: HTMLElement;
79 /**
80 * A callback that is invoked when user interaction causes the overlay to close, such as
81 * clicking on the overlay or pressing the `esc` key (if enabled).
82 *
83 * Receives the event from the user's interaction, if there was an event (generally either a
84 * mouse or key event). Note that, since this component is controlled by the `isOpen` prop, it
85 * will not actually close itself until that prop becomes `false`.
86 */
87 onClose?: (event: React.SyntheticEvent<HTMLElement>) => void;
88}
89export declare type OverlayLifecycleProps = IOverlayLifecycleProps;
90export interface IOverlayLifecycleProps {
91 /**
92 * Lifecycle method invoked just before the CSS _close_ transition begins on
93 * a child. Receives the DOM element of the child being closed.
94 */
95 onClosing?: (node: HTMLElement) => void;
96 /**
97 * Lifecycle method invoked just after the CSS _close_ transition ends but
98 * before the child has been removed from the DOM. Receives the DOM element
99 * of the child being closed.
100 */
101 onClosed?: (node: HTMLElement) => void;
102 /**
103 * Lifecycle method invoked just after mounting the child in the DOM but
104 * just before the CSS _open_ transition begins. Receives the DOM element of
105 * the child being opened.
106 */
107 onOpening?: (node: HTMLElement) => void;
108 /**
109 * Lifecycle method invoked just after the CSS _open_ transition ends.
110 * Receives the DOM element of the child being opened.
111 */
112 onOpened?: (node: HTMLElement) => void;
113}
114export declare type BackdropProps = IBackdropProps;
115export interface IBackdropProps {
116 /** CSS class names to apply to backdrop element. */
117 backdropClassName?: string;
118 /** HTML props for the backdrop element. */
119 backdropProps?: React.HTMLProps<HTMLDivElement>;
120 /**
121 * Whether clicking outside the overlay element (either on backdrop when present or on document)
122 * should invoke `onClose`.
123 *
124 * @default true
125 */
126 canOutsideClickClose?: boolean;
127 /**
128 * Whether a container-spanning backdrop element should be rendered behind the contents.
129 *
130 * @default true
131 */
132 hasBackdrop?: boolean;
133}
134export declare type OverlayProps = IOverlayProps;
135/** @deprecated use OverlayProps */
136export interface IOverlayProps extends OverlayableProps, IBackdropProps, Props {
137 /** Element to overlay. */
138 children?: React.ReactNode;
139 /**
140 * Toggles the visibility of the overlay and its children.
141 * This prop is required because the component is controlled.
142 */
143 isOpen: boolean;
144 /**
145 * Name of the transition for internal `CSSTransition`.
146 * Providing your own name here will require defining new CSS transition properties.
147 *
148 * @default Classes.OVERLAY
149 */
150 transitionName?: string;
151}
152export interface IOverlayState {
153 hasEverOpened?: boolean;
154}
155/**
156 * Overlay component.
157 *
158 * @see https://blueprintjs.com/docs/#core/components/overlay
159 */
160export declare class Overlay extends AbstractPureComponent2<OverlayProps, IOverlayState> {
161 static displayName: string;
162 static defaultProps: OverlayProps;
163 static getDerivedStateFromProps({ isOpen: hasEverOpened }: OverlayProps): {
164 hasEverOpened: true;
165 } | null;
166 private static openStack;
167 private static getLastOpened;
168 private isAutoFocusing;
169 private lastActiveElementBeforeOpened;
170 state: IOverlayState;
171 containerElement: HTMLElement | null;
172 private startFocusTrapElement;
173 private endFocusTrapElement;
174 private refHandlers;
175 render(): JSX.Element | null;
176 componentDidMount(): void;
177 componentDidUpdate(prevProps: OverlayProps): void;
178 componentWillUnmount(): void;
179 private maybeRenderChild;
180 private maybeRenderBackdrop;
181 private renderDummyElement;
182 /**
183 * Ensures repeatedly pressing shift+tab keeps focus inside the Overlay. Moves focus to
184 * the `endFocusTrapElement` or the first keyboard-focusable element in the Overlay (excluding
185 * the `startFocusTrapElement`), depending on whether the element losing focus is inside the
186 * Overlay.
187 */
188 private handleStartFocusTrapElementFocus;
189 /**
190 * Wrap around to the end of the dialog if `enforceFocus` is enabled.
191 */
192 private handleStartFocusTrapElementKeyDown;
193 /**
194 * Ensures repeatedly pressing tab keeps focus inside the Overlay. Moves focus to the
195 * `startFocusTrapElement` or the last keyboard-focusable element in the Overlay (excluding the
196 * `startFocusTrapElement`), depending on whether the element losing focus is inside the
197 * Overlay.
198 */
199 private handleEndFocusTrapElementFocus;
200 private getKeyboardFocusableElements;
201 private overlayWillClose;
202 private overlayWillOpen;
203 private handleTransitionExited;
204 private handleBackdropMouseDown;
205 private handleDocumentClick;
206 /**
207 * When multiple Overlays are open, this event handler is only active for the most recently
208 * opened one to avoid Overlays competing with each other for focus.
209 */
210 private handleDocumentFocus;
211 private handleKeyDown;
212 private handleTransitionAddEnd;
213}