You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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).
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 WordPress/gutenberg#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?
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.
Background
Currently
TourKit
optionally positions itself with respect to some element on the canvas with a set ofreferenceElements
, further broken down intomobile
anddesktop
selectors (eg). This works tolerably well for UI elements, but runs into problems with actual Block elements because:desktop
vsmobile
distinction is over-engineered. In practice they are all identical.Adding Editor support
Let's add a separate
referenceBlock
field to theWpcomStep
type and use it by default, falling back toreferenceElement
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-foundreferenceBlock
, 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, egcore/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 the0
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 useuseBlockElement
and/oruseBlockRef
from WordPress/gutenberg#29573 here (they are buried in internals and we may need to re-implement similar logic).Checklist
referenceElement
to a single selectorreferenceBlock
member toWpcomStep
core/block-editor
storescrollIntoView
logic for when the desired block is offscreenreturn [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:offset
Popper modifierRelated
#64080
The text was updated successfully, but these errors were encountered: