1 | import * as React from "react";
|
2 | import { AbstractPureComponent2 } from "../../common";
|
3 | import { Props } from "../../common/props";
|
4 | export declare type OverlayableProps = IOverlayableProps;
|
5 | /** @deprecated use OverlayableProps */
|
6 | export 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 | }
|
89 | export declare type OverlayLifecycleProps = IOverlayLifecycleProps;
|
90 | export 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 | }
|
114 | export declare type BackdropProps = IBackdropProps;
|
115 | export 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 | }
|
134 | export declare type OverlayProps = IOverlayProps;
|
135 | /** @deprecated use OverlayProps */
|
136 | export 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 | }
|
152 | export interface IOverlayState {
|
153 | hasEverOpened?: boolean;
|
154 | }
|
155 | export declare class Overlay extends AbstractPureComponent2<OverlayProps, IOverlayState> {
|
156 | static displayName: string;
|
157 | static defaultProps: OverlayProps;
|
158 | static getDerivedStateFromProps({ isOpen: hasEverOpened }: OverlayProps): {
|
159 | hasEverOpened: true;
|
160 | } | null;
|
161 | private static openStack;
|
162 | private static getLastOpened;
|
163 | private isAutoFocusing;
|
164 | private lastActiveElementBeforeOpened;
|
165 | state: IOverlayState;
|
166 | containerElement: HTMLElement | null;
|
167 | private startFocusTrapElement;
|
168 | private endFocusTrapElement;
|
169 | private refHandlers;
|
170 | render(): JSX.Element | null;
|
171 | componentDidMount(): void;
|
172 | componentDidUpdate(prevProps: OverlayProps): void;
|
173 | componentWillUnmount(): void;
|
174 | private maybeRenderChild;
|
175 | private maybeRenderBackdrop;
|
176 | private renderDummyElement;
|
177 | /**
|
178 | * Ensures repeatedly pressing shift+tab keeps focus inside the Overlay. Moves focus to
|
179 | * the `endFocusTrapElement` or the first keyboard-focusable element in the Overlay (excluding
|
180 | * the `startFocusTrapElement`), depending on whether the element losing focus is inside the
|
181 | * Overlay.
|
182 | */
|
183 | private handleStartFocusTrapElementFocus;
|
184 | /**
|
185 | * Wrap around to the end of the dialog if `enforceFocus` is enabled.
|
186 | */
|
187 | private handleStartFocusTrapElementKeyDown;
|
188 | /**
|
189 | * Ensures repeatedly pressing tab keeps focus inside the Overlay. Moves focus to the
|
190 | * `startFocusTrapElement` or the last keyboard-focusable element in the Overlay (excluding the
|
191 | * `startFocusTrapElement`), depending on whether the element losing focus is inside the
|
192 | * Overlay.
|
193 | */
|
194 | private handleEndFocusTrapElementFocus;
|
195 | private getKeyboardFocusableElements;
|
196 | private overlayWillClose;
|
197 | private overlayWillOpen;
|
198 | private handleTransitionExited;
|
199 | private handleBackdropMouseDown;
|
200 | private handleDocumentClick;
|
201 | /**
|
202 | * When multiple Overlays are open, this event handler is only active for the most recently
|
203 | * opened one to avoid Overlays competing with each other for focus.
|
204 | */
|
205 | private handleDocumentFocus;
|
206 | private handleKeyDown;
|
207 | private handleTransitionAddEnd;
|
208 | }
|