Skip to content

Annotations enhancer

Install @prose-reader/enhancer-annotations, create annotations with createAnnotation and give each one an id of your own before you store it, show them as highlights, find the annotations of each page with annotationsByItemPage$, find the pages that can hold one with candidates$, and avoid the root CFI you get on a blank page.

Terminal window
npm install @prose-reader/enhancer-annotations @prose-reader/core @prose-reader/shared rxjs

All three are peer dependencies: the enhancer runs against the reader your app creates, so it shares that reader's copies rather than bringing its own.

reader.annotations.createAnnotation() gives a new annotation its cfi and, for a selection, its highlightedText. Pass it one of two things:

  • a selection and the index of its spine item, as reader.selection.getSelection() gives them, for a highlight;
  • the absolute index of a page, for a bookmark.
const currentSelection = reader.selection.getSelection()
if (currentSelection) {
const highlight = reader.annotations.createAnnotation({
itemIndex: currentSelection.itemIndex,
selection: currentSelection.selection,
})
if (highlight) {
saveAnnotation({
...highlight,
id: crypto.randomUUID(),
highlightColor: "yellow",
notes: "",
})
}
}
const bookmark = reader.annotations.createAnnotation({ absolutePageIndex })

It returns { cfi, highlightedText } for a selection and { cfi } for a page: strings and nothing else. Add an id of your own and the other fields of your annotation to it, such as highlightColor and notes, and store the result as it is: in IndexedDB, for example. The type of an annotation without its id is NewAnnotation.

  • For a selection, the CFI is the range of the selection, and highlightedText is the text of that range: see The text of a highlight.
  • For a page, the CFI points to the first visible node of the page, or to the root of its spine item when the page has none: see Blank pages and annotations. The result has no highlightedText.
  • It returns undefined when the reader has no such spine item or page, or when the selection holds no range.

The reader only needs each id to be unique among the annotations you give it, so your ids can take the form your store uses.

Do not store a page index with an annotation: its page changes with the layout and the device. See Danger of persisting weak references.

highlightedText is the text of the range, as Range.toString() gives it: the text nodes of the document, joined.

  • It keeps the whitespace that the document holds, such as the line breaks and tabs of its source.
  • It adds nothing between two paragraphs.
  • It does not depend on CSS, the layout or the browser, so it is the same on every device.

It is not the text of the selection as the browser renders it, which Selection.toString() gives and which differs between browsers.

Store it to list, export or search highlights without the book. To find out whether the passage at a stored CFI still holds that text, read the passage the same way: range.toString() of the range that the CFI resolves to, such as the range that reader.locateResource() gives. To show it outside of HTML, collapse its whitespace, as HTML does when it renders text.

Give the enhancer your annotations as an observable. Each time they change, emit a new array, and put each changed annotation in it as a new object:

import { createReader } from "@prose-reader/core"
import {
type Annotation,
annotationsEnhancer,
} from "@prose-reader/enhancer-annotations"
import { BehaviorSubject } from "rxjs"
const annotations$ = new BehaviorSubject<Annotation[]>([])
const reader = annotationsEnhancer(createReader)({
manifest,
annotations: { annotations$ },
})
// The user changed the color of an annotation.
annotations$.next(
annotations$.value.map((annotation) =>
annotation.id === changedId
? { ...annotation, highlightColor: "red" }
: annotation,
),
)
// The user removed an annotation.
annotations$.next(
annotations$.value.filter((annotation) => annotation.id !== removedId),
)

The enhancer compares each entry with the previous one by reference. It ignores an array that holds the same objects as the previous one, so it does not draw again an annotation that you change in place.

The enhancer draws a highlight for each annotation whose CFI is a range, while the document of its spine item is loaded. The highlight covers each line of the text that the range covers, from the line's first selected character to its last. It covers the box of each img, svg, math, video, audio, canvas, iframe, object or embed element that the range covers whole, even one that holds text. It does not cover the blank space beside a line. It is drawn:

  • in its highlightColor, or yellow when it has none, with a note icon when it has notes;
  • with a red dashed border when it is the first annotation in the array whose selected is true.

The enhancer matches each highlight to its annotation by id, so give each annotation an id of its own. When an annotation changes, the enhancer draws its highlight again. When an annotation leaves the array, the enhancer removes its highlight at once.

reader.annotations.highlightTap$ emits { event, annotation } for each tap on a highlight. annotation is the annotation of the tapped highlight. Where highlights overlap, a tap reaches the highlight drawn on top, and the stream reports that one. It completes when the reader is destroyed.

reader.annotations.annotationsByItemPage$ emits the annotations whose page is known, by spine item index, then by page index in the item, in the order of the array. A range is on the page where it starts. Read it for anything shown per page, such as a mark on each annotated page:

reader.annotations.annotationsByItemPage$.subscribe((annotationsByItemPage) => {
const annotationsOfPage =
annotationsByItemPage.get(itemIndex)?.get(pageIndex) ?? []
})

It locates the annotations with reader.locateResource() in its shallow mode, so it loads no chapter, and an annotation has a page as the Page indexes rules give it. Unless its CFI names only its chapter, an annotation in a reflowable chapter that is not loaded has none, and neither has one added while a layout of its chapter is pending, until that layout's pages are published.

It emits once the annotations are located, then each time an annotation of a page moves to another page, comes, goes or changes. It completes when the reader is destroyed.

The enhancer does not tell bookmarks from highlights: what each kind of annotation means is up to your app. React Reader, for example, takes the annotations of a page whose CFI is not a range as the bookmarks of that page.

Sometimes you may end up with blank pages. Some of the scenarios that lead to a blank page are:

  • Document configured to show a blank page before or after a specific page (by design)
  • Document spreading on more than one page but the DOM does not cover all pages

This situation is unfortunate but sometimes by design as well. Trying to annotate a page on which it's impossible to create a CFI from (other than a root CFI) will make it impossible to derive the correct page for it later.

We provide a .candidates$ observable which you can observe to know which page is a good candidate for annotation or not. A good candidate is defined as such:

  • Page from a pre-paginated document (there can be only one page anyway)
  • Page with a visible DOM node (meaning you can target it with a CFI)

pre-paginated documents are by design always on one page so we don't check whether they have a visible node.

candidates$ emits one boolean per page the reader has published, by absolute page index, each time the reader publishes its pages. Until the reader has published its first pages, it emits an empty array. It gives its latest value to a new subscriber at once, so it can be read with withLatestFrom.

If you get a root CFI when trying to annotate a page, it is likely because we were unable to find a node to create a CFI from. This can happen when trying to annotate a blank page. Try to filter out such pages.