@labpics/colors 0.9.1 → 0.10.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +381 -282
- package/adapt-theme.d.ts +76 -74
- package/adapt-theme.js +738 -542
- package/apply-theme.d.ts +16 -16
- package/apply-theme.js +45 -44
- package/build-metadata.json +19 -0
- package/effective-bg.d.ts +51 -50
- package/effective-bg.js +501 -492
- package/index.d.ts +70 -37
- package/index.js +21 -21
- package/package.json +11 -5
- package/pkg/labcolors.d.ts +282 -37
- package/pkg/labcolors.js +65 -33
- package/pkg/labcolors_bg.wasm +0 -0
- package/pkg/labcolors_bg.wasm.d.ts +2 -1
- package/watch-theme.d.ts +57 -57
- package/watch-theme.js +144 -144
package/pkg/labcolors.js
CHANGED
|
@@ -18,44 +18,30 @@ export class LabColors {
|
|
|
18
18
|
wasm.__wbg_labcolors_free(ptr, 0);
|
|
19
19
|
}
|
|
20
20
|
/**
|
|
21
|
-
*
|
|
22
|
-
*
|
|
23
|
-
*
|
|
24
|
-
*
|
|
25
|
-
*
|
|
26
|
-
*
|
|
27
|
-
*
|
|
28
|
-
*
|
|
29
|
-
* Returns a flat, background-major `Float64Array`: sample `s`, foreground `i`
|
|
30
|
-
* is at `(s * fgHexes.length + i) * 2` (`lc`) and `+1` (`wcagRatio`). The
|
|
31
|
-
* values are byte-identical to calling `recheckContrast(bgHexes[s], fgHexes,
|
|
32
|
-
* theme)` for each `s`. Wiring the runtime to it is an OWNER decision (it
|
|
33
|
-
* changes the controller↔engine call shape); it is measured, not adopted.
|
|
34
|
-
* @param {string[]} bg_hexes
|
|
35
|
-
* @param {string[]} fg_hexes
|
|
36
|
-
* @param {string} theme
|
|
37
|
-
* @returns {Float64Array}
|
|
21
|
+
* Exact stable-Glow runtime recheck. Returns whether the point screen
|
|
22
|
+
* layer is a byte-for-byte no-op for every alpha under encoded sRGB8.
|
|
23
|
+
* `adaptTheme` uses this cheap core-owned predicate to detect the only
|
|
24
|
+
* stable determinate/indeterminate class transition without running CAM16
|
|
25
|
+
* or re-solving on every animated-background frame.
|
|
26
|
+
* @param {string} tint_hex
|
|
27
|
+
* @param {string} bg_hex
|
|
28
|
+
* @returns {boolean}
|
|
38
29
|
*/
|
|
39
|
-
|
|
30
|
+
isStableGlowPointNoop(tint_hex, bg_hex) {
|
|
40
31
|
try {
|
|
41
32
|
const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
|
|
42
|
-
const ptr0 =
|
|
33
|
+
const ptr0 = passStringToWasm0(tint_hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
|
|
43
34
|
const len0 = WASM_VECTOR_LEN;
|
|
44
|
-
const ptr1 =
|
|
35
|
+
const ptr1 = passStringToWasm0(bg_hex, wasm.__wbindgen_export, wasm.__wbindgen_export2);
|
|
45
36
|
const len1 = WASM_VECTOR_LEN;
|
|
46
|
-
|
|
47
|
-
const len2 = WASM_VECTOR_LEN;
|
|
48
|
-
wasm.labcolors__recheckContrastMulti(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
|
|
37
|
+
wasm.labcolors_isStableGlowPointNoop(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1);
|
|
49
38
|
var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
|
|
50
39
|
var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
|
|
51
40
|
var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
throw takeObject(r2);
|
|
41
|
+
if (r2) {
|
|
42
|
+
throw takeObject(r1);
|
|
55
43
|
}
|
|
56
|
-
|
|
57
|
-
wasm.__wbindgen_export4(r0, r1 * 8, 8);
|
|
58
|
-
return v4;
|
|
44
|
+
return r0 !== 0;
|
|
59
45
|
} finally {
|
|
60
46
|
wasm.__wbindgen_add_to_stack_pointer(16);
|
|
61
47
|
}
|
|
@@ -99,7 +85,12 @@ export class LabColors {
|
|
|
99
85
|
}
|
|
100
86
|
}
|
|
101
87
|
/**
|
|
102
|
-
*
|
|
88
|
+
* Return the frozen legacy `muddiness` coordinate for an sRGB hex colour.
|
|
89
|
+
*
|
|
90
|
+
* This is an experimental compatibility proxy: it reproduces the historic
|
|
91
|
+
* numeric API, but is not an observer-validated human clean/dirty verdict
|
|
92
|
+
* or a production decision. The legacy identifier is retained only for
|
|
93
|
+
* compatibility.
|
|
103
94
|
* @param {string} hex
|
|
104
95
|
* @returns {number}
|
|
105
96
|
*/
|
|
@@ -173,6 +164,47 @@ export class LabColors {
|
|
|
173
164
|
wasm.__wbindgen_add_to_stack_pointer(16);
|
|
174
165
|
}
|
|
175
166
|
}
|
|
167
|
+
/**
|
|
168
|
+
* Recheck one foreground set against MANY background samples in a single
|
|
169
|
+
* call. The reactive controller's worst-case loop rechecks the same
|
|
170
|
+
* foregrounds against every sample of a varying backdrop (gradient / image /
|
|
171
|
+
* bg-blur / glass); the dominant per-foreground CAM16 forward is background-
|
|
172
|
+
* independent, so this shares it across all samples instead of recomputing it
|
|
173
|
+
* per `recheckContrast` call — a measured ~2.6x on the multi-sample recheck.
|
|
174
|
+
*
|
|
175
|
+
* Returns a flat, background-major `Float64Array`: sample `s`, foreground `i`
|
|
176
|
+
* is at `(s * fgHexes.length + i) * 2` (`lc`) and `+1` (`wcagRatio`). The
|
|
177
|
+
* values are byte-identical to calling `recheckContrast(bgHexes[s], fgHexes,
|
|
178
|
+
* theme)` for each `s`.
|
|
179
|
+
* @param {string[]} bg_hexes
|
|
180
|
+
* @param {string[]} fg_hexes
|
|
181
|
+
* @param {string} theme
|
|
182
|
+
* @returns {Float64Array}
|
|
183
|
+
*/
|
|
184
|
+
recheckContrastMulti(bg_hexes, fg_hexes, theme) {
|
|
185
|
+
try {
|
|
186
|
+
const retptr = wasm.__wbindgen_add_to_stack_pointer(-16);
|
|
187
|
+
const ptr0 = passArrayJsValueToWasm0(bg_hexes, wasm.__wbindgen_export);
|
|
188
|
+
const len0 = WASM_VECTOR_LEN;
|
|
189
|
+
const ptr1 = passArrayJsValueToWasm0(fg_hexes, wasm.__wbindgen_export);
|
|
190
|
+
const len1 = WASM_VECTOR_LEN;
|
|
191
|
+
const ptr2 = passStringToWasm0(theme, wasm.__wbindgen_export, wasm.__wbindgen_export2);
|
|
192
|
+
const len2 = WASM_VECTOR_LEN;
|
|
193
|
+
wasm.labcolors_recheckContrastMulti(retptr, this.__wbg_ptr, ptr0, len0, ptr1, len1, ptr2, len2);
|
|
194
|
+
var r0 = getDataViewMemory0().getInt32(retptr + 4 * 0, true);
|
|
195
|
+
var r1 = getDataViewMemory0().getInt32(retptr + 4 * 1, true);
|
|
196
|
+
var r2 = getDataViewMemory0().getInt32(retptr + 4 * 2, true);
|
|
197
|
+
var r3 = getDataViewMemory0().getInt32(retptr + 4 * 3, true);
|
|
198
|
+
if (r3) {
|
|
199
|
+
throw takeObject(r2);
|
|
200
|
+
}
|
|
201
|
+
var v4 = getArrayF64FromWasm0(r0, r1).slice();
|
|
202
|
+
wasm.__wbindgen_export4(r0, r1 * 8, 8);
|
|
203
|
+
return v4;
|
|
204
|
+
} finally {
|
|
205
|
+
wasm.__wbindgen_add_to_stack_pointer(16);
|
|
206
|
+
}
|
|
207
|
+
}
|
|
176
208
|
/**
|
|
177
209
|
* Resolve every role for `bgHex` under `theme` (`"light" | "dark" |
|
|
178
210
|
* "light-ic" | "dark-ic"`).
|
|
@@ -180,9 +212,9 @@ export class LabColors {
|
|
|
180
212
|
* Returns a `ResolvedTheme` object. Per-role unreachability is part of a
|
|
181
213
|
* successful result (each role carries its own `kind`); only whole-call
|
|
182
214
|
* failures reject (no config loaded yet as `config_required`, invalid hex,
|
|
183
|
-
* unknown theme, and the by-construction-
|
|
184
|
-
* failure as `internal_error`) — as a
|
|
185
|
-
* error, never an unwound panic.
|
|
215
|
+
* unknown theme, a core invariant failure, and the by-construction-
|
|
216
|
+
* unreachable oklch serialisation failure as `internal_error`) — as a
|
|
217
|
+
* structured `"<code>: <message>"` error, never an unwound panic.
|
|
186
218
|
* @param {string} bg_hex
|
|
187
219
|
* @param {string} theme
|
|
188
220
|
* @returns {ResolvedTheme}
|
package/pkg/labcolors_bg.wasm
CHANGED
|
Binary file
|
|
@@ -2,11 +2,12 @@
|
|
|
2
2
|
/* eslint-disable */
|
|
3
3
|
export const memory: WebAssembly.Memory;
|
|
4
4
|
export const __wbg_labcolors_free: (a: number, b: number) => void;
|
|
5
|
-
export const
|
|
5
|
+
export const labcolors_isStableGlowPointNoop: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
|
|
6
6
|
export const labcolors_loadConfig: (a: number, b: number, c: number, d: number) => void;
|
|
7
7
|
export const labcolors_muddiness: (a: number, b: number, c: number, d: number) => void;
|
|
8
8
|
export const labcolors_new: () => number;
|
|
9
9
|
export const labcolors_recheckContrast: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
|
|
10
|
+
export const labcolors_recheckContrastMulti: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) => void;
|
|
10
11
|
export const labcolors_resolveTheme: (a: number, b: number, c: number, d: number, e: number, f: number) => void;
|
|
11
12
|
export const __wbindgen_export: (a: number, b: number) => number;
|
|
12
13
|
export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
|
package/watch-theme.d.ts
CHANGED
|
@@ -1,57 +1,57 @@
|
|
|
1
|
-
// Public types for the reactive theme runtime.
|
|
2
|
-
|
|
3
|
-
import type { LabColors, ResolvedTheme, ThemeName } from "./pkg/labcolors.js";
|
|
4
|
-
|
|
5
|
-
export interface WatchThemeOptions {
|
|
6
|
-
/** An initialised `LabColors` engine (after `await init()`). */
|
|
7
|
-
colors: Pick<LabColors, "resolveTheme">;
|
|
8
|
-
/** Theme name. */
|
|
9
|
-
theme: ThemeName;
|
|
10
|
-
/**
|
|
11
|
-
* Explicit effective background, overriding the ancestor-composite. Use a hex
|
|
12
|
-
* string or a `() => hex` you sample yourself for image/gradient/blur surfaces
|
|
13
|
-
* that have no single readable `background-color`.
|
|
14
|
-
*/
|
|
15
|
-
background?: string | (() => string);
|
|
16
|
-
/** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
|
|
17
|
-
target?: HTMLElement;
|
|
18
|
-
/** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
|
|
19
|
-
fallback?: string;
|
|
20
|
-
/** Auto-refresh on DOM attribute mutations. Default `true`. */
|
|
21
|
-
observe?: boolean;
|
|
22
|
-
/** Mutation-observer root. Defaults to the document element. */
|
|
23
|
-
root?: Node;
|
|
24
|
-
/** Window-like host (for `MutationObserver`). Defaults to `globalThis`. */
|
|
25
|
-
win?: Window;
|
|
26
|
-
/** Injection seam for the computed style of an element (testing). */
|
|
27
|
-
getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
|
|
28
|
-
/** Injection seam for an element's parent (testing). */
|
|
29
|
-
parentOf?: (element: unknown) => unknown;
|
|
30
|
-
}
|
|
31
|
-
|
|
32
|
-
export interface WatchController {
|
|
33
|
-
/**
|
|
34
|
-
* Re-resolve and re-apply if the effective background (or theme) changed;
|
|
35
|
-
* `force` re-applies unconditionally. Returns the now-applied result, or the
|
|
36
|
-
* cached one when nothing changed.
|
|
37
|
-
*/
|
|
38
|
-
refresh(force?: boolean): ResolvedTheme | null;
|
|
39
|
-
/** Switch theme and re-apply. */
|
|
40
|
-
setTheme(theme: ThemeName): void;
|
|
41
|
-
/** The effective background hex last resolved. */
|
|
42
|
-
background(): string;
|
|
43
|
-
/** Disconnect observers and stop watching. */
|
|
44
|
-
stop(): void;
|
|
45
|
-
}
|
|
46
|
-
|
|
47
|
-
/**
|
|
48
|
-
* Keep an element's `--lab-*` variables in sync with its (effective) background.
|
|
49
|
-
*
|
|
50
|
-
* Discrete background/theme changes are caught by a `MutationObserver`;
|
|
51
|
-
* continuous (animated) backgrounds are driven by calling `refresh()` from a
|
|
52
|
-
* `requestAnimationFrame` loop (cheap — re-resolves only on real change).
|
|
53
|
-
*/
|
|
54
|
-
export declare function watchTheme(
|
|
55
|
-
element: HTMLElement,
|
|
56
|
-
options: WatchThemeOptions,
|
|
57
|
-
): WatchController;
|
|
1
|
+
// Public types for the reactive theme runtime.
|
|
2
|
+
|
|
3
|
+
import type { LabColors, ResolvedTheme, ThemeName } from "./pkg/labcolors.js";
|
|
4
|
+
|
|
5
|
+
export interface WatchThemeOptions {
|
|
6
|
+
/** An initialised `LabColors` engine (after `await init()`). */
|
|
7
|
+
colors: Pick<LabColors, "resolveTheme">;
|
|
8
|
+
/** Theme name. */
|
|
9
|
+
theme: ThemeName;
|
|
10
|
+
/**
|
|
11
|
+
* Explicit effective background, overriding the ancestor-composite. Use a hex
|
|
12
|
+
* string or a `() => hex` you sample yourself for image/gradient/blur surfaces
|
|
13
|
+
* that have no single readable `background-color`.
|
|
14
|
+
*/
|
|
15
|
+
background?: string | (() => string);
|
|
16
|
+
/** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
|
|
17
|
+
target?: HTMLElement;
|
|
18
|
+
/** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
|
|
19
|
+
fallback?: string;
|
|
20
|
+
/** Auto-refresh on DOM attribute mutations. Default `true`. */
|
|
21
|
+
observe?: boolean;
|
|
22
|
+
/** Mutation-observer root. Defaults to the document element. */
|
|
23
|
+
root?: Node;
|
|
24
|
+
/** Window-like host (for `MutationObserver`). Defaults to `globalThis`. */
|
|
25
|
+
win?: Window;
|
|
26
|
+
/** Injection seam for the computed style of an element (testing). */
|
|
27
|
+
getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
|
|
28
|
+
/** Injection seam for an element's parent (testing). */
|
|
29
|
+
parentOf?: (element: unknown) => unknown;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export interface WatchController {
|
|
33
|
+
/**
|
|
34
|
+
* Re-resolve and re-apply if the effective background (or theme) changed;
|
|
35
|
+
* `force` re-applies unconditionally. Returns the now-applied result, or the
|
|
36
|
+
* cached one when nothing changed.
|
|
37
|
+
*/
|
|
38
|
+
refresh(force?: boolean): ResolvedTheme | null;
|
|
39
|
+
/** Switch theme and re-apply. */
|
|
40
|
+
setTheme(theme: ThemeName): void;
|
|
41
|
+
/** The effective background hex last resolved. */
|
|
42
|
+
background(): string;
|
|
43
|
+
/** Disconnect observers and stop watching. */
|
|
44
|
+
stop(): void;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
/**
|
|
48
|
+
* Keep an element's `--lab-*` variables in sync with its (effective) background.
|
|
49
|
+
*
|
|
50
|
+
* Discrete background/theme changes are caught by a `MutationObserver`;
|
|
51
|
+
* continuous (animated) backgrounds are driven by calling `refresh()` from a
|
|
52
|
+
* `requestAnimationFrame` loop (cheap — re-resolves only on real change).
|
|
53
|
+
*/
|
|
54
|
+
export declare function watchTheme(
|
|
55
|
+
element: HTMLElement,
|
|
56
|
+
options: WatchThemeOptions,
|
|
57
|
+
): WatchController;
|
package/watch-theme.js
CHANGED
|
@@ -1,144 +1,144 @@
|
|
|
1
|
-
// Reactive theme runtime — zero dependencies.
|
|
2
|
-
//
|
|
3
|
-
// `applyTheme` writes a resolved theme's `--lab-*` variables onto an element
|
|
4
|
-
// once. `watchTheme` closes the loop the css-injection-runtime chapter left
|
|
5
|
-
// open: it keeps an element's variables *in sync* with its background. Point it
|
|
6
|
-
// at a surface and theming follows the background — the seamless drop-in for a
|
|
7
|
-
// design system that re-resolves against a changing background.
|
|
8
|
-
//
|
|
9
|
-
// It serves both regimes:
|
|
10
|
-
// * DISCRETE changes (theme switch, a class/style toggle, DOM reflow) are
|
|
11
|
-
// caught automatically by a `MutationObserver` — call once, forget.
|
|
12
|
-
// * CONTINUOUS changes (a CSS-animated or per-frame-scripted background that
|
|
13
|
-
// never mutates inline style) are driven by the caller calling `refresh()`
|
|
14
|
-
// inside its own `requestAnimationFrame` loop. `refresh()` is cheap: it
|
|
15
|
-
// re-resolves only when the effective background actually changed, so a
|
|
16
|
-
// steady background costs one string compare per frame, not a WASM solve.
|
|
17
|
-
//
|
|
18
|
-
// The effective background is computed by alpha-compositing ancestors
|
|
19
|
-
// (`effective-bg.js`); for surfaces over images/gradients/blur — which have no
|
|
20
|
-
// single readable colour — pass an explicit `background` (a hex string or a
|
|
21
|
-
// `() => hex` you sample yourself).
|
|
22
|
-
|
|
23
|
-
import { applyTheme } from "./apply-theme.js";
|
|
24
|
-
import { effectiveBackground } from "./effective-bg.js";
|
|
25
|
-
|
|
26
|
-
/**
|
|
27
|
-
* @typedef {object} WatchController
|
|
28
|
-
* @property {(force?: boolean) => (object | null)} refresh Re-resolve+apply if the
|
|
29
|
-
* background (or theme) changed; `force` re-applies unconditionally. Returns the
|
|
30
|
-
* `resolveTheme` result that is now applied, or `null` if nothing was applied.
|
|
31
|
-
* @property {(theme: string) => void} setTheme Switch theme and re-apply.
|
|
32
|
-
* @property {() => string} background The effective background hex last resolved.
|
|
33
|
-
* @property {() => void} stop Disconnect observers and stop watching.
|
|
34
|
-
*/
|
|
35
|
-
|
|
36
|
-
/**
|
|
37
|
-
* Keep `element`'s `--lab-*` variables in sync with its (effective) background.
|
|
38
|
-
*
|
|
39
|
-
* @param {*} element The surface to read the background from and (by default)
|
|
40
|
-
* write the variables onto.
|
|
41
|
-
* @param {object} options
|
|
42
|
-
* @param {{ resolveTheme: (bgHex: string, theme: string) => object }} options.colors
|
|
43
|
-
* An initialised `LabColors` engine (already `await init()`-ed).
|
|
44
|
-
* @param {string} options.theme Theme name (`"light" | "dark" | …`).
|
|
45
|
-
* @param {string | (() => string)} [options.background] Explicit effective
|
|
46
|
-
* background, overriding the ancestor-composite (use for image/gradient/blur
|
|
47
|
-
* surfaces you sample yourself).
|
|
48
|
-
* @param {*} [options.target=element] Element to write the variables onto.
|
|
49
|
-
* @param {string} [options.fallback="#FFFFFF"] Base for a fully-translucent chain.
|
|
50
|
-
* @param {boolean} [options.observe=true] Auto-refresh on DOM attribute mutations.
|
|
51
|
-
* @param {*} [options.root] Mutation-observer root (default: the document element).
|
|
52
|
-
* @param {*} [options.win=globalThis] Window-like host (for MutationObserver).
|
|
53
|
-
* @param {(el:*)=>*} [options.getStyle] Injection seam for `effectiveBackground`.
|
|
54
|
-
* @param {(el:*)=>*} [options.parentOf] Injection seam for `effectiveBackground`.
|
|
55
|
-
* @returns {WatchController}
|
|
56
|
-
*/
|
|
57
|
-
export function watchTheme(element, options) {
|
|
58
|
-
if (!options || typeof options.colors?.resolveTheme !== "function") {
|
|
59
|
-
throw new TypeError("watchTheme: options.colors must be an initialised LabColors engine");
|
|
60
|
-
}
|
|
61
|
-
if (typeof options.theme !== "string") {
|
|
62
|
-
throw new TypeError("watchTheme: options.theme must be a theme name string");
|
|
63
|
-
}
|
|
64
|
-
|
|
65
|
-
const target = options.target ?? element;
|
|
66
|
-
const fallback = options.fallback ?? "#FFFFFF";
|
|
67
|
-
const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
|
|
68
|
-
let theme = options.theme;
|
|
69
|
-
let lastBg = null;
|
|
70
|
-
let lastTheme = null;
|
|
71
|
-
let lastResult = null;
|
|
72
|
-
|
|
73
|
-
const readBackground = () => {
|
|
74
|
-
const b = options.background;
|
|
75
|
-
if (typeof b === "function") return b();
|
|
76
|
-
if (typeof b === "string") return b;
|
|
77
|
-
return effectiveBackground(element, {
|
|
78
|
-
fallback,
|
|
79
|
-
getStyle: options.getStyle,
|
|
80
|
-
parentOf: options.parentOf,
|
|
81
|
-
});
|
|
82
|
-
};
|
|
83
|
-
|
|
84
|
-
const refresh = (force = false) => {
|
|
85
|
-
const bg = readBackground();
|
|
86
|
-
if (!force && bg === lastBg && theme === lastTheme) return lastResult;
|
|
87
|
-
const result = options.colors.resolveTheme(bg, theme);
|
|
88
|
-
applyTheme(target, result);
|
|
89
|
-
lastBg = bg;
|
|
90
|
-
lastTheme = theme;
|
|
91
|
-
lastResult = result;
|
|
92
|
-
return result;
|
|
93
|
-
};
|
|
94
|
-
|
|
95
|
-
// Coalesce a burst of mutations into a single refresh on the next microtask.
|
|
96
|
-
let scheduled = false;
|
|
97
|
-
let stopped = false;
|
|
98
|
-
const schedule = () => {
|
|
99
|
-
if (scheduled || stopped) return;
|
|
100
|
-
scheduled = true;
|
|
101
|
-
Promise.resolve().then(() => {
|
|
102
|
-
scheduled = false;
|
|
103
|
-
// A `stop()` between scheduling and this microtask must cancel the refresh
|
|
104
|
-
// — the watcher is done, no late writes.
|
|
105
|
-
if (!stopped) refresh();
|
|
106
|
-
});
|
|
107
|
-
};
|
|
108
|
-
|
|
109
|
-
let observer = null;
|
|
110
|
-
if (options.observe !== false && win && typeof win.MutationObserver === "function") {
|
|
111
|
-
const root =
|
|
112
|
-
options.root ??
|
|
113
|
-
(typeof win.document !== "undefined" ? win.document.documentElement : null);
|
|
114
|
-
if (root) {
|
|
115
|
-
observer = new win.MutationObserver(schedule);
|
|
116
|
-
// A background can change on the element OR any ancestor, via inline style
|
|
117
|
-
// or a class swap — so watch attribute changes across the subtree.
|
|
118
|
-
observer.observe(root, {
|
|
119
|
-
subtree: true,
|
|
120
|
-
attributes: true,
|
|
121
|
-
attributeFilter: ["style", "class"],
|
|
122
|
-
});
|
|
123
|
-
}
|
|
124
|
-
}
|
|
125
|
-
|
|
126
|
-
// Apply immediately so the surface is correct on creation.
|
|
127
|
-
refresh(true);
|
|
128
|
-
|
|
129
|
-
return {
|
|
130
|
-
refresh,
|
|
131
|
-
setTheme(next) {
|
|
132
|
-
theme = next;
|
|
133
|
-
refresh();
|
|
134
|
-
},
|
|
135
|
-
background() {
|
|
136
|
-
return lastBg;
|
|
137
|
-
},
|
|
138
|
-
stop() {
|
|
139
|
-
stopped = true;
|
|
140
|
-
if (observer) observer.disconnect();
|
|
141
|
-
observer = null;
|
|
142
|
-
},
|
|
143
|
-
};
|
|
144
|
-
}
|
|
1
|
+
// Reactive theme runtime — zero dependencies.
|
|
2
|
+
//
|
|
3
|
+
// `applyTheme` writes a resolved theme's `--lab-*` variables onto an element
|
|
4
|
+
// once. `watchTheme` closes the loop the css-injection-runtime chapter left
|
|
5
|
+
// open: it keeps an element's variables *in sync* with its background. Point it
|
|
6
|
+
// at a surface and theming follows the background — the seamless drop-in for a
|
|
7
|
+
// design system that re-resolves against a changing background.
|
|
8
|
+
//
|
|
9
|
+
// It serves both regimes:
|
|
10
|
+
// * DISCRETE changes (theme switch, a class/style toggle, DOM reflow) are
|
|
11
|
+
// caught automatically by a `MutationObserver` — call once, forget.
|
|
12
|
+
// * CONTINUOUS changes (a CSS-animated or per-frame-scripted background that
|
|
13
|
+
// never mutates inline style) are driven by the caller calling `refresh()`
|
|
14
|
+
// inside its own `requestAnimationFrame` loop. `refresh()` is cheap: it
|
|
15
|
+
// re-resolves only when the effective background actually changed, so a
|
|
16
|
+
// steady background costs one string compare per frame, not a WASM solve.
|
|
17
|
+
//
|
|
18
|
+
// The effective background is computed by alpha-compositing ancestors
|
|
19
|
+
// (`effective-bg.js`); for surfaces over images/gradients/blur — which have no
|
|
20
|
+
// single readable colour — pass an explicit `background` (a hex string or a
|
|
21
|
+
// `() => hex` you sample yourself).
|
|
22
|
+
|
|
23
|
+
import { applyTheme } from "./apply-theme.js";
|
|
24
|
+
import { effectiveBackground } from "./effective-bg.js";
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @typedef {object} WatchController
|
|
28
|
+
* @property {(force?: boolean) => (object | null)} refresh Re-resolve+apply if the
|
|
29
|
+
* background (or theme) changed; `force` re-applies unconditionally. Returns the
|
|
30
|
+
* `resolveTheme` result that is now applied, or `null` if nothing was applied.
|
|
31
|
+
* @property {(theme: string) => void} setTheme Switch theme and re-apply.
|
|
32
|
+
* @property {() => string} background The effective background hex last resolved.
|
|
33
|
+
* @property {() => void} stop Disconnect observers and stop watching.
|
|
34
|
+
*/
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Keep `element`'s `--lab-*` variables in sync with its (effective) background.
|
|
38
|
+
*
|
|
39
|
+
* @param {*} element The surface to read the background from and (by default)
|
|
40
|
+
* write the variables onto.
|
|
41
|
+
* @param {object} options
|
|
42
|
+
* @param {{ resolveTheme: (bgHex: string, theme: string) => object }} options.colors
|
|
43
|
+
* An initialised `LabColors` engine (already `await init()`-ed).
|
|
44
|
+
* @param {string} options.theme Theme name (`"light" | "dark" | …`).
|
|
45
|
+
* @param {string | (() => string)} [options.background] Explicit effective
|
|
46
|
+
* background, overriding the ancestor-composite (use for image/gradient/blur
|
|
47
|
+
* surfaces you sample yourself).
|
|
48
|
+
* @param {*} [options.target=element] Element to write the variables onto.
|
|
49
|
+
* @param {string} [options.fallback="#FFFFFF"] Base for a fully-translucent chain.
|
|
50
|
+
* @param {boolean} [options.observe=true] Auto-refresh on DOM attribute mutations.
|
|
51
|
+
* @param {*} [options.root] Mutation-observer root (default: the document element).
|
|
52
|
+
* @param {*} [options.win=globalThis] Window-like host (for MutationObserver).
|
|
53
|
+
* @param {(el:*)=>*} [options.getStyle] Injection seam for `effectiveBackground`.
|
|
54
|
+
* @param {(el:*)=>*} [options.parentOf] Injection seam for `effectiveBackground`.
|
|
55
|
+
* @returns {WatchController}
|
|
56
|
+
*/
|
|
57
|
+
export function watchTheme(element, options) {
|
|
58
|
+
if (!options || typeof options.colors?.resolveTheme !== "function") {
|
|
59
|
+
throw new TypeError("watchTheme: options.colors must be an initialised LabColors engine");
|
|
60
|
+
}
|
|
61
|
+
if (typeof options.theme !== "string") {
|
|
62
|
+
throw new TypeError("watchTheme: options.theme must be a theme name string");
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
const target = options.target ?? element;
|
|
66
|
+
const fallback = options.fallback ?? "#FFFFFF";
|
|
67
|
+
const win = options.win ?? (typeof globalThis !== "undefined" ? globalThis : undefined);
|
|
68
|
+
let theme = options.theme;
|
|
69
|
+
let lastBg = null;
|
|
70
|
+
let lastTheme = null;
|
|
71
|
+
let lastResult = null;
|
|
72
|
+
|
|
73
|
+
const readBackground = () => {
|
|
74
|
+
const b = options.background;
|
|
75
|
+
if (typeof b === "function") return b();
|
|
76
|
+
if (typeof b === "string") return b;
|
|
77
|
+
return effectiveBackground(element, {
|
|
78
|
+
fallback,
|
|
79
|
+
getStyle: options.getStyle,
|
|
80
|
+
parentOf: options.parentOf,
|
|
81
|
+
});
|
|
82
|
+
};
|
|
83
|
+
|
|
84
|
+
const refresh = (force = false) => {
|
|
85
|
+
const bg = readBackground();
|
|
86
|
+
if (!force && bg === lastBg && theme === lastTheme) return lastResult;
|
|
87
|
+
const result = options.colors.resolveTheme(bg, theme);
|
|
88
|
+
applyTheme(target, result);
|
|
89
|
+
lastBg = bg;
|
|
90
|
+
lastTheme = theme;
|
|
91
|
+
lastResult = result;
|
|
92
|
+
return result;
|
|
93
|
+
};
|
|
94
|
+
|
|
95
|
+
// Coalesce a burst of mutations into a single refresh on the next microtask.
|
|
96
|
+
let scheduled = false;
|
|
97
|
+
let stopped = false;
|
|
98
|
+
const schedule = () => {
|
|
99
|
+
if (scheduled || stopped) return;
|
|
100
|
+
scheduled = true;
|
|
101
|
+
Promise.resolve().then(() => {
|
|
102
|
+
scheduled = false;
|
|
103
|
+
// A `stop()` between scheduling and this microtask must cancel the refresh
|
|
104
|
+
// — the watcher is done, no late writes.
|
|
105
|
+
if (!stopped) refresh();
|
|
106
|
+
});
|
|
107
|
+
};
|
|
108
|
+
|
|
109
|
+
let observer = null;
|
|
110
|
+
if (options.observe !== false && win && typeof win.MutationObserver === "function") {
|
|
111
|
+
const root =
|
|
112
|
+
options.root ??
|
|
113
|
+
(typeof win.document !== "undefined" ? win.document.documentElement : null);
|
|
114
|
+
if (root) {
|
|
115
|
+
observer = new win.MutationObserver(schedule);
|
|
116
|
+
// A background can change on the element OR any ancestor, via inline style
|
|
117
|
+
// or a class swap — so watch attribute changes across the subtree.
|
|
118
|
+
observer.observe(root, {
|
|
119
|
+
subtree: true,
|
|
120
|
+
attributes: true,
|
|
121
|
+
attributeFilter: ["style", "class"],
|
|
122
|
+
});
|
|
123
|
+
}
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
// Apply immediately so the surface is correct on creation.
|
|
127
|
+
refresh(true);
|
|
128
|
+
|
|
129
|
+
return {
|
|
130
|
+
refresh,
|
|
131
|
+
setTheme(next) {
|
|
132
|
+
theme = next;
|
|
133
|
+
refresh();
|
|
134
|
+
},
|
|
135
|
+
background() {
|
|
136
|
+
return lastBg;
|
|
137
|
+
},
|
|
138
|
+
stop() {
|
|
139
|
+
stopped = true;
|
|
140
|
+
if (observer) observer.disconnect();
|
|
141
|
+
observer = null;
|
|
142
|
+
},
|
|
143
|
+
};
|
|
144
|
+
}
|