[popover2] feat: export DefaultPopover2TargetHTMLProps (#5735)

packages/datetime2/src/common/datetimePopoverProps.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { Popover2, Popover2Props } from "@blueprintjs/popover2";
+import type { DefaultPopover2TargetHTMLProps, Popover2, Popover2Props } from "@blueprintjs/popover2";
 
 /**
  * Reusable collection of props for components in this package which render a `Popover2`
@@ -34,6 +34,9 @@ export interface DatetimePopoverProps {
     /**
      * Optional ref for the Popover2 component instance.
      * This is sometimes useful to reposition the popover.
+     *
+     * Note that this is defined as a specific kind of Popover2 which should be compatible with
+     * most use cases, since it uses the default target props interface.
      */
-    popoverRef?: React.RefObject<Popover2<React.HTMLProps<unknown>>>;
+    popoverRef?: React.RefObject<Popover2<DefaultPopover2TargetHTMLProps>>;
 }

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

@@ -18,7 +18,7 @@ import * as React from "react";
 
 import { Code, H5, Intent, MenuItem, Switch, TagProps } from "@blueprintjs/core";
 import { Example, ExampleProps } from "@blueprintjs/docs-theme";
-import { Popover2 } from "@blueprintjs/popover2";
+import { DefaultPopover2TargetHTMLProps, Popover2 } from "@blueprintjs/popover2";
 import { ItemRenderer, MultiSelect2 } from "@blueprintjs/select";
 import {
     areFilmsEqual,
@@ -72,7 +72,7 @@ export class MultiSelectExample extends React.PureComponent<ExampleProps, IMulti
         tagMinimal: false,
     };
 
-    private popoverRef: React.RefObject<Popover2<any>> = React.createRef();
+    private popoverRef: React.RefObject<Popover2<DefaultPopover2TargetHTMLProps>> = React.createRef();
 
     private handleAllowCreateChange = this.handleSwitchChange("allowCreate");
 

packages/popover2/src/index.ts

@@ -28,6 +28,7 @@ export {
 } from "./contextMenu2";
 export { MenuItem2, MenuItem2Props } from "./menuItem2";
 export {
+    DefaultPopover2TargetHTMLProps,
     IPopover2SharedProps,
     IPopover2TargetProps,
     Popover2SharedProps,

packages/popover2/src/popover2.tsx

@@ -36,7 +36,7 @@ import { matchReferenceWidthModifier } from "./customModifiers";
 import * as Errors from "./errors";
 import { Popover2Arrow, POPOVER_ARROW_SVG_SIZE } from "./popover2Arrow";
 import { positionToPlacement } from "./popover2PlacementUtils";
-import { Popover2SharedProps } from "./popover2SharedProps";
+import { DefaultPopover2TargetHTMLProps, Popover2SharedProps } from "./popover2SharedProps";
 import { PopupKind } from "./popupKind";
 import { ResizeSensor2 } from "./resizeSensor2";
 // eslint-disable-next-line import/no-cycle
@@ -53,9 +53,9 @@ export const Popover2InteractionKind = {
 export type Popover2InteractionKind = typeof Popover2InteractionKind[keyof typeof Popover2InteractionKind];
 
 // eslint-disable-next-line deprecation/deprecation
-export type Popover2Props<TProps = React.HTMLProps<HTMLElement>> = IPopover2Props<TProps>;
+export type Popover2Props<TProps = DefaultPopover2TargetHTMLProps> = IPopover2Props<TProps>;
 /** @deprecated use Popover2Props */
-export interface IPopover2Props<TProps = React.HTMLProps<HTMLElement>> extends Popover2SharedProps<TProps> {
+export interface IPopover2Props<TProps = DefaultPopover2TargetHTMLProps> extends Popover2SharedProps<TProps> {
     /**
      * Whether the popover/tooltip should acquire application focus when it first opens.
      *
@@ -129,7 +129,13 @@ export interface IPopover2State {
 }
 
 /**
- * @template T target element props interface
+ * Component to display a floating UI next to and tethered to a target element.
+ *
+ * @template T target element props interface. Note that we cannot assign a default value for this type param because it
+ * makes the type of the props supplied to `renderTarget()` cumbersome to work with when that API is used. Consumers
+ * wishing to stay in sync with Blueprint's default target HTML props interface should use the
+ * `DefaultPopover2TargetHTMLProps` type exported from @blueprintjs/popover2.
+ * @see https://blueprintjs.com/docs/#popover2-package/popover2
  */
 export class Popover2<T> extends AbstractPureComponent2<Popover2Props<T>, IPopover2State> {
     public static displayName = `${DISPLAYNAME_PREFIX}.Popover2`;

packages/popover2/src/popover2SharedProps.ts

@@ -40,6 +40,22 @@ export type PopperModifierOverrides = Partial<{
  */
 export type PopperCustomModifer = Partial<Modifier<any, object>>;
 
+/**
+ * Default props interface for the Popover2 target element.
+ *
+ * These props are applied to the generated target element (whose tag name is customizable via `targetTagName`)
+ * or, when the `renderTarget` API is used, sent as props to that render function.
+ *
+ * This interface is generic enough to be compatible with the various HTML attributes Popover2 needs in
+ * order to function properly, including things like event handlers and ARIA accessibility attributes.
+ */
+export type DefaultPopover2TargetHTMLProps = React.HTMLProps<HTMLElement>;
+
+/**
+ * Properties injected by Popover2 when rendering custom targets via the `renderTarget` API.
+ *
+ * @see https://blueprintjs.com/docs/#popover2-package/popover2.structure
+ */
 // eslint-disable-next-line deprecation/deprecation
 export type Popover2TargetProps = IPopover2TargetProps;
 /**

packages/popover2/src/tooltip2.tsx

@@ -23,13 +23,13 @@ import * as Classes from "./classes";
 // eslint-disable-next-line import/no-cycle
 import { Popover2, Popover2InteractionKind } from "./popover2";
 import { TOOLTIP_ARROW_SVG_SIZE } from "./popover2Arrow";
-import { Popover2SharedProps } from "./popover2SharedProps";
+import { DefaultPopover2TargetHTMLProps, Popover2SharedProps } from "./popover2SharedProps";
 import { Tooltip2Context, Tooltip2ContextState, Tooltip2Provider } from "./tooltip2Context";
 
 // eslint-disable-next-line deprecation/deprecation
-export type Tooltip2Props<TProps = React.HTMLProps<HTMLElement>> = ITooltip2Props<TProps>;
+export type Tooltip2Props<TProps = DefaultPopover2TargetHTMLProps> = ITooltip2Props<TProps>;
 /** @deprecated use Tooltip2Props */
-export interface ITooltip2Props<TProps = React.HTMLProps<HTMLElement>>
+export interface ITooltip2Props<TProps = DefaultPopover2TargetHTMLProps>
     extends Omit<Popover2SharedProps<TProps>, "shouldReturnFocusOnClose">,
         IntentProps {
     /**

packages/select/src/common/selectPopoverProps.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 
-import type { Popover2, Popover2Props } from "@blueprintjs/popover2";
+import type { DefaultPopover2TargetHTMLProps, Popover2, Popover2Props } from "@blueprintjs/popover2";
 
 /**
  * Reusable collection of props for components in this package which render a `Popover2`
@@ -27,7 +27,7 @@ export interface SelectPopoverProps {
     popoverContentProps?: React.HTMLAttributes<HTMLDivElement>;
 
     /**
-     * Props to spread to `Popover2`.
+     * Props to spread to Popover2.
      *
      * Note that `content` cannot be changed, but you may apply some props to the content wrapper element
      * with `popoverContentProps`. Likewise, `targetProps` is no longer supported as it was in Blueprint v4, but you
@@ -38,8 +38,11 @@ export interface SelectPopoverProps {
     /**
      * Optional ref for the Popover2 component instance.
      * This is sometimes useful to reposition the popover.
+     *
+     * Note that this is defined as a specific kind of Popover2 which should be compatible with
+     * most use cases, since it uses the default target props interface.
      */
-    popoverRef?: React.RefObject<Popover2<React.HTMLProps<unknown>>>;
+    popoverRef?: React.RefObject<Popover2<DefaultPopover2TargetHTMLProps>>;
 
     /**
      * HTML attributes to add to the popover target element.

packages/select/src/components/multi-select/multiSelect2.tsx

@@ -30,7 +30,7 @@ import {
     TagInputProps,
     Utils,
 } from "@blueprintjs/core";
-import { Popover2, Popover2TargetProps, PopupKind } from "@blueprintjs/popover2";
+import { DefaultPopover2TargetHTMLProps, Popover2, Popover2TargetProps, PopupKind } from "@blueprintjs/popover2";
 
 import { Classes, ListItemsProps, SelectPopoverProps } from "../../common";
 import { QueryList, QueryListRendererProps } from "../query-list/queryList";
@@ -147,7 +147,7 @@ export class MultiSelect2<T> extends AbstractPureComponent2<MultiSelect2Props<T>
 
     private refHandlers: {
         input: React.RefCallback<HTMLInputElement>;
-        popover: React.RefObject<Popover2<React.HTMLProps<HTMLDivElement>>>;
+        popover: React.RefObject<Popover2<DefaultPopover2TargetHTMLProps>>;
         queryList: React.RefCallback<QueryList<T>>;
     } = {
         input: refHandler(this, "input", this.props.tagInputProps?.inputRef),