lightgallery 3.0.0-beta.2 → 3.0.0-beta.3

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;

package/dist/types/headless/origin-crop.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Math for the origin crop plugin: zoom-from-origin flights from cropped
+ * thumbnails. A grid tile cropped with `object-fit: cover` (or
+ * `background-size: cover`) shows only a window of the image. The plugin
+ * grows that window from the tile at a uniform scale while two boxes
+ * around the slides crop the rest of the image, revealed as the flight
+ * lands. Pure rect arithmetic: the plugin measures the DOM and passes
+ * plain numbers in. The core flight (`origin.ts`) never imports this.
+ */
+import { type ImageSize, type RectLike } from './origin';
+/** A region of an image as fractions of its width and height (0..1). */
+export interface FractionRect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** The whole image: the window of an uncropped thumbnail. */
+export declare const WHOLE_IMAGE: FractionRect;
+/** Whether a region covers the whole image (within rounding). */
+export declare function isWholeImage(rect: FractionRect): boolean;
+/**
+ * How a trigger paints its thumbnail file into its box: the CSS
+ * `object-fit` of an `<img>`, or the `background-size` keyword of an
+ * element with a background image.
+ */
+export type ThumbFit = 'fill' | 'contain' | 'cover' | 'none' | 'scale-down';
+/**
+ * One axis of a CSS `object-position`/`background-position`: a share of
+ * the free space (the box minus the painted image) plus a px offset.
+ */
+export interface CssPositionAxis {
+    percent: number;
+    px: number;
+}
+export interface CssPosition {
+    x: CssPositionAxis;
+    y: CssPositionAxis;
+}
+/** The CSS default, `50% 50%`. */
+export declare const CSS_POSITION_CENTER: CssPosition;
+/**
+ * Parse a computed `object-position` or `background-position` value
+ * (`"50% 50%"`, `"10px 20px"`, `"calc(100% - 10px) 0%"`, keywords).
+ * Unparseable values fall back to the centre. Only the first layer of a
+ * multi-layer background is read.
+ */
+export declare function parseCssPosition(value: string | undefined): CssPosition;
+/** Parse a computed `object-fit` value; the CSS default is `fill`. */
+export declare function parseObjectFit(value: string | undefined): ThumbFit;
+/**
+ * Parse a computed `background-size` value into the fit it paints like:
+ * `cover` and `contain` as themselves, `auto` as `none` (natural size),
+ * `100% 100%` as `fill`. Explicit lengths cannot be modelled and return
+ * undefined. Only the first layer of a multi-layer background is read.
+ */
+export declare function parseBackgroundFit(value: string | undefined): ThumbFit | undefined;
+/** The first URL of a computed `background-image` value, if any. */
+export declare function parseCssUrl(value: string | undefined): string | undefined;
+export interface OriginWindowInput {
+    /** Rendered box of the trigger (thumbnail img or background element), viewport px. */
+    box: RectLike;
+    /** The full image; only its aspect ratio matters. */
+    imageSize: ImageSize;
+    /**
+     * Natural size of the thumbnail file when known (an `<img>`'s
+     * `naturalWidth`/`naturalHeight`). A file with a different aspect ratio
+     * than the image is taken as a centred crop of it. Unknown (a background
+     * image, an unloaded img) assumes the image's own aspect ratio.
+     */
+    thumbSize?: ImageSize;
+    /** How the file is painted into the box. Defaults to `fill`. */
+    fit?: ThumbFit;
+    /** Where the painted file sits in the box. Defaults to the centre. */
+    position?: CssPosition;
+}
+export interface OriginWindow {
+    /**
+     * The part of the trigger box that shows thumbnail pixels, viewport px:
+     * the box itself unless the file is letterboxed inside it.
+     */
+    rect: RectLike;
+    /** The part of the image visible in `rect`, as fractions of the image. */
+    window: FractionRect;
+    /**
+     * The part of the image the thumbnail file covers, as fractions: the
+     * whole image unless the file is pre-cropped. Sizes the flight's
+     * dummy, which shows the file, so its pixels land where they belong.
+     */
+    region: FractionRect;
+}
+/**
+ * Where a thumbnail's visible pixels sit in the full image. Models the CSS
+ * fit and position of the file inside its box, and a pre-cropped file as a
+ * centred crop of the image.
+ */
+export declare function getOriginWindow(input: OriginWindowInput): OriginWindow;
+export interface OriginCropFlightInput {
+    /**
+     * The part of the trigger showing thumbnail pixels
+     * ({@link OriginWindow.rect}), viewport px.
+     */
+    triggerRect: RectLike;
+    /** Bounding rect of the gallery outer element, viewport coordinates. */
+    containerRect: RectLike;
+    /** Media container top offset (toolbar height), px. */
+    top: number;
+    /** Media container bottom offset (caption + thumb strip height), px. */
+    bottom: number;
+    /** Final displayed image size (see `fitImageSize`). */
+    imageSize: ImageSize;
+    /** The part of the image the trigger shows ({@link OriginWindow.window}). */
+    window: FractionRect;
+}
+export interface OriginCropFlight {
+    /**
+     * The slide's transform: the window lands on the trigger, at a uniform
+     * scale, inside the translated stage boxes.
+     */
+    transform: string;
+    /** The outer stage box: its bottom-right corner on the trigger's. */
+    outer: string;
+    /** The inner stage box: its top-left corner on the trigger's. */
+    inner: string;
+}
+/**
+ * The start of a flight from a cropped thumbnail (and the end of the flight
+ * back to it). Two stage-sized, overflow-hidden boxes wrap the slides: the
+ * outer one translates so that its bottom-right corner sits on the
+ * trigger's, the inner one so that its top-left corner sits on the
+ * trigger's, and their intersection is exactly the trigger's box. As both
+ * transition back to rest with the slide, the crop's edges move linearly on
+ * screen out to the whole stage, and only transforms animate.
+ */
+export declare function getOriginCropFlight(input: OriginCropFlightInput): OriginCropFlight;

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

@@ -0,0 +1,65 @@
+/**
+ * Zoom-from-origin math, ported from 2.x `utils.getSize`/`utils.getTransform`
+ * (`src/lg-utils.ts`) as pure rect arithmetic. The framework layer measures
+ * the DOM (trigger/container bounding rects) and passes plain numbers in.
+ *
+ * Note: this module is an addition to the ADR 0001 §1 table — it
+ * follows the standing rule that pure functions needed by React live in
+ * headless. It is distinct from `zoom-math.ts` (zoom plugin).
+ */
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+export interface RectLike {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/**
+ * Parse an item's `lgSize` value (`"1920-1280"`, or a responsive list like
+ * `"240-160-375, 1600-1067"` where the third number is the max viewport
+ * width the entry applies to).
+ */
+export declare function parseImageSize(lgSize: string | undefined, viewportWidth: number): ImageSize | undefined;
+/**
+ * Fit a natural image size into the available container box, preserving
+ * aspect ratio and never scaling up (2.x `utils.getSize` math).
+ */
+export declare function fitImageSize(size: ImageSize, containerWidth: number, containerHeight: number): ImageSize;
+/**
+ * Whether a measured trigger rect can anchor the zoom-from-origin flight.
+ * A trigger that is hidden (`display: none`, the `hidden` attribute),
+ * detached or collapsed measures 0×0 at the viewport origin; a flight
+ * aimed at it would shrink the slide into the top-left corner.
+ */
+export declare function isUsableOriginRect(rect: RectLike | null | undefined): rect is RectLike;
+/** Scale the closing slide shrinks to when it has no trigger to return to. */
+export declare const CENTER_CLOSE_SCALE = 0.5;
+/**
+ * Close transform for a slide without a usable origin (hidden or
+ * collapsed trigger, no `lgSize`): shrink in place about the stage centre,
+ * the mirror of the `lg-start-zoom` open. The runtime pairs it with the
+ * `lg-close-to-center` class, which fades the slide out over the same
+ * duration.
+ */
+export declare function getCenterCloseTransform(scale?: number): string;
+export interface OriginTransformInput {
+    /** Bounding rect of the trigger thumbnail image, viewport coordinates. */
+    triggerRect: RectLike;
+    /** Bounding rect of the gallery outer element, viewport coordinates. */
+    containerRect: RectLike;
+    /** Media container top offset (toolbar height), px. */
+    top: number;
+    /** Media container bottom offset (caption + thumb strip height), px. */
+    bottom: number;
+    /** Final displayed image size (see {@link fitImageSize}). */
+    imageSize: ImageSize;
+}
+/**
+ * CSS transform that places the (centered, final-size) slide image exactly
+ * over the trigger thumbnail — the starting point of the zoom-from-origin
+ * open animation and the end point of the close animation.
+ */
+export declare function getOriginTransform(input: OriginTransformInput): string;

package/dist/types/headless/plugin-slices.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Typed per-plugin state slices (ADR 0001 §5). Framework layers hold these
+ * in their own reactivity; the shapes and transitions live here so plugin
+ * behavior matches across frameworks.
+ */
+import { type ZoomPan } from './zoom-math';
+export interface ZoomSlice {
+    scale: number;
+    pan: ZoomPan;
+    zoomed: boolean;
+}
+export declare const initialZoomSlice: ZoomSlice;
+/** Per-slide rotate/flip state (rotate plugin). */
+export interface RotateSlice {
+    /** Rotation in degrees (multiples of 90, may run negative). */
+    rotate: number;
+    /** 1 or -1. */
+    flipHorizontal: number;
+    /** 1 or -1. */
+    flipVertical: number;
+}
+export declare const initialRotateSlice: RotateSlice;
+export declare function rotateLeft(slice: RotateSlice): RotateSlice;
+export declare function rotateRight(slice: RotateSlice): RotateSlice;
+export declare function flipHorizontal(slice: RotateSlice): RotateSlice;
+export declare function flipVertical(slice: RotateSlice): RotateSlice;
+/** Whether the slice's rotation swaps the image's visual axes (90°/270°). */
+export declare function isOrientationSwapped(slice: RotateSlice): boolean;
+/**
+ * Scale that refits a rotated image into its stage. At 90°/270° the
+ * image's rendered width runs vertically (and vice versa), so the fit is
+ * computed against the swapped axes; capped at 1 — rotation never
+ * upscales. At 0°/180° (and with degenerate dimensions) the image already
+ * fits the way it was laid out: scale 1.
+ */
+export declare function getRotateFitScale(imageWidth: number, imageHeight: number, stageWidth: number, stageHeight: number, slice: RotateSlice): number;
+/**
+ * CSS transform for a rotate slice (2.x `applyStyles`), with the fit
+ * scale folded into the same transform so rotate + refit animate as one
+ * motion. `fitScale` defaults to 1 (the 2.x output, byte-identical).
+ */
+export declare function getRotateTransform(slice: RotateSlice, fitScale?: number): string;
+/**
+ * Visual footprint of an image sitting inside the rotate wrapper.
+ * Layout offsets ignore CSS transforms, so pan-bounds math fed by
+ * them sees the unrotated box: at 90°/270° the rendered width runs
+ * along the layout height (and vice versa), and the folded-in fit
+ * scale shrinks both axes. `transform` is the wrapper's inline style
+ * (`getRotateTransform` output); absent or unparseable input reads
+ * as unrotated.
+ */
+export declare function getRotatedVisualSize(width: number, height: number, transform: string | null | undefined): {
+    width: number;
+    height: number;
+};
+/** Autoplay run-state (autoplay plugin). */
+export interface AutoplaySlice {
+    running: boolean;
+    pausedOnDrag: boolean;
+    pausedOnSlideChange: boolean;
+}
+export declare const initialAutoplaySlice: AutoplaySlice;
+/** Commit a zoom change; scale 1 always recenters (2.x behavior). */
+export declare function applyZoom(_slice: ZoomSlice, scale: number, pan: ZoomPan, maxScale: number, infiniteZoom: boolean): ZoomSlice;

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

@@ -0,0 +1,36 @@
+/**
+ * Slide windowing and preload math, ported from 2.x
+ * `getItemsToBeInsertedToDom` / `preload` (`src/lightgallery.ts`). Pure
+ * index arithmetic — the framework layer maps the returned indexes to
+ * mounted slide components.
+ */
+/**
+ * Which slide indexes should be mounted for a given current/previous index.
+ *
+ * Mirrors 2.x behavior: at least 3 items (capped at the gallery length),
+ * the window centered around `index` biased by which half of the gallery it
+ * falls in, plus the far-end slide at the edges when `loop` is on, plus the
+ * previous slide so an outgoing transition can finish.
+ */
+export declare function getSlideIndexesInDom(index: number, prevIndex: number, slidesCount: number, numberOfItems?: number, loop?: boolean): number[];
+/**
+ * Slide-pool policy (plan 010 virtualization): the mounted-slide window
+ * from `getSlideIndexesInDom`, plus any protected indexes that must never
+ * be recycled while they hold live state — a zoomed slide keeps its
+ * transform/gesture session, so recycling it would drop the user's zoom.
+ * Protected indexes outside the gallery bounds are ignored.
+ */
+export declare function getSlidePoolIndexes(options: {
+    index: number;
+    prevIndex: number;
+    slidesCount: number;
+    poolSize?: number;
+    loop?: boolean;
+    protectedIndexes?: readonly number[];
+}): number[];
+/**
+ * Indexes to preload around `index` once the current slide has finished
+ * loading: up to `preload` slides forward and backward, clamped at the
+ * gallery bounds (no wrap-around — 2.x parity).
+ */
+export declare function getPreloadIndexes(index: number, preload: number, slidesCount: number): number[];

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

@@ -0,0 +1,90 @@
+/**
+ * Responsive image selection + decode gating (plan: responsive loading).
+ *
+ * The browser already picks a candidate natively when the runtimes render
+ * `<picture>`/`srcset` — these helpers exist for the places that need the
+ * DECISION as data: preload warming at the right resolution, tooling, and
+ * the framework image-component recipes. The algorithm mirrors the HTML
+ * spec's srcset selection closely enough to be deterministic and
+ * unit-testable: parse candidates, derive the slot width from `sizes`,
+ * scale by DPR, pick the smallest candidate that covers the target
+ * (falling back to the largest available).
+ */
+import type { GalleryItem, ImageSources } from './items';
+export interface SrcsetCandidate {
+    url: string;
+    /** Width descriptor (`640w`) in px, if given. */
+    width?: number;
+    /** Density descriptor (`2x`), if given; bare candidates read as 1x. */
+    density?: number;
+}
+export interface Viewport {
+    width: number;
+    height: number;
+    /** devicePixelRatio; defaults to 1. */
+    dpr?: number;
+}
+/** Parse a `srcset` attribute string into candidates. Malformed entries
+ * are skipped rather than thrown — item data is author-provided. */
+export declare function parseSrcset(srcset: string | undefined): SrcsetCandidate[];
+/**
+ * Effective slot width (px) from a `sizes` attribute for a viewport.
+ * Supports the common authored forms deterministically: comma-separated
+ * `(min-width: Npx) <len>` / `(max-width: Npx) <len>` clauses with a
+ * bare `<len>` default, where `<len>` is `px` or `vw`. The first
+ * matching clause wins (spec order). Unsupported conditions are skipped;
+ * no match falls back to the full viewport width (`100vw`, the spec
+ * default).
+ */
+export declare function resolveSizes(sizes: string | undefined, viewportWidth: number): number;
+/** Whether a `<source media>` condition matches the viewport. Same
+ * deterministic subset as {@link resolveSizes}: min/max-width in px;
+ * unsupported conditions read as NOT matching. Absent media matches. */
+export declare function matchesMedia(media: string | undefined, viewport: Viewport): boolean;
+export interface ResolvedImageSource {
+    src: string;
+    /** Intrinsic width (px) when the winning candidate declared one. */
+    width?: number;
+    /** The `<source>` entry that won, when selection went through
+     * `sources` (picture semantics) rather than the item srcset. */
+    source?: ImageSources;
+}
+/**
+ * Deterministically resolve which image URL a viewport displays for an
+ * item, mirroring picture/srcset semantics: the first matching
+ * `sources[]` entry wins (spec order), then the item-level
+ * `srcset`/`sizes`, then plain `src`. Returns null for items with no
+ * image source at all.
+ */
+export declare function resolveImageSource(item: Pick<GalleryItem, 'src' | 'srcset' | 'sizes' | 'sources'>, viewport: Viewport): ResolvedImageSource | null;
+/**
+ * The width "actual size" zoom refers to. `img.naturalWidth` LIES under
+ * `srcset`/`sizes`: w-descriptor selection density-corrects the
+ * intrinsic size to roughly the layout slot — on phones that collapses
+ * the actual-size scale to ~1 and kills double-tap/pinch zoom. The
+ * resolution order mirrors what the item DECLARES before trusting the
+ * element: explicit `width` (2.x `data-width`), the largest candidate
+ * the srcset ladder can serve (first matching `sources[]` entry per
+ * picture semantics, else the item srcset), the `lgSize` natural dims,
+ * and only then the reported natural width. The declared tiers are what
+ * make optimizer components (next/image, NuxtImg, NgOptimizedImage) —
+ * which manage their own srcset — zoomable to full resolution.
+ */
+export declare function getActualSizeWidth(item: Pick<GalleryItem, 'width' | 'srcset' | 'sources' | 'lgSize'>, viewport: Viewport, naturalWidth: number): number;
+/**
+ * How long a slide waits on `img.decode()` before completing anyway —
+ * the gate must never strand a slide on a browser that rejects or
+ * stalls decode (huge images evict decoded data; some UAs reject on
+ * detached nodes).
+ */
+export declare const DECODE_TIMEOUT_MS = 500;
+/**
+ * Decode gate: resolve when the image is safe to paint — after
+ * `decode()` settles (success OR rejection; rejection still means the
+ * data arrived) or after the timeout, whichever is first. Browsers
+ * without `decode()` resolve immediately (the load event already
+ * fired). Never rejects.
+ */
+export declare function awaitDecode(img: {
+    decode?: () => Promise<void>;
+}, timeoutMs?: number): Promise<void>;