Annotation API #7718

atimmer · 2018-07-05T09:33:05Z

Description

This PR includes an API to annotation text inside blocks. This PR on its own is mostly useful to plugin authors. This would make it possible for a feature plugin to build #3026. It also allows plugins like Jetpack or Yoast SEO to highlight certain parts of the text to make their feedback more contextual and actionable.

The best way to see this in action is combine it with this Yoast SEO PR: Yoast/wordpress-seo#10265

XPath has been chosen because it is a format that is compatible with the W3C annotation standard. This will give it future compatibility with front-end annotations. Partial XPaths can really easily be combined into a fully qualified XPath that works globally on a certain page. XPath is also the only format in the W3C annotation standard that can refer to text node. This is in contrast to the CSS selector which can't refer to text nodes.

All annotations in the editor get an annotation-text and an annotation-text-[source] class to they can be styled by the source of the annotation.

Browser compatibility

document.evaluate is not supported in all browsers, but for this version of the PR I don't use document.evaluate. I parse the XPath myself to result in a position within the data structure for rich-text.

Doesn't include, but should be added in a later iteration

A custom block should be able to track which RichText an annotation is for. Currently this implementation only works for block with a single RichText.
More data can be added to an annotation such as comment, author, etc.

How has this been tested?

Using the annotations tester plugin: https://github.com/atimmer/gutenberg-annotations-tester. The plugin also shows which annotations are currently in the state, this makes it a bit easier to debug what is happening.
Running this in combination with Implement annotations for Gutenberg Yoast/wordpress-seo#10265.

Screenshots

Checklist:

My code is tested.
My code follows the WordPress code style.
My code follows the accessibility standards.
My code has proper inline documentation.

gziolo · 2018-08-06T14:35:32Z

It looks like we should find a good solution for making RichText extensible so this could be developed as a plugin initially to speed up things. Related issues: #3688 and #4658. /cc @iseulde

Screencast looks really nice 👍

gziolo · 2018-08-22T14:14:45Z

@iseulde - is there any way we could allow register custom TinyMCE plugins? It looks like this is the blocker for having annotations developed as a plugin. Another question is if we want to have it included in the core at some point.

ellatrix · 2018-08-22T15:29:14Z

With the RichText state PR (#7890) and future helpers build on that, it should no longer be necessary to do this as a TinyMCE plugin, and then it can also easily be made as a plugin for Gutenberg.

atimmer · 2018-09-12T11:27:18Z

An alternative implementation of this PR can be found in the try/annotations-with-rich-text-refactor branch. That branch is based on #7890 and I've updated Yoast/wordpress-seo#10265 to work with that branch.

Whenever #7890 is merged I will make try/annotations work with the new rich text structure.

packages/editor/src/components/rich-text/index.js

packages/rich-text/src/xpath.js

packages/rich-text/src/test/xpath.js

ellatrix · 2018-10-04T12:44:37Z

Could you write some docs as part of this PR that explain how to use the annotations API?

It is not possible to have overlapping annotations.

Could you elaborate? Why not?

atimmer · 2018-10-04T13:16:22Z

Could you elaborate? Why not?

Because of the new RichText structure this is no longer the case. The TinyMCE plugin that I used for matching XPaths couldn't do it (yet).

Could you write some docs as part of this PR that explain how to use the annotations API?

Will do.

gziolo · 2018-10-10T09:09:45Z

I'm adding this PR to 4.1 milestone to ensure it is included early in the process. As discussed during JS weekly chat yesterday, it depends on #10068 which @iseulde is going to work on as soon as 4.0-RC is out. Those two task depend on each other, so let's make sure we shape formatting API for RichText in a way which makes this PR work :)

gziolo · 2018-10-10T09:11:42Z

There is work in progress PR for formatting API #10209, @atimmer we would love to hear your feedback early on 🙇

gziolo · 2018-10-15T11:23:41Z

I'm moving it to 4.2 as we decided that 4.1 should be UI freeze focused. 4.2 is planned to be focused on API freeze and this PR fits perfectly to that description :)

packages/annotations/README.md

lib/client-assets.php

test/e2e/test-plugins/plugins-api/sidebar.js

docs/extensibility/annotations.md

youknowriad · 2018-11-09T14:53:43Z

packages/annotations/src/store/test/reducer.js

+	} );
+
+	it( 'allows an annotation to be removed', () => {
+		const state = annotations( {


A good enhancement to these tests would be to apply deepFreeze on the original states. (also need a dev dependency)

youknowriad

LGTM overall 👍 Thanks for your patience @atimmer

Anyone for a quick second PR as this is a big addition.

packages/annotations/src/store/actions.js

aduth · 2018-11-09T15:52:28Z

packages/annotations/src/store/actions.js

+		selector,
+	};
+
+	if ( selector === 'range' ) {


Isn't the selector argument redundant if you also have to provide a range value for it to be used?

In other words, can't we infer selector === 'range' by the presence of a truthy range ?

packages/annotations/src/store/actions.js

aduth · 2018-11-09T15:57:16Z

packages/annotations/src/store/reducer.js

+	switch ( action.type ) {
+		case 'ANNOTATION_ADD':
+			const blockClientId = action.blockClientId;
+			const newAnnotation = {


If the action was shaped such that the annotation itself was an object value, we wouldn't have to reconstruct what essentially amounts to const newAnnotation = omit( action, 'type' );

e.g. something like:

action = { type: 'ANNOTATION_ADD', annotation: { id, /* .. */ } };

aduth · 2018-11-09T15:59:29Z

packages/annotations/src/store/reducer.js

+					...state.all,
+					newAnnotation,
+				],
+				byBlockClientId: {


This is redundant data?

getAnnotationsByBlockClientId = ( state, blockClientId ) => filter( state.annotations.all, { blockClientId } );

https://github.com/reduxjs/redux/blob/master/docs/faq/OrganizingState.md#how-do-i-organize-nested-or-duplicate-data-in-my-state

aduth · 2018-11-09T16:01:56Z

packages/editor/src/components/rich-text/index.js

@@ -839,25 +839,25 @@ export class RichText extends Component {
 		} ).body.innerHTML;
 	}

-	valueToFormat( { formats, text } ) {
+	valueToFormat( value ) {


Why?

Where's the unit test which would have failed under the previous implementation?

aduth · 2018-11-09T16:09:39Z

packages/annotations/src/format/index.js

+
+const { name, ...settings } = annotation;
+
+registerFormatType( name, settings );


Not entirely related to this pull request, but in mind of #11611, there's an inconsistency we're considering in how / when formats become registered, particularly for "core" formats not specifically registered within @wordpress/format-library.

aduth · 2018-11-09T16:27:24Z

packages/annotations/src/format/annotation.js

+ */
+
+export function applyAnnotations( record, annotations = [] ) {
+	annotations.forEach( ( annotation ) => {


This is a perfect use-case for Array#reduce:

return annotations.reduce( ( recordResult, annotation ) => { // ... return applyFormat( recordResult, { type: 'core/annotation', attributes: { className } }, start, end ); }, record );

I'd do the refactoring but there aren't any unit tests to verify the behavior so I don't feel confident.

packages/annotations/package.json

packages/annotations/src/store/reducer.js

aduth

Blocking items resolved. Consider unresolved conversations for subsequent pull requests.

omarreiss · 2018-11-09T19:38:32Z

<3

atimmer force-pushed the try/annotations branch from 4b31c23 to 3b5f11e Compare July 24, 2018 15:35

atimmer force-pushed the try/annotations branch 2 times, most recently from d670f2b to e100b06 Compare August 3, 2018 11:28

atimmer requested review from aduth, gziolo and youknowriad August 3, 2018 13:05

gziolo requested a review from ellatrix August 6, 2018 14:35

gziolo added [Feature] Extensibility The ability to extend blocks or the editing experience [Type] Technical Prototype Offers a technical exploration into an idea as an example of what's possible labels Aug 6, 2018

ellatrix mentioned this pull request Aug 28, 2018

RichText state structure for value manipulation #7890

Merged

4 tasks

aduth mentioned this pull request Sep 13, 2018

Try block annotation, starting with full block annotation #3628

Closed

5 tasks

atimmer force-pushed the try/annotations branch from 318435e to 7aa0fa3 Compare October 2, 2018 08:31

atimmer changed the title ~~Try an annotation API~~ Annotation API Oct 2, 2018

ellatrix reviewed Oct 3, 2018

View reviewed changes

packages/editor/src/components/rich-text/index.js Outdated Show resolved Hide resolved

ellatrix reviewed Oct 3, 2018

View reviewed changes

packages/rich-text/src/xpath.js Outdated Show resolved Hide resolved

ellatrix reviewed Oct 3, 2018

View reviewed changes

packages/rich-text/src/test/xpath.js Outdated Show resolved Hide resolved

ellatrix reviewed Oct 3, 2018

View reviewed changes

packages/rich-text/src/test/xpath.js Outdated Show resolved Hide resolved

gziolo added this to the 4.1 milestone Oct 10, 2018

gziolo added the [Feature] Rich Text Related to the Rich Text component that allows developers to render a contenteditable label Oct 10, 2018

gziolo modified the milestones: 4.1, 4.2 Oct 15, 2018

atimmer force-pushed the try/annotations branch from 594fc27 to 64acd0c Compare November 9, 2018 10:35

Add _experimental flag to e2e tests

399f9bc

youknowriad reviewed Nov 9, 2018

View reviewed changes

packages/annotations/README.md Outdated Show resolved Hide resolved

lib/client-assets.php Outdated Show resolved Hide resolved

test/e2e/test-plugins/plugins-api/sidebar.js Show resolved Hide resolved

atimmer added 2 commits November 9, 2018 12:14

Remove wp-annotations as a dependency of wp-editor

f5eabaa

Fix spacing

fc29ca4

atimmer mentioned this pull request Nov 9, 2018

Implement annotations for Gutenberg Yoast/wordpress-seo#10265

Merged

2 tasks

youknowriad reviewed Nov 9, 2018

View reviewed changes

docs/extensibility/annotations.md Show resolved Hide resolved

youknowriad reviewed Nov 9, 2018

View reviewed changes

youknowriad approved these changes Nov 9, 2018

View reviewed changes

aduth reviewed Nov 9, 2018

View reviewed changes

packages/annotations/package.json Show resolved Hide resolved

Annotations: Add missing uuid dependency

6f84e3a

aduth reviewed Nov 9, 2018

View reviewed changes

packages/annotations/src/store/reducer.js Show resolved Hide resolved

aduth added 5 commits November 9, 2018 11:36

Annotations: Fix DocBlock inconsistency

4774943

Annotations: Add missing Lodash dependency

807571b

Annotations: Fix up a few more DocBlocks

c7e0e52

Annotations: Add a basic description for package

f7d0f14

Docs: Include Annotations document in root manifest

ebf62c9

aduth approved these changes Nov 9, 2018

View reviewed changes

Update dependencies

03c41cb

youknowriad merged commit 52a3375 into master Nov 9, 2018

youknowriad deleted the try/annotations branch November 9, 2018 17:44

aduth mentioned this pull request Nov 12, 2018

Format library: Allow explicit registration when using npm packages #11611

Closed

omarreiss added the [Feature] Annotations Adding annotation functionality label Mar 26, 2019

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Annotation API #7718

Annotation API #7718

atimmer commented Jul 5, 2018 •

edited

Loading

gziolo commented Aug 6, 2018 •

edited

Loading

gziolo commented Aug 22, 2018

ellatrix commented Aug 22, 2018

atimmer commented Sep 12, 2018

ellatrix commented Oct 4, 2018

atimmer commented Oct 4, 2018

gziolo commented Oct 10, 2018

gziolo commented Oct 10, 2018

gziolo commented Oct 15, 2018

youknowriad Nov 9, 2018

youknowriad left a comment

aduth Nov 9, 2018

aduth Nov 9, 2018

aduth Nov 9, 2018

aduth Nov 9, 2018

aduth Nov 9, 2018

aduth Nov 9, 2018

aduth Nov 9, 2018

aduth left a comment

omarreiss commented Nov 9, 2018


		const { name, ...settings } = annotation;

		registerFormatType( name, settings );

Annotation API #7718

Annotation API #7718

Conversation

atimmer commented Jul 5, 2018 • edited Loading

Description

Browser compatibility

Doesn't include, but should be added in a later iteration

How has this been tested?

Screenshots

Related

Checklist:

gziolo commented Aug 6, 2018 • edited Loading

gziolo commented Aug 22, 2018

ellatrix commented Aug 22, 2018

atimmer commented Sep 12, 2018

ellatrix commented Oct 4, 2018

atimmer commented Oct 4, 2018

gziolo commented Oct 10, 2018

gziolo commented Oct 10, 2018

gziolo commented Oct 15, 2018

Choose a reason for hiding this comment

youknowriad left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

aduth left a comment

Choose a reason for hiding this comment

omarreiss commented Nov 9, 2018

atimmer commented Jul 5, 2018 •

edited

Loading

gziolo commented Aug 6, 2018 •

edited

Loading