@mkbabb/value.js 0.4.2 → 0.4.5

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 +51 -22
  2. package/dist/value.d.ts +2 -1997
  3. package/dist/value.js +2689 -2406
  4. package/package.json +3 -3
  5. package/dist/value.cjs +0 -8
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # value.js ![image](demo/color-picker/cube.png)
2
2
 
3
- CSS value parsing, color theory, and unit conversion. Typed values with units—`deg`, `px`, `rem`, `oklch()`—the full CSS value vocabulary.
3
+ CSS value parsing, color theory, and unit conversion. Typed values with units—`deg`, `px`, `rem`, `oklch()`—the core CSS value vocabulary.
4
4
 
5
5
  [demo](https://color.babb.dev)
6
6
 
@@ -11,7 +11,7 @@ CSS value parsing, color theory, and unit conversion. Typed values with units—
11
11
  - Color space conversion via **XYZ hub** with analytical gamut mapping (Ottosson's algorithm)
12
12
  - CSS Color Level 4 support: `color()`, `color-mix()`, relative color syntax
13
13
  - CSS math functions: `calc()`, `min()`, `max()`, `clamp()`, trig, exponential
14
- - 40+ easing functions: cubic-bezier, stepped, linear(), bounce, sine, expo
14
+ - 30+ easing functions: cubic-bezier, stepped, linear(), bounce, sine, expo
15
15
  - 2D/3D matrix decomposition with quaternion slerp interpolation
16
16
  - Normalize, interpolate, and convert between units
17
17
 
@@ -24,7 +24,12 @@ npm install @mkbabb/value.js
24
24
  ## Usage
25
25
 
26
26
  ```ts
27
- import { parseCSSValue, parseCSSColor, ValueUnit, FunctionValue } from "@mkbabb/value.js";
27
+ import {
28
+ parseCSSValue,
29
+ parseCSSColor,
30
+ ValueUnit,
31
+ FunctionValue,
32
+ } from "@mkbabb/value.js";
28
33
  ```
29
34
 
30
35
  ## Build
@@ -32,8 +37,8 @@ import { parseCSSValue, parseCSSColor, ValueUnit, FunctionValue } from "@mkbabb/
32
37
  ```bash
33
38
  npm run build # library → dist/value.js + value.cjs + value.d.ts
34
39
  npm run gh-pages # demo → dist/
35
- npm run dev # dev server on :8080
36
- npm test # vitest (1279 tests)
40
+ npm run dev # dev server (Vite default port)
41
+ npm test # vitest (1372 tests)
37
42
  npm run test:e2e # playwright (desktop + mobile)
38
43
  ```
39
44
 
@@ -44,29 +49,32 @@ src/
44
49
  ├── index.ts # barrel exports (~200 symbols)
45
50
  ├── math.ts # lerp, bezier, clamp, scale, deCasteljau
46
51
  ├── easing.ts # CSS timing functions (cubic-bezier, stepped, linear())
47
- ├── utils.ts # clone, memoize, debounce, RAF
52
+ ├── utils.ts # clone, memoize, debounce, RAF, case conversion
48
53
  ├── parsing/ # @mkbabb/parse-that combinators for CSS values
49
54
  │ ├── index.ts # parseCSSValue, gradients, transforms, var()
50
55
  │ ├── units.ts # length, angle, time, frequency, resolution, flex, %
51
56
  │ ├── color.ts # 15 spaces, hex, named, color-mix(), relative syntax
52
57
  │ ├── math.ts # calc() AST, min/max/clamp, trig, exp
53
- │ └── grammars/ # BBNF spec grammars (documentation only)
58
+ │ ├── utils.ts # istring, number, none, tryParse helpers
59
+ │ └── grammars/ # BBNF spec grammars (used in equivalence tests)
54
60
  ├── units/ # core value classes + unit definitions
55
61
  │ ├── index.ts # ValueUnit, FunctionValue, ValueArray
56
- │ ├── constants.ts # unit arrays, 735+ CSS property names
62
+ │ ├── constants.ts # unit arrays, 630+ CSS property names
57
63
  │ ├── utils.ts # unit conversion (px, deg, ms, Hz, dpi)
64
+ │ ├── normalize.ts # value normalization + interpolation setup
58
65
  │ └── color/ # 15 color spaces, conversion, gamut mapping
59
66
  │ ├── index.ts # Color<T> base + space classes
60
67
  │ ├── constants.ts # ranges, matrices, white points, named colors
61
68
  │ ├── matrix.ts # Vec3/Mat3 (row-major, replaces gl-matrix)
62
- │ ├── utils.ts # 100+ conversions via XYZ, mixColors, gamutMap
69
+ │ ├── utils.ts # conversions via XYZ, mixColors, gamutMap
70
+ │ ├── normalize.ts # color normalization to [0,1], space conversion
63
71
  │ ├── gamut.ts # Ottosson analytical sRGB gamut mapping
64
72
  │ └── colorFilter.ts # CSS filter solver (SPSA)
65
73
  └── transform/
66
74
  └── decompose.ts # 2D/3D matrix decomposition, quaternion slerp
67
75
 
68
76
  test/ # vitest unit tests (24 files)
69
- e2e/ # playwright E2E (10 specs)
77
+ e2e/ # playwright E2E (14 specs)
70
78
  demo/ # Vue 3.5 color picker (reka-ui, Tailwind)
71
79
  api/ # Hono + MongoDB palette API (Docker)
72
80
  docs/ # color-theory.md, gamut-mapping.md
@@ -75,37 +83,58 @@ assets/docs/ # 10 color space reference pages
75
83
 
76
84
  ## Color Spaces
77
85
 
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.
86
+ All conversions route through the **XYZ D65** hub, enabling any-to-any conversion. Perceptual spaces (OKLab, Lab) use D50 natively with Bradford chromatic adaptation where needed.
79
87
 
80
88
  Each color space is documented in [`assets/docs/`](assets/docs/)—historical context, component ranges, conversion functions, and practical applications.
81
89
 
82
90
  ### Gamut Mapping
83
91
 
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.
92
+ Out-of-gamut colors are mapped using Björn Ottosson's analytical sRGB algorithm: a polynomial initial guess refined by a single Halley's method step (cubic convergence). Significantly faster than CSS Color 4's iterative binary search. Hue is preserved exactly; an adaptive `L0` formula blends between chroma reduction and mid-gray anchoring.
85
93
 
86
94
  See [`docs/gamut-mapping.md`](docs/gamut-mapping.md) for the full treatment.
87
95
 
88
96
  ## Easing
89
97
 
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.
98
+ 30+ timing functions covering the CSS `<easing-function>` grammar plus bounce and back. `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
99
 
92
100
  ## Transforms
93
101
 
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.
102
+ CSS `matrix()` and `matrix3d()` decomposition per the CSSOM View and CSS Transforms specs. 3D uses Gram-Schmidt orthogonalization + quaternion extraction. `slerp` for rotation interpolation. `interpolateDecomposed()` for full transform blending.
95
103
 
96
104
  ## Palette API
97
105
 
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.
106
+ The [demo](https://color.babb.dev) is backed by a palette API for saving, sharing, and voting on color palettes. Users register via `POST /sessions`, which mints a UUID token and a four-word slug—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
107
 
100
108
  Hono + MongoDB, Dockerized. See [`api/README.md`](api/README.md) for endpoints, schema, and deployment.
101
109
 
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) |
110
+ | Feature | Mechanism |
111
+ | ----------------- | ------------------------------------------------------------------------------------------------------------ |
112
+ | **Sessions** | `POST /sessions` → UUID token + user slug; stored with hashed IP; 30-day TTL |
113
+ | **Palettes** | CRUD by slug; 1–50 color stops with CSS string + optional name + position |
114
+ | **Voting** | `POST /palettes/:slug/vote` — idempotent toggle; unique composite index on `{userSlug, paletteSlug}` |
115
+ | **Color names** | `POST /colors/propose` → admin approval queue → `GET /colors/approved` feeds the demo's custom name registry |
116
+ | **Rate limiting** | 60 reads/min, 10 writes/min per IP (in-memory, rightmost X-Forwarded-For) |
117
+
118
+ ### Palette System Flow (Frontend + API)
119
+
120
+ 1. **Save locally** (`PaletteForm` / `usePaletteStore`): stores palettes in browser storage (`color-palettes`) for instant local recall.
121
+ 2. **Publish** (`PaletteDialog`): ensures a session (`POST /sessions`), then publishes via `POST /palettes` with `X-Session-Token`.
122
+ 3. **Browse + vote** (`Browse` tab): fetches `GET /palettes` and toggles votes with `POST /palettes/:slug/vote` (server maintains atomic vote counts).
123
+ 4. **Suggest color names** (`ColorInput` propose form): ensures session, then submits `POST /colors/propose` for moderation.
124
+ 5. **Admin moderation** (`AdminPanel`): token login (`Authorization: Bearer ...`), queue from `GET /admin/queue`, actions for approve/reject + feature/delete.
125
+
126
+ ### Validation
127
+
128
+ - **API smoke (live backend)**: session creation, publish/list/get, vote toggle, rename, propose, admin queue, approve, feature, delete.
129
+ - **Playwright live integration**: [`e2e/palette-api-live.spec.ts`](e2e/palette-api-live.spec.ts) validates save/publish/vote/propose/admin end-to-end against a real API.
130
+
131
+ ```bash
132
+ # 1) Start API (example)
133
+ MONGODB_URI=mongodb://127.0.0.1:27019/palette-e2e ADMIN_TOKEN=test-admin-token PORT=3100 npm --prefix api run dev
134
+
135
+ # 2) Run live frontend + backend integration
136
+ PALETTE_API_E2E=1 VITE_API_URL=http://127.0.0.1:3100 npx playwright test e2e/palette-api-live.spec.ts --project=desktop
137
+ ```
109
138
 
110
139
  ## Sources, acknowledgements, &c.
111
140