@mkbabb/value.js 0.4.0 → 0.4.2

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.
Files changed (5) hide show
  1. package/README.md +98 -8
  2. package/dist/value.cjs +6 -6
  3. package/dist/value.d.ts +5 -3
  4. package/dist/value.js +1138 -1100
  5. package/package.json +1 -1
package/README.md CHANGED
@@ -1,14 +1,18 @@
1
1
  # value.js ![image](demo/color-picker/cube.png)
2
2
 
3
- CSS value units for color, length, angles, & c. Create a moderately-typed value with a unit, like `deg`, `px`, etc.
3
+ CSS value parsing, color theory, and unit conversion. Typed values with units—`deg`, `px`, `rem`, `oklch()`—the full CSS value vocabulary.
4
4
 
5
- [demo 🌈](https://color.babb.dev)
5
+ [demo](https://color.babb.dev)
6
6
 
7
7
  ## Features
8
8
 
9
- - Parse any CSS value: lengths, angles, times, colors, `calc()`, `var()`, gradients
10
- - 10 color spaces: RGB, HSL, HSV, HWB, Lab, LCh, OKLab, OKLCh, XYZ, Kelvin
11
- - Full color space conversion via XYZ hub with gamut mapping
9
+ - Parse any CSS value: lengths, angles, times, colors, `calc()`, `var()`, gradients, transforms
10
+ - **15 color spaces**: RGB, HSL, HSV, HWB, Lab, LCh, OKLab, OKLCh, XYZ, Kelvin, sRGB-linear, Display P3, Adobe RGB, ProPhoto RGB, Rec. 2020
11
+ - Color space conversion via **XYZ hub** with analytical gamut mapping (Ottosson's algorithm)
12
+ - CSS Color Level 4 support: `color()`, `color-mix()`, relative color syntax
13
+ - CSS math functions: `calc()`, `min()`, `max()`, `clamp()`, trig, exponential
14
+ - 40+ easing functions: cubic-bezier, stepped, linear(), bounce, sine, expo
15
+ - 2D/3D matrix decomposition with quaternion slerp interpolation
12
16
  - Normalize, interpolate, and convert between units
13
17
 
14
18
  ## Install
@@ -20,14 +24,100 @@ npm install @mkbabb/value.js
20
24
  ## Usage
21
25
 
22
26
  ```ts
23
- import { ValueUnit, FunctionValue } from "@mkbabb/value.js";
27
+ import { parseCSSValue, parseCSSColor, ValueUnit, FunctionValue } from "@mkbabb/value.js";
24
28
  ```
25
29
 
26
30
  ## Build
27
31
 
28
32
  ```bash
29
- npm run build # library → dist/
33
+ npm run build # library → dist/value.js + value.cjs + value.d.ts
30
34
  npm run gh-pages # demo → dist/
31
35
  npm run dev # dev server on :8080
32
- npm test # vitest
36
+ npm test # vitest (1279 tests)
37
+ npm run test:e2e # playwright (desktop + mobile)
33
38
  ```
39
+
40
+ ## Structure
41
+
42
+ ```
43
+ src/
44
+ ├── index.ts # barrel exports (~200 symbols)
45
+ ├── math.ts # lerp, bezier, clamp, scale, deCasteljau
46
+ ├── easing.ts # CSS timing functions (cubic-bezier, stepped, linear())
47
+ ├── utils.ts # clone, memoize, debounce, RAF
48
+ ├── parsing/ # @mkbabb/parse-that combinators for CSS values
49
+ │ ├── index.ts # parseCSSValue, gradients, transforms, var()
50
+ │ ├── units.ts # length, angle, time, frequency, resolution, flex, %
51
+ │ ├── color.ts # 15 spaces, hex, named, color-mix(), relative syntax
52
+ │ ├── math.ts # calc() AST, min/max/clamp, trig, exp
53
+ │ └── grammars/ # BBNF spec grammars (documentation only)
54
+ ├── units/ # core value classes + unit definitions
55
+ │ ├── index.ts # ValueUnit, FunctionValue, ValueArray
56
+ │ ├── constants.ts # unit arrays, 735+ CSS property names
57
+ │ ├── utils.ts # unit conversion (px, deg, ms, Hz, dpi)
58
+ │ └── color/ # 15 color spaces, conversion, gamut mapping
59
+ │ ├── index.ts # Color<T> base + space classes
60
+ │ ├── constants.ts # ranges, matrices, white points, named colors
61
+ │ ├── matrix.ts # Vec3/Mat3 (row-major, replaces gl-matrix)
62
+ │ ├── utils.ts # 100+ conversions via XYZ, mixColors, gamutMap
63
+ │ ├── gamut.ts # Ottosson analytical sRGB gamut mapping
64
+ │ └── colorFilter.ts # CSS filter solver (SPSA)
65
+ └── transform/
66
+ └── decompose.ts # 2D/3D matrix decomposition, quaternion slerp
67
+
68
+ test/ # vitest unit tests (24 files)
69
+ e2e/ # playwright E2E (10 specs)
70
+ demo/ # Vue 3.5 color picker (reka-ui, Tailwind)
71
+ api/ # Hono + MongoDB palette API (Docker)
72
+ docs/ # color-theory.md, gamut-mapping.md
73
+ assets/docs/ # 10 color space reference pages
74
+ ```
75
+
76
+ ## Color Spaces
77
+
78
+ All conversions route through the **XYZ D65** hub for universal interoperability. Perceptual spaces (OKLab, Lab) use D50 natively with Bradford chromatic adaptation where needed.
79
+
80
+ Each color space is documented in [`assets/docs/`](assets/docs/)—historical context, component ranges, conversion functions, and practical applications.
81
+
82
+ ### Gamut Mapping
83
+
84
+ Out-of-gamut colors are mapped using Ottosson's analytical sRGB algorithm: a polynomial initial guess refined by one Halley's method step. Zero iteration, cubic convergence, ~60–125x faster than CSS Color 4's binary search. Hue is preserved exactly; an adaptive `L0` formula blends between chroma reduction and mid-gray anchoring.
85
+
86
+ See [`docs/gamut-mapping.md`](docs/gamut-mapping.md) for the full treatment.
87
+
88
+ ## Easing
89
+
90
+ 40+ timing functions covering every CSS `<easing-function>` value plus bounce, back, and elastic. `CSSCubicBezier` solves via Newton-Raphson with bisection fallback; `cssLinear()` implements CSS Easing Level 2 piecewise-linear with gap filling per spec; stepped easings support all four jump terms.
91
+
92
+ ## Transforms
93
+
94
+ CSS `matrix()` and `matrix3d()` decomposition per CSSOM spec. 3D uses Gram-Schmidt orthogonalization + quaternion extraction. `slerp` for rotation interpolation. `interpolateDecomposed()` for full transform blending.
95
+
96
+ ## Palette API
97
+
98
+ The [demo](https://color.babb.dev) is backed by a palette API for saving, sharing, and voting on color palettes. Anonymous sessions (UUID tokens via `X-Session-Token`) gate all writes—no accounts required. Palettes are slug-addressed, votable (atomic toggle), and sortable by popularity or recency. A color name registry lets users propose names for CSS colors; admins approve or reject through a moderation queue.
99
+
100
+ Hono + MongoDB, Dockerized. See [`api/README.md`](api/README.md) for endpoints, schema, and deployment.
101
+
102
+ | Feature | Mechanism |
103
+ |---------|-----------|
104
+ | **Sessions** | `POST /sessions` → UUID token; stored with hashed IP; 30-day TTL |
105
+ | **Palettes** | CRUD by slug; 1–50 color stops with CSS string + optional name + position |
106
+ | **Voting** | `POST /palettes/:slug/vote` — idempotent toggle; unique composite index prevents duplication |
107
+ | **Color names** | `POST /colors/propose` → admin approval queue → `GET /colors/approved` feeds the demo's custom name registry |
108
+ | **Rate limiting** | 60 reads/min, 10 writes/min per IP (in-memory, rightmost X-Forwarded-For) |
109
+
110
+ ## Sources, acknowledgements, &c.
111
+
112
+ - Ottosson, B. (2020). [A perceptual color space for image processing](https://bottosson.github.io/posts/oklab/). — OKLab: the perceptual color space used for `color-mix()` and gamut mapping.
113
+ - Ottosson, B. (2021). [sRGB gamut clipping](https://bottosson.github.io/posts/gamutclipping/). — Analytical gamut mapping algorithm (cubic boundary + Halley's method).
114
+ - Atkins Jr., T., Lilley, C., & Verou, L. (2025). [CSS Color Module Level 4](https://www.w3.org/TR/css-color-4/). W3C CRD. — The spec governing all CSS color functions.
115
+ - [CSS Filter Effects Module Level 1](https://www.w3.org/TR/filter-effects/#feColorMatrixElement). W3C. — `feColorMatrix`; basis for the CSS filter solver.
116
+ - Lindbloom, B. [XYZ to Correlated Color Temperature](http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_T.html). — CCT conversion reference.
117
+ - [`@mkbabb/parse-that`](https://github.com/mkbabb/parse-that) — Parser combinators powering the CSS value grammar.
118
+
119
+ See [`docs/color-theory.md`](docs/color-theory.md) for the full bibliography.
120
+
121
+ ## License
122
+
123
+ GPL-3.0-only