@readium/navigator-html-injectables 2.4.3 → 2.5.0

package/src/modules/Peripherals.ts

@@ -1,3 +1,4 @@
+import { Locator } from "@readium/shared";
 import { Comms } from "../comms/comms.ts";
 import { Module } from "./Module.ts";
 import { ReadiumWindow, nearestInteractiveElement } from "../helpers/dom.ts";
@@ -28,6 +29,8 @@ export interface BasicTextSelection {
     width: number;
     height: number;
     targetFrameSrc: string;
+    /** Locator for the frame the selection originated from. Populated by the navigator. */
+    locator?: Locator;
 }
 
 export interface BaseSuspiciousActivityEvent {

package/src/modules/snapper/ColumnSnapper.ts

@@ -1,6 +1,7 @@
 import { Comms } from "../../comms/index.ts";
 import { Snapper } from "./Snapper.ts";
 import { getColumnCountPerScreen, isRTL, appendVirtualColumnIfNeeded } from "../../helpers/document.ts";
+import { styleChangeAffectsLayout } from "../../helpers/css.ts";
 import { easeInOutQuad } from "../../helpers/animation.ts";
 import { ModuleName } from "../ModuleLibrary.ts";
 import { Locator, LocatorLocations, LocatorText } from "@readium/shared";
@@ -392,7 +393,7 @@ export class ColumnSnapper extends Snapper {
                     const oldValueTransform = oldValue?.match(transformRegex);
                     const newValueTransform = newValue?.match(transformRegex);
                     if (
-                        (!oldValueTransform && !newValueTransform) ||
+                        (!oldValueTransform && !newValueTransform && styleChangeAffectsLayout(oldValue, newValue)) ||
                         (oldValueTransform && !newValueTransform) ||
                         (oldValueTransform && newValueTransform && oldValueTransform[1] !== newValueTransform[1])
                     ) {

package/types/src/comms/keys.d.ts

@@ -1,3 +1,3 @@
-export type CommsEventKey = "_pong" | "_unhandled" | "_ack" | "log" | "error" | "click" | "tap" | "tap_more" | "no_more" | "no_less" | "swipe" | "scroll" | "progress" | "first_visible_locator" | "text_selected" | "context_menu" | "media_play" | "media_pause" | "content_protection" | "keyboard_peripherals";
-export type CommsCommandKey = "_ping" | "go_prev" | "go_next" | "go_id" | "go_text" | "go_end" | "go_start" | "go_progression" | "get_properties" | "update_properties" | "set_property" | "remove_property" | "first_visible_locator" | "decorate" | "protect" | "unprotect" | "unfocus" | "focus" | "activate" | "shake" | "force_webkit_recalc" | "peripherals_protection" | "keyboard_peripherals" | "scroll_protection" | "print_protection";
+export type CommsEventKey = "_pong" | "_unhandled" | "_ack" | "log" | "error" | "click" | "tap" | "tap_more" | "no_more" | "no_less" | "swipe" | "scroll" | "progress" | "first_visible_locator" | "text_selected" | "context_menu" | "media_play" | "media_pause" | "content_protection" | "keyboard_peripherals" | "decoration_activated";
+export type CommsCommandKey = "_ping" | "go_prev" | "go_next" | "go_id" | "go_text" | "go_end" | "go_start" | "go_progression" | "get_properties" | "update_properties" | "set_property" | "remove_property" | "first_visible_locator" | "decorate" | "decoration_activatable" | "protect" | "unprotect" | "unfocus" | "focus" | "activate" | "shake" | "force_webkit_recalc" | "peripherals_protection" | "keyboard_peripherals" | "scroll_protection" | "print_protection";
 export type SuspiciousActivityType = "developer_tools" | "select_all" | "save" | "suspicious_selection" | "bulk_copy" | "suspicious_scrolling" | "suspicious_snapping" | "drag_detected" | "drop_detected" | "print";

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

@@ -24,3 +24,4 @@ export declare const checkContrast: (color1: string | {
 export declare const isDarkColor: (color: string, blendedWith?: string | null) => boolean;
 export declare const isLightColor: (color: string, blendedWith?: string | null) => boolean;
 export declare const getContrastingTextColor: (color: string, blendedWith?: string | null) => "black" | "white";
+export declare const adjustColorForContrast: (baseColor: string, backgroundColor?: string | null, targetContrast?: number) => string;

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

@@ -1,4 +1,10 @@
 import { ReadiumWindow } from "./dom.ts";
+/**
+ * Returns true if the style attribute change between oldValue and newValue
+ * includes at least one ReadiumCSS property that affects document layout/geometry.
+ * Pure appearance changes (colors, filters) return false.
+ */
+export declare function styleChangeAffectsLayout(oldValue: string | null, newValue: string | null): boolean;
 export declare function getProperties(wnd: ReadiumWindow): {
     [key: string]: string;
 };

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

@@ -1,6 +1,72 @@
 import { ReadiumWindow } from "./dom.ts";
 export declare function isRTL(wnd: ReadiumWindow): boolean;
 export declare function isVerticalLR(wnd: ReadiumWindow): boolean;
+export declare function isVerticalWriting(wnd: ReadiumWindow): boolean;
+/**
+ * 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 declare function makeWritingContext(wnd: ReadiumWindow): WritingContext;
 export declare function getColumnCountPerScreen(wnd: ReadiumWindow): number;
 /**
 * Returns the "content height" of an element, which is its clientHeight

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

@@ -6,5 +6,5 @@ export interface Rect {
     top: number;
     width: number;
 }
-export declare function getClientRectsNoOverlap(range: Range, doNotMergeHorizontallyAlignedRects: boolean): Rect[];
+export declare function getClientRectsNoOverlap(range: Range, doNotMergeHorizontallyAlignedRects: boolean, doNotMergeVerticallyAlignedRects?: boolean): Rect[];
 export declare function rectContainsPoint(rect: Rect, x: number, y: number, tolerance: number): boolean;

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

@@ -0,0 +1,56 @@
+/*!
+ *                                                                                                                         (℠)
+ *  # sML.js | I'm a Simple and Middling Library.
+ *
+ *  * Copyright (c) Satoru MATSUSHIMA - https://github.com/satorumurmur/sML
+ *  * Licensed under the MIT license. - http://www.opensource.org/licenses/mit-license.php
+ *
+ * Portions of this code come from the sML library
+ * Current version: 1.0.36
+ */
+declare interface OSFlags {
+    iOS: number[];
+    macOS: number[];
+    iPadOS: number[];
+    WindowsPhone: number[];
+    ChromeOS: number[];
+    Windows: number[];
+    Android: number[];
+    Linux: number[];
+    Firefox: boolean;
+}
+declare interface UAFlags {
+    Gecko: number[];
+    Firefox: number[];
+    Waterfox: number[];
+    Opera: number[];
+    Silk: number[];
+    Blink: number[];
+    EdgeHTML: number[];
+    Chrome: number[];
+    Chromium: number[];
+    Phoebe: number[];
+    UCBrowser: number[];
+    Vivaldi: number[];
+    Safari: number[];
+    Edge: number[];
+    WebKit: number[];
+    Trident: number[];
+    InternetExplorer: number[];
+    Flash: number[];
+    Facebook: number[];
+    LINE: number[];
+}
+declare type iOSRequest = "mobile" | "desktop" | undefined;
+declare class sMLFactory {
+    OS: OSFlags;
+    UA: UAFlags;
+    Env: string[];
+    constructor();
+}
+declare class sMLFactoryWithRequest extends sMLFactory {
+    get iOSRequest(): iOSRequest;
+}
+declare const sML: sMLFactory;
+declare const sMLWithRequest: sMLFactoryWithRequest;
+export { sML, sMLWithRequest };

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

@@ -0,0 +1,13 @@
+/**
+ * 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 declare function sanitizeHTML(wnd: Window, html: string): Element | null;

package/types/src/index.d.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 './helpers/sML.ts';
 export * from './keyboard/index.ts';

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

@@ -3,42 +3,91 @@ import { Comms } from "../comms/comms.ts";
 import { Module } from "./Module.ts";
 import { ModuleName } from "./ModuleLibrary.ts";
 import { ReadiumWindow } from "../helpers/dom.ts";
-export declare enum Width {
+export declare const DecorationStyleType: {
+    readonly Highlight: "highlight";
+    readonly Underline: "underline";
+    readonly Outline: "outline";
+    readonly TextColor: "textColor";
+    readonly Mask: "mask";
+    readonly Template: "template";
+};
+export type DecorationStyleType = typeof DecorationStyleType[keyof typeof DecorationStyleType];
+export declare enum DecorationWidth {
     Wrap = "wrap",// Smallest width fitting the CSS border box.
     Viewport = "viewport",// Fills the whole viewport.
-    Bounds = "bounds",// Fills the anchor page, useful for dual page.
+    Bounds = "bounds",// Fills the bounding region of all CSS border boxes.
     Page = "page"
 }
-export declare enum Layout {
+export declare enum DecorationLayout {
     Boxes = "boxes",// One HTML element for each CSS border box (e.g. line of text).
     Bounds = "bounds"
 }
-export interface Style {
-    tint: string;
-    layout: Layout;
-    width: Width;
+/** Built-in decoration styles. layout/width are optional overrides; defaults are Boxes/Wrap. */
+export interface BuiltinDecorationStyle {
+    type?: Exclude<DecorationStyleType, "template">;
+    tint?: string;
+    layout?: DecorationLayout;
+    width?: DecorationWidth;
+    isActive?: boolean;
+    enforceContrast?: boolean;
 }
+/**
+ * Custom decoration style backed by caller-supplied HTML.
+ * Matches the HTMLDecorationTemplate class from the Readium spec.
+ * The element string is sanitized before injection.
+ * --readium-tint is injected as a CSS custom property on each created element.
+ */
+export interface HTMLDecorationTemplate {
+    type: "template";
+    layout: DecorationLayout;
+    width: DecorationWidth;
+    element: string;
+    stylesheet?: string;
+    isActive?: boolean;
+}
+export type DecorationStyle = BuiltinDecorationStyle | HTMLDecorationTemplate;
 export interface Decoration {
     id: string;
     locator: Locator;
-    style: Style;
+    style: DecorationStyle;
+    extras?: Record<string, unknown>;
 }
-export interface DecoratorRequest {
+export interface DecorationActivatedEvent {
+    decorationId: string;
     group: string;
-    action: "add" | "remove" | "clear" | "update";
-    decoration: Decoration | undefined;
+    rect: {
+        top: number;
+        left: number;
+        width: number;
+        height: number;
+    };
+    point: {
+        x: number;
+        y: number;
+    };
 }
+export type DecoratorRequest = {
+    group: string;
+    action: "add" | "update";
+    decoration: Decoration;
+} | {
+    group: string;
+    action: "remove";
+    decoration: Pick<Decoration, "id">;
+} | {
+    group: string;
+    action: "clear";
+};
 export declare class Decorator extends Module {
     static readonly moduleName: ModuleName;
     private resizeObserver;
-    private backgroundObserver;
+    private styleObserver;
     private wnd;
     private resizeFrame;
     private lastGroupId;
     private groups;
     private cleanup;
     private updateHighlightStyles;
-    private extractCustomProperty;
     private handleResize;
     private readonly handleResizer;
     mount(wnd: ReadiumWindow, comms: Comms): boolean;

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

@@ -1,3 +1,4 @@
+import { Locator } from "@readium/shared";
 import { Comms } from "../comms/comms.ts";
 import { Module } from "./Module.ts";
 import { ReadiumWindow } from "../helpers/dom.ts";
@@ -24,6 +25,8 @@ export interface BasicTextSelection {
     width: number;
     height: number;
     targetFrameSrc: string;
+    /** Locator for the frame the selection originated from. Populated by the navigator. */
+    locator?: Locator;
 }
 export interface BaseSuspiciousActivityEvent {
     type: SuspiciousActivityType;