Decorator API

navigator-html-injectables/CHANGELOG.MD

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.5.0] – 2026–06–04
+
+### Added
+
+- Implemented Decorator API ([#209](https://github.com/readium/ts-toolkit/pull/209))
+
+### Changed
+
+- Snappers and Decorator modules will avoid running callbacks on mutation when not necessary
+- `BasicTextSelection` now returns a ready-to-use `Locator`
+- Decorations appended into the DOM are now appended into the Shadow DOM
+
 ## [2.4.4] – 2026–06–04
 
 ### Added

navigator-html-injectables/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/navigator-html-injectables",
-  "version": "2.4.4",
+  "version": "2.5.0",
   "type": "module",
   "description": "An embeddable solution for connecting frames of HTML publications with a Readium Navigator",
   "author": "readium",
@@ -54,6 +54,7 @@
     "rimraf": "^6.1.2",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",
+    "user-agent-data-types": "^0.4.2",
     "vite": "^7.3.1"
   }
 }

navigator-html-injectables/src/comms/keys.ts

@@ -20,8 +20,8 @@ export type CommsEventKey =
     "media_play" |
     "media_pause" |
     "content_protection" |
-    "keyboard_peripherals";
-;
+    "keyboard_peripherals" |
+    "decoration_activated";
 
 export type CommsCommandKey =
     "_ping" |
@@ -39,6 +39,7 @@ export type CommsCommandKey =
     // "exact_progress" |
     "first_visible_locator" |
     "decorate" |
+    "decoration_activatable" |
     "protect" |
     "unprotect" |
     "unfocus" |

navigator-html-injectables/src/helpers/color.ts

@@ -202,4 +202,67 @@ export const isLightColor = (color: string, blendedWith: string | null = null):
 
 export const getContrastingTextColor = (color: string, blendedWith: string | null = null): "black" | "white" => {
   return isDarkColor(color, blendedWith) ? "white" : "black";
+};
+
+const rgbaToCss = (rgba: { r: number; g: number; b: number; a?: number }): string => {
+  const a = rgba.a !== undefined ? rgba.a : 1;
+  return `rgba(${Math.round(rgba.r)}, ${Math.round(rgba.g)}, ${Math.round(rgba.b)}, ${a})`;
+};
+
+const lightenColor = (rgba: { r: number; g: number; b: number; a?: number }, factor: number): { r: number; g: number; b: number; a: number } => {
+  return {
+    r: Math.min(255, rgba.r + (255 - rgba.r) * factor),
+    g: Math.min(255, rgba.g + (255 - rgba.g) * factor),
+    b: Math.min(255, rgba.b + (255 - rgba.b) * factor),
+    a: rgba.a ?? 1
+  };
+};
+
+const darkenColor = (rgba: { r: number; g: number; b: number; a?: number }, factor: number): { r: number; g: number; b: number; a: number } => {
+  return {
+    r: Math.max(0, rgba.r * (1 - factor)),
+    g: Math.max(0, rgba.g * (1 - factor)),
+    b: Math.max(0, rgba.b * (1 - factor)),
+    a: rgba.a ?? 1
+  };
+};
+
+export const adjustColorForContrast = (
+  baseColor: string,
+  backgroundColor: string | null = null,
+  targetContrast: number = 3
+): string => {
+  const baseRgba = colorToRgba(baseColor);
+  const bgRgba = backgroundColor ? colorToRgba(backgroundColor) : { r: 255, g: 255, b: 255, a: 1 };
+
+  let currentContrast = checkContrast(baseRgba, bgRgba);
+
+  // If already meets target, return as-is
+  if (currentContrast >= targetContrast) {
+    return baseColor;
+  }
+
+  const bgLuminance = getLuminance(bgRgba);
+  const isBgDark = bgLuminance < 0.5;
+
+  let adjustedRgba = { ...baseRgba, a: baseRgba.a ?? 1 };
+  const maxIterations = 20;
+  const step = 0.1;
+
+  for (let i = 0; i < maxIterations; i++) {
+    if (isBgDark) {
+      // Dark background: lighten the base color
+      adjustedRgba = lightenColor(adjustedRgba, step);
+    } else {
+      // Light background: darken the base color
+      adjustedRgba = darkenColor(adjustedRgba, step);
+    }
+
+    currentContrast = checkContrast(adjustedRgba, bgRgba);
+    if (currentContrast >= targetContrast) {
+      break;
+    }
+  }
+
+  return rgbaToCss(adjustedRgba);
 };

navigator-html-injectables/src/helpers/css.ts

@@ -1,5 +1,34 @@
 import { ReadiumWindow } from "./dom.ts";
 
+const COSMETIC_PROPERTIES = new Set([
+    "backgroundColor", "textColor",
+    "linkColor", "visitedColor",
+    "primaryColor", "secondaryColor",
+    "selectionBackgroundColor", "selectionTextColor",
+    "blendFilter", "darkenFilter", "invertFilter", "invertGaiji",
+]);
+
+const CSS_PROP_RE = /--(?:USER|RS)__([\w-]+)/g;
+
+/**
+ * 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 function styleChangeAffectsLayout(oldValue: string | null, newValue: string | null): boolean {
+    const old_ = oldValue ?? "";
+    const new_ = newValue ?? "";
+    const seen = new Set<string>();
+
+    for (const match of old_.matchAll(CSS_PROP_RE)) seen.add(match[1]);
+    for (const match of new_.matchAll(CSS_PROP_RE)) seen.add(match[1]);
+
+    for (const suffix of seen) {
+        if (!COSMETIC_PROPERTIES.has(suffix)) return true;
+    }
+    return false;
+}
+
 export function getProperties(wnd: ReadiumWindow) {
     const cssProperties: { [key: string]: string } = {};
 

navigator-html-injectables/src/helpers/document.ts

@@ -13,6 +13,126 @@ export function isVerticalLR(wnd: ReadiumWindow): boolean {
     return writingMode === 'vertical-lr';
 }
 
+export function isVerticalWriting(wnd: ReadiumWindow): 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: ReadiumWindow): 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: ReadiumWindow): number {
     return parseInt(
         wnd.getComputedStyle(

navigator-html-injectables/src/helpers/rect.ts

@@ -12,7 +12,8 @@ export interface Rect {
 
 export function getClientRectsNoOverlap(
     range: Range,
-    doNotMergeHorizontallyAlignedRects: boolean
+    doNotMergeHorizontallyAlignedRects: boolean,
+    doNotMergeVerticallyAlignedRects: boolean = false
 ) {
     let clientRects = range.getClientRects();
 
@@ -36,7 +37,8 @@ export function getClientRectsNoOverlap(
     const mergedRects = mergeTouchingRects(
         originalRects,
         tolerance,
-        doNotMergeHorizontallyAlignedRects
+        doNotMergeHorizontallyAlignedRects,
+        doNotMergeVerticallyAlignedRects
     );
     const noContainedRects = removeContainedRects(mergedRects, tolerance);
     const newRects = replaceOverlapingRects(noContainedRects);
@@ -61,7 +63,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 +81,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 +98,8 @@ function mergeTouchingRects(
                 return mergeTouchingRects(
                     newRects,
                     tolerance,
-                    doNotMergeHorizontallyAlignedRects
+                    doNotMergeHorizontallyAlignedRects,
+                    doNotMergeVerticallyAlignedRects
                 );
             }
         }