lightgallery 2.9.0 → 3.0.0-beta.3

package/{scss → dist/scss}/transitions/_lg-zoom-out.scss

@@ -3,6 +3,12 @@
 .lg-css3 {
     &.lg-zoom-out {
         .lg-item {
+            // The crossfade IS the effect here, so it runs for the
+            // whole slide instead of the short default swap. Declared on
+            // the item: --lg-speed is published on .lg-inner, so only its
+            // descendants can resolve it.
+            --lg-opacity-speed: var(--lg-speed, 400ms);
+
             opacity: 0;
 
             &.lg-prev-slide {

package/dist/types/headless/announce.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Slide-change announcement formatting for the shared `aria-live` region.
+ * All four runtimes build their announcer text through this helper so the
+ * wording (and its localization surface, `strings.slideAnnouncement`) stays
+ * identical everywhere.
+ */
+export interface SlideAnnouncementOptions {
+    /** `strings.slideAnnouncement` template with `{index}`/`{total}` slots. */
+    template: string;
+    /** 1-based position of the shown slide. */
+    index: number;
+    /** Total slide count. */
+    total: number;
+    /** Plain-text caption of the shown slide, if any. */
+    caption?: string;
+}
+/**
+ * Build the text announced on a slide change: the filled template, then the
+ * caption (comma-separated) when one exists. Whitespace in the caption is
+ * collapsed so multi-line/rich captions read as one sentence.
+ */
+export declare function formatSlideAnnouncement(options: SlideAnnouncementOptions): string;

package/dist/types/headless/emitter.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Framework-free typed event emitter — the plugin/core event bus shared by
+ * every framework runtime (React ADR 0001 §1 boundary note; Angular ADR
+ * 0001 §5). Each framework supplies its own event map type; unknown event
+ * names stay usable for plugin-private events.
+ */
+export interface TypedEmitter<TMap extends object> {
+    /** Subscribe; returns the unsubscribe function. */
+    on<K extends keyof TMap & string>(name: K, listener: (detail: TMap[K]) => void): () => void;
+    on(name: string, listener: (detail: unknown) => void): () => void;
+    emit<K extends keyof TMap & string>(name: K, detail: TMap[K]): void;
+    emit(name: string, detail?: unknown): void;
+}
+export declare function createEmitter<TMap extends object>(): TypedEmitter<TMap>;

package/dist/types/headless/gestures.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Gesture math, ported from the 2.x touch/drag implementation
+ * (`touchMove`/`touchEnd` in `src/lightgallery.ts`) as pure functions. The
+ * framework layer owns pointer events and writes the returned transforms
+ * straight to the DOM (never through framework state — one render per
+ * gesture, not per move); every *decision* lives here so swipe feel is
+ * identical across frameworks.
+ */
+import type { ResolvedGalleryDirection } from './settings';
+export type SwipeAxis = 'horizontal' | 'vertical';
+/**
+ * Minimum travel (px) before a drag commits to an axis. Tuned from the
+ * 2.x 15px to ~10 (UIPanGestureRecognizer territory): drags answer a
+ * touch sooner without axis flip-flop — the commit is still sticky.
+ */
+export declare const SWIPE_AXIS_THRESHOLD = 10;
+/**
+ * Flick support: a release faster than this (px/ms, windowed — see
+ * `velocity.ts`) navigates even below `swipeThreshold`. Default per the
+ * gesture-physics teardown: windowed readings run higher than the old
+ * whole-gesture averages, so this gate and windowed measurement ship as
+ * one change. Public setting: `flickVelocity`.
+ */
+export declare const FLICK_VELOCITY = 0.5;
+/** Minimum travel (px) for a flick, so taps never navigate. */
+export declare const FLICK_MIN_DISTANCE = 20;
+/** Vertical travel (px) beyond which the drag hides the UI chrome — 2.x. */
+export declare const VERTICAL_CLOSE_THRESHOLD = 100;
+/**
+ * Drag-to-close verdict: the momentum-projected travel must pass this
+ * fraction of the viewport height — a small fast downward flick closes,
+ * a large slow drag released while returning does not.
+ */
+export declare const VERTICAL_CLOSE_RATIO = 0.4;
+/**
+ * Minimum actual travel (px) before the projected close arms. Momentum
+ * may extend a real drag, never replace one: a grazed tap releases with
+ * a fast final instant, and projection alone would read it as a close
+ * flick.
+ */
+export declare const VERTICAL_CLOSE_MIN_DRAG = 40;
+/**
+ * Rubber-band friction past the first/last slide (no loop): the drag
+ * keeps moving at this fraction of the finger instead of the 2.x
+ * un-resisted 1:1 travel — you feel that there is nothing further.
+ */
+export declare const SLIDE_EDGE_FRICTION = 0.35;
+/**
+ * Horizontal drag delta with rubber-banding past the gallery ends.
+ * `hasPrev`/`hasNext` reflect whether a slide exists in that direction
+ * (loop counts); the release spring returns the frictioned distance.
+ */
+export declare function getEdgeFrictionedDelta(deltaX: number, hasPrev: boolean, hasNext: boolean, direction?: ResolvedGalleryDirection): number;
+/** Decide (once) which axis a drag follows; sticky after the first commit. */
+export declare function getSwipeAxis(deltaX: number, deltaY: number, current: SwipeAxis | undefined): SwipeAxis | undefined;
+export interface HorizontalDragTransforms {
+    current: string;
+    prev: string;
+    next: string;
+}
+/**
+ * Follow-the-finger transforms for the current slide and its neighbors
+ * (2.x `touchMove` horizontal branch, including the shrinking gutter).
+ */
+export declare function getHorizontalDragTransforms(deltaX: number, slideWidth: number, direction?: ResolvedGalleryDirection): HorizontalDragTransforms;
+export interface VerticalDragEffects {
+    /** Backdrop opacity fading out with the drag. */
+    backdropOpacity: number;
+    /** Transform for the current slide (translate + shrink). */
+    transform: string;
+    /** True once the UI chrome should hide (past the close threshold). */
+    hideUi: boolean;
+}
+/** Drag-to-close visuals (2.x `touchMove` vertical branch). */
+export declare function getVerticalDragEffects(deltaY: number, viewportWidth: number, viewportHeight: number): VerticalDragEffects;
+export type SwipeReleaseVerdict = 'next' | 'prev' | 'stay';
+export interface SwipeReleaseInput {
+    deltaX: number;
+    /** Release velocity, px/ms signed (windowed — see `velocity.ts`). */
+    velocityX: number;
+    /** `swipeThreshold` setting (px). */
+    threshold: number;
+    /** `flickVelocity` setting (px/ms). */
+    flickVelocity?: number;
+    /**
+     * Slide width (px). When given, a release whose momentum-projected
+     * travel crosses the midpoint also navigates — a firm half-hearted
+     * swipe keeps going where a hesitant one snaps back.
+     */
+    viewportWidth?: number;
+    /** Resolved gallery direction; in `'rtl'` the verdict mirrors. */
+    direction?: ResolvedGalleryDirection;
+}
+/**
+ * Horizontal release decision: past `swipeThreshold`, or a quick flick →
+ * navigate (negative delta = next, 2.x parity); otherwise snap back.
+ * The flick counts only when the release velocity points the same way
+ * as the drag — reversing direction just before lifting is a cancel,
+ * not a flick.
+ */
+export declare function getSwipeReleaseVerdict({ deltaX, velocityX, threshold, flickVelocity, viewportWidth, direction, }: SwipeReleaseInput): SwipeReleaseVerdict;
+/**
+ * Vertical release decision: close when the momentum-projected travel
+ * passes {@link VERTICAL_CLOSE_RATIO} of the viewport in the drag's own
+ * direction (a release moving back toward rest never closes), and the
+ * finger actually travelled {@link VERTICAL_CLOSE_MIN_DRAG}.
+ */
+export declare function shouldCloseOnVerticalDrag(deltaY: number, velocityY: number, viewportHeight: number, options: {
+    closable: boolean;
+    swipeToClose: boolean;
+}): boolean;
+/**
+ * Which slide navigation a release verdict maps to, honoring the 2.x touch
+ * loop rule: galleries with fewer than 3 slides never wrap from touch.
+ */
+export declare function resolveSwipeTarget(verdict: SwipeReleaseVerdict, currentIndex: number, slidesCount: number, loop: boolean): number | null;
+/** One live pointer, for multi-pointer consumers (zoom plugin). */
+export interface PointerRecord {
+    id: number;
+    startX: number;
+    startY: number;
+    x: number;
+    y: number;
+}
+/** Add or update a pointer record, returning a new array. */
+export declare function upsertPointer(pointers: readonly PointerRecord[], record: PointerRecord): PointerRecord[];
+/** Remove a pointer record by id, returning a new array. */
+export declare function removePointer(pointers: readonly PointerRecord[], id: number): PointerRecord[];

package/dist/types/headless/hash-driver.d.ts

@@ -0,0 +1,77 @@
+/**
+ * URL-hash drivers for the hash plugin (plan 012). The plugin's history
+ * side-effects — replace-write the deep link, restore/clear on close,
+ * follow back/forward — sit behind one interface with two engines:
+ *
+ * - `history`: today's behavior (history.replaceState + `hashchange`) —
+ *   the default fallback everywhere.
+ * - `navigation`: the Navigation API (Baseline Newly Available, Jan
+ *   2026) — replace-navigations carry entry state, and back/forward is
+ *   observed via `currententrychange`. Strictly a feature-detected
+ *   enhancement: nothing here is load-bearing (Safari's missing
+ *   `precommitHandler` is irrelevant — we never intercept), and any
+ *   missing capability falls back to the history driver.
+ *
+ * The deep-link URL format (`#lg=<galleryId>&slide=<index|name>`) is
+ * public API and identical across drivers — pinned by the parity tests.
+ *
+ * Everything is structurally typed (the runtimes pass `window`); nothing
+ * in this module touches DOM globals directly.
+ *
+ * Revisit note: flip the docs' default emphasis toward `navigation` once
+ * the API reaches Widely Available (~2028 per current projection).
+ */
+export interface HashDriver {
+    /** Which engine this driver runs on (also used by the parity tests). */
+    readonly kind: 'history' | 'navigation';
+    /** The current URL hash including the leading '#', or ''. */
+    getHash(): string;
+    /** Replace the current entry's hash (never grows history). */
+    replaceHash(hash: string): void;
+    /** Replace the current entry with the bare URL (drops the hash). */
+    clearHash(): void;
+    /**
+     * Notify on URL changes the driver did not itself cause is NOT
+     * guaranteed — subscribers must be re-entrant-safe (the hash plugin's
+     * handlers already are: same-slide jumps no-op and close checks the
+     * open flag).
+     */
+    subscribe(onChange: () => void): () => void;
+}
+export interface HashHistoryWindow {
+    location: {
+        hash: string;
+        pathname: string;
+        search: string;
+    };
+    history: {
+        replaceState(data: unknown, unused: string, url?: string): void;
+    };
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+/** Structural slice of the Navigation API the driver uses. */
+export interface NavigationLike {
+    currentEntry?: {
+        url?: string | null;
+    } | null;
+    navigate(url: string, options?: {
+        history?: 'auto' | 'push' | 'replace';
+        state?: unknown;
+    }): unknown;
+    addEventListener(type: string, listener: () => void): void;
+    removeEventListener(type: string, listener: () => void): void;
+}
+export interface HashNavigationWindow extends HashHistoryWindow {
+    navigation?: NavigationLike;
+}
+export type HashDriverPreference = 'auto' | 'history' | 'navigation';
+export declare function createHistoryHashDriver(win: HashHistoryWindow): HashDriver;
+export declare function createNavigationHashDriver(win: HashHistoryWindow, navigation: NavigationLike): HashDriver;
+/**
+ * Pick a driver: `navigation` when preferred-or-auto and the Navigation
+ * API is present with everything the driver needs; the history driver in
+ * every other case (including an explicit `navigation` preference on a
+ * browser without support — the enhancement is never load-bearing).
+ */
+export declare function createHashDriver(win: HashNavigationWindow, preference?: HashDriverPreference): HashDriver;

package/dist/types/headless/icons.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Built-in UI icon set: inline SVG strings, one per icon name, grouped
+ * by the feature that renders them so bundlers ship only the groups a
+ * consumer's plugins import. Pure string data — safe in this DOM-free
+ * package. Runtimes render these when the consumer supplies no custom
+ * icon for a name.
+ *
+ * The artwork is lightGallery's own icon set, carried over from the
+ * 2.x icon font: each glyph's vector outline extracted from the font
+ * and re-baselined onto a square viewBox (font ascent 960 on a 1024
+ * em). Same shapes the library has always shipped — now crisp inline
+ * SVGs that follow `currentColor`.
+ */
+/** The icon-name contract shared by every runtime and plugin. */
+export type LgIconName = 'close' | 'prev' | 'next' | 'download' | 'maximize' | 'minimize' | 'more' | 'zoomIn' | 'zoomOut' | 'actualSize' | 'rotateLeft' | 'rotateRight' | 'flipHorizontal' | 'flipVertical' | 'share' | 'shareFacebook' | 'shareX' | 'sharePinterest' | 'autoplayPlay' | 'autoplayPause' | 'fullscreen' | 'fullscreenExit' | 'comment' | 'commentClose' | 'toggleThumbnails';
+export declare const coreDefaultIcons: {
+    readonly close: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M810 664.667l-238-238 238-238-60-60-238 238-238-238-60 60 238 238-238 238 60 60 238-238 238 238z\"/></svg>";
+    readonly more: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><circle cx=\"232\" cy=\"512\" r=\"80\"/><circle cx=\"512\" cy=\"512\" r=\"80\"/><circle cx=\"792\" cy=\"512\" r=\"80\"/></svg>";
+    readonly prev: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M426.667 768q17.667 0 30.167-12.5t12.5-30.167q0-18-12.667-30.333l-225.667-225.667h665q17.667 0 30.167-12.5t12.5-30.167-12.5-30.167-30.167-12.5h-665l225.667-225.667q12.667-12.333 12.667-30.333 0-17.667-12.5-30.167t-30.167-12.5q-18 0-30.333 12.333l-298.667 298.667q-12.333 13-12.333 30.333t12.333 30.333l298.667 298.667q12.667 12.333 30.333 12.333z\"/></svg>";
+    readonly next: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M597.333 768q18 0 30.333-12.333l298.667-298.667q12.333-12.333 12.333-30.333t-12.333-30.333l-298.667-298.667q-12.333-12.333-30.333-12.333-18.333 0-30.5 12.167t-12.167 30.5q0 18 12.333 30.333l226 225.667h-665q-17.667 0-30.167 12.5t-12.5 30.167 12.5 30.167 30.167 12.5h665l-226 225.667q-12.333 12.333-12.333 30.333 0 18.333 12.167 30.5t30.5 12.167z\"/></svg>";
+    readonly download: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M170 128.667h684v-86h-684v86zM682 384.667l-170-172-170 172h128v426h84v-426h128z\"/></svg>";
+    readonly maximize: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M793.003 768l-225.835-225.835c-16.683-16.683-16.683-43.691 0-60.331s43.691-16.683 60.331 0l225.835 225.835v-153.003c0-23.552 19.115-42.667 42.667-42.667s42.667 19.115 42.667 42.667v256c0 5.803-1.152 11.307-3.243 16.341s-5.163 9.728-9.216 13.781c-0.043 0.043-0.043 0.043-0.085 0.085-3.925 3.925-8.619 7.083-13.781 9.216-5.035 2.091-10.539 3.243-16.341 3.243h-256c-23.552 0-42.667-19.115-42.667-42.667s19.115-42.667 42.667-42.667zM230.997 85.334l225.835 225.835c16.683 16.683 16.683 43.691 0 60.331s-43.691 16.683-60.331 0l-225.835-225.835v153.003c0 23.552-19.115 42.667-42.667 42.667s-42.667-19.115-42.667-42.667v-256c0-23.552 19.115-42.667 42.667-42.667h256c23.552 0 42.667 19.115 42.667 42.667s-19.115 42.667-42.667 42.667z\"/></svg>";
+    readonly minimize: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M700.331 554.667l225.835 225.835c16.683 16.683 16.683 43.691 0 60.331s-43.691 16.683-60.331 0l-225.835-225.835v153.003c0 23.552-19.115 42.667-42.667 42.667s-42.667-19.115-42.667-42.667v-256c0-5.803 1.152-11.307 3.243-16.341s5.163-9.728 9.216-13.781c0.043-0.043 0.043-0.043 0.085-0.085 3.925-3.925 8.619-7.083 13.781-9.216 5.035-2.091 10.539-3.243 16.341-3.243h256c23.552 0 42.667 19.115 42.667 42.667s-19.115 42.667-42.667 42.667zM158.165 12.502l225.835 225.835v-153.003c0-23.552 19.115-42.667 42.667-42.667s42.667 19.115 42.667 42.667v256c0 5.803-1.152 11.307-3.243 16.341s-5.163 9.728-9.216 13.781c-0.043 0.043-0.043 0.043-0.085 0.085-4.096 4.053-8.789 7.125-13.781 9.216-5.035 2.091-10.539 3.243-16.341 3.243h-256c-23.552 0-42.667-19.115-42.667-42.667s19.115-42.667 42.667-42.667h153.003l-225.835-225.835c-16.683-16.683-16.683-43.691 0-60.331s43.691-16.683 60.331 0z\"/></svg>";
+};
+export declare const zoomDefaultIcons: {
+    readonly zoomIn: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M512 512.667h-86v-86h-42v86h-86v42h86v86h42v-86h86v-42zM406 340.667q80 0 136 56t56 136-56 136-136 56-136-56-56-136 56-136 136-56zM662 340.667l212-212-64-64-212 212v34l-12 12q-76-66-180-66-116 0-197 80t-81 196 81 197 197 81 196-81 80-197q0-104-66-180l12-12h34z\"/></svg>";
+    readonly zoomOut: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M298 554.667h214v-42h-214v42zM406 340.667q80 0 136 56t56 136-56 136-136 56-136-56-56-136 56-136 136-56zM662 340.667l212-212-64-64-212 212v34l-12 12q-76-66-180-66-116 0-197 80t-81 196 81 197 197 81 196-81 80-197q0-104-66-180l12-12h34z\"/></svg>";
+    readonly actualSize: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M384 853.334h426.667q53 0 90.5-37.5t37.5-90.5v-426.667q0-53-37.5-90.5t-90.5-37.5h-426.667q-53 0-90.5 37.5t-37.5 90.5v426.667q0 53 37.5 90.5t90.5 37.5zM170.667 675.334v-547.333q0-17.667 12.5-30.167t30.167-12.5h547.333q-13.333-37.667-46.333-61.5t-74.333-23.833h-426.667q-53 0-90.5 37.5t-37.5 90.5v426.667q0 41.333 23.833 74.333t61.5 46.333zM810.667 768h-426.667q-17.667 0-30.167-12.5t-12.5-30.167v-426.667q0-17.667 12.5-30.167t30.167-12.5h426.667q17.667 0 30.167 12.5t12.5 30.167v426.667q0 17.667-12.5 30.167t-30.167 12.5z\"/></svg>";
+};
+export declare const rotateDefaultIcons: {
+    readonly rotateLeft: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M554 764.667q126-16 213-112t87-226-87-226-213-112v86q92 16 153 87t61 165-61 165-153 87v-166l-194 190 194 194v-132zM302 156.667l62 62q46-34 106-44v-86q-96 12-168 68zM260 384.667q10-58 42-106l-60-60q-56 74-68 166h86zM304 574.667q-36-52-44-106h-86q12 90 70 166z\"/></svg>";
+    readonly rotateRight: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M720 278.667q34 46 44 106h86q-12-92-68-166zM554 174.667q60 10 106 44l62-62q-72-56-168-68v86zM850 468.667h-86q-10 60-44 106l62 60q58-72 68-166zM664 702.667l-194-190v166q-92-16-153-87t-61-165 61-165 153-87v-86q-126 16-213 112t-87 226 87 226 213 112v132z\"/></svg>";
+    readonly flipHorizontal: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M896 554.667l-170-170v128h-300v84h300v128zM298 468.667v-128h300v-84h-300v-128l-170 170z\"/></svg>";
+    readonly flipVertical: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M384 810.667l170-170h-128v-300h-84v300h-128zM682 212.667h128l-170-170-170 170h128v300h84v-300z\"/></svg>";
+};
+export declare const shareDefaultIcons: {
+    readonly share: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M768 252.667c68 0 124-56 124-124s-56-126-124-126-124 58-124 126c0 10 0 20 2 28l-302 176c-24-22-54-34-88-34-70 0-128 58-128 128s58 128 128 128c34 0 64-12 88-34l300 174c-2 10-4 20-4 30 0 70 58 128 128 128s128-58 128-128-58-128-128-128c-34 0-64 14-88 36l-300-176c2-10 4-20 4-30s-2-20-4-30l304-176c22 20 52 32 84 32z\"/></svg>";
+    readonly shareFacebook: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M512 952.32c-271.462 0-491.52-220.058-491.52-491.52s220.058-491.52 491.52-491.52 491.52 220.058 491.52 491.52-220.058 491.52-491.52 491.52zM628.429 612.659h-73.882c-8.755 0-18.483-11.52-18.483-26.829v-53.35h92.416l-13.978-76.083h-78.438v-228.403h-87.194v228.403h-79.104v76.083h79.104v44.749c0 64.205 44.544 116.378 105.677 116.378h73.882v-80.947z\"/></svg>";
+    readonly shareX: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><circle cx=\"512\" cy=\"512\" r=\"491.52\"/><path fill=\"#fff\" transform=\"translate(227 224) scale(24)\" d=\"M18.244 2.25h3.308l-7.227 8.26 8.502 11.24H16.17l-5.214-6.817L4.99 21.75H1.68l7.73-8.835L1.254 2.25H8.08l4.713 6.231zm-1.161 17.52h1.833L7.084 4.126H5.117z\"/></svg>";
+    readonly sharePinterest: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M512 952.32c-271.462 0-491.52-220.058-491.52-491.52s220.058-491.52 491.52-491.52 491.52 220.058 491.52 491.52-220.058 491.52-491.52 491.52zM545.638 344.32c-31.539 2.406-44.749 18.022-69.427 32.973-13.568-71.219-30.157-139.52-79.309-175.206-15.206 107.725 22.221 188.518 39.629 274.381-29.645 49.92 3.533 150.323 66.099 125.645 76.954-30.515-66.662-185.6 29.747-205.005 100.659-20.173 141.773 174.694 79.36 237.978-90.214 91.494-262.502 2.099-241.306-128.87 5.12-32 38.246-41.728 13.21-85.914-57.702 12.8-74.957 58.317-72.704 118.989 3.533 99.328 89.242 168.909 175.155 178.483 108.698 12.083 210.688-39.885 224.819-142.182 15.821-115.405-49.101-240.282-165.274-231.27z\"/></svg>";
+};
+export declare const autoplayDefaultIcons: {
+    readonly autoplayPlay: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M512 84.667q140 0 241 101t101 241-101 241-241 101-241-101-101-241 101-241 241-101zM512 852.667q176 0 301-125t125-301-125-301-301-125-301 125-125 301 125 301 301 125zM426 234.667v384l256-192z\"/></svg>";
+    readonly autoplayPause: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M554 256.667v340h86v-340h-86zM512 84.667q140 0 241 101t101 241-101 241-241 101-241-101-101-241 101-241 241-101zM512 852.667q176 0 301-125t125-301-125-301-301-125-301 125-125 301 125 301 301 125zM384 256.667v340h86v-340h-86z\"/></svg>";
+};
+export declare const fullscreenDefaultIcons: {
+    readonly fullscreen: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M598 724.667h212v-212h-84v128h-128v84zM726 212.667v128h84v-212h-212v84h128zM214 512.667v212h212v-84h-128v-128h-84zM298 340.667v-128h128v-84h-212v212h84z\"/></svg>";
+    readonly fullscreenExit: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M682 596.667h128v-84h-212v212h84v-128zM598 128.667v212h212v-84h-128v-128h-84zM342 596.667v128h84v-212h-212v84h128zM214 256.667v84h212v-212h-84v128h-128z\"/></svg>";
+};
+export declare const commentDefaultIcons: {
+    readonly comment: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M938.667 448.128v21.205c0 0.725-0.043 1.621-0.085 2.475-5.803 99.755-47.488 190.336-112.725 258.176-68.352 71.125-162.731 117.419-268.843 123.264-0.683 0.043-1.536 0.085-2.347 0.085h-20.864c-59.947 0.683-122.965-13.227-181.931-43.008-52.181-26.496-97.749-63.488-133.931-108.16-56.405-69.717-89.899-158.080-89.941-253.696-0.597-54.4 10.795-111.36 35.157-165.419l-75.605-226.859c-2.816-8.363-3.072-17.835 0-26.965 7.467-22.357 31.616-34.432 53.973-26.965l226.731 75.563c49.493-22.485 105.984-35.243 165.376-35.115 58.539 0.384 115.797 13.141 168.149 36.949 81.579 37.163 151.040 101.248 193.749 186.667 27.477 53.291 43.307 115.84 43.136 181.803zM853.333 447.872c0.128-52.267-12.459-101.333-33.664-142.464-34.176-68.352-88.832-118.827-153.259-148.139-41.387-18.859-86.827-28.971-133.376-29.269-52.096-0.128-101.163 12.459-142.293 33.664-10.624 5.504-22.528 6.059-33.067 2.56l-162.261-54.101 54.101 162.261c3.755 11.221 2.56 22.912-2.389 32.725-23.552 46.677-34.304 96.171-33.792 142.421 0.043 76.331 26.411 145.92 70.955 200.917 28.629 35.371 64.768 64.725 106.24 85.76 46.592 23.552 96.085 34.304 142.336 33.792h19.456c83.712-4.565 158.037-41.003 212.011-97.152 51.285-53.376 84.139-124.416 89.003-202.795z\"/></svg>";
+    readonly commentClose: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M810 664.667l-238-238 238-238-60-60-238 238-238-238-60 60 238 238-238 238 60 60 238-238 238 238z\"/></svg>";
+};
+export declare const thumbnailDefaultIcons: {
+    readonly toggleThumbnails: "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 1024 1024\" fill=\"currentColor\"><path transform=\"translate(0, 960) scale(1, -1)\" d=\"M682 84.667v172h172v-172h-172zM682 340.667v172h172v-172h-172zM426 596.667v172h172v-172h-172zM682 768.667h172v-172h-172v172zM426 340.667v172h172v-172h-172zM170 340.667v172h172v-172h-172zM170 84.667v172h172v-172h-172zM426 84.667v172h172v-172h-172zM170 596.667v172h172v-172h-172z\"/></svg>";
+};

package/dist/types/headless/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Framework-free core logic for lightGallery. Nothing in this package may
+ * import a framework or the DOM — the tsconfig excludes the DOM lib so
+ * `window`/`document` do not typecheck here by construction.
+ */
+export { createGalleryState, galleryReducer, type CreateGalleryStateOptions, type GalleryAction, type GalleryState, type SlideDirection, } from './state';
+export { getSlideType, type GalleryItem, type ImageSources, type SlideType, } from './items';
+export { createEmitter, type TypedEmitter } from './emitter';
+export { checkLicenseKey, LICENSE_KEY_PREFIX, resolveLicenseKey, setLicenseKey, takeLicenseNotice, TESTING_LICENSE_KEY, type LicenseNotice, } from './license';
+export { formatSlideAnnouncement, type SlideAnnouncementOptions, } from './announce';
+export { createHashDriver, createHistoryHashDriver, createNavigationHashDriver, type HashDriver, type HashDriverPreference, type HashHistoryWindow, type HashNavigationWindow, type NavigationLike, } from './hash-driver';
+export { coreSettingsDefaults, resolveSettings, type CaptionPosition, type GalleryDirection, type ResolvedGalleryDirection, type CoreSettings, type GalleryCoreStrings, type GalleryMode, type MobileSettings, type ResolveSettingsOptions, type UserSettings, type VirtualizationSettings, } from './settings';
+export { getPreloadIndexes, getSlideIndexesInDom, getSlidePoolIndexes, } from './preload';
+export { FLICK_MIN_DISTANCE, FLICK_VELOCITY, SLIDE_EDGE_FRICTION, SWIPE_AXIS_THRESHOLD, VERTICAL_CLOSE_MIN_DRAG, VERTICAL_CLOSE_RATIO, VERTICAL_CLOSE_THRESHOLD, getEdgeFrictionedDelta, getHorizontalDragTransforms, getSwipeAxis, getSwipeReleaseVerdict, getVerticalDragEffects, removePointer, resolveSwipeTarget, shouldCloseOnVerticalDrag, upsertPointer, type HorizontalDragTransforms, type PointerRecord, type SwipeAxis, type SwipeReleaseInput, type SwipeReleaseVerdict, type VerticalDragEffects, } from './gestures';
+export { CENTER_CLOSE_SCALE, fitImageSize, getCenterCloseTransform, getOriginTransform, isUsableOriginRect, parseImageSize, type ImageSize, type OriginTransformInput, type RectLike, } from './origin';
+export { CSS_POSITION_CENTER, WHOLE_IMAGE, getOriginCropFlight, getOriginWindow, isWholeImage, parseBackgroundFit, parseCssPosition, parseCssUrl, parseObjectFit, type CssPosition, type CssPositionAxis, type FractionRect, type OriginCropFlight, type OriginCropFlightInput, type OriginWindow, type OriginWindowInput, type ThumbFit, } from './origin-crop';
+export { autoplayDefaultIcons, type LgIconName, commentDefaultIcons, coreDefaultIcons, fullscreenDefaultIcons, rotateDefaultIcons, shareDefaultIcons, thumbnailDefaultIcons, zoomDefaultIcons, } from './icons';
+export { VIMEO_PLAYER_SCRIPT_URL, WISTIA_PLAYER_SCRIPT_URL, getFacadePoster, getVideoInfo, getVimeoEmbedUrl, getWistiaEmbedUrl, getYouTubeEmbedUrl, getYouTubePosterUrl, isYouTubeNoCookie, param, paramsToObject, type PlayerParams, type VideoInfo, } from './video-urls';
+export { PINCH_OVER_FRICTION, PINCH_UNDER_FRICTION, clampPan, clampPanToStage, clampScale, getActualSizeScale, getPanBounds, getPinchPan, getPinchScale, getPointZoomPan, getPointerDistance, shouldCloseOnPinch, type PanBounds, type ZoomPan, } from './zoom-math';
+export { clampThumbTranslate, getActiveThumbTranslate, getElasticThumbTranslate, getScrubThumbIndex, getScrubThumbTranslate, getThumbCorridorWindow, getThumbTotalWidth, getThumbWindow, type ThumbPagerPosition, type ThumbWindow, } from './thumb-math';
+export { TOOLBAR_DEFAULT_PRIORITY, TOOLBAR_PINNED, consumeBackdropPress, getToolbarItemPriority, getToolbarOverflow, isToolbarEventPath, type MenuDismissEvent, type ToolbarOverflowInput, type ToolbarOverflowItem, } from './toolbar-overflow';
+export { getJustifiedLayout, getJustifiedRows, getRevealableItems, type JustifiedBox, type JustifiedLayout, type JustifiedLayoutOptions, type JustifiedReveal, } from './justified-layout';
+export { onTransitionSettle, type TransitionSettleEvent, type TransitionSettleTarget, } from './transition';
+export { DECODE_TIMEOUT_MS, awaitDecode, getActualSizeWidth, matchesMedia, parseSrcset, resolveImageSource, resolveSizes, type ResolvedImageSource, type SrcsetCandidate, type Viewport, } from './responsive';
+export { DECELERATION_RATE, SPRING_BOUNCE_DAMPING, SPRING_NATURAL_FREQUENCY, SPRING_SETTLE_DAMPING, isSpringSettled, project, stepSpring, type SpringConfig, type SpringState, } from './spring';
+export { VELOCITY_WINDOW_MS, getWindowedVelocity, pushVelocitySample, type Velocity, type VelocitySample, } from './velocity';
+export { applyZoom, flipHorizontal, flipVertical, getRotateFitScale, getRotateTransform, getRotatedVisualSize, isOrientationSwapped, initialAutoplaySlice, initialRotateSlice, initialZoomSlice, rotateLeft, rotateRight, type AutoplaySlice, type RotateSlice, type ZoomSlice, } from './plugin-slices';
+export { canNativeShare, getFacebookShareLink, getPinterestShareLink, getSharePayload, getTwitterShareLink, getXShareLink, type NativeShareNavigator, type ShareItemFields, type SharePayload, } from './share-urls';
+/**
+ * Clamp a slide index into the valid range for a gallery of `length` slides.
+ * With `loop`, out-of-range indexes wrap around; without it they clamp to the
+ * nearest bound. An empty gallery always resolves to 0.
+ */
+export declare function clampIndex(index: number, length: number, loop: boolean): number;

package/dist/types/headless/items.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Framework-free gallery item data model, ported from the 2.x `GalleryItem`
+ * shape (`src/lg-utils.ts`) minus the DOM-scraping era fields. Data always
+ * arrives typed — there is no selector/attribute scraping in 3.x.
+ *
+ * The caption is generic so each framework can narrow it to its own node type
+ * (React narrows `TCaption` to `ReactNode`). Raw-HTML captions go through the
+ * deliberately loud `captionHtml` field instead.
+ */
+export interface ImageSources {
+    media?: string;
+    srcset: string;
+    sizes?: string;
+    type?: string;
+}
+export interface GalleryItem<TCaption = unknown> {
+    /** URL of the media. */
+    src?: string;
+    /** srcset attribute values for the main image. */
+    srcset?: string;
+    /** srcset sizes attribute for the main image. */
+    sizes?: string;
+    /** `<source>` attributes for rendering the image inside a `<picture>`. */
+    sources?: ImageSources[];
+    /** Thumbnail URL (used by thumbnail plugin and gallery triggers). */
+    thumb?: string;
+    /** alt attribute for the image. */
+    alt?: string;
+    /** Title attribute (videos). */
+    title?: string;
+    /** Caption for the slide, rendered by the framework layer. */
+    caption?: TCaption;
+    /**
+     * Raw-HTML caption opt-in — the explicit analog of 2.x `subHtml` strings.
+     * Rendered with the framework's raw-HTML escape hatch
+     * (`dangerouslySetInnerHTML` in React); prefer `caption`.
+     */
+    captionHtml?: string;
+    /** Render the src inside an iframe instead of an image. */
+    iframe?: boolean;
+    /** Title for the iframe. */
+    iframeTitle?: string;
+    /**
+     * HTML5 video sources (video plugin). Kept loosely typed until
+     * the video plugin lands.
+     */
+    video?: unknown;
+    /** Poster URL for video slides. */
+    poster?: string;
+    /**
+     * Download URL for the media. Pass `false` to hide the download button
+     * for this slide.
+     */
+    downloadUrl?: string | false;
+    /** Filename for the download attribute. */
+    download?: string | boolean;
+    /**
+     * Natural size of the full image as `"width-height"` (2.x
+     * `data-lg-size`), optionally a comma separated responsive list
+     * `"240-160-375, 1600-1067"`. Required for the zoom-from-origin open
+     * animation.
+     */
+    lgSize?: string;
+    /** Actual image width in px (zoom plugin actual-size math). */
+    width?: string;
+    /** Custom slide name for the hash plugin. */
+    slideName?: string;
+    /**
+     * Share plugin: canonical per-item URL for the native share sheet
+     * (defaults to the network-specific share URLs, then the page URL).
+     */
+    shareUrl?: string;
+    /** Share plugin: per-item Facebook share URL (defaults to the page URL). */
+    facebookShareUrl?: string;
+    /** Share plugin: tweet text. */
+    tweetText?: string;
+    /** Share plugin: per-item Twitter share URL. */
+    twitterShareUrl?: string;
+    /** Share plugin: per-item Pinterest share URL (must be absolute). */
+    pinterestShareUrl?: string;
+    /** Share plugin: Pinterest post description. */
+    pinterestText?: string;
+    /** mediumZoom plugin: per-item backdrop color. */
+    lgBackgroundColor?: string;
+}
+export type SlideType = 'image' | 'video' | 'iframe';
+/**
+ * Classify a gallery item: html5 `video` sources, a `poster`, or a
+ * YouTube/Vimeo/Wistia src URL make it a video (2.x `getSlideType` +
+ * `__slideVideoInfo` combined).
+ */
+export declare function getSlideType(item: GalleryItem<unknown>): SlideType;

package/dist/types/headless/justified-layout.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Justified grid layout for the trigger thumbnails: rows of equal
+ * height and varying widths that fill the container edge to edge, the
+ * row height staying as close as possible to a target. Pure math —
+ * runtimes measure the container, hand in aspect ratios, and position
+ * elements from the returned boxes.
+ */
+export interface JustifiedLayoutOptions {
+    /** Aspect ratios (width / height) in item order. */
+    ratios: readonly number[];
+    /** Content-box width available for rows (px). */
+    containerWidth: number;
+    /** Row height (px) the algorithm aims for. */
+    targetRowHeight?: number;
+    /** Gap between items and between rows (px). */
+    gap?: number;
+    /**
+     * Last-row policy: `'justify'` scales the leftover row to fill the
+     * width like every other row (clamped by `maxScale`), `'start'`
+     * keeps the target height aligned to the reading start, `'hide'`
+     * drops the leftover items (their boxes come back zero-sized).
+     */
+    lastRow?: 'justify' | 'start' | 'hide';
+    /**
+     * Row-height clamp as a multiple of `targetRowHeight` — a sparse
+     * row (single portrait, justified leftovers) never renders taller
+     * than `maxScale * targetRowHeight`. Clamped rows align to the
+     * reading start instead of filling the width.
+     */
+    maxScale?: number;
+}
+export interface JustifiedBox {
+    top: number;
+    /**
+     * Offset from the reading-start edge (logical): the runtime maps
+     * it to `left` in LTR and `right` in RTL, the same convention as
+     * the thumbnail strip math.
+     */
+    start: number;
+    width: number;
+    height: number;
+}
+export interface JustifiedLayout {
+    /**
+     * One box per input ratio, in item order — items hidden by
+     * `lastRow: 'hide'` come back zero-sized (runtimes hide them).
+     */
+    boxes: JustifiedBox[];
+    /** Total content height including the final row (px). */
+    containerHeight: number;
+}
+export declare function getJustifiedLayout(options: JustifiedLayoutOptions): JustifiedLayout;
+/**
+ * Reveal policy for laid-out thumbnails: 'image' shows each one as it
+ * loads, 'row' shows whole rows top to bottom, a row only once every
+ * thumbnail in it (and every row above it) has loaded.
+ */
+export type JustifiedReveal = 'row' | 'image';
+/**
+ * Group laid-out boxes into rows by their top offset, in layout order.
+ * Hidden boxes (0×0, the 'hide' last-row policy) belong to no row.
+ * Returns item indexes per row.
+ */
+export declare function getJustifiedRows(boxes: JustifiedBox[]): number[][];
+/**
+ * Which laid-out items may show now, given which have loaded: per
+ * image, or per row in reading order (see JustifiedReveal). The result
+ * is cumulative — callers reveal every returned item that is not
+ * already showing.
+ */
+export declare function getRevealableItems<T>(rows: T[][], isLoaded: (item: T) => boolean, reveal: JustifiedReveal): T[];

package/dist/types/headless/license.d.ts

@@ -0,0 +1,35 @@
+/**
+ * License key check shared by every package. The key never limits a
+ * feature; it only decides which console message, if any, the gallery
+ * logs. `checkLicenseKey` is pure; the page-wide key and the once-per-page
+ * bookkeeping are module state, and the runtime does the logging.
+ */
+/** The temporary key; also the default `licenseKey`. */
+export declare const TESTING_LICENSE_KEY = "0000-0000-000-0000";
+/** Every lightGallery 3 key starts with this; v1 and v2 keys don't. */
+export declare const LICENSE_KEY_PREFIX = "LIG";
+export interface LicenseNotice {
+    level: 'error' | 'warn';
+    message: string;
+}
+/**
+ * The console notice for a license key, or `null` for a lightGallery 3
+ * key. An empty key is an error; the testing key and keys from v1 or v2
+ * (no `LIG` prefix) are warnings.
+ */
+export declare function checkLicenseKey(licenseKey: string | undefined): LicenseNotice | null;
+/**
+ * Set the license key once for every gallery on the page. Call it before
+ * creating galleries; a gallery's own `licenseKey` still wins.
+ */
+export declare function setLicenseKey(licenseKey: string): void;
+/**
+ * The key a gallery runs with: its own `licenseKey`, or the page-wide key
+ * when it has none (or only the testing default).
+ */
+export declare function resolveLicenseKey(instanceKey: string | undefined): string;
+/**
+ * The notice a new gallery should log, or `null`. Each message is logged
+ * once per page, however many galleries share the key.
+ */
+export declare function takeLicenseNotice(instanceKey: string | undefined): LicenseNotice | null;