This is an editor for AnnotationPage(s) when they are the value(s) of the annotations property of a Canvas or any other resource that can have an annotations property. It is NOT an editor for pages in the items property of a Canvas - for that see #97.

Almost all of the time there will be zero or one annotation pages. The following approach avoids an extra step in the UI hierarchy for most users but doesn't cause a problem in the rare cases where there are multiple pages.

It also understands the difference between embedded annotation pages and referenced annotation pages. (see https://iiif.io/api/presentation/3.0/#12-terminology for the spec definition of embedded and referenced)

An embedded AnnotationPage has an items property. In the Manifest, a referenced AnnotationPage does not.

A reference in the manifest to an external annotation page must have id and type and may have other properties in the manifest, especially label. The manifest editor DOES NOT KNOW what label or other properties the external annotation page has, and (certainly in MVP) will NEVER DEREFERENCE IT except in the one special "internalise" operation described below. All the ME cares about is the properties on that reference in the Manifest - that's what it needs to edit.

An embedded AnnotationPage has standard descriptive properties, and a list of non-media annotations (each edited by #99). This is somewhat similar to #97 except that its annotations do NOT have the painting motivation, and the representation of Annos in a list may be more textual.
A referenced AnnotationPage has standard descriptive properties, but has an External Resource (#72) instead of the items property, and no editable annotations.

Standard Descriptive Properties

(string values, or lists of strings, or maps, or lists of pairs of maps)	property	editable here
label	#67	no
metadata	#68	no
summary	#67	no
requiredStatement	#67	no
rights	#73	no
behavior	#73	no
language	#73	no

Items (if and only if embedded)

One or more of these:

property	editable here	has further editor
(member)	#99	no

If a thumbnail is used for each anno (a "mini" annotation representation), it's going to make more sense to be a crop to the target (if the usual case of the target being a Canvas or part of a Canvas).

... or, referenced AnnotationPage (if and only if referenced)

property	editable here	has further editor
(annotation page)	no	#72

(we won't support annotation pages that are both embedded and referenced; if it has an items property inline in the Manifest, we ignore the referenced version).

There is a potential nesting of resource editors / resource editor components here:

Non-Media Annotation Page (this Task), which if embedded has one or more of: Non-Media Annotation #99, which has, for each body: A "capture model" (or capture-model-like concept) (e.g., #117 and more)

We can assume that annotations in these pages still target the canvas whose annotations property the page almost always belong to. So they have the same target properties as #96. However, the annotations property of resources that are not canvases - e.g., manifests - might have targets that are other resources (e.g., the manifest itself) - see #99.

So how does this work?

See next comment...

Starting conditions

This applies whether the user has created a new manifest, or has loaded an existing one.

The resource currently being edited (manifest, canvas within that manifest, later range etc) has one of the following, in rapidly decreasing order of likelihood:

An empty annotations property (always the case for a new resource, and probably the most common for loaded resources)
An annotations property that contains a single referenced resource, with an inline label (probably the second most common scenario)
An annotations property that contains more than one referenced AnnotationPage resources, usually with inline label
An annotations property that contains one embedded AnnotationPage
An annotations property that contains more than one embedded AnnotationPage
An annotations property that contains a mixture of embedded and referenced AnnotationPage resources (all of which likely have inline labels and possibly other properties)

Only 1 and 2 are common. But as far as ME is concerned and certainly in MVP, there are no annotations to edit or display in 1, 2 or 3 - because the annotations are not part of the Manifest, they are separate external resources. We have no means, yet, of managing the persistence of these external resources. They are just external resources as edited by #72.

ME is not a viewer - if you just want to observe existing annotations, which are likely to be referenced, use Mirador.

BUT... we want to let ME users create annotations. And we want to let ME users work on existing annotations - adding to and modifying them. But we don't want to deal (right now) with the problem of secondary external resources that are not the Manifest, because that's an explosion of complexity. We want to focus right now on Manifest editing UI, including annotations, and not resource persistence and management.

Some conclusions from the above.

We support the creation and editing of annotations only when they are part of the manifest - when they are included in the items property of an embedded AnnotationPage resource.
We will encounter referenced AnnotationPages when people load existing Manifests (they need to survive round-tripping), and we also need to let users to create references to external AnnotationPage resources.
This means we need to distinguish between embedded and referenced. They share common properties like label, but one has an items property and one does not.
It would be very very useful to be able to convert a referenced AnnotationPage into an embedded one - to pull its content into the Manifest. This allows users to fork a manifest and edit existing third party annotations.

For this last point the sequence would be:

In the UI, a referenced AnnotationPage has a button "Convert to internal annotation page".
This creates a new annotation page in the annotations property of the resource.
The external AnnotationPage is loaded and its items property copied to the new AnnotationPage.
The new annotation page is given the id property of <old-id>#me-internal.
All other properties are merged: if they are different, they are added, but if they are the same, they don't result in duplicates. Extreme case - the old reference had a label property with an en value, the external page has more values in more languages, the result is the union of the two.
The old reference AnnotationPage stays in the annotations property array, in the same position, but is given the behavior value of hidden.
If an AnnotationPage has behavior = hidden AND has an id that matches another AnnotationPage with <id>#me-internal, then it is no longer displayed in the ME UI. (hidden alone is not enough - it may have that for other reasons!)

Later, when we have persistence mechanisms for annotation pages, we can add UI to un-hide and otherwise reverse the operation.

What does the UI for all this look like?

See

https://preview.uxpin.com/cabb8dec496a444a18e1ed442230485a02c17484#/pages/148641657/simulate/sitemap?mode=i and an experiment: https://tomcrane.github.io/scratch/me/anno-paging.html

In the latter the idea that there are multiple pages only becomes apparent when you have more than one anno page AND at least one of them is embedded. If you have multiple external pages they can be listed as in case 3, using #72.

In case 5-6, the pages become separate, some are embedded, you can add annos to their items, but some are external. The same external resource editor is used (#72) but now they have to live on their "pages".

Right, so this is a tricky one. It required a change to the IIIF parser to introduce a new parser specific property, since once an Annotation page is normalized there is no way of knowing if it's internal (and empty) or external.

Now when a Manifest, Collection or Annotation Page is loaded, it will have a property: iiif-parser:isExternal which can be true or false. This will be useful for Collection editing. When the serialisation happens, it will use these properties and ignore the items property.

The iiif-parser:partOf can be used to choose which properties are serialised, although this is not supported in the Manifest Editor directly.

New internal pages can be edited in the ME. There is a <PreviewVault /> context that will allow us to load and use External annotation pages for visual purposes, but this has not been implemented yet. There is also no conversion from External to internal. However, you can create new internal annotation pages and edit existing ones - like the Ocean Liners example.

digirati-co-uk / iiif-manifest-editor

Resource Editor: Non-media annotation page (MVP) #100