Popover: write better docs regarding the recent API changes

[ciampo]

What?

Following up from #43691 (comment), this PR:

• adds more detailed notes about recent prop deprecations while working on the Popover component
• renames the affected CHANGELOG sections from Breaking Changes to Deprecations

@mirka I'm not sure what to do with the deprecations.md file — it looks like it hasn't been updated in some time

Dev note

Note: this dev note is a collective dev note for the recent changes to the Popover component which aimed at addressing a spike of regressions happened recently, mostly tracked in #42770

The Popover component from the @wordpress/components package has been mostly rewritten, in an effort to make it more stable, more reliable and more performant. While doing so, one of the main goals was to avoid introducing breaking changes. Here is the list with the main API changes:

• a new placement prop has been introduced. This prop is meant to replace the legacy position prop (which will be marked as deprecated in the near future)
• a new anchor prop has been introduced. This prop is meant to replace all previous anchor-related props (anchorRef, anchorRect, getAnchorRect). These older anchor-related props are now marked as deprecated and are scheduled to be removed in WordPress 6.3
• the __unstableForcePosition prop has been marked as deprecated, in favour of new flip and resize props. The __unstableForcePosition is currently scheduled for removal in WordPress 6.3
• the __unstableShift prop has been marked as deprecated, in favour of the shift prop. The __unstableShift is currently scheduled for removal in WordPress 6.3
• the __unstableObserveElement prop has been removed, since it's not necessary anymore after the recent updates to the Popover

For more details, see the updated component's README and the Storybook examples.

The changes to the Popover component also affected the @wordpress/rich-text, where a new useAnchor hook was introduced. The previous useAnchorRef hook has been marked as deprecated, and is scheduled to be removed in WordPress 6.3.

Why?

The recent changes won't cause any breakage (apart from deprecation warnings in dev mode), and therefore should not be flagged as such.

We will flag correctly the breaking changes in future versions of Gutenberg, when we will delete those deprecated props.

How?

Editing the docs

[ciampo]

@mirka it would be great if you could also take a look at the dev note, as part of the review 🙏

[mirka]

I'm not sure what to do with the deprecations.md file — it looks like it hasn't been updated in some time

Yes, I think we can leave it alone at this point 😶

component also affected the @wordpress/richt-text

Dev note looks good to me! Just one typo in the ☝️ package name here.

[mirka]

Thanks for also updating the old ones 🙏