@labpics/colors 0.8.0 → 0.9.1
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/README.md +282 -271
- package/adapt-theme.d.ts +74 -67
- package/adapt-theme.js +542 -525
- package/apply-theme.d.ts +16 -16
- package/apply-theme.js +44 -44
- package/effective-bg.d.ts +50 -50
- package/effective-bg.js +492 -492
- package/index.d.ts +37 -37
- package/index.js +21 -21
- package/package.json +16 -2
- package/pkg/labcolors_bg.wasm +0 -0
- package/watch-theme.d.ts +57 -57
- package/watch-theme.js +144 -144
package/adapt-theme.d.ts
CHANGED
|
@@ -1,67 +1,74 @@
|
|
|
1
|
-
// Public types for the adaptive hysteresis controller.
|
|
2
|
-
|
|
3
|
-
import type { LabColors, ThemeName } from "./pkg/labcolors.js";
|
|
4
|
-
|
|
5
|
-
export interface AdaptThemeOptions {
|
|
6
|
-
/**
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
*
|
|
11
|
-
*
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
/**
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
/**
|
|
50
|
-
|
|
51
|
-
/**
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
|
|
67
|
-
|
|
1
|
+
// Public types for the adaptive hysteresis controller.
|
|
2
|
+
|
|
3
|
+
import type { LabColors, ThemeName } from "./pkg/labcolors.js";
|
|
4
|
+
|
|
5
|
+
export interface AdaptThemeOptions {
|
|
6
|
+
/**
|
|
7
|
+
* An initialised engine — needs `resolveTheme` AND `recheckContrast`.
|
|
8
|
+
* `recheckContrastMulti` is optional: when present, a multi-sample backdrop
|
|
9
|
+
* is rechecked in ONE batched call per frame (byte-identical to the
|
|
10
|
+
* per-sample loop, locked by the wasm boundary parity test); when absent,
|
|
11
|
+
* the controller falls back to N `recheckContrast` calls.
|
|
12
|
+
*/
|
|
13
|
+
colors: Pick<LabColors, "resolveTheme" | "recheckContrast"> &
|
|
14
|
+
Partial<Pick<LabColors, "recheckContrastMulti">>;
|
|
15
|
+
theme: ThemeName;
|
|
16
|
+
/**
|
|
17
|
+
* Explicit effective background, overriding the ancestor-composite. A single
|
|
18
|
+
* hex is one solid surface; an array (or a function returning one) is a set of
|
|
19
|
+
* worst-case samples of a varying backdrop (gradient / image / video the
|
|
20
|
+
* caller sampled), and the colours are held legible against the hardest
|
|
21
|
+
* sample. With one sample this is identical to plain single-background mode.
|
|
22
|
+
*/
|
|
23
|
+
background?: string | string[] | (() => string | string[]);
|
|
24
|
+
/** Element to write the `--lab-*` variables onto. Defaults to the watched element. */
|
|
25
|
+
target?: HTMLElement;
|
|
26
|
+
/** Base colour when the ancestor chain is fully translucent. Default `"#FFFFFF"`. */
|
|
27
|
+
fallback?: string;
|
|
28
|
+
/** Fraction of a role's contrast surplus that may be lost before a re-solve. Default `0.2`. */
|
|
29
|
+
dropFraction?: number;
|
|
30
|
+
/** A breach must persist this many ms before re-solving (debounce). Default `120`. */
|
|
31
|
+
sustainMs?: number;
|
|
32
|
+
/** Minimum ms between re-solves (dwell / rate cap). Default `250`. */
|
|
33
|
+
dwellMs?: number;
|
|
34
|
+
/** Crossfade duration in ms. Default `280` (capped to a short fade under reduced motion). */
|
|
35
|
+
easeMs?: number;
|
|
36
|
+
/**
|
|
37
|
+
* Hold each role's WCAG legal floor every frame of the ease: an interpolated
|
|
38
|
+
* colour is only shown while it still clears the role's `legalFloor` against
|
|
39
|
+
* the live background (for text on animated content / `prefers-contrast`).
|
|
40
|
+
* Default `false` (the free ease — brief surplus dips, destination always legal).
|
|
41
|
+
*/
|
|
42
|
+
strict?: boolean;
|
|
43
|
+
/** Override reduced-motion detection (default reads `matchMedia`). */
|
|
44
|
+
reducedMotion?: boolean;
|
|
45
|
+
/** Clock injection (default `performance.now`/`Date.now`). */
|
|
46
|
+
now?: () => number;
|
|
47
|
+
/** Window-like host (rAF, matchMedia). Defaults to `globalThis`. */
|
|
48
|
+
win?: Window;
|
|
49
|
+
/** Injection seam for the computed style of an element (testing). */
|
|
50
|
+
getStyle?: (element: unknown) => { getPropertyValue(property: string): string };
|
|
51
|
+
/** Injection seam for an element's parent (testing). */
|
|
52
|
+
parentOf?: (element: unknown) => unknown;
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
export interface AdaptController {
|
|
56
|
+
/** Drive one step. Cheap (a re-check); re-solves only on a sustained breach. */
|
|
57
|
+
tick(now?: number): void;
|
|
58
|
+
/** Switch theme INSTANTLY (intent, not drift) — bypasses the hysteresis. */
|
|
59
|
+
setTheme(theme: ThemeName): void;
|
|
60
|
+
/** Begin an internal `requestAnimationFrame` loop. */
|
|
61
|
+
start(): void;
|
|
62
|
+
/** Stop the loop. */
|
|
63
|
+
stop(): void;
|
|
64
|
+
/** The currently-applied `--lab-*` variables. */
|
|
65
|
+
current(): Record<string, string>;
|
|
66
|
+
}
|
|
67
|
+
|
|
68
|
+
/**
|
|
69
|
+
* Keep an element's `--lab-*` variables adapting to its (changing) background
|
|
70
|
+
* **lazily and smoothly**: re-check each frame, hold while colours still pass,
|
|
71
|
+
* and re-solve + ease only when contrast stably degrades. The calm, cheap
|
|
72
|
+
* alternative to re-solving every frame.
|
|
73
|
+
*/
|
|
74
|
+
export declare function adaptTheme(element: HTMLElement, options: AdaptThemeOptions): AdaptController;
|