Format API

[ellatrix]

This issue is to discuss any formatting API build on top of #7890. The idea is to stick close the block registration API so it's a familiar concept.

See #10209 for more concrete information!

• Shortcut is seen a separate form of UI, which can work on it's own (e.g. a code button only has a shortcut).
• ToolbarControls fills controls in the toolbar portal.
• InserterItems fills controls in the inserter portal.
• All value manipulations are passed as props. See https://github.com/WordPress/gutenberg/blob/try/rich-text-record/packages/rich-text-value/src/readme.md.
• The render function can contain all of the format's components, such as LinkContainer, and can have its own state.

It would remove the current format settings object in RichText, remove shortcuts to be registered separately, and remove the inline tokens API.

Adding simple formatting button

registerFormat( 'bold', {
	selector: 'strong',
	edit( { isActive, toggleFormat } ) {
		return (
			<Fragment>
				<Shortcut
					type="primary"
					key="b"
					 onUse={ () => toggleFormat() }
				/>
				<ToolbarControls>
					<ToolbarButton
						icon="editor-bold",
						title={ __( 'Bold' ) }
						isActive ={ isActive }
						onClick={ () => toggleFormat() }
					/>
				</ToolbarControls>
			</Fragment>
		);
	},
} );

Adding a link button

registerFormat( 'link', {
	selector: 'a',
	attributes: {
		url: {
			source: 'attribute',
			attribute: 'href',
		},
	},
	edit( { isActive, removeFormat } ) {
		return (
			<Fragment>
				<Shortcut
					type="access"
					key="s"
					onUse={ () => removeFormat() }
				/>
				<Shortcut
					type="access"
					key="a"
					onUse={ /* Set state and pass to LinkContainer */ }
				/>
				<Shortcut
					type="primary"
					key="k"
					onUse={ /* Set state and pass to LinkContainer */ }
				/>
				<ToolbarControls>
					{ isActive && <ToolbarButton
						icon="editor-unlink",
						title={ __( 'Unlink' ) }
						onClick={ () => removeFormat() }
					/> }
					{ ! isActive && <ToolbarButton
						icon="admin-links",
						title={ __( 'Link' ) }
						onClick={ () => /* Set state and pass to LinkContainer */ }
					/> }
				</ToolbarControls>
				<LinkContainer { ...props } />
			</Fragment>
		);
	},
} );

Adding an image button

registerFormat( 'image', {
	selector: 'img',
	attributes: {
		url: {
			source: 'attribute',
			attribute: 'src',
		},
	},
	edit: class ImageFormatEdit extends Component {
		constructor() {
			super( ...arguments );
			this.state = {
				modal: false;
			};
		}

		openModal() {
			this.setState( { modal: true } )
		}

		closeModal() {
			this.setState( { modal: false } )
		}

		render() {
			const { insertObject } = this.props;

			return (
				<Fragment>
					<InserterItems>
						<InserterItem
							icon="inline-image",
							title={ __( 'Inline Image' ) }
							onClick={ openModal }
						/>
					</InserterItems>
					{ this.state.modal && <MediaUpload
						type="image"
						onSelect={ ( { id, url, alt, width } ) => {
							this.closeModal()
							insertObject( {
								src: url,
								alt,
								class: `wp-image-${ id }`,
								style: `width: ${ Math.min( width, 150 ) }px;`,
							} );
						} }
						onClose={ this.closeModal }
						render={ ( { open } ) => {
							open();
							return null;
						} }
					/> }
				</Fragment>
			);
		}
	},
} );

[ellatrix]

I'm in the process of creating a PR with this proposal on top of #7890.

[chrisvanpatten]

I like this a lot! It seems slightly strange to call it a format since inline images would also go through this API, but that's very much bikeshedding. At this point, it's just awesome to see this in the works :)

[youknowriad]

About the first example:

Can you expand a bit more about how it works? I don't see any onClick or onUseShortcut. I assume it's kind of bound automatically into Shortcut and ToolbarButton using context or something?

Can't this be more explicit: similar to the removeFormat, insertObject props? I'm thinking what if I don't want to use Shortcut or ToolbarButton. Also the block edit function is explicit because we always have to call setAttributes (There's only InnerBlocks that's implicit).

I understand that it might seem better/easier to add small formats with implicitness but I prefer if we start with explicitness and evolve towards some implicit defaults. We need to learn new components here Shortcut and ToolbarButton to add a format while with explicit API, we can just reuse what we already know in block registration: Button, KeyboardShortcuts...

Great proposal anyway.

[ellatrix]

@chrisvanpatten I guess I don't really see it the same way. The way I see it is that there are two things: text and formatting. Images are formatting on top of text. Maybe the naming could be better, but I don't really see anything wrong with "format". Ideally we have a name for it that applies to any HTML on top of text.

[ellatrix]

@youknowriad Agreed on staying explicit, I'll adjust the example.

[gziolo]

We have just landed Format API with #10068. It allows registering any format you need as described in this issue. We are still working on a way to give better control which control can be displayed for a given block and documentation. It should be all ready early next week.