[core] feat: Overlay2 component

packages/core/src/common/errors.ts

@@ -109,3 +109,12 @@ export const DIALOG_WARN_NO_HEADER_CLOSE_BUTTON =
 
 export const DRAWER_ANGLE_POSITIONS_ARE_CASTED =
     ns + ` <Drawer> all angle positions are casted into pure position (TOP, BOTTOM, LEFT or RIGHT)`;
+
+export const OVERLAY_CHILD_REF_REQUIRES_SINGLE_CHILD =
+    ns + ` <Overlay2> cannot have more than one child when using the childRef prop`;
+export const OVERLAY_CHILD_REF_AND_REFS_MUTEX =
+    ns + ` <Overlay2> cannot use childRef and childRefs props simultaneously`;
+export const OVERLAY_DYNAMIC_CHILDREN_REQUIRES_CHILD_REFS =
+    ns + ` <Overlay2> requires childRefs prop when rendering a dynamic number of child elements`;
+export const OVERLAY_CHILD_REQUIRES_KEY =
+    ns + ` <Overlay2> requires each child element to have a unique key prop when childRefs is used`;

packages/core/src/common/refs.ts

@@ -53,7 +53,11 @@ export function getRef<T>(ref: T | React.RefObject<T> | null): T | null {
         return null;
     }
 
-    return (ref as React.RefObject<T>).current ?? (ref as T);
+    if (typeof (ref as React.RefObject<T>).current === "undefined") {
+        return ref as T;
+    }
+
+    return (ref as React.RefObject<T>).current;
 }
 
 /**

packages/core/src/common/utils/jsUtils.ts

@@ -79,3 +79,10 @@ export function uniqueId(namespace: string) {
     uniqueCountForNamespace.set(namespace, curCount + 1);
     return `${namespace}-${curCount}`;
 }
+
+/**
+ * @returns `true` if the value is an empty string after trimming whitespace
+ */
+export function isEmptyString(val: any) {
+    return typeof val === "string" && val.trim().length === 0;
+}

packages/core/src/common/utils/reactUtils.ts

@@ -45,28 +45,40 @@ export function isReactChildrenElementOrElements(
 }
 
 /**
- * Converts a React node to an element: non-empty string or number or
- * `React.Fragment` (React 16.3+) is wrapped in given tag name; empty strings
- * and booleans are discarded.
+ * Converts a React node to an element. Non-empty strings, numbers, and Fragments will be wrapped in given tag name;
+ * empty strings and booleans will be discarded.
+ *
+ * @param child     the React node to convert
+ * @param tagName   the HTML tag name to use when a wrapper element is needed
+ * @param props     additional props to spread onto the element, if any. If the child is a React element and this argument
+ *                  is defined, the child will be cloned and these props will be merged in.
  */
-export function ensureElement(child: React.ReactNode | undefined, tagName: keyof React.JSX.IntrinsicElements = "span") {
+export function ensureElement(
+    child: React.ReactNode | undefined,
+    tagName: keyof React.JSX.IntrinsicElements = "span",
+    props: React.HTMLProps<HTMLElement> = {},
+) {
     if (child == null || typeof child === "boolean") {
         return undefined;
     } else if (typeof child === "string") {
         // cull whitespace strings
-        return child.trim().length > 0 ? React.createElement(tagName, {}, child) : undefined;
+        return child.trim().length > 0 ? React.createElement(tagName, props, child) : undefined;
     } else if (typeof child === "number" || typeof (child as any).type === "symbol" || Array.isArray(child)) {
         // React.Fragment has a symbol type, ReactNodeArray extends from Array
-        return React.createElement(tagName, {}, child);
+        return React.createElement(tagName, props, child);
     } else if (isReactElement(child)) {
-        return child;
+        if (Object.keys(props).length > 0) {
+            return React.cloneElement(child, props);
+        } else {
+            return child;
+        }
     } else {
         // child is inferred as {}
         return undefined;
     }
 }
 
-function isReactElement<T = any>(child: React.ReactNode): child is React.ReactElement<T> {
+export function isReactElement<T = any>(child: React.ReactNode): child is React.ReactElement<T> {
     return (
         typeof child === "object" &&
         typeof (child as any).type !== "undefined" &&

packages/core/src/components/alert/alert.tsx

@@ -33,7 +33,7 @@ import {
 import { Button } from "../button/buttons";
 import { Dialog } from "../dialog/dialog";
 import { Icon, type IconName } from "../icon/icon";
-import type { OverlayLifecycleProps } from "../overlay/overlay";
+import type { OverlayLifecycleProps } from "../overlay/overlayProps";
 
 export interface AlertProps extends OverlayLifecycleProps, Props {
     /**

packages/core/src/components/components.md

@@ -56,6 +56,7 @@
 @## Overlays
 
 @page overlay
+@page overlay2
 @page portal
 @page alert
 @page context-menu

packages/core/src/components/context-menu/contextMenuShared.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { OverlayLifecycleProps } from "../overlay/overlay";
+import type { OverlayLifecycleProps } from "../overlay/overlayProps";
 import type { PopoverProps } from "../popover/popover";
 
 export type Offset = {

packages/core/src/components/dialog/dialog.tsx

@@ -19,13 +19,21 @@ import * as React from "react";
 
 import { type IconName, IconSize, SmallCross } from "@blueprintjs/icons";
 
-import { AbstractPureComponent, Classes, DISPLAYNAME_PREFIX, type MaybeElement, type Props } from "../../common";
+import {
+    AbstractPureComponent,
+    Classes,
+    DISPLAYNAME_PREFIX,
+    type MaybeElement,
+    mergeRefs,
+    type Props,
+} from "../../common";
 import * as Errors from "../../common/errors";
 import { uniqueId } from "../../common/utils";
 import { Button } from "../button/buttons";
 import { H6 } from "../html/html";
 import { Icon } from "../icon/icon";
-import { type BackdropProps, Overlay, type OverlayableProps } from "../overlay/overlay";
+import type { BackdropProps, OverlayableProps } from "../overlay/overlayProps";
+import { Overlay2 } from "../overlay2/overlay2";
 
 export interface DialogProps extends OverlayableProps, BackdropProps, Props {
     /** Dialog contents. */
@@ -77,7 +85,7 @@ export interface DialogProps extends OverlayableProps, BackdropProps, Props {
     transitionName?: string;
 
     /**
-     * Ref supplied to the `Classes.DIALOG_CONTAINER` element.
+     * Ref attached to the `Classes.DIALOG_CONTAINER` element.
      */
     containerRef?: React.Ref<HTMLDivElement>;
 
@@ -106,6 +114,8 @@ export class Dialog extends AbstractPureComponent<DialogProps> {
         isOpen: false,
     };
 
+    private childRef = React.createRef<HTMLDivElement>();
+
     private titleId: string;
 
     public static displayName = `${DISPLAYNAME_PREFIX}.Dialog`;
@@ -118,21 +128,31 @@ export class Dialog extends AbstractPureComponent<DialogProps> {
     }
 
     public render() {
+        const { className, children, containerRef, style, title, ...overlayProps } = this.props;
+
         return (
-            <Overlay {...this.props} className={Classes.OVERLAY_SCROLL_CONTAINER} hasBackdrop={true}>
-                <div className={Classes.DIALOG_CONTAINER} ref={this.props.containerRef}>
+            <Overlay2
+                {...overlayProps}
+                className={Classes.OVERLAY_SCROLL_CONTAINER}
+                childRef={this.childRef}
+                hasBackdrop={true}
+            >
+                <div
+                    className={Classes.DIALOG_CONTAINER}
+                    ref={containerRef === undefined ? this.childRef : mergeRefs(containerRef, this.childRef)}
+                >
                     <div
-                        className={classNames(Classes.DIALOG, this.props.className)}
+                        className={classNames(Classes.DIALOG, className)}
                         role="dialog"
-                        aria-labelledby={this.props["aria-labelledby"] || (this.props.title ? this.titleId : undefined)}
+                        aria-labelledby={this.props["aria-labelledby"] || (title ? this.titleId : undefined)}
                         aria-describedby={this.props["aria-describedby"]}
-                        style={this.props.style}
+                        style={style}
                     >
                         {this.maybeRenderHeader()}
-                        {this.props.children}
+                        {children}
                     </div>
                 </div>
-            </Overlay>
+            </Overlay2>
         );
     }
 

packages/core/src/components/drawer/drawer.tsx

@@ -26,7 +26,8 @@ import { DISPLAYNAME_PREFIX, type MaybeElement } from "../../common/props";
 import { Button } from "../button/buttons";
 import { H4 } from "../html/html";
 import { Icon } from "../icon/icon";
-import { type BackdropProps, Overlay, type OverlayableProps } from "../overlay/overlay";
+import type { BackdropProps, OverlayableProps } from "../overlay/overlayProps";
+import { Overlay2 } from "../overlay2/overlay2";
 
 export enum DrawerSize {
     SMALL = "360px",
@@ -134,12 +135,12 @@ export class Drawer extends AbstractPureComponent<DrawerProps> {
         return (
             // N.B. the `OVERLAY_CONTAINER` class is a bit of a misnomer since it is only being used by the Drawer
             // component, but we keep it for backwards compatibility.
-            <Overlay {...overlayProps} className={classNames({ [Classes.OVERLAY_CONTAINER]: hasBackdrop })}>
+            <Overlay2 {...overlayProps} className={classNames({ [Classes.OVERLAY_CONTAINER]: hasBackdrop })}>
                 <div className={classes} style={styleProp}>
                     {this.maybeRenderHeader()}
                     {children}
                 </div>
-            </Overlay>
+            </Overlay2>
         );
     }
 

packages/core/src/components/index.ts

@@ -70,7 +70,10 @@ export { NavbarGroup, type NavbarGroupProps } from "./navbar/navbarGroup";
 export { NavbarHeading, type NavbarHeadingProps } from "./navbar/navbarHeading";
 export { NonIdealState, type NonIdealStateProps, NonIdealStateIconSize } from "./non-ideal-state/nonIdealState";
 export { OverflowList, type OverflowListProps } from "./overflow-list/overflowList";
-export { Overlay, type OverlayLifecycleProps, type OverlayProps, type OverlayableProps } from "./overlay/overlay";
+// eslint-disable-next-line deprecation/deprecation
+export { Overlay } from "./overlay/overlay";
+export type { OverlayLifecycleProps, OverlayProps, OverlayableProps } from "./overlay/overlayProps";
+export { Overlay2, type Overlay2Props, type OverlayInstance } from "./overlay2/overlay2";
 export { Text, type TextProps } from "./text/text";
 // eslint-disable-next-line deprecation/deprecation
 export { PanelStack, type PanelStackProps } from "./panel-stack/panelStack";
@@ -120,7 +123,8 @@ export { Tag, type TagProps } from "./tag/tag";
 export { TagInput, type TagInputProps, type TagInputAddMethod } from "./tag-input/tagInput";
 export { OverlayToaster, type OverlayToasterCreateOptions } from "./toast/overlayToaster";
 export type { OverlayToasterProps, ToasterPosition } from "./toast/overlayToasterProps";
-export { Toast, type ToastProps } from "./toast/toast";
+export { Toast } from "./toast/toast";
+export type { ToastProps } from "./toast/toastProps";
 export { Toaster, type ToastOptions } from "./toast/toaster";
 export { type TooltipProps, Tooltip } from "./tooltip/tooltip";
 export { Tree, type TreeProps } from "./tree/tree";

packages/core/src/components/overlay/overlay.md

@@ -1,23 +1,36 @@
 @# Overlay
 
-__Overlay__ is a generic low-level component for rendering content _on top of_ its siblings or above the entire
+<div class="@ns-callout @ns-intent-danger @ns-icon-error @ns-callout-has-body-content">
+    <h5 class="@ns-heading">
+
+Deprecated: use [**Overlay2**](#core/components/overlay2)
+
+</h5>
+
+This component is **deprecated since @blueprintjs/core v5.9.0** in favor of the new
+**Overlay2** component which is compatible with React 18 strict mode. You should migrate to the
+new API which will become the standard in Blueprint v6.
+
+</div>
+
+**Overlay** is a generic low-level component for rendering content _on top of_ its siblings or above the entire
 application.
 
-It combines the functionality of the [__Portal__](#core/components/portal) component (which allows React elements to
-escape their current DOM hierarchy) with a [__CSSTransitionGroup__](https://reactcommunity.org/react-transition-group/)
+It combines the functionality of the [**Portal**](#core/components/portal) component (which allows React elements to
+escape their current DOM hierarchy) with a [**CSSTransitionGroup**](https://reactcommunity.org/react-transition-group/)
 (to show elegant enter and leave transitions).
 
 An optional "backdrop" element can be rendered behind the overlaid children to provide modal behavior, whereby the
 overlay prevents interaction with anything behind it.
 
-__Overlay__ is the backbone of all the components listed in the **Overlays** group in the sidebar. Using __Overlay__
+**Overlay** is the backbone of all the components listed in the **Overlays** group in the sidebar. Using **Overlay**
 directly should be rare in your application; it should only be necessary if no existing component meets your needs.
 
 @reactExample OverlayExample
 
 @## Usage
 
-__Overlay__ is a controlled component that renders its children only when `isOpen={true}`. The optional backdrop element
+**Overlay** is a controlled component that renders its children only when `isOpen={true}`. The optional backdrop element
 will be inserted before the children if `hasBackdrop={true}`.
 
 The `onClose` callback prop is invoked when user interaction causes the overlay to close, but your application is
@@ -50,7 +63,7 @@ scrollable, so any overflowing content will be hidden. Fortunately, making an ov
 <Overlay className={Classes.OVERLAY_SCROLL_CONTAINER} />
 ```
 
-Note that the [__Dialog__](https://blueprintjs.com/docs/#core/components/dialog) component applies this CSS class
+Note that the [**Dialog**](https://blueprintjs.com/docs/#core/components/dialog) component applies this CSS class
 automatically.
 
 @## Props interface