TourKit: First class Editor support

[mattwiebe]

Background

Currently TourKit optionally positions itself with respect to some element on the canvas with a set of referenceElements, further broken down into mobile and desktop selectors (eg). This works tolerably well for UI elements, but runs into problems with actual Block elements because:

1. The Site Editor's editor canvas is encapsulated in an iframe, which can't be addressed by a simple selector (the Post Editor and others are intended to migrate to an iframe in the future as well).
2. The desktop vs mobile distinction is over-engineered. In practice they are all identical.

Adding Editor support

Let's add a separate referenceBlock field to the WpcomStep type and use it by default, falling back to referenceElement if present and a statically positioned step in the absence of both. If the element isn't found it should fallback to no positioning. (We will also want to introduce a callback in another issue to deal with a not-found referenceBlock, possibly prompting the user to insert one, such as ensuring there's a Post Content block in the currently-edited Template, and offering to insert one.)

To start, the referenceBlock field will simply name a block type, eg core/paragraph to select. There is a very handy __experimentalGetGlobalBlocksByName selector in the @wordpress/block-editor package for just this purpose. To start with, let's simply return the 0 index of the found blocks.

This will return some clientIDs that we can then use to derive the actual DOM element for ultimately passing internally to the Popper.js library. Investigate if we can use useBlockElement and/or useBlockRef from https://github.com/WordPress/gutenberg/pull/29573 here (they are buried in internals and we may need to re-implement similar logic).

Checklist

• [ ] consolidate referenceElement to a single selector
• [ ] add the referenceBlock member to WpcomStep
• [ ] fetch the DOM node for that block type from the core/block-editor store
• [ ] ensure we have scrollIntoView logic for when the desired block is offscreen
• [ ] this will trigger a bug, (should return [0, 0]) in the Site Editor so beware. We might want to remove that modifier altogether in favour of what we do in the next step:
• [ ] adjust positioning as needed based on the iframe's document offsets, using an offset Popper modifier
• [ ] bonus: how do we reliably focus on a block's toolbar, or toolbar items therein?

Related

64080

[mattwiebe]

Some concerns originally raised in #64080 that partially prompted this issue:

Maintenance concerns with the challenge of brittle DOM selectors.

• Previous attempts at similar projects have resulted in difficult maintenance due to breakages from brittle DOM selectors changing.
• We must be mindful of which selectors may or may not be reasonably stable. Most blocks and main interface buttons at this time should be have stable selectors. However, newer features can be subject to change and we need to be cautious. If certain steps are only able to rely on unstable selectors, we should avoid using pinpoint/spotlight features.

[rjchow]

In case you missed it - https://github.com/Automattic/wp-calypso/pull/64647#issuecomment-1157360901

It's probably worth having a look at floating-ui as it's the successor of popperjs and undergoing active development