@gallerist/renderer-dom 0.0.0-stage → 0.3.1

package/dist/index.d.cts

@@ -0,0 +1,252 @@
+import { MediaAdapter, OverlaySpec, Group, ViewerApi, ViewerOptions, Collection } from '@gallerist/core';
+export { KeyReconcile, reconcileKeys, windowIndices } from '@gallerist/core/internal';
+
+declare function imageAdapter(): MediaAdapter;
+
+/** Visual skin. `gallery` ships in gallerist.css; `console` and `editorial` need their stylesheet
+ *  (console.css, editorial.css) loaded after it. */
+type Skin = 'gallery' | 'console' | 'editorial' | (string & {});
+/** Accents are named per skin. Gallery: periwinkle (default), mint, amber, vermilion. Console:
+ *  amber (default), cyan, vermilion. Editorial: vermilion (default), cobalt. A name the skin
+ *  doesn't know falls back to its default. */
+type Accent = 'periwinkle' | 'mint' | 'amber' | 'cyan' | 'vermilion' | 'cobalt' | (string & {});
+/** `auto` follows the system's `prefers-color-scheme`. Unset, each skin uses its own default:
+ *  Gallery and Console dark, Editorial the light wall. */
+type ColorScheme = 'dark' | 'light' | 'auto';
+interface Appearance {
+    skin?: Skin;
+    accent?: Accent;
+    scheme?: ColorScheme;
+}
+/**
+ * Write an appearance onto a viewer root (`data-gallerist-skin|accent|scheme`). Only the options
+ * present in `appearance` change, so `applyAppearance(root, { accent: 'cyan' })` keeps the skin and
+ * scheme; an option present but `undefined` goes back to its default (`gallery`, the skin's own
+ * scheme and accent).
+ */
+declare function applyAppearance(root: HTMLElement, appearance: Appearance): void;
+
+type PresetName = 'filmstrip' | 'immersive' | 'reviewer' | 'contact' | 'editorial' | 'tour';
+type ResolvedPreset = {
+    /** data-* attributes the renderer sets on the root (drives the theme). */
+    readonly rootAttrs: Readonly<Record<string, string>>;
+    /** default arrow placement (overridable by an explicit mount option). */
+    readonly arrows: ArrowLayout;
+    /** default chrome auto-hide-on-idle (overridable). */
+    readonly autoHide: boolean;
+    /** default thumbnail rail placement (overridable). */
+    readonly rail: RailPlacement;
+    /** thumbnails() defaults: the plugin applies them to the options it wasn't given. */
+    readonly thumbnails: Readonly<{
+        itemAxis: 'vertical' | 'horizontal';
+        groupDisplay?: 'stacked' | 'flat' | 'index';
+        timeline?: boolean;
+        numberItems?: boolean;
+    }>;
+    /** turn on the zoom navigator by default (overridable). */
+    readonly navigator?: boolean;
+    /** frame the media (overridable). */
+    readonly frame?: boolean;
+    /** default item indicator (overridable). */
+    readonly itemIndicator?: ItemIndicator;
+    /** which arrow keys and on-screen arrows move between groups, if not the rail's own (overridable). */
+    readonly groupAxis?: GroupAxis;
+    /** name the group arrows after the group they go to (overridable). */
+    readonly arrowLabels?: boolean;
+};
+/** Resolve a preset name to its layout config; unknown names warn (dev) and fall back to `filmstrip`. */
+declare function resolvePreset(name: string): ResolvedPreset;
+
+interface Strings {
+    /** accessible name of the overlay dialog (the `label` mount option still wins) */
+    dialog: string;
+    /** role description announced for an inline viewer */
+    carousel: string;
+    close: string;
+    previous: string;
+    next: string;
+    previousItem: string;
+    nextItem: string;
+    /** name of a labelled group arrow (`arrowLabels`), given the group it goes to */
+    previousTo: (name: string) => string;
+    nextTo: (name: string) => string;
+    resetZoom: string;
+    showThumbnails: string;
+    hideThumbnails: string;
+    /** name of a caption renderer's band while it scrolls (it then takes focus, to scroll by keyboard) */
+    caption: string;
+    /** label of an item pill in the position indicator */
+    item: (n: number) => string;
+    /** announced on group navigation, e.g. "Group 2 of 12" */
+    groupOf: (n: number, total: number) => string;
+    /** announced on item navigation (and for every item in linear mode), e.g. "Item 3 of 5" */
+    itemOf: (n: number, total: number) => string;
+}
+declare const DEFAULT_STRINGS: Strings;
+
+type ItemIndicator = 'pills' | 'dots' | 'counter' | 'placard';
+interface MountOptions {
+    /** null/undefined → overlay (portal to body); element → inline. */
+    container?: HTMLElement | null;
+    controls?: boolean;
+    adapters?: MediaAdapter[];
+    preload?: {
+        ahead: number;
+        behind: number;
+    };
+    /** global overlays applied to every slide (spec §8.1, §9). */
+    overlays?: OverlaySpec[];
+    /**
+     * Placement of the within-group ↑/↓ arrows, surfaced as `data-gallerist-arrows` for the theme
+     * (UX-D). `pill-right` (default): ←/→ on the side edges, ↑/↓ as a stacked pill at right-center.
+     * `corner-br`: ↑/↓ paired bottom-right. `dpad`: all four clustered as a d-pad. `split`: legacy
+     * ↑/↓ top/bottom-center. `docked` (the `reviewer` preset): nothing over the media — the group
+     * arrows sit in gutters beside the stage, and the item navigator (↑ · `n / N` · ↓) docks as a
+     * header on the aside item column when it shows, else at the end of the caption row.
+     */
+    arrows?: ArrowLayout;
+    /**
+     * Auto-hide the chrome after a period of inactivity (UX-C), flagged as `data-gallerist-idle` for
+     * the theme. Default true; inert under prefers-reduced-motion. The thumbnail rail collapses
+     * separately (the `t` key / toggle button / fullscreen), tracked as `data-gallerist-rail`.
+     */
+    autoHide?: boolean;
+    /**
+     * Named layout preset (UX-E) — sets `data-gallerist-preset` and supplies defaults for `arrows` and
+     * `autoHide` (both still overridable by explicit options above). Plugin regions get the preset
+     * too: thumbnails() takes `resolvePreset(name).thumbnails` for the options it wasn't given.
+     */
+    preset?: PresetName;
+    /**
+     * Thumbnail rail placement (UX-E), surfaced as `data-gallerist-rail-pos`. `bottom` (default) keeps
+     * the rail horizontal (group axis = ←/→); `left` / `right` run it vertically and remap the
+     * keys/arrows (group axis = ↑/↓, items = ←/→ — touch swipes stay conventional); `hidden` starts
+     * collapsed (reveal with the toggle / `t` / hover). Overridable; presets supply a default.
+     */
+    rail?: RailPlacement;
+    /**
+     * Linear traversal: ←/→ walk the flattened item sequence across groups (1a, 1b, 2a, 2b, 2c, 3a…),
+     * ↑/↓ retire, the counter shows `item N / total`, and the within-group pills hide — surfaced as
+     * `data-gallerist-linear`. Unset, it follows the rail: on while the `thumbnails` region holds an
+     * element marked `data-gallerist-linear` (a flat rail, `thumbnails({ groupDisplay: 'flat' })`,
+     * marks its region so), off otherwise, and it changes when the plugins do. `true` or `false`
+     * fixes it.
+     */
+    linear?: boolean;
+    /**
+     * Whether navigation wraps at the ends (mirror of the core `loop` option). Only consulted for
+     * `linear` traversal, to wrap the flattened sequence at the global first/last item. Default false.
+     */
+    loop?: boolean;
+    /** UI text overrides (button labels, announcements) for translation; merged over English. */
+    strings?: Partial<Strings>;
+    /**
+     * How the position within a multi-item group is shown, surfaced as the indicator's `data-mode`.
+     * `pills` (default): numbered pills up to 8 items, then `n / N`. `dots`: plain dots with the
+     * `n / N` count, up to 12 items, then the count alone. `counter`: always `n / N`. `placard`: the
+     * whole item navigator (↑ · ticks · `n / N` · ↓) moves into the caption, which becomes a label
+     * beside the work in the `editorial` preset. On a touch screen the theme shows the count only
+     * (swipes navigate).
+     */
+    itemIndicator?: ItemIndicator;
+    /**
+     * Visual skin (`data-gallerist-skin`, default `gallery`). Other skins need their stylesheet loaded
+     * after gallerist.css, e.g. `@gallerist/theme-default/console.css` for `console`.
+     */
+    skin?: Skin;
+    /** The skin's accent by name (`data-gallerist-accent`); unset uses the skin's default. */
+    accent?: Accent;
+    /** `dark`, `light`, or `auto` to follow the system (`data-gallerist-scheme`); unset, the skin's
+     *  own default (Gallery and Console dark, Editorial light). */
+    scheme?: ColorScheme;
+    /**
+     * Zoom navigator: while zoomed in, a minimap of the image in the stage's bottom corner with a box
+     * for the visible part; click or drag it to move around. Default off (the `reviewer` preset turns
+     * it on). Part of the built-in controls, so `controls: false` has none.
+     */
+    navigator?: boolean;
+    /**
+     * Framed media: the image hangs inside the stage with room around it (the skin's
+     * `--gallerist-frame-inset`), and the media element is sized to the image itself so a skin can
+     * give it a mat and a shadow. Zoom bounds, overlays and pins follow the framed box. Default off
+     * (the `editorial` preset turns it on).
+     */
+    frame?: boolean;
+    /**
+     * Which arrow keys and on-screen arrows move between groups. Default: follows the rail (`horizontal`
+     * with a bottom rail, `vertical` with a side rail). The `tour` preset keeps `horizontal` beside a
+     * side rail, so ←/→ moves between sections while ↑/↓ moves within one.
+     */
+    groupAxis?: GroupAxis;
+    /**
+     * Name the group arrows after the group they go to: `true` uses `group.caption`, a function returns
+     * the label. Needs horizontal group arrows in the `pill-right` layout; otherwise ignored. The name
+     * also goes into the arrow's accessible name (`strings.previousTo` / `nextTo`).
+     */
+    arrowLabels?: boolean | ((group: Group, index: number) => string | undefined);
+    /** Accessible name for the overlay dialog (default 'Media viewer'); sets aria-label. */
+    label?: string;
+    /** Element (or getter) to return focus to when the overlay closes. Falls back to whatever
+     *  had focus when it opened — useful when the trigger lives in a tree that may have unmounted. */
+    returnFocus?: HTMLElement | (() => HTMLElement | null);
+}
+type ArrowLayout = 'pill-right' | 'corner-br' | 'dpad' | 'split' | 'docked';
+type RailPlacement = 'bottom' | 'hidden' | 'left' | 'right';
+type GroupAxis = 'horizontal' | 'vertical';
+interface RendererHandle {
+    root: HTMLElement;
+    destroy(): void;
+}
+declare function mount(viewer: ViewerApi, opts?: MountOptions): RendererHandle;
+
+type PerGallery<T> = T | ((gallery: string) => T);
+interface BindOptions {
+    /** which elements are links (default `[data-gallerist]`). */
+    selector?: string;
+    /** where to look for them (default `document`). */
+    root?: Document | HTMLElement;
+    /**
+     * `createViewer` options besides the collection (`plugins`, `loop`…), or a function returning a set
+     * per gallery. With several galleries use the function for `pins()`, which holds its state on the
+     * plugin and so can't be shared between viewers.
+     */
+    viewer?: PerGallery<Omit<ViewerOptions, 'collection' | 'groups' | 'items'>>;
+    /** `mount` options (`preset`, `skin`…), or one set per gallery. */
+    mount?: PerGallery<MountOptions>;
+}
+interface BindHandle {
+    /** open a gallery from code, at its first item or the one given. */
+    open(gallery?: string, at?: {
+        g?: number;
+        i?: number;
+    }): void;
+    /** the gallery's viewer, once it has been opened. */
+    viewer(gallery?: string): ViewerApi | undefined;
+    /** stop listening and destroy every viewer. */
+    destroy(): void;
+}
+interface LinkCollection {
+    collection: Collection;
+    /** where each link landed */
+    positions: Map<Element, {
+        g: number;
+        i: number;
+    }>;
+}
+/**
+ * Build a collection from link elements. A link with `data-gallerist-group` joins the group of that
+ * id, in first-seen order (named by `-group-caption`, with `-group-subtitle` in its meta); any other
+ * link is a group of its own. Elements with neither a `data-gallerist-src` nor an `href` are skipped.
+ */
+declare function collectionFromLinks(links: Iterable<Element>, idPrefix?: string): LinkCollection;
+/**
+ * Open a viewer from `data-gallerist` links. Each distinct attribute value is its own gallery. A plain
+ * click opens the viewer at that link; a modified click (new tab, download) stays the browser's.
+ */
+declare function bind(opts?: BindOptions): BindHandle;
+
+/** Package version, injected from package.json at build (tsup `define`). Guarded with `typeof` so
+ *  importing the source without the define (e2e / example fixtures) yields a dev marker, not a crash. */
+declare const VERSION: string;
+
+export { type Accent, type Appearance, type ArrowLayout, type BindHandle, type BindOptions, type ColorScheme, DEFAULT_STRINGS, type GroupAxis, type ItemIndicator, type MountOptions, type PresetName, type RailPlacement, type RendererHandle, type ResolvedPreset, type Skin, type Strings, VERSION, applyAppearance, bind, collectionFromLinks, imageAdapter, mount, resolvePreset };

package/dist/index.d.ts

@@ -0,0 +1,252 @@
+import { MediaAdapter, OverlaySpec, Group, ViewerApi, ViewerOptions, Collection } from '@gallerist/core';
+export { KeyReconcile, reconcileKeys, windowIndices } from '@gallerist/core/internal';
+
+declare function imageAdapter(): MediaAdapter;
+
+/** Visual skin. `gallery` ships in gallerist.css; `console` and `editorial` need their stylesheet
+ *  (console.css, editorial.css) loaded after it. */
+type Skin = 'gallery' | 'console' | 'editorial' | (string & {});
+/** Accents are named per skin. Gallery: periwinkle (default), mint, amber, vermilion. Console:
+ *  amber (default), cyan, vermilion. Editorial: vermilion (default), cobalt. A name the skin
+ *  doesn't know falls back to its default. */
+type Accent = 'periwinkle' | 'mint' | 'amber' | 'cyan' | 'vermilion' | 'cobalt' | (string & {});
+/** `auto` follows the system's `prefers-color-scheme`. Unset, each skin uses its own default:
+ *  Gallery and Console dark, Editorial the light wall. */
+type ColorScheme = 'dark' | 'light' | 'auto';
+interface Appearance {
+    skin?: Skin;
+    accent?: Accent;
+    scheme?: ColorScheme;
+}
+/**
+ * Write an appearance onto a viewer root (`data-gallerist-skin|accent|scheme`). Only the options
+ * present in `appearance` change, so `applyAppearance(root, { accent: 'cyan' })` keeps the skin and
+ * scheme; an option present but `undefined` goes back to its default (`gallery`, the skin's own
+ * scheme and accent).
+ */
+declare function applyAppearance(root: HTMLElement, appearance: Appearance): void;
+
+type PresetName = 'filmstrip' | 'immersive' | 'reviewer' | 'contact' | 'editorial' | 'tour';
+type ResolvedPreset = {
+    /** data-* attributes the renderer sets on the root (drives the theme). */
+    readonly rootAttrs: Readonly<Record<string, string>>;
+    /** default arrow placement (overridable by an explicit mount option). */
+    readonly arrows: ArrowLayout;
+    /** default chrome auto-hide-on-idle (overridable). */
+    readonly autoHide: boolean;
+    /** default thumbnail rail placement (overridable). */
+    readonly rail: RailPlacement;
+    /** thumbnails() defaults: the plugin applies them to the options it wasn't given. */
+    readonly thumbnails: Readonly<{
+        itemAxis: 'vertical' | 'horizontal';
+        groupDisplay?: 'stacked' | 'flat' | 'index';
+        timeline?: boolean;
+        numberItems?: boolean;
+    }>;
+    /** turn on the zoom navigator by default (overridable). */
+    readonly navigator?: boolean;
+    /** frame the media (overridable). */
+    readonly frame?: boolean;
+    /** default item indicator (overridable). */
+    readonly itemIndicator?: ItemIndicator;
+    /** which arrow keys and on-screen arrows move between groups, if not the rail's own (overridable). */
+    readonly groupAxis?: GroupAxis;
+    /** name the group arrows after the group they go to (overridable). */
+    readonly arrowLabels?: boolean;
+};
+/** Resolve a preset name to its layout config; unknown names warn (dev) and fall back to `filmstrip`. */
+declare function resolvePreset(name: string): ResolvedPreset;
+
+interface Strings {
+    /** accessible name of the overlay dialog (the `label` mount option still wins) */
+    dialog: string;
+    /** role description announced for an inline viewer */
+    carousel: string;
+    close: string;
+    previous: string;
+    next: string;
+    previousItem: string;
+    nextItem: string;
+    /** name of a labelled group arrow (`arrowLabels`), given the group it goes to */
+    previousTo: (name: string) => string;
+    nextTo: (name: string) => string;
+    resetZoom: string;
+    showThumbnails: string;
+    hideThumbnails: string;
+    /** name of a caption renderer's band while it scrolls (it then takes focus, to scroll by keyboard) */
+    caption: string;
+    /** label of an item pill in the position indicator */
+    item: (n: number) => string;
+    /** announced on group navigation, e.g. "Group 2 of 12" */
+    groupOf: (n: number, total: number) => string;
+    /** announced on item navigation (and for every item in linear mode), e.g. "Item 3 of 5" */
+    itemOf: (n: number, total: number) => string;
+}
+declare const DEFAULT_STRINGS: Strings;
+
+type ItemIndicator = 'pills' | 'dots' | 'counter' | 'placard';
+interface MountOptions {
+    /** null/undefined → overlay (portal to body); element → inline. */
+    container?: HTMLElement | null;
+    controls?: boolean;
+    adapters?: MediaAdapter[];
+    preload?: {
+        ahead: number;
+        behind: number;
+    };
+    /** global overlays applied to every slide (spec §8.1, §9). */
+    overlays?: OverlaySpec[];
+    /**
+     * Placement of the within-group ↑/↓ arrows, surfaced as `data-gallerist-arrows` for the theme
+     * (UX-D). `pill-right` (default): ←/→ on the side edges, ↑/↓ as a stacked pill at right-center.
+     * `corner-br`: ↑/↓ paired bottom-right. `dpad`: all four clustered as a d-pad. `split`: legacy
+     * ↑/↓ top/bottom-center. `docked` (the `reviewer` preset): nothing over the media — the group
+     * arrows sit in gutters beside the stage, and the item navigator (↑ · `n / N` · ↓) docks as a
+     * header on the aside item column when it shows, else at the end of the caption row.
+     */
+    arrows?: ArrowLayout;
+    /**
+     * Auto-hide the chrome after a period of inactivity (UX-C), flagged as `data-gallerist-idle` for
+     * the theme. Default true; inert under prefers-reduced-motion. The thumbnail rail collapses
+     * separately (the `t` key / toggle button / fullscreen), tracked as `data-gallerist-rail`.
+     */
+    autoHide?: boolean;
+    /**
+     * Named layout preset (UX-E) — sets `data-gallerist-preset` and supplies defaults for `arrows` and
+     * `autoHide` (both still overridable by explicit options above). Plugin regions get the preset
+     * too: thumbnails() takes `resolvePreset(name).thumbnails` for the options it wasn't given.
+     */
+    preset?: PresetName;
+    /**
+     * Thumbnail rail placement (UX-E), surfaced as `data-gallerist-rail-pos`. `bottom` (default) keeps
+     * the rail horizontal (group axis = ←/→); `left` / `right` run it vertically and remap the
+     * keys/arrows (group axis = ↑/↓, items = ←/→ — touch swipes stay conventional); `hidden` starts
+     * collapsed (reveal with the toggle / `t` / hover). Overridable; presets supply a default.
+     */
+    rail?: RailPlacement;
+    /**
+     * Linear traversal: ←/→ walk the flattened item sequence across groups (1a, 1b, 2a, 2b, 2c, 3a…),
+     * ↑/↓ retire, the counter shows `item N / total`, and the within-group pills hide — surfaced as
+     * `data-gallerist-linear`. Unset, it follows the rail: on while the `thumbnails` region holds an
+     * element marked `data-gallerist-linear` (a flat rail, `thumbnails({ groupDisplay: 'flat' })`,
+     * marks its region so), off otherwise, and it changes when the plugins do. `true` or `false`
+     * fixes it.
+     */
+    linear?: boolean;
+    /**
+     * Whether navigation wraps at the ends (mirror of the core `loop` option). Only consulted for
+     * `linear` traversal, to wrap the flattened sequence at the global first/last item. Default false.
+     */
+    loop?: boolean;
+    /** UI text overrides (button labels, announcements) for translation; merged over English. */
+    strings?: Partial<Strings>;
+    /**
+     * How the position within a multi-item group is shown, surfaced as the indicator's `data-mode`.
+     * `pills` (default): numbered pills up to 8 items, then `n / N`. `dots`: plain dots with the
+     * `n / N` count, up to 12 items, then the count alone. `counter`: always `n / N`. `placard`: the
+     * whole item navigator (↑ · ticks · `n / N` · ↓) moves into the caption, which becomes a label
+     * beside the work in the `editorial` preset. On a touch screen the theme shows the count only
+     * (swipes navigate).
+     */
+    itemIndicator?: ItemIndicator;
+    /**
+     * Visual skin (`data-gallerist-skin`, default `gallery`). Other skins need their stylesheet loaded
+     * after gallerist.css, e.g. `@gallerist/theme-default/console.css` for `console`.
+     */
+    skin?: Skin;
+    /** The skin's accent by name (`data-gallerist-accent`); unset uses the skin's default. */
+    accent?: Accent;
+    /** `dark`, `light`, or `auto` to follow the system (`data-gallerist-scheme`); unset, the skin's
+     *  own default (Gallery and Console dark, Editorial light). */
+    scheme?: ColorScheme;
+    /**
+     * Zoom navigator: while zoomed in, a minimap of the image in the stage's bottom corner with a box
+     * for the visible part; click or drag it to move around. Default off (the `reviewer` preset turns
+     * it on). Part of the built-in controls, so `controls: false` has none.
+     */
+    navigator?: boolean;
+    /**
+     * Framed media: the image hangs inside the stage with room around it (the skin's
+     * `--gallerist-frame-inset`), and the media element is sized to the image itself so a skin can
+     * give it a mat and a shadow. Zoom bounds, overlays and pins follow the framed box. Default off
+     * (the `editorial` preset turns it on).
+     */
+    frame?: boolean;
+    /**
+     * Which arrow keys and on-screen arrows move between groups. Default: follows the rail (`horizontal`
+     * with a bottom rail, `vertical` with a side rail). The `tour` preset keeps `horizontal` beside a
+     * side rail, so ←/→ moves between sections while ↑/↓ moves within one.
+     */
+    groupAxis?: GroupAxis;
+    /**
+     * Name the group arrows after the group they go to: `true` uses `group.caption`, a function returns
+     * the label. Needs horizontal group arrows in the `pill-right` layout; otherwise ignored. The name
+     * also goes into the arrow's accessible name (`strings.previousTo` / `nextTo`).
+     */
+    arrowLabels?: boolean | ((group: Group, index: number) => string | undefined);
+    /** Accessible name for the overlay dialog (default 'Media viewer'); sets aria-label. */
+    label?: string;
+    /** Element (or getter) to return focus to when the overlay closes. Falls back to whatever
+     *  had focus when it opened — useful when the trigger lives in a tree that may have unmounted. */
+    returnFocus?: HTMLElement | (() => HTMLElement | null);
+}
+type ArrowLayout = 'pill-right' | 'corner-br' | 'dpad' | 'split' | 'docked';
+type RailPlacement = 'bottom' | 'hidden' | 'left' | 'right';
+type GroupAxis = 'horizontal' | 'vertical';
+interface RendererHandle {
+    root: HTMLElement;
+    destroy(): void;
+}
+declare function mount(viewer: ViewerApi, opts?: MountOptions): RendererHandle;
+
+type PerGallery<T> = T | ((gallery: string) => T);
+interface BindOptions {
+    /** which elements are links (default `[data-gallerist]`). */
+    selector?: string;
+    /** where to look for them (default `document`). */
+    root?: Document | HTMLElement;
+    /**
+     * `createViewer` options besides the collection (`plugins`, `loop`…), or a function returning a set
+     * per gallery. With several galleries use the function for `pins()`, which holds its state on the
+     * plugin and so can't be shared between viewers.
+     */
+    viewer?: PerGallery<Omit<ViewerOptions, 'collection' | 'groups' | 'items'>>;
+    /** `mount` options (`preset`, `skin`…), or one set per gallery. */
+    mount?: PerGallery<MountOptions>;
+}
+interface BindHandle {
+    /** open a gallery from code, at its first item or the one given. */
+    open(gallery?: string, at?: {
+        g?: number;
+        i?: number;
+    }): void;
+    /** the gallery's viewer, once it has been opened. */
+    viewer(gallery?: string): ViewerApi | undefined;
+    /** stop listening and destroy every viewer. */
+    destroy(): void;
+}
+interface LinkCollection {
+    collection: Collection;
+    /** where each link landed */
+    positions: Map<Element, {
+        g: number;
+        i: number;
+    }>;
+}
+/**
+ * Build a collection from link elements. A link with `data-gallerist-group` joins the group of that
+ * id, in first-seen order (named by `-group-caption`, with `-group-subtitle` in its meta); any other
+ * link is a group of its own. Elements with neither a `data-gallerist-src` nor an `href` are skipped.
+ */
+declare function collectionFromLinks(links: Iterable<Element>, idPrefix?: string): LinkCollection;
+/**
+ * Open a viewer from `data-gallerist` links. Each distinct attribute value is its own gallery. A plain
+ * click opens the viewer at that link; a modified click (new tab, download) stays the browser's.
+ */
+declare function bind(opts?: BindOptions): BindHandle;
+
+/** Package version, injected from package.json at build (tsup `define`). Guarded with `typeof` so
+ *  importing the source without the define (e2e / example fixtures) yields a dev marker, not a crash. */
+declare const VERSION: string;
+
+export { type Accent, type Appearance, type ArrowLayout, type BindHandle, type BindOptions, type ColorScheme, DEFAULT_STRINGS, type GroupAxis, type ItemIndicator, type MountOptions, type PresetName, type RailPlacement, type RendererHandle, type ResolvedPreset, type Skin, type Strings, VERSION, applyAppearance, bind, collectionFromLinks, imageAdapter, mount, resolvePreset };