@nulib/clover 0.0.0-stage → 4.0.0-beta.1

package/dist/web-components/index.d.mts

@@ -0,0 +1,604 @@
+/*
+ * @nulib/clover/web-components: Clover's elements, for pages without React. Written
+ * from the elements' specs by build/custom-elements.mjs.
+ */
+
+export interface CloverI18nOptions {
+  /** The language to use: else the page's `<html lang>`, then the browser's. */
+  lng?: string;
+  /** Languages to try, in order, when a string is missing. English is always last. */
+  fallbackLng?: string | readonly string[] | false;
+  /** Strings to add or replace: `resources[language].clover[key]`. */
+  resources?: Record<string, Record<string, Record<string, string>>>;
+}
+
+/** Set the language of Clover's own words, or add strings, for every element on the page. */
+export declare function initCloverI18n(options?: CloverI18nOptions): Promise<unknown>;
+
+/** Define Clover's elements: done for you on import; for a build of your own with its own assets. */
+export declare function defineCloverElements(assets: unknown, tags?: readonly string[]): void;
+
+export interface CloverRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+export interface CloverPoint {
+  x: number;
+  y: number;
+}
+
+/** Where the camera looks, its zoom and its turn (degrees, clockwise). */
+export interface CloverCamera {
+  x: number;
+  y: number;
+  zoom: number;
+  rotation: number;
+}
+
+/** A IIIF resource as Clover holds it: Presentation 4, upgraded as it loaded. */
+export type CloverResource = Record<string, unknown> & { id: string; type: string };
+
+export type CloverStatus = "idle" | "loading" | "ready" | "error";
+
+/** What every part draws from (`CloverState` in React). */
+export interface CloverState {
+  status: CloverStatus;
+  error: Error | null;
+  /** The Manifest shown. */
+  manifest: CloverResource | null;
+  /** The Collection it was reached through, if any. */
+  collection: CloverResource | null;
+  /** The Canvas the reader is on: the first of the view that shows it. */
+  canvasId: string | null;
+  /** The annotation picked, from a list or its hotspot. */
+  annotationId: string | null;
+  /** Annotation sets switched off. */
+  hiddenSets: string[];
+  addedSets: CloverAnnotationSet[];
+  search: {
+    query: string;
+    status: CloverStatus;
+    hits: Array<{ id: string; canvasId: string; match: string; before?: string; after?: string }>;
+  };
+}
+
+/** The Canvases Clover can show, in order, grouped into views (each a list of indexes). */
+export interface CloverSequence {
+  canvases: CloverResource[];
+  views: number[][];
+  direction: "left-to-right" | "right-to-left" | "top-to-bottom" | "bottom-to-top";
+}
+
+/** Moving between views (`useNavigation()`): a spread moves two pages at a time. */
+export interface CloverNavigation {
+  /** Zero-based index of the current view. */
+  position: number;
+  total: number;
+  hasPrevious: boolean;
+  hasNext: boolean;
+  previous(): void;
+  next(): void;
+  first(): void;
+  last(): void;
+  goTo(canvasId: string): void;
+}
+
+export interface CloverAnnotationSet {
+  id: string;
+  label?: CloverLanguageMap;
+  source: "manifest" | "added" | "search";
+  entries: Array<{
+    id: string;
+    setId: string;
+    canvasId: string;
+    motivation: string[];
+    /** The annotation as published. */
+    annotation: Record<string, unknown>;
+  }>;
+}
+
+/** A IIIF language map, or a plain string. */
+export type CloverLanguageMap =
+  | string
+  | Record<string, string[] | string | undefined>
+  | null
+  | undefined;
+
+/** A value that changes too often for the state: the viewport, the media element… */
+export interface CloverChannel<Value> {
+  get(): Value;
+  emit(value: Value): void;
+  subscribe(listener: (value: Value) => void): () => void;
+}
+
+/**
+ * `root.clover`: a root's Clover, for a part of your own. What React's hooks read, each a
+ * method of the same name (`useNavigation()` is `navigation()`), the state and a way to
+ * hear of it, the root's language, and the Clover `useClover()` hands a React part: its
+ * store, its actions and its channels.
+ */
+export interface CloverRootApi {
+  /** The state, now. */
+  readonly state: CloverState;
+  /** Hear of every change of the state; returns the way to stop. */
+  subscribe(listener: (state: CloverState) => void): () => void;
+  /** The language the root reads IIIF text in, where it is given one. */
+  readonly language: string | undefined;
+  status(): { status: CloverStatus; error: Error | null };
+  manifest(): CloverResource | null;
+  sequence(): CloverSequence;
+  visibleCanvases(): CloverResource[];
+  activeCanvas(): CloverResource | null;
+  navigation(): CloverNavigation;
+  annotationSets(): CloverAnnotationSet[];
+  /** A language map as text in the root's language, with the tag it is in. */
+  localize(value: CloverLanguageMap): { text: string; lang?: string };
+  /** One of Clover's own strings, in its language now: `t("commonClose")`. */
+  t(key: string, values?: Record<string, unknown>): string;
+  /** That string's language where it is not the page's, for the `lang` of what shows it. */
+  langOf(key: string): string | undefined;
+  /**
+   * A popup of yours joined to Clover's, which open one at a time (`useOneOpen`): call it as
+   * yours opens, with the way to close it; call what it returns as yours closes.
+   */
+  oneOpen(close: () => void): () => void;
+  readonly store: {
+    get(): CloverState;
+    set(patch: Partial<CloverState>): void;
+    subscribe(listener: () => void): () => void;
+  };
+  goTo(
+    canvasId: string,
+    target?: { region?: { x: number; y: number; w: number; h: number }; time?: number },
+  ): void;
+  goToManifest(id: string, canvasId?: string): Promise<void>;
+  openCollection(id: string): Promise<void>;
+  next(options?: { autoplay?: boolean; wrap?: boolean }): void;
+  previous(): void;
+  first(): void;
+  last(): void;
+  selectAnnotation(id: string | null): void;
+  search(query: string): Promise<void>;
+  setSetVisible(setId: string, visible: boolean): void;
+  loadAnnotations(input: unknown): Promise<void>;
+  /** Where the reader is, as a content state. */
+  getContentState(): { json: Record<string, unknown>; encoded: string } | null;
+  readonly viewport: CloverChannel<{
+    canvasId: string;
+    region: { x: number; y: number; w: number; h: number };
+  } | null>;
+  readonly media: CloverChannel<HTMLVideoElement | null>;
+  readonly captions: CloverChannel<string | null>;
+  readonly highlight: CloverChannel<string | null>;
+  readonly chapter: CloverChannel<string | null>;
+}
+
+/**
+ * A renderer of yours, without React: the views it claims, and `render`, which draws one
+ * into a box filling the Body and returns what undoes it.
+ */
+export interface CloverRenderer {
+  /** Views showing one of these Canvases… */
+  canvasId?: string[];
+  /** …or painting a body of one of these formats (`model/gltf-binary`)… */
+  format?: string[];
+  /** …or any view this says yes to. */
+  match?: (view: { canvases: CloverResource[]; bodies: Array<Record<string, unknown>> }) => boolean;
+  render(
+    container: HTMLElement,
+    view: {
+      canvases: CloverResource[];
+      bodies: Array<Record<string, unknown>>;
+      clover: CloverRootApi | null;
+    },
+  ): void | (() => void);
+}
+
+/** What the function for one of the Body's controls is told. */
+export interface CloverControl {
+  name: keyof CloverControlButtons;
+  /** Its name, as its `aria-label` says it. */
+  label: string;
+  /** Clover's icon for it, to put in your button, kept current. */
+  icon: HTMLElement;
+}
+
+/** The Body's controls, each replaced by a button you make. */
+export interface CloverControlButtons {
+  zoomIn?: (control: CloverControl) => Element;
+  zoomOut?: (control: CloverControl) => Element;
+  fullPage?: (control: CloverControl) => Element;
+  rotateRight?: (control: CloverControl) => Element;
+  rotateLeft?: (control: CloverControl) => Element;
+  reset?: (control: CloverControl) => Element;
+  choice?: (control: CloverControl) => Element;
+}
+
+/** The Canvas's handle (onReady in React): the camera and its coordinates. <clover-canvas> and <clover-body> keep it as handle. */
+export interface CloverCanvasHandle {
+  readonly backendKind: "webgl2" | "canvas2d" | "none";
+  /** Whether the view is at home, fitted whole: false once the reader zooms, pans or turns it. */
+  readonly atHome: boolean;
+  /** Fit the whole view again, as Reset does. */
+  home(immediate?: boolean): void;
+  /** Zoom by a factor (2 in, 0.5 out), about a point on the screen if given. */
+  zoomBy(factor: number, at?: CloverPoint, animate?: boolean): void;
+  /** Move the view, in screen pixels. */
+  panBy(dx: number, dy: number, animate?: boolean): void;
+  /** Turn the view by an angle, clockwise. */
+  rotateBy(degrees: number): void;
+  /** Turn the view to an angle, clockwise. */
+  setRotation(degrees: number, immediate?: boolean): void;
+  /** The view's angle, in degrees clockwise. */
+  getRotation(): number;
+  /** Frame a rectangle, in world units. */
+  fitBounds(bounds: CloverRect, immediate?: boolean): void;
+  /** Frame a rectangle in one image's own coordinates, by its place among those shown. */
+  fitItemRect(index: number, rect: CloverRect, immediate?: boolean): void;
+  /** Frame a region of a Canvas shown, in its own coordinates (an xywh): false before it is laid out. */
+  fitCanvasRect(canvasId: string, rect: CloverRect, immediate?: boolean): boolean;
+  /** Frame an annotation's hotspot and focus it, as picking it does: false while it has none. */
+  zoomToAnnotation(id: string): boolean;
+  /** The visible rectangle, in world units. */
+  getBounds(): CloverRect;
+  /** What home fits: the whole view, in world units. */
+  getHomeBounds(): CloverRect | null;
+  /** The camera: where it looks, its zoom and its turn. */
+  getCamera(): CloverCamera;
+  /** The visible part of the Canvas filling most of the view, in its own coordinates: what a share link records. */
+  getCanvasRegion(): { canvasId: string; rect: CloverRect } | null;
+  /** A rectangle in one image's own coordinates, in world units. */
+  itemRectToWorld(index: number, rect: CloverRect): CloverRect | null;
+  /** A point in world units, on the screen. */
+  worldToScreenPoint(point: CloverPoint): CloverPoint;
+  /** A point on the screen, in world units. */
+  screenToWorldPoint(point: CloverPoint): CloverPoint;
+  /** Hear the renderer (viewport: the camera moved; change: new images); returns the way to stop. */
+  on(event: "open" | "viewport" | "change" | "error" | "backend" | "tap", listener: (detail?: unknown) => void): () => void;
+}
+
+/** Clover's Viewer, in one of its templates: Default (the title over the Body, the thumbnails under it, the information panel beside them), Document (a PDF reader's pages, thumbnails beside them) or Gallery (a grid, each item opening in a lightbox). Each template loads when used, its styles with it. */
+export interface CloverViewerElement extends HTMLElement {
+  /** What to show, as the attribute takes it, or a IIIF resource as an object. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** Annotations to show beside the Manifest's own, as URLs or objects. */
+  annotations: string | Record<string, unknown> | Array<string | Record<string, unknown>> | null;
+  /** Credentials, headers and a fetch of your own, for every request. */
+  request: { credentials?: RequestCredentials; headers?: Record<string, string>; fetch?: typeof fetch } | null;
+  /** Renderers of yours, for its Body: each claims views (canvasId, format or match) and draws one into a box of its own (render), returning what undoes it. */
+  renderers: CloverRenderer[] | null;
+}
+
+/** The root of a layout of your own: it loads what it is given, holds where the reader is, and gives every part inside it the same state. The page's markup inside it stays as written. */
+export interface CloverRootElement extends HTMLElement {
+  /** Its Clover, for a part of your own, once it has loaded (clover-ready): what React's hooks read, as methods of the same name (navigation(), visibleCanvases()…), the table of contents (contents()), its state and subscribe, its actions and channels, and its language. Null before. */
+  readonly clover: CloverRootApi | null;
+  /** What to show, as the attribute takes it, or a IIIF resource as an object. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** Annotations to show beside the Manifest's own, as URLs or objects. */
+  annotations: string | Record<string, unknown> | Array<string | Record<string, unknown>> | null;
+  /** Credentials, headers and a fetch of your own, for every request. */
+  request: { credentials?: RequestCredentials; headers?: Record<string, string>; fetch?: typeof fetch } | null;
+  /** Renderers of yours, for every clover-body in it: each claims views (canvasId, format or match) and draws one into a box of its own (render), returning what undoes it. */
+  renderers: CloverRenderer[] | null;
+}
+
+/** The view of the clover-root it is in, drawn as Body draws it: images, video and sound, or a renderer of yours. It is the Body's box, its height from --clover-body-height (60vh by default) or its own style. A clover-panel-toggle, and a button of yours, in it are among its controls. */
+export interface CloverBodyElement extends HTMLElement {
+  /** The Canvas's handle once its view is laid out (clover-ready), as onReady hands it in React: the camera and its coordinates (handle.zoomBy(2), handle.home()). Null before. */
+  readonly handle: CloverCanvasHandle | null;
+  /** Which of the Body's controls it shows, as Canvas's controls takes it: false for none, or some ({ rotation: false }), in place of the attribute. */
+  controls: boolean | { zoom?: boolean; fullPage?: boolean; rotation?: boolean; reset?: boolean; annotations?: boolean; information?: boolean; [option: string]: unknown } | null;
+  /** The Canvas's options: the request it loads with (credentials, headers, a fetch of your own), its gestures and more. */
+  options: { request?: { credentials?: RequestCredentials; headers?: Record<string, string>; fetch?: typeof fetch }; [key: string]: unknown } | null;
+  /** The Body's controls, each replaced by a button you make: a function given the control's name, label and Clover's icon, returning the button. Clover keeps it named, keyed and in its state, presses the control with it, and adds its popover. */
+  controlButtons: CloverControlButtons | null;
+  /** Renderers of yours for this Body only, in place of the root's: each claims views (canvasId, format or match) and draws one into a box of its own (render). */
+  renderers: CloverRenderer[] | null;
+}
+
+/** A label, as Label draws it, marked with the language it is in. Inside a clover-root, the Manifest's or the Canvas's; alone, the one it is given. Nothing is drawn while there is none, so a heading is never left empty. */
+export interface CloverLabelElement extends HTMLElement {
+  /** A label to show instead, as text or a IIIF language map. */
+  label: string | Record<string, string[]> | null;
+}
+
+/** Thumbnails, as Items draws them. Inside a clover-root, its views (or its Collection's members), choosing what it shows; alone, the members or views of what it is given, as links. */
+export interface CloverItemsElement extends HTMLElement {
+  /** Alone: what to list, as a URL or a IIIF resource. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** Alone: a list of IIIF resources to show, as they are. */
+  items: unknown[] | null;
+  /** Alone: credentials, headers and a fetch of your own. In a root, the root's are used. */
+  request: { credentials?: RequestCredentials; headers?: Record<string, string>; fetch?: typeof fetch } | null;
+  /** Your own figure for an item, in place of its thumbnail and label: a node or text, which names the item. A new node each time. */
+  renderItem: ((item: { id: string; label?: string | Record<string, string[]>; summary?: string | Record<string, string[]>; href?: string }, state: { selected: boolean }) => Node | string | null | undefined) | null;
+}
+
+/** Where the reader is, as a count: Item 3 of 12. It keeps the room of its widest count, so nothing beside it moves. */
+export interface CloverPositionElement extends HTMLElement {
+}
+
+/** A button to the previous view (or member), shown disabled where there is none. */
+export interface CloverPreviousElement extends HTMLElement {
+}
+
+/** A button to the next view (or member), shown disabled where there is none. */
+export interface CloverNextElement extends HTMLElement {
+}
+
+/** What the root is doing: its loading mark while it loads, announced as Loading…, and why it failed if it did, as an alert. Empty and out of sight once it is ready. */
+export interface CloverStatusElement extends HTMLElement {
+}
+
+/** The thumbnail (for a Canvas, its first image), its alt text the resource's label. */
+export interface CloverThumbnailElement extends HTMLElement {
+  /** A resource to picture (a Manifest, Canvas or Collection), instead of the root's. */
+  value: Record<string, unknown> | null;
+}
+
+/** The summary, as sanitized HTML, cut to five lines with Read more under it when it runs longer (--clover-summary-lines). */
+export interface CloverSummaryElement extends HTMLElement {
+  /** A summary, instead of the root's. */
+  value: string | Record<string, string[]> | null;
+}
+
+/** The metadata, as a description list of labels and their values. */
+export interface CloverMetadataElement extends HTMLElement {
+  /** Metadata, instead of the root's. */
+  value: Array<{ label: Record<string, string[]>; value: Record<string, string[]> }> | null;
+  /** Your own drawing of a value: a node or text to show in its place, or undefined for Clover's. A new node each time. */
+  renderValue: ((item: { label: Record<string, string[]>; value: Record<string, string[]> }) => Node | string | null | undefined) | null;
+}
+
+/** The required statement: the attribution that must be shown, as a label and its value. */
+export interface CloverRequiredStatementElement extends HTMLElement {
+  /** A required statement, instead of the root's. */
+  value: { label: Record<string, string[]>; value: Record<string, string[]> } | null;
+}
+
+/** The rights: a link to the license or rights statement. */
+export interface CloverRightsElement extends HTMLElement {
+  /** A rights URL, instead of the root's. */
+  value: string | null;
+}
+
+/** The homepage: the resource's own web page, as a list of links. */
+export interface CloverHomepageElement extends HTMLElement {
+  /** Homepages, instead of the root's. */
+  value: string | Array<{ id: string; label?: Record<string, string[]>; format?: string }> | null;
+}
+
+/** See also: machine-readable descriptions elsewhere, as a list of links. */
+export interface CloverSeeAlsoElement extends HTMLElement {
+  /** Descriptions, instead of the root's. */
+  value: string | Array<{ id: string; label?: Record<string, string[]>; format?: string }> | null;
+}
+
+/** The rendering: alternate formats, such as a PDF of the whole object, as a list of links, each with its format. */
+export interface CloverRenderingElement extends HTMLElement {
+  /** Renderings, instead of the root's. */
+  value: string | Array<{ id: string; label?: Record<string, string[]>; format?: string }> | null;
+}
+
+/** Part of: the Collections the resource belongs to, as a list of links. */
+export interface CloverPartOfElement extends HTMLElement {
+  /** Collections, instead of the root's. */
+  value: string | Array<{ id: string; label?: Record<string, string[]>; format?: string }> | null;
+}
+
+/** The resource's id: a link to its IIIF JSON. */
+export interface CloverIdElement extends HTMLElement {
+  /** An id, instead of the root's. */
+  value: string | null;
+}
+
+/** The providers: who provided the resource, each its logo and its name, linked to its homepage. With a clover-logo in it, each provider's logo alone, linked, its alt text the provider's name. */
+export interface CloverProviderElement extends HTMLElement {
+  /** Providers (IIIF Agents), instead of the root's. */
+  value: Record<string, unknown> | Array<Record<string, unknown>> | null;
+}
+
+/** A provider's logo, its alt text the provider's name: each of the resource's providers' in turn. Inside a clover-provider it draws nothing itself, and the provider draws each provider's logo in its place. */
+export interface CloverLogoElement extends HTMLElement {
+  /** Logos: images, or Agents with theirs, instead of the root's. */
+  value: Record<string, unknown> | Array<Record<string, unknown>> | null;
+}
+
+/** Any IIIF language map in the reader's language, read strictly by its format: text/html as sanitized HTML, text/plain as written, text/markdown as Markdown. */
+export interface CloverValueElement extends HTMLElement {
+  /** What to show. */
+  value: string | Record<string, string[]> | null;
+}
+
+/** The information panel's first section, on its own: the label and thumbnail, summary, metadata, required statement, rights, homepage, see also, downloads and address. */
+export interface CloverAboutElement extends HTMLElement {
+}
+
+/** The annotations, by layer and then by Canvas: each to pick, which frames it on the Body, with its region pictured. */
+export interface CloverAnnotationsElement extends HTMLElement {
+  /** Your own drawing of an annotation's content: a node or text, in place of its bodies. A new node each time. */
+  renderEntry: ((entry: { id: string; canvasId: string; annotation: Record<string, unknown> }) => Node | string | null | undefined) | null;
+}
+
+/** The Collection the Manifest was reached through: its label, summary and members, each to open, its homepage and its address. */
+export interface CloverCollectionElement extends HTMLElement {
+}
+
+/** A menu of the Collection's members, choosing the Manifest shown. A key steps through it and Enter opens the one stepped to. */
+export interface CloverCollectionSelectElement extends HTMLElement {
+}
+
+/** The Manifest's table of contents (its Ranges), as a tree of links to each section, the one in view marked. */
+export interface CloverContentsElement extends HTMLElement {
+}
+
+/** A Content Search of the Manifest, where it offers one: a field, and its hits by Canvas, each going to its place, with Previous and Next through them. */
+export interface CloverSearchElement extends HTMLElement {
+}
+
+/** The recording's captions as a transcript, following where it plays, and any plain-text transcript after them. Each cue goes to its time; a field over the captions finds words in them, with steps through the cues that have them. */
+export interface CloverTranscriptElement extends HTMLElement {
+}
+
+/** The renderings of the page in view and of the Manifest (a PDF, a text, a full-size file), as links in two groups, This page and All pages. Nothing while there are none. */
+export interface CloverDownloadElement extends HTMLElement {
+}
+
+/** A map: inside a clover-root, its places (navPlace) and the view's georeferenced images; alone, those of the iiif-content it is given. Its places are listed under it as buttons, for the keyboard. */
+export interface CloverMapElement extends HTMLElement {
+  /** Alone: what to map, by URL or as a IIIF resource. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** Alone: GeoJSON to draw, as navPlace is. */
+  navPlace: Record<string, unknown> | null;
+  /** Alone: Georeference Extension annotations to overlay. */
+  georeferences: unknown[] | null;
+  /** Alone: credentials, headers and a fetch of your own. */
+  request: { credentials?: RequestCredentials; headers?: Record<string, string>; fetch?: typeof fetch } | null;
+}
+
+/** The information panel of the clover-root it is in, in tabs or stacked boxes: the sections Clover has data for (About, Contents, Search, a Map, the Transcript, Annotations, the Collection), or its clover-tab children, in their order. */
+export interface CloverPanelElement extends HTMLElement {
+}
+
+/** One tab of the clover-panel it is in: its label, and what it holds, which the panel shows in its section, moved there when the section first opens. It draws nothing itself. */
+export interface CloverTabElement extends HTMLElement {
+}
+
+/** A button that shows and hides an element, the information panel's or any, by its id: open while it is not hidden. In a clover-body, it is one of the Body's controls; elsewhere, a button where it is. */
+export interface CloverPanelToggleElement extends HTMLElement {
+}
+
+/** Panes side by side, its clover-split-pane children, divided by clover-split-handle bars the reader drags, clicks or moves by keyboard to share the width. */
+export interface CloverSplitElement extends HTMLElement {
+}
+
+/** One side of a clover-split. One pane beside each handle has a size; the other takes the width that is left. */
+export interface CloverSplitPaneElement extends HTMLElement {
+}
+
+/** The bar between two clover-split-panes, a focusable separator with a grip at its middle: drag it; click or tap it to step the pane through its narrowest, own and widest widths; or move it with the arrow keys, Home and End. Named Resize panels, or by its aria-label. */
+export interface CloverSplitHandleElement extends HTMLElement {
+}
+
+/** Clover's renderer for images, video and sound. Alone, it draws what it is given: a IIIF resource by URL (a Manifest gives its first Canvas), image URLs, or Canvases as a property. Inside a clover-root, given nothing, the root's view. As tall as --clover-body-height (60vh) or its own style. */
+export interface CloverCanvasElement extends HTMLElement {
+  /** The Canvas's handle once its view is laid out (clover-ready), as onReady hands it in React: the camera and its coordinates (handle.zoomBy(2), handle.home()). Null before. */
+  readonly handle: CloverCanvasHandle | null;
+  /** What to load and draw, as a URL or a IIIF resource. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** Presentation 4 Canvases to draw, one or several shown together (a spread). */
+  canvases: Record<string, unknown>[] | null;
+  /** Image URLs, or image services with tiled. */
+  src: string | string[] | null;
+  /** Annotations to draw as hotspots, with rectangular (xywh) targets in the image's own coordinates. */
+  annotations: Array<{ id: string; target: string; label?: string; [key: string]: unknown }> | null;
+  /** The Canvas's options: the request it loads with (credentials, headers, a fetch of your own), its gestures and more. */
+  options: { request?: { credentials?: RequestCredentials; headers?: Record<string, string>; fetch?: typeof fetch }; [key: string]: unknown } | null;
+  /** The Body's controls, each replaced by a button you make: a function given the control's name, label and Clover's icon, returning the button. Clover keeps it named, keyed and in its state, presses the control with it, and adds its popover. */
+  controlButtons: CloverControlButtons | null;
+  /** Which of the Body's controls it shows, as Canvas's controls takes it: false for none, or some ({ rotation: false }), in place of the attribute. */
+  controls: boolean | { zoom?: boolean; fullPage?: boolean; rotation?: boolean; reset?: boolean; annotations?: boolean; information?: boolean; [option: string]: unknown } | null;
+}
+
+/** A IIIF Presentation 4 Timeline (sound), played through Canvas, with its transport, captions, chapters and annotations on its time, and its accompanying or placeholder Canvas while it plays. Alone, it plays what it is given; inside a clover-root, given nothing, the root's view when that is a Timeline. As tall as --clover-body-height (60vh) or its own style. */
+export interface CloverTimelineElement extends HTMLElement {
+  /** What to load and play, as a URL or a IIIF resource. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** A Presentation 4 Timeline to play. */
+  timeline: Record<string, unknown> | null;
+  /** Annotations on its time, each shown as a cue while its stretch plays, as Canvas's annotations property takes them. */
+  annotations: Record<string, unknown>[] | null;
+  /** As Canvas's options: request (credentials, headers) and hideDelay among them. */
+  options: Record<string, unknown> | null;
+  /** Which of the Body's controls it shows, as Canvas's controls takes it, in place of the attribute. */
+  controls: boolean | { information?: boolean; annotations?: boolean; [option: string]: unknown } | null;
+}
+
+/** A IIIF Presentation 4 Scene, drawn in 3D: the glTF models it paints, lit and framed, turned and zoomed by pointer, key or control. Its 3D library loads only when one is drawn. Alone, it draws what it is given; inside a clover-root, given nothing, the root's view when that is a Scene. As tall as --clover-body-height (60vh) or its own style. */
+export interface CloverSceneElement extends HTMLElement {
+  /** What to load and draw, as a URL or a IIIF resource. */
+  iiifContent: string | Record<string, unknown> | null;
+  /** A Presentation 4 Scene to draw. */
+  scene: Record<string, unknown> | null;
+  /** request: credentials and headers for the Scene and its models; hideDelay: how long the controls stay after a mouse stops, in milliseconds. */
+  options: { request?: Record<string, unknown>; hideDelay?: number } | null;
+  /** Which of the Body's controls it shows: false for none, or some ({ rotation: false }), in place of the attribute. */
+  controls: boolean | { zoom?: boolean; fullPage?: boolean; rotation?: boolean; reset?: boolean; information?: boolean } | null;
+}
+
+/** The popover Clover's controls show on hover and on keyboard focus, for a control of your own: written inside your button, it shows there its label and its key. Give the button the same name (aria-label) and the key (aria-keyshortcuts): the popover is hidden from assistive technology, which reads the button. The element itself shows nothing. */
+export interface CloverTipElement extends HTMLElement {
+  /** The key, as Clover.Tip takes it: in place of keys and glyph. */
+  shortcut: { keys: string; glyph: string } | null;
+}
+
+/** Read more, for text of your own: its one child, clamped by your CSS (a -webkit-line-clamp), gets a button under it once the text runs past its box, which opens it in full (aria-expanded) and cuts it short again. While open, the child carries data-read-more="open", which your clamp should leave alone. */
+export interface CloverReadMoreElement extends HTMLElement {
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "clover-viewer": CloverViewerElement;
+    "clover-root": CloverRootElement;
+    "clover-body": CloverBodyElement;
+    "clover-label": CloverLabelElement;
+    "clover-items": CloverItemsElement;
+    "clover-position": CloverPositionElement;
+    "clover-previous": CloverPreviousElement;
+    "clover-next": CloverNextElement;
+    "clover-status": CloverStatusElement;
+    "clover-thumbnail": CloverThumbnailElement;
+    "clover-summary": CloverSummaryElement;
+    "clover-metadata": CloverMetadataElement;
+    "clover-required-statement": CloverRequiredStatementElement;
+    "clover-rights": CloverRightsElement;
+    "clover-homepage": CloverHomepageElement;
+    "clover-see-also": CloverSeeAlsoElement;
+    "clover-rendering": CloverRenderingElement;
+    "clover-part-of": CloverPartOfElement;
+    "clover-id": CloverIdElement;
+    "clover-provider": CloverProviderElement;
+    "clover-logo": CloverLogoElement;
+    "clover-value": CloverValueElement;
+    "clover-about": CloverAboutElement;
+    "clover-annotations": CloverAnnotationsElement;
+    "clover-collection": CloverCollectionElement;
+    "clover-collection-select": CloverCollectionSelectElement;
+    "clover-contents": CloverContentsElement;
+    "clover-search": CloverSearchElement;
+    "clover-transcript": CloverTranscriptElement;
+    "clover-download": CloverDownloadElement;
+    "clover-map": CloverMapElement;
+    "clover-panel": CloverPanelElement;
+    "clover-tab": CloverTabElement;
+    "clover-panel-toggle": CloverPanelToggleElement;
+    "clover-split": CloverSplitElement;
+    "clover-split-pane": CloverSplitPaneElement;
+    "clover-split-handle": CloverSplitHandleElement;
+    "clover-canvas": CloverCanvasElement;
+    "clover-timeline": CloverTimelineElement;
+    "clover-scene": CloverSceneElement;
+    "clover-tip": CloverTipElement;
+    "clover-read-more": CloverReadMoreElement;
+  }
+  interface GlobalEventHandlersEventMap {
+    "clover-canvas-change": CustomEvent<{ canvasId: string }>;
+    "clover-manifest-change": CustomEvent<{ manifestId: string }>;
+    "clover-status-change": CustomEvent<{ status: "loading" | "ready" | "error"; error: Error | null }>;
+    "clover-content-state-change": CustomEvent<{ json: Record<string, unknown>; encoded: string }>;
+    "clover-ready": CustomEvent<{ clover: CloverRootApi } | { handle: CloverCanvasHandle }>;
+    "clover-annotation-active": CustomEvent<{ id: string | null }>;
+    "clover-caption-change": CustomEvent<{ caption: { id: string; language?: string } | null }>;
+    "clover-ended": CustomEvent<Record<string, never>>;
+    "clover-select": CustomEvent<{ item: { id: string; label?: string | Record<string, string[]>; summary?: string | Record<string, string[]>; href?: string } } | { feature: { title?: string; canvasId?: string; [key: string]: unknown } }>;
+    "clover-change": CustomEvent<{ manifestId: string }>;
+    "clover-value-change": CustomEvent<{ value: string }>;
+    "clover-close": CustomEvent<Record<string, never>>;
+    "clover-open-change": CustomEvent<{ open: boolean }>;
+    "clover-annotation-select": CustomEvent<{ id: string | null }>;
+  }
+}

package/dist/web-components/index.mjs

@@ -0,0 +1 @@
+import{d as n,i as o}from"./index-B7nZdqLg.mjs";export{n as defineCloverElements,o as initCloverI18n};

package/dist/web-components/index.umd.js

@@ -0,0 +1,18 @@
+// Preserve the classic script URL while letting the browser load feature chunks.
+// Resolve against this script, not the embedding page (including on a CDN).
+(function () {
+  var script = document.currentScript;
+  if (!script || !script.src) {
+    throw new Error("Load Clover web components using an external script src.");
+  }
+  var url = new URL("./index.mjs", script.src).href;
+  // Say so when it cannot load: a CDN must serve the module beside this script, with CORS.
+  import(url).catch(function (error) {
+    console.error(
+      "Clover's web components could not load from " +
+        url +
+        ". Serve index.mjs and its chunks beside index.umd.js, with CORS if from another origin.",
+      error,
+    );
+  });
+})();

package/dist/web-components/items-CB2Uk7ts.mjs

@@ -0,0 +1 @@
+import{j as p,E as u,o as r,O as v}from"./shared-YUjOSBKO.mjs";function g(t){var i;return(i=v(t).find(({body:a})=>a.type))==null?void 0:i.body.type}function o(t){const i=g(t)??(t.type==="Timeline"?"Sound":void 0);return{id:t.id,type:t.type,label:t.label,resource:t,duration:Number(t.duration)||void 0,media:i}}const s=new WeakMap;function m(t){if(!t)return[];let i=s.get(t);if(!i){const{canvases:a,views:e}=u(t);i=e.map(y=>{const n=y.map(l=>o(a[l]));return{id:n[0].id,parts:n,label:n.length===1?n[0].label:{none:[n.map(l=>r(l.label).text).filter(Boolean).join(" \u2013 ")]}}}),s.set(t,i)}return i}const d=new WeakMap;function f(t){if(!t)return[];let i=d.get(t);return i||(i=p(t.items).filter(a=>a==null?void 0:a.id).map(a=>{var e;return{id:a.id,parts:[o(a)],label:a.label,summary:a.summary,href:((e=p(a.homepage)[0])==null?void 0:e.id)??a.id}}),d.set(t,i)),i}function O(t){return t?Array.isArray(t)?f({items:t}):t.type==="Collection"?f(t):m(t):[]}export{m as a,O as b,f as i};

package/dist/web-components/items-jfQ5XzEj.mjs

@@ -0,0 +1 @@
+import{T as m,u as r}from"./shared-YUjOSBKO.mjs";import{I as o}from"./Items-DRj1UEpC.mjs";import{w as n}from"./nodes-B7JRwBgl.mjs";function I({props:t}){const e=m(()=>n(t,["renderItem"]),[t]);return r(o,{...e})}export{I as ItemsElement};

package/dist/web-components/keep-fragments-B5nlv2ck.mjs

@@ -0,0 +1 @@
+const s=r=>!!r&&typeof r=="object"&&!Array.isArray(r)&&typeof r.id=="string"&&r.id.includes("#")&&r.type!=="SpecificResource";function c(r){if(Array.isArray(r))return r.some(c);if(!r||typeof r!="object")return false;for(const[n,e]of Object.entries(r))if(n==="target"&&(Array.isArray(e)?e:[e]).some(s)||c(e))return true;return false}function f(r){const{id:n,...e}=r,[t,i]=n.split("#");return{type:"SpecificResource",source:{...e,id:t},selector:{type:"FragmentSelector",value:i}}}function o(r){if(Array.isArray(r))return r.map(o);if(!r||typeof r!="object")return r;const n={};for(const[e,t]of Object.entries(r))n[e]=e==="target"?Array.isArray(t)?t.map(i=>s(i)?f(i):o(i)):s(t)?f(t):o(t):o(t);return n}function y(r){return c(r)?o(r):r}export{y as keepFragments};

package/dist/web-components/label-Vbg_cMOJ.mjs

@@ -0,0 +1 @@
+import{u as e}from"./shared-YUjOSBKO.mjs";import{L as o}from"./Label-D6aVJB9s.mjs";function n({props:r}){return e(o,{...r})}export{n as LabelElement};

package/dist/web-components/languageCode-cCpiU0b0.mjs

@@ -0,0 +1 @@
+function n(e){if(!(!e||e==="none"))return e.toUpperCase()}export{n as l};