[Popover] Allow more flexible Popover reference position calculation

[robin-drexler]

Issue summary

When the activator of a Popover (or PositonedOverlay) contains an input element, the Overlay always uses said element to calculate its position and width/height.

That behavior causes at least two issues:

When an activator contains an input that is hidden, the Overlay will have no width.

When a TextInput has an icon prefix, the Overlay will not expand to the TextInput's full width. It will not account for the width of the icon. This is usually the desired behavior. However, that is not always the case. We have at least one instance where we'd like to stretch the Overlay to the TextInput's full width.

We have a few ideas on how to address this issue and would like to discuss them:

1. Introduce a preferInputActivator prop to the Popover (and hence PositonedOverlay component). This prop would be true by default to not introduce a breaking change.

   When it's true, the behavior does not change. The Overlay will continue to search for an input, and if it finds one, use it. If the consumer sets the prop to false, the Overlay will never search for an input and always use the activator to calculate its dimensions.

2. Introduce a getActivatorReferencePositionNode (name to be determined) prop. That'd be a function that the consumer can pass to return the node that should act as the reference for the Overlay's dimension calculation.

   The activator node would be passed as an argument. The default implementation would be non-breaking. We'd still search for the input and use that if it exists. However, this would allow us to override the function to return the activator where we want to use that instead.

This approach would also allow users to customize the position calculation beyond using an input or not.

Reduced test case

Case for overlay not being shown at all when non-visible input is inside activator: https://codesandbox.io/s/eloquent-edison-skb9f

Case for not expanding when TextInput has icon: https://codesandbox.io/s/cocky-mendel-my3v8

Specifications

• Are you using the React components? (Y/N): Y
• Polaris version number: 4.13.`
• Browser: all
• Device: all
• Operating System: all

[dleroux]

I prefer the first solution, simpler and more in line with what we do for these types of changes. I was thinking of just removing the selector in the next version of Polaris, but this really has very little impact and is more flexible.

[robin-drexler]

@dleroux thanks for your feedback. We gave it a shot right away in #2754 :)