diff --git a/packages/datetime2/src/common/datetimePopoverProps.ts b/packages/datetime2/src/common/datetimePopoverProps.ts index 205b8d3a48..ef89e2f41b 100644 --- a/packages/datetime2/src/common/datetimePopoverProps.ts +++ b/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>>; + popoverRef?: React.RefObject>; } diff --git a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx b/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx index 01dfae74b4..aae581a0f1 100644 --- a/packages/docs-app/src/examples/select-examples/multiSelectExample.tsx +++ b/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> = React.createRef(); + private popoverRef: React.RefObject> = React.createRef(); private handleAllowCreateChange = this.handleSwitchChange("allowCreate"); diff --git a/packages/popover2/src/index.ts b/packages/popover2/src/index.ts index 196c408388..4340260330 100644 --- a/packages/popover2/src/index.ts +++ b/packages/popover2/src/index.ts @@ -28,6 +28,7 @@ export { } from "./contextMenu2"; export { MenuItem2, MenuItem2Props } from "./menuItem2"; export { + DefaultPopover2TargetHTMLProps, IPopover2SharedProps, IPopover2TargetProps, Popover2SharedProps, diff --git a/packages/popover2/src/popover2.tsx b/packages/popover2/src/popover2.tsx index 982c5df02a..97f6a7bf0e 100644 --- a/packages/popover2/src/popover2.tsx +++ b/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> = IPopover2Props; +export type Popover2Props = IPopover2Props; /** @deprecated use Popover2Props */ -export interface IPopover2Props> extends Popover2SharedProps { +export interface IPopover2Props extends Popover2SharedProps { /** * 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 extends AbstractPureComponent2, IPopover2State> { public static displayName = `${DISPLAYNAME_PREFIX}.Popover2`; diff --git a/packages/popover2/src/popover2SharedProps.ts b/packages/popover2/src/popover2SharedProps.ts index 735ed83265..42d8afcfde 100644 --- a/packages/popover2/src/popover2SharedProps.ts +++ b/packages/popover2/src/popover2SharedProps.ts @@ -40,6 +40,22 @@ export type PopperModifierOverrides = Partial<{ */ export type PopperCustomModifer = Partial>; +/** + * 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; + +/** + * 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; /** diff --git a/packages/popover2/src/tooltip2.tsx b/packages/popover2/src/tooltip2.tsx index fcc3907a20..36c2dcaeb0 100644 --- a/packages/popover2/src/tooltip2.tsx +++ b/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> = ITooltip2Props; +export type Tooltip2Props = ITooltip2Props; /** @deprecated use Tooltip2Props */ -export interface ITooltip2Props> +export interface ITooltip2Props extends Omit, "shouldReturnFocusOnClose">, IntentProps { /** diff --git a/packages/select/src/common/selectPopoverProps.ts b/packages/select/src/common/selectPopoverProps.ts index aaac0f0f2a..78ca7d650f 100644 --- a/packages/select/src/common/selectPopoverProps.ts +++ b/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; /** - * 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>>; + popoverRef?: React.RefObject>; /** * HTML attributes to add to the popover target element. diff --git a/packages/select/src/components/multi-select/multiSelect2.tsx b/packages/select/src/components/multi-select/multiSelect2.tsx index bec561badd..85ef8bbdf7 100644 --- a/packages/select/src/components/multi-select/multiSelect2.tsx +++ b/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 extends AbstractPureComponent2 private refHandlers: { input: React.RefCallback; - popover: React.RefObject>>; + popover: React.RefObject>; queryList: React.RefCallback>; } = { input: refHandler(this, "input", this.props.tagInputProps?.inputRef),