Vault helper for Choice

[tomcrane]

Broken out of #156, extending #106

Current proposal is https://iiif-canvas-panel.netlify.app/docs/examples/handling-choice#additional-choice-helper-api

but it doesn't have to look like that.

[stephenwf]

This will require a pre-requisite vault helper for painting annotations (as they are tied together). That API currently has the following surface:

getPaintingAnnotations(vault, canvas): AnnotationNormalized[];
getPaintables(vault, paintingAnnotations, enabledChoices): { types, items, choice }

The concept is that you can get a flat list of painting annotations from getPaintingAnnotations() and then pass it to getPaintables() to take into account the choices made to get a list of things to actually display.

If you call getPaintables() without any enabled choices, you will see a choice is returned. It can be either be a simple choice or a complex one. Complex choices are not supported. You can then use that to create a UI and if you need a new set of "things to render" you call getPaintables() again with the updated choices.

With these lower level tools, helpers could further add:

function containsChoice(vault, canvas) {
  const { choice } = getPaintables(vault, getPaintingAnnotations(vault, canvas));
  return choice !== null;
}

function extractChoices(vault, canvas) {
  const { choice } = getPaintables(vault, getPaintingAnnotations(vault, canvas));
  return choice;
}

Although that might feel a bit redundant, and we could simplify to just extract choices and update the example:

const choiceSets = vault.extractChoiceSets(canvas);
if (choiceSets) {
  // Render UI for choices.
  // When I'm ready, I can insert a web component onto the page:
  // <canvas-panel canvas-id=" ... " choice-id=" ... " />
} else {
  // Render normal component
  // <canvas-panel canvas-id=" ... " ... />
}

[stephenwf]

Docs will be updated, implementation here: IIIF-Commons/vault-helpers#11

const helper = createPaintingAnnotationsHelper(vault);

helper.getAllPaintingAnnotations(canvas); // returns flattened list of annotations
helper.getPaintables(canvas); // returns list of types, choices and items
helper.extractChoices(canvas); // returns just choices

[stephenwf]

This has been expanded in #246 so that you can listen for choice events on multiple canvases in a sequence and make choices on both images. The current implementation is documented though.