@readium/navigator-html-injectables 2.4.4 → 2.6.0

package/src/helpers/document.ts

@@ -1,19 +1,139 @@
 import { ReadiumWindow } from "./dom.ts";
 
-export function isRTL(wnd: ReadiumWindow): boolean {
+export function isRTL(wnd: Window): boolean {
     // Check documentElement first, then fall back to body.
     const dir = wnd.document.documentElement.dir || wnd.document.body.dir;
     return dir.toLowerCase() === "rtl";
 }
 
-export function isVerticalLR(wnd: ReadiumWindow): boolean {
+export function isVerticalLR(wnd: Window): boolean {
     // Check documentElement first, then fall back to body.
     const writingMode = wnd.getComputedStyle(wnd.document.documentElement).writingMode
         || wnd.getComputedStyle(wnd.document.body).writingMode;
     return writingMode === 'vertical-lr';
 }
 
-export function getColumnCountPerScreen(wnd: ReadiumWindow): number {
+export function isVerticalWriting(wnd: Window): boolean {
+    const writingMode = wnd.getComputedStyle(wnd.document.documentElement).writingMode
+        || wnd.getComputedStyle(wnd.document.body).writingMode;
+    return writingMode === 'vertical-rl' || writingMode === 'vertical-lr';
+}
+
+/**
+ * Axis-normalizing context for decoration layout.
+ *
+ * Translates CSS physical properties into logical inline/block terms so that
+ * callers can position elements identically regardless of writing mode:
+ *
+ *   horizontal writing  →  inline = horizontal, block = vertical
+ *   vertical writing    →  inline = vertical,   block = horizontal
+ */
+export interface WritingContext {
+    isVertical: boolean;
+    isVertLR: boolean;
+    /** Viewport size along the inline axis (innerWidth / innerHeight). */
+    viewportInlineSize: number;
+    /** Viewport size along the block axis (innerHeight / innerWidth). */
+    viewportBlockSize: number;
+    /**
+     * Size of a single page along the inline axis.
+     * Horizontal: viewportWidth / columnCount.
+     * Vertical: viewportHeight (no columns).
+     */
+    pageInlineSize: number;
+    /**
+     * Physical x offset to add to a client-space x coordinate to get document space.
+     * Horizontal: scrollLeft (non-negative).
+     * Vertical-rl: scrollWidth − viewportWidth + scrollLeft (scrollLeft is negative,
+     *   so this normalises it to the viewport's left edge in document coordinates).
+     * Vertical-lr: scrollLeft (non-negative, same as horizontal).
+     */
+    xDocOffset: number;
+    /** Physical y offset to add to a client-space y coordinate to get document space (scrollTop). */
+    yDocOffset: number;
+    /** Scroll offset along the inline axis, derived from xDocOffset / yDocOffset. */
+    inlineScrollOffset: number;
+    /** Scroll offset along the block axis, derived from xDocOffset / yDocOffset. */
+    blockScrollOffset: number;
+
+    /** Logical inline start of a rect (left / top). */
+    inlineStart(r: DOMRect | { top: number; left: number }): number;
+    /** Logical block start of a rect (top / left). */
+    blockStart(r: DOMRect | { top: number; left: number }): number;
+    /** Logical inline size of a rect (width / height). */
+    inlineSize(r: DOMRect | { width: number; height: number }): number;
+    /** Logical block size of a rect (height / width). */
+    blockSize(r: DOMRect | { width: number; height: number }): number;
+
+    /**
+     * Set absolute position on an element using logical coordinates.
+     * `iz` is the inverse zoom factor (1 in non-Blink, 1/zoom in Blink).
+     */
+    applyPosition(el: HTMLElement, inlineStart: number, blockStart: number, inlineSize: number, blockSize: number, iz: number): void;
+
+    /** Convert logical coordinates back to a physical DOMRect. */
+    toRect(inlineStart: number, blockStart: number, inlineSize: number, blockSize: number): DOMRect;
+}
+
+export function makeWritingContext(wnd: Window): WritingContext {
+    const isVert = isVerticalWriting(wnd);
+    const isVLR  = isVert && isVerticalLR(wnd);
+    const vw     = wnd.innerWidth;
+    const vh     = wnd.innerHeight;
+    const se     = wnd.document.scrollingElement!;
+    const xOff   = se.scrollLeft;   // negative for vertical-rl, non-negative otherwise
+    const yOff   = se.scrollTop;
+    const cols   = parseInt(wnd.getComputedStyle(wnd.document.documentElement).getPropertyValue("column-count"));
+
+    // In vertical-rl, scrollLeft starts at 0 (document start = right side) and goes
+    // negative as the reader scrolls left. The viewport's left edge in document space
+    // is therefore (scrollWidth − viewportWidth + scrollLeft). For vertical-lr and
+    // horizontal modes, scrollLeft is non-negative and is the offset directly.
+    const xDocOffset = (isVert && !isVLR)
+        ? se.scrollWidth - vw + xOff
+        : xOff;
+    const yDocOffset = yOff;
+
+    return {
+        isVertical:          isVert,
+        isVertLR:            isVLR,
+        viewportInlineSize:  isVert ? vh : vw,
+        viewportBlockSize:   isVert ? vw : vh,
+        pageInlineSize:      isVert ? vh : vw / (cols || 1),
+        xDocOffset,
+        yDocOffset,
+        inlineScrollOffset:  isVert ? yDocOffset : xDocOffset,
+        blockScrollOffset:   isVert ? xDocOffset : yDocOffset,
+
+        inlineStart: (r) => isVert ? r.top  : r.left,
+        blockStart:  (r) => isVert ? r.left : r.top,
+        inlineSize:  (r) => isVert ? r.height : r.width,
+        blockSize:   (r) => isVert ? r.width  : r.height,
+
+        applyPosition(el, inlineStart, blockStart, inlineSize, blockSize, iz) {
+            el.style.position = "absolute";
+            if (isVert) {
+                el.style.top    = `${inlineStart * iz}px`;
+                el.style.left   = `${blockStart  * iz}px`;
+                el.style.height = `${inlineSize  * iz}px`;
+                el.style.width  = `${blockSize   * iz}px`;
+            } else {
+                el.style.left   = `${inlineStart * iz}px`;
+                el.style.top    = `${blockStart  * iz}px`;
+                el.style.width  = `${inlineSize  * iz}px`;
+                el.style.height = `${blockSize   * iz}px`;
+            }
+        },
+
+        toRect(inlineStart, blockStart, inlineSize, blockSize) {
+            return isVert
+                ? new DOMRect(blockStart, inlineStart, blockSize, inlineSize)
+                : new DOMRect(inlineStart, blockStart, inlineSize, blockSize);
+        },
+    };
+}
+
+export function getColumnCountPerScreen(wnd: Window): number {
     return parseInt(
         wnd.getComputedStyle(
             wnd.document.documentElement

package/src/helpers/locator.ts

@@ -1,4 +1,4 @@
-import { Locator } from "@readium/shared";
+import { getCssSelector, Locator } from "@readium/shared";
 import { TextQuoteAnchor } from "../vendor/hypothesis/anchoring/types.ts";
 
 function isReplacedLikeElement(element: Element): boolean {
@@ -13,8 +13,8 @@ export function rangeFromLocator(doc: Document, locator: Locator) {
         const text = locator.text;
         if (text && text.highlight) {
             let root;
-            if (locations && locations.getCssSelector()) {
-                root = doc.querySelector(locations.getCssSelector()!);
+            if (locations && getCssSelector(locations)) {
+                root = doc.querySelector(getCssSelector(locations)!);
             }
             if (!root) {
                 root = doc.body;
@@ -36,8 +36,8 @@ export function rangeFromLocator(doc: Document, locator: Locator) {
         if (locations) {
             let element = null;
 
-            if (!element && locations.getCssSelector()) {
-                element = doc.querySelector(locations.getCssSelector()!);
+            if (!element && getCssSelector(locations)) {
+                element = doc.querySelector(getCssSelector(locations)!);
             }
 
             if (!element && locations.fragments) {

package/src/helpers/rect.ts

@@ -10,33 +10,96 @@ export interface Rect {
     width: number;
 }
 
+export function getTextClientRects(range: Range, skipTags: string[]): Rect[] {
+    const upperTags = skipTags.map(t => t.toUpperCase());
+    const rects: Rect[] = [];
+
+    const ancestor = range.commonAncestorContainer;
+    // TreeWalker only visits descendants, never the root itself. If the common
+    // ancestor is already a text node (single-node selection), walk from its
+    // parent so the text node itself is included in the traversal.
+    const walkerRoot = ancestor.nodeType === Node.TEXT_NODE ? ancestor.parentNode! : ancestor;
+    const walker = range.startContainer.ownerDocument!.createTreeWalker(
+        walkerRoot,
+        NodeFilter.SHOW_TEXT
+    );
+
+    let node = walker.nextNode();
+    while (node) {
+        if (range.intersectsNode(node)) {
+            let ancestor = node.parentNode;
+            let skip = false;
+            while (ancestor) {
+                if (ancestor.nodeType === Node.ELEMENT_NODE && upperTags.includes((ancestor as Element).tagName.toUpperCase())) {
+                    skip = true;
+                    break;
+                }
+                ancestor = ancestor.parentNode;
+            }
+            if (!skip) {
+                const textRange = range.cloneRange();
+                textRange.selectNode(node);
+                if (textRange.compareBoundaryPoints(Range.START_TO_START, range) < 0)
+                    textRange.setStart(range.startContainer, range.startOffset);
+                if (textRange.compareBoundaryPoints(Range.END_TO_END, range) > 0)
+                    textRange.setEnd(range.endContainer, range.endOffset);
+                for (const r of textRange.getClientRects()) {
+                    rects.push({ left: r.left, right: r.right, top: r.top, bottom: r.bottom, width: r.width, height: r.height });
+                }
+            }
+        }
+        node = walker.nextNode();
+    }
+
+    return rects;
+}
+
 export function getClientRectsNoOverlap(
-    range: Range,
-    doNotMergeHorizontallyAlignedRects: boolean
+    source: Range | Rect[],
+    doNotMergeHorizontallyAlignedRects: boolean,
+    doNotMergeVerticallyAlignedRects: boolean = false,
+    expand: number = 0
 ) {
-    let clientRects = range.getClientRects();
+    const tolerance = 1;
+    let originalRects: Rect[];
 
-    // Try falling back to the client rects of the common ancestor of the range if it's an HTML Element
-    if(!clientRects.length)
-        if(range.commonAncestorContainer.nodeType === Node.ELEMENT_NODE)
-            clientRects = (range.commonAncestorContainer as HTMLElement).getClientRects();
+    if (Array.isArray(source)) {
+        originalRects = source;
+    } else {
+        let clientRects = source.getClientRects();
 
-    const tolerance = 1;
-    const originalRects: Rect[] = [];
-    for (const rangeClientRect of clientRects) {
-        originalRects.push({
-            bottom: rangeClientRect.bottom,
-            height: rangeClientRect.height,
-            left: rangeClientRect.left,
-            right: rangeClientRect.right,
-            top: rangeClientRect.top,
-            width: rangeClientRect.width,
-        });
+        // Try falling back to the client rects of the common ancestor of the range if it's an HTML Element
+        if(!clientRects.length)
+            if(source.commonAncestorContainer.nodeType === Node.ELEMENT_NODE)
+                clientRects = (source.commonAncestorContainer as HTMLElement).getClientRects();
+
+        originalRects = [];
+        for (const rangeClientRect of clientRects) {
+            originalRects.push({
+                bottom: rangeClientRect.bottom,
+                height: rangeClientRect.height,
+                left: rangeClientRect.left,
+                right: rangeClientRect.right,
+                top: rangeClientRect.top,
+                width: rangeClientRect.width,
+            });
+        }
+    }
+    if (expand) {
+        for (const rect of originalRects) {
+            rect.left   -= expand;
+            rect.top    -= expand;
+            rect.right  += expand;
+            rect.bottom += expand;
+            rect.width  += expand * 2;
+            rect.height += expand * 2;
+        }
     }
     const mergedRects = mergeTouchingRects(
         originalRects,
         tolerance,
-        doNotMergeHorizontallyAlignedRects
+        doNotMergeHorizontallyAlignedRects,
+        doNotMergeVerticallyAlignedRects
     );
     const noContainedRects = removeContainedRects(mergedRects, tolerance);
     const newRects = replaceOverlapingRects(noContainedRects);
@@ -61,7 +124,8 @@ export function getClientRectsNoOverlap(
 function mergeTouchingRects(
     rects: Rect[],
     tolerance: number,
-    doNotMergeHorizontallyAlignedRects: boolean
+    doNotMergeHorizontallyAlignedRects: boolean,
+    doNotMergeVerticallyAlignedRects: boolean = false
 ): Rect[] {
     for (let i = 0; i < rects.length; i++) {
         for (let j = i + 1; j < rects.length; j++) {
@@ -78,8 +142,9 @@ function mergeTouchingRects(
                 almostEqual(rect1.left, rect2.left, tolerance) &&
                 almostEqual(rect1.right, rect2.right, tolerance);
             const horizontalAllowed = !doNotMergeHorizontallyAlignedRects;
+            const verticalAllowed = !doNotMergeVerticallyAlignedRects;
             const aligned =
-                (rectsLineUpHorizontally && horizontalAllowed) ||
+                (rectsLineUpHorizontally && horizontalAllowed && verticalAllowed) ||
                 (rectsLineUpVertically && !rectsLineUpHorizontally);
             const canMerge = aligned && rectsTouchOrOverlap(rect1, rect2, tolerance);
             if (canMerge) {
@@ -94,7 +159,8 @@ function mergeTouchingRects(
                 return mergeTouchingRects(
                     newRects,
                     tolerance,
-                    doNotMergeHorizontallyAlignedRects
+                    doNotMergeHorizontallyAlignedRects,
+                    doNotMergeVerticallyAlignedRects
                 );
             }
         }

package/src/helpers/sanitize.ts

@@ -0,0 +1,77 @@
+/**
+ * Elements a decoration template is allowed to contain.
+ * Allowlisting instead of denylisting: anything not listed here is stripped,
+ * including elements that do not yet exist in the HTML spec.
+ */
+const ALLOWED_ELEMENTS = [
+    // Structure / presentation
+    "div", "span", "p", "br", "hr",
+    "b", "i", "em", "strong", "s", "u", "mark", "small", "sub", "sup",
+    "abbr", "cite", "code", "data", "dfn", "kbd", "q", "samp", "time", "var",
+    "blockquote", "pre",
+    // SVG — useful for icon-style decorations (e.g. sidemarks)
+    "svg", "g", "path", "circle", "ellipse", "rect", "line",
+    "polygon", "polyline", "text", "tspan", "defs", "use",
+];
+
+/** Attributes that introduce executable code on any element. */
+const DANGEROUS_ATTR = /^on/i;
+/** Attributes that carry URLs and must be checked for unsafe schemes. */
+const URL_ATTRS = new Set(["href", "src", "action", "formaction", "xlink:href"]);
+/** URL schemes that must not appear in URL-bearing attributes. */
+const DANGEROUS_SCHEME = /^\s*(javascript|data):/i;
+
+/**
+ * Parses `html` and returns its first element child with all executable
+ * content removed. Uses the Sanitizer API when available, falls back to a
+ * manual DOMParser scrub otherwise.
+ *
+ * The allowlist approach is intentional: unknown or future elements are
+ * stripped by default rather than permitted by oversight.
+ *
+ * @param wnd  Window whose document is used when adopting nodes.
+ * @param html Raw HTML string supplied by the caller.
+ * @returns    The sanitized first element child, or `null` for empty input.
+ */
+export function sanitizeHTML(wnd: Window, html: string): Element | null {
+    const host = wnd.document.createElement("div");
+
+    if ("Sanitizer" in wnd && typeof (host as any).setHTML === "function") {
+        try {
+            const sanitizer = new (wnd as any).Sanitizer({ allowElements: ALLOWED_ELEMENTS });
+            (host as any).setHTML(html, { sanitizer });
+            return host.firstElementChild as Element | null;
+        } catch {
+            // Sanitizer API present but call failed — fall through to DOMParser.
+        }
+    }
+
+    // DOMParser fallback: parse in an isolated document then scrub manually.
+    const scratch = wnd.document.implementation.createHTMLDocument("");
+    scratch.body.innerHTML = html;
+    scrubNode(scratch.body, new Set(ALLOWED_ELEMENTS));
+    while (scratch.body.firstChild) {
+        host.appendChild(wnd.document.adoptNode(scratch.body.firstChild));
+    }
+    return host.firstElementChild as Element | null;
+}
+
+function scrubNode(root: Element, allowed: Set<string>): void {
+    // Walk in reverse so removals don't shift indices.
+    const all = Array.from(root.querySelectorAll("*")).reverse();
+    for (const el of all) {
+        if (!allowed.has(el.localName)) {
+            // Replace disallowed element with its children to preserve text.
+            el.replaceWith(...Array.from(el.childNodes));
+            continue;
+        }
+        for (const { name, value } of Array.from(el.attributes)) {
+            if (
+                DANGEROUS_ATTR.test(name) ||
+                (URL_ATTRS.has(name) && DANGEROUS_SCHEME.test(value))
+            ) {
+                el.removeAttribute(name);
+            }
+        }
+    }
+}

package/src/index.ts

@@ -2,4 +2,5 @@ export * from './comms/index.ts';
 export * from './modules/index.ts';
 export * from './Loader.ts';
 export * from './protection/index.ts';
-export * from './keyboard/index.ts'
+export type { ReadiumWindow } from './helpers/dom.ts';
+export * from './keyboard/index.ts'