css-calipers 0.15.0 → 1.1.0-beta.0

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

@@ -0,0 +1,21 @@
+import { alphaSlot, fitGamut, hueOf, inSrgb, pct, toHwb, } from '../internals';
+import { defineColorSpace } from '../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`.
+ */
+export const hwb = defineColorSpace({
+    format: 'hwb',
+    hasAlpha: true,
+    gamut: 'srgb',
+    supportsProbe: '(color: hwb(0 0% 0%))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = toHwb(fitGamut(color, inSrgb, 'rgb', cfg.strictness));
+        return `hwb(${hueOf(c.h)} ${pct(c.w)}% ${pct(c.b)}%${alphaSlot(color, cfg)})`;
+    },
+});

package/dist/esm/color/formats/index.d.ts

@@ -0,0 +1,24 @@
+import type { ColorSpaceDescriptor } from './types';
+/**
+ * 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.
+ */
+export declare const colorFormats: {
+    rgba: ColorSpaceDescriptor<"rgba">;
+    rgb: ColorSpaceDescriptor<"rgb">;
+    hex: ColorSpaceDescriptor<"hex">;
+    hexAlpha: ColorSpaceDescriptor<"hexAlpha">;
+    hsl: ColorSpaceDescriptor<"hsl">;
+    hwb: ColorSpaceDescriptor<"hwb">;
+    lab: ColorSpaceDescriptor<"lab">;
+    lch: ColorSpaceDescriptor<"lch">;
+    oklab: ColorSpaceDescriptor<"oklab">;
+    oklch: ColorSpaceDescriptor<"oklch">;
+    displayP3: ColorSpaceDescriptor<"displayP3">;
+};
+export type { ColorSpaceDescriptor, ColorString, Gamut, } from './types';
+export { defineColorSpace } from './types';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/color/formats/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/color/formats/index.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;CAY2B,CAAC;AAErD,YAAY,EACV,oBAAoB,EACpB,WAAW,EACX,KAAK,GACN,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC"}

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

@@ -0,0 +1,32 @@
+import { displayP3 } from './display-p3/display-p3';
+import { hex } from './hex/hex';
+import { hexAlpha } from './hexAlpha/hexAlpha';
+import { hsl } from './hsl/hsl';
+import { hwb } from './hwb/hwb';
+import { lab } from './lab/lab';
+import { lch } from './lch/lch';
+import { oklab } from './oklab/oklab';
+import { oklch } from './oklch/oklch';
+import { rgb } from './rgb/rgb';
+import { rgba } from './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.
+ */
+export const colorFormats = {
+    rgba,
+    rgb,
+    hex,
+    hexAlpha,
+    hsl,
+    hwb,
+    lab,
+    lch,
+    oklab,
+    oklch,
+    displayP3,
+};
+export { defineColorSpace } from './types';

package/dist/esm/color/formats/internals.d.ts

@@ -0,0 +1,35 @@
+import type { Color } from 'culori';
+import type { ColorConfig, Strictness } from '../types';
+/**
+ * Surface a "can't faithfully represent this" violation (dropped alpha,
+ * out-of-gamut) per the strictness knob. `auto` = throw in dev / warn in prod.
+ */
+export declare const violate: (message: string, strictness: Strictness) => void;
+/** Round to `precision` decimal places (default 3). */
+export declare const round: (value: number, precision?: number) => number;
+export declare const clamp01: (value: number) => number;
+export declare const channel255: (value: number) => number;
+/** Normalize a hue to `[0, 360)` at 2dp; a missing hue reads as 0. */
+export declare const hueOf: (h: number | undefined) => number;
+export declare const pct: (value: number) => number;
+/** A color's alpha rounded to 3dp; a missing alpha is opaque (1). */
+export declare const alphaOf: (color: Color) => number;
+/**
+ * The ` / <alpha>` slot for alpha-capable formats. Emitted unless the color is
+ * opaque and the config drops opaque alpha (`omitOpaqueAlpha`).
+ */
+export declare const alphaSlot: (color: Color, cfg: ColorConfig) => string;
+export declare const toRgb: import("culori/src/converter").ConvertFn<"rgb">;
+export declare const toHsl: import("culori/src/converter").ConvertFn<"hsl">;
+export declare const toHwb: import("culori/src/converter").ConvertFn<"hwb">;
+export declare const toLab: import("culori/src/converter").ConvertFn<"lab">;
+export declare const toLch: import("culori/src/converter").ConvertFn<"lch">;
+export declare const toOklab: import("culori/src/converter").ConvertFn<"oklab">;
+export declare const toOklch: import("culori/src/converter").ConvertFn<"oklch">;
+export declare const toP3: import("culori/src/converter").ConvertFn<"p3">;
+export declare const inSrgb: (color: Color) => boolean;
+export declare const inP3: (color: Color) => boolean;
+/** Bring a color into a target gamut, surfacing a violation if it wasn't inside. */
+export declare const fitGamut: (color: Color, within: (c: Color) => boolean, gamut: "rgb" | "p3", strictness: Strictness) => Color;
+export declare const hasRealAlpha: (color: Color) => boolean;
+//# sourceMappingURL=internals.d.ts.map

package/dist/esm/color/formats/internals.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"internals.d.ts","sourceRoot":"","sources":["../../../../src/color/formats/internals.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAGpC,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAaxD;;;GAGG;AACH,eAAO,MAAM,OAAO,GAClB,SAAS,MAAM,EACf,YAAY,UAAU,KACrB,IASF,CAAC;AAEF,uDAAuD;AACvD,eAAO,MAAM,KAAK,GAAI,OAAO,MAAM,EAAE,kBAAa,KAAG,MAGpD,CAAC;AACF,eAAO,MAAM,OAAO,GAAI,OAAO,MAAM,KAAG,MACP,CAAC;AAClC,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,MACT,CAAC;AACnC,sEAAsE;AACtE,eAAO,MAAM,KAAK,GAAI,GAAG,MAAM,GAAG,SAAS,KAAG,MACJ,CAAC;AAC3C,eAAO,MAAM,GAAG,GAAI,OAAO,MAAM,KAAG,MAA+B,CAAC;AACpE,qEAAqE;AACrE,eAAO,MAAM,OAAO,GAAI,OAAO,KAAK,KAAG,MACX,CAAC;AAE7B;;;GAGG;AACH,eAAO,MAAM,SAAS,GAAI,OAAO,KAAK,EAAE,KAAK,WAAW,KAAG,MAI1D,CAAC;AAEF,eAAO,MAAM,KAAK,iDAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,iDAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,iDAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,iDAAmB,CAAC;AACtC,eAAO,MAAM,KAAK,iDAAmB,CAAC;AACtC,eAAO,MAAM,OAAO,mDAAqB,CAAC;AAC1C,eAAO,MAAM,OAAO,mDAAqB,CAAC;AAC1C,eAAO,MAAM,IAAI,gDAAkB,CAAC;AAQpC,eAAO,MAAM,MAAM,GAAI,OAAO,KAAK,KAAG,OAGrC,CAAC;AACF,eAAO,MAAM,IAAI,GAAI,OAAO,KAAK,KAAG,OAGnC,CAAC;AAEF,oFAAoF;AACpF,eAAO,MAAM,QAAQ,GACnB,OAAO,KAAK,EACZ,QAAQ,CAAC,CAAC,EAAE,KAAK,KAAK,OAAO,EAC7B,OAAO,KAAK,GAAG,IAAI,EACnB,YAAY,UAAU,KACrB,KASF,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,OAAO,KAAK,KAAG,OACI,CAAC"}

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

@@ -0,0 +1,78 @@
+import { clampChroma, converter } from '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.
+ */
+export 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);
+};
+/** Round to `precision` decimal places (default 3). */
+export const round = (value, precision = 3) => {
+    const factor = 10 ** precision;
+    return Math.round(value * factor) / factor;
+};
+export const clamp01 = (value) => Math.min(1, Math.max(0, value));
+export const channel255 = (value) => Math.round(clamp01(value) * 255);
+/** Normalize a hue to `[0, 360)` at 2dp; a missing hue reads as 0. */
+export const hueOf = (h) => round((((h !== null && h !== void 0 ? h : 0) % 360) + 360) % 360, 2);
+export const pct = (value) => round(value * 100, 2);
+/** A color's alpha rounded to 3dp; a missing alpha is opaque (1). */
+export const alphaOf = (color) => { var _a; return round((_a = color.alpha) !== null && _a !== void 0 ? _a : 1, 3); };
+/**
+ * The ` / <alpha>` slot for alpha-capable formats. Emitted unless the color is
+ * opaque and the config drops opaque alpha (`omitOpaqueAlpha`).
+ */
+export const alphaSlot = (color, cfg) => {
+    const alpha = alphaOf(color);
+    const dropOpaque = cfg.omitOpaqueAlpha && alpha === 1;
+    return dropOpaque ? '' : ` / ${alpha}`;
+};
+export const toRgb = converter('rgb');
+export const toHsl = converter('hsl');
+export const toHwb = converter('hwb');
+export const toLab = converter('lab');
+export const toLch = converter('lch');
+export const toOklab = converter('oklab');
+export const toOklch = converter('oklch');
+export const toP3 = 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;
+export const inSrgb = (color) => {
+    const c = toRgb(color);
+    return within01(c.r) && within01(c.g) && within01(c.b);
+};
+export const inP3 = (color) => {
+    const c = toP3(color);
+    return within01(c.r) && within01(c.g) && within01(c.b);
+};
+/** Bring a color into a target gamut, surfacing a violation if it wasn't inside. */
+export const fitGamut = (color, within, gamut, strictness) => {
+    if (within(color)) {
+        return color;
+    }
+    violate(`color: out of ${gamut === 'rgb' ? 'sRGB' : 'display-p3'} gamut; chroma clamped to fit`, strictness);
+    return clampChroma(color, 'oklch', gamut);
+};
+export const hasRealAlpha = (color) => color.alpha !== undefined && color.alpha !== 1;

package/dist/esm/color/formats/lab/lab.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`.
+ */
+export declare const lab: import("../types").ColorSpaceDescriptor<"lab">;
+//# sourceMappingURL=lab.d.ts.map

package/dist/esm/color/formats/lab/lab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lab.d.ts","sourceRoot":"","sources":["../../../../../src/color/formats/lab/lab.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,GAAG,gDAWd,CAAC"}

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

@@ -0,0 +1,21 @@
+import { alphaSlot, round, toLab } from '../internals';
+import { defineColorSpace } from '../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`.
+ */
+export const lab = defineColorSpace({
+    format: 'lab',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: lab(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = toLab(color);
+        return `lab(${round(c.l, 3)} ${round(c.a, 3)} ${round(c.b, 3)}${alphaSlot(color, cfg)})`;
+    },
+});

package/dist/esm/color/formats/lch/lch.d.ts

@@ -0,0 +1,8 @@
+/**
+ * lch — CIELCH (cylindrical CIELAB), unbounded gamut, float precision. Syntax-level,
+ * so a fallback needs only an `@supports` probe; not a floor.
+ *
+ * See `lch.md`.
+ */
+export declare const lch: import("../types").ColorSpaceDescriptor<"lch">;
+//# sourceMappingURL=lch.d.ts.map

package/dist/esm/color/formats/lch/lch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lch.d.ts","sourceRoot":"","sources":["../../../../../src/color/formats/lch/lch.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,eAAO,MAAM,GAAG,gDAWd,CAAC"}

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

@@ -0,0 +1,20 @@
+import { alphaSlot, hueOf, round, toLch } from '../internals';
+import { defineColorSpace } from '../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`.
+ */
+export const lch = defineColorSpace({
+    format: 'lch',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: lch(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = toLch(color);
+        return `lch(${round(c.l, 3)} ${round(c.c, 3)} ${hueOf(c.h)}${alphaSlot(color, cfg)})`;
+    },
+});

package/dist/esm/color/formats/oklab/oklab.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`.
+ */
+export declare const oklab: import("../types").ColorSpaceDescriptor<"oklab">;
+//# sourceMappingURL=oklab.d.ts.map

package/dist/esm/color/formats/oklab/oklab.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oklab.d.ts","sourceRoot":"","sources":["../../../../../src/color/formats/oklab/oklab.ts"],"names":[],"mappings":"AAOA;;;;;;GAMG;AACH,eAAO,MAAM,KAAK,kDAWhB,CAAC"}

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

@@ -0,0 +1,21 @@
+import { alphaSlot, round, toOklab } from '../internals';
+import { defineColorSpace } from '../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`.
+ */
+export const oklab = defineColorSpace({
+    format: 'oklab',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: oklab(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = toOklab(color);
+        return `oklab(${round(c.l, 4)} ${round(c.a, 4)} ${round(c.b, 4)}${alphaSlot(color, cfg)})`;
+    },
+});

package/dist/esm/color/formats/oklch/oklch.d.ts

@@ -0,0 +1,13 @@
+/**
+ * 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.
+ */
+export declare const oklch: import("../types").ColorSpaceDescriptor<"oklch">;
+//# sourceMappingURL=oklch.d.ts.map

package/dist/esm/color/formats/oklch/oklch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oklch.d.ts","sourceRoot":"","sources":["../../../../../src/color/formats/oklch/oklch.ts"],"names":[],"mappings":"AAOA;;;;;;;;;;GAUG;AACH,eAAO,MAAM,KAAK,kDAWhB,CAAC"}

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

@@ -0,0 +1,25 @@
+import { alphaSlot, hueOf, round, toOklch } from '../internals';
+import { defineColorSpace } from '../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.
+ */
+export const oklch = defineColorSpace({
+    format: 'oklch',
+    hasAlpha: true,
+    gamut: 'unbounded',
+    supportsProbe: '(color: oklch(0 0 0))',
+    gamutDependent: false,
+    srgbFloor: false,
+    render: (color, cfg) => {
+        const c = toOklch(color);
+        return `oklch(${round(c.l, 4)} ${round(c.c, 4)} ${hueOf(c.h)}${alphaSlot(color, cfg)})`;
+    },
+});

package/dist/esm/color/formats/resolve.d.ts

@@ -0,0 +1,15 @@
+import type { OutputFormat } from '../types';
+import type { ColorSpaceDescriptor } from './types';
+/**
+ * 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.
+ */
+export declare const asDescriptor: (format: OutputFormat, registry: Readonly<Record<string, ColorSpaceDescriptor<string>>>) => ColorSpaceDescriptor<string>;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/esm/color/formats/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../../../src/color/formats/resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,UAAU,CAAC;AAC7C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAEpD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,YAAY,GACvB,QAAQ,YAAY,EACpB,UAAU,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC,KAC/D,oBAAoB,CAAC,MAAM,CACyB,CAAC"}

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export const asDescriptor = (format, registry) => 'render' in format ? format : registry[format.format];

package/dist/esm/color/formats/rgb/rgb.d.ts

@@ -0,0 +1,11 @@
+/**
+ * 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`.
+ */
+export declare const rgb: import("../types").ColorSpaceDescriptor<"rgb">;
+//# sourceMappingURL=rgb.d.ts.map

package/dist/esm/color/formats/rgb/rgb.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgb.d.ts","sourceRoot":"","sources":["../../../../../src/color/formats/rgb/rgb.ts"],"names":[],"mappings":"AAeA;;;;;;;;GAQG;AACH,eAAO,MAAM,GAAG,gDAiBd,CAAC"}

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

@@ -0,0 +1,26 @@
+import { alphaOf, channel255, fitGamut, hasRealAlpha, inSrgb, toRgb, violate, } from '../internals';
+import { defineColorSpace } from '../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`.
+ */
+export const rgb = defineColorSpace({
+    format: 'rgb',
+    hasAlpha: false,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        if (hasRealAlpha(color)) {
+            violate(`color: alpha ${alphaOf(color)} dropped by 'rgb' (no alpha channel); use rgba or solid()`, cfg.strictness);
+        }
+        const c = toRgb(fitGamut(color, inSrgb, 'rgb', cfg.strictness));
+        return `rgb(${channel255(c.r)}, ${channel255(c.g)}, ${channel255(c.b)})`;
+    },
+});

package/dist/esm/color/formats/rgba/rgba.d.ts

@@ -0,0 +1,9 @@
+/**
+ * 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`.
+ */
+export declare const rgba: import("../types").ColorSpaceDescriptor<"rgba">;
+//# sourceMappingURL=rgba.d.ts.map

package/dist/esm/color/formats/rgba/rgba.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rgba.d.ts","sourceRoot":"","sources":["../../../../../src/color/formats/rgba/rgba.ts"],"names":[],"mappings":"AAaA;;;;;;GAMG;AACH,eAAO,MAAM,IAAI,iDAgBf,CAAC"}

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

@@ -0,0 +1,24 @@
+import { alphaOf, channel255, fitGamut, inSrgb, toRgb, } from '../internals';
+import { defineColorSpace } from '../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`.
+ */
+export const rgba = defineColorSpace({
+    format: 'rgba',
+    hasAlpha: true,
+    gamut: 'srgb',
+    supportsProbe: null,
+    gamutDependent: false,
+    srgbFloor: true,
+    render: (color, cfg) => {
+        const alpha = alphaOf(color);
+        const dropOpaque = cfg.omitOpaqueAlpha && alpha === 1;
+        const c = toRgb(fitGamut(color, inSrgb, 'rgb', cfg.strictness));
+        const body = `${channel255(c.r)}, ${channel255(c.g)}, ${channel255(c.b)}`;
+        return (dropOpaque ? `rgb(${body})` : `rgba(${body}, ${alpha})`);
+    },
+});

package/dist/esm/color/formats/types.d.ts

@@ -0,0 +1,48 @@
+import type { Color } from 'culori';
+import type { ColorConfig, ColorString, FormatName } from '../types';
+export type { ColorString };
+/** The gamut a format can represent, widening `srgb` ⊂ `p3` ⊂ `unbounded`. */
+export type Gamut = 'srgb' | 'p3' | 'unbounded';
+/**
+ * A color-format descriptor: how to render the format from the canonical OKLCH
+ * store, plus the metadata its two readers need.
+ *
+ * - **fidelity** (`hasAlpha`, `gamut`): the color book reads these to pick the
+ *   single simplest format that faithfully holds a color (the output escalation).
+ * - **browser** (`supportsProbe`, `gamutDependent`, `srgbFloor`): a separate
+ *   fallback helper reads these to assemble multi-declaration browser fallbacks.
+ *
+ * `render` returns a `ColorString<F>` so each format's output is hardened to its
+ * own type. Built-ins use a `FormatName`; a custom format (via `defineColorSpace`)
+ * uses any string and is then usable in the priority list / fallback chain.
+ */
+export interface ColorSpaceDescriptor<F extends string = FormatName> {
+    /** the format's key; also keys it in the registry and brands its output. */
+    readonly format: F;
+    /** render a stored (OKLCH) color to this format's CSS value, typed to the brand. */
+    readonly render: (color: Color, cfg: ColorConfig) => ColorString<F>;
+    /** fidelity: whether the format carries an alpha channel. */
+    readonly hasAlpha: boolean;
+    /** fidelity: the gamut the format can represent. */
+    readonly gamut: Gamut;
+    /**
+     * browser: the `@supports` test that detects parse-support (e.g.
+     * `'(color: oklch(0 0 0))'`), or `null` for a universally-supported format.
+     */
+    readonly supportsProbe: string | null;
+    /**
+     * browser: whether a fallback should also gate on `@media (color-gamut: ...)`
+     * (e.g. `display-p3`). Syntax-only modern formats (`oklch`, `lab`) are `false`.
+     */
+    readonly gamutDependent: boolean;
+    /** browser: a safe sRGB floor; the fallback chain stops here. */
+    readonly srgbFloor: boolean;
+}
+/**
+ * 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.
+ */
+export declare const defineColorSpace: <F extends string>(descriptor: ColorSpaceDescriptor<F>) => ColorSpaceDescriptor<F>;
+//# sourceMappingURL=types.d.ts.map

package/dist/esm/color/formats/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../../src/color/formats/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAEpC,OAAO,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AAIrE,YAAY,EAAE,WAAW,EAAE,CAAC;AAE5B,8EAA8E;AAC9E,MAAM,MAAM,KAAK,GAAG,MAAM,GAAG,IAAI,GAAG,WAAW,CAAC;AAEhD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,oBAAoB,CAAC,CAAC,SAAS,MAAM,GAAG,UAAU;IACjE,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACnB,oFAAoF;IACpF,QAAQ,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,KAAK,WAAW,CAAC,CAAC,CAAC,CAAC;IACpE,6DAA6D;IAC7D,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;IACjC,iEAAiE;IACjE,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,GAAI,CAAC,SAAS,MAAM,EAC/C,YAAY,oBAAoB,CAAC,CAAC,CAAC,KAClC,oBAAoB,CAAC,CAAC,CAAe,CAAC"}

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

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export const defineColorSpace = (descriptor) => descriptor;

package/dist/esm/color/index.d.ts

@@ -0,0 +1,81 @@
+import type { Color } from 'culori';
+import { colorFormats, type ColorSpaceDescriptor, defineColorSpace, type Gamut } from './formats';
+import type { ColorConfig, ColorFormatPlugin, ColorInput, CssFormat, FormatName, ResolvedColor, Store } from './types';
+export * from './types';
+/**
+ * Parse any `ColorInput` into the canonical store (built-in formats only). The public,
+ * instance-agnostic parser. Factory instances thread their own plugin-aware parser
+ * internally; this stays the bare built-in entry point.
+ */
+export declare const parseColor: (input: ColorInput | Color) => Store;
+/** Normalize a parsed store into the canonical OKLCH working space. */
+export declare const storeColor: (store: Store) => Store;
+export { colorFormats, type ColorSpaceDescriptor, defineColorSpace, type Gamut, };
+/**
+ * Resolve a store + config into an immutable, navigable `ResolvedColor`, using the
+ * built-in parser and no custom plugins. The public, instance-agnostic resolver
+ * (re-exported as `resolveColor`). Factory instances use `resolveWith` internally to
+ * thread their own plugin-aware parser and named selectors.
+ */
+export declare const resolve: <F extends FormatName = FormatName>(store: Store, cfg: ColorConfig) => ResolvedColor<F>;
+/**
+ * The default output priority: the simplest faithful format first. With no argument
+ * `.css()` escalates down this ladder to the first format that holds the color (see
+ * `formats/README.md`). Overridable per book via `publishBookColor({ config })`.
+ *
+ * Pared to one format per distinct output space, most popular first (see
+ * `docs/color-format-popularity.md`). Every other built-in format is a redundant
+ * cover of one of these three, so it would never win escalation; it stays reachable
+ * via a named selector (`.hwb()`, ...) or `.formatAs(colorFormats.x)`.
+ *   - `hex`:   solids (opaque sRGB). ~76% of real-world colour declarations.
+ *   - `rgba`:  translucent sRGB. The dominant alpha form (rgba >> #rrggbbaa, hsla).
+ *   - `oklch`: the unbounded floor, holds any colour (P3 and beyond), and is the
+ *              primitive's own storage space, so it is the zero-loss fallback.
+ */
+export declare const defaultFormatPriority: CssFormat[];
+/** The colour primitive's defaults. */
+export declare const defaultColorConfig: ColorConfig;
+/** The format-literal union carried by a plugins tuple (`'zoo' | ...`). */
+type PluginFormat<P extends ReadonlyArray<ColorFormatPlugin>> = P[number]['format'];
+/**
+ * A `ResolvedColor` augmented with one typed, lazy named selector per registered
+ * plugin format (e.g. `.zoo`): each returns this colour reconfigured to render through
+ * that plugin's descriptor, then finished via `.css()`. Typed from the passed formats
+ * tuple, not `any`.
+ */
+type CustomResolvedColor<P extends ReadonlyArray<ColorFormatPlugin>> = ResolvedColor & {
+    readonly [K in PluginFormat<P>]: ResolvedColor<K>;
+};
+/** A factory-bound `color()`: same call shape, plus the per-instance registry. */
+export interface CustomColor<P extends ReadonlyArray<ColorFormatPlugin>> {
+    (input: ColorInput, config?: Partial<ColorConfig>): CustomResolvedColor<P>;
+    /**
+     * The per-instance format registry (built-ins + plugins), keyed by format name. A
+     * future gilding/fallback seam reads each descriptor's fidelity / browser bits from
+     * here.
+     */
+    readonly formats: Readonly<Record<string, ColorSpaceDescriptor<string>>>;
+}
+/** The config a custom colour instance is built from. */
+export interface CreateColorConfig<P extends ReadonlyArray<ColorFormatPlugin>> {
+    /** the custom format plugins to register at the input + output edges. */
+    formats: P;
+}
+/**
+ * Build a `color()`-shaped function bound to the given custom format plugins. The
+ * instance parser tries the built-in parse first, then each plugin's `parse` in order;
+ * the plugins are valid `output` descriptors and resolve through `asDescriptor`. The
+ * returned result exposes a typed lazy selector per plugin format.
+ */
+export declare const createColor: <const P extends ReadonlyArray<ColorFormatPlugin>>(config: CreateColorConfig<P>) => CustomColor<P>;
+/**
+ * `color(input, config?)`: the native colour input, alongside `m()`, `r()`, `i()`,
+ * `f()`. Parses + normalizes `input` to OKLCH and resolves it with the default
+ * config (override per call via `config`). Mirrors how `m()` wraps a measurement.
+ *
+ * It is `createColor({ formats: [] })` at defaults: the module-level instance is just
+ * the factory with no custom plugins, so the default and the factory share one
+ * construction path. Typed as the bare `(input, config?) => ResolvedColor` surface.
+ */
+export declare const color: (input: ColorInput, config?: Partial<ColorConfig>) => ResolvedColor;
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/color/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/color/index.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,KAAK,EAQN,MAAM,QAAQ,CAAC;AAUhB,OAAO,EACL,YAAY,EACZ,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,KAAK,EACX,MAAM,WAAW,CAAC;AASnB,OAAO,KAAK,EAEV,WAAW,EACX,iBAAiB,EACjB,UAAU,EAIV,SAAS,EACT,UAAU,EAEV,aAAa,EACb,KAAK,EAGN,MAAM,SAAS,CAAC;AAEjB,cAAc,SAAS,CAAC;AAmPxB;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,OAAO,UAAU,GAAG,KAAK,KAAG,KAChC,CAAC;AAexB,uEAAuE;AACvE,eAAO,MAAM,UAAU,GAAI,OAAO,KAAK,KAAG,KAKzC,CAAC;AAeF,OAAO,EACL,YAAY,EACZ,KAAK,oBAAoB,EACzB,gBAAgB,EAChB,KAAK,KAAK,GACX,CAAC;AA2WF;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,CAAC,SAAS,UAAU,GAAG,UAAU,EACvD,OAAO,KAAK,EACZ,KAAK,WAAW,KACf,aAAa,CAAC,CAAC,CAA+C,CAAC;AAElE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,EAI5C,CAAC;AAEF,uCAAuC;AACvC,eAAO,MAAM,kBAAkB,EAAE,WAKhC,CAAC;AAaF,2EAA2E;AAC3E,KAAK,YAAY,CAAC,CAAC,SAAS,aAAa,CAAC,iBAAiB,CAAC,IAC1D,CAAC,CAAC,MAAM,CAAC,CAAC,QAAQ,CAAC,CAAC;AAEtB;;;;;GAKG;AACH,KAAK,mBAAmB,CAAC,CAAC,SAAS,aAAa,CAAC,iBAAiB,CAAC,IACjE,aAAa,GAAG;IACd,QAAQ,EAAE,CAAC,IAAI,YAAY,CAAC,CAAC,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC;CAClD,CAAC;AAEJ,kFAAkF;AAClF,MAAM,WAAW,WAAW,CAC1B,CAAC,SAAS,aAAa,CAAC,iBAAiB,CAAC;IAE1C,CACE,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,GAC5B,mBAAmB,CAAC,CAAC,CAAC,CAAC;IAC1B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,QAAQ,CACxB,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAC7C,CAAC;CACH;AAED,yDAAyD;AACzD,MAAM,WAAW,iBAAiB,CAChC,CAAC,SAAS,aAAa,CAAC,iBAAiB,CAAC;IAE1C,yEAAyE;IACzE,OAAO,EAAE,CAAC,CAAC;CACZ;AAED;;;;;GAKG;AACH,eAAO,MAAM,WAAW,GACtB,KAAK,CAAC,CAAC,SAAS,aAAa,CAAC,iBAAiB,CAAC,EAEhD,QAAQ,iBAAiB,CAAC,CAAC,CAAC,KAC3B,WAAW,CAAC,CAAC,CA6Bf,CAAC;AAEF;;;;;;;;GAQG;AACH,eAAO,MAAM,KAAK,EAAE,CAClB,KAAK,EAAE,UAAU,EACjB,MAAM,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,KAC1B,aAA4C,CAAC"}