@readium/helpers 1.2.1 → 1.3.0

package/README.md

@@ -1,11 +1,11 @@
 # @readium/helpers
 
-General-purpose browser helpers for Readium packages: color parsing/contrast utilities, OS/browser detection, and WICG Text Fragment parsing/resolution/generation.
+General-purpose browser helpers for Readium packages: color parsing/contrast utilities, OS/browser detection, URI fragment decoding, and WICG Text Fragment parsing/resolution/generation.
 
 ## Installation
 
 ```ts
-import { colorToRgba, checkContrast, isDarkColor, isLightColor, getContrastingTextColor, adjustColorForContrast, getLuminance, sML, sMLWithRequest, decodeTextFragmentDirective, processTextFragmentDirective, generateFragmentFromRange } from "@readium/helpers";
+import { colorToRgba, checkContrast, isDarkColor, isLightColor, getContrastingTextColor, adjustColorForContrast, getLuminance, sML, sMLWithRequest, decodeFragmentComponent, decodeTextFragmentDirective, processTextFragmentDirective, generateFragmentFromRange } from "@readium/helpers";
 ```
 
 ## Color utilities
@@ -45,6 +45,15 @@ sMLWithRequest.iOSRequest // "mobile" | "desktop" | undefined — iPadOS "Reques
 
 `sML` is a bundled subset of [sML.js](https://github.com/satorumurmur/sML) by Satoru Matsushima, MIT licensed. Falls back safely when `navigator` is unavailable (SSR).
 
+## URI fragments
+
+```ts
+// Percent-decodes one fragment component (e.g. an element id), keeping a malformed escape as-is
+decodeFragmentComponent("caf%C3%A9%20noir"): string // "café noir"
+```
+
+A structured fragment must be split on its delimiters before its components are decoded.
+
 ## Text Fragments
 
 ```ts

package/dist/fragment.js

@@ -0,0 +1 @@
+function r(n){return n.replace(/(?:%[0-9A-Fa-f]{2})+/g,e=>{try{return decodeURIComponent(e)}catch{return e}})}export{r as decodeFragmentComponent};

package/dist/index.js

@@ -1 +1 @@
-import{adjustColorForContrast as r,checkContrast as o,colorToRgba as n,getContrastingTextColor as a,getLuminance as s,isDarkColor as i,isLightColor as g}from"./color.js";import{sML as c,sMLWithRequest as x}from"./sML.js";import{BINDING_PUNCT_CLASS as l,ssmlAttrEscape as p,ssmlTextEscape as C,startsWithBindingPunct as T}from"./text.js";import{decodeTextFragmentDirective as u}from"./textFragmentDirective.js";import{forTesting as L,internal as h,processTextFragmentDirective as D}from"./vendor/text-fragments-polyfill/textFragmentMatcher.js";import{GenerateFragmentStatus as R,generateFragment as N,generateFragmentFromRange as S,isValidRangeForFragmentGeneration as k,setFragmentGenerationTimeout as v}from"./vendor/text-fragments-polyfill/textFragmentGenerator.js";export{l as BINDING_PUNCT_CLASS,R as GenerateFragmentStatus,r as adjustColorForContrast,o as checkContrast,n as colorToRgba,u as decodeTextFragmentDirective,L as forTesting,N as generateFragment,S as generateFragmentFromRange,a as getContrastingTextColor,s as getLuminance,h as internal,i as isDarkColor,g as isLightColor,k as isValidRangeForFragmentGeneration,D as processTextFragmentDirective,c as sML,x as sMLWithRequest,v as setFragmentGenerationTimeout,p as ssmlAttrEscape,C as ssmlTextEscape,T as startsWithBindingPunct};
+import{adjustColorForContrast as r,checkContrast as o,colorToRgba as n,getContrastingTextColor as a,getLuminance as s,isDarkColor as m,isLightColor as i}from"./color.js";import{decodeFragmentComponent as c}from"./fragment.js";import{sML as x,sMLWithRequest as F}from"./sML.js";import{BINDING_PUNCT_CLASS as l,ssmlAttrEscape as f,ssmlTextEscape as T,startsWithBindingPunct as d}from"./text.js";import{decodeTextFragmentDirective as L}from"./textFragmentDirective.js";import{forTesting as D,internal as G,processTextFragmentDirective as R}from"./vendor/text-fragments-polyfill/textFragmentMatcher.js";import{GenerateFragmentStatus as S,generateFragment as k,generateFragmentFromRange as v,isValidRangeForFragmentGeneration as A,setFragmentGenerationTimeout as B}from"./vendor/text-fragments-polyfill/textFragmentGenerator.js";export{l as BINDING_PUNCT_CLASS,S as GenerateFragmentStatus,r as adjustColorForContrast,o as checkContrast,n as colorToRgba,c as decodeFragmentComponent,L as decodeTextFragmentDirective,D as forTesting,k as generateFragment,v as generateFragmentFromRange,a as getContrastingTextColor,s as getLuminance,G as internal,m as isDarkColor,i as isLightColor,A as isValidRangeForFragmentGeneration,R as processTextFragmentDirective,x as sML,F as sMLWithRequest,B as setFragmentGenerationTimeout,f as ssmlAttrEscape,T as ssmlTextEscape,d as startsWithBindingPunct};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@readium/helpers",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "type": "module",
   "description": "General-purpose browser helpers for Readium packages",
   "author": "readium",

package/src/fragment.ts

@@ -0,0 +1,11 @@
+// Percent-decodes one component of a URI fragment, after any structured
+// fragment has been split on its delimiters. A malformed escape is kept as-is.
+export function decodeFragmentComponent(component: string): string {
+  return component.replace(/(?:%[0-9A-Fa-f]{2})+/g, (escapes) => {
+    try {
+      return decodeURIComponent(escapes);
+    } catch {
+      return escapes;
+    }
+  });
+}

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from "./color.ts";
+export * from "./fragment.ts";
 export * from "./sML.ts";
 export * from "./text.ts";
 export * from "./textFragmentDirective.ts";

package/types/src/fragment.d.ts

@@ -0,0 +1 @@
+export declare function decodeFragmentComponent(component: string): string;

package/types/src/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./color.ts";
+export * from "./fragment.ts";
 export * from "./sML.ts";
 export * from "./text.ts";
 export * from "./textFragmentDirective.ts";