@mkbabb/value.js 0.5.1 → 0.11.0

package/dist/units/color/mix.d.ts

@@ -0,0 +1,16 @@
+import { Color } from '.';
+import { ColorSpace } from './constants';
+import { HueInterpolationMethod } from './dispatch';
+/**
+ * Mix N colors with optional per-color weights.
+ *
+ * @param colors  Array of Color objects (must be ≥ 1). All should be
+ *                normalized (components in [0, 1]).
+ * @param weights Optional per-color weights (same length as `colors`).
+ *                Defaults to equal weighting. Values need not sum to 1 —
+ *                they are normalized internally.
+ * @param space   Interpolation color space (default "oklab").
+ * @param hueMethod  Hue interpolation for cylindrical spaces (default "shorter").
+ * @returns A single Color in the interpolation space.
+ */
+export declare function mixColorsN(colors: Color[], weights?: number[], space?: ColorSpace, hueMethod?: HueInterpolationMethod): Color;

package/dist/units/color/normalize.d.ts

@@ -1,10 +1,10 @@
 import { Color, ColorSpaceMap } from '.';
 import { ValueUnit } from '..';
 import { ColorSpace } from './constants';
-import { HueInterpolationMethod } from './utils';
+import { HueInterpolationMethod } from './dispatch';
 export type { HueInterpolationMethod };
-export declare const normalizeColorUnitComponent: (v: number, unit: string, colorSpace: ColorSpace, component: string, inverse?: boolean) => ValueUnit<number, string>;
+export declare const normalizeColorUnitComponent: (v: number, unit: string | undefined, colorSpace: ColorSpace, component: string, inverse?: boolean) => ValueUnit<number, string>;
 export declare const normalizeColor: (color: Color<ValueUnit<number> | number>, inverse?: boolean) => Color<ValueUnit<number>>;
 export declare const normalizeColorUnit: (color: ValueUnit<Color<ValueUnit<number>>, "color">, inverse?: boolean, inplace?: boolean) => ValueUnit<Color<ValueUnit<number>>, "color">;
 export declare const colorUnit2: <C extends ColorSpace>(color: ValueUnit<Color<ValueUnit<number>>, "color">, to?: C | null, normalized?: boolean, inverse?: boolean, inplace?: boolean) => ValueUnit<ColorSpaceMap<ValueUnit<number>>[C], "color">;
-export declare const normalizeColorUnits: (a: ValueUnit<Color<ValueUnit<number>>, "color">, b: ValueUnit<Color<ValueUnit<number>>, "color">, to?: ColorSpace, normalized?: boolean, inverse?: boolean, inplace?: boolean, hueMethod?: HueInterpolationMethod) => readonly [ValueUnit<import('.').RGBColor<ValueUnit<number, string | undefined>> | import('.').HSLColor<ValueUnit<number, string | undefined>> | import('.').HSVColor<ValueUnit<number, string | undefined>> | import('.').HWBColor<ValueUnit<number, string | undefined>> | import('.').LABColor<ValueUnit<number, string | undefined>> | import('.').LCHColor<ValueUnit<number, string | undefined>> | import('.').OKLABColor<ValueUnit<number, string | undefined>> | import('.').OKLCHColor<ValueUnit<number, string | undefined>> | import('.').XYZColor<ValueUnit<number, string | undefined>> | import('.').KelvinColor<ValueUnit<number, string | undefined>> | import('.').LinearSRGBColor<ValueUnit<number, string | undefined>> | import('.').DisplayP3Color<ValueUnit<number, string | undefined>> | import('.').AdobeRGBColor<ValueUnit<number, string | undefined>> | import('.').ProPhotoRGBColor<ValueUnit<number, string | undefined>> | import('.').Rec2020Color<ValueUnit<number, string | undefined>>, "color">, ValueUnit<import('.').RGBColor<ValueUnit<number, string | undefined>> | import('.').HSLColor<ValueUnit<number, string | undefined>> | import('.').HSVColor<ValueUnit<number, string | undefined>> | import('.').HWBColor<ValueUnit<number, string | undefined>> | import('.').LABColor<ValueUnit<number, string | undefined>> | import('.').LCHColor<ValueUnit<number, string | undefined>> | import('.').OKLABColor<ValueUnit<number, string | undefined>> | import('.').OKLCHColor<ValueUnit<number, string | undefined>> | import('.').XYZColor<ValueUnit<number, string | undefined>> | import('.').KelvinColor<ValueUnit<number, string | undefined>> | import('.').LinearSRGBColor<ValueUnit<number, string | undefined>> | import('.').DisplayP3Color<ValueUnit<number, string | undefined>> | import('.').AdobeRGBColor<ValueUnit<number, string | undefined>> | import('.').ProPhotoRGBColor<ValueUnit<number, string | undefined>> | import('.').Rec2020Color<ValueUnit<number, string | undefined>>, "color">, HueInterpolationMethod | undefined];
+export declare const normalizeColorUnits: (a: ValueUnit<Color<ValueUnit<number>>, "color">, b: ValueUnit<Color<ValueUnit<number>>, "color">, to?: ColorSpace, normalized?: boolean, inverse?: boolean, inplace?: boolean, hueMethod?: HueInterpolationMethod) => readonly [ValueUnit<import('.').RGBColor<ValueUnit<number, string>> | import('.').HSLColor<ValueUnit<number, string>> | import('.').HSVColor<ValueUnit<number, string>> | import('.').HWBColor<ValueUnit<number, string>> | import('.').LABColor<ValueUnit<number, string>> | import('.').LCHColor<ValueUnit<number, string>> | import('.').OKLABColor<ValueUnit<number, string>> | import('.').OKLCHColor<ValueUnit<number, string>> | import('.').XYZColor<ValueUnit<number, string>> | import('.').KelvinColor<ValueUnit<number, string>> | import('.').LinearSRGBColor<ValueUnit<number, string>> | import('.').DisplayP3Color<ValueUnit<number, string>> | import('.').AdobeRGBColor<ValueUnit<number, string>> | import('.').ProPhotoRGBColor<ValueUnit<number, string>> | import('.').Rec2020Color<ValueUnit<number, string>>, "color">, ValueUnit<import('.').RGBColor<ValueUnit<number, string>> | import('.').HSLColor<ValueUnit<number, string>> | import('.').HSVColor<ValueUnit<number, string>> | import('.').HWBColor<ValueUnit<number, string>> | import('.').LABColor<ValueUnit<number, string>> | import('.').LCHColor<ValueUnit<number, string>> | import('.').OKLABColor<ValueUnit<number, string>> | import('.').OKLCHColor<ValueUnit<number, string>> | import('.').XYZColor<ValueUnit<number, string>> | import('.').KelvinColor<ValueUnit<number, string>> | import('.').LinearSRGBColor<ValueUnit<number, string>> | import('.').DisplayP3Color<ValueUnit<number, string>> | import('.').AdobeRGBColor<ValueUnit<number, string>> | import('.').ProPhotoRGBColor<ValueUnit<number, string>> | import('.').Rec2020Color<ValueUnit<number, string>>, "color">, HueInterpolationMethod | undefined];

package/dist/units/index.d.ts

@@ -1,6 +1,9 @@
 import { UNITS } from './constants';
+import { ColorSpace } from './color/constants';
+import { HueInterpolationMethod } from './color/dispatch';
+import { ColorChannelPlan } from './interpolate';
 export { registerColorNames, clearCustomColorNames, getCustomColorNames } from '../parsing/color';
-export declare class ValueUnit<T = any, U = (typeof UNITS)[number] | string> {
+export declare class ValueUnit<T = any, U extends string = Exclude<(typeof UNITS)[number], undefined> | string> {
     value: T;
     unit?: U | undefined;
     superType?: string[] | undefined;
@@ -8,6 +11,23 @@ export declare class ValueUnit<T = any, U = (typeof UNITS)[number] | string> {
     property?: string | undefined;
     targets?: HTMLElement[] | undefined;
     constructor(value: T, unit?: U | undefined, superType?: string[] | undefined, subProperty?: string | undefined, property?: string | undefined, targets?: HTMLElement[] | undefined);
+    /**
+     * Fully unwrap a (possibly nested) `ValueUnit`, returning the innermost
+     * non-`ValueUnit` value.
+     *
+     * **G.W2 Lane D (G-OPP-5)** — codifies the Mar 2026 iOS Safari
+     * stack-overflow fix as a first-class `ValueUnit` primitive. The
+     * `while (raw instanceof ValueUnit) raw = raw.value` idiom was inlined
+     * across the color pipeline + the parser; each inline copy was a place the
+     * `VU<VU<…>>` accumulation guard could silently drift. This static is the
+     * single source of truth — see `test/recursion-guard.test.ts`.
+     *
+     * The conditional return type peels exactly one `ValueUnit` layer at the
+     * type level (`ValueUnit` payloads can themselves be `ValueUnit` only via
+     * the bug class this guards against, so one peel is the honest static
+     * type); at runtime the `while` loop peels every layer.
+     */
+    static unwrapDeep<T>(x: T): T extends ValueUnit<infer V> ? V : T;
     setSubProperty(subProperty: any): void;
     setProperty(property: any): void;
     setTargets(targets: HTMLElement[]): void;
@@ -48,4 +68,54 @@ export type InterpolatedVar<T> = {
     stop: ValueUnit<T>;
     value: ValueUnit<T>;
     computed: boolean;
+    /**
+     * For color interpolation in cylindrical spaces (hsl/hsv/hwb/lch/oklch):
+     * which hue-direction method to use. Defaults to `"shorter"` per CSS
+     * Color 4 §12.4 when omitted.
+     */
+    hueMethod?: HueInterpolationMethod;
+    /**
+     * For color interpolation: the color space the start/stop endpoints have
+     * been normalised into. Drives the choice of which component is the hue
+     * channel in `lerpColorValue`.
+     */
+    colorSpace?: ColorSpace;
+    /**
+     * Pre-resolved dispatch function set by `prepareInterpVar`. Avoids three
+     * sequential type checks per `lerpValue` call in hot paths. Optional —
+     * external callers can construct an `InterpolatedVar` without it and the
+     * runtime dispatch in `lerpValue` will resolve at call time.
+     */
+    _lerp?: (t: number, iv: InterpolatedVar<any>) => ValueUnit<any>;
+    /**
+     * Frozen color-channel plan set by `prepareInterpVar` for color ivs (B3).
+     * Drives the closure-free per-frame loop in `lerpColorValue`; absent for
+     * non-color ivs and externally constructed colors (which take the fallback
+     * walk). Typed loosely here to avoid a cycle with `interpolate.ts`.
+     */
+    _colorPlan?: ColorChannelPlan;
+    /**
+     * Resolved computed-endpoint cache set by `lerpComputedValue` for computed
+     * ivs (C1, tranche-F Wave C). A computed leaf (`var`/`calc`) re-resolves
+     * BOTH endpoints against the live box every frame — but the resolved pair
+     * is invariant while the layout epoch is stable, so the first frame after a
+     * (re)resolve stamps `(startN, stopN, unit, target, epoch)` here and every
+     * later frame collapses to a bare `lerp(startN, stopN, t)`. Invalidated
+     * when the target changes or the layout epoch advances (resize). Absent for
+     * non-computed ivs. Typed loosely to avoid a cycle with `interpolate.ts`.
+     */
+    _computedCache?: ComputedEndpointCache;
+};
+/**
+ * The resolved-endpoint cache stamped on a computed `InterpolatedVar` (C1).
+ * `target` and `epoch` are the invalidation keys: a steady frame whose live
+ * target and layout epoch both match the stamp serves `startN`/`stopN`/`unit`
+ * directly; any mismatch re-resolves both endpoints and re-stamps.
+ */
+export type ComputedEndpointCache = {
+    startN: number;
+    stopN: number;
+    unit: string | undefined;
+    target: HTMLElement;
+    epoch: number;
 };

package/dist/units/interpolate.d.ts

@@ -0,0 +1,70 @@
+import { Color } from './color';
+import { ValueUnit, InterpolatedVar } from './index';
+/**
+ * Interpolate a `ValueUnit` whose unit is *computed* (`var`, `calc`,
+ * `vh`, `vw`, etc.) by resolving both endpoints against a target
+ * element's live computed style and lerping the resulting numeric
+ * values.
+ *
+ * C1 (tranche-F Wave C) — the endpoint cache. The resolved
+ * `(startN, stopN, unit)` pair is invariant while the layout epoch is
+ * stable, so it is cached on the iv (`_computedCache`) the first frame
+ * and every later steady frame collapses to a bare
+ * `lerp(startN, stopN, t)` — no `getComputedValue` memo call, no
+ * `value.toString()`, no forced reflow. The cache busts when the live
+ * target changes or the layout epoch advances (resize → `bumpLayoutEpoch`).
+ * Pixel-identical while the epoch is stable.
+ *
+ * Mutates and returns the `value` field of the InterpolatedVar.
+ */
+export declare function lerpComputedValue(t: number, iv: InterpolatedVar<any>): ValueUnit<any>;
+/**
+ * A `Color` at interpolation time: its channels may be raw `number`s (numeric
+ * pipeline) or `ValueUnit<number>` wrappers (parser-produced colors). Both
+ * shapes flow through `lerpColorValue`; the per-channel `instanceof ValueUnit`
+ * branch dispatches between them.
+ */
+type InterpColor = Color<ValueUnit<number> | number>;
+/**
+ * Frozen per-frame color-channel plan (B3). Built once at `prepareInterpVar`;
+ * drives `lerpColorValue`'s closure-free hot loop. Parallel arrays (a light SoA)
+ * indexed by channel position: the unwrapped start/stop numbers, the hue
+ * channel index (or -1), the destination ValueUnit ref per channel (or null
+ * when the destination slot is a raw number written via `setChannel`).
+ */
+export type ColorChannelPlan = {
+    keys: readonly string[];
+    startN: Float64Array;
+    stopN: Float64Array;
+    hueIndex: number;
+    dstVU: (ValueUnit<number> | null)[];
+};
+/**
+ * Interpolate a colour `ValueUnit` (`unit === "color"`). Walks each
+ * channel of the parsed `Color` instance and lerps independently. The
+ * surrounding `normalizeColorUnits` step is responsible for putting
+ * `start` / `stop` in the same colour space (oklab, oklch, etc.) and
+ * for hue handling.
+ */
+export declare function lerpColorValue(t: number, iv: InterpolatedVar<InterpColor>): ValueUnit<InterpColor>;
+/** Lerp a simple numeric InterpolatedVar in-place. */
+export declare function lerpNumericValue(t: number, { start, stop, value }: InterpolatedVar<number>): ValueUnit<number>;
+/**
+ * Interpolate any `InterpolatedVar` at progress `t`.
+ *
+ * Uses a pre-resolved dispatch function (`_lerp`) when the
+ * InterpolatedVar was created via `prepareInterpVar` — avoids three
+ * sequential type checks per call in hot paths. Falls back to
+ * runtime dispatch for externally constructed values.
+ */
+export declare function lerpValue(t: number, iv: InterpolatedVar<any>): ValueUnit<any> | undefined;
+/**
+ * Pre-resolve the interpolation dispatch function on an
+ * `InterpolatedVar`. Sets a hidden `_lerp` property used by
+ * `lerpValue`'s fast path.
+ *
+ * Call once per InterpolatedVar after `normalizeValueUnits`; the
+ * dispatch is invariant for the lifetime of the InterpolatedVar.
+ */
+export declare function prepareInterpVar(iv: InterpolatedVar<any>): InterpolatedVar<any>;
+export {};

package/dist/units/normalize.d.ts

@@ -1,9 +1,59 @@
 import { ValueUnit, InterpolatedVar } from '.';
-export declare const getComputedValue: ((value: ValueUnit, target: HTMLElement) => ValueUnit<any, any>) & {
-    cache: Map<string, {
-        value: ValueUnit<any, any>;
-        timestamp: number;
-    }>;
-};
+import { ColorSpace } from './color/constants';
+import { HueInterpolationMethod } from './color/dispatch';
+import { isColorUnit } from './utils';
+/** The current layout-epoch generation. Bumped on resize. */
+export declare const getLayoutEpoch: () => number;
+/**
+ * Invalidate every layout-epoch-stamped cache (the C1 endpoint cache and the
+ * `getComputedValue` memo) by advancing the generation counter. Call on any
+ * event that changes a computed-unit resolution — a viewport `resize`, a
+ * container `ResizeObserver` callback, a writing-mode flip, etc. Cheap (one
+ * integer increment + one memo clear); the next computed frame re-resolves.
+ */
+export declare const bumpLayoutEpoch: () => number;
+/**
+ * Resolve a computed CSS value (`var()`, `calc()`, or other
+ * deferred-evaluation unit) against a target element by writing it
+ * into the target's inline style and reading back the computed
+ * style. Memoised by `(value.toString(), element-id)`.
+ *
+ * For `calc()` values whose `subProperty` names a transform axis
+ * (`translateX`, `scaleY`, etc.), the round-trip yields a `matrix()`
+ * or `matrix3d()`; this function decomposes the matrix to recover
+ * the resolved numeric value for that single axis.
+ *
+ * Caching is suppressed when the target is disconnected — layout
+ * units (`vh`, `cqw`, etc.) resolve to 0 outside the live tree, so
+ * caching that value would poison later reads.
+ */
+export declare const getComputedValue: import('../utils').Memoized<(value: ValueUnit, target?: HTMLElement) => ValueUnit<any, any>>;
+/**
+ * Convert two `ValueUnit`s of the same superType to a common base
+ * unit: length → px, angle → deg, time → ms, resolution → dpi.
+ *
+ * Throws if either input has a unit that isn't recognised for its
+ * superType — silent passthrough hides bugs upstream.
+ */
 export declare const normalizeNumericUnits: (a: ValueUnit, b: ValueUnit, inplace?: boolean) => [ValueUnit, ValueUnit];
-export declare function normalizeValueUnits(left: ValueUnit, right: ValueUnit): InterpolatedVar<any>;
+export type NormalizeValueUnitsOptions = {
+    /** Color space for color interpolation. Default: `"oklab"`. */
+    colorSpace?: ColorSpace;
+    /** Hue interpolation method for cylindrical color spaces. */
+    hueMethod?: HueInterpolationMethod;
+};
+/**
+ * Compute an `InterpolatedVar` from two endpoint `ValueUnit`s,
+ * preparing them for later `lerpValue` calls.
+ *
+ * - Colors: collapsed to a common space via `normalizeColorUnits`.
+ *   `colorSpace` defaults to `oklab` (perceptually uniform); `hueMethod`
+ *   selects the cylindrical hue interpolation strategy.
+ * - Mixed units (e.g. `10px` ↔ `1em`): collapsed via
+ *   `normalizeNumericUnits` to a common base unit.
+ * - Computed units (`var`, `calc`, `vh`, `cqw`, etc.): left as-is and
+ *   marked `computed: true`. The actual numeric resolution happens
+ *   later in `lerpComputedValue` against a live target.
+ */
+export declare function normalizeValueUnits(left: ValueUnit, right: ValueUnit, options?: NormalizeValueUnitsOptions): InterpolatedVar<unknown>;
+export { isColorUnit };

package/dist/units/utils.d.ts

@@ -1,7 +1,7 @@
 import { FunctionValue, ValueUnit } from '.';
 import { Color } from './color';
 import { ABSOLUTE_LENGTH_UNITS, ANGLE_UNITS, FREQUENCY_UNITS, PERCENTAGE_UNITS, RELATIVE_LENGTH_UNITS, RESOLUTION_UNITS, STYLE_NAMES, TIME_UNITS, UNITS, MatrixValues } from './constants';
-export declare function isColorUnit(value: ValueUnit<Color<ValueUnit>>): value is ValueUnit<Color<ValueUnit>>;
+export declare function isColorUnit(value: ValueUnit): value is ValueUnit<Color<ValueUnit>>;
 export declare const flattenObject: (obj: any) => Record<string, any>;
 export declare const unflattenObject: (flatObj: Record<string, any[]>) => any;
 export declare const unflattenObjectToString: (flatObj: Record<string, any[]>) => Record<string, string>;

package/dist/utils.d.ts

@@ -15,14 +15,15 @@ export interface MemoizeOptions<T extends (...args: any[]) => any = (...args: an
     /** When provided, the result is only cached if this returns true. */
     shouldCache?: (result: ReturnType<T>, ...args: Parameters<T>) => boolean;
 }
-export declare function memoize<T extends (...args: any[]) => any>(func: T, options?: MemoizeOptions<T>): T & {
+export type Memoized<T extends (...args: any[]) => any> = T & {
     cache: Map<string, {
         value: ReturnType<T>;
         timestamp: number;
     }>;
 };
+export declare function memoize<T extends (...args: any[]) => any>(func: T, options?: MemoizeOptions<T>): Memoized<T>;
 export declare const hyphenToCamelCase: (str: string) => string;
 export declare function camelCaseToHyphen(str: string): string;
 export declare function seekPreviousValue<T>(ix: number, values: T[], pred: (f: T) => boolean): number | undefined;
-export declare function requestAnimationFrame(callback: FrameRequestCallback): number | NodeJS.Timeout;
+export declare function requestAnimationFrame(callback: FrameRequestCallback): number;
 export declare function cancelAnimationFrame(handle: number | undefined | null | any): void;