Stabilize BlockCanvas's contentRef property

[costasovo]

What problem does this address?

The contentRef property, which provides access to the editor canvas wrapping element, is currently available only in the ExperimentalBlockCanvas. This prevents third parties which use the BlockCanvas to access the canvas element via the ref.

The property is used in the VisualEditor component in wordpress/editor package to handle various visual effects, focusing blocks or handling clicks.

There is a similar use case in the Email Editor we are building for MailPoet. The editor is currently experimental, but we plan to release in the next couple of months so we want to eliminate usage of private APIs as much as possible.

Another example of usage is in IsolatedBlockEditor.

It seems that a couple of independent custom editors ended up using this property.

What is your proposed solution?

I propose exposing the contentRef property on the public BlockCanvas component PR:(#67210).

Stabilizing the contentRef prop was already proposed as part of #57672. I want to highlight the comment from @youknowriad.

BlockCanvas shouldIframe, iframeProps contentRef
I intentionally kept these props private. They were needed because of our weird implementations and backward compatibility needs in WordPress but from a third-party developer perspective, I would love for the iframe to be default (no need to provide a choice), and for the other props to be not needed. I didn't want to commit to them as API because they felt very unclear from an implementer's perspective.

It has been more than half a year since the proposal so I hope we could revisit this. Using ref/forwardRef is quite common so I wouldn't say it is unclear. My concern here that allowing access to a dom element as public API could be too powerful and hard to manage in terms of backward compatibility. What would be the alternative approach?

Pros

1. ref forwarding is known React pattern
2. it is easy to do

Cons

1. exposing a dom node to third parties allows variety of modifications and we can't fully garant backward compatibility as any change in the dom can potentially break something. We could perhaps address this by limiting the ref via useImperativeHandle

[youknowriad]

Cn you share what use-cases you're trying to achieve by exposing the content ref? Trying to understand the problem rather than the solution.

[costasovo]

Cn you share what use-cases you're trying to achieve by exposing the content ref? Trying to understand the problem rather than the solution.

As for the email editor, the important use-case is handling clicking into the canvas. When the user clicks in the non-editable template area, we show a popup that allows switching to the template mode. We also use the click event for selecting a nearest editable block, and we also merge typewriterRef into the contentRef but these are rather nice to have which we could live without.

[youknowriad]

I would love if we can solve these issues without necessarily making contentRef public as it's fairly low level.

When the user clicks in the non-editable template area, we show a popup that allows switching to the template mode.

We have something very similar in the editor package: We lock the template and handle double click on non-editable template areas to show a popup to switch to template mode. If I'm not wrong, you're using the editor package in the email editor. Is that behavior not something that worked for you?