@michaelyagi/shoji 0.1.0-alpha.10 → 0.1.0-alpha.12

package/dist/esm/core/Gallery.d.ts

@@ -30,6 +30,8 @@ export declare class Gallery {
     private autoHidden;
     private hoveredControlCount;
     private isClosing;
+    /** True while a vertical drag has hidden controls past its own distance threshold (`setControlsHiddenForDrag`) — `onActivity()` defers to it, since the drag's own continuous pointermove stream would otherwise immediately re-reveal what it just hid on every single move. */
+    private controlsHiddenByDrag;
     private itemList;
     private scannedElements;
     private activeIndex;
@@ -48,8 +50,22 @@ export declare class Gallery {
     private pluginCleanups;
     private readonly onContainerClick;
     private readonly onOuterClick;
-    /** DESIGN.md §2.8 — any interaction re-shows controls, restarts the idle clock. `autoHideDelay: 0` = "never show controls" — a no-op here. */
+    /**
+     * DESIGN.md §2.8 — any interaction re-shows controls, restarts the idle
+     * clock. `autoHideDelay: 0` = "never show controls" — a no-op here.
+     * `autoHideDelay: false` = "always visible" — also a no-op: nothing to
+     * reveal (already shown) or reschedule (no timer ever runs). Also a no-op
+     * once `isClosing` — a real bug, reported from real usage: moving the
+     * mouse during close()'s own controls-fade-then-zoom-out sequence (§2.6a)
+     * re-showed the just-hidden controls mid-animation, since these listeners
+     * stay wired for the whole close sequence. Same reasoning for
+     * `controlsHiddenByDrag` (§2.4/§2.8): a vertical drag's own `pointermove`
+     * stream would otherwise re-reveal what it just hid, every single frame.
+     */
     private readonly onActivity;
+    /** x */
+    private controlsHiddenAtGestureStart;
+    private readonly captureGestureStartState;
     private readonly onKeydown;
     constructor(target: HTMLElement | string, options?: GalleryOptions);
     /** Everything the constructor does after `this.element` is resolved — shared with `reinit()` (§2.7). */
@@ -102,7 +118,19 @@ export declare class Gallery {
      */
     getOriginElement(index: number): HTMLElement | null;
     private scheduleAutoHide;
-    private hideControls;
+    /**
+     * Forces the same fade §2.8's idle timer would eventually trigger —
+     * public so a plugin can hide controls on its own trigger. Same
+     * `isControlActive()` guard as the timer. Also a no-op under
+     * `autoHideDelay: false` — a real bug, reported from real usage: Autoplay's
+     * tap-to-toggle-chrome behavior called this directly and ignored `false`
+     * entirely, since only the idle timer checked it. `false` has to hold for
+     * every caller, not just the timer — `mobileSettings.controls: false` is
+     * affected the same way, by design. `forceHideControls()`/
+     * `setControlsHiddenForDrag()` (close, drag-to-close) deliberately don't
+     * check this — direct user actions with their own feedback, not auto-hide.
+     */
+    hideControls(): void;
     private showControls;
     /**
      * DESIGN.md §2.1 — `caption` is `string | HTMLElement | DangerousHtmlCaption`:
@@ -173,8 +201,52 @@ export declare class Gallery {
      */
     private applyMobileControlsSetting;
     close(): void;
+    /**
+     * DESIGN.md §2.4/§2.6a — same effect as `close()`, from a completed
+     * vertical swipe. `frozenDrag` is threaded through to `zoomOut()`'s own
+     * `dragStart`, so the whole close continues as one motion from exactly
+     * where the drag left off (see `GestureController.
+     * takeFrozenDragTransform`).
+     */
+    private closeFromSwipe;
+    /**
+     * `frozenDrag` — see `closeFromSwipe()`'s doc comment; absent for a
+     * button-close, which has no drag to continue from. Controls fade and the
+     * zoom-out run concurrently, both starting the instant `forceHideControls()`
+     * runs — not sequenced one after the other. (A previous version waited for
+     * the controls' own fade to fully finish before starting the zoom-out, for
+     * a button-close specifically — requested directly, to avoid stationary
+     * chrome hovering over an already-shrinking photo. Reversed on later,
+     * explicit feedback: waiting read as two distinct steps rather than one
+     * motion; starting both together still avoids stationary chrome, since
+     * the chrome is disappearing too, just without the pause.)
+     */
+    private beginClose;
+    /** Forces the same fade §2.8's idle timer would eventually trigger, bypassing `hideControls()`'s own `isControlActive()` hover guard — the most common close path (clicking close) is hovering a control at this exact instant, and a deliberate close should hide regardless. No-op if already hidden. */
+    private forceHideControls;
+    /**
+     * DESIGN.md §2.4/§2.8 — `GestureController`'s live vertical-drag cue: hide
+     * past the same distance a release would close, reveal again on retreat.
+     * `hidden: false` only reveals if visible when *this* gesture started
+     * (`controlsHiddenAtGestureStart`) — shouldn't resurrect controls already
+     * separately hidden (idle, or `autoHideDelay: 0`) before the drag began.
+     * `dragCloseThreshold` (bus event) fires on every crossing regardless of
+     * that guard — Autoplay (§4-autoplay) needs to know about the crossing
+     * itself, not just whether controls visibly moved.
+     */
+    private setControlsHiddenForDrag;
     /** `item.width`/`height`, else origin's `naturalWidth`/`naturalHeight` (accurate when `item.thumb` is unset). Feeds `computeTransform`'s letterbox-aware sizing. */
     private resolveAspectRatio;
+    /**
+     * `item.width`/`height` only — deliberately never a thumbnail's own
+     * `naturalWidth`/`naturalHeight` the way `resolveAspectRatio` above will:
+     * that's a fine stand-in for *shape*, but using it as the real photo's
+     * true pixel size would under-cap a genuinely large photo down to
+     * thumbnail resolution. `undefined` here just means "genuinely unknown,"
+     * not "assume small" — `zoomTransition.ts`'s `containedBox` already
+     * treats it that way (no cap applied at all).
+     */
+    private resolveNaturalSize;
     /**
      * Idempotent on purpose: a pending zoom-out's `transitionend`/fallback
      * timeout can still fire after `destroy()` has already force-finished the

package/dist/esm/core/GestureController.d.ts

@@ -1,12 +1,15 @@
 import { GestureEngineOptions } from '../gestures/GestureEngine';
 import { SlideManager } from './SlideManager';
+import { FrozenDragTransform } from './zoomTransition';
 /**
- * A real interactive control. Also used by `Gallery.ts`'s `isBackdropClick`,
- * which used to have its own narrower list (missing select/input/textarea/
- * a[href]) — a plugin-mounted non-button control got misread as a backdrop
- * click and closed the gallery. One shared selector so that can't recur.
+ * A real interactive control, plus `.shoji-caption` — a click/drag starting
+ * there should select/scroll its text natively, not get captured as a
+ * gesture. Also used by `Gallery.ts`'s `isBackdropClick`, which used to have
+ * its own narrower list (missing select/input/textarea/a[href]) — a
+ * plugin-mounted non-button control got misread as a backdrop click and
+ * closed the gallery. One shared selector so that can't recur.
  */
-export declare const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag]";
+export declare const INTERACTIVE_CONTROL_SELECTOR = "button, video, input, select, textarea, a[href], [data-shoji-no-drag], .shoji-caption";
 /** What `GestureController` needs from `Gallery` — narrow on purpose, so this module never reaches into Gallery internals beyond this contract. */
 export interface GestureControllerHost {
     dialog: HTMLElement;
@@ -16,6 +19,10 @@ export interface GestureControllerHost {
     next(): void;
     prev(): void;
     close(): void;
+    /** Same effect as `close()`, but for a completed vertical swipe — skips the separate controls-fade pause in front of the zoom-out (see `finishVerticalDrag`). */
+    closeFromSwipe(frozenDrag: FrozenDragTransform): void;
+    /** Live, reversible — crossing the close threshold mid-drag hides the toolbar/nav/counter/caption (a "let go now and this closes" cue); dragging back under it before release reveals them again. See `applyVerticalDragFeedback`. */
+    setControlsHiddenForDrag(hidden: boolean): void;
     /** `closable: false` (GalleryOptions) — false suspends vertical drag-to-close entirely: no live feedback, release never calls `close()`. */
     canClose(): boolean;
     onActivity(): void;
@@ -42,6 +49,10 @@ export interface GestureRelayCallbacks {
 export declare class GestureController {
     private readonly host;
     private readonly engine;
+    /** Same distance `GestureEngine` itself uses to decide a release would complete the close — reused here so the live controls-hide cue in `applyVerticalDragFeedback` actually means what it visually claims. */
+    private readonly controlsHideThreshold;
+    private controlsHiddenForDrag;
+    private lastDragDelta;
     constructor(host: GestureControllerHost, relay: GestureRelayCallbacks, options?: Partial<GestureEngineOptions>);
     destroy(): void;
     /** Horizontal follows the finger 1:1; vertical drives close-feedback instead. Axis-locked, one branch per drag. */
@@ -50,8 +61,33 @@ export declare class GestureController {
     /** `completed` decides intent; `canGoNext`/`canGoPrev` guard whether that's actually possible (`loop: false` at an end item). */
     private finishHorizontalDrag;
     private settleDragOffset;
-    /** Purely presentational drag feedback — scales/fades the dialog toward `close()`'s target state as the viewer drags, without closing until release decides the outcome. */
+    /**
+     * Purely presentational — scales/fades the *image* as it's dragged away,
+     * without closing until release decides. Applied to `host.slides.element`,
+     * not `host.dialog` — requested directly: toolbar/nav/counter/caption are
+     * siblings, not descendants, so they stay anchored, not moving with it.
+     */
     private applyVerticalDragFeedback;
     private clearVerticalDragFeedback;
     private finishVerticalDrag;
+    /**
+     * Reads the drag's last live appearance, instantly resets `.shoji-slides`
+     * back to neutral (nothing left on it to visibly snap — `Gallery` bakes
+     * these same values onto the photo itself in the same synchronous tick,
+     * so the rendered result is unchanged, just re-homed), and returns them
+     * for that hand-off. Translate is the raw, unclamped drag distance —
+     * requested directly: the close animation must continue from exactly
+     * where the drag left off, full stop, not recenter first. (A previous
+     * version clamped this to the same 160px the dim/scale feedback ramps
+     * over, to bound how far away the close animation could start — but
+     * clamping is itself an instant correction: for any drag past that
+     * distance, release visibly snapped the photo from wherever it actually
+     * was back to the clamped point, before the real shrink-to-thumbnail
+     * motion continued from there. That snap — not the shrink itself — is
+     * what reads as "jumps to a small image in the middle of the screen."
+     * Reported from real usage, confirmed on video: released past the clamp,
+     * the photo visibly jumped from off-screen back to near-center in a
+     * single frame.)
+     */
+    private takeFrozenDragTransform;
 }

package/dist/esm/core/SlideManager.d.ts

@@ -66,7 +66,33 @@ export declare class SlideManager {
     private moveIn;
     /** Starts decoding `item` for `index`, only if nothing already is (see `pending`). Resolves by looking up whichever slot currently wants this index, not the one active when the decode started. */
     private ensureImageDecoding;
-    /** DESIGN.md §2.3 — swaps the spinner for the placeholder once *it* decodes, not immediately: `item.thumb` is often just `item.src` again, so an undecoded placeholder can leave as long a blank gap as the spinner it replaces. */
+    /**
+     * DESIGN.md §2.3 — swaps the spinner for the placeholder once *it*
+     * decodes, not immediately: `item.thumb` is often just `item.src` again,
+     * so an undecoded placeholder can leave as long a blank gap as the
+     * spinner it replaces.
+     *
+     * A real bug: `.shoji-slide-open-placeholder`'s CSS unconditionally
+     * force-fills the frame (deliberate default: a real photo is usually
+     * bigger than the dialog). Wrong for a genuinely small photo with known
+     * `item.width`/`item.height` — same "grows too big, snaps down once real"
+     * symptom the zoom-in transition itself had (§2.3b), but that fix only
+     * governs the animated *transform*, not this placeholder's own CSS box
+     * once it settles. When `naturalSize` is known, sizes the placeholder
+     * explicitly instead, reusing `containedBox` (`zoomTransition.ts`) —
+     * unknown-size items keep the original force-fill guess.
+     *
+     * A second real bug in that same fix: measured `slot.media`'s own rect as
+     * "the container" — but `slot.media` is the exact element the zoom-in
+     * transition (§2.3b) animates a `scale()` transform on. `getBoundingClientRect()`
+     * reflects whatever transform is *currently* applied, and the placeholder's
+     * own decode typically resolves before that ~300ms animation settles — so
+     * this measured a still-small, mid-animation rect (often the origin
+     * thumbnail's own tiny size) instead of the real dialog size. `slot.root`
+     * (`.shoji-slide`) fixes it: same box, only ever `translateX`'d for
+     * pool-offset positioning, never scaled — a stable read regardless of
+     * what its child is mid-animation through.
+     */
     private revealOpenPlaceholder;
     /** Native `<video controls>` — real playback, not just a poster. Not autoplayed/muted: a deliberate click-to-play, not a background loop. */
     private renderVideo;

package/dist/esm/core/dom.d.ts

@@ -7,6 +7,7 @@ export interface LightboxLabels {
 }
 export interface LightboxDom {
     outer: HTMLElement;
+    backdrop: HTMLElement;
     dialog: HTMLElement;
     counter: HTMLElement;
     caption: HTMLElement;