@labpics/colors 0.1.0 → 0.3.0

package/package.json

@@ -1,65 +1,65 @@
-{
-  "name": "@labpics/colors",
-  "version": "0.1.0",
-  "description": "Framework-agnostic contrast engine: resolve accessible, perceptually-anchored colour roles for any background. WASM core, zero runtime dependencies.",
-  "type": "module",
-  "license": "MIT",
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
-  },
-  "repository": {
-    "type": "git",
-    "url": "https://github.com/Labpics-Team/lab-colors",
-    "directory": "packages/colors"
-  },
-  "exports": {
-    ".": {
-      "types": "./index.d.ts",
-      "default": "./index.js"
-    },
-    "./apply-theme": {
-      "types": "./apply-theme.d.ts",
-      "default": "./apply-theme.js"
-    },
-    "./watch-theme": {
-      "types": "./watch-theme.d.ts",
-      "default": "./watch-theme.js"
-    },
-    "./adapt-theme": {
-      "types": "./adapt-theme.d.ts",
-      "default": "./adapt-theme.js"
-    },
-    "./effective-bg": {
-      "types": "./effective-bg.d.ts",
-      "default": "./effective-bg.js"
-    }
-  },
-  "files": [
-    "index.js",
-    "index.d.ts",
-    "apply-theme.js",
-    "apply-theme.d.ts",
-    "watch-theme.js",
-    "watch-theme.d.ts",
-    "adapt-theme.js",
-    "adapt-theme.d.ts",
-    "effective-bg.js",
-    "effective-bg.d.ts",
-    "pkg/labcolors.js",
-    "pkg/labcolors.d.ts",
-    "pkg/labcolors_bg.wasm",
-    "pkg/labcolors_bg.wasm.d.ts"
-  ],
-  "scripts": {
-    "//build": "wasm-pack resolves --out-dir relative to the CRATE dir (crates/labcolors-wasm), not the cwd, so the ../../packages path is correct and unambiguous regardless of where npm runs it.",
-    "build": "wasm-pack build ../../crates/labcolors-wasm --release --target web --out-dir ../../packages/colors/pkg --out-name labcolors",
-    "typecheck": "tsc --noEmit -p tsconfig.json",
-    "test": "node --test"
-  },
-  "devDependencies": {
-    "typescript": "^5.5.0"
-  },
-  "types": "./index.d.ts",
-  "sideEffects": false
-}
+{
+  "name": "@labpics/colors",
+  "version": "0.3.0",
+  "description": "Framework-agnostic contrast engine: resolve accessible, perceptually-anchored colour roles for any background. WASM core, zero runtime dependencies.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Labpics-Team/lab-colors",
+    "directory": "packages/colors"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./apply-theme": {
+      "types": "./apply-theme.d.ts",
+      "default": "./apply-theme.js"
+    },
+    "./watch-theme": {
+      "types": "./watch-theme.d.ts",
+      "default": "./watch-theme.js"
+    },
+    "./adapt-theme": {
+      "types": "./adapt-theme.d.ts",
+      "default": "./adapt-theme.js"
+    },
+    "./effective-bg": {
+      "types": "./effective-bg.d.ts",
+      "default": "./effective-bg.js"
+    }
+  },
+  "files": [
+    "index.js",
+    "index.d.ts",
+    "apply-theme.js",
+    "apply-theme.d.ts",
+    "watch-theme.js",
+    "watch-theme.d.ts",
+    "adapt-theme.js",
+    "adapt-theme.d.ts",
+    "effective-bg.js",
+    "effective-bg.d.ts",
+    "pkg/labcolors.js",
+    "pkg/labcolors.d.ts",
+    "pkg/labcolors_bg.wasm",
+    "pkg/labcolors_bg.wasm.d.ts"
+  ],
+  "scripts": {
+    "//build": "wasm-pack resolves --out-dir relative to the CRATE dir (crates/labcolors-wasm), not the cwd, so the ../../packages path is correct and unambiguous regardless of where npm runs it.",
+    "build": "wasm-pack build ../../crates/labcolors-wasm --release --target web --out-dir ../../packages/colors/pkg --out-name labcolors",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "test": "node --test"
+  },
+  "devDependencies": {
+    "typescript": "^5.5.0"
+  },
+  "types": "./index.d.ts",
+  "sideEffects": false
+}

package/pkg/labcolors.js

@@ -191,11 +191,11 @@ if (Symbol.dispose) LabColors.prototype[Symbol.dispose] = LabColors.prototype.fr
 function __wbg_get_imports() {
     const import0 = {
         __proto__: null,
-        __wbg_Error_9dc85fe1bc224456: function(arg0, arg1) {
+        __wbg_Error_92b29b0548f8b746: function(arg0, arg1) {
             const ret = Error(getStringFromWasm0(arg0, arg1));
             return addHeapObject(ret);
         },
-        __wbg___wbindgen_string_get_fa2687d531ed17a5: function(arg0, arg1) {
+        __wbg___wbindgen_string_get_b0ca35b86a603356: function(arg0, arg1) {
             const obj = getObject(arg1);
             const ret = typeof(obj) === 'string' ? obj : undefined;
             var ptr1 = isLikeNone(ret) ? 0 : passStringToWasm0(ret, wasm.__wbindgen_export, wasm.__wbindgen_export2);
@@ -203,14 +203,14 @@ function __wbg_get_imports() {
             getDataViewMemory0().setInt32(arg0 + 4 * 1, len1, true);
             getDataViewMemory0().setInt32(arg0 + 4 * 0, ptr1, true);
         },
-        __wbg___wbindgen_throw_bbadd78c1bac3a77: function(arg0, arg1) {
+        __wbg___wbindgen_throw_344f42d3211c4765: function(arg0, arg1) {
             throw new Error(getStringFromWasm0(arg0, arg1));
         },
-        __wbg_new_20b778a4c5c691c3: function() {
+        __wbg_new_da52cf8fe3429cb2: function() {
             const ret = new Object();
             return addHeapObject(ret);
         },
-        __wbg_set_a6ba3ac0e634b822: function() { return handleError(function (arg0, arg1, arg2) {
+        __wbg_set_8535240470bf2500: function() { return handleError(function (arg0, arg1, arg2) {
             const ret = Reflect.set(getObject(arg0), getObject(arg1), getObject(arg2));
             return ret;
         }, arguments); },

package/watch-theme.d.ts

@@ -1,57 +1,57 @@
-// Public types for the reactive theme runtime.
-
-import type { LabColors, ResolvedTheme, ThemeName } from "./pkg/labcolors.js";
-
-export interface WatchThemeOptions {
-  /** An initialised `LabColors` engine (after `await init()`). */
-  colors: Pick<LabColors, "resolveTheme">;
-  /** Theme name. */
-  theme: ThemeName;
-  /**
-   * Explicit effective background, overriding the ancestor-composite. Use a hex
-   * string or a `() => hex` you sample yourself for image/gradient/blur surfaces
-   * that have no single readable `background-color`.
-   */
-  background?: string | (() => string);
-  /** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
-  target?: HTMLElement;
-  /** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
-  fallback?: string;
-  /** Auto-refresh on DOM attribute mutations. Default `true`. */
-  observe?: boolean;
-  /** Mutation-observer root. Defaults to the document element. */
-  root?: Node;
-  /** Window-like host (for `MutationObserver`). Defaults to `globalThis`. */
-  win?: Window;
-  /** Injection seam for the computed style of an element (testing). */
-  getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
-  /** Injection seam for an element's parent (testing). */
-  parentOf?: (element: unknown) => unknown;
-}
-
-export interface WatchController {
-  /**
-   * Re-resolve and re-apply if the effective background (or theme) changed;
-   * `force` re-applies unconditionally. Returns the now-applied result, or the
-   * cached one when nothing changed.
-   */
-  refresh(force?: boolean): ResolvedTheme | null;
-  /** Switch theme and re-apply. */
-  setTheme(theme: ThemeName): void;
-  /** The effective background hex last resolved. */
-  background(): string;
-  /** Disconnect observers and stop watching. */
-  stop(): void;
-}
-
-/**
- * Keep an element's `--lab-*` variables in sync with its (effective) background.
- *
- * Discrete background/theme changes are caught by a `MutationObserver`;
- * continuous (animated) backgrounds are driven by calling `refresh()` from a
- * `requestAnimationFrame` loop (cheap — re-resolves only on real change).
- */
-export declare function watchTheme(
-  element: HTMLElement,
-  options: WatchThemeOptions,
-): WatchController;
+// Public types for the reactive theme runtime.
+
+import type { LabColors, ResolvedTheme, ThemeName } from "./pkg/labcolors.js";
+
+export interface WatchThemeOptions {
+  /** An initialised `LabColors` engine (after `await init()`). */
+  colors: Pick<LabColors, "resolveTheme">;
+  /** Theme name. */
+  theme: ThemeName;
+  /**
+   * Explicit effective background, overriding the ancestor-composite. Use a hex
+   * string or a `() => hex` you sample yourself for image/gradient/blur surfaces
+   * that have no single readable `background-color`.
+   */
+  background?: string | (() => string);
+  /** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
+  target?: HTMLElement;
+  /** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
+  fallback?: string;
+  /** Auto-refresh on DOM attribute mutations. Default `true`. */
+  observe?: boolean;
+  /** Mutation-observer root. Defaults to the document element. */
+  root?: Node;
+  /** Window-like host (for `MutationObserver`). Defaults to `globalThis`. */
+  win?: Window;
+  /** Injection seam for the computed style of an element (testing). */
+  getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
+  /** Injection seam for an element's parent (testing). */
+  parentOf?: (element: unknown) => unknown;
+}
+
+export interface WatchController {
+  /**
+   * Re-resolve and re-apply if the effective background (or theme) changed;
+   * `force` re-applies unconditionally. Returns the now-applied result, or the
+   * cached one when nothing changed.
+   */
+  refresh(force?: boolean): ResolvedTheme | null;
+  /** Switch theme and re-apply. */
+  setTheme(theme: ThemeName): void;
+  /** The effective background hex last resolved. */
+  background(): string;
+  /** Disconnect observers and stop watching. */
+  stop(): void;
+}
+
+/**
+ * Keep an element's `--lab-*` variables in sync with its (effective) background.
+ *
+ * Discrete background/theme changes are caught by a `MutationObserver`;
+ * continuous (animated) backgrounds are driven by calling `refresh()` from a
+ * `requestAnimationFrame` loop (cheap — re-resolves only on real change).
+ */
+export declare function watchTheme(
+  element: HTMLElement,
+  options: WatchThemeOptions,
+): WatchController;

package/watch-theme.js

@@ -1,144 +1,144 @@
-// Reactive theme runtime — zero dependencies.
-//
-// `applyTheme` writes a resolved theme's `--lab-*` variables onto an element
-// once. `watchTheme` closes the loop the css-injection-runtime chapter left
-// open: it keeps an element's variables *in sync* with its background. Point it
-// at a surface and theming follows the background — the seamless drop-in for a
-// design system that re-resolves against a changing background.
-//
-// It serves both regimes:
-//   * DISCRETE changes (theme switch, a class/style toggle, DOM reflow) are
-//     caught automatically by a `MutationObserver` — call once, forget.
-//   * CONTINUOUS changes (a CSS-animated or per-frame-scripted background that
-//     never mutates inline style) are driven by the caller calling `refresh()`
-//     inside its own `requestAnimationFrame` loop. `refresh()` is cheap: it
-//     re-resolves only when the effective background actually changed, so a
-//     steady background costs one string compare per frame, not a WASM solve.
-//
-// The effective background is computed by alpha-compositing ancestors
-// (`effective-bg.js`); for surfaces over images/gradients/blur — which have no
-// single readable colour — pass an explicit `background` (a hex string or a
-// `() => hex` you sample yourself).
-
-import { applyTheme } from "./apply-theme.js";
-import { effectiveBackground } from "./effective-bg.js";
-
-/**
- * @typedef {object} WatchController
- * @property {(force?: boolean) => (object | null)} refresh  Re-resolve+apply if the
- *   background (or theme) changed; `force` re-applies unconditionally. Returns the
- *   `resolveTheme` result that is now applied, or `null` if nothing was applied.
- * @property {(theme: string) => void} setTheme  Switch theme and re-apply.
- * @property {() => string} background  The effective background hex last resolved.
- * @property {() => void} stop  Disconnect observers and stop watching.
- */
-
-/**
- * Keep `element`'s `--lab-*` variables in sync with its (effective) background.
- *
- * @param {*} element  The surface to read the background from and (by default)
- *   write the variables onto.
- * @param {object} options
- * @param {{ resolveTheme: (bgHex: string, theme: string) => object }} options.colors
- *   An initialised `LabColors` engine (already `await init()`-ed).
- * @param {string} options.theme  Theme name (`"light" | "dark" | …`).
- * @param {string | (() => string)} [options.background]  Explicit effective
- *   background, overriding the ancestor-composite (use for image/gradient/blur
- *   surfaces you sample yourself).
- * @param {*} [options.target=element]  Element to write the variables onto.
- * @param {string} [options.fallback="#FFFFFF"]  Base for a fully-translucent chain.
- * @param {boolean} [options.observe=true]  Auto-refresh on DOM attribute mutations.
- * @param {*} [options.root]  Mutation-observer root (default: the document element).
- * @param {*} [options.win=globalThis]  Window-like host (for MutationObserver).
- * @param {(el:*)=>*} [options.getStyle]  Injection seam for `effectiveBackground`.
- * @param {(el:*)=>*} [options.parentOf]  Injection seam for `effectiveBackground`.
- * @returns {WatchController}
- */
-export function watchTheme(element, options) {
-  if (!options || typeof options.colors?.resolveTheme !== "function") {
-    throw new TypeError("watchTheme: options.colors must be an initialised LabColors engine");
-  }
-  if (typeof options.theme !== "string") {
-    throw new TypeError("watchTheme: options.theme must be a theme name string");
-  }
-
-  const target = options.target ?? element;
-  const fallback = options.fallback ?? "#FFFFFF";
-  const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
-  let theme = options.theme;
-  let lastBg = null;
-  let lastTheme = null;
-  let lastResult = null;
-
-  const readBackground = () => {
-    const b = options.background;
-    if (typeof b === "function") return b();
-    if (typeof b === "string") return b;
-    return effectiveBackground(element, {
-      fallback,
-      getStyle: options.getStyle,
-      parentOf: options.parentOf,
-    });
-  };
-
-  const refresh = (force = false) => {
-    const bg = readBackground();
-    if (!force && bg === lastBg && theme === lastTheme) return lastResult;
-    const result = options.colors.resolveTheme(bg, theme);
-    applyTheme(target, result);
-    lastBg = bg;
-    lastTheme = theme;
-    lastResult = result;
-    return result;
-  };
-
-  // Coalesce a burst of mutations into a single refresh on the next microtask.
-  let scheduled = false;
-  let stopped = false;
-  const schedule = () => {
-    if (scheduled || stopped) return;
-    scheduled = true;
-    Promise.resolve().then(() => {
-      scheduled = false;
-      // A `stop()` between scheduling and this microtask must cancel the refresh
-      // — the watcher is done, no late writes.
-      if (!stopped) refresh();
-    });
-  };
-
-  let observer = null;
-  if (options.observe !== false && win && typeof win.MutationObserver === "function") {
-    const root =
-      options.root ??
-      (typeof win.document !== "undefined" ? win.document.documentElement : null);
-    if (root) {
-      observer = new win.MutationObserver(schedule);
-      // A background can change on the element OR any ancestor, via inline style
-      // or a class swap — so watch attribute changes across the subtree.
-      observer.observe(root, {
-        subtree: true,
-        attributes: true,
-        attributeFilter: ["style", "class"],
-      });
-    }
-  }
-
-  // Apply immediately so the surface is correct on creation.
-  refresh(true);
-
-  return {
-    refresh,
-    setTheme(next) {
-      theme = next;
-      refresh();
-    },
-    background() {
-      return lastBg;
-    },
-    stop() {
-      stopped = true;
-      if (observer) observer.disconnect();
-      observer = null;
-    },
-  };
-}
+// Reactive theme runtime — zero dependencies.
+//
+// `applyTheme` writes a resolved theme's `--lab-*` variables onto an element
+// once. `watchTheme` closes the loop the css-injection-runtime chapter left
+// open: it keeps an element's variables *in sync* with its background. Point it
+// at a surface and theming follows the background — the seamless drop-in for a
+// design system that re-resolves against a changing background.
+//
+// It serves both regimes:
+//   * DISCRETE changes (theme switch, a class/style toggle, DOM reflow) are
+//     caught automatically by a `MutationObserver` — call once, forget.
+//   * CONTINUOUS changes (a CSS-animated or per-frame-scripted background that
+//     never mutates inline style) are driven by the caller calling `refresh()`
+//     inside its own `requestAnimationFrame` loop. `refresh()` is cheap: it
+//     re-resolves only when the effective background actually changed, so a
+//     steady background costs one string compare per frame, not a WASM solve.
+//
+// The effective background is computed by alpha-compositing ancestors
+// (`effective-bg.js`); for surfaces over images/gradients/blur — which have no
+// single readable colour — pass an explicit `background` (a hex string or a
+// `() => hex` you sample yourself).
+
+import { applyTheme } from "./apply-theme.js";
+import { effectiveBackground } from "./effective-bg.js";
+
+/**
+ * @typedef {object} WatchController
+ * @property {(force?: boolean) => (object | null)} refresh  Re-resolve+apply if the
+ *   background (or theme) changed; `force` re-applies unconditionally. Returns the
+ *   `resolveTheme` result that is now applied, or `null` if nothing was applied.
+ * @property {(theme: string) => void} setTheme  Switch theme and re-apply.
+ * @property {() => string} background  The effective background hex last resolved.
+ * @property {() => void} stop  Disconnect observers and stop watching.
+ */
+
+/**
+ * Keep `element`'s `--lab-*` variables in sync with its (effective) background.
+ *
+ * @param {*} element  The surface to read the background from and (by default)
+ *   write the variables onto.
+ * @param {object} options
+ * @param {{ resolveTheme: (bgHex: string, theme: string) => object }} options.colors
+ *   An initialised `LabColors` engine (already `await init()`-ed).
+ * @param {string} options.theme  Theme name (`"light" | "dark" | …`).
+ * @param {string | (() => string)} [options.background]  Explicit effective
+ *   background, overriding the ancestor-composite (use for image/gradient/blur
+ *   surfaces you sample yourself).
+ * @param {*} [options.target=element]  Element to write the variables onto.
+ * @param {string} [options.fallback="#FFFFFF"]  Base for a fully-translucent chain.
+ * @param {boolean} [options.observe=true]  Auto-refresh on DOM attribute mutations.
+ * @param {*} [options.root]  Mutation-observer root (default: the document element).
+ * @param {*} [options.win=globalThis]  Window-like host (for MutationObserver).
+ * @param {(el:*)=>*} [options.getStyle]  Injection seam for `effectiveBackground`.
+ * @param {(el:*)=>*} [options.parentOf]  Injection seam for `effectiveBackground`.
+ * @returns {WatchController}
+ */
+export function watchTheme(element, options) {
+  if (!options || typeof options.colors?.resolveTheme !== "function") {
+    throw new TypeError("watchTheme: options.colors must be an initialised LabColors engine");
+  }
+  if (typeof options.theme !== "string") {
+    throw new TypeError("watchTheme: options.theme must be a theme name string");
+  }
+
+  const target = options.target ?? element;
+  const fallback = options.fallback ?? "#FFFFFF";
+  const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
+  let theme = options.theme;
+  let lastBg = null;
+  let lastTheme = null;
+  let lastResult = null;
+
+  const readBackground = () => {
+    const b = options.background;
+    if (typeof b === "function") return b();
+    if (typeof b === "string") return b;
+    return effectiveBackground(element, {
+      fallback,
+      getStyle: options.getStyle,
+      parentOf: options.parentOf,
+    });
+  };
+
+  const refresh = (force = false) => {
+    const bg = readBackground();
+    if (!force && bg === lastBg && theme === lastTheme) return lastResult;
+    const result = options.colors.resolveTheme(bg, theme);
+    applyTheme(target, result);
+    lastBg = bg;
+    lastTheme = theme;
+    lastResult = result;
+    return result;
+  };
+
+  // Coalesce a burst of mutations into a single refresh on the next microtask.
+  let scheduled = false;
+  let stopped = false;
+  const schedule = () => {
+    if (scheduled || stopped) return;
+    scheduled = true;
+    Promise.resolve().then(() => {
+      scheduled = false;
+      // A `stop()` between scheduling and this microtask must cancel the refresh
+      // — the watcher is done, no late writes.
+      if (!stopped) refresh();
+    });
+  };
+
+  let observer = null;
+  if (options.observe !== false && win && typeof win.MutationObserver === "function") {
+    const root =
+      options.root ??
+      (typeof win.document !== "undefined" ? win.document.documentElement : null);
+    if (root) {
+      observer = new win.MutationObserver(schedule);
+      // A background can change on the element OR any ancestor, via inline style
+      // or a class swap — so watch attribute changes across the subtree.
+      observer.observe(root, {
+        subtree: true,
+        attributes: true,
+        attributeFilter: ["style", "class"],
+      });
+    }
+  }
+
+  // Apply immediately so the surface is correct on creation.
+  refresh(true);
+
+  return {
+    refresh,
+    setTheme(next) {
+      theme = next;
+      refresh();
+    },
+    background() {
+      return lastBg;
+    },
+    stop() {
+      stopped = true;
+      if (observer) observer.disconnect();
+      observer = null;
+    },
+  };
+}