Annotation classes

[tim-evans]

This branch is a culmination of a deep rewrite of AtJSON, making Annotations classes instead of object literals.

Previously, annotations were ephemeral, and were loosely defined in sources and renderers. With changes made here, annotations will have an explicit class where they can be documented, altered, and define extension points.

Bold annotations are one of the most basic for text editing. Creating a bold annotation looked like:

doc.addAnnotation({
   type: 'bold',
   start: 0,
   end: 5
});

Now, adding a bold annotation is done using a class + a vendor prefixed version of it. To add support for Bold annotations in our rich text editor, Offset, the following class would be made:

import { InlineAnnotation } from '@atjson/document';

class Bold extends InlineAnnotation {
  static vendorPrefix = 'offset';
  static type = 'bold';
}

And we would add it to our document by adding the following JSON:

doc.addAnnotation({
  type: '-offset-bold',
  start: 0,
  end: 5,
  attributes: {}
});

Note that the vendor prefix is prepended (like a CSS vendor prefix) to the beginning of the type of the annotation. This is to help to be clear with distinguishing between various types of annotations that exist on multiple sources, and stop them from clobbering one another. In addition, attributes is now a required field on the Annotation JSON.

[blaine]

Sooooorry for the massive delay on reviewing this - tbh, I thought I'd already approved, but clearly not. 🙃 😢

This is great, and looking forward to moving the change behaviour to Annotations so that we can move some of the conditional logic that's creeping into Document & offset out to Annotations.

[blaine]

Does it make sense to also abstract adding/removing/changing annotations as Changes? High-level, that feels the right approach, but it might be impractical at the moment.

[foobarrio]

The JS objects in the opening line is tripping me up. How do you feel about something more along the lines of:

"This branch is a culmination of a deep rewrite of AtJSON to represent Annotation objects using class instances instead of object literals."

[foobarrio]

A few places still try to import Display; want I should make a PR against this to fix?

[tim-evans]

@foobarrio thanks, but it's ok for now! there's still a bunch more to be done with this rewrite. If you'd like to help, I am happy to have you bring you up to speed and help you contribute ❤️

[tim-evans]

Oooh! I think you could help create our base annotation package! That would be very helpful :)

[foobarrio]

I tried to tsc build and it balks on being unable to import Display is all.

Happy to help w/ whatever--point me in the right direction!