[core] chore: docs improvements for Drawer, Overlay, Omnibar (#6654)

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

@@ -38,11 +38,9 @@ export interface DialogProps extends OverlayableProps, BackdropProps, Props {
     isOpen: boolean;
 
     /**
-     * Dialog always has a backdrop so this prop is excluded from the public API.
-     *
-     * @internal
+     * Dialog always has a backdrop so this prop cannot be overriden.
      */
-    hasBackdrop?: boolean;
+    hasBackdrop?: never;
 
     /**
      * Name of a Blueprint UI icon (or an icon element) to render in the

packages/core/src/components/drawer/drawer.md

@@ -1,18 +1,21 @@
 @# Drawer
 
-__Drawers__ overlay content over existing parts of the UI and are anchored to the edge of the screen.
+**Drawers** overlay content over existing parts of the UI and are anchored to the edge of the screen. It is built using
+the lower-level [**Overlay**](#core/components/overlay) component.
 
 @reactExample DrawerExample
 
-@## Props interface
+@## Usage
 
-__Drawer__ is a stateless React component controlled by the `isOpen` prop.
+`<Drawer>` is a stateless React component controlled by its `isOpen` prop.
 
-Use the `size` prop to set the size of the __Drawer__. This prop sets CSS `width` if `vertical={false}` (default)
+Use the `size` prop to set the size of a **Drawer**. This prop sets CSS `width` if `vertical={false}` (default)
 and `height` otherwise. Constants are available for common sizes:
 
 -   `DrawerSize.SMALL = 360px`
 -   `DrawerSize.STANDARD = 50%` (default)
 -   `DrawerSize.LARGE = 90%`
 
+@## Props interface
+
 @interface DrawerProps

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

@@ -130,7 +130,10 @@ export class Drawer extends AbstractPureComponent<DrawerProps> {
                       ...style,
                       [isPositionHorizontal(realPosition) ? "height" : "width"]: size,
                   };
+
         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 })}>
                 <div className={classes} style={styleProp}>
                     {this.maybeRenderHeader()}

packages/core/src/components/overlay/_overlay.scss

@@ -21,6 +21,8 @@ body.#{$ns}-overlay-open {
     pointer-events: none;
   }
 
+  // N.B. this class name is a bit of a misnomer since it is only being used by the Drawer component. It also
+  // shares quite a bit with the "overlay-scroll-container" class, so it's due for a DRY refactor.
   &.#{$ns}-overlay-container {
     overflow: hidden;
     // container covers the entire viewport

packages/core/src/components/overlay/overlay.tsx

@@ -172,6 +172,7 @@ export interface BackdropProps {
 
     /**
      * Whether a container-spanning backdrop element should be rendered behind the contents.
+     * When `false`, users will be able to scroll through and interact with overlaid content.
      *
      * @default true
      */

packages/docs-app/src/examples/select-examples/omnibarExample.tsx

@@ -40,18 +40,24 @@ import {
 export interface OmnibarExampleState {
     allowCreate: boolean;
     isOpen: boolean;
+    overlayHasBackdrop: boolean;
     resetOnSelect: boolean;
 }
 
 export class OmnibarExample extends React.PureComponent<ExampleProps, OmnibarExampleState> {
     public state: OmnibarExampleState = {
         allowCreate: false,
         isOpen: false,
+        overlayHasBackdrop: true,
         resetOnSelect: true,
     };
 
     private handleAllowCreateChange = handleBooleanChange(allowCreate => this.setState({ allowCreate }));
 
+    private handleOverlayHasBackdropChange = handleBooleanChange(overlayHasBackdrop =>
+        this.setState({ overlayHasBackdrop }),
+    );
+
     private handleResetChange = handleBooleanChange(resetOnSelect => this.setState({ resetOnSelect }));
 
     private toaster: Toaster;
@@ -61,7 +67,7 @@ export class OmnibarExample extends React.PureComponent<ExampleProps, OmnibarExa
     };
 
     public render() {
-        const { allowCreate } = this.state;
+        const { allowCreate, overlayHasBackdrop } = this.state;
 
         const maybeCreateNewItemFromQuery = allowCreate ? createFilm : undefined;
         const maybeCreateNewItemRenderer = allowCreate ? renderCreateFilmMenuItem : null;
@@ -97,6 +103,7 @@ export class OmnibarExample extends React.PureComponent<ExampleProps, OmnibarExa
                         noResults={<MenuItem disabled={true} text="No results." />}
                         onClose={this.handleClose}
                         onItemSelect={this.handleItemSelect}
+                        overlayProps={{ hasBackdrop: overlayHasBackdrop }}
                     />
                     <OverlayToaster position={Position.TOP} ref={this.refHandlers.toaster} />
                 </Example>
@@ -105,15 +112,23 @@ export class OmnibarExample extends React.PureComponent<ExampleProps, OmnibarExa
     }
 
     protected renderOptions() {
+        const { allowCreate, overlayHasBackdrop, resetOnSelect } = this.state;
+
         return (
             <>
                 <H5>Props</H5>
-                <Switch label="Reset on select" checked={this.state.resetOnSelect} onChange={this.handleResetChange} />
+                <Switch label="Reset on select" checked={resetOnSelect} onChange={this.handleResetChange} />
                 <Switch
                     label="Allow creating new films"
-                    checked={this.state.allowCreate}
+                    checked={allowCreate}
                     onChange={this.handleAllowCreateChange}
                 />
+                <H5>Overlay props</H5>
+                <Switch
+                    label="Has backdrop"
+                    checked={overlayHasBackdrop}
+                    onChange={this.handleOverlayHasBackdropChange}
+                />
             </>
         );
     }

packages/select/src/components/omnibar/omnibar.md

@@ -1,16 +1,19 @@
 @# Omnibar
 
-__Omnibar__ is a macOS Spotlight-style typeahead component built using [__Overlay__](#core/components/overlay) and
-[__QueryList__](#select/query-list). Its usage is similar to that of [__Select__](#select/select-component): provide
-your items and a predicate to customize the filtering algorithm. The component is fully controlled via the `isOpen`
-prop, which means you can decide exactly how to trigger the component. The following example responds to a button and
-a hotkey.
+**Omnibar** is a macOS Spotlight-style typeahead component built using [**Overlay**](#core/components/overlay) and
+[**QueryList**](#select/query-list). Its usage is similar to that of [**Select**](#select/select-component): provide
+your items and a predicate to customize the filtering algorithm.
 
-`Omnibar<T>` is a _generic component_ where `<T>` represents the type of one item in the array of `items`.
+The following example responds to a button and a hotkey.
 
 @reactExample OmnibarExample
 
+@## Usage
+
+In TypeScript, `Omnibar<T>` is a _generic component_ where `<T>` represents the type of one item in the array of `items`.
+
+The component is fully controlled via the `isOpen` prop, which means you can decide exactly how to trigger it.
+
 @## Props interface
 
 @interface OmnibarProps
-

packages/select/src/components/select/select-component.md

@@ -10,6 +10,10 @@ You may provide a predicate to customize the filtering algorithm. The value of a
 
 @## Usage
 
+In TypeScript, `Select<T>` is a _generic component_ so you must define a local type that specifies `<T>`, the type of
+one item in `items`. The props on this local type will now operate on your data type so you can easily define handlers
+without transformation steps, but most props are required as a result.
+
 ```tsx
 import { Button, MenuItem } from "@blueprintjs/core";
 import { ItemPredicate, ItemRenderer, Select } from "@blueprintjs/select";
@@ -75,10 +79,6 @@ const FilmSelect: React.FC = () => {
 ReactDOM.render(<FilmSelect />, document.querySelector("#root"));
 ```
 
-In TypeScript, `Select<T>` is a _generic component_ so you must define a local type that specifies `<T>`, the type of
-one item in `items`. The props on this local type will now operate on your data type so you can easily define handlers
-without transformation steps, but most props are required as a result.
-
 @## Props interface
 
 @interface SelectProps