@labpics/colors 0.1.0 → 0.2.0

package/apply-theme.d.ts

@@ -1,16 +1,16 @@
-import type { ResolvedTheme } from "./pkg/labcolors.js";
-
-/**
- * Apply a resolved theme's CSS variables to an element.
- *
- * Writes every reachable role from `result.vars` onto `element.style` via
- * `setProperty`. Unreachable and zero-token roles are absent from `vars` and
- * are not written, so the caller's CSS fallbacks stay in effect for them.
- *
- * @param element The target element (e.g. `document.documentElement`).
- * @param result A `LabColors.resolveTheme(...)` result.
- */
-export declare function applyTheme(
-  element: HTMLElement,
-  result: Pick<ResolvedTheme, "vars">,
-): void;
+import type { ResolvedTheme } from "./pkg/labcolors.js";
+
+/**
+ * Apply a resolved theme's CSS variables to an element.
+ *
+ * Writes every reachable role from `result.vars` onto `element.style` via
+ * `setProperty`. Unreachable and zero-token roles are absent from `vars` and
+ * are not written, so the caller's CSS fallbacks stay in effect for them.
+ *
+ * @param element The target element (e.g. `document.documentElement`).
+ * @param result A `LabColors.resolveTheme(...)` result.
+ */
+export declare function applyTheme(
+  element: HTMLElement,
+  result: Pick<ResolvedTheme, "vars">,
+): void;

package/apply-theme.js

@@ -1,44 +1,44 @@
-// Vanilla DOM helper — zero dependencies.
-//
-// The WASM core returns data and never touches the DOM (that separation is
-// deliberate; full reactive injection is the css-injection-runtime chapter).
-// This helper is the minimal, framework-free bridge: write a resolved theme's
-// reachable colours onto an element as `--lab-*` custom properties.
-
-const LAB_VAR_PREFIX = "--lab-";
-
-/**
- * Apply a resolved theme's CSS variables to an element.
- *
- * First clears every inline `--lab-*` custom property a previous call set on
- * this element, then writes every reachable role from `result.vars` via
- * `setProperty`. Unreachable and zero-token (`none`) roles carry no colour, so
- * they are absent from `vars` and are not written — the caller's CSS fallbacks
- * stay in effect for those, including across theme re-application (a role
- * reachable in the previous theme but not in the new one does not linger).
- *
- * @param {HTMLElement} element - The target element (e.g. `document.documentElement`).
- * @param {{ vars: Record<string, string> }} result - A `resolveTheme(...)` result.
- * @returns {void}
- */
-export function applyTheme(element, result) {
-  if (!element || typeof element.style?.setProperty !== "function") {
-    throw new TypeError("applyTheme: first argument must be an element with a style");
-  }
-  if (!result || typeof result.vars !== "object" || result.vars === null) {
-    throw new TypeError("applyTheme: second argument must be a resolveTheme result");
-  }
-  // Inline style is a live list; collect names first, then remove, so the
-  // iteration is not invalidated mid-walk.
-  const stale = [];
-  for (let i = 0; i < element.style.length; i++) {
-    const name = element.style.item(i);
-    if (name.startsWith(LAB_VAR_PREFIX)) stale.push(name);
-  }
-  for (const name of stale) {
-    element.style.removeProperty(name);
-  }
-  for (const [name, value] of Object.entries(result.vars)) {
-    element.style.setProperty(name, value);
-  }
-}
+// Vanilla DOM helper — zero dependencies.
+//
+// The WASM core returns data and never touches the DOM (that separation is
+// deliberate; full reactive injection is the css-injection-runtime chapter).
+// This helper is the minimal, framework-free bridge: write a resolved theme's
+// reachable colours onto an element as `--lab-*` custom properties.
+
+const LAB_VAR_PREFIX = "--lab-";
+
+/**
+ * Apply a resolved theme's CSS variables to an element.
+ *
+ * First clears every inline `--lab-*` custom property a previous call set on
+ * this element, then writes every reachable role from `result.vars` via
+ * `setProperty`. Unreachable and zero-token (`none`) roles carry no colour, so
+ * they are absent from `vars` and are not written — the caller's CSS fallbacks
+ * stay in effect for those, including across theme re-application (a role
+ * reachable in the previous theme but not in the new one does not linger).
+ *
+ * @param {HTMLElement} element - The target element (e.g. `document.documentElement`).
+ * @param {{ vars: Record<string, string> }} result - A `resolveTheme(...)` result.
+ * @returns {void}
+ */
+export function applyTheme(element, result) {
+  if (!element || typeof element.style?.setProperty !== "function") {
+    throw new TypeError("applyTheme: first argument must be an element with a style");
+  }
+  if (!result || typeof result.vars !== "object" || result.vars === null) {
+    throw new TypeError("applyTheme: second argument must be a resolveTheme result");
+  }
+  // Inline style is a live list; collect names first, then remove, so the
+  // iteration is not invalidated mid-walk.
+  const stale = [];
+  for (let i = 0; i < element.style.length; i++) {
+    const name = element.style.item(i);
+    if (name.startsWith(LAB_VAR_PREFIX)) stale.push(name);
+  }
+  for (const name of stale) {
+    element.style.removeProperty(name);
+  }
+  for (const [name, value] of Object.entries(result.vars)) {
+    element.style.setProperty(name, value);
+  }
+}

package/effective-bg.d.ts

@@ -1,48 +1,48 @@
-// Public types for the effective-background resolver.
-
-/** `[r, g, b, a]` — r,g,b in 0..255, a in 0..1. */
-export type Rgba = [number, number, number, number];
-
-/** A computed-style-like accessor: only `getPropertyValue` is used. */
-export interface StyleLike {
-  getPropertyValue(property: string): string;
-}
-
-export interface EffectiveBackgroundOptions {
-  /** Base colour when the ancestor chain never reaches an opaque layer. Default `"#FFFFFF"`. */
-  fallback?: string;
-  /** Injection seam for the computed style of an element. Defaults to `getComputedStyle`. */
-  getStyle?: (element: unknown) => StyleLike;
-  /** Injection seam for an element's parent. Defaults to `el.parentElement`. */
-  parentOf?: (element: unknown) => unknown;
-  /** Guard against detached/cyclic chains. Default `64`. */
-  maxDepth?: number;
-}
-
-/** Parse a CSS colour string into `[r,g,b,a]`, or `null` if unrecognised. */
-export declare function parseCssColor(css: string): Rgba | null;
-
-/** Porter-Duff source-over composite of `top` onto `bottom`. */
-export declare function compositeOver(top: Rgba, bottom: Rgba): Rgba;
-
-/** `[r,g,b]` (0..255) → `#RRGGBB`. */
-export declare function toHex(rgb: Rgba | [number, number, number]): string;
-
-/**
- * Interpolate two `#RRGGBB` colours in Oklab at `t ∈ [0,1]` → `#RRGGBB`.
- * Perceptually uniform (even crossfade timing, non-muddy chroma path); endpoints
- * are exact and out-of-gamut intermediates are clamped per channel.
- */
-export declare function oklabLerp(fromHex: string, toHex_: string, t: number): string;
-
-/** Composite an ordered front-to-back layer stack over an opaque base → `#RRGGBB`. */
-export declare function compositeStackToHex(layersFrontToBack: Rgba[], opaqueBase: Rgba): string;
-
-/**
- * The opaque effective background `#RRGGBB` visible behind `element`'s content,
- * by walking ancestors and alpha-compositing their `background-color`s.
- */
-export declare function effectiveBackground(
-  element: unknown,
-  opts?: EffectiveBackgroundOptions,
-): string;
+// Public types for the effective-background resolver.
+
+/** `[r, g, b, a]` — r,g,b in 0..255, a in 0..1. */
+export type Rgba = [number, number, number, number];
+
+/** A computed-style-like accessor: only `getPropertyValue` is used. */
+export interface StyleLike {
+  getPropertyValue(property: string): string;
+}
+
+export interface EffectiveBackgroundOptions {
+  /** Base colour when the ancestor chain never reaches an opaque layer. Default `"#FFFFFF"`. */
+  fallback?: string;
+  /** Injection seam for the computed style of an element. Defaults to `getComputedStyle`. */
+  getStyle?: (element: unknown) => StyleLike;
+  /** Injection seam for an element's parent. Defaults to `el.parentElement`. */
+  parentOf?: (element: unknown) => unknown;
+  /** Guard against detached/cyclic chains. Default `64`. */
+  maxDepth?: number;
+}
+
+/** Parse a CSS colour string into `[r,g,b,a]`, or `null` if unrecognised. */
+export declare function parseCssColor(css: string): Rgba | null;
+
+/** Porter-Duff source-over composite of `top` onto `bottom`. */
+export declare function compositeOver(top: Rgba, bottom: Rgba): Rgba;
+
+/** `[r,g,b]` (0..255) → `#RRGGBB`. */
+export declare function toHex(rgb: Rgba | [number, number, number]): string;
+
+/**
+ * Interpolate two `#RRGGBB` colours in Oklab at `t ∈ [0,1]` → `#RRGGBB`.
+ * Perceptually uniform (even crossfade timing, non-muddy chroma path); endpoints
+ * are exact and out-of-gamut intermediates are clamped per channel.
+ */
+export declare function oklabLerp(fromHex: string, toHex_: string, t: number): string;
+
+/** Composite an ordered front-to-back layer stack over an opaque base → `#RRGGBB`. */
+export declare function compositeStackToHex(layersFrontToBack: Rgba[], opaqueBase: Rgba): string;
+
+/**
+ * The opaque effective background `#RRGGBB` visible behind `element`'s content,
+ * by walking ancestors and alpha-compositing their `background-color`s.
+ */
+export declare function effectiveBackground(
+  element: unknown,
+  opts?: EffectiveBackgroundOptions,
+): string;