css-calipers 1.0.0 → 1.1.0-beta.0

package/dist/cjs/color/formats/hex/hex.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hex = void 0;
+const culori_1 = require("culori");
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * hex — sRGB, no alpha, 8-bit (`#rrggbb`). The most compact universal form; a safe
+ * floor with no `@supports` probe. A real alpha can't be held and is a violation
+ * (use `hexAlpha`); out-of-sRGB is clamped (strictness-governed).
+ *
+ * See `hex.md`.
+ */
+exports.hex = (0, types_1.defineColorSpace)({
+    format: 'hex',
+    hasAlpha: false,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        if ((0, internals_1.hasRealAlpha)(color)) {
+            (0, internals_1.violate)(`color: alpha ${(0, internals_1.alphaOf)(color)} dropped by 'hex' (no alpha channel); use hexAlpha or solid()`, cfg.strictness);
+        }
+        const c = (0, internals_1.toRgb)((0, internals_1.fitGamut)(color, internals_1.inSrgb, 'rgb', cfg.strictness));
+        return (0, culori_1.formatHex)(c);
+    },
+});

package/dist/cjs/color/formats/hexAlpha/hexAlpha.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hexAlpha = void 0;
+const culori_1 = require("culori");
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * hexAlpha — sRGB with alpha, 8-bit (`#rrggbbaa`). The alpha counterpart of `hex`;
+ * universal, a safe floor, always carries the alpha byte. Out-of-sRGB is clamped
+ * (strictness-governed).
+ *
+ * See `hexAlpha.md`.
+ */
+exports.hexAlpha = (0, types_1.defineColorSpace)({
+    format: 'hexAlpha',
+    hasAlpha: true,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toRgb)((0, internals_1.fitGamut)(color, internals_1.inSrgb, 'rgb', cfg.strictness));
+        return (0, culori_1.formatHex8)(c);
+    },
+});

package/dist/cjs/color/formats/hsl/hsl.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hsl = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * hsl — sRGB, alpha, higher precision than 8-bit. Universal, so no `@supports` probe
+ * and a safe floor. Out-of-sRGB is clamped (strictness-governed).
+ *
+ * See `hsl.md`.
+ */
+exports.hsl = (0, types_1.defineColorSpace)({
+    format: 'hsl',
+    hasAlpha: true,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toHsl)((0, internals_1.fitGamut)(color, internals_1.inSrgb, 'rgb', cfg.strictness));
+        return `hsl(${(0, internals_1.hueOf)(c.h)} ${(0, internals_1.pct)(c.s)}% ${(0, internals_1.pct)(c.l)}%${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/hwb/hwb.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hwb = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * hwb — sRGB, alpha, higher precision. Newer than `hsl`/`rgb` (~96% support), so it
+ * carries an `@supports` probe and is not treated as the safe floor. Out-of-sRGB is
+ * clamped (strictness-governed).
+ *
+ * See `hwb.md`.
+ */
+exports.hwb = (0, types_1.defineColorSpace)({
+    format: 'hwb',
+    hasAlpha: true,
+    gamut: 'srgb',
+    supportsProbe: '(color: hwb(0 0% 0%))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toHwb)((0, internals_1.fitGamut)(color, internals_1.inSrgb, 'rgb', cfg.strictness));
+        return `hwb(${(0, internals_1.hueOf)(c.h)} ${(0, internals_1.pct)(c.w)}% ${(0, internals_1.pct)(c.b)}%${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/index.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineColorSpace = exports.colorFormats = void 0;
+const display_p3_1 = require("./display-p3/display-p3");
+const hex_1 = require("./hex/hex");
+const hexAlpha_1 = require("./hexAlpha/hexAlpha");
+const hsl_1 = require("./hsl/hsl");
+const hwb_1 = require("./hwb/hwb");
+const lab_1 = require("./lab/lab");
+const lch_1 = require("./lch/lch");
+const oklab_1 = require("./oklab/oklab");
+const oklch_1 = require("./oklch/oklch");
+const rgb_1 = require("./rgb/rgb");
+const rgba_1 = require("./rgba/rgba");
+/**
+ * The unified color-format registry: every built-in format's descriptor, keyed by
+ * its format name. Each entry doubles as the book's output selector (it satisfies
+ * `CssFormat`, having a `format`) and as the fallback descriptor (render + metadata).
+ * Custom/experimental formats join a priority list via `defineColorSpace`, they do
+ * not need to live here.
+ */
+exports.colorFormats = {
+    rgba: rgba_1.rgba,
+    rgb: rgb_1.rgb,
+    hex: hex_1.hex,
+    hexAlpha: hexAlpha_1.hexAlpha,
+    hsl: hsl_1.hsl,
+    hwb: hwb_1.hwb,
+    lab: lab_1.lab,
+    lch: lch_1.lch,
+    oklab: oklab_1.oklab,
+    oklch: oklch_1.oklch,
+    displayP3: display_p3_1.displayP3,
+};
+var types_1 = require("./types");
+Object.defineProperty(exports, "defineColorSpace", { enumerable: true, get: function () { return types_1.defineColorSpace; } });

package/dist/cjs/color/formats/internals.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasRealAlpha = exports.fitGamut = exports.inP3 = exports.inSrgb = exports.toP3 = exports.toOklch = exports.toOklab = exports.toLch = exports.toLab = exports.toHwb = exports.toHsl = exports.toRgb = exports.alphaSlot = exports.alphaOf = exports.pct = exports.hueOf = exports.channel255 = exports.clamp01 = exports.round = exports.violate = void 0;
+const culori_1 = require("culori");
+/**
+ * Shared render toolkit for the per-format descriptors under `formats/` (and, for
+ * now, for `../color.ts`'s `serialize`, which imports from here). Descriptors own
+ * their render and build it from these; `serialize` will retire once every format
+ * has a descriptor.
+ */
+const notRelease = () => {
+    var _a, _b;
+    return ((_b = (_a = globalThis
+        .process) === null || _a === void 0 ? void 0 : _a.env) === null || _b === void 0 ? void 0 : _b.NODE_ENV) !== 'production';
+};
+/**
+ * Surface a "can't faithfully represent this" violation (dropped alpha,
+ * out-of-gamut) per the strictness knob. `auto` = throw in dev / warn in prod.
+ */
+const violate = (message, strictness) => {
+    const mode = strictness === 'auto'
+        ? notRelease()
+            ? 'throw'
+            : 'warn'
+        : strictness;
+    if (mode === 'throw')
+        throw new Error(message);
+    if (mode === 'warn')
+        console.warn(message);
+};
+exports.violate = violate;
+/** Round to `precision` decimal places (default 3). */
+const round = (value, precision = 3) => {
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+};
+exports.round = round;
+const clamp01 = (value) => Math.min(1, Math.max(0, value));
+exports.clamp01 = clamp01;
+const channel255 = (value) => Math.round((0, exports.clamp01)(value) * 255);
+exports.channel255 = channel255;
+/** Normalize a hue to `[0, 360)` at 2dp; a missing hue reads as 0. */
+const hueOf = (h) => (0, exports.round)((((h !== null && h !== void 0 ? h : 0) % 360) + 360) % 360, 2);
+exports.hueOf = hueOf;
+const pct = (value) => (0, exports.round)(value * 100, 2);
+exports.pct = pct;
+/** A color's alpha rounded to 3dp; a missing alpha is opaque (1). */
+const alphaOf = (color) => { var _a; return (0, exports.round)((_a = color.alpha) !== null && _a !== void 0 ? _a : 1, 3); };
+exports.alphaOf = alphaOf;
+/**
+ * The ` / <alpha>` slot for alpha-capable formats. Emitted unless the color is
+ * opaque and the config drops opaque alpha (`omitOpaqueAlpha`).
+ */
+const alphaSlot = (color, cfg) => {
+    const alpha = (0, exports.alphaOf)(color);
+    const dropOpaque = cfg.omitOpaqueAlpha && alpha === 1;
+    return dropOpaque ? '' : ` / ${alpha}`;
+};
+exports.alphaSlot = alphaSlot;
+exports.toRgb = (0, culori_1.converter)('rgb');
+exports.toHsl = (0, culori_1.converter)('hsl');
+exports.toHwb = (0, culori_1.converter)('hwb');
+exports.toLab = (0, culori_1.converter)('lab');
+exports.toLch = (0, culori_1.converter)('lch');
+exports.toOklab = (0, culori_1.converter)('oklab');
+exports.toOklch = (0, culori_1.converter)('oklch');
+exports.toP3 = (0, culori_1.converter)('p3');
+// Tolerant gamut check: a color round-tripped through OKLCH can drift a hair past a
+// channel bound (sRGB `red` -> 1.0000001), so allow a tiny epsilon before calling it
+// out-of-gamut. Genuinely out-of-gamut colors miss by far more.
+const GAMUT_EPSILON = 1e-4;
+const within01 = (n) => n >= -GAMUT_EPSILON && n <= 1 + GAMUT_EPSILON;
+const inSrgb = (color) => {
+    const c = (0, exports.toRgb)(color);
+    return within01(c.r) && within01(c.g) && within01(c.b);
+};
+exports.inSrgb = inSrgb;
+const inP3 = (color) => {
+    const c = (0, exports.toP3)(color);
+    return within01(c.r) && within01(c.g) && within01(c.b);
+};
+exports.inP3 = inP3;
+/** Bring a color into a target gamut, surfacing a violation if it wasn't inside. */
+const fitGamut = (color, within, gamut, strictness) => {
+    if (within(color)) {
+        return color;
+    }
+    (0, exports.violate)(`color: out of ${gamut === 'rgb' ? 'sRGB' : 'display-p3'} gamut; chroma clamped to fit`, strictness);
+    return (0, culori_1.clampChroma)(color, 'oklch', gamut);
+};
+exports.fitGamut = fitGamut;
+const hasRealAlpha = (color) => color.alpha !== undefined && color.alpha !== 1;
+exports.hasRealAlpha = hasRealAlpha;

package/dist/cjs/color/formats/lab/lab.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lab = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * lab — CIELAB, unbounded gamut (holds any color), float precision. Syntax-level
+ * (browser gamut-maps to the display), so a fallback needs only an `@supports`
+ * probe; not a floor.
+ *
+ * See `lab.md`.
+ */
+exports.lab = (0, types_1.defineColorSpace)({
+    format: 'lab',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: lab(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toLab)(color);
+        return `lab(${(0, internals_1.round)(c.l, 3)} ${(0, internals_1.round)(c.a, 3)} ${(0, internals_1.round)(c.b, 3)}${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/lch/lch.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.lch = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * lch — CIELCH (cylindrical CIELAB), unbounded gamut, float precision. Syntax-level,
+ * so a fallback needs only an `@supports` probe; not a floor.
+ *
+ * See `lch.md`.
+ */
+exports.lch = (0, types_1.defineColorSpace)({
+    format: 'lch',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: lch(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toLch)(color);
+        return `lch(${(0, internals_1.round)(c.l, 3)} ${(0, internals_1.round)(c.c, 3)} ${(0, internals_1.hueOf)(c.h)}${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/oklab/oklab.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oklab = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * oklab — OKLab (rectangular), unbounded gamut, float precision. Perceptual, like
+ * `oklch` but in a/b coordinates. Syntax-level, so a fallback needs only an
+ * `@supports` probe; not a floor.
+ *
+ * See `oklab.md`.
+ */
+exports.oklab = (0, types_1.defineColorSpace)({
+    format: 'oklab',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: oklab(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toOklab)(color);
+        return `oklab(${(0, internals_1.round)(c.l, 4)} ${(0, internals_1.round)(c.a, 4)} ${(0, internals_1.round)(c.b, 4)}${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/oklch/oklch.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.oklch = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * oklch — the perceptual modern default (CSS Color 4).
+ *
+ * Fidelity: carries alpha; gamut is unbounded, so it can hold any color losslessly
+ * from the OKLCH store (it is the storage space). Browser: a syntax-level format, so
+ * a fallback needs only an `@supports` probe, not `@media (color-gamut)`, and it is
+ * not an sRGB floor. Render is a direct read of l / c / h, hardened to
+ * `ColorString<'oklch'>`.
+ *
+ * See `oklch.md` for the format's tests and possible fallbacks.
+ */
+exports.oklch = (0, types_1.defineColorSpace)({
+    format: 'oklch',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: oklch(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = (0, internals_1.toOklch)(color);
+        return `oklch(${(0, internals_1.round)(c.l, 4)} ${(0, internals_1.round)(c.c, 4)} ${(0, internals_1.hueOf)(c.h)}${(0, internals_1.alphaSlot)(color, cfg)})`;
+    },
+});

package/dist/cjs/color/formats/resolve.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asDescriptor = void 0;
+/**
+ * Resolve an `output` entry to the descriptor that owns its render + fidelity bits.
+ *
+ * An `output` entry is already a full `ColorSpaceDescriptor` (e.g. `colorFormats.hex`
+ * IS one), OR a bare `CssFormat` selector (`{ format: 'hex' }`). A CUSTOM format
+ * authored via `defineColorSpace` carries an arbitrary `format` string, so it can
+ * never be found by name in the built-in registry; it must be used as-is. So: if the
+ * passed object already carries descriptor fields (it has a `render`), use it
+ * directly; otherwise fall back to the registry by name. No global mutable registry,
+ * the custom descriptor travels through the config object.
+ */
+const asDescriptor = (format, registry) => 'render' in format ? format : registry[format.format];
+exports.asDescriptor = asDescriptor;

package/dist/cjs/color/formats/rgb/rgb.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgb = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * rgb — the sRGB floor: 8-bit, no alpha, universally renderable.
+ *
+ * Fidelity: sRGB gamut, no alpha. Browser: universal, so no `@supports` probe, and
+ * the fallback chain stops here (`srgbFloor`). An out-of-sRGB color is clamped
+ * (strictness-governed); a real alpha can't be held and is a violation.
+ *
+ * See `rgb.md`.
+ */
+exports.rgb = (0, types_1.defineColorSpace)({
+    format: 'rgb',
+    hasAlpha: false,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        if ((0, internals_1.hasRealAlpha)(color)) {
+            (0, internals_1.violate)(`color: alpha ${(0, internals_1.alphaOf)(color)} dropped by 'rgb' (no alpha channel); use rgba or solid()`, cfg.strictness);
+        }
+        const c = (0, internals_1.toRgb)((0, internals_1.fitGamut)(color, internals_1.inSrgb, 'rgb', cfg.strictness));
+        return `rgb(${(0, internals_1.channel255)(c.r)}, ${(0, internals_1.channel255)(c.g)}, ${(0, internals_1.channel255)(c.b)})`;
+    },
+});

package/dist/cjs/color/formats/rgba/rgba.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.rgba = void 0;
+const internals_1 = require("../internals");
+const types_1 = require("../types");
+/**
+ * rgba — sRGB with alpha (8-bit). Universal, so no `@supports` probe and a safe
+ * floor. When the color is opaque and `omitOpaqueAlpha` is set it collapses to
+ * `rgb(...)` (lossless), matching the book.
+ *
+ * See `rgba.md`.
+ */
+exports.rgba = (0, types_1.defineColorSpace)({
+    format: 'rgba',
+    hasAlpha: true,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        const alpha = (0, internals_1.alphaOf)(color);
+        const dropOpaque = cfg.omitOpaqueAlpha && alpha === 1;
+        const c = (0, internals_1.toRgb)((0, internals_1.fitGamut)(color, internals_1.inSrgb, 'rgb', cfg.strictness));
+        const body = `${(0, internals_1.channel255)(c.r)}, ${(0, internals_1.channel255)(c.g)}, ${(0, internals_1.channel255)(c.b)}`;
+        return (dropOpaque ? `rgb(${body})` : `rgba(${body}, ${alpha})`);
+    },
+});

package/dist/cjs/color/formats/types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineColorSpace = void 0;
+/**
+ * Author a color-format descriptor (built-in or custom/experimental). A thin
+ * identity that pins the type and infers the format brand `F`, so a new format can
+ * be registered for the priority list / fallback chain without the library shipping
+ * it.
+ */
+const defineColorSpace = (descriptor) => descriptor;
+exports.defineColorSpace = defineColorSpace;