New concept: block attribute sets

[dmsnell]

In this discussion I'd like to introduce and share design work on a new concept to the block API, what I'm currently calling "attribute sets." Attribute sets give block authors a way to classify relevance of specific block attributes in different contexts to let the editor make more informed decisions in those contexts.

Related

• Block API: Add role for 'internal' attributes not copied on duplication #34750

Description and motivation

Let us consider different contexts that exist while editing a document:

• undo/redo, where we want to review our changes and maybe choose a different revision
• styling, where we want to adjust the purely-visual aspects of how our block is rendered
• content, where we are discussing the ultimate content a block represents, content which might be translatable into new forms, for example, a transcript, an image description, a plaintext watch notification
• identity, lacking a better name, where we are determining what essentially represents a block, which might include an overlap of content, styling, and other metadata.

These contexts provide a basis for classifying block attributes so that we don't have to treat every block attribute in the same way. These classifications can provide new and enhanced functionality such as:

• Copy the visual style from one block and apply it to another.
• Copy only the content from one block and paste it into another (paste without formatting).
• Relax validation constraints that often break legitimate blocks because of minor attribute differences.
• Improve the undo/redo behaviors by removing jarring and corrupting flows.
• Allow extra CSS classes, style attributes, or HTML attributes without treating them in the block validation flow.

Design

It's tempting to look at these use-cases and build the inverse of what is proposed here: classifyAttributes where we specify which context each attribute applies to. However, the categories overlap and so it's not appropriate to force a 1:1 mapping. It's also more burdensome to classify attributes into contexts than to report membership into a context of the set of attributes.

When registering a block with registerBlockType we can add a new optional setting, attributeSets( context, attributes ), giving block authors the ability to perform the classification and to do so dynamically based not only on the names of the attributes but also their values.

const attributeSets = ( attributes, context, contextData ) => {
	switch ( context ) {
		case 'undo/redo': {
			// don't revert to the temporary/local image upload data
			if ( contextData.attributes.src.startsWith( 'data:') ) {
				const { src, ...undoableAttributes } = attributes;
				return undoableAttributes;
			}
			return attributes;
		}

		case 'style':
			return [ 'alignment', 'size' ];
	}
}

Return type

The inputs to this function don't need to be that complicated in order to provide a useful and easy API. The return type, however, will determine how confusing it is to use. There are different answers we might want to give to the question:

• Which attributes should be included in this context? (specify only those we want to include)
• Which attributes should be excluded in this context? (specify only those we want to ignore)
• Can we include some but exclude others?
• Should we allow transforming attribute values?
• Is the default behavior to include every attribute?
• Should we allow indicating just the attribute name since that is probably a much more common case than needing to supply the full attributes record?

Some of these questions need more consideration. It's my believe right now that we will likely want to allow people to specify a list of attribute names to include, provide a full attribute set to use instead of the block attributes (which could include or exclude specific attributes or transform their values), and accept returning undefined to accept a default behavior.

API injection

It's also possible given the likelihood of only needing minor adjustments to the attribute sets in normal practice that instead of returning an indicator for which attributes are relevant to a context that we provide a little imperative API instead.

const attributeSets = ( context, contextData, attributes, { exclude, excludeAll, include ) => {
	switch ( context ) {
		case 'undo/redo':
			// don't revert to the temporary/local image upload data
			if ( contextData.revisionAttributes.src.startsWith( 'data:') ) {
				exclude( 'src' );
			}
			return;

		case 'style':
			excludeAll();
			include( 'alignment', 'size' );
			return;
	}
}

The imperative approach has some strong disadvantages by its nature but it may have a stronger match to the mental model of marking attributes and remove some complexity around making a sensible DSL for including and excluding at the same time (c.f. the same challenge with .gitignore files).

Performance considerations

There's a potential blow-up if we don't properly design how often we classify attributes. For the most part classification should only need to occur after human-initiated actions like undo/redo or copy/paste. It's also possible however that every change in the editor could trigger classification due to the saving and serialization process.

One pre-emotive way to mitigate the issue would be to only allow classifying attributes by their name and not by their value. There's a strong disadvantage to this as it would prevent solving one of the motivating cases for the feature: don't undo an image's source the local data URI generated when uploading the image (it would be wise for blocks not to use their attributes for data like that, but many do in practice, making classification a practical value-add).

Another way would be to simply watch the metrics and see how it works in practice. Thankfully most or all of the performance issues should be addressable on the framework side and I don't see code in the block implementations causing that much trouble. If we maintain our contract in the framework then we can iterate on the algorithm as needed.

Next steps

If you have thoughts on this design I'd love to hear your feedback. There are potentially many more contexts where attribute classification could be useful. We can imagine core- or plugin-defined contexts that blocks could opt into simply by being aware of their existence: grammar-check, readable, etc…

If you know of issues that are related to this please link them. It would be good to draw a wide net to see how people are currently trying to solve these problems and let that inform how we design a solution in the block API.

Thank you for your time reading through this and your thoughts!

[dmsnell]

cc: @mtias @youknowriad

[youknowriad]

I think the idea has value, bringing more semantics to the block API can be useful in a lot of situations. That said, I don't think the proposed approach is the right one, I think we should favor serializable APIs in favor of functions. The server might also need to know about this information and declaring this as a JS function forbids that entirely. So I'm actually more in favor of the opposite direction (assign a "role" to an attribute), in fact we already have such attribute today but it's marked unstable __unstableRole and we use it when transforming blocks using patterns, we only keep the attributes that are marked as "content".

I think what I'm missing before stabilizing and expanding that API is to actually use it more, expand the use-cases for it and once the dust settles we can make it stable as it would have proven its value.

[dmsnell]

Given the use-cases I had in mind I don't see all of these being particularly relevant on the server. At lest the contexts I was thinking about are specifically in-editor contexts.

If we go about using a declarative config it would limit one of the primary motivating examples that led to this: preventing someone from undoing the image block to the point where it sets the source as the local data URI from the upload.

If we go about assigning a role to an attribute we'll probably also miss that attributes fulfill multiple roles. We could declare a list of roles for each attribute, or list which attributes are in each context, but again, if we don't have access to the values of those attributes then I think we're talking about a different need.

[youknowriad]

If we go about using a declarative config it would limit one of the primary motivating examples that led to this: preventing someone from undoing the image block to the point where it sets the source as the local data URI from the upload.

For me, these are two different concepts:

• Adding semantics to attributes (the attribute itself has a special meaning: content, styling....)
• Adding semantics to attribute values (depending on the value itself, the attribute can have a different behavior)

[dmsnell]

in discussion here is primarily the second, attribute values, though the first is a subset of that where the value itself doesn't matter.

if the name is misleading I can try and think of something more attuned to the concept. I'm not happy with the name, but so far don't have anything better.

relevantAttributes would convey more of the progressive tense that we are making decisions right now based on the block attributes at the same time.

[luisherranz]

I like the idea of Attribute Sets and I like the API proposed. I think it's easy to understand and flexible.

However, as Riad, I'm also worried about adding additional block APIs that obscure block semantics to the server, especially if we add some sort of standard frontend hydration in the future (or even Universal Blocks).

I have two comments/ideas:

1. I usually like the idea of two-level APIs, one simple for 95% of the use cases and another hackable for the other 5%.

   The simple API could be a declarative API in the block.json that covers most cases and works in both the client and the server:

   {
     "attributeSets": {
       "undo/redo": "src",
       "style": ["alignment", "size"],
       "internal": "imageId",
       "frontend": ["src", "size"]
     }
   }

   Or added directly to the attributes:

   {
     "attributes": {
       "someAttribute": {
         "type": "string",
         "...": "...",
         "sets": ["undo/redo", "frontend"]
       }
     }
   }

   We could find an API to exclude an attribute from a default set. Imagine "undo/redo" is a default set:

   {
     "attributes": {
       "someAttribute": {
         "type": "string",
         "...": "...",
         "includedSets": ["frontend"],
         "excludedSets": ["undo/redo"]
       }
     }
   }

   Those names are a bit confusing though, it would need a better naming.

   Blocks could opt-in to use the setAttributes function proposed by Dennis to solve more complex scenarios, like the attribute value problem. But if they do, they would also need to replicate the code in the server (if that information is also needed there) with an additional server function registered in a similar way to render_callback.

   This has the disadvantage of duplicating code, but I think it would be acceptable because it would only affect a minimal number of cases.

2. For sets exclusive to the Editor, we could use Editor-only APIs instead.

   For example, we could use an API similar to Mobx untracked or React startTransition. Something like this:

   if (attribute.src.startsWith("data:")) {
     disableUndo(() => {
       setAttributes({ src: newSrc });
     });
   } else {
     setAttributes({ src: newSrc });
   }

   Or add options to setAttributes:

   setAttributes({ src: newSrc }, { undo: false });

   @dmsnell: what benefits do you see on using sets for the undo use case? Does it need to be exposed outside the scope of the setAttributes()? I'm not familiar with that part of the codebase yet.