Document getAnchorRect prop for Popover component.

[desaiuditd]

Description

Add missing documentation for this hidden gem-like prop for Popover component.

Types of changes

Documentation change. (Non-breaking)

[ellatrix]

To be honest, I'm not sure if getAnchorRect is the best API we can provide. I'll have a look into this soon. In the meantime, I'm also not sure if we should document it, maybe others have an opinion on this.

[youknowriad]

I was thinking about this too and I agree that we can have a more friendly prop, "position stategy" or something like that and it could have values like "parent" (default), "element" (pass a ref there somehow)...

That said, that prop still need to be supported anyway, so I won't be against documenting it now since it's not deprecated.

[ellatrix]

Sounds good. Yeah, I was thinking if we could pass reference nodes directly to Popover... And allow a buffer to be set, an option to ignore padding, etc. Would simplify a lot of use cases.

[desaiuditd]

To be honest, I'm not sure if getAnchorRect is the best API we can provide. I'll have a look into this soon.

I wasn't aware this is going to be changed. (cc: @aprea) At my work, I stumbled upon this and I had to use it in one of the use-case that I wanted to support. So I used it and thought that this should be documented. It was hard enough for me to understand it by reading the code, and not many people would know about it. So better to document it. Happy to wait until it's matured and close this or leave this open for comments/review.

[desaiuditd]

@ellatrix @youknowriad Can this be reviewed and merged, if all okay?

[ellatrix]

@youknowriad @peterwilsoncc I'm not sure if we should be documenting this. Currently we don't use this prop at all anymore anywhere in Gutenberg. Instead we use (and should use) anchorRef.

[youknowriad]

Documenting it or not doesn't change the fact that it's a public API that we need to support. If you think it's a deprecated API, why not mark it explicitly (trigger a deprecated call?)