@mkbabb/value.js 0.3.1 → 0.4.0

package/dist/value.d.ts

@@ -627,7 +627,7 @@ export declare const COLOR_SPACE_RANGES: {
             };
             readonly number: {
                 readonly min: 0;
-                readonly max: 100;
+                readonly max: 1;
             };
         };
         readonly a: {
@@ -669,7 +669,7 @@ export declare const COLOR_SPACE_RANGES: {
             };
             readonly number: {
                 readonly min: 0;
-                readonly max: 100;
+                readonly max: 1;
             };
         };
         readonly c: {
@@ -1033,12 +1033,16 @@ export declare function convertToDegrees(value: number, unit: (typeof ANGLE_UNIT
 
 export declare function convertToDPI(value: number, unit: (typeof RESOLUTION_UNITS)[number]): number;
 
+export declare function convertToHz(value: number, unit: (typeof FREQUENCY_UNITS)[number]): number;
+
 export declare function convertToMs(value: number, unit: (typeof TIME_UNITS)[number]): number;
 
 export declare function convertToPixels(value: number, unit: (typeof ABSOLUTE_LENGTH_UNITS)[number] | (typeof RELATIVE_LENGTH_UNITS)[number] | (typeof PERCENTAGE_UNITS)[number], element?: HTMLElement, property?: string): number;
 
 export declare function createHash(algorithm: string, data: string): Promise<string>;
 
+export declare const CSS_WIDE_KEYWORDS: readonly ["inherit", "initial", "unset", "revert", "revert-layer"];
+
 export declare const CSSColor: {
     Value: Parser<ValueUnit<any, string | undefined>>;
     colorValue: Parser<ValueUnit<any, string | undefined>>;
@@ -1048,7 +1052,7 @@ export declare const CSSColor: {
     div: Parser<string>;
 };
 
-export declare const CSSCubicBezier: (x1: number, y1: number, x2: number, y2: number) => (t: number) => number;
+export declare const CSSCubicBezier: (x1: number, y1: number, x2: number, y2: number) => (x: number) => number;
 
 export declare function cssFiltersToString(filters: number[]): string;
 
@@ -1060,6 +1064,8 @@ export declare const CSSFunction: {
 
 export declare const CSSJSON: Parser<ValueUnit<any, string>>;
 
+export declare function cssLinear(stops: LinearStop[]): (t: number) => number;
+
 export declare const CSSString: Parser<ValueUnit<string, string | undefined>>;
 
 export declare const CSSValues: {
@@ -1072,7 +1078,9 @@ export declare const CSSValueUnit: {
     Angle: Parser<ValueUnit<number, string>>;
     Time: Parser<ValueUnit<number, string>>;
     TimePercentage: Parser<ValueUnit<any, string | undefined>>;
+    Frequency: Parser<ValueUnit<number, string>>;
     Resolution: Parser<ValueUnit<number, string>>;
+    Flex: Parser<ValueUnit<number, string>>;
     Percentage: Parser<ValueUnit<any, string | undefined>>;
     Color: Parser<ValueUnit<any, string | undefined>>;
     Slash: Parser<ValueUnit<string, string>>;
@@ -1094,6 +1102,48 @@ export declare function debounce<T extends (...args: any[]) => any>(func: T, wai
 
 export declare function deCasteljau(t: number, points: number[]): number;
 
+export declare interface DecomposedMatrix2D {
+    translateX: number;
+    translateY: number;
+    scaleX: number;
+    scaleY: number;
+    angle: number;
+    skew: number;
+}
+
+export declare interface DecomposedMatrix3D {
+    translate: [number, number, number];
+    scale: [number, number, number];
+    skew: [number, number, number];
+    quaternion: Vec4;
+    perspective: Vec4;
+}
+
+/**
+ * Decompose a 2D CSS matrix(a, b, c, d, e, f) into translate, scale, rotation, and skew.
+ *
+ * The matrix maps like:
+ *   | a c e |
+ *   | b d f |
+ *   | 0 0 1 |
+ */
+export declare function decomposeMatrix2D(a: number, b: number, c: number, d: number, e: number, f: number): DecomposedMatrix2D;
+
+/**
+ * Decompose a CSS matrix3d (16 values in column-major CSS order) into
+ * translate, scale, skew, rotation (quaternion), and perspective.
+ *
+ * CSS `matrix3d(a1,b1,c1,d1, a2,b2,c2,d2, a3,b3,c3,d3, a4,b4,c4,d4)` maps to:
+ *   | a1 a2 a3 a4 |
+ *   | b1 b2 b3 b4 |
+ *   | c1 c2 c3 c4 |
+ *   | d1 d2 d3 d4 |
+ * The parameter order is already column-major: [a1,b1,c1,d1, a2,b2,c2,d2, ...].
+ *
+ * Based on the "unmatrix" algorithm from the CSS Transforms spec.
+ */
+export declare function decomposeMatrix3D(cssValues: number[]): DecomposedMatrix3D | null;
+
 /**
  * Analytical sRGB gamut mapping based on Bjorn Ottosson's ok_color.h
  * https://bottosson.github.io/posts/gamutclipping/
@@ -1151,6 +1201,15 @@ export declare function easeOutQuad(t: number): number;
 
 export declare function easeOutSine(t: number): number;
 
+/**
+ * Evaluate a math FunctionValue to a numeric ValueUnit.
+ * Returns null if the expression can't be fully resolved.
+ *
+ * The result unit is determined by the first resolvable argument's unit,
+ * since CSS requires type-compatible arguments.
+ */
+export declare function evaluateMathFunction(fn: FunctionValue): ValueUnit | null;
+
 /** Parser that always fails with the given message. */
 export declare function fail(message: string): Parser<never>;
 
@@ -1176,8 +1235,12 @@ export declare function findGamutIntersection(a_: number, b_: number, L1: number
 
 export declare const flattenObject: (obj: any) => Record<string, any>;
 
+export declare const FLEX_UNITS: readonly ["fr"];
+
 export declare const FRAME_RATE: number;
 
+export declare const FREQUENCY_UNITS: readonly ["Hz", "kHz"];
+
 export declare class FunctionValue<T = any, N extends string = string> {
     name: N;
     values: Array<ValueUnit<T> | FunctionValue<T>>;
@@ -1326,6 +1389,12 @@ export declare const integer: Parser<number>;
 
 export declare function interpBezier(t: number, points: number[][]): number[];
 
+/**
+ * Interpolate between two decomposed 3D matrices at parameter t.
+ * Uses slerp for rotation, lerp for everything else.
+ */
+export declare function interpolateDecomposed(a: DecomposedMatrix3D, b: DecomposedMatrix3D, t: number): DecomposedMatrix3D;
+
 export declare type InterpolatedVar<T> = {
     start: ValueUnit<T>;
     stop: ValueUnit<T>;
@@ -1399,7 +1468,7 @@ export declare class LCHColor<T = number> extends Color<T> {
     set h(value: T);
 }
 
-export declare const LENGTH_UNITS: readonly ["px", "cm", "mm", "Q", "in", "pc", "pt", "em", "ex", "ch", "rem", "lh", "rlh", "vw", "vh", "vmin", "vmax", "vb", "vi", "svw", "svh", "lvw", "lvh", "dvw", "dvh"];
+export declare const LENGTH_UNITS: readonly ["px", "cm", "mm", "Q", "in", "pc", "pt", "em", "ex", "ch", "cap", "ic", "rem", "lh", "rlh", "vw", "vh", "vmin", "vmax", "vb", "vi", "svw", "svh", "svi", "svb", "svmin", "svmax", "lvw", "lvh", "lvi", "lvb", "lvmin", "lvmax", "dvw", "dvh", "dvi", "dvb", "dvmin", "dvmax", "cqw", "cqh", "cqi", "cqb", "cqmin", "cqmax"];
 
 export declare function lerp(t: number, start: number, end: number): number;
 
@@ -1419,6 +1488,24 @@ export declare class LinearSRGBColor<T = number> extends Color<T> {
     set b(value: T);
 }
 
+/**
+ * CSS Easing Level 2 `linear()` — piecewise-linear timing function.
+ *
+ * Each stop is `{ output: number, input?: number }`.
+ * - `output` is the easing output value (typically 0–1 but can overshoot).
+ * - `input` is the progress percentage (0–100). If omitted, stops are
+ *   evenly distributed.
+ *
+ * Syntax examples:
+ *   linear(0, 0.25, 1)          → three evenly-spaced stops
+ *   linear(0, 0.25 75%, 1)      → second stop at 75% input
+ *   linear(0, 0.5 25% 75%, 1)   → second stop spans 25%–75% (flat segment)
+ */
+export declare interface LinearStop {
+    output: number;
+    input?: number;
+}
+
 export declare function linearToAdobeRgb(c: number): number;
 
 export declare function linearToProPhoto(c: number): number;
@@ -1447,6 +1534,8 @@ number,
 number
 ];
 
+export declare type Mat4 = number[];
+
 export declare interface MatrixValues {
     scaleX: number;
     scaleY: number;
@@ -1497,7 +1586,7 @@ export declare const normalizeColorUnit: (color: ValueUnit<Color<ValueUnit<numbe
 
 export declare const normalizeColorUnitComponent: (v: number, unit: string, colorSpace: ColorSpace, component: string, inverse?: boolean) => ValueUnit<number, string>;
 
-export declare const normalizeColorUnits: (a: ValueUnit<Color<ValueUnit<number>>, "color">, b: ValueUnit<Color<ValueUnit<number>>, "color">, to?: ColorSpace, normalized?: boolean, inverse?: boolean, inplace?: boolean) => readonly [ValueUnit<RGBColor<ValueUnit<number, string | undefined>> | HSLColor<ValueUnit<number, string | undefined>> | HSVColor<ValueUnit<number, string | undefined>> | HWBColor<ValueUnit<number, string | undefined>> | LABColor<ValueUnit<number, string | undefined>> | LCHColor<ValueUnit<number, string | undefined>> | OKLABColor<ValueUnit<number, string | undefined>> | OKLCHColor<ValueUnit<number, string | undefined>> | XYZColor<ValueUnit<number, string | undefined>> | KelvinColor<ValueUnit<number, string | undefined>> | LinearSRGBColor<ValueUnit<number, string | undefined>> | DisplayP3Color<ValueUnit<number, string | undefined>> | AdobeRGBColor<ValueUnit<number, string | undefined>> | ProPhotoRGBColor<ValueUnit<number, string | undefined>> | Rec2020Color<ValueUnit<number, string | undefined>>, "color">, ValueUnit<RGBColor<ValueUnit<number, string | undefined>> | HSLColor<ValueUnit<number, string | undefined>> | HSVColor<ValueUnit<number, string | undefined>> | HWBColor<ValueUnit<number, string | undefined>> | LABColor<ValueUnit<number, string | undefined>> | LCHColor<ValueUnit<number, string | undefined>> | OKLABColor<ValueUnit<number, string | undefined>> | OKLCHColor<ValueUnit<number, string | undefined>> | XYZColor<ValueUnit<number, string | undefined>> | KelvinColor<ValueUnit<number, string | undefined>> | LinearSRGBColor<ValueUnit<number, string | undefined>> | DisplayP3Color<ValueUnit<number, string | undefined>> | AdobeRGBColor<ValueUnit<number, string | undefined>> | ProPhotoRGBColor<ValueUnit<number, string | undefined>> | Rec2020Color<ValueUnit<number, string | undefined>>, "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<RGBColor<ValueUnit<number, string | undefined>> | HSLColor<ValueUnit<number, string | undefined>> | HSVColor<ValueUnit<number, string | undefined>> | HWBColor<ValueUnit<number, string | undefined>> | LABColor<ValueUnit<number, string | undefined>> | LCHColor<ValueUnit<number, string | undefined>> | OKLABColor<ValueUnit<number, string | undefined>> | OKLCHColor<ValueUnit<number, string | undefined>> | XYZColor<ValueUnit<number, string | undefined>> | KelvinColor<ValueUnit<number, string | undefined>> | LinearSRGBColor<ValueUnit<number, string | undefined>> | DisplayP3Color<ValueUnit<number, string | undefined>> | AdobeRGBColor<ValueUnit<number, string | undefined>> | ProPhotoRGBColor<ValueUnit<number, string | undefined>> | Rec2020Color<ValueUnit<number, string | undefined>>, "color">, ValueUnit<RGBColor<ValueUnit<number, string | undefined>> | HSLColor<ValueUnit<number, string | undefined>> | HSVColor<ValueUnit<number, string | undefined>> | HWBColor<ValueUnit<number, string | undefined>> | LABColor<ValueUnit<number, string | undefined>> | LCHColor<ValueUnit<number, string | undefined>> | OKLABColor<ValueUnit<number, string | undefined>> | OKLCHColor<ValueUnit<number, string | undefined>> | XYZColor<ValueUnit<number, string | undefined>> | KelvinColor<ValueUnit<number, string | undefined>> | LinearSRGBColor<ValueUnit<number, string | undefined>> | DisplayP3Color<ValueUnit<number, string | undefined>> | AdobeRGBColor<ValueUnit<number, string | undefined>> | ProPhotoRGBColor<ValueUnit<number, string | undefined>> | Rec2020Color<ValueUnit<number, string | undefined>>, "color">, HueInterpolationMethod | undefined];
 
 export declare const normalizeNumericUnits: (a: ValueUnit, b: ValueUnit, inplace?: boolean) => [ValueUnit, ValueUnit];
 
@@ -1615,12 +1704,17 @@ export declare class Rec2020Color<T = number> extends Color<T> {
 
 export declare function rec2020ToLinear(c: number): number;
 
-export declare const RELATIVE_LENGTH_UNITS: readonly ["em", "ex", "ch", "rem", "lh", "rlh", "vw", "vh", "vmin", "vmax", "vb", "vi", "svw", "svh", "lvw", "lvh", "dvw", "dvh"];
+/**
+ * Recompose a 3D decomposed matrix back into a CSS matrix3d() value array (16 values, column-major CSS order).
+ */
+export declare function recomposeMatrix3D(d: DecomposedMatrix3D): number[];
+
+export declare const RELATIVE_LENGTH_UNITS: readonly ["em", "ex", "ch", "cap", "ic", "rem", "lh", "rlh", "vw", "vh", "vmin", "vmax", "vb", "vi", "svw", "svh", "svi", "svb", "svmin", "svmax", "lvw", "lvh", "lvi", "lvb", "lvmin", "lvmax", "dvw", "dvh", "dvi", "dvb", "dvmin", "dvmax", "cqw", "cqh", "cqi", "cqb", "cqmin", "cqmax"];
 
 declare function requestAnimationFrame_2(callback: FrameRequestCallback): number | NodeJS.Timeout;
 export { requestAnimationFrame_2 as requestAnimationFrame }
 
-export declare const RESOLUTION_UNITS: readonly ["dpi", "dpcm", "dppx", "cqw"];
+export declare const RESOLUTION_UNITS: readonly ["dpi", "dpcm", "dppx"];
 
 export declare function rgb2ColorFilter(color: RGBColor<number>): {
     values: number[];
@@ -1665,6 +1759,12 @@ export declare function seekPreviousValue<T>(ix: number, values: T[], pred: (f:
 
 export declare function sleep(ms: number): Promise<unknown>;
 
+/**
+ * Spherical linear interpolation between two quaternions.
+ * Both quaternions should be normalized.
+ */
+export declare function slerp(qa: Vec4, qb: Vec4, t: number): Vec4;
+
 export declare function smoothStep3(t: number): number;
 
 export declare function srgbToLinear(channel: number): number;
@@ -1736,13 +1836,13 @@ export declare const timingFunctions: {
     readonly "ease-in-out-expo": typeof easeInOutExpo;
     readonly smoothStep3: typeof smoothStep3;
     readonly "smooth-step-3": typeof smoothStep3;
-    readonly ease: (t: number) => number;
-    readonly "ease-in": (t: number) => number;
-    readonly "ease-out": (t: number) => number;
-    readonly "ease-in-out": (t: number) => number;
-    readonly "ease-in-back": (t: number) => number;
-    readonly "ease-out-back": (t: number) => number;
-    readonly "ease-in-out-back": (t: number) => number;
+    readonly ease: (x: number) => number;
+    readonly "ease-in": (x: number) => number;
+    readonly "ease-out": (x: number) => number;
+    readonly "ease-in-out": (x: number) => number;
+    readonly "ease-in-back": (x: number) => number;
+    readonly "ease-out-back": (x: number) => number;
+    readonly "ease-in-out-back": (x: number) => number;
     readonly steps: typeof steppedEase;
     readonly "step-start": typeof stepStart;
     readonly "step-end": typeof stepEnd;
@@ -1775,7 +1875,7 @@ export declare const UNIT_RANGE: {
     };
 };
 
-export declare const UNITS: readonly ["px", "cm", "mm", "Q", "in", "pc", "pt", "em", "ex", "ch", "rem", "lh", "rlh", "vw", "vh", "vmin", "vmax", "vb", "vi", "svw", "svh", "lvw", "lvh", "dvw", "dvh", "s", "ms", "deg", "rad", "grad", "turn", "%", "dpi", "dpcm", "dppx", "cqw", "var", "calc", "string", "color", "", undefined];
+export declare const UNITS: readonly ["px", "cm", "mm", "Q", "in", "pc", "pt", "em", "ex", "ch", "cap", "ic", "rem", "lh", "rlh", "vw", "vh", "vmin", "vmax", "vb", "vi", "svw", "svh", "svi", "svb", "svmin", "svmax", "lvw", "lvh", "lvi", "lvb", "lvmin", "lvmax", "dvw", "dvh", "dvi", "dvb", "dvmin", "dvmax", "cqw", "cqh", "cqi", "cqb", "cqmin", "cqmax", "s", "ms", "deg", "rad", "grad", "turn", "%", "Hz", "kHz", "dpi", "dpcm", "dppx", "fr", "var", "calc", "string", "color", "", undefined];
 
 export declare const unpackMatrixValues: (value: FunctionValue) => MatrixValues;
 
@@ -1821,6 +1921,15 @@ export declare class ValueUnit<T = any, U = (typeof UNITS)[number] | string> {
  */
 export declare type Vec3 = [number, number, number];
 
+/**
+ * CSS Transform Matrix Decomposition and Recomposition.
+ *
+ * Implements the CSSOM View spec algorithm (§15.1) for 2D matrices
+ * and polar decomposition for 3D matrices.
+ * Also includes quaternion slerp for smooth rotation interpolation.
+ */
+export declare type Vec4 = [number, number, number, number];
+
 export declare function waitUntil(condition: () => boolean, delay?: number): Promise<void>;
 
 export declare const WHITE_POINT_D50: Vec3;