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

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;

package/dist/types/headless/share-urls.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Share link builders + Web Share payload logic for the share plugin. The
+ * URL builders are ported from the 2.x `lg-*-share-utils` files as pure
+ * functions — the page URL fallback is a parameter instead of
+ * `window.location.href`. The Web Share helpers are pure too: the runtime
+ * hands in a structural `navigator` so nothing here touches the DOM.
+ */
+/**
+ * Structural slice of a gallery item the share builders read — kept
+ * narrow so any runtime's item shape (including the 2.x vanilla one)
+ * satisfies it without casts.
+ */
+export interface ShareItemFields {
+    src?: string;
+    alt?: string;
+    title?: string;
+    shareUrl?: string;
+    facebookShareUrl?: string;
+    tweetText?: string;
+    twitterShareUrl?: string;
+    pinterestShareUrl?: string;
+    pinterestText?: string;
+}
+export declare function getFacebookShareLink(item: ShareItemFields, currentUrl: string): string;
+/**
+ * X (formerly Twitter) intent URL. The 2.x `tweetText`/`twitterShareUrl`
+ * item fields (and their `data-tweet-text` style attributes) keep working —
+ * only the target changed. Unlike the 2.x builder the text is URL-encoded.
+ */
+export declare function getXShareLink(item: ShareItemFields, currentUrl: string): string;
+/** @deprecated Renamed — use {@link getXShareLink} (X intent URL). */
+export declare const getTwitterShareLink: typeof getXShareLink;
+export declare function getPinterestShareLink(item: ShareItemFields, currentUrl: string): string;
+/**
+ * Data handed to `navigator.share`. URL-sharing only by design: attaching
+ * the image itself would require fetching cross-origin bytes (a proxy),
+ * which the share plugin will not do.
+ */
+export interface SharePayload {
+    title?: string;
+    text?: string;
+    url: string;
+}
+/**
+ * Build the Web Share payload for a slide. The per-item `shareUrl` wins,
+ * then the network-specific share URLs, then the page URL; text falls back
+ * from the tweet text to the Pinterest description.
+ */
+export declare function getSharePayload(item: ShareItemFields, currentUrl: string): SharePayload;
+/** Structural slice of `navigator` the Web Share decision needs. */
+export interface NativeShareNavigator {
+    share?: (data: SharePayload) => Promise<void>;
+    canShare?: (data: SharePayload) => boolean;
+}
+/**
+ * True when the runtime can hand this payload to the OS share sheet.
+ * Feature-detected and never load-bearing: no `navigator.share` (or a
+ * `canShare` veto) simply keeps the branded dropdown menu.
+ */
+export declare function canNativeShare(nav: NativeShareNavigator | undefined | null, payload: SharePayload): boolean;

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

@@ -0,0 +1,42 @@
+/**
+ * Gesture-release physics: momentum projection and a damped-spring
+ * stepper. Releases compute where momentum would land (`project`),
+ * clamp that into bounds, and animate there with a spring seeded by the
+ * live release velocity — velocity stays continuous across the
+ * finger-lift boundary, which is most of what native feel is.
+ *
+ * The stepper advances the standard damped harmonic oscillator by its
+ * closed-form solution over each frame, so step size never affects the
+ * trajectory and the state (position + velocity) can re-seed a new
+ * spring at any interruption point.
+ */
+export interface SpringState {
+    position: number;
+    /** px per ms (same unit as the windowed gesture velocity). */
+    velocity: number;
+}
+export interface SpringConfig {
+    /** 1 = never overshoot; < 1 overshoots and returns. */
+    dampingRatio?: number;
+    /** Rad/s — higher settles faster. */
+    naturalFrequency?: number;
+}
+/** Settling toward an in-bounds target: no overshoot. */
+export declare const SPRING_SETTLE_DAMPING = 1;
+/** Settling against a clamped bound: one soft bounce. */
+export declare const SPRING_BOUNCE_DAMPING = 0.82;
+export declare const SPRING_NATURAL_FREQUENCY = 12;
+/**
+ * Momentum projection: how far a release keeps traveling when it loses
+ * `1 - decelerationRate` of its velocity every millisecond (the classic
+ * scroll-view constant; 0.995 ≈ half a percent per ms).
+ */
+export declare const DECELERATION_RATE = 0.995;
+export declare function project(velocity: number, decelerationRate?: number): number;
+/**
+ * Advance a spring toward `target` by `dtMs`, exactly (closed form with
+ * the current state as initial conditions).
+ */
+export declare function stepSpring(state: SpringState, target: number, dtMs: number, { dampingRatio, naturalFrequency, }?: SpringConfig): SpringState;
+/** Whether a spring is close enough to stop animating. */
+export declare function isSpringSettled(state: SpringState, target: number, restDelta?: number, restVelocity?: number): boolean;

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

@@ -0,0 +1,63 @@
+/**
+ * Framework-free gallery state machine. React (and later Angular/Vue) wrap
+ * this with their own reactivity; every transition lives here so behavior is
+ * identical across frameworks and testable without any DOM.
+ */
+export type SlideDirection = 'next' | 'prev';
+export interface GalleryState {
+    open: boolean;
+    currentIndex: number;
+    previousIndex: number;
+    slidesCount: number;
+    loop: boolean;
+    /**
+     * True once any slide media has finished loading (or failed) since the
+     * gallery opened — 2.x `lGalleryOn`. Distinguishes the first slide
+     * (backdrop/zoom entrance, no slide animation) from navigation.
+     */
+    galleryOn: boolean;
+    /**
+     * True while a slide transition runs — 2.x `lgBusy`. Navigation actions
+     * are ignored until `TRANSITION_END`.
+     */
+    transitioning: boolean;
+    /** Direction of the last navigation; drives prev/next slide classes. */
+    slideDirection?: SlideDirection;
+    /** Indexes whose media has fully loaded (`lg-complete`). */
+    loadedSlides: ReadonlySet<number>;
+}
+export type GalleryAction = {
+    type: 'OPEN';
+    index?: number;
+} | {
+    type: 'CLOSE';
+} | {
+    type: 'GO_TO';
+    index: number;
+    direction?: SlideDirection;
+} | {
+    type: 'NEXT';
+} | {
+    type: 'PREV';
+} | {
+    type: 'SET_SLIDES_COUNT';
+    count: number;
+} | {
+    type: 'SET_LOOP';
+    loop: boolean;
+} | {
+    type: 'SLIDE_LOADED';
+    index: number;
+} | {
+    type: 'SLIDE_ERROR';
+    index: number;
+} | {
+    type: 'TRANSITION_END';
+};
+export interface CreateGalleryStateOptions {
+    slidesCount: number;
+    loop?: boolean;
+    index?: number;
+}
+export declare function createGalleryState(options: CreateGalleryStateOptions): GalleryState;
+export declare function galleryReducer(state: GalleryState, action: GalleryAction): GalleryState;

package/dist/types/headless/thumb-math.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Thumbnail strip math (2.x `animateThumb`/`getPossibleTransformX`) as pure
+ * functions for the thumbnail plugin.
+ */
+import type { ResolvedGalleryDirection } from './settings';
+export type ThumbPagerPosition = 'left' | 'middle' | 'right';
+/**
+ * Rubber-band a raw strip translate (plan 010 physics): inside the
+ * bounds it passes through; beyond an edge the overshoot compresses by
+ * the shared edge friction so the strip resists like the slide gestures.
+ * The release spring pulls the compressed overshoot back to the bound.
+ */
+export declare function getElasticThumbTranslate(raw: number, totalWidth: number, stripWidth: number, friction?: number): number;
+export declare function getThumbTotalWidth(count: number, thumbWidth: number, thumbMargin: number): number;
+/** Clamp a strip translate into `[0, total - visible]` (never negative). */
+export declare function clampThumbTranslate(translate: number, totalWidth: number, stripWidth: number): number;
+/**
+ * The window of thumbnails that must exist in the DOM for a given strip
+ * translate (plan 010 virtualization): the visible range plus `overscan`
+ * thumbs on each side, with leading/trailing pad widths so the strip keeps
+ * its full scroll geometry while only the window renders.
+ */
+export interface ThumbWindow {
+    /** First rendered thumb index (inclusive). */
+    start: number;
+    /** Last rendered thumb index (inclusive). */
+    end: number;
+    /** Spacer width (px) standing in for the thumbs before `start`. */
+    leadingPad: number;
+    /** Spacer width (px) standing in for the thumbs after `end`. */
+    trailingPad: number;
+}
+/**
+ * Compute the rendered thumb window from the strip translate. `overscan`
+ * is the number of extra thumbs kept mounted on each side of the visible
+ * range ('auto' derives one extra viewport per side — enough that a full
+ * flick lands on already-rendered thumbs).
+ */
+export declare function getThumbWindow(options: {
+    translate: number;
+    stripWidth: number;
+    thumbWidth: number;
+    thumbMargin: number;
+    count: number;
+    overscan?: number | 'auto';
+}): ThumbWindow;
+/**
+ * Window covering a fling's whole flight path (plan 010): the union of
+ * the windows at the start and end translates, so a released strip never
+ * glides over unrendered thumbs — the destination is known at release.
+ */
+export declare function getThumbCorridorWindow(options: {
+    from: number;
+    to: number;
+    stripWidth: number;
+    thumbWidth: number;
+    thumbMargin: number;
+    count: number;
+    overscan?: number | 'auto';
+}): ThumbWindow;
+/**
+ * Which slide a live strip translate selects in scrub mode (the strip
+ * drives the gallery while it moves). Proportional: the strip's full
+ * scroll travel maps onto the full index range, so the FIRST and LAST
+ * slides are always reachable — a fixed pager-point inverse cannot
+ * reach the ends, because the clamped translate never brings them
+ * under the pager slot. For long strips this converges to one index
+ * per thumb unit of travel. Translate is the logical strip scalar
+ * (RTL-agnostic); elastic overshoot clamps, pinning the ends.
+ * Exact inverse: {@link getScrubThumbTranslate}.
+ */
+export declare function getScrubThumbIndex(translate: number, totalWidth: number, stripWidth: number, count: number): number;
+/**
+ * Strip translate at which {@link getScrubThumbIndex} resolves exactly
+ * `index` — for aligning the strip to the scrubbed slide after the
+ * release glide settles. (Not `getActiveThumbTranslate`: that pager
+ * alignment is a different map and would re-resolve to a neighboring
+ * index near the ends.)
+ */
+export declare function getScrubThumbTranslate(index: number, totalWidth: number, stripWidth: number, count: number): number;
+/**
+ * Strip translate that brings the active thumbnail to the pager position
+ * (2.x `animateThumb`, including its off-by-one `- 1`).
+ */
+export declare function getActiveThumbTranslate(index: number, thumbWidth: number, thumbMargin: number, stripWidth: number, totalWidth: number, pagerPosition: ThumbPagerPosition, direction?: ResolvedGalleryDirection): number;

package/dist/types/headless/toolbar-overflow.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Toolbar overflow: when the toolbar's icon buttons do not fit on one row
+ * beside the counter, the lowest-priority buttons move into a "More
+ * options" menu. Pure layout arithmetic over measured widths; each runtime
+ * measures its own DOM, applies the result and renders the menu.
+ */
+/** Priority of a button that never moves into the menu (close). */
+export declare const TOOLBAR_PINNED: number;
+/** Priority of a button the table does not know (custom plugin buttons). */
+export declare const TOOLBAR_DEFAULT_PRIORITY = 20;
+/** Overflow priority of a toolbar button from its class names. */
+export declare function getToolbarItemPriority(classList: Iterable<string>): number;
+export interface ToolbarOverflowItem {
+    /** Measured width, px. */
+    width: number;
+    /** From {@link getToolbarItemPriority}; higher stays longer. */
+    priority: number;
+}
+export interface ToolbarOverflowInput {
+    /** Width of the toolbar row, px. */
+    available: number;
+    /** Width taken by content that never moves (the counter), px. */
+    reserved: number;
+    /** Width of the More button, px. */
+    moreWidth: number;
+    /** The toolbar's icon buttons, in DOM order. */
+    items: readonly ToolbarOverflowItem[];
+}
+/**
+ * Indices (in DOM order) of the buttons that move into the menu; empty
+ * when everything fits, or when the toolbar has no width yet (not laid
+ * out). Lowest priority moves first; among equals, the button later in
+ * DOM order goes first, which is the one furthest from the close button.
+ * The More button's own width is paid as soon as anything moves.
+ */
+export declare function getToolbarOverflow({ available, reserved, moreWidth, items, }: ToolbarOverflowInput): number[];
+/**
+ * Whether a click's event path runs through the toolbar. Clicks there are
+ * controls, not a tap on the backdrop: Medium zoom closes on the latter
+ * only. The path (`event.composedPath()`) still lists a More menu item the
+ * click already removed from the document.
+ */
+export declare function isToolbarEventPath(path: readonly unknown[]): boolean;
+/** What the dismissal of a toolbar menu reads from the dismissing press. */
+export interface MenuDismissEvent {
+    target: unknown;
+    preventDefault(): void;
+    stopPropagation(): void;
+}
+/**
+ * A press outside an open toolbar menu (the More options menu, the share
+ * dropdown) dismisses it. A press on a control passes through, so one
+ * click on another toolbar button both dismisses the menu and runs the
+ * button. A press on the backdrop around the slide is consumed instead:
+ * there the gallery's own tap-to-close and drag would fire, and
+ * dismissing a menu must not also close the gallery. Cancelling the
+ * pointerdown suppresses the compatibility mouse events the vanilla
+ * runtime listens to; stopping it keeps the pointer-driven runtimes'
+ * handlers from arming. Returns whether the press was consumed.
+ */
+export declare function consumeBackdropPress(event: MenuDismissEvent): boolean;

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

@@ -0,0 +1,33 @@
+/**
+ * Settle gate for a CSS transition: call back once the transition of
+ * `property` on `element` has actually ended.
+ *
+ * A fixed timer measured from the moment the target value is applied
+ * lands at the same wall-clock offset whether or not the transition has
+ * started, but the transition only starts at the first style recalc
+ * after the value lands — on a busy main thread (a gallery's first
+ * layout, a big thumbnail decode) that can be well past the offset.
+ * Anything gated on the fixed timer then fires mid-flight.
+ *
+ * Contract:
+ * - No `transitionstart` within `fallbackMs` → the element is not
+ *   transitioning (reduced motion, identity transform, no CSS) and the
+ *   gate settles on the timer, exactly like the fixed timer did.
+ * - `transitionstart` re-bases the timer on the real start; `transitionend`
+ *   settles immediately. Interrupted transitions (`transitioncancel`)
+ *   leave the timer running so a restart still settles in time.
+ * - Events bubbling from descendants, or for other properties, are
+ *   ignored. The callback runs at most once.
+ *
+ * Returns a disposer; disposing after settle is a no-op.
+ */
+export interface TransitionSettleEvent {
+    target: unknown;
+    propertyName?: string;
+}
+/** Structural slice of a DOM element: headless carries no DOM lib. */
+export interface TransitionSettleTarget {
+    addEventListener(type: string, listener: (event: TransitionSettleEvent) => void): void;
+    removeEventListener(type: string, listener: (event: TransitionSettleEvent) => void): void;
+}
+export declare function onTransitionSettle(element: TransitionSettleTarget, property: string, fallbackMs: number, callback: () => void): () => void;

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

@@ -0,0 +1,31 @@
+/**
+ * Rolling-window velocity tracking. Release decisions must read the
+ * velocity of the gesture's final instant, not its whole-gesture
+ * average: a drag that pauses and then flicks reads fast, and a drag
+ * that ends resting reads zero. Sessions push a sample per move; the
+ * release reads the window ending at the release timestamp.
+ */
+export interface VelocitySample {
+    x: number;
+    y: number;
+    /** Timestamp in ms (same clock as the release read). */
+    t: number;
+}
+export interface Velocity {
+    /** px/ms, signed. */
+    x: number;
+    y: number;
+}
+/** How far back a release looks when reading the gesture velocity. */
+export declare const VELOCITY_WINDOW_MS = 100;
+/**
+ * Append a sample, pruning everything older than the window — the
+ * buffer stays a handful of entries regardless of gesture length.
+ */
+export declare function pushVelocitySample(samples: readonly VelocitySample[], sample: VelocitySample, windowMs?: number): VelocitySample[];
+/**
+ * Velocity (px/ms per axis) over the samples inside the window ending
+ * at `releaseTime`. Fewer than two recent samples — the finger rested
+ * before lifting — reads as zero, as does sub-pixel drift.
+ */
+export declare function getWindowedVelocity(samples: readonly VelocitySample[], releaseTime: number, windowMs?: number): Velocity;