search

WordPress / gutenberg

The Block Editor project for WordPress and beyond. Plugin is available from the official repository.
https://wordpress.org/gutenberg/
Other
10.53k stars 4.21k forks source link

Stabilize BlockCanvas's contentRef property #67209

Open costasovo opened 15 hours ago

costasovo commented 15 hours ago

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:(https://github.com/WordPress/gutenberg/pull/67210).

Stabilizing the contentRef prop was already proposed as part of https://github.com/WordPress/gutenberg/issues/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 commented 15 hours ago

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.