@nulib/clover 4.3.1 → 4.4.0

package/dist/templates/index.d.mts

@@ -3,11 +3,76 @@
 import * as P4 from '@iiif/parser/presentation-4/types';
 import React from 'react';
 
+/**
+ * Where an annotation points, read from any form of Presentation 4 target:
+ *
+ * - a URI, `canvas#xywh=x,y,w,h` or `canvas#t=start,end`;
+ * - a reference, `{ id, type }`, whose id carries the same fragments (what the upgrader
+ *   makes of a Presentation 3 string target);
+ * - a `SpecificResource`, `{ source, selector }`, with a `FragmentSelector`,
+ *   `PointSelector` or `SvgSelector` (or an array of them, of which the first that
+ *   applies wins);
+ * - several of these, as Presentation 4 groups them (`Independents`, `List`,
+ *   `Composite`, which the upgrader makes of a Presentation 3 array), of which this reads
+ *   the first; `annotationTargets` (`components/Canvas/track.ts`, with the hotspots that
+ *   follow a recording) reads them all.
+ *
+ * A fragment may give a region and a time at once (`xywh=…&t=…`, both dimensions of a
+ * Media Fragment): the region through that stretch of a recording.
+ */
+export interface ParsedAnnotationTarget {
+	/** The Canvas (or other resource) targeted, without its fragment. */
+	id: string;
+	point?: {
+		x: number;
+		y: number;
+	};
+	rect?: {
+		x: number;
+		y: number;
+		w: number;
+		h: number;
+	};
+	svg?: string;
+	/** A media fragment's time, as written: `start` or `start,end`. */
+	t?: string;
+}
 /**
  * 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;
+/**
+ * What an annotation says: its text bodies (plain, HTML or Markdown, as their `format`
+ * says), its images (Cookbook 0377) and its named places (Cookbook 0139), each read too
+ * where a `SpecificResource` holds it as its `source` (Cookbook 0045: a comment's words,
+ * given a `styleClass`). Caption files belong to the media transcript, so are left out.
+ * Light, for the Canvas's caption as well as the lists.
+ */
+export interface AnnotationBodyEntry {
+	/** `TextualBody` text, as published: plain, or IIIF's limited HTML. */
+	value?: string;
+	format?: string;
+	language?: string;
+	/** An image body (Cookbook 0377): its URL. */
+	image?: string;
+	/**
+	 * An image body's label, else its annotation's: the image's text alternative. A place's
+	 * name, its feature's `label`, else its annotation's.
+	 */
+	label?: LanguageMapLike;
+	/**
+	 * A place, a GeoJSON `Feature` (Cookbook 0139: a map on the page, tagged with where it
+	 * shows): named by its `label`, which the Map draws it under too.
+	 */
+	place?: true;
+	/**
+	 * One item of a `Choice` (Cookbook 0346: the same words in English and in Japanese), by
+	 * the choice's place among the annotation's: of each, one shows, the one in the reader's
+	 * language (`bodyInLanguage`, `core/annotation-name.ts`).
+	 */
+	choice?: number;
+}
 export type Presentation4Canvas = P4.Canvas;
 export type Presentation4Scene = P4.Scene;
 export type Presentation4Timeline = P4.Timeline;
@@ -16,6 +81,74 @@ export type Presentation4Timeline = P4.Timeline;
  * Timeline (`Timeline`, sound) or a Scene (`Scene`, 3D).
  */
 export type Container = Presentation4Canvas | Presentation4Timeline | Presentation4Scene;
+/**
+ * Annotations to read and to point at: everything a Manifest's Canvases carry in their
+ * `annotations` (comments, tags, transcriptions, descriptions), and pages a host adds.
+ * Painting annotations are the picture, not commentary, and caption files belong to the
+ * media transcript, so neither is listed here.
+ *
+ * A set is one AnnotationPage. Sets are memoized on the Manifest and the added pages, so
+ * the same arrays come back while nothing changes.
+ */
+export interface AnnotationEntry {
+	id: string;
+	/** The set it came from. */
+	setId: string;
+	/** The Canvas it targets. */
+	canvasId: string;
+	target: ParsedAnnotationTarget;
+	motivation: string[];
+	bodies: AnnotationBodyEntry[];
+	/** The annotation as published, for a host's own rendering. */
+	annotation: Record<string, any>;
+	/**
+	 * A Range's region (`range-regions.ts`): its place among the Range's parts, "1 of 4",
+	 * which its hotspot shows after its name.
+	 */
+	place?: {
+		index: number;
+		total: number;
+	};
+	/**
+	 * An annotation of one image of a `Choice` (Cookbook 0326: an X-ray's tag), not of the
+	 * Canvas: the choice's key (`core/choice-key.ts`), the item's place in it, and the
+	 * image's id. It is drawn while that item is the one chosen, and its `target` is given
+	 * here in the Canvas's terms, placed through the image's painting.
+	 */
+	layer?: {
+		key: string;
+		item: number;
+		image: string;
+	};
+}
+/** An annotation page a Canvas names: by id, its Canvas, and whether it is fetched. */
+export interface AnnotationPageRef {
+	id: string;
+	canvasId: string;
+	fetched: boolean;
+}
+/**
+ * Annotations walked as one whole, as a viewer walks a Collection's members: the
+ * AnnotationPage or AnnotationCollection given as the content (James Turner's tags across
+ * Manifests, all in hand), else an AnnotationCollection the Manifest's annotation pages
+ * are part of (Cookbook 0309: layout markup across a newspaper's pages, managed as one
+ * whole), whose pages load as the reader reaches them.
+ */
+export interface AnnotationCollection {
+	id: string;
+	type: "AnnotationPage" | "AnnotationCollection";
+	label?: LanguageMapLike;
+	/** The number of its annotations, where it says. */
+	total?: number;
+	/**
+	 * The Manifest's pages of it, in the Canvases' order, so a listing loads them as the
+	 * reader reaches them (`usePagesReached`, `clover.fetchAnnotationPages`). None for the
+	 * content's, whose annotations are all in hand.
+	 */
+	pages: AnnotationPageRef[];
+	/** Its annotations on the Manifest's Canvases, in their order, as far as fetched. */
+	entries: AnnotationEntry[];
+}
 /**
  * How Clover asks for things: one setting for every request it makes — the IIIF resource,
  * referenced annotation pages, `info.json`, tiles, captions and HLS segments.
@@ -334,6 +467,12 @@ export interface ItemsProps extends Omit<React.HTMLAttributes<HTMLElement>, "onS
 	 * `summary` (the default), its `navDate`, or `none`. Default `"summary"`.
 	 */
 	secondary?: ItemSecondary;
+	/**
+	 * Show each item's label, and the line under it, beside its picture (`true`, the
+	 * default). `false` shows the pictures alone: the labels are hidden from sight but kept
+	 * as each item's name for assistive technology (WCAG 4.1.2). Default `true`.
+	 */
+	labels?: boolean;
 	/**
 	 * 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"`.
@@ -415,6 +554,77 @@ export type PanelSectionLabel = string | Readonly<Record<string, string>>;
 export type PanelSectionLabels = Partial<Record<PanelSection, PanelSectionLabel>>;
 /** How an information panel lays out its sections. */
 export type PanelLayout = SectionsLayout;
+export interface PanelProps extends Omit<React.HTMLAttributes<HTMLElement>, "defaultValue"> {
+	/**
+	 * `tabs` (the default): a row of tabs, one section shown at a time. `accordion`: the
+	 * sections stacked as boxes, each opened by its heading, one always open.
+	 */
+	layout?: PanelLayout;
+	/** The tab shown, controlled (`tabs`). */
+	value?: string;
+	/**
+	 * The tab shown first (`tabs`), or the box open to start with (`accordion`). Default:
+	 * the first.
+	 */
+	defaultValue?: string;
+	/** Called with the tab chosen, or the box opened. */
+	onValueChange?: (value: string) => void;
+	/**
+	 * The panel can be closed: a close button appears in it. Closing from inside the panel
+	 * hands focus back to the control that opens it (whatever has `aria-controls` naming the
+	 * panel or an element around it), so focus is never left on something hidden.
+	 */
+	onClose?: () => void;
+	/**
+	 * The panel floats over the page: Escape inside it closes it too, and its close button
+	 * sits at its inner edge (the start, for a panel over the end of the page) rather than
+	 * the end of its first row. A panel docked beside the Body needs neither, and is
+	 * better without `onClose` at all: the toggle that opens it closes it.
+	 */
+	closeOnEscape?: boolean;
+	/**
+	 * The level of the sections' headings (`accordion`), one under the heading the panel
+	 * belongs to. The default sections' own headings are a level below them; tabs are not
+	 * headings, so there they start at this level. Default 3.
+	 */
+	headingLevel?: number;
+	/** The element to render. Default `aside`. */
+	as?: React.ElementType;
+	/**
+	 * Whether About's heading offers the downloads, by a Download button that lists the
+	 * `rendering` of the page in view and of the Manifest. Default `true`.
+	 */
+	download?: boolean;
+	/**
+	 * Where what the resource says of itself comes in several languages, About's heading
+	 * offers them, and the whole Root reads in the one chosen. Default `true`; `false`
+	 * leaves the choice out, and the Root reads in its `language`, else the reader's.
+	 */
+	languages?: boolean;
+	/**
+	 * Which of the default sections the panel may have, in Clover's own order: with
+	 * `["contents", "search"]` it has those two and no About. Each still shows only where
+	 * the resource has data for it, so a resource with none of them draws no panel at all.
+	 * `Tab` children win over it. Default: every section.
+	 */
+	sections?: readonly PanelSection[];
+	/**
+	 * What a default section's tab or heading says, in place of Clover's own word for it:
+	 * `{ annotations: "Chapters" }`, or `{ annotations: { en: "Chapters", de: "Kapitel" } }`
+	 * to say it in several, read in the one Clover speaks and marked with its language
+	 * where that is not the page's (WCAG 3.1.2). A `Tab` of your own says it in `label`.
+	 */
+	labels?: PanelSectionLabels;
+	/**
+	 * `Clover.Tab`s, the panel's sections whole, in their order: they win over `sections`.
+	 * Without any, the panel has the tabs Clover has data for: About,
+	 * Contents when the Manifest has Ranges, Search when it has a Content Search service, a
+	 * Map when it (or a Canvas or annotation) has navPlace or a georeference,
+	 * a Transcript when the view's media has captions or a plain-text transcript, and
+	 * Annotations when there are any.
+	 */
+	children?: React.ReactNode;
+}
 export type DefaultProps = Omit<RootProps, "children"> & {
 	/** The header over the Body: the resource's title and provider. Default `true`. */
 	header?: boolean;
@@ -661,6 +871,210 @@ export type GalleryProps = Omit<RootProps, "children"> & {
  * closes it, and focus returns to the cell.
  */
 export declare function Gallery({ className, size, height, gap, items, secondary, summary, lightboxItems, panel, defaultPanelOpen, panelLayout, panelSections, panelLabels, download, languages, storageKey, headingLevel, collapseControls, canvasOptions, style, ...root }: GalleryProps): React.JSX.Element;
+/**
+ * Focus that follows a control as it moves. A toggle drawn in one place while its pane is
+ * open and in another while it is shut is a new element after every press, and the one
+ * pressed goes with focus on it; focus is never left on what is gone or hidden (WCAG
+ * 2.4.3). Call the returned function, with a way to find the control, as the change that
+ * moves it is made. From the next frame, once the control is in its new place and focus
+ * has gone (with the element it was on, or the pane it was in), the control takes it.
+ * Frame by frame, not after a render: React may commit the move a render or more later
+ * (a Canvas draws its controls later still). If the reader puts focus somewhere of their
+ * own meanwhile, it is left there. A layout whose panes' toggles all move gives them one,
+ * so a later follow takes over from any before it: focus has one place to go.
+ */
+export declare function useFollowFocus(): (find: () => HTMLElement | null | undefined) => void;
+export type PanelPart = React.ComponentType<PanelProps>;
+export interface PanelPaneOptions {
+	/** The pane's `id`, which its toggle's `aria-controls` names. */
+	id: string;
+	/**
+	 * Whether there is room for it beside the Body (`useWideEnough`): `undefined` until
+	 * measured, and beside until then, as on the server.
+	 */
+	beside: boolean | undefined;
+	/** Whether it starts open beside the Body. Over the Body it always starts closed. */
+	defaultOpen: boolean;
+	/**
+	 * The Body's side it sits on, and slides in from over the Body: `"end"` (the default,
+	 * every template's) or `"start"`. `PanelPane` goes after the main `SplitPane` for the
+	 * end, and before it for the start (Mat, 2026-11-04: the Helpers page's Map example).
+	 */
+	side?: "start" | "end";
+	/** The layout's `useFollowFocus`, one for all its drawers. */
+	followFocus: ReturnType<typeof useFollowFocus>;
+	/**
+	 * The Body its toggle sits level with on the spine, its top measured as it moves
+	 * (`useSpineTop`): a title over it wrapping, the bar dragged. Without one, the toggle
+	 * sits the inset down from the spine's top, as the Body starts there.
+	 */
+	body?: () => HTMLElement | null | undefined;
+	/**
+	 * The sections the panel may have (`Clover.Panel`'s `sections`). Where the resource has
+	 * none of them the pane and its toggle are left out altogether, so a layout never keeps
+	 * room for a panel with nothing in it.
+	 */
+	sections?: readonly PanelSection[];
+	/**
+	 * The Panel, `Clover.Panel`, drawn at once, on the server too: Default's. Without it,
+	 * the pane loads the Panel's code itself (Mat, 2026-11-04: "always lazy if started
+	 * closed. not lazy if open"): at once where it starts open, and otherwise as the
+	 * reader reaches for its toggle (pointed at or focused), or on a first press, which
+	 * waits for it, then opens the panel whole, so focus has its section to go to.
+	 * Document's and the lightbox's, which start shut or out of sight.
+	 */
+	panel?: PanelPart;
+}
+/**
+ * The information panel beside the Body, one for every template (Mat, 2026-11-01: "an
+ * abstracted pane and not recreating the wheel for every template"): Default's, Document's
+ * and the Gallery's lightbox's. Its rule is `useDrawer`'s: beside the Body, a pane of its
+ * own past a bar that shares the width, where there is room for both; over the Body where
+ * there is not, sliding in, taking focus, and put away by Escape, its close button, a
+ * press on the Body beside it or a drag back off the end. Its toggle (`PanelToggle`) sits
+ * on the spine, the bar between them, while the panel is open beside the Body, and among
+ * the Body's controls otherwise, which the template places (`toggle`, while `!docked`): a
+ * press moves it, and focus follows it there. `PanelPane` draws the rest.
+ *
+ * The template's `Split` takes `splitProps`: where the panel is, Escape over the Body, and
+ * the reach that loads its code and the drag's.
+ */
+export declare function usePanelPane({ id, beside, defaultOpen, side, followFocus, body, sections, panel, }: PanelPaneOptions): {
+	id: string;
+	side: "start" | "end";
+	/** Open beside the Body: its bar and spine drawn, its toggle on the spine. */
+	docked: boolean;
+	spine: React.RefObject<HTMLDivElement | null>;
+	/** The toggle: the template draws it among the Body's controls while `!docked`. */
+	toggle: React.JSX.Element;
+	Part: PanelPart | undefined;
+	splitProps: {
+		"data-panel": string;
+		onKeyDown: (event: React.KeyboardEvent) => void;
+		onPointerOver: (event: React.SyntheticEvent) => void;
+		onFocus: (event: React.SyntheticEvent) => void;
+	};
+	pane: React.RefObject<HTMLElement | null>;
+	over: boolean;
+	open: boolean;
+	shown: boolean;
+	opened: boolean;
+	setOpen: (next: boolean) => void;
+	close: () => void;
+	onKeyDown: (event: React.KeyboardEvent) => void;
+	scrim: false | {
+		ref: React.RefObject<HTMLDivElement | null>;
+		"data-open": boolean;
+		"aria-hidden": boolean;
+		onMouseDown: (event: React.MouseEvent) => void;
+		onClick: () => void;
+	};
+};
+export type PanelPaneState = ReturnType<typeof usePanelPane>;
+/**
+ * The panel's side of a template's `Split`, after its main pane (before it, for the
+ * start side): while docked, the bar and the spine holding the toggle, between the two;
+ * the pane itself (`clover-template-panel`), its Panel given `onClose` and Escape while
+ * it floats over the Body; and, over the Body, the wash beside it. Nothing at all where the resource has none of the panel's sections: a
+ * template keeps no room, and no toggle, for a panel that would draw nothing. Its look is
+ * written once, in `Default.css`, which `styles.css` carries.
+ */
+export declare function PanelPane({ pane, className, ...panel }: {
+	pane: PanelPaneState;
+	className?: string;
+} & Omit<PanelProps, "onClose" | "closeOnEscape">): React.JSX.Element | null;
+export interface DrawerOptions {
+	/** The pane's `id`, which its toggle's `aria-controls` names. */
+	id: string;
+	/**
+	 * Whether there is room for it beside the page (`useWideEnough`): `undefined` until
+	 * measured, and beside until then, as on the server.
+	 */
+	beside: boolean | undefined;
+	/** Whether it starts open beside the page. Over the page it always starts closed. */
+	defaultOpen: boolean;
+	/** The edge it floats from over the page, and is dragged back to. */
+	side: "start" | "end";
+	/** Where focus goes as the reader opens it over the page. Default: the panel's. */
+	focus?: (pane: HTMLElement) => HTMLElement | null | undefined;
+	/** Over the page it slides in and out; `false`, it simply shows and hides. */
+	slides?: boolean;
+	/** What sits on its edge and moves with it as it is dragged (its toggle, on its spine). */
+	alongside?: React.RefObject<HTMLElement | null>;
+	/**
+	 * The layout's `useFollowFocus`, one for all its drawers, so that a later follow takes
+	 * over from any before it.
+	 */
+	followFocus: ReturnType<typeof useFollowFocus>;
+}
+/**
+ * A pane beside the page where there is room, and a drawer over it where there is not:
+ * Document's panel and thumbnails. One rule (Mat, 2026-10-27), which Default's panel
+ * follows in its own code (one drawer; through this hook it would weigh more):
+ *
+ * - Beside the page it opens as the host asks, then as the reader chooses.
+ * - Over the page it starts closed, whatever the host asks, and closes as the layout
+ *   narrows under it: open, it would cover what the reader came for, focus behind it
+ *   (WCAG 2.4.11). Focus in it goes to its toggle. Widening brings it back beside.
+ * - Opened over the page, it takes focus (`focus`). Escape anywhere, a press on the wash
+ *   beside it, a drag back off the way it came or its toggle puts it away, and focus in
+ *   it goes to its toggle; focus elsewhere is left where it is.
+ *
+ * Its toggle is the button whose `aria-controls` names it. A toggle the template draws
+ * in another place as the pane opens or closes is followed there (`useFollowFocus`).
+ */
+export declare function useDrawer({ id, beside: measured, defaultOpen, side, focus, slides, alongside, followFocus, }: DrawerOptions): {
+	pane: React.RefObject<HTMLElement | null>;
+	/** Over the page, where there is no room beside it. */
+	over: boolean;
+	open: boolean;
+	/** In the layout: open, or over the page still sliding out. Its pane's `hidden` is `!shown`. */
+	shown: boolean;
+	/** Open and, over the page, slid in: its pane's `data-open`. */
+	opened: boolean;
+	setOpen: (next: boolean) => void;
+	close: () => void;
+	/** For the layout's `onKeyDown`: Escape anywhere puts it away over the page. */
+	onKeyDown: (event: React.KeyboardEvent) => void;
+	scrim: false | {
+		ref: React.RefObject<HTMLDivElement | null>;
+		"data-open": boolean;
+		"aria-hidden": boolean;
+		onMouseDown: (event: React.MouseEvent) => void;
+		onClick: () => void;
+	};
+};
+/**
+ * Starts loading the drag's code as the reader reaches for a floating pane's toggle
+ * (pointed at, pressed or focused; Mat, 2026-10-31), so it is there as the pane opens: a
+ * swipe right after is never missed while it loads. A layout whose panes sit beside the
+ * page never calls it.
+ */
+export declare function preloadDrag(): void;
+/**
+ * The narrowest the page (Default's Body, Document's pages) and the panel may be dragged,
+ * side by side: one pair for both templates, so their layouts never drift apart.
+ */
+export declare const PAGE_MIN = "16rem";
+export declare const PANEL_MIN = "14rem";
+/**
+ * The room the two need beside each other: their minimums and the bar between them. Any
+ * narrower (a phone) and the panel slides over the page instead.
+ */
+export declare const BESIDE_REM: number;
+/**
+ * Whether `element` is at least `rem` wide: measured before paint, and again whenever it
+ * resizes. Its own width, not the window's, so a layout in a narrow column of a wide page
+ * still knows it is narrow. `undefined` until measured (on the server, or with no layout
+ * yet), so the first measure is never mistaken for the layout narrowing or widening.
+ */
+export declare function useWideEnough(element: React.RefObject<HTMLElement | null>, rem: number): boolean | undefined;
+/**
+ * Starts loading the lightbox's view before it is first opened: as the reader's pointer or
+ * focus first comes to the layout, so the Body is there, or nearly, by the time they open
+ * a view.
+ */
+export declare const preloadLightbox: () => undefined;
 export interface LightboxProps {
 	open: boolean;
 	onClose: () => void;
@@ -703,6 +1117,18 @@ export interface LightboxProps {
 	collapseControls?: "auto" | "always";
 	/** The Body's Canvas `options`: its gestures, zoom limits and motion. */
 	canvasOptions?: CloverCanvasOptions;
+	/**
+	 * The Body's `placeholder`: a Canvas's `placeholderContainer` first (the default), or,
+	 * `false`, the Canvas itself at once.
+	 */
+	placeholder?: boolean;
+	/**
+	 * The current Canvas's label under the Body. Default `true`; `false` leaves it out, as
+	 * a single image with its caption beside it on the page needs no second one (Mat,
+	 * 2026-11-04: "remove canvas label"). The dialog is named by the Manifest's label all
+	 * the same, or the Canvas's where there is none.
+	 */
+	caption?: boolean;
 	className?: string;
 }
 /**
@@ -733,5 +1159,12 @@ export interface LightboxProps {
  * loads as it opens, the chunk Document's is (`PanelPart`).
  */
 export declare function Lightbox({ open, onClose, headingLevel, items, className, ...view }: LightboxProps): React.JSX.Element;
+/**
+ * The annotations given as the Root's content (`addedSets` marked `content`), walked as
+ * one whole (`useAnnotationCollection`); null where the content is a Manifest or a
+ * Collection, even one whose pages are part of an AnnotationCollection. The lightbox
+ * reads it too, to step through them and to name where Back goes.
+ */
+export declare function useGivenAnnotations(): AnnotationCollection | null;
 
 export {};

package/dist/templates/index.mjs

@@ -2,10 +2,27 @@
 import { Default } from "./default/Default.mjs";
 import { Document } from "./document/Document.mjs";
 import { Gallery } from "./gallery/Gallery.mjs";
-import { Lightbox } from "./shared/Lightbox.mjs";
+import { PanelPane, usePanelPane } from "./shared/PanelPane.mjs";
+import { useDrawer } from "./shared/useDrawer.mjs";
+import { preloadDrag } from "./shared/useDragToClose.mjs";
+import { useFollowFocus } from "./shared/useFollowFocus.mjs";
+import { BESIDE_REM, PAGE_MIN, PANEL_MIN, useWideEnough } from "./shared/useSlide.mjs";
+import { Lightbox, preloadLightbox } from "./shared/Lightbox.mjs";
+import { useGivenAnnotations } from "./shared/givenAnnotations.mjs";
 export {
+  BESIDE_REM,
   Default,
   Document,
   Gallery,
-  Lightbox
+  Lightbox,
+  PAGE_MIN,
+  PANEL_MIN,
+  PanelPane,
+  preloadDrag,
+  preloadLightbox,
+  useDrawer,
+  useFollowFocus,
+  useGivenAnnotations,
+  usePanelPane,
+  useWideEnough
 };

package/dist/templates/shared/LightboxView.mjs

@@ -1,8 +1,7 @@
 "use client";
 import { jsxs, jsx } from "react/jsx-runtime";
 import { useRef, useEffect } from "react";
-import { PanelPane } from "./PanelPane.mjs";
-import { useLazyPanelPane } from "./useLazyPanelPane.mjs";
+import { usePanelPane, PanelPane } from "./PanelPane.mjs";
 import { useFollowFocus } from "./useFollowFocus.mjs";
 import { useWideEnough, BESIDE_REM, PAGE_MIN } from "./useSlide.mjs";
 import { Split, SplitPane } from "../../components/Split/Split.mjs";
@@ -23,7 +22,9 @@ function LightboxView({
   languages = true,
   storageKey,
   collapseControls,
-  canvasOptions
+  canvasOptions,
+  placeholder,
+  caption = true
 }) {
   const panes = useRef(null);
   useEffect(() => {
@@ -50,7 +51,7 @@ function LightboxView({
     observer.observe(dialog, { childList: true, subtree: true });
     return () => observer.disconnect();
   }, []);
-  const pane = useLazyPanelPane({
+  const pane = usePanelPane({
     id: `${id}-panel`,
     beside: useWideEnough(panes, BESIDE_REM),
     defaultOpen: defaultPanelOpen,
@@ -83,10 +84,11 @@ function LightboxView({
                   className: "clover-template-lightbox-body",
                   collapseControls,
                   options: canvasOptions,
+                  placeholder,
                   children: panel && !pane.docked && pane.toggle
                 }
               ),
-              /* @__PURE__ */ jsx(
+              caption && /* @__PURE__ */ jsx(
                 Label,
                 {
                   of: "canvas",

package/dist/templates/shared/PanelPane.mjs

@@ -1,6 +1,6 @@
 "use client";
-import { jsx, jsxs, Fragment } from "react/jsx-runtime";
-import { useRef } from "react";
+import { jsxs, Fragment, jsx } from "react/jsx-runtime";
+import { useRef, useState, useEffect } from "react";
 import { preloadDrag } from "./useDragToClose.mjs";
 import { useDrawer } from "./useDrawer.mjs";
 import { PANEL_MIN } from "./useSlide.mjs";
@@ -8,31 +8,38 @@ import { useSpineTop } from "./useSpine.mjs";
 import { usePanelSections } from "../../components/Panel/sections.mjs";
 import { SplitHandle, SplitPane } from "../../components/Split/Split.mjs";
 import { PanelToggle } from "../../components/Panel/PanelToggle.mjs";
+const loadPanel = () => import("./PanelPart.mjs");
 function usePanelPane({
   id,
   beside,
   defaultOpen,
+  side = "end",
   followFocus,
   body,
   sections,
-  panel,
-  load
+  panel
 }) {
   const drawer = useDrawer({
     id,
     beside,
     defaultOpen,
-    side: "end",
+    side,
     followFocus
   });
   const docked = !drawer.over && drawer.open;
   const spine = useRef(null);
+  const [loaded, setLoaded] = useState();
+  const Part = panel ?? loaded;
+  const load = () => loadPanel().then((module) => setLoaded(() => module.default));
+  useEffect(() => {
+    if (drawer.open && !Part) void load();
+  }, [drawer.open]);
   useSpineTop(spine, () => body == null ? void 0 : body(), docked && Boolean(body));
   const reach = (event) => {
     var _a, _b;
     if (!((_b = (_a = event.target).closest) == null ? void 0 : _b.call(_a, `[aria-controls~="${id}"]`)))
       return;
-    if (!panel) void (load == null ? void 0 : load());
+    if (!Part) void load();
     if (drawer.over) preloadDrag();
   };
   const toggle = /* @__PURE__ */ jsx(
@@ -40,19 +47,21 @@ function usePanelPane({
     {
       sections,
       open: drawer.open,
-      onOpenChange: (next) => next && !panel && load ? load().then(() => drawer.setOpen(true)) : drawer.setOpen(next),
-      controls: id
+      onOpenChange: (next) => next && !Part ? load().then(() => drawer.setOpen(true)) : drawer.setOpen(next),
+      controls: id,
+      side
     }
   );
   return {
     ...drawer,
     id,
+    side,
     /** Open beside the Body: its bar and spine drawn, its toggle on the spine. */
     docked,
     spine,
     /** The toggle: the template draws it among the Body's controls while `!docked`. */
     toggle,
-    Part: panel,
+    Part,
     splitProps: {
       "data-panel": drawer.over ? "over" : "beside",
       onKeyDown: drawer.onKeyDown,
@@ -72,24 +81,28 @@ function PanelPane({
   className,
   ...panel
 }) {
-  const { id, over, docked, Part } = pane;
+  const { id, over, docked, side, Part } = pane;
   const offered = usePanelSections(panel.sections);
   if (!offered.length) return null;
-  return /* @__PURE__ */ jsxs(Fragment, { children: [
-    docked && /* @__PURE__ */ jsx(
+  const bar = docked && /* @__PURE__ */ jsxs(Fragment, { children: [
+    /* @__PURE__ */ jsx(
       SplitHandle,
       {
         className: "clover-template-panel-handle",
         "aria-controls": id
       }
     ),
-    docked && /* @__PURE__ */ jsx("div", { ref: pane.spine, className: "clover-template-spine", children: pane.toggle }),
+    /* @__PURE__ */ jsx("div", { ref: pane.spine, className: "clover-template-spine", children: pane.toggle })
+  ] });
+  return /* @__PURE__ */ jsxs(Fragment, { children: [
+    side === "end" && bar,
     /* @__PURE__ */ jsx(
       SplitPane,
       {
         ref: pane.pane,
         id,
         "data-spine": over || void 0,
+        "data-side": side,
         name: "panel",
         "data-about": offered.includes("about") || void 0,
         className: ["clover-template-panel clover-template-drawer", className].filter(Boolean).join(" "),
@@ -107,6 +120,7 @@ function PanelPane({
         )
       }
     ),
+    side === "start" && bar,
     pane.scrim && /* @__PURE__ */ jsx("div", { className: "clover-template-scrim", ...pane.scrim })
   ] });
 }