lightgallery 2.9.0 → 3.0.0-beta.3

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>;

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

@@ -0,0 +1,268 @@
+/**
+ * Typed core settings and the non-mutating merge, ported from
+ * `src/lg-settings.ts` (2.x) with the ADR 0001 §7 renames applied:
+ * `appendSubHtmlTo` → `captionPosition`; DOM-scraping options
+ * (`selector`, `extraProps`, `getCaptionFromTitleOrAlt`, …), HTML-string
+ * options (`nextHtml`, `prevHtml`, `appendCounterTo`) and
+ * `supportLegacyBrowser` are gone. `container`, `addClass`/`className` and
+ * `index` are framework-layer props, not headless settings.
+ */
+export type GalleryMode = 'lg-slide' | 'lg-fade' | 'lg-zoom-in' | 'lg-zoom-in-big' | 'lg-zoom-out' | 'lg-zoom-out-big' | 'lg-zoom-out-in' | 'lg-zoom-in-out' | 'lg-soft-zoom' | 'lg-scale-up' | 'lg-slide-circular' | 'lg-slide-circular-vertical' | 'lg-slide-vertical' | 'lg-slide-vertical-growth' | 'lg-slide-skew-only' | 'lg-slide-skew-only-rev' | 'lg-slide-skew-only-y' | 'lg-slide-skew-only-y-rev' | 'lg-slide-skew' | 'lg-slide-skew-rev' | 'lg-slide-skew-cross' | 'lg-slide-skew-cross-rev' | 'lg-slide-skew-ver' | 'lg-slide-skew-ver-rev' | 'lg-slide-skew-ver-cross' | 'lg-slide-skew-ver-cross-rev' | 'lg-lollipop' | 'lg-lollipop-rev' | 'lg-rotate' | 'lg-rotate-rev' | 'lg-tube';
+/** Where slide captions render (2.x `appendSubHtmlTo`, without selectors). */
+export type CaptionPosition = 'bar' | 'slide' | 'outer';
+/**
+ * Gallery reading direction. `'auto'` inherits the page direction —
+ * resolved by the framework layer (this module is DOM-free, so `'auto'`
+ * reaches the runtimes unresolved, like `isMobile`).
+ */
+export type GalleryDirection = 'ltr' | 'rtl' | 'auto';
+/** `direction` with `'auto'` already resolved against the document. */
+export type ResolvedGalleryDirection = 'ltr' | 'rtl';
+/** Plan-010 virtualization knobs; the feature is off when the whole
+ *  object is absent. */
+export interface VirtualizationSettings {
+    /** Mounted-slide pool size (overrides `numberOfSlideItemsInDom`). */
+    slides?: number;
+    /**
+     * Thumbnail-strip windowing: overscan thumbs kept mounted on each
+     * side of the visible range, or 'auto' for one extra viewport.
+     */
+    thumbs?: 'auto' | number;
+}
+export interface GalleryCoreStrings {
+    closeGallery: string;
+    toggleMaximize: string;
+    previousSlide: string;
+    nextSlide: string;
+    download: string;
+    playVideo: string;
+    mediaLoadingFailed: string;
+    /** Accessible name of the gallery dialog when `ariaLabelledby` is not set. */
+    galleryLabel: string;
+    /**
+     * Template announced to assistive technology on every slide change.
+     * `{index}` and `{total}` are replaced with the 1-based slide position
+     * and the slide count; the slide caption, when present, is appended.
+     */
+    slideAnnouncement: string;
+    /** Label of the toolbar's More options menu button. */
+    moreOptions: string;
+    /** Share plugin: share button label. */
+    share: string;
+    /** Thumbnail plugin: strip toggle button label. */
+    toggleThumbnails: string;
+    /** Autoplay plugin: slideshow toggle button label. */
+    toggleAutoplay: string;
+    /** Fullscreen plugin: fullscreen toggle button label. */
+    toggleFullscreen: string;
+    /** Zoom plugin: zoom-in button label. */
+    zoomIn: string;
+    /** Zoom plugin: zoom-out button label. */
+    zoomOut: string;
+    /** Zoom plugin: actual-size button label. */
+    viewActualSize: string;
+    /** Rotate plugin: rotate-left button label. */
+    rotateLeft: string;
+    /** Rotate plugin: rotate-right button label. */
+    rotateRight: string;
+    /** Rotate plugin: horizontal flip button label. */
+    flipHorizontal: string;
+    /** Rotate plugin: vertical flip button label. */
+    flipVertical: string;
+    /** Comment plugin: comments toggle button label. */
+    toggleComments: string;
+}
+export interface CoreSettings {
+    /** Type of transition between slides. */
+    mode: GalleryMode;
+    /** Slide animation CSS easing property. */
+    easing: string;
+    /** Transition duration in ms. */
+    speed: number;
+    /**
+     * Commercial license key. lightGallery 3 keys start with `LIG`;
+     * `0000-0000-000-0000` is the temporary testing key.
+     */
+    licenseKey: string;
+    /** Height of the gallery, e.g. '100%', '300px'. */
+    height: string;
+    /** Width of the gallery, e.g. '100%', '300px'. */
+    width: string;
+    /**
+     * Start animation class applied to the outer element while opening when
+     * no zoom-from-origin transform is available. Empty string disables.
+     */
+    startClass: string;
+    /**
+     * Animate the opening slide from the trigger thumbnail's bounding rect.
+     * Needs the natural image size via the item's `lgSize` field; falls back
+     * to `startClass` when unavailable. On close, a slide with no thumbnail
+     * to return to (its trigger is hidden or collapsed behind a "+9 photos"
+     * tile, it has no `lgSize`, or the items came without trigger elements)
+     * shrinks to the centre of the stage and fades instead of flying to a
+     * thumbnail it cannot reach.
+     */
+    zoomFromOrigin: boolean;
+    /** Zoom-from-origin animation duration in ms. */
+    startAnimationDuration: number;
+    /** Backdrop fade duration in ms. */
+    backdropDuration: number;
+    /** Delay in ms before hiding controls on idle. 0 keeps them visible. */
+    hideBarsDelay: number;
+    /** Delay before the idle-hide behavior arms after opening. */
+    showBarsAfter: number;
+    /** Delay slide transitions in ms (`lg-slide-progress` window). */
+    slideDelay: number;
+    /** If true, toolbar/captions/thumbnails may overlap the media. */
+    allowMediaOverlap: boolean;
+    /** Default video size as `"width-height"`. */
+    videoMaxSize: string;
+    /** Automatically load poster images for YouTube videos. */
+    loadYouTubePoster: boolean;
+    /** Caption height used for media positioning when overlap is off. */
+    defaultCaptionHeight: number;
+    /** aria-labelledby attribute for the gallery dialog. */
+    ariaLabelledby: string;
+    /** aria-describedby attribute for the gallery dialog. */
+    ariaDescribedby: string;
+    /** Hide the page scrollbar (with padding compensation) while open. */
+    hideScrollbar: boolean;
+    /** Restore the previous scroll position when the gallery closes. */
+    resetScrollPosition: boolean;
+    /** If false the gallery cannot be closed (inline galleries). */
+    closable: boolean;
+    /** Allow vertical drag/swipe to close (forced off when not closable). */
+    swipeToClose: boolean;
+    /** Close when clicking the black area around the slide. */
+    closeOnTap: boolean;
+    /** Show the close button. */
+    showCloseIcon: boolean;
+    /** Show the maximize button (inline galleries). */
+    showMaximizeIcon: boolean;
+    /**
+     * Keep the toolbar on one row: when its buttons do not fit beside the
+     * counter, the lowest-priority ones move into a "More options" menu.
+     * Set to `false` to let the buttons wrap onto a second row instead.
+     */
+    toolbarOverflow: boolean;
+    /**
+     * Show the toolbar buttons that repeat a touch gesture: zoom in, zoom
+     * out and actual size (pinch and double-tap do the same). On by
+     * default; `mobileSettings` turns it off on touch devices.
+     */
+    showGestureButtons: boolean;
+    /** Loop back to the first slide from the last. */
+    loop: boolean;
+    /** Close on Escape. */
+    escKey: boolean;
+    /** Keyboard navigation (arrow keys). */
+    keyPress: boolean;
+    /** Trap focus within the gallery. */
+    trapFocus: boolean;
+    /** Show prev/next buttons. */
+    controls: boolean;
+    /** Bounce animation when navigating past the ends without loop. */
+    slideEndAnimation: boolean;
+    /**
+     * Disable prev/next buttons on first/last slide. Ignored (forced false)
+     * when `loop` or `slideEndAnimation` is on — 2.x parity.
+     */
+    hideControlOnEnd: boolean;
+    /** Navigate on mousewheel. */
+    mousewheel: boolean;
+    /**
+     * Gallery reading direction: keyboard arrows, swipe advance and the
+     * slide/thumbnail transforms follow it. Visual mirroring is the
+     * opt-in `lg-rtl.css` layer — load it whenever this resolves to
+     * `'rtl'`. `'auto'` inherits the page direction; the default stays
+     * `'ltr'` so upgrades never change behavior on existing pages.
+     */
+    direction: GalleryDirection;
+    /** Where slide captions render. */
+    captionPosition: CaptionPosition;
+    /** Number of slides to preload around the current slide. */
+    preload: number;
+    /** How many slide elements are kept mounted at a time (minimum 3). */
+    numberOfSlideItemsInDom: number;
+    /** iframe slide width. */
+    iframeWidth: string;
+    /** iframe slide height. */
+    iframeHeight: string;
+    /** iframe slide max width. */
+    iframeMaxWidth: string;
+    /** iframe slide max height. */
+    iframeMaxHeight: string;
+    /** Show the download button. */
+    download: boolean;
+    /** Show the slide counter. */
+    counter: boolean;
+    /** Minimum swipe distance in px to change slides. */
+    swipeThreshold: number;
+    /**
+     * Release velocity (px/ms, measured over the gesture's final
+     * ~100ms) at which a short swipe still changes slides — a flick.
+     */
+    flickVelocity: number;
+    /**
+     * Pinching down on an un-zoomed image and releasing closes the
+     * gallery (iOS Photos). Guarded: a pinch that went past fit zoom
+     * at any point is a zoom correction and never closes. Requires
+     * `closable`.
+     */
+    pinchToClose: boolean;
+    /** Enable touch swipe. */
+    enableSwipe: boolean;
+    /** Enable desktop mouse drag. */
+    enableDrag: boolean;
+    /**
+     * Large-gallery virtualization (plan 010). Off when undefined — the
+     * 2.x behavior: every thumbnail renders and the mounted-slide window
+     * is `numberOfSlideItemsInDom`. `slides` overrides the mounted-slide
+     * pool size; `thumbs` turns on thumbnail-strip windowing (only the
+     * visible thumbs plus an overscan render, with spacers preserving the
+     * strip geometry) — a number is the overscan thumb count per side,
+     * 'auto' derives one extra viewport per side. The window advances at
+     * commit points (release, slide change, resize), never per
+     * pointermove — interaction stays zero-reactivity.
+     */
+    virtualization?: VirtualizationSettings;
+    /**
+     * Announce slide changes to assistive technology through a dedicated
+     * polite live region (`strings.slideAnnouncement` + the slide caption).
+     * While enabled, the counter and caption bar are not separate live
+     * regions — the announcer is the single source of slide-change
+     * announcements. Set to `false` to restore the 2.x behavior (live
+     * counter and caption, no announcer).
+     */
+    ariaAnnouncements: boolean;
+    /** Localizable UI strings. */
+    strings: GalleryCoreStrings;
+    /** Detect mobile devices; defaults to a UA sniff in the framework layer. */
+    isMobile?: () => boolean;
+    /** Settings overrides applied when a mobile device is detected. */
+    mobileSettings: MobileSettings;
+}
+export type MobileSettings = Partial<Omit<CoreSettings, 'mobileSettings' | 'isMobile'>>;
+/** User-facing shape: everything optional, strings mergeable per-key. */
+export type UserSettings = Partial<Omit<CoreSettings, 'strings'>> & {
+    strings?: Partial<GalleryCoreStrings>;
+};
+export declare const coreSettingsDefaults: CoreSettings;
+export interface ResolveSettingsOptions {
+    /**
+     * Whether the current device is mobile — decided by the framework layer
+     * (headless cannot touch `navigator`). Applies `mobileSettings`.
+     */
+    isMobile?: boolean;
+    /**
+     * Plugin default settings merged below user settings (plugin runtime). Merged
+     * left-to-right, never mutating any input.
+     */
+    pluginDefaults?: ReadonlyArray<Partial<CoreSettings>>;
+}
+/**
+ * Merge defaults + plugin defaults + user settings + mobile overrides into a
+ * resolved settings object. Non-mutating by construction: every input object
+ * is left untouched (2.x mutated `settings` in place; 3.x never does).
+ */
+export declare function resolveSettings(user?: UserSettings, options?: ResolveSettingsOptions): CoreSettings;