@luntta/swatch 3.0.0

package/CHANGELOG.md

@@ -0,0 +1,56 @@
+# Changelog
+
+## 3.0.0 — BREAKING
+
+A complete rewrite. Storage moved to a canonical `{ space, coords, alpha }` state (colorjs.io / culori model) so wide-gamut inputs are preserved losslessly, conversions go through a lazy CIE XYZ D65 hub, and the monolithic `src/swatch.js` has been split into `src/core`, `src/spaces`, `src/parse`, `src/format`, `src/operations`, `src/scale`, `src/palettes`, and `src/data`.
+
+See [`MIGRATING.md`](./MIGRATING.md) for the v2 → v3 cookbook.
+
+### Breaking
+
+- **Manipulation moved to OKLCh.** `lighten`, `darken`, `saturate`, `desaturate`, `spin`, `greyscale`, and `complement` now operate in OKLCh instead of HSL, with amounts in `0..1` OKLCh L/C units instead of `0..100` HSL %. `swatch("#ff0000").lighten(20)` (v2) becomes `swatch("#ff0000").lighten(0.1)` (v3). Rationale: HSL lightness is not perceptually uniform, so v2's `swatch("#ffff00").lighten(0.1)` looked almost unchanged while `swatch("#0000ff").lighten(0.1)` jumped.
+- **Space conversions are getters, not methods.** `c.toLab()` → `c.lab`, `c.toOklch()` → `c.oklch`, `c.toRGB()` → `c.srgb`, etc. Getters are lazily memoized on the instance.
+- **Wide-gamut inputs are no longer clamped at parse.** `swatch("color(display-p3 1 0 0)")` keeps its P3 coordinates; `.srgb` on that swatch returns a raw, possibly out-of-range conversion. Use `.toGamut({ space: "srgb", method: "css4" })` to get a properly chroma-reduced in-gamut version.
+- **`toJSON()` shape changed** from `{ hex, rgb, hsl, isValid, format }` to `{ space, coords, alpha }`. The new shape round-trips cleanly through `swatch(...)`.
+- **`equals()` signature changed** from `equals(other, { tolerance, space })` to `equals(other, epsilon)`. `other` must now be a `Swatch` instance.
+- **Removed v2 fields:** `isValid`, `hasAlpha`, `_original`, `_originalFormat`. Invalid input now throws; check `alpha < 1` for alpha presence; use `c.space` / `c.coords` to introspect state.
+- **`mix()` takes an options bag** for the interpolation space: `a.mix(b, 0.5, "lab")` → `a.mix(b, 0.5, { space: "lab" })`.
+- **Harmonies not yet ported.** `complementary`, `triad`, `tetrad`, `splitComplement`, `analogous`, `monochromatic` are not in v3.0. They will return in a follow-up release. Workaround: `[c, c.spin(120), c.spin(240)]`.
+- **Internal rename.** The v2 monolith lives at `src/_v2-monolith.js` as an internal artifact and is not part of the public API. Do not import from it.
+
+### Added
+
+- **CSS Color 4 parsing and serialization.** `swatch("oklch(0.7 0.15 240)")`, `swatch("lab(52.2% 40 -70)")`, `swatch("hwb(240 0% 0%)")`, `swatch("color(display-p3 1 0 0)")`, `swatch("color(rec2020 1 0 0)")`, `swatch("color(xyz-d65 0.4 0.2 0.2)")`, modern slash-alpha, `none` keyword, percentage values, the whole set. `c.toString({ format: "oklch" })` / `"lab"` / `"hwb"` / `"lch"` / `"oklab"` / `"color"` for output.
+- **Wide-gamut spaces.** Display P3, Rec2020, Adobe RGB 1998, ProPhoto RGB. Each registered in the conversion graph with their correct primaries and transfer functions; ProPhoto carries a Bradford D50 → D65 CAT internally.
+- **Additional spaces.** HSV, HWB, CMYK (naive), HSLuv, Luv, linear sRGB, XYZ D65 and D50.
+- **Channel get/set.** `c.get("oklch.l")`, `c.set("hsl.h", 120)`, `c.get("alpha")`.
+- **Gamut mapping.** `c.inGamut("srgb")`, `c.toGamut({ space, method })`, with `"clip"`, `"css4"` (CSS Color 4 binary chroma reduction in OKLCh, default), and `"oklch-chroma"` (alias).
+- **Tint, shade, tone.** `c.tint(0.2)`, `c.shade(0.2)`, `c.tone(0.2)` — mix toward white / black / mid-grey in OKLab.
+- **W3C Compositing and Blending Level 1 blend modes.** `normal`, `multiply`, `screen`, `darken`, `lighten`, `overlay`, `color-dodge`, `color-burn`, `hard-light`, `soft-light`, `difference`, `exclusion`. Per-channel in linear sRGB, then re-encoded.
+- **Color scales.** `swatch.scale([c1, c2, ...])` returns a chroma.js-style `Scale` with chainable `.domain([a, b])`, `.classes(n)`, `.padding([l, r])`, `.gamma(g)`, `.mode(spaceId)`, `.correctLightness()`, `.cache(on)`, plus `.colors(n, format?)`.
+- **Built-in palettes.** Matplotlib perceptually-uniform colormaps (`viridis`, `magma`, `plasma`, `inferno`, `cividis`) and the ColorBrewer 2.0 sequential (`Blues`, `Greens`, `Reds`, `Oranges`, `Purples`, `Greys`), diverging (`RdBu`, `RdYlBu`, `PiYG`, `BrBG`, `Spectral`), and qualitative (`Set1`, `Set2`, `Set3`, `Pastel1`, `Dark2`) sets. Look up by name: `swatch.scale("viridis")`, `swatch.scale("RdBu")`, etc. List all: `swatch.palettes()`.
+- **Scale interpolators.** `swatch.bezier([colors])` (de Casteljau in Lab), `swatch.cubehelix({ start, rotations, hue, gamma, lightness })` (Green 2011).
+- **Color naming.** `c.name()` returns `{ name, hex, deltaE }` of the nearest CSS named color measured in ΔE2000; `c.toName()` returns just the string.
+- **Temperature.** `swatch.temperature(6500)` (Krystek 1985 blackbody polynomial) and `c.temperature()` (McCamy 1992 inverse approximation). Range 1000 K – 40000 K.
+- **Random color generation.** `swatch.random({ space, hue, lightness, chroma, saturation, seed })` with a seeded xorshift32 PRNG for reproducibility.
+- **Extra ΔE metrics.** `"94"` (CIE94 graphic arts), `"cmc"` (CMC l:c with optional `{ l, c }` coefficients), `"hyab"` (Abasi & Fairchild HyAB). Existing `"76"`, `"2000"`, `"ok"` still supported.
+- **TypeScript definitions rewritten.** `types/swatch.d.ts` now covers the full v3 surface including the `SpaceId` literal union, all per-space channel shapes, the widened `ColorInput`, every option bag, the `Scale` interface, and the `SwatchFactory` statics.
+- **New docs.** [`README.md`](./README.md) rewritten for v3. [`MIGRATING.md`](./MIGRATING.md) added with the v2 → v3 cookbook.
+
+### Unchanged
+
+The CVD / APCA / WCAG story is preserved end-to-end:
+
+- `simulate(type, { severity })` — Brettel/Viénot dichromat simulation with a severity continuum
+- `daltonize(type, { severity })` — Fidaner error redistribution
+- `swatch.checkPalette(colors, { cvd, minDeltaE, mode })`
+- `swatch.nearestDistinguishable(target, against, { cvd, minDeltaE, step })`
+- `swatch.mostReadable(bg, candidates, { level, size })`
+- `contrast(a, b)`, `isReadable(a, b, { level, size })`, `ensureContrast(a, b, { minRatio, direction, step })`
+- `apcaContrast(text, background)`
+
+All of these moved to new module paths internally but kept their public signatures.
+
+## 2.0.0-alpha.2 and earlier
+
+See the git history.

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to Swatch
+
+Thanks for working on Swatch. This repo contains the library, tests, TypeScript
+declarations, and the Eleventy docs/playground.
+
+## Requirements
+
+- Node.js 20 or newer.
+- npm.
+
+## Install
+
+```bash
+npm install
+npm --prefix docs install
+```
+
+## Common commands
+
+From the repository root:
+
+```bash
+npm test             # Run the library test suite
+npm run typecheck    # Type-check the public .d.ts against types/swatch.test-d.ts
+npm run docs:dev     # Start the docs/playground at http://localhost:8080
+npm run docs:build   # Build the static docs site
+npm run check        # Run tests, typecheck, and build docs
+npm run pack:check   # Show the npm package contents without publishing
+```
+
+The docs package also has its own local scripts under `docs/package.json`.
+
+Reference-page search is powered by [Pagefind](https://pagefind.app), whose
+index is generated by `npm run docs:build` (not by `docs:dev`), so the search
+box only returns results against a production build.
+
+## Project layout
+
+- `src/swatch.js` is the public package entry point.
+- `src/bootstrap.js` registers built-in color spaces, parsers, operations,
+  palettes, scales, and factory statics.
+- `src/core/` contains the registry, immutable state helpers, and `Swatch`
+  class.
+- `src/spaces/` contains color-space conversions.
+- `src/parse/` contains CSS/object/named-color parsing.
+- `src/operations/` contains manipulation, gamut, contrast, CVD, ΔE, palette,
+  naming, random, and temperature helpers.
+- `src/scale/` and `src/palettes/` contain scale/interpolator and built-in
+  palette support.
+- `types/swatch.d.ts` is hand-written and should be updated with public API
+  changes.
+- `tests/` contains Vitest coverage for v2 compatibility and v3 APIs.
+- `docs/src/` contains the Eleventy site and interactive playground.
+
+## API design notes
+
+- `Swatch` instances are immutable. Operations should return a new `Swatch`.
+- The canonical state shape is `{ space, coords, alpha }`.
+- Space conversions route through the registry and are lazily memoized on the
+  instance.
+- Raw space getters such as `.srgb` return mathematical coordinates and may be
+  out of gamut. Display helpers such as `.hex()` and `.rgb()` gamut-map to sRGB
+  by default.
+- Public string options should have tests and helpful error messages.
+
+## Documentation changes
+
+When adding or changing public API:
+
+1. Update `README.md`.
+2. Update or add a page in `docs/src/reference/`.
+3. Add or update playground affordances if the feature is visual.
+4. Update `types/swatch.d.ts`.
+5. Add tests that exercise the documented examples.
+
+Run `npm run check` before opening a PR.
+
+## Release checklist
+
+Before publishing:
+
+```bash
+npm run check
+npm run pack:check
+```
+
+Then review the package contents printed by `pack:check` to make sure only the
+intended source, declarations, docs, changelog, migration guide, license, and
+package metadata are included.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 Raine Luntta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MIGRATING.md

@@ -0,0 +1,189 @@
+# Migrating from swatch 2.x to 3.0
+
+Swatch 3.0 is a breaking rewrite. Storage moved to a canonical `{ space, coords, alpha }` state, conversions are lazy and memoized, manipulation became OKLCh-based by default, and the library gained CSS Color 4 parsing, wide-gamut spaces, color scales, built-in palettes, and more.
+
+Most existing code will work with only small changes. The sections below cover the breakages, from most visible to most obscure.
+
+## 1. Manipulation amounts and space (the big one)
+
+In v2 `lighten`/`darken`/`saturate`/`desaturate` operated in HSL with amounts in `0..100` (percentage-ish). In v3 they operate in OKLCh with amounts in `0..1` (OKLCh L and C units).
+
+```js
+// v2
+swatch("#ff0000").lighten(20);     // +20 HSL L
+swatch("#ff0000").saturate(10);    // +10 HSL S
+
+// v3
+swatch("#ff0000").lighten(0.1);    // +0.1 OKLCh L
+swatch("#ff0000").saturate(0.05);  // +0.05 OKLCh C
+```
+
+**Why the change?** HSL lightness isn't perceptually uniform — `#ffff00` barely moves when you lighten it in HSL, because yellow already has near-maximum HSL L. OKLCh L is perceptually uniform, so `swatch("#ffff00").lighten(0.05)` and `swatch("#0000ff").lighten(0.05)` look equally brighter.
+
+**Rough conversion:** v2 HSL amounts divide by about 200 to get a comparable v3 OKLCh amount, but the results are not numerically equivalent — they're perceptually better. Re-test visually.
+
+`spin(degrees)` is unchanged (still degrees). `greyscale`, `complement`, and `invert` keep their v2 behavior.
+
+## 2. Space conversions are getters, not methods
+
+```js
+// v2
+c.toRGB();
+c.toLab();
+c.toOklch();
+
+// v3
+c.srgb;
+c.lab;
+c.oklch;
+```
+
+v3 also adds a large set of new space getters: `c.hsv`, `c.hwb`, `c.cmyk`, `c.hsluv`, `c.luv`, `c.displayP3`, `c.rec2020`, `c.a98`, `c.prophoto`, `c.linearSrgb`, `c.xyz`.
+
+Use `c.to("<spaceId>")` to move the canonical space itself (not just read in another space):
+
+```js
+const p3 = swatch("#ff0000").to("display-p3");
+p3.space;     // "display-p3"
+p3.coords;    // [r, g, b] in Display P3, not sRGB
+```
+
+## 3. Wide-gamut inputs are no longer clamped at parse
+
+v2 parsed `color(display-p3 1 0 0)` by immediately projecting into sRGB (which clipped the chromaticity). v3 preserves the original Display P3 coordinates losslessly in the canonical state.
+
+```js
+const p3red = swatch("color(display-p3 1 0 0)");
+p3red.space;             // "display-p3"
+p3red.inGamut("srgb");   // false
+p3red.displayP3;         // { r: 1, g: 0, b: 0 }
+p3red.srgb;              // { r: 1.093, g: -0.227, b: -0.150 } — raw conversion, out of range
+p3red.toString({ format: "hex" });  // "#ff0000" (naive clip for presentation)
+```
+
+The `.srgb` / `.linearSrgb` / `.hsl` getters no longer gamut-map. For a wide-gamut source, they will return out-of-range coordinates. Call `.toGamut({ space: "srgb", method: "css4" })` explicitly to get a properly chroma-reduced in-gamut Swatch, then read its `.srgb` / `.hex`.
+
+## 4. New `toJSON()` shape
+
+```js
+// v2
+c.toJSON();
+// { hex: "#3366cc", rgb: { r, g, b }, hsl: { h, s, l }, isValid: true, format: "HEX" }
+
+// v3
+c.toJSON();
+// { space: "srgb", coords: [0.2, 0.4, 0.8], alpha: 1 }
+```
+
+The new shape round-trips cleanly: `swatch(c.toJSON()).equals(c)` is true.
+
+If you stored v2 JSON blobs, read them through an adapter that extracts `hex` and passes it to `swatch()`.
+
+## 5. `equals()` signature changed
+
+```js
+// v2
+c.equals(other);
+c.equals(other, { tolerance: 1 });
+c.equals(other, { space: "oklab", tolerance: 0.01 });
+
+// v3
+c.equals(other);              // default epsilon 1e-6 in the source space
+c.equals(other, 1e-4);        // custom epsilon
+```
+
+`other` must be a `Swatch` instance in v3 (wrap strings with `swatch(...)` first).
+
+## 6. Removed: `isValid`, `hasAlpha`, `_original`, `_originalFormat`
+
+In v2, invalid input produced a swatch with `isValid: false`. In v3, invalid input throws. Use `try`/`catch` to validate:
+
+```js
+// v2
+if (swatch(input).isValid) { ... }
+
+// v3
+try {
+  const c = swatch(input);
+  ...
+} catch {
+  // invalid
+}
+```
+
+For alpha presence, check the numeric channel directly:
+
+```js
+c.alpha < 1     // v3 replacement for v2's `c.hasAlpha`
+```
+
+`_original` and `_originalFormat` (v2 internals) are gone; use `c.space` and `c.coords` to introspect the canonical state.
+
+## 7. `mix()` takes an options bag for the space
+
+```js
+// v2
+a.mix(b, 0.5, "lab");
+a.mix(b, 0.5, "rgb");
+
+// v3
+a.mix(b, 0.5, { space: "lab" });
+a.mix(b, 0.5, { space: "srgb" });
+```
+
+Default space is still `oklab`.
+
+## 8. Harmonies are not yet ported
+
+v2's `complementary()`, `triad()`, `tetrad()`, `splitComplement()`, `analogous()`, `monochromatic()` are not in v3.0. They will return in a follow-up release. As a workaround, `spin()` + an array literal covers most cases:
+
+```js
+// v2
+c.triad();
+
+// v3 workaround
+const s = swatch(c);
+[s, s.spin(120), s.spin(240)];
+```
+
+Tracked for follow-up. If you rely on harmonies, pin to v2 or file an issue.
+
+## 9. Named color list moved
+
+v2 exported `named-colors.js` directly. v3 moved it to `src/data/named-colors.js`. If you imported the raw table, update the path. For most users, `c.toName()` / `c.name()` are the preferred API.
+
+## 10. New APIs worth learning
+
+Things v2 didn't have at all:
+
+| Feature | API |
+|---|---|
+| CSS Color 4 parsing | `swatch("oklch(0.7 0.15 240)")`, `swatch("color(display-p3 1 0 0)")` |
+| Channel get/set | `c.get("oklch.l")`, `c.set("oklch.h", 120)` |
+| Gamut mapping | `c.inGamut("srgb")`, `c.toGamut({ space, method })` |
+| Tint / shade / tone | `c.tint(0.2)`, `c.shade(0.2)`, `c.tone(0.2)` |
+| Blend modes | `c.blend(other, "multiply")` — all W3C Level 1 modes |
+| Color scales | `swatch.scale([...])`, `.domain`, `.classes`, `.padding`, `.gamma`, `.mode`, `.correctLightness`, `.cache`, `.colors(n)` |
+| Built-in palettes | `swatch.scale("viridis")`, `swatch.scale("RdBu")`, `swatch.palettes()` |
+| Interpolators | `swatch.bezier([...])`, `swatch.cubehelix({...})` |
+| Color naming | `c.name()`, `c.toName()` |
+| Temperature | `swatch.temperature(6500)`, `c.temperature()` |
+| Random | `swatch.random({ space, hue, lightness, chroma, seed })` |
+| Extra ΔE | `"94"`, `"cmc"`, `"hyab"` on top of `"76"`, `"2000"`, `"ok"` |
+| New spaces | HSV, HWB, CMYK, HSLuv, Luv, Display P3, Rec2020, A98, ProPhoto |
+
+See [README.md](./README.md) for examples of each.
+
+## 11. Unchanged
+
+The CVD/APCA/WCAG story — the heart of swatch — is unchanged:
+
+- `simulate(type, { severity })` — Brettel/Viénot dichromat simulation
+- `daltonize(type, { severity })` — Fidaner error redistribution
+- `swatch.checkPalette(colors, { cvd, minDeltaE, mode })`
+- `swatch.nearestDistinguishable(target, against, { cvd, minDeltaE, step })`
+- `swatch.mostReadable(bg, candidates, { level, size })`
+- `contrast(a, b)`, `isReadable(a, b, { level, size })`, `ensureContrast(a, b, { minRatio, direction, step })`
+- `apcaContrast(text, background)`
+
+All of these moved to new module paths internally but kept their public signatures.