@readium/navigator-html-injectables 2.3.1 → 2.4.0-beta.2

package/src/modules/snapper/ColumnSnapper.ts

@@ -36,26 +36,50 @@ export class ColumnSnapper extends Snapper {
     private lastTurnTime: number = 0;
     private wnd!: ReadiumWindow;
     private comms!: Comms;
+    private rtl = false;
     private doc() { return this.wnd.document.scrollingElement as HTMLElement; }
     private scrollOffset() {
         // The reason we do this is because when the document is transformed (translate3d),
         // the scrollLeft value is 0 because... reasons. So we have to use the cached value
         // from this.alreadyScrollLeft instead.
-        return (this.doc().scrollLeft > 0) ? this.doc().scrollLeft : this.alreadyScrollLeft;
+        // Note: for RTL, scrollLeft is negative, so we check !== 0, not > 0.
+        const sl = this.doc().scrollLeft;
+        return (sl !== 0) ? sl : this.alreadyScrollLeft;
     }
 
     snapOffset(offset: number) {
-        const value = offset + (isRTL(this.wnd) ? -1 : 1);
+        const value = offset + (this.rtl ? -1 : 1);
         return value - (value % this.wnd.innerWidth);
     }
 
+    /**
+     * Snap a non-negative normalized offset (distance from document start) to
+     * the nearest page boundary. Works identically regardless of reading direction.
+     */
+    private snapNormOffset(offset: number): number {
+        const value = offset + 1;
+        return value - (value % this.wnd.innerWidth);
+    }
+
+    /**
+     * Normalized scroll position: distance from document start, always in
+     * [0, scrollWidth - innerWidth] regardless of reading direction.
+     * scrollLeft may be negative depending on the browser — Math.abs() normalizes it.
+     */
+    private normScroll(): number {
+        const raw = this.doc().scrollLeft || this.alreadyScrollLeft;
+        return this.rtl ? Math.abs(raw) : Math.max(0, this.wnd.scrollX > 0 ? this.wnd.scrollX : raw);
+    }
+
     reportProgress() {
-        // Contrary to ScrollTop, Android slightly adds to scrollX
-        // So we do not need to round it up
-        const scrollX = this.wnd.scrollX;
         const scrollWidth = this.cachedScrollWidth;
-        const progress = Math.max(0, Math.min(1, scrollX / scrollWidth));
-        const viewportEnd = Math.max(0, Math.min(1, (scrollX + this.wnd.innerWidth) / scrollWidth));
+        const viewportWidth = this.wnd.innerWidth;
+        const norm = this.normScroll();
+        const scrollable = Math.max(1, scrollWidth - viewportWidth);
+
+        // progress 0 = document start, 1 = document end — same regardless of direction.
+        const progress = Math.max(0, Math.min(1, norm / scrollable));
+        const viewportEnd = Math.max(0, Math.min(1, (norm + viewportWidth) / scrollWidth));
         this.comms.send("progress", {
             start: progress,
             end: viewportEnd
@@ -69,11 +93,17 @@ export class ColumnSnapper extends Snapper {
         if(this.overscroll !== 0 || this.shakeTimeout !== 0) return;
         const doc = this.doc();
 
-        doc.classList.add((isRTL(this.wnd) ? "readium-bounce-l" : "readium-bounce-r"));
+        // Bounce toward the boundary that was hit.
+        // LTR: end is on the right → bounce-r. RTL: start is on the right (norm≈0),
+        // end is on the left → bounce direction flips based on which boundary we're at.
+        const atStart = this.normScroll() < 5;
+        const bounceClass = this.rtl
+            ? (atStart ? "readium-bounce-r" : "readium-bounce-l")
+            : "readium-bounce-r";
+        doc.classList.add(bounceClass);
         const curScrollLeft = this.scrollOffset();
         this.shakeTimeout = this.wnd.setTimeout(() => {
-            doc.classList.remove("readium-bounce-l");
-            doc.classList.remove("readium-bounce-r");
+            doc.classList.remove(bounceClass);
             this.shakeTimeout = 0;
             this.doc().scrollLeft = curScrollLeft;
         }, 150);
@@ -95,33 +125,36 @@ export class ColumnSnapper extends Snapper {
 
     // Snaps the current offset to the page width.
     snapCurrentOffset(smooth=false, noprogress=false) {
-        const startX = this.wnd.scrollX > 0 ? this.wnd.scrollX : this.alreadyScrollLeft;
         const doc = this.doc();
-        const cdo = this.dragOffset();
         const columnCount = getColumnCountPerScreen(this.wnd);
-        const currentOffset = Math.min(Math.max(0, startX), this.cachedScrollWidth);
-        const factor = isRTL(this.wnd) ? -1 : 1;
-        const hurdle =
-            // The hurdle to overcome in order to change pages
-            factor *
-            (this.wnd.innerWidth / 3) *
-            ((factor * cdo) > 0 ? 2 : 1);
+        const maxScroll = this.cachedScrollWidth - this.wnd.innerWidth;
 
-        const so = this.snapOffset(currentOffset + hurdle);
+        // Work in normalized (non-negative, distance-from-start) coordinates
+        // so all arithmetic is direction-agnostic.
+        const currentNorm = Math.min(Math.max(0, this.normScroll()), maxScroll);
+
+        // Forward drag: LTR = drag left (cdo > 0), RTL = drag right (cdo < 0).
+        // Normalize so that positive = moving forward in reading order.
+        const cdo = this.dragOffset();
+        const normalizedCdo = this.rtl ? -cdo : cdo;
+        const hurdle = (this.wnd.innerWidth / 3) * (normalizedCdo > 0 ? 2 : 1);
 
-        const direction = so > this.scrollOffset() ? "right" : "left";
+        const snappedNorm = Math.min(maxScroll, Math.max(0, this.snapNormOffset(currentNorm + hurdle)));
 
-        this.checkSuspiciousSnap(direction, Math.abs(so - this.scrollOffset()));
+        // Convert back to signed scrollLeft for the actual DOM write.
+        const so = this.rtl ? -snappedNorm : snappedNorm;
+        const currentScrollLeft = this.rtl ? -currentNorm : currentNorm;
 
-        if(smooth && so !== this.scrollOffset()) { // Smooth snapping
+        const direction = so > currentScrollLeft ? "right" : "left";
+        this.checkSuspiciousSnap(direction, Math.abs(so - currentScrollLeft));
+
+        if(smooth && so !== currentScrollLeft) { // Smooth snapping
             this.snappingCancelled = false;
             const position = (start: number, end: number, elapsed: number, period: number) => {
-                if (elapsed > period) {
-                    return end;
-                }
+                if (elapsed > period) return end;
                 return start + (end - start) * easeInOutQuad(elapsed / period);
-            }
-            const period = /*Math.abs(startX - (this.useTransform ? currentOffset : 0)) < 10 ? 1 : */SNAP_DURATION * columnCount; // TODO revamp
+            };
+            const period = SNAP_DURATION * columnCount;
             let startTime: number;
             const step = (timestamp: number) => {
                 if(this.snappingCancelled) return;
@@ -130,7 +163,7 @@ export class ColumnSnapper extends Snapper {
                 const elapsed = timestamp - startTime;
 
                 const lpos = position(this.overscroll, 0, elapsed, period);
-                const spos = position(startX, so, elapsed, period);
+                const spos = position(currentScrollLeft, so, elapsed, period);
                 doc.scrollLeft = spos;
                 if(this.overscroll !== 0)
                     doc.style.transform = `translate3d(${-lpos}px, 0px, 0px)`;
@@ -143,7 +176,7 @@ export class ColumnSnapper extends Snapper {
                     doc.scrollLeft = so;
                     if(!noprogress) this.reportProgress();
                 }
-            }
+            };
             this.wnd.requestAnimationFrame(step);
         } else { // Instant snapping
             doc.style.removeProperty("transform");
@@ -193,18 +226,24 @@ export class ColumnSnapper extends Snapper {
         if(this.touchState === ScrollTouchState.MOVE) {
             // Get the horizontal drag distance
             const dragOffset = this.dragOffset();
-            const scrollOffset = this.scrollOffset();
-            // this.cachedScrollWidth = this.doc().scrollWidth!;
+
+            // Normalize: distance from document start, forward drag is positive.
+            const norm = this.normScroll();
+            const maxScroll = this.cachedScrollWidth - this.wnd.innerWidth;
+            const normalizedDrag = this.rtl ? -dragOffset : dragOffset;
+
             if(this.cachedScrollWidth <= this.wnd.innerWidth) {
                 // Only a single page, meaning any swipe triggers next/prev
                 this.reportProgress();
-                if(dragOffset > 5) this.comms.send("no_more", undefined);
-                if(dragOffset < -5) this.comms.send("no_less", undefined);
-            } else if(scrollOffset < 5 && dragOffset < 5) {
+                if(normalizedDrag > 5) this.comms.send("no_more", undefined);
+                if(normalizedDrag < -5) this.comms.send("no_less", undefined);
+            } else if(norm < 5 && normalizedDrag < 5) {
+                // At document start, tried to go backward
                 this.alreadyScrollLeft = 0;
                 this.comms.send("no_less", undefined);
-            } else if((this.cachedScrollWidth - scrollOffset - this.wnd.innerWidth) < 5 && dragOffset > 5) {
-                this.alreadyScrollLeft = this.cachedScrollWidth;
+            } else if((maxScroll - norm) < 5 && normalizedDrag > 5) {
+                // At document end, tried to go forward
+                this.alreadyScrollLeft = this.rtl ? -maxScroll : maxScroll;
                 this.comms.send("no_more", undefined);
             }
 
@@ -235,16 +274,22 @@ export class ColumnSnapper extends Snapper {
 
         const dro = this.dragOffset();
         const newpos = this.alreadyScrollLeft + dro;
-        if(newpos < 0) {
+
+        // For RTL, scrollLeft is in [-(scrollWidth - innerWidth), 0].
+        // For LTR, scrollLeft is in [0, scrollWidth - innerWidth].
+        const minScrollLeft = this.rtl ? -(this.cachedScrollWidth - this.wnd.innerWidth) : 0;
+        const maxScrollLeft = this.rtl ? 0 : (this.cachedScrollWidth - this.wnd.innerWidth);
+
+        if(newpos < minScrollLeft) {
             this.overscroll = newpos;
             this.doc().style.transform = `translate3d(${-this.overscroll}px, 0px, 0px)`;
-        } else if((newpos + this.wnd.innerWidth) > this.cachedScrollWidth) {
+        } else if(newpos > maxScrollLeft) {
             this.overscroll = newpos;
             this.doc().style.transform = `translate3d(${-newpos}px, 0px, 0px)`;
         } else {
             this.overscroll = 0;
             this.doc().style.removeProperty("transform");
-            this.doc().scrollLeft = this.alreadyScrollLeft + dro;
+            this.doc().scrollLeft = newpos;
         }
     }
     private readonly onTouchMover = this.onTouchMove.bind(this);
@@ -283,6 +328,7 @@ export class ColumnSnapper extends Snapper {
     mount(wnd: ReadiumWindow, comms: Comms): boolean {
         this.wnd = wnd;
         this.comms = comms;
+        this.rtl = isRTL(wnd);
         if(!super.mount(wnd, comms)) return false;
 
         wnd.navigator.epubReadingSystem && (wnd.navigator.epubReadingSystem.layoutStyle = "paginated");
@@ -371,10 +417,19 @@ export class ColumnSnapper extends Snapper {
             ack(true);
         });
 
+        // LTR only — snapOffset only works with non-negative values.
         const scrollToOffset = (offset: number): boolean => {
             const oldScrollLeft = this.doc().scrollLeft;
-            this.doc().scrollLeft = this.snapOffset(offset); // TODO assert if never undefined (same for rest of !)
+            this.doc().scrollLeft = this.snapOffset(offset);
+            return oldScrollLeft !== this.doc().scrollLeft;
+        }
 
+        // RTL: offset is normalized (non-negative, 0 = start, scrollable = end).
+        // Snaps to page boundary and sets scrollLeft = -snappedNorm.
+        const rtlScrollToNorm = (norm: number): boolean => {
+            const oldScrollLeft = this.doc().scrollLeft;
+            const snapped = this.snapNormOffset(Math.max(0, Math.min(this.cachedScrollWidth - wnd.innerWidth, norm)));
+            this.doc().scrollLeft = -snapped;
             return oldScrollLeft !== this.doc().scrollLeft;
         }
 
@@ -393,10 +448,13 @@ export class ColumnSnapper extends Snapper {
             }
             this.wnd.requestAnimationFrame(() => {
                 this.cachedScrollWidth = this.doc().scrollWidth!;
-                const documentWidth = this.cachedScrollWidth;
-                const factor = isRTL(wnd) ? -1 : 1;
-                const offset = documentWidth * position * factor;
-                this.doc().scrollLeft = this.snapOffset(offset);
+                const scrollable = this.cachedScrollWidth - wnd.innerWidth;
+                const norm = scrollable * position;
+                if (this.rtl) {
+                    this.doc().scrollLeft = -this.snapNormOffset(norm);
+                } else {
+                    this.doc().scrollLeft = this.snapOffset(norm);
+                }
                 this.reportProgress();
                 deselect(this.wnd);
                 ack(true);
@@ -410,7 +468,11 @@ export class ColumnSnapper extends Snapper {
                 return;
             }
             this.wnd.requestAnimationFrame(() => {
-                this.doc().scrollLeft = this.snapOffset(element.getBoundingClientRect().left + wnd.scrollX);
+                if (this.rtl) {
+                    this.doc().scrollLeft = -this.snapNormOffset(element.getBoundingClientRect().left + wnd.scrollX);
+                } else {
+                    this.doc().scrollLeft = this.snapOffset(element.getBoundingClientRect().left + wnd.scrollX);
+                }
                 this.reportProgress();
                 deselect(this.wnd);
                 ack(true);
@@ -441,7 +503,11 @@ export class ColumnSnapper extends Snapper {
                 return;
             }
             this.wnd.requestAnimationFrame(() => {
-                this.doc().scrollLeft = this.snapOffset(r.getBoundingClientRect().left + wnd.scrollX);
+                if (this.rtl) {
+                    this.doc().scrollLeft = -this.snapNormOffset(r.getBoundingClientRect().left + wnd.scrollX);
+                } else {
+                    this.doc().scrollLeft = this.snapOffset(r.getBoundingClientRect().left + wnd.scrollX);
+                }
                 this.reportProgress();
                 deselect(this.wnd);
                 ack(true);
@@ -449,12 +515,18 @@ export class ColumnSnapper extends Snapper {
         });
 
         comms.register("go_end", ColumnSnapper.moduleName, (_, ack) => {
-            const factor = isRTL(wnd) ? -1 : 1;
             this.wnd.requestAnimationFrame(() => {
                 this.cachedScrollWidth = this.doc().scrollWidth!;
-                const final = this.cachedScrollWidth * factor;
-                if(this.doc().scrollLeft === final) return ack(false);
-                this.doc().scrollLeft = this.snapOffset(final);
+                let snappedFinal: number;
+                if (this.rtl) {
+                    // RTL: end is the leftmost position, using normalized snapping first
+                    snappedFinal = -this.snapNormOffset(this.cachedScrollWidth - wnd.innerWidth);
+                } else {
+                    // LTR: end is scrollWidth (browser clamps to scrollWidth - innerWidth)
+                    snappedFinal = this.snapOffset(this.cachedScrollWidth);
+                }
+                if(this.doc().scrollLeft === snappedFinal) return ack(false);
+                this.doc().scrollLeft = snappedFinal;
                 this.reportProgress();
                 deselect(this.wnd);
                 ack(true);
@@ -474,11 +546,15 @@ export class ColumnSnapper extends Snapper {
         comms.register("go_prev", ColumnSnapper.moduleName, (_, ack) => {
             this.wnd.requestAnimationFrame(() => {
                 this.cachedScrollWidth = this.doc().scrollWidth!;
-                const offset = wnd.scrollX - wnd.innerWidth;
-                const minOffset = isRTL(wnd) ? - (this.cachedScrollWidth - wnd.innerWidth) : 0;
-                const change = scrollToOffset(Math.max(offset, minOffset));
+                let change: boolean;
+                if (this.rtl) {
+                    // RTL: go_prev = toward document start = decreasing norm = scrollLeft toward 0
+                    change = rtlScrollToNorm(this.normScroll() - wnd.innerWidth);
+                } else {
+                    change = scrollToOffset(wnd.scrollX - wnd.innerWidth);
+                }
+                this.reportProgress();
                 if(change) {
-                    this.reportProgress();
                     deselect(this.wnd);
                     this.checkSuspiciousSnap("left", this.wnd.innerWidth);
                 }
@@ -489,11 +565,15 @@ export class ColumnSnapper extends Snapper {
         comms.register("go_next", ColumnSnapper.moduleName, (_, ack) => {
             this.wnd.requestAnimationFrame(() => {
                 this.cachedScrollWidth = this.doc().scrollWidth!;
-                const offset = wnd.scrollX + wnd.innerWidth;
-                const maxOffset = isRTL(wnd) ? 0 : this.cachedScrollWidth - wnd.innerWidth;
-                const change = scrollToOffset(Math.min(offset, maxOffset));
+                let change: boolean;
+                if (this.rtl) {
+                    // RTL: go_next = toward document end = increasing norm = scrollLeft more negative
+                    change = rtlScrollToNorm(this.normScroll() + wnd.innerWidth);
+                } else {
+                    change = scrollToOffset(wnd.scrollX + wnd.innerWidth);
+                }
+                this.reportProgress();
                 if(change) {
-                    this.reportProgress();
                     deselect(this.wnd);
                     this.checkSuspiciousSnap("right", this.wnd.innerWidth);
                 }

package/types/src/Loader.d.ts

@@ -1,5 +1,5 @@
-import { ReadiumWindow } from "./helpers/dom";
-import { ModuleName } from "./modules";
+import { ReadiumWindow } from "./helpers/dom.ts";
+import { ModuleName } from "./modules/index.ts";
 /**
  * The Module loader. Handles initialization of the HTML injectables
  * in the target Window, which could be an IFrame, or the current window).

package/types/src/helpers/document.d.ts

@@ -1,5 +1,6 @@
 import { ReadiumWindow } from "./dom.ts";
 export declare function isRTL(wnd: ReadiumWindow): boolean;
+export declare function isVerticalLR(wnd: ReadiumWindow): boolean;
 export declare function getColumnCountPerScreen(wnd: ReadiumWindow): number;
 /**
 * Returns the "content height" of an element, which is its clientHeight

package/types/src/modules/ModuleLibrary.d.ts

@@ -1,5 +1,5 @@
 import { ModuleDerived } from "./Module.ts";
-export type ModuleName = "setup" | "snapper" | "column_snapper" | "scroll_snapper" | "webpub_snapper" | "fixed_setup" | "decorator" | "reflowable_setup" | "peripherals" | "webpub_setup" | "print_protection";
+export type ModuleName = "setup" | "snapper" | "column_snapper" | "scroll_snapper" | "cjk_vertical_snapper" | "webpub_snapper" | "fixed_setup" | "decorator" | "reflowable_setup" | "peripherals" | "webpub_setup" | "print_protection";
 export declare const FXLModules: ModuleName[];
 export declare const ReflowableModules: ModuleName[];
 export declare const WebPubModules: ModuleName[];

package/types/src/modules/snapper/CJKVerticalSnapper.d.ts

@@ -0,0 +1,58 @@
+import { Comms } from "../../comms/comms.ts";
+import { ReadiumWindow } from "../../helpers/dom.ts";
+import { ModuleName } from "../ModuleLibrary.ts";
+import { Snapper } from "./Snapper.ts";
+import { BaseSuspiciousActivityEvent } from "../Peripherals.ts";
+export interface SuspiciousCJKScrollingEvent extends BaseSuspiciousActivityEvent {
+    type: "suspicious_scrolling";
+    scrollDelta: number;
+    scrollDirection: "left" | "right";
+    targetElement: {
+        tagName: string;
+    } | null;
+}
+/**
+ * Snapper for CJK vertical writing (writing-mode: vertical-rl).
+ *
+ * In vertical-rl, content overflows on the X axis, flowing from right (start)
+ * to left (end). This snapper is the horizontal counterpart of ScrollSnapper:
+ * it tracks scrollLeft / scrollWidth / innerWidth and reports progress
+ * accordingly.
+ *
+ * Progress convention:
+ *   scrollLeft = 0 (right edge, document start)  →  progress 0
+ *   scrollLeft = ±(scrollWidth − clientWidth)    →  progress 1 (document end, left edge)
+ *
+ * All modern browsers use negative scrollLeft for vertical-rl (range: [−scrollable, 0]).
+ * Read it with Math.abs() to get a non-negative offset from document start.
+ * Write absolute positions as negative values (go_progression, go_end).
+ * Write relative adjustments as viewport-coordinate deltas (go_id, go_text) — this
+ * is sign-agnostic and works regardless of browser convention.
+ *
+ * go_next / go_prev always return false so that the navigator advances to the
+ * next or previous spine item — this snapper intentionally provides free
+ * horizontal scroll without intra-resource page fragmentation.
+ */
+export declare class CJKVerticalSnapper extends Snapper {
+    static readonly moduleName: ModuleName;
+    private wnd;
+    private comms;
+    private resizeObserver;
+    private patternAnalyzer;
+    private lastScrollTime;
+    private isScrollProtectionEnabled;
+    private initialScrollHandled;
+    private isScrolling;
+    private lastScrollLeft;
+    private isResizing;
+    private resizeDebounce;
+    private verticalLR;
+    private doc;
+    /** Total horizontally scrollable distance (magnitude). */
+    private scrollable;
+    private reportProgress;
+    private handleScroll;
+    private enableScrollProtection;
+    mount(wnd: ReadiumWindow, comms: Comms): boolean;
+    unmount(wnd: ReadiumWindow, comms: Comms): boolean;
+}

package/types/src/modules/snapper/ColumnSnapper.d.ts

@@ -19,9 +19,21 @@ export declare class ColumnSnapper extends Snapper {
     private lastTurnTime;
     private wnd;
     private comms;
+    private rtl;
     private doc;
     private scrollOffset;
     snapOffset(offset: number): number;
+    /**
+     * Snap a non-negative normalized offset (distance from document start) to
+     * the nearest page boundary. Works identically regardless of reading direction.
+     */
+    private snapNormOffset;
+    /**
+     * Normalized scroll position: distance from document start, always in
+     * [0, scrollWidth - innerWidth] regardless of reading direction.
+     * scrollLeft may be negative depending on the browser — Math.abs() normalizes it.
+     */
+    private normScroll;
     reportProgress(): void;
     private shakeTimeout;
     shake(): void;