@readium/helpers 1.0.0

package/README.md

@@ -0,0 +1,50 @@
+# @readium/helpers
+
+General-purpose browser helpers for Readium packages: color parsing/contrast utilities and OS/browser detection.
+
+## Installation
+
+```ts
+import { colorToRgba, checkContrast, isDarkColor, isLightColor, getContrastingTextColor, adjustColorForContrast, getLuminance, sML, sMLWithRequest } from "@readium/helpers";
+```
+
+## Color utilities
+
+```ts
+// Parse any CSS color value (including custom properties resolved by the browser) to RGBA
+colorToRgba("rebeccapurple"): { r: number; g: number; b: number; a: number }
+
+// Relative luminance per WCAG 2.2
+getLuminance({ r: 255, g: 255, b: 255 }): number
+
+// WCAG 2.2 contrast ratio between two colors (string or RGBA)
+checkContrast("#000", "#fff"): number
+
+// Whether a color reads as dark/light against an optional background it's blended with
+isDarkColor("#333", "#fff"): boolean
+isLightColor("#333", "#fff"): boolean
+
+// "black" or "white", whichever contrasts best against the given color
+getContrastingTextColor("#333"): "black" | "white"
+
+// Lightens/darkens baseColor against backgroundColor until targetContrast (default 3) is met
+adjustColorForContrast("#888", "#fff", 3): string
+```
+
+`colorToRgba` uses an offscreen canvas to resolve any value the browser's CSS engine understands (named colors, `hsl()`, `oklch()`, etc.) and caches results. Unparseable or special values (`transparent`, `currentColor`, gradients, CSS variables) log a warning and fall back to opaque white.
+
+## OS / browser detection
+
+```ts
+sML.OS   // { iOS, macOS, iPadOS, Windows, Android, ChromeOS, Linux, ... } — each a version array, e.g. [17, 4]
+sML.UA   // { Chrome, Safari, Firefox, Edge, WebKit, Blink, ... } — each a version array
+sML.Env  // string[] of all detected OS/UA flag names
+
+sMLWithRequest.iOSRequest // "mobile" | "desktop" | undefined — iPadOS "Request Desktop Site" state
+```
+
+`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).
+
+## Third-party licenses
+
+This package is BSD-3-Clause, except for `src/sML.ts`, which vendors code from [sML.js](https://github.com/satorumurmur/sML), Copyright (c) Satoru Matsushima, licensed under the MIT license (see the header of that file for the full notice).

package/dist/color.js

@@ -0,0 +1 @@
+let m=null,x=null,g=0;const l={r:255,g:255,b:255,a:1},i=new Map,R=()=>{if(!m)if(typeof OffscreenCanvas<"u")m=new OffscreenCanvas(5,5),x=m.getContext("2d",{willReadFrequently:!0,desynchronized:!0});else{const t=document.createElement("canvas");t.width=5,t.height=5,m=t,x=t.getContext("2d",{willReadFrequently:!0,desynchronized:!0})}return x},$=t=>{if(!t)return!0;const e=t.trim().toLowerCase();return e.startsWith("var(")||["transparent","currentcolor","inherit","initial","revert","unset","revert-layer"].includes(e)?!0:["linear-gradient","radial-gradient","conic-gradient","repeating-linear-gradient","repeating-radial-gradient","repeating-conic-gradient"].some(n=>e.includes(n))},p=(t,e)=>{console.warn(`[Decorator] Could not parse color: "${t}". ${e} Falling back to ${JSON.stringify(l)} to compute contrast. Please use a CSS color value that can be computed to RGB(A).`)},h=(t,e=null)=>{const r=e?`${t}|${e}`:t,s=i.get(r);if(s!==void 0)return s??l;if($(t))return p(t,"Unsupported color format or special value."),i.set(r,null),l;const n=R();if(!n)return p(t,"Could not get canvas context."),i.set(r,null),l;try{g===0&&n.clearRect(0,0,5,5);const a=g%5,c=Math.floor(g/5);n.clearRect(a,c,1,1),e&&(n.fillStyle=e,n.fillRect(a,c,1,1)),n.fillStyle=t,n.fillRect(a,c,1,1);const u=n.getImageData(a,c,1,1);g=(g+1)%25;const[o,y,f,d]=u.data;if(d===0)return p(t,"Fully transparent color."),i.set(r,null),l;const b={r:o,g:y,b:f,a:d/255};return i.set(r,b),b}catch(a){return p(t,`Error: ${a instanceof Error?a.message:String(a)}`),i.set(r,null),l}},v=t=>{const e=t/255;return e<=.03928?e/12.92:Math.pow((e+.055)/1.055,2.4)},M=t=>{const e=v(t.r),r=v(t.g),s=v(t.b);return .2126*e+.7152*r+.0722*s},C=(t,e)=>{const r=typeof t=="string"?h(t):t,s=typeof e=="string"?h(e):e,n=M(r),a=M(s),c=Math.max(n,a),u=Math.min(n,a);return(c+.05)/(u+.05)},w=(t,e=null)=>{const r=h(t,e),s=C(r,{r:255,g:255,b:255,a:1}),n=C(r,{r:0,g:0,b:0,a:1});return s>n},F=(t,e=null)=>!w(t,e),T=(t,e=null)=>w(t,e)?"white":"black",L=t=>{const e=t.a!==void 0?t.a:1;return`rgba(${Math.round(t.r)}, ${Math.round(t.g)}, ${Math.round(t.b)}, ${e})`},S=(t,e)=>({r:Math.min(255,t.r+(255-t.r)*e),g:Math.min(255,t.g+(255-t.g)*e),b:Math.min(255,t.b+(255-t.b)*e),a:t.a??1}),D=(t,e)=>({r:Math.max(0,t.r*(1-e)),g:Math.max(0,t.g*(1-e)),b:Math.max(0,t.b*(1-e)),a:t.a??1}),k=(t,e=null,r=3)=>{const s=h(t),n=e?h(e):{r:255,g:255,b:255,a:1};let a=C(s,n);if(a>=r)return t;const u=M(n)<.5;let o={...s,a:s.a??1};const y=20,f=.1;for(let d=0;d<y&&(u?o=S(o,f):o=D(o,f),a=C(o,n),!(a>=r));d++);return L(o)};export{k as adjustColorForContrast,C as checkContrast,h as colorToRgba,T as getContrastingTextColor,M as getLuminance,w as isDarkColor,F as isLightColor};

package/dist/index.js

@@ -0,0 +1 @@
+import{adjustColorForContrast as r,checkContrast as e,colorToRgba as s,getContrastingTextColor as a,getLuminance as C,isDarkColor as i,isLightColor as n}from"./color.js";import{sML as l,sMLWithRequest as c}from"./sML.js";export{r as adjustColorForContrast,e as checkContrast,s as colorToRgba,a as getContrastingTextColor,C as getLuminance,i as isDarkColor,n as isLightColor,l as sML,c as sMLWithRequest};

package/dist/sML.js

@@ -0,0 +1 @@
+const a=()=>typeof navigator>"u"?"":navigator.userAgent||"",l=()=>typeof navigator>"u"?void 0:navigator.userAgentData||void 0;class u{constructor(){const n=l(),s=a(),d=e=>(typeof e=="string"||typeof e=="number")&&e?String(e).replace(/_/g,".").split(".").map(r=>parseInt(r)||0):[],i=(e="")=>{if(!e)return[];const r=new RegExp("^.*"+e+"[ :\\/]?(\\d+([\\._]\\d+)*).*$");return r.test(s)?d(s.replace(r,"$1")):[]};this.OS=(e=>(/(macOS|Mac OS X)/.test(s)?(/\(iP(hone|od touch);/.test(s)&&(e.iOS=i("CPU (?:iPhone )?OS ")),/\(iPad;/.test(s)?e.iOS=e.iPadOS=i("CPU (?:iPhone )?OS "):/(macOS|Mac OS X) \d/.test(s)&&(document.ontouchend!==void 0?e.iOS=e.iPadOS=i():e.macOS=i("(?:macOS|Mac OS X) "))):/Windows( NT)? \d/.test(s)?e.Windows=(r=>r[0]!==6||!r[1]?r:r[1]===1?[7]:r[1]===2?[8]:[8,1])(i("Windows(?: NT)?")):/Android \d/.test(s)?e.Android=i("Android"):/CrOS/.test(s)?e.ChromeOS=i():/X11;/.test(s)&&(e.Linux=i()),e))({}),n&&n.getHighEntropyValues(["architecture","model","platform","platformVersion","uaFullVersion"]).then(e=>(r=>{const t=e.platform,o=e.platformVersion;if(!(!t||!o)){if(/^i(OS|P(hone|od touch))$/.test(t))r.iOS=d(o);else if(/^iPad(OS)?$/.test(t))r.iOS=r.iPadOS=d(o);else if(/^(macOS|(Mac )?OS X|Mac(Intel)?)$/.test(t))document.ontouchend!==void 0?r.iOS=r.iPadOS=d():r.macOS=d(o);else if(/^(Microsoft )?Windows$/.test(t))r.Windows=d(o);else if(/^(Google )?Android$/.test(t))r.Android=d(o);else if(/^((Google )?Chrome OS|CrOS)$/.test(t))r.ChromeOS=d(o);else if(/^(Linux|Ubuntu|X11)$/.test(t))r.Linux=d(o);else return;Object.keys(this.OS).forEach(f=>delete this.OS[f]),Object.assign(this.OS,r)}})({})),this.UA=(e=>{let r=!1;if(n&&Array.isArray(n.brands)){const t=n.brands.reduce((o,f)=>(o[f.brand]=[f.version*1],o),{});t["Google Chrome"]?(r=!0,e.Blink=e.Chromium=t.Chromium||[],e.Chrome=t["Google Chrome"]):t["Microsoft Edge"]?(r=!0,e.Blink=e.Chromium=t.Chromium||[],e.Edge=t["Microsoft Edge"]):t.Opera&&(r=!0,e.Blink=e.Chromium=t.Chromium||[],e.Opera=t.Opera)}return r||(/ Gecko\/\d/.test(s)?(e.Gecko=i("rv"),/ Waterfox\/\d/.test(s)?e.Waterfox=i("Waterfox"):/ Firefox\/\d/.test(s)&&(e.Firefox=i("Firefox"))):/ Edge\/\d/.test(s)?(e.EdgeHTML=i("Edge"),e.Edge=e.EdgeHTML):/ Chrom(ium|e)\/\d/.test(s)?(e.Blink=e.Chromium=(t=>t[0]?t:i("Chrome"))(i("Chromium")),/ EdgA?\/\d/.test(s)?e.Edge=(t=>t[0]?t:i("Edg"))(i("EdgA")):/ OPR\/\d/.test(s)?e.Opera=i("OPR"):/ Vivaldi\/\d/.test(s)?e.Vivaldi=i("Vivaldi"):/ Silk\/\d/.test(s)?e.Silk=i("Silk"):/ UCBrowser\/\d/.test(s)?e.UCBrowser=i("UCBrowser"):/ Phoebe\/\d/.test(s)?e.Phoebe=i("Phoebe"):e.Chrome=(t=>t[0]?t:e.Chromium)(i("Chrome"))):/ AppleWebKit\/\d/.test(s)?(e.WebKit=i("AppleWebKit"),/ CriOS \d/.test(s)?e.Chrome=i("CriOS"):/ FxiOS \d/.test(s)?e.Firefox=i("FxiOS"):/ EdgiOS\/\d/.test(s)?e.Edge=i("EdgiOS"):/ Version\/\d/.test(s)&&(e.Safari=i("Version"))):/ Trident\/\d/.test(s)&&(e.Trident=i("Trident"),e.InternetExplorer=(t=>t[0]?t:i("MSIE"))(i("rv")))),/[\[; ]FB(AN|_IAB)\//.test(s)&&(e.Facebook=i("FBAV")),/ Line\/\d/.test(s)&&(e.LINE=i("Line")),e})({}),this.Env={get:()=>[this.OS,this.UA].reduce((e,r)=>{for(const t in r)r[t]&&e.push(t);return e},[])}}}class h extends u{get iOSRequest(){const n=l(),s=a();if(this.OS.iOS&&!this.OS.iPadOS)return"mobile";if(this.OS.iPadOS)return/\(iPad;/.test(s)||n&&/^iPad(OS)?$/.test(n.platform)?"mobile":"desktop"}}const m=new u,g=new h;export{m as sML,g as sMLWithRequest};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@readium/helpers",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "General-purpose browser helpers for Readium packages",
+  "author": "readium",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/readium/ts-toolkit.git",
+    "directory": "helpers"
+  },
+  "license": "BSD-3-Clause",
+  "bugs": {
+    "url": "https://github.com/readium/ts-toolkit/issues"
+  },
+  "homepage": "https://github.com/readium/ts-toolkit",
+  "types": "./types/src/index.d.ts",
+  "exports": {
+    ".": {
+      "ts-toolkit-source": "./src/index.ts",
+      "types": "./types/src/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "src",
+    "types"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "clean": "rimraf types dist",
+    "build": "pnpm clean && tsc && vite build"
+  },
+  "dependencies": {
+    "user-agent-data-types": "^0.4.2"
+  },
+  "devDependencies": {
+    "rimraf": "^6.1.2",
+    "tslib": "^2.8.1",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.1"
+  }
+}

package/src/color.ts

@@ -0,0 +1,268 @@
+// Lazy canvas/offscreen canvas initialization for color conversion
+let canvas: HTMLCanvasElement | OffscreenCanvas | null = null;
+let ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null = null;
+
+// Track which pixel to use next for color sampling (0-24 for 5x5 grid)
+let currentPixelIndex = 0;
+
+// Default color for failed conversions
+const DEFAULT_COLOR = { r: 255, g: 255, b: 255, a: 1 };
+
+// Cache for computed color conversions
+const colorCache = new Map<string, { r: number; g: number; b: number; a: number; } | null>();
+
+const getCanvasContext = (): CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D | null => {
+  if (!canvas) {
+    // Try to use OffscreenCanvas if available
+    if (typeof OffscreenCanvas !== "undefined") {
+      canvas = new OffscreenCanvas(5, 5);
+      ctx = canvas.getContext("2d", {
+        willReadFrequently: true,
+        desynchronized: true
+      });
+    } else {
+      // Fall back to regular canvas
+      const htmlCanvas = document.createElement("canvas");
+      htmlCanvas.width = 5;
+      htmlCanvas.height = 5;
+      canvas = htmlCanvas;
+      ctx = htmlCanvas.getContext("2d", {
+        willReadFrequently: true,
+        desynchronized: true
+      });
+    }
+  }
+  return ctx;
+};
+
+const isSpecialColorValue = (color: string): boolean => {
+  if (!color) return true;
+
+  const normalizedColor = color.trim().toLowerCase();
+
+  // Check for CSS variables
+  if (normalizedColor.startsWith("var(")) {
+    return true;
+  }
+
+  // Check for CSS color keywords
+  const cssKeywords = [
+    "transparent",
+    "currentcolor",
+    "inherit",
+    "initial",
+    "revert",
+    "unset",
+    "revert-layer"
+  ];
+
+  if (cssKeywords.includes(normalizedColor)) {
+    return true;
+  }
+
+  // Check for gradients
+  const gradientTypes = [
+    "linear-gradient",
+    "radial-gradient",
+    "conic-gradient",
+    "repeating-linear-gradient",
+    "repeating-radial-gradient",
+    "repeating-conic-gradient"
+  ];
+
+  return gradientTypes.some(grad => normalizedColor.includes(grad));
+};
+
+const warnAboutInvalidColor = (color: string, reason: string): void => {
+  console.warn(
+    `[Decorator] Could not parse color: "${color}". ${reason} Falling back to ${JSON.stringify(DEFAULT_COLOR)} to compute contrast. Please use a CSS color value that can be computed to RGB(A).`
+  );
+};
+
+export const colorToRgba = (
+  color: string,
+  backgroundColor: string | null = null
+): { r: number; g: number; b: number; a: number } => {
+  // Check cache with background key if provided
+  const cacheKey = backgroundColor ? `${color}|${backgroundColor}` : color;
+  const cached = colorCache.get(cacheKey);
+  if (cached !== undefined) {
+    return cached ?? DEFAULT_COLOR;
+  }
+
+  // Check for special color values
+  if (isSpecialColorValue(color)) {
+    warnAboutInvalidColor(color, "Unsupported color format or special value.");
+    colorCache.set(cacheKey, null);
+    return DEFAULT_COLOR;
+  }
+
+  const context = getCanvasContext();
+  if (!context) {
+    warnAboutInvalidColor(color, "Could not get canvas context.");
+    colorCache.set(cacheKey, null);
+    return DEFAULT_COLOR;
+  }
+
+  try {
+    // Clear and initialize canvas at the start of each cycle
+    if (currentPixelIndex === 0) {
+      context.clearRect(0, 0, 5, 5);
+    }
+
+    // Calculate which pixel to use for this operation
+    const x = currentPixelIndex % 5;
+    const y = Math.floor(currentPixelIndex / 5);
+
+    // Clear just this pixel to ensure clean state
+    context.clearRect(x, y, 1, 1);
+
+    // Fill background color if provided
+    if (backgroundColor) {
+      context.fillStyle = backgroundColor;
+      context.fillRect(x, y, 1, 1);
+    }
+
+    // Draw the color at the current pixel
+    context.fillStyle = color;
+    context.fillRect(x, y, 1, 1);
+
+    // Get the pixel data for this specific pixel
+    const imageData = context.getImageData(x, y, 1, 1);
+
+    // Move to next pixel for next call
+    currentPixelIndex = (currentPixelIndex + 1) % 25;
+
+    // Get the pixel data for the pixel we just sampled
+    const [r, g, b, a] = imageData.data;
+
+    // If the color is completely transparent, return default
+    if (a === 0) {
+      warnAboutInvalidColor(color, "Fully transparent color.");
+      colorCache.set(cacheKey, null);
+      return DEFAULT_COLOR;
+    }
+
+    const result = { r, g, b, a: a / 255 };
+    colorCache.set(cacheKey, result);
+    return result;
+  } catch (error) {
+    warnAboutInvalidColor(color, `Error: ${error instanceof Error ? error.message : String(error)}`);
+    colorCache.set(cacheKey, null);
+    return DEFAULT_COLOR;
+  }
+};
+
+const toLinear = (c: number): number => {
+  const normalized = c / 255;
+  return normalized <= 0.03928
+    ? normalized / 12.92
+    : Math.pow((normalized + 0.055) / 1.055, 2.4);
+};
+
+export const getLuminance = (color: { r: number; g: number; b: number; a?: number }): number => {
+  // Convert sRGB to linear RGB and apply WCAG 2.2 formula
+  const r = toLinear(color.r);
+  const g = toLinear(color.g);
+  const b = toLinear(color.b);
+
+  // WCAG 2.2 relative luminance formula (returns 0-1)
+  // Note: Alpha is ignored for contrast calculations. WCAG 2.2 only defines contrast for opaque colors,
+  // and semi-transparent colors have a range of possible contrast ratios depending on background.
+  // For text readability decisions, we use the base color as the most conservative approach.
+  const luminance = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+  return luminance;
+};
+
+export const checkContrast = (
+  color1: string | { r: number; g: number; b: number; a?: number },
+  color2: string | { r: number; g: number; b: number; a?: number }
+): number => {
+  const rgba1 = typeof color1 === "string" ? colorToRgba(color1) : color1;
+  const rgba2 = typeof color2 === "string" ? colorToRgba(color2) : color2;
+
+  const l1 = getLuminance(rgba1);
+  const l2 = getLuminance(rgba2);
+
+  const lighter = Math.max(l1, l2);
+  const darker = Math.min(l1, l2);
+  return (lighter + 0.05) / (darker + 0.05);
+};
+
+export const isDarkColor = (color: string, blendedWith: string | null = null): boolean => {
+  const blended = colorToRgba(color, blendedWith);
+  const contrastWithWhite = checkContrast(blended, { r: 255, g: 255, b: 255, a: 1 });
+  const contrastWithBlack = checkContrast(blended, { r: 0, g: 0, b: 0, a: 1 });
+  return contrastWithWhite > contrastWithBlack;
+};
+
+export const isLightColor = (color: string, blendedWith: string | null = null): boolean => {
+  return !isDarkColor(color, blendedWith);
+};
+
+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);
+};

package/src/index.ts

@@ -0,0 +1,2 @@
+export * from "./color.ts";
+export * from "./sML.ts";

package/src/sML.ts

@@ -0,0 +1,143 @@
+/*!
+ *                                                                                                                         (℠)
+ *  # 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
+ */
+/// <reference types="user-agent-data-types" />
+
+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;
+
+// Fallback when global 'navigator' is not available, such as in SSR environments.
+const userAgent = () => typeof navigator === "undefined" ? "" : (navigator.userAgent || "");
+const userAgentData = () => typeof navigator === "undefined" ? undefined : (navigator.userAgentData || undefined);
+
+class sMLFactory {
+    OS: OSFlags;
+    UA: UAFlags;
+    Env!: string[];
+
+    constructor() {
+        const NUAD = userAgentData(), NUA = userAgent();
+
+        const _sV = (V?: string | number) => (typeof V === "string" || typeof V === "number") && V ? String(V).replace(/_/g, ".").split(".").map(I => parseInt(I) || 0) : [];
+        const _dV = (Pre="") => {
+            if(!Pre) return [];
+            const RE = new RegExp("^.*" + Pre + "[ :\\/]?(\\d+([\\._]\\d+)*).*$");
+            if(!RE.test(NUA)) return [];
+            return _sV(NUA.replace(RE, "$1"));
+        };
+
+        this.OS = ((OS: OSFlags) => {
+            if(                /(macOS|Mac OS X)/.test(NUA)) {
+                    if(/\(iP(hone|od touch);/.test(NUA)) OS.iOS = _dV("CPU (?:iPhone )?OS ");
+                    if(             /\(iPad;/.test(NUA)) OS.iOS = OS.iPadOS = _dV("CPU (?:iPhone )?OS ");
+                else if( /(macOS|Mac OS X) \d/.test(NUA)) document.ontouchend !== undefined ? OS.iOS = OS.iPadOS = _dV() : OS.macOS = _dV("(?:macOS|Mac OS X) ");
+            } else if(      /Windows( NT)? \d/.test(NUA)) OS.Windows = (V => V[0] !== 6 || !V[1] ? V : V[1] === 1 ? [7] : V[1] === 2 ? [8] : [8, 1])(_dV("Windows(?: NT)?"));
+            else if(            /Android \d/.test(NUA)) OS.Android = _dV("Android");
+            else if(                  /CrOS/.test(NUA)) OS.ChromeOS = _dV();
+            else if(                  /X11;/.test(NUA)) OS.Linux = _dV();
+            return OS;
+        })({} as OSFlags); if(NUAD) NUAD.getHighEntropyValues(["architecture", "model", "platform", "platformVersion", "uaFullVersion"]).then((HEUAD: any) => (OS => { const Pf = HEUAD.platform, PfV = HEUAD.platformVersion; if(!Pf || !PfV) return;
+                if(         /^i(OS|P(hone|od touch))$/.test(Pf)) OS.iOS = _sV(PfV);
+            else if(                      /^iPad(OS)?$/.test(Pf)) OS.iOS = OS.iPadOS = _sV(PfV);
+            else if(/^(macOS|(Mac )?OS X|Mac(Intel)?)$/.test(Pf)) document.ontouchend !== undefined ? OS.iOS = OS.iPadOS = _sV() : OS.macOS = _sV(PfV);
+            else if(           /^(Microsoft )?Windows$/.test(Pf)) OS.Windows = _sV(PfV);
+            else if(              /^(Google )?Android$/.test(Pf)) OS.Android = _sV(PfV);
+            else if(     /^((Google )?Chrome OS|CrOS)$/.test(Pf)) OS.ChromeOS = _sV(PfV);
+            else if(             /^(Linux|Ubuntu|X11)$/.test(Pf)) OS.Linux = _sV(PfV);
+            else return; /**/ Object.keys(this.OS).forEach(Key => delete (this.OS as any)[Key]), Object.assign(this.OS, OS);
+        })({} as OSFlags));
+
+        this.UA = ((UA: UAFlags) => { let _OK = false;
+            if(NUAD && Array.isArray(NUAD.brands)) { const BnV = NUAD.brands.reduce((BnV: Record<string, number[]>, _: NavigatorUABrandVersion) => { BnV[_.brand] = [(_.version as any) * 1]; return BnV; }, {});
+                    if(BnV["Google Chrome"])  _OK = true, UA.Blink = UA.Chromium = BnV["Chromium"] || [], UA.Chrome = BnV["Google Chrome"];
+                else if(BnV["Microsoft Edge"]) _OK = true, UA.Blink = UA.Chromium = BnV["Chromium"] || [], UA.Edge = BnV["Microsoft Edge"];
+                else if(BnV["Opera"])          _OK = true, UA.Blink = UA.Chromium = BnV["Chromium"] || [], UA.Opera = BnV["Opera"];
+            } if(!_OK) {
+                if(              / Gecko\/\d/.test(NUA)) { UA.Gecko = _dV("rv");
+                        if(  / Waterfox\/\d/.test(NUA))   UA.Waterfox = _dV("Waterfox");
+                    else if(   / Firefox\/\d/.test(NUA))   UA.Firefox = _dV("Firefox");
+                } else if(        / Edge\/\d/.test(NUA)) { UA.EdgeHTML = _dV("Edge");
+                                                        UA.Edge = UA.EdgeHTML;
+                } else if(/ Chrom(ium|e)\/\d/.test(NUA)) { UA.Blink = UA.Chromium = (V => V[0] ? V : _dV("Chrome"))(_dV("Chromium"));
+                        if(     / EdgA?\/\d/.test(NUA))   UA.Edge = (V => V[0] ? V : _dV("Edg"))(_dV("EdgA"));
+                    else if(       / OPR\/\d/.test(NUA))   UA.Opera = _dV("OPR");
+                    else if(   / Vivaldi\/\d/.test(NUA))   UA.Vivaldi = _dV("Vivaldi");
+                    else if(      / Silk\/\d/.test(NUA))   UA.Silk = _dV("Silk");
+                    else if( / UCBrowser\/\d/.test(NUA))   UA.UCBrowser = _dV("UCBrowser");
+                    else if(    / Phoebe\/\d/.test(NUA))   UA.Phoebe = _dV("Phoebe");
+                    else                                   UA.Chrome = (V => V[0] ? V : UA.Chromium)(_dV("Chrome"));
+                } else if( / AppleWebKit\/\d/.test(NUA)) { UA.WebKit = _dV("AppleWebKit");
+                        if(      / CriOS \d/.test(NUA))   UA.Chrome = _dV("CriOS");
+                    else if(      / FxiOS \d/.test(NUA))   UA.Firefox = _dV("FxiOS");
+                    else if(    / EdgiOS\/\d/.test(NUA))   UA.Edge = _dV("EdgiOS");
+                    else if(   / Version\/\d/.test(NUA))   UA.Safari = _dV("Version");
+                } else if(     / Trident\/\d/.test(NUA)) { UA.Trident = _dV("Trident");
+                                                        UA.InternetExplorer = (V => V[0] ? V : _dV("MSIE"))(_dV("rv"));
+                }
+            } /*+*/ if( /[\[; ]FB(AN|_IAB)\//.test(NUA))   UA.Facebook = _dV("FBAV");
+            /*+*/ if(           / Line\/\d/.test(NUA))   UA.LINE = _dV("Line");
+            return UA;
+        })({} as UAFlags);
+
+        (this.Env as any) = { get: () => [this.OS, this.UA].reduce((Env: string[], OS_UA) => { for(const Par in OS_UA) if((OS_UA as any)[Par]) Env.push(Par); return Env; }, []) };
+    }
+}
+
+class sMLFactoryWithRequest extends sMLFactory {
+    get iOSRequest(): iOSRequest {
+        const NUAD = userAgentData(), NUA = userAgent();
+
+        if (this.OS.iOS && !this.OS.iPadOS) {
+            return "mobile";
+        } else if (this.OS.iPadOS) {
+            return (/\(iPad;/.test(NUA) || (NUAD && /^iPad(OS)?$/.test(NUAD.platform))) ? "mobile" : "desktop"
+        }
+
+        return undefined;
+    }
+}
+
+const sML = new sMLFactory();
+const sMLWithRequest = new sMLFactoryWithRequest();
+export { sML, sMLWithRequest };

package/types/src/color.d.ts

@@ -0,0 +1,27 @@
+export declare const colorToRgba: (color: string, backgroundColor?: string | null) => {
+    r: number;
+    g: number;
+    b: number;
+    a: number;
+};
+export declare const getLuminance: (color: {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}) => number;
+export declare const checkContrast: (color1: string | {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}, color2: string | {
+    r: number;
+    g: number;
+    b: number;
+    a?: number;
+}) => number;
+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/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./color.ts";
+export * from "./sML.ts";

package/types/src/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 };