@nulib/clover 4.0.0-beta.1 → 4.1.0

package/dist/templates/gallery/Gallery.mjs

@@ -1,62 +1,134 @@
 "use client";
-import { jsxs, jsx } from "react/jsx-runtime";
-import { useState } from "react";
+import { jsxs, jsx, Fragment } from "react/jsx-runtime";
+import { useState, useCallback } from "react";
+import { useGivenAnnotations } from "../shared/givenAnnotations.mjs";
 import { preloadLightbox, Lightbox } from "../shared/Lightbox.mjs";
 import { titled } from "../../ui/heading.mjs";
 import { useUniqueId } from "../../ui/useUniqueId.mjs";
 import { Root } from "../../components/Root/Root.mjs";
+import { useCloverSelector } from "../../react/context.mjs";
 import { Label } from "../../components/Label/Label.mjs";
 import { Summary } from "../../components/Primitives/Primitives.mjs";
 import { Status } from "../../components/Status/Status.mjs";
 import { Items } from "../../components/Items/Items.mjs";
 const below = (level) => level + 1;
+const length = (value) => typeof value === "number" ? `${value}px` : value;
 function Gallery({
   className,
   size,
+  height = "auto",
+  gap,
+  items = "grid",
+  secondary,
+  summary = true,
+  lightboxItems = "slider",
+  panel = true,
+  defaultPanelOpen = true,
+  panelLayout = "accordion",
+  download = true,
+  languages = true,
+  storageKey = "clover-template-gallery",
   headingLevel = 2,
+  collapseControls,
   style,
   ...root
 }) {
   const [open, setOpen] = useState(false);
+  const close = useCallback(() => setOpen(false), []);
   const title = titled(
     headingLevel,
     `${useUniqueId().replace(/:/g, "")}-title`
   );
+  const fixed = height !== "auto";
+  const vars = {
+    ...size && { "--clover-items-size": size },
+    ...fixed && { "--clover-template-gallery-height": length(height) },
+    ...gap != null && { "--clover-template-gallery-gap": length(gap) }
+  };
   return /* @__PURE__ */ jsxs(
     Root,
     {
       className: ["clover-template-gallery", className].filter(Boolean).join(" "),
-      style: size ? { ...style, "--clover-items-size": size } : style,
+      style: { ...style, ...vars },
+      "data-height": fixed ? "fixed" : "auto",
       onPointerOver: preloadLightbox,
       onFocus: preloadLightbox,
       ...title.group,
       ...root,
       children: [
-        /* @__PURE__ */ jsxs("header", { className: "clover-template-gallery-header", children: [
-          /* @__PURE__ */ jsx(
-            Label,
-            {
-              as: title.as,
-              className: "clover-template-gallery-title",
-              ...title.title
-            }
-          ),
-          /* @__PURE__ */ jsx(Summary, { className: "clover-template-gallery-summary" })
-        ] }),
-        /* @__PURE__ */ jsx(Status, {}),
-        /* @__PURE__ */ jsx(Items, { layout: "grid", onSelect: () => setOpen(true) }),
+        /* @__PURE__ */ jsx(
+          GalleryGrid,
+          {
+            title,
+            layout: items === "masonry" ? "masonry" : "grid",
+            secondary,
+            summary,
+            onOpen: () => setOpen(true)
+          }
+        ),
         /* @__PURE__ */ jsx(
           Lightbox,
           {
             open,
-            onClose: () => setOpen(false),
-            headingLevel: below(headingLevel)
+            onClose: close,
+            headingLevel: below(headingLevel),
+            items: lightboxItems,
+            panel,
+            defaultPanelOpen,
+            panelLayout,
+            download,
+            languages,
+            storageKey,
+            collapseControls
           }
         )
       ]
     }
   );
 }
+function GalleryGrid({
+  title,
+  layout,
+  secondary,
+  summary,
+  onOpen
+}) {
+  const collection = useCloverSelector(
+    (state) => state.throughCollection ? state.collection : null
+  );
+  const set = useGivenAnnotations();
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsxs("header", { className: "clover-template-gallery-header", children: [
+      /* @__PURE__ */ jsx(
+        Label,
+        {
+          as: title.as,
+          className: "clover-template-gallery-title clover-template-title clover-title",
+          label: set ? set.label : collection == null ? void 0 : collection.label,
+          ...title.title
+        }
+      ),
+      summary && !set && /* @__PURE__ */ jsx(
+        Summary,
+        {
+          className: "clover-template-gallery-summary",
+          value: collection == null ? void 0 : collection.summary
+        }
+      )
+    ] }),
+    /* @__PURE__ */ jsx(Status, { loading: collection || set ? false : void 0 }),
+    /* @__PURE__ */ jsx(
+      Items,
+      {
+        layout,
+        secondary,
+        of: set ? "annotations" : collection ? "members" : "views",
+        singleItem: true,
+        onSelect: onOpen
+      }
+    )
+  ] });
+}
 export {
   Gallery
 };

package/dist/templates/index.d.mts

@@ -3,6 +3,11 @@
 import * as P4 from '@iiif/parser/presentation-4/types';
 import React from 'react';
 
+/**
+ * IIIF language maps as text: the closest language to the reader's, and that language's
+ * tag, so the text can carry a `lang` attribute.
+ */
+export type LanguageMapLike = string | Record<string, string[] | string | undefined> | null | undefined;
 export type Presentation4Canvas = P4.Canvas;
 export type Presentation4Scene = P4.Scene;
 export type Presentation4Timeline = P4.Timeline;
@@ -118,6 +123,14 @@ export interface RootProps extends Omit<React.HTMLAttributes<HTMLElement>, "chil
 	request?: CloverRequest;
 	/** The language to read IIIF text in. The reader's, by default. */
 	language?: string;
+	/**
+	 * Clover's higher-contrast mode, for every part inside: the accent kept to rings,
+	 * outlines and marks, and never under words or a glyph, where the controls' dark fill
+	 * takes its place, edged in the accent. For an accent that cannot carry white text at
+	 * 4.5:1. It is on wherever the reader's system asks for more contrast, too. Default
+	 * `false`.
+	 */
+	highContrast?: boolean;
 	/**
 	 * Renderers of your own for some views — by Canvas id, painting format, or a test —
 	 * drawn by every `Body` inside in place of `Canvas` (3.x's `customDisplays`).
@@ -134,19 +147,169 @@ export interface RootProps extends Omit<React.HTMLAttributes<HTMLElement>, "chil
 	 */
 	annotationPages?: "view" | "all";
 	/**
-	 * Where the reader is, as a IIIF content state, whenever it settles: after a move, a
-	 * pan or zoom, or a pause or seek in media. Debounced, and only when it changed.
+	 * Where the reader is, as a IIIF content state, as it changes: a move, a pan or zoom,
+	 * or a pause or seek in media. At most every 150ms while it moves, always its last
+	 * place, and only when it changed.
 	 */
 	onContentStateChange?: (state: ContentStateOutput) => void;
 	/** The element to render. Default `div`. */
 	as?: React.ElementType;
 	children?: React.ReactNode;
 }
+/** A region of the image as shares of it: 0 to 1 across and down. */
+export interface RegionShare {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+}
+/**
+ * A small picture of a IIIF resource, for a list or a strip of them.
+ *
+ * - The resource's own `thumbnail` comes first; then, for a Canvas, the first image it
+ *   paints; then its placeholder or accompanying Canvas's (video and sound).
+ * - An image service is asked for nothing until its own `info.json` has been read (the
+ *   renderer's cached fetch, so a Canvas shown later does not ask again), and then only
+ *   as strictly as it says it can answer (`sizedImageUrl`): never more than the image has,
+ *   nor than its limits, at level 0 only a size it lists (Mat, 2026-10-24: "be
+ *   responsible when making IIIF image server requests"). What a manifest says of a
+ *   service is not trusted to say what its server does.
+ * - Without a service, the image itself is used.
+ */
+export interface ThumbnailSource {
+	/** Ready to use: an image with no service. */
+	src?: string;
+	/** An image service: its `info.json` is read before a URL is made (`resolveThumbnail`). */
+	service?: string;
+	/**
+	 * Only part of the image: shares of it (a target's region), or a region in Image API
+	 * syntax in the service's own pixels (a painting's selector), read against its `info.json`.
+	 */
+	region?: RegionShare | string;
+	/** Used if the service cannot answer. */
+	fallback?: string;
+}
+/**
+ * What `Items` shows: light models of a Manifest's views or a Collection's members, never
+ * the resources themselves, so a long sequence costs a few fields per item.
+ *
+ * Memoized on the resource object, as the selectors are.
+ */
+export interface ItemPart {
+	id: string;
+	type: string;
+	label?: LanguageMapLike;
+	/** The resource, for a thumbnail and for `renderItem`. */
+	resource: unknown;
+	/** Seconds, for video and sound. */
+	duration?: number;
+	/** What it mostly paints: `Image`, `Video`, `Audio` (`Sound` in Presentation 3) or `Model`. */
+	media?: string;
+	/**
+	 * Its picture, where it is not the resource's own: a region of its Canvas (a content
+	 * state's target, Cookbook 0540). Null for none.
+	 */
+	source?: ThumbnailSource | null;
+}
+export interface ItemModel {
+	/** The first Canvas of a view, or a member's id. What selecting it goes to. */
+	id: string;
+	/** A Canvas view: one Canvas, or a spread. A member: itself. */
+	parts: ItemPart[];
+	label?: LanguageMapLike;
+	summary?: LanguageMapLike;
+	/** A member's date for navigation, as written (Cookbook 0318). */
+	navDate?: string;
+	/** Where a link to a member goes: its `homepage`, else its id. */
+	href?: string;
+	/** That homepage's own language, where its `language` gives one. */
+	hrefLang?: string;
+}
+/** The line under an item's label: its summary, its date (`navDate`), or neither. */
+export type ItemSecondary = "summary" | "navDate" | "none";
 /**
- * A scrolling row of thumbnails (`slider`), a column, a wrapping grid, or one item at a
- * time (`pager`: Previous, Position and Next).
+ * A scrolling row of thumbnails (`slider`), a column, a wrapping grid, a grid whose
+ * pictures keep their proportions (`masonry`), or one item at a time (`pager`: Previous,
+ * Position and Next).
  */
-export type ItemsLayout = "slider" | "list" | "grid" | "pager";
+export type ItemsLayout = "slider" | "list" | "grid" | "masonry" | "pager";
+export interface ItemsProps extends Omit<React.HTMLAttributes<HTMLElement>, "onSelect" | "children"> {
+	/**
+	 * A scrolling row (the default), a column, a wrapping grid, `masonry`, or `pager`:
+	 * Previous, Position and Next, stepping one item at a time, with no thumbnails.
+	 * `masonry` is a grid whose pictures keep their own proportions, each item packed up
+	 * under the one above it, still in reading order, left to right.
+	 */
+	layout?: ItemsLayout;
+	/**
+	 * The line under an item's label, where it has one (a Collection's members do): its
+	 * `summary` (the default), its `navDate`, or `none`. Default `"summary"`.
+	 */
+	secondary?: ItemSecondary;
+	/**
+	 * The pager's size: `large` (the default), round controls; or `small`, its steps and
+	 * count as Search's are, for a header's line. Default `"large"`.
+	 */
+	size?: "large" | "small";
+	/**
+	 * Inside a `Root`: the Manifest's views (default), the members of the Collection it
+	 * belongs to, choosing one to show, a content state's targets, where it names two or
+	 * more (Cookbook 0540), each opening its Manifest at its place, or annotations walked as
+	 * one whole: the AnnotationPage or AnnotationCollection given as the content, else the
+	 * AnnotationCollection its annotation pages are part of (Cookbook 0309), each picked
+	 * and framed on its Canvas.
+	 */
+	of?: "views" | "members" | "targets" | "annotations";
+	/**
+	 * Standalone: a Collection (its members), a Manifest (its views) or a URL to one. Inside
+	 * a `Root`, leave it out to list the Root's views.
+	 */
+	iiifContent?: IIIFContent;
+	/** Standalone: a list of IIIF resources (Manifests, Collections, Canvases) as they are. */
+	items?: unknown[];
+	/**
+	 * `id` selects: a listbox whose options go to a view (in a `Root`). `homepage` leaves: a
+	 * list of links to each item's `homepage`. Defaults to `id` for views and `homepage`
+	 * for a Collection's members or a list.
+	 */
+	navigation?: "id" | "homepage";
+	/**
+	 * An item was chosen, with the click's or the key's own event. For a link, call
+	 * `event.preventDefault()` to stay on the page and handle it yourself.
+	 */
+	onSelect?: (item: ItemModel, event: React.SyntheticEvent) => void;
+	/** Standalone: show the resource's label, summary and homepage link. Default true. */
+	header?: boolean;
+	/**
+	 * Standalone: the level of the header's title, to fit the outline of the page around
+	 * it (a slider under an `h2` takes 3). Default 2.
+	 */
+	headingLevel?: number;
+	/** Pixels requested for each thumbnail's longer side. Default 200. */
+	thumbnailSize?: number;
+	/**
+	 * Inside a `Root`: list the views even where there is only one, as a gallery's grid
+	 * does. The pager, with nothing to step to, still draws nothing. Default `false`: one
+	 * view has nothing to choose between.
+	 */
+	singleItem?: boolean;
+	/** Standalone: credentials, headers and `fetch`. In a `Root`, the Root's are used. */
+	request?: CloverRequest;
+	/** Standalone: the language to read IIIF text in. */
+	language?: string;
+	/**
+	 * Clover's higher-contrast mode: the accent kept to rings, outlines and marks, and never
+	 * under words or a glyph, where the controls' dark fill takes its place, edged in the
+	 * accent. Inside a `Root`, the Root's too; on wherever the reader's system asks for more
+	 * contrast. Default `false`.
+	 */
+	highContrast?: boolean;
+	/** Replace an item's figure with your own. */
+	renderItem?: (item: ItemModel, state: {
+		selected: boolean;
+	}) => React.ReactNode;
+	as?: React.ElementType;
+}
 /** How the sections are laid out. */
 export type SectionsLayout = "tabs" | "accordion";
 /** How an information panel lays out its sections. */
@@ -172,10 +335,20 @@ export type DefaultProps = Omit<RootProps, "children"> & {
 	 * stacked boxes each opened by its heading, or `"tabs"`.
 	 */
 	panelLayout?: PanelLayout;
-	/** The downloads in the panel's About, as links. Default `true`. */
+	/** The downloads, from a Download button beside the panel's About heading. Default `true`. */
 	download?: boolean;
+	/**
+	 * The languages to read the resource in, beside the panel's About heading, where what
+	 * it says of itself comes in several (the Panel's `languages`). Default `true`.
+	 */
+	languages?: boolean;
 	/** The thumbnails under the Body: a layout, or `false` for none. Default `slider`. */
 	items?: Exclude<ItemsLayout, "pager"> | false;
+	/**
+	 * The thumbnails even where the resource has one view, which has nothing to choose
+	 * between. Default `false`.
+	 */
+	singleItem?: boolean;
 	/**
 	 * Where the panel's width is remembered once the reader drags its bar
 	 * (`localStorage`). Default `"clover-template-default"`; `false` forgets it.
@@ -188,6 +361,12 @@ export type DefaultProps = Omit<RootProps, "children"> & {
 	 * `--clover-body-height` tall, and the layout as tall as it needs.
 	 */
 	fill?: boolean;
+	/**
+	 * When the Body's view controls (zoom, the turns, reset, full screen) wait behind
+	 * More: `"auto"` (the default), only where its row cannot hold them all; `"always"`.
+	 * The Body's `collapseControls`.
+	 */
+	collapseControls?: "auto" | "always";
 };
 /**
  * The Viewer's own layout, drawn when no `template` is given: Clover 3.x's Viewer, built
@@ -201,13 +380,18 @@ export type DefaultProps = Omit<RootProps, "children"> & {
  * uncovered: a click there, Escape or the panel's close button puts it away. Size it with
  * `--clover-body-height`.
  */
-export declare function Default({ className, header, headingLevel, panel, defaultPanelOpen, panelLayout, download, items, storageKey, fill, ...root }: DefaultProps): React.JSX.Element;
+export declare function Default({ className, header, headingLevel, panel, defaultPanelOpen, panelLayout, download, languages, items, singleItem, storageKey, fill, collapseControls, ...root }: DefaultProps): React.JSX.Element;
 export type DocumentProps = Omit<RootProps, "children"> & {
 	/**
 	 * Whether the page thumbnails start shown beside the page. Default `true`. On a phone,
 	 * where they would float over the page, they start put away.
 	 */
 	defaultSidebarOpen?: boolean;
+	/**
+	 * The page thumbnails, and their toggle, even where the resource has one page, which
+	 * has nothing to choose between. Default `false`.
+	 */
+	singleItem?: boolean;
 	/**
 	 * Whether the information panel starts open beside the page. Default `false`. Where it
 	 * has no room there and would slide over the page, it starts closed.
@@ -220,6 +404,11 @@ export type DocumentProps = Omit<RootProps, "children"> & {
 	panelLayout?: PanelLayout;
 	/** The downloads in the toolbar, as links: the page's and the Manifest's `rendering`. Default `true`. */
 	download?: boolean;
+	/**
+	 * The languages to read the resource in, beside the panel's About heading, where what
+	 * it says of itself comes in several (the Panel's `languages`). Default `true`.
+	 */
+	languages?: boolean;
 	/**
 	 * The title's heading level, to fit the outline of the page around the layout (under
 	 * an `h2`, 3). The panel's sections, and the downloads' groups, are a level below
@@ -231,6 +420,12 @@ export type DocumentProps = Omit<RootProps, "children"> & {
 	 * (`localStorage`). Default `"clover-template-document"`; `false` forgets it.
 	 */
 	storageKey?: string | false;
+	/**
+	 * When the Body's view controls (zoom, the turns, reset, full screen) wait behind
+	 * More: `"auto"` (the default), only where its row cannot hold them all; `"always"`.
+	 * The Body's `collapseControls`.
+	 */
+	collapseControls?: "auto" | "always";
 };
 /**
  * A layout that reads like a PDF viewer: a toolbar, page thumbnails down the left, and
@@ -241,36 +436,141 @@ export type DocumentProps = Omit<RootProps, "children"> & {
  * where there is room for both, and slides out over the page where there is not. Size
  * it with `--clover-template-document-height`.
  */
-export declare function Document({ className, defaultSidebarOpen, defaultPanelOpen, panelLayout, download, headingLevel, storageKey, ...root }: DocumentProps): React.JSX.Element;
+export declare function Document({ className, defaultSidebarOpen, singleItem, defaultPanelOpen, panelLayout, download, languages, headingLevel, storageKey, collapseControls, ...root }: DocumentProps): React.JSX.Element;
 export type GalleryProps = Omit<RootProps, "children"> & {
 	/** The size of a grid cell. Default `10rem`, through `--clover-items-size`. */
 	size?: string;
+	/**
+	 * The Gallery's height: `"auto"` (the default) grows with its grid; a number (pixels)
+	 * or any CSS length fixes it, its padding inside, and the grid scrolls under the header.
+	 */
+	height?: number | string;
+	/**
+	 * The space between the grid's cells: a number (pixels) or any CSS length. Default the
+	 * Gallery's inset, `--clover-inset`.
+	 */
+	gap?: number | string;
+	/**
+	 * The grid, as its Items' layout: `grid`, square cells, or `masonry`, each picture at
+	 * its own proportions. Default `grid`.
+	 */
+	items?: Extract<ItemsLayout, "grid" | "masonry">;
+	/**
+	 * The line under each cell's label, where it has one (a Collection's members do): its
+	 * `summary`, its `navDate`, or `none`. Default `summary`.
+	 */
+	secondary?: ItemsProps["secondary"];
+	/**
+	 * The resource's summary under the title, cut to two lines with Read more under it where
+	 * it runs longer. Default `true`; `false` leaves it out, the title alone over the grid.
+	 */
+	summary?: boolean;
+	/**
+	 * How the lightbox moves on from the view it shows: a short strip of thumbnails
+	 * (`slider`, Items' carousel), or `pager`, Previous, the position and Next. Default
+	 * `slider`.
+	 */
+	lightboxItems?: "slider" | "pager";
+	/**
+	 * The information panel beside the lightbox's view, as Default's and Document's is
+	 * beside theirs, and its toggle. Default `true`.
+	 */
+	panel?: boolean;
+	/**
+	 * Whether the panel starts open beside the lightbox's view. Default `true`. Where it has
+	 * no room there and would slide over the view, it starts closed.
+	 */
+	defaultPanelOpen?: boolean;
+	/** How the panel lays out its sections: `"accordion"` (the default) or `"tabs"`. */
+	panelLayout?: PanelLayout;
+	/** The downloads in the panel's About, where there is a `rendering`. Default `true`. */
+	download?: boolean;
+	/**
+	 * The languages to read the resource in, beside the panel's About heading, where what
+	 * it says of itself comes in several (the Panel's `languages`). Default `true`.
+	 */
+	languages?: boolean;
+	/**
+	 * Where the panel's width is remembered once the reader drags its bar
+	 * (`localStorage`). Default `"clover-template-gallery"`; `false` forgets it.
+	 */
+	storageKey?: string | false;
 	/**
 	 * The title's heading level, to fit the outline of the page around the layout (under
 	 * an `h2`, 3). The lightbox's title is a level below it. Default 2.
 	 */
 	headingLevel?: number;
+	/**
+	 * When the Body's view controls (zoom, the turns, reset, full screen) wait behind
+	 * More: `"auto"` (the default), only where its row cannot hold them all; `"always"`.
+	 * Its lightbox's Body's `collapseControls`.
+	 */
+	collapseControls?: "auto" | "always";
 };
 /**
- * A grid of the Manifest's views — a spread is one cell — that opens one in a lightbox
- * with the Body and the pager. Escape, the close button, or a press outside closes it,
- * and focus returns to the cell.
+ * A grid framed by what it opens, that opens a cell in a lightbox with the Body and the
+ * pager. A Manifest: its title and summary, and a cell for each view (a spread is one
+ * cell). A Collection: its own title and summary, and a cell for each member, which
+ * shows that Manifest in the lightbox. Escape, the close button, or a press outside
+ * closes it, and focus returns to the cell.
  */
-export declare function Gallery({ className, size, headingLevel, style, ...root }: GalleryProps): React.JSX.Element;
+export declare function Gallery({ className, size, height, gap, items, secondary, summary, lightboxItems, panel, defaultPanelOpen, panelLayout, download, languages, storageKey, headingLevel, collapseControls, style, ...root }: GalleryProps): React.JSX.Element;
 export interface LightboxProps {
 	open: boolean;
 	onClose: () => void;
 	/** The level of its title, a level under the layout's. Default 3. */
 	headingLevel?: number;
+	/**
+	 * How the reader moves on from the view shown: a short strip of thumbnails (`slider`,
+	 * Items' carousel), or `pager`, Previous, the position and Next. Default `slider`.
+	 */
+	items?: "slider" | "pager";
+	/**
+	 * The information panel beside the view, as every template's is (`PanelPane`): its
+	 * toggle among the Body's controls, or on the bar beside it. Default `true`.
+	 */
+	panel?: boolean;
+	/** Whether the panel starts open beside the view; over it, closed. Default `true`. */
+	defaultPanelOpen?: boolean;
+	/** The panel's sections as stacked boxes (`"accordion"`, the default) or tabs. */
+	panelLayout?: PanelLayout;
+	/** The downloads in the panel's About, where there is a `rendering`. Default `true`. */
+	download?: boolean;
+	/** The languages to read the resource in, beside the panel's About heading. Default `true`. */
+	languages?: boolean;
+	/** Where the panel's width is remembered once dragged; `false` forgets it. */
+	storageKey?: string | false;
+	/** The Body's `collapseControls`: when the view's controls collapse behind one button. */
+	collapseControls?: "auto" | "always";
 	className?: string;
 }
 /**
- * The current Canvas in a modal `<dialog>`: its label, the Body, and the pager (with the
- * position). A native dialog keeps focus inside, closes on Escape, and returns focus to
- * whatever opened it. The Body mounts only while open, so it is sized when drawn, and its
- * code loads the first time (`preloadLightbox` starts it sooner): until then its box holds
- * its place, busy, while the title, Close and the pager are already there.
+ * The current Canvas in a modal layer over the layout, and only the layout (Mat,
+ * 2026-10-30: "backdrop should not extend beyond the bounds of the template"): over it,
+ * a step back to the level it opened from, the Manifest's label as its title (Mat,
+ * 2026-11-01: "the Manifest label stay up here in the title and be more obvious as a
+ * heading") and Close; then the Body, the view's label under it (Mat, 2026-11-01: "move
+ * the Canvas/Scene/Timeline label below the item"), and a short strip of thumbnails (Mat,
+ * 2026-11-01: "carousel by default") or the pager (with the position). A modal
+ * `<dialog>`'s backdrop always covers the whole window, so this is a layer in the Root, a
+ * `dialog` to assistive technology, named by its title: while it is open the rest of the
+ * Root is inert, focus is on the view in its strip (on Close with the pager), and Escape,
+ * Close, Back or a press on the layer outside the panel closes it, focus going back to
+ * what opened it.
+ * By default it fills the layout's bounds; `--clover-template-lightbox-inset`,
+ * `-backdrop` and `-radius` give it room, a backdrop and corners (`Lightbox.css`). The
+ * layout positions it and holds its stacking (`position: relative` and `isolation:
+ * isolate`, as the Gallery does), so its layer never stacks over the page around it.
+ *
+ * Beside the view, the information panel, as every template's is (`PanelPane`; Mat,
+ * 2026-11-01: "show the pane like we have for document/default"), its every interaction
+ * theirs.
+ *
+ * Its view mounts only while open, so it is sized when drawn, and its code (the Body, the
+ * panes and the panel's pane) loads the first time (`preloadLightbox` starts it sooner):
+ * until then a busy box holds its place under the title and Close. The Panel's own code
+ * loads as it opens, the chunk Document's is (`PanelPart`).
  */
-export declare function Lightbox({ open, onClose, headingLevel, className, }: LightboxProps): React.JSX.Element;
+export declare function Lightbox({ open, onClose, headingLevel, items, className, ...view }: LightboxProps): React.JSX.Element;
 
 export {};