Question: How can we surface expected attributes of a block?

[aduth]

Problems:

At a glance of a block's implementation, there is no easy way to know all attributes that the block uses and manipulates.

The block's attributes property allows an implementer to define which attributes are to be parsed from the saved markup of a post. This is not the only state that's available for a block, however, and the default behavior is such that in serializing a block, any attributes which do not have a corresponding key present in the attributes property are assumed to be encoded into the comment demarcations.

There are other issues related to this one, specifically ideas around defining an attribute as required, default values, or providing options for the block implementer to coerce an attribute value to a specific type. For the purpose of this issue, I'd like to keep this targeted at the discoverability worry.

See also:

• Documentation (out of date, also specifies an additional encodeAttributes function for granular control which has not yet been implemented)
• Implementation

Ideas:

• Perhaps the attributes property could behave more like React's PropTypes, defining all attributes which the block is expected to handle.
• Rather than implicitly assuming values whose keys are not in the attributes property are to be encoded in the comment, we could be more explicit.
  • A new metadata( 'foo' ) matcher?
  • A separate property encodedAttributes: string[] ?
  • Require that encodeAttributes in the above documentation be implemented, so it's more obvious which values are encoded into the comment?

[youknowriad]

I like the ideas here. I'd see something like this would be great:

attributes: {
  content: children( 'p' ).string()
  style: metadata( 'style' ).int()
}

[aduth]

Similarly expressive, but maybe not quite as obvious, is Lodash's flow:

attributes: {
  style: flow( metadata( 'style' ), toInteger )
}

• _.toInteger
• _.toNumber
• _.toString

[aduth]

Another alternative is a more expanded object of attribute details:

attributes: {
  style: {
    type: 'number',
    source: metadata( 'style' )
  }
}