@konce-pt/color 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 konce.pt
+
+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/README.md

@@ -0,0 +1,68 @@
+<p align="center">
+  <img src="https://ui.konce.pt/images/koncept_ui_lib.png" alt="Koncept UI — Angular component library" width="100%" />
+</p>
+
+# @konce-pt/color
+
+Rachunek barw [Koncept UI](https://gitlab.com/konce-pt/koncept-ui): konwersje sRGB ↔ OKLab ↔ OKLCH,
+mieszanie po kole odcieni, sprowadzanie barwy do gamutu sRGB oraz kontrast w dwóch miarach —
+WCAG 2.1 i APCA. Czysty TypeScript, **zero zależności runtime**, bez wiązania z frameworkiem.
+
+Paleta biblioteki jest zapisana w OKLCH i przechodzi przez build **verbatim**, bez transformacji
+kolorów. Żeby cokolwiek z tymi wartościami policzyć — wymieszać dwie barwy, wyprowadzić rampę
+z jednego ziarna, sprawdzić czy napis na tle da się przeczytać — potrzebny jest model, w którym
+jasność znaczy jasność. Tym modelem jest OKLab i to jest ta paczka.
+
+Zwykle nie instalujesz jej samodzielnie: używa jej `KptBackdrop` z `@konce-pt/angular`
+i z `@konce-pt/react`. Sięgnij po nią wprost, gdy liczysz barwy po swojej stronie.
+
+```bash
+npm i @konce-pt/color
+```
+
+```ts
+import { clampToGamut, formatOklch, parseOklch, apcaLc, parseHexColor } from '@konce-pt/color';
+
+// Odcień marki przeniesiony na tę samą jasność co token biblioteki.
+const token = parseOklch('oklch(0.546 0.190 255)');
+const brand = { ...token, h: 152 };
+
+formatOklch(clampToGamut(brand)); // 'oklch(0.546 0.161 152)' — nasycenie zbite do gamutu sRGB
+
+// Czy biały napis na tym tle da się przeczytać? |Lc| 75 to próg tekstu podstawowego.
+apcaLc(parseHexColor('#ffffff'), parseHexColor('#3b82f6')); // -66.4 → za mało
+```
+
+## Dlaczego po kole, a nie po prostej
+
+Interpolacja w sRGB miesza wartości po gammie i prowadzi przejście przez błoto. Prostokątny OKLab
+naprawia jasność, ale dla odcieni leżących naprzeciwko siebie przecina oś achromatyczną: w połowie
+przejścia z niebieskiego w żółty zostaje szarość dokładnie tam, gdzie mieszanka ma świecić
+najmocniej. `mixOklch` idzie krótszym łukiem koła z zachowanym nasyceniem, a przystanek bez
+nasycenia przejmuje odcień sąsiada — inaczej `atan2` na zerowej chromie zwraca kąt przypadkowy
+i barwa szarpie.
+
+Z tego samego powodu `clampToGamut` obniża **samo nasycenie**, zamiast przycinać składowe RGB:
+przycięta po kanałach barwa marki potrafi zmienić odcień o kilkanaście stopni, czyli przestać być
+tą barwą.
+
+## Dwie miary kontrastu
+
+`contrastRatio` to WCAG 2.1 — symetryczna liczba 1–21, progi 4.5 (tekst) i 3 (tekst duży,
+elementy interfejsu). `apcaLc` to APCA: wartość ze znakiem, gdzie znak niesie biegunowość
+(dodatni — treść ciemna na jasnym tle), a kolejność argumentów **ma** znaczenie, bo ta sama para
+barw czyta się inaczej w każdą stronę. Progi |Lc|: 75 tekst podstawowy, 60 tekst większy,
+45 elementy interfejsu.
+
+Pełny opis: [`llms.txt`](https://ui.konce.pt/llms/color/llms.txt) (EN)
+i [`llms-pl.txt`](https://ui.konce.pt/llms/color/llms-pl.txt) (PL).
+
+## Testy
+
+```bash
+pnpm --filter @konce-pt/color exec node --test "src/**/*.test.ts"
+```
+
+## Licencja
+
+MIT © [konce.pt](https://konce.pt)

package/dist/contrast.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Kontrast: ile światła wychodzi z barwy i czy para barw nadaje się na tekst.
+ *
+ * To nie jest ta sama wielkość co jasność OKLab. OKLab opisuje, jak jasno barwa *wygląda*;
+ * tutaj liczy się, ile z niej wychodzi światła — i tylko na tym stoi rachunek kontrastu.
+ */
+import type { KptRgb } from './srgb.ts';
+/** Jasność względna wg WCAG (0 = czerń, 1 = biel). */
+export declare function relativeLuminance(rgb: KptRgb): number;
+/**
+ * Czy na tej powierzchni czytelniejsza jest treść ciemna.
+ *
+ * Sekcja z własnym tłem przestaje być powierzchnią strony, więc `--kpt-color-on-surface` opisuje
+ * już nie to tło, tylko sąsiada. Bez tego rachunku treść w sekcji z ciemnym tłem w motywie jasnym
+ * wychodzi czarna na czarnym.
+ */
+export declare function prefersDarkContent(surface: KptRgb): boolean;
+/**
+ * Kontrast wg WCAG 2.1 — liczba od 1 (te same barwy) do 21 (czerń na bieli).
+ *
+ * Progi ze specyfikacji: 4.5 dla tekstu, 3 dla tekstu dużego i dla elementów interfejsu.
+ * Kolejność argumentów nie ma znaczenia, bo wzór jest symetryczny.
+ */
+export declare function contrastRatio(a: KptRgb, b: KptRgb): number;
+/**
+ * Kontrast APCA (Lc) — wartość ze znakiem w zakresie mniej więcej −108…+106.
+ *
+ * Znak niesie biegunowość: dodatni to treść ciemna na jasnym tle, ujemny odwrotnie. Poziomy
+ * z roboczych wytycznych: |Lc| 75 dla tekstu podstawowego, 60 dla tekstu większego, 45 dla
+ * elementów interfejsu i tekstu wyłączonego.
+ *
+ * W odróżnieniu od WCAG 2.1 APCA uwzględnia biegunowość i rozmiar, więc para barw daje dwa różne
+ * wyniki zależnie od tego, która jest tłem — dlatego kolejność argumentów **ma** tu znaczenie.
+ * Poniżej `deltaYmin` zwraca 0 zamiast szumu numerycznego.
+ */
+export declare function apcaLc(text: KptRgb, background: KptRgb): number;

package/dist/contrast.js

@@ -0,0 +1,81 @@
+/**
+ * Kontrast: ile światła wychodzi z barwy i czy para barw nadaje się na tekst.
+ *
+ * To nie jest ta sama wielkość co jasność OKLab. OKLab opisuje, jak jasno barwa *wygląda*;
+ * tutaj liczy się, ile z niej wychodzi światła — i tylko na tym stoi rachunek kontrastu.
+ */
+import { toLinear } from "./srgb.js";
+/** Jasność względna wg WCAG (0 = czerń, 1 = biel). */
+export function relativeLuminance(rgb) {
+    return 0.2126 * toLinear(rgb.r) + 0.7152 * toLinear(rgb.g) + 0.0722 * toLinear(rgb.b);
+}
+/** Próg WCAG na wybór treści ciemnej albo jasnej — powyżej niego ciemna wygrywa kontrastem. */
+const CONTENT_THRESHOLD = 0.179;
+/**
+ * Czy na tej powierzchni czytelniejsza jest treść ciemna.
+ *
+ * Sekcja z własnym tłem przestaje być powierzchnią strony, więc `--kpt-color-on-surface` opisuje
+ * już nie to tło, tylko sąsiada. Bez tego rachunku treść w sekcji z ciemnym tłem w motywie jasnym
+ * wychodzi czarna na czarnym.
+ */
+export function prefersDarkContent(surface) {
+    return relativeLuminance(surface) > CONTENT_THRESHOLD;
+}
+/**
+ * Kontrast wg WCAG 2.1 — liczba od 1 (te same barwy) do 21 (czerń na bieli).
+ *
+ * Progi ze specyfikacji: 4.5 dla tekstu, 3 dla tekstu dużego i dla elementów interfejsu.
+ * Kolejność argumentów nie ma znaczenia, bo wzór jest symetryczny.
+ */
+export function contrastRatio(a, b) {
+    const la = relativeLuminance(a);
+    const lb = relativeLuminance(b);
+    const lighter = Math.max(la, lb);
+    const darker = Math.min(la, lb);
+    return (lighter + 0.05) / (darker + 0.05);
+}
+// Stałe APCA-W3 0.1.9 (G-4g), z publicznej specyfikacji. Nie ma sensu ich rozdzielać na nazwane
+// zmienne per rodzaj — działają wyłącznie jako komplet i tylko w tym jednym wzorze.
+const APCA_TRC = 2.4;
+const APCA_BLACK_THRESHOLD = 0.022;
+const APCA_BLACK_CLAMP = 1.414;
+const APCA_DELTA_Y_MIN = 0.0005;
+const APCA_LO_CLIP = 0.1;
+const APCA_SCALE = 1.14;
+const APCA_LO_OFFSET = 0.027;
+const APCA_NORM_BG = 0.56;
+const APCA_NORM_TXT = 0.57;
+const APCA_REV_TXT = 0.62;
+const APCA_REV_BG = 0.65;
+/** Luminancja APCA — inne współczynniki i inna krzywa niż WCAG, więc osobny rachunek. */
+const apcaY = (rgb) => {
+    const y = (rgb.r / 255) ** APCA_TRC * 0.2126729 +
+        (rgb.g / 255) ** APCA_TRC * 0.7151522 +
+        (rgb.b / 255) ** APCA_TRC * 0.072175;
+    // Miękkie przycięcie czerni: poniżej progu oko przestaje rozróżniać, a wzór bez tego
+    // zawyżałby kontrast ciemnych par.
+    return y < APCA_BLACK_THRESHOLD ? y + (APCA_BLACK_THRESHOLD - y) ** APCA_BLACK_CLAMP : y;
+};
+/**
+ * Kontrast APCA (Lc) — wartość ze znakiem w zakresie mniej więcej −108…+106.
+ *
+ * Znak niesie biegunowość: dodatni to treść ciemna na jasnym tle, ujemny odwrotnie. Poziomy
+ * z roboczych wytycznych: |Lc| 75 dla tekstu podstawowego, 60 dla tekstu większego, 45 dla
+ * elementów interfejsu i tekstu wyłączonego.
+ *
+ * W odróżnieniu od WCAG 2.1 APCA uwzględnia biegunowość i rozmiar, więc para barw daje dwa różne
+ * wyniki zależnie od tego, która jest tłem — dlatego kolejność argumentów **ma** tu znaczenie.
+ * Poniżej `deltaYmin` zwraca 0 zamiast szumu numerycznego.
+ */
+export function apcaLc(text, background) {
+    const yTxt = apcaY(text);
+    const yBg = apcaY(background);
+    if (Math.abs(yBg - yTxt) < APCA_DELTA_Y_MIN)
+        return 0;
+    if (yBg > yTxt) {
+        const sapc = (yBg ** APCA_NORM_BG - yTxt ** APCA_NORM_TXT) * APCA_SCALE;
+        return sapc < APCA_LO_CLIP ? 0 : (sapc - APCA_LO_OFFSET) * 100;
+    }
+    const sapc = (yBg ** APCA_REV_BG - yTxt ** APCA_REV_TXT) * APCA_SCALE;
+    return sapc > -APCA_LO_CLIP ? 0 : (sapc + APCA_LO_OFFSET) * 100;
+}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type { KptRgb } from './srgb.ts';
+export { clamp255, parseHexColor, readCssColor, toGamma, toHexColor, toLinear } from './srgb.ts';
+export type { KptOklab } from './oklab.ts';
+export { adaptLightness, adaptToSurface, mixOklch, oklabToLinearSrgb, oklabToSrgb, shiftHue, srgbToOklab, ACHROMATIC, TAU, } from './oklab.ts';
+export type { KptOklch } from './oklch.ts';
+export { clampToGamut, formatOklch, isInGamut, oklabToOklch, oklchToOklab, oklchToSrgb, parseOklch, srgbToOklch, } from './oklch.ts';
+export { apcaLc, contrastRatio, prefersDarkContent, relativeLuminance } from './contrast.ts';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { clamp255, parseHexColor, readCssColor, toGamma, toHexColor, toLinear } from "./srgb.js";
+export { adaptLightness, adaptToSurface, mixOklch, oklabToLinearSrgb, oklabToSrgb, shiftHue, srgbToOklab, ACHROMATIC, TAU, } from "./oklab.js";
+export { clampToGamut, formatOklch, isInGamut, oklabToOklch, oklchToOklab, oklchToSrgb, parseOklch, srgbToOklch, } from "./oklch.js";
+export { apcaLc, contrastRatio, prefersDarkContent, relativeLuminance } from "./contrast.js";

package/dist/oklab.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Model OKLab Björna Ottossona: konwersje sRGB ↔ OKLab, mieszanie po współrzędnych biegunowych
+ * i przenoszenie barwy na inną powierzchnię.
+ *
+ * Interpolacja sRGB prowadzi mieszankę przez błoto, bo miesza wartości po gammie. Prostokątny
+ * OKLab naprawia jasność, ale dla odcieni leżących naprzeciwko siebie i tak przecina oś
+ * achromatyczną: w połowie przejścia z niebieskiego w żółty zostaje szarość dokładnie tam, gdzie
+ * mieszanka ma świecić najmocniej. Dopiero rozbicie na jasność, nasycenie i kąt odcienia pozwala
+ * obejść koło dookoła z zachowanym nasyceniem.
+ */
+import type { KptRgb } from './srgb.ts';
+/** Kolor w OKLab: jasność `l` oraz para składowych chromatycznych. */
+export interface KptOklab {
+    l: number;
+    a: number;
+    b: number;
+}
+export declare const TAU: number;
+export declare function srgbToOklab(rgb: KptRgb): KptOklab;
+/**
+ * OKLab na liniowe sRGB **bez przycinania** — składowa poza zakresem 0–1 oznacza barwę spoza
+ * gamutu sRGB. Na tym stoi `clampToGamut`, bo `oklabToSrgb` przycina po cichu i po nim nie da się
+ * już odróżnić barwy leżącej dokładnie na krawędzi od takiej, która wypadła daleko poza nią.
+ */
+export declare function oklabToLinearSrgb(lab: KptOklab): {
+    r: number;
+    g: number;
+    b: number;
+};
+export declare function oklabToSrgb(lab: KptOklab): KptRgb;
+/**
+ * Obrót odcienia o zadany kąt (stopnie) przy zachowanej jasności i nasyceniu.
+ *
+ * Stąd biorą się domyślne barwy towarzyszące: paleta biblioteki jest neutralna, więc zamiast
+ * sięgać po tokeny statusowe (`info`, `success`) do celów dekoracyjnych, barwy pochodne
+ * wyprowadzamy z koloru wiodącego. Dekoracja zostaje w kolorach aplikacji niezależnie od motywu.
+ */
+export declare function shiftHue(rgb: KptRgb, degrees: number): KptRgb;
+/** Poniżej tego nasycenia odcień przestaje cokolwiek znaczyć — szarość nie ma kąta. */
+export declare const ACHROMATIC = 0.0001;
+/**
+ * Kolor na zamkniętej rampie `colors` w miejscu `position`.
+ *
+ * Rampa jest cykliczna: ostatni przystanek wraca do pierwszego, bo barwy przesuwają się bez końca
+ * i szew w środku byłby widoczny. `position` poza zakresem 0–1 zawija się, więc wywołujący nie
+ * musi pilnować rosnącego czasu.
+ *
+ * Odcień idzie krótszym łukiem koła. Przystanek bez nasycenia przejmuje odcień sąsiada — inaczej
+ * przejście do szarości i z powrotem szarpnęłoby barwą, bo `atan2` na zerowym nasyceniu zwraca
+ * kąt przypadkowy.
+ */
+export declare function mixOklch(colors: readonly KptRgb[], position: number): KptRgb;
+/**
+ * Jasność przeniesiona na powierzchnię bieżącego motywu z zachowaniem odległości od niej.
+ *
+ * Barwa zapisana na biel odsuwa się od niej o `d`; na ciemnej powierzchni ma się odsunąć o to samo
+ * `d`, tyle że w drugą stronę — bo tam właśnie jest miejsce. Stąd czerń na bieli staje się bielą
+ * na ciemnym tle, a biel staje się dokładnie powierzchnią. Barwa w połowie skali zostaje mniej
+ * więcej tam, gdzie była, i dalej odcina się od tła.
+ *
+ * Na jasnej powierzchni wychodzi tożsamość: `1 - (1 - L)` to `L`.
+ */
+export declare function adaptLightness(lightness: number, surface: number): number;
+/**
+ * Barwa przeniesiona na zadaną powierzchnię. Rusza wyłącznie jasność — odcień i nasycenie zostają,
+ * więc barwa marki nie zmienia się w inną barwę, tylko dobiera jasność do tła.
+ */
+export declare function adaptToSurface(rgb: KptRgb, surface: KptRgb): KptRgb;

package/dist/oklab.js

@@ -0,0 +1,138 @@
+/**
+ * Model OKLab Björna Ottossona: konwersje sRGB ↔ OKLab, mieszanie po współrzędnych biegunowych
+ * i przenoszenie barwy na inną powierzchnię.
+ *
+ * Interpolacja sRGB prowadzi mieszankę przez błoto, bo miesza wartości po gammie. Prostokątny
+ * OKLab naprawia jasność, ale dla odcieni leżących naprzeciwko siebie i tak przecina oś
+ * achromatyczną: w połowie przejścia z niebieskiego w żółty zostaje szarość dokładnie tam, gdzie
+ * mieszanka ma świecić najmocniej. Dopiero rozbicie na jasność, nasycenie i kąt odcienia pozwala
+ * obejść koło dookoła z zachowanym nasyceniem.
+ */
+import { toGamma, toLinear } from "./srgb.js";
+export const TAU = Math.PI * 2;
+export function srgbToOklab(rgb) {
+    const r = toLinear(rgb.r);
+    const g = toLinear(rgb.g);
+    const b = toLinear(rgb.b);
+    const l = Math.cbrt(0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b);
+    const m = Math.cbrt(0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b);
+    const s = Math.cbrt(0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b);
+    return {
+        l: 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s,
+        a: 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s,
+        b: 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s,
+    };
+}
+/**
+ * OKLab na liniowe sRGB **bez przycinania** — składowa poza zakresem 0–1 oznacza barwę spoza
+ * gamutu sRGB. Na tym stoi `clampToGamut`, bo `oklabToSrgb` przycina po cichu i po nim nie da się
+ * już odróżnić barwy leżącej dokładnie na krawędzi od takiej, która wypadła daleko poza nią.
+ */
+export function oklabToLinearSrgb(lab) {
+    const l = (lab.l + 0.3963377774 * lab.a + 0.2158037573 * lab.b) ** 3;
+    const m = (lab.l - 0.1055613458 * lab.a - 0.0638541728 * lab.b) ** 3;
+    const s = (lab.l - 0.0894841775 * lab.a - 1.291485548 * lab.b) ** 3;
+    return {
+        r: 4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+        g: -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+        b: -0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s,
+    };
+}
+export function oklabToSrgb(lab) {
+    const linear = oklabToLinearSrgb(lab);
+    return { r: toGamma(linear.r), g: toGamma(linear.g), b: toGamma(linear.b) };
+}
+/**
+ * Obrót odcienia o zadany kąt (stopnie) przy zachowanej jasności i nasyceniu.
+ *
+ * Stąd biorą się domyślne barwy towarzyszące: paleta biblioteki jest neutralna, więc zamiast
+ * sięgać po tokeny statusowe (`info`, `success`) do celów dekoracyjnych, barwy pochodne
+ * wyprowadzamy z koloru wiodącego. Dekoracja zostaje w kolorach aplikacji niezależnie od motywu.
+ */
+export function shiftHue(rgb, degrees) {
+    const lab = srgbToOklab(rgb);
+    const chroma = Math.hypot(lab.a, lab.b);
+    const hue = Math.atan2(lab.b, lab.a) + (degrees / 360) * TAU;
+    return oklabToSrgb({ l: lab.l, a: Math.cos(hue) * chroma, b: Math.sin(hue) * chroma });
+}
+/** Poniżej tego nasycenia odcień przestaje cokolwiek znaczyć — szarość nie ma kąta. */
+export const ACHROMATIC = 1e-4;
+/**
+ * Kolor na zamkniętej rampie `colors` w miejscu `position`.
+ *
+ * Rampa jest cykliczna: ostatni przystanek wraca do pierwszego, bo barwy przesuwają się bez końca
+ * i szew w środku byłby widoczny. `position` poza zakresem 0–1 zawija się, więc wywołujący nie
+ * musi pilnować rosnącego czasu.
+ *
+ * Odcień idzie krótszym łukiem koła. Przystanek bez nasycenia przejmuje odcień sąsiada — inaczej
+ * przejście do szarości i z powrotem szarpnęłoby barwą, bo `atan2` na zerowym nasyceniu zwraca
+ * kąt przypadkowy.
+ */
+export function mixOklch(colors, position) {
+    if (colors.length === 0)
+        return { r: 0, g: 0, b: 0 };
+    if (colors.length === 1)
+        return colors[0];
+    const wrapped = position - Math.floor(position);
+    const scaled = wrapped * colors.length;
+    const index = Math.min(Math.floor(scaled), colors.length - 1);
+    const blend = scaled - index;
+    const from = srgbToOklab(colors[index]);
+    const to = srgbToOklab(colors[(index + 1) % colors.length]);
+    const fromChroma = Math.hypot(from.a, from.b);
+    const toChroma = Math.hypot(to.a, to.b);
+    const chroma = fromChroma + (toChroma - fromChroma) * blend;
+    let hue;
+    if (fromChroma < ACHROMATIC && toChroma < ACHROMATIC) {
+        hue = 0;
+    }
+    else if (fromChroma < ACHROMATIC) {
+        hue = Math.atan2(to.b, to.a);
+    }
+    else if (toChroma < ACHROMATIC) {
+        hue = Math.atan2(from.b, from.a);
+    }
+    else {
+        const start = Math.atan2(from.b, from.a);
+        const end = Math.atan2(to.b, to.a);
+        // Krótszy łuk: różnicę sprowadzamy do (-π, π], zamiast iść dookoła przez pół koła.
+        const delta = ((end - start + Math.PI * 3) % TAU) - Math.PI;
+        hue = start + delta * blend;
+    }
+    return oklabToSrgb({
+        l: from.l + (to.l - from.l) * blend,
+        a: Math.cos(hue) * chroma,
+        b: Math.sin(hue) * chroma,
+    });
+}
+/**
+ * Jasność powierzchni, względem której zapisano barwę. Biblioteka trzyma motyw jasny w `:root`,
+ * a ciemny jako nadpisanie, więc wartość wpisana do szablonu jest z założenia dobrana do jasnego —
+ * i to jest jedyne założenie, jakie robi adaptacja.
+ */
+const REFERENCE_SURFACE = 1;
+/** Powyżej tej jasności powierzchnię uznajemy za jasną, poniżej za ciemną. */
+const SURFACE_MIDPOINT = 0.5;
+const clamp01 = (value) => (value < 0 ? 0 : value > 1 ? 1 : value);
+/**
+ * Jasność przeniesiona na powierzchnię bieżącego motywu z zachowaniem odległości od niej.
+ *
+ * Barwa zapisana na biel odsuwa się od niej o `d`; na ciemnej powierzchni ma się odsunąć o to samo
+ * `d`, tyle że w drugą stronę — bo tam właśnie jest miejsce. Stąd czerń na bieli staje się bielą
+ * na ciemnym tle, a biel staje się dokładnie powierzchnią. Barwa w połowie skali zostaje mniej
+ * więcej tam, gdzie była, i dalej odcina się od tła.
+ *
+ * Na jasnej powierzchni wychodzi tożsamość: `1 - (1 - L)` to `L`.
+ */
+export function adaptLightness(lightness, surface) {
+    const distance = Math.abs(REFERENCE_SURFACE - lightness);
+    return clamp01(surface > SURFACE_MIDPOINT ? REFERENCE_SURFACE - distance : surface + distance);
+}
+/**
+ * Barwa przeniesiona na zadaną powierzchnię. Rusza wyłącznie jasność — odcień i nasycenie zostają,
+ * więc barwa marki nie zmienia się w inną barwę, tylko dobiera jasność do tła.
+ */
+export function adaptToSurface(rgb, surface) {
+    const lab = srgbToOklab(rgb);
+    return oklabToSrgb({ ...lab, l: adaptLightness(lab.l, srgbToOklab(surface).l) });
+}

package/dist/oklch.d.ts

@@ -0,0 +1,50 @@
+/**
+ * OKLCH — ten sam model co OKLab, tylko we współrzędnych biegunowych: jasność, nasycenie, kąt
+ * odcienia. W tej postaci tokeny biblioteki są zapisane i w tej postaci mają wyjść z edytora,
+ * więc tu żyje parser i serializator zapisu `oklch()`.
+ *
+ * Dlaczego własny parser, skoro jest `readCssColor`: tamten maluje piksel na canvasie, więc
+ * wymaga DOM i gubi wszystko poza 8 bitami na kanał. Generator palety i emitery motywu pracują
+ * w Node (build, testy) i muszą trzymać pełną precyzję — inaczej rampa liczona z ziarna wracałaby
+ * z zaokrągleniem do sRGB przy każdym kroku.
+ */
+import type { KptOklab } from './oklab.ts';
+import type { KptRgb } from './srgb.ts';
+/** Kolor w OKLCH: jasność 0–1, nasycenie od 0, kąt odcienia w stopniach 0–360, alfa 0–1. */
+export interface KptOklch {
+    l: number;
+    c: number;
+    h: number;
+    alpha?: number;
+}
+export declare function oklabToOklch(lab: KptOklab): KptOklch;
+export declare function oklchToOklab(color: KptOklch): KptOklab;
+export declare const srgbToOklch: (rgb: KptRgb) => KptOklch;
+export declare const oklchToSrgb: (color: KptOklch) => KptRgb;
+/** Czy barwa mieści się w sRGB. Liczone na składowych liniowych, przed przycięciem. */
+export declare function isInGamut(color: KptOklch): boolean;
+/**
+ * Barwa sprowadzona do gamutu sRGB przez obniżenie samego nasycenia.
+ *
+ * Jasność i odcień zostają nietknięte, bo to one niosą tożsamość barwy: przyciętej po składowych
+ * RGB barwie marki potrafi się przesunąć odcień o kilkanaście stopni, a to już jest inny kolor.
+ * Obniżenie nasycenia daje najbliższą barwę, którą ekran faktycznie potrafi pokazać.
+ *
+ * Połowienie przedziału, nie wzór: granica gamutu w OKLCH jest kawałkami gładka i nie ma
+ * zamkniętej postaci, więc dwadzieścia kroków jest i krótsze do napisania, i pewniejsze.
+ */
+export declare function clampToGamut(color: KptOklch): KptOklch;
+/**
+ * Zapis `oklch(L C H)` albo `oklch(L C H / A)` na składowe. Zwraca `null` na wszystkim innym —
+ * w tym na `none`, `color-mix()` i na łańcuchu `var()`, bo tych bez DOM i bez kontekstu kaskady
+ * nie da się uczciwie rozwiązać, a zgadywanie skończyłoby się kolorem, którego nikt nie wpisał.
+ */
+export declare function parseOklch(value: string): KptOklch | null;
+/**
+ * Składowe na zapis `oklch()` w formacie, w jakim tokeny są zapisane w źródłach: jasność
+ * i nasycenie na trzech miejscach, odcień całkowity, alfa tylko gdy mniejsza od 1.
+ *
+ * Trzy miejsca to nie ozdoba — przy dwóch sąsiednie stopnie rampy neutralnej zaczynają się
+ * zlewać w tę samą wartość.
+ */
+export declare function formatOklch(color: KptOklch): string;

package/dist/oklch.js

@@ -0,0 +1,104 @@
+/**
+ * OKLCH — ten sam model co OKLab, tylko we współrzędnych biegunowych: jasność, nasycenie, kąt
+ * odcienia. W tej postaci tokeny biblioteki są zapisane i w tej postaci mają wyjść z edytora,
+ * więc tu żyje parser i serializator zapisu `oklch()`.
+ *
+ * Dlaczego własny parser, skoro jest `readCssColor`: tamten maluje piksel na canvasie, więc
+ * wymaga DOM i gubi wszystko poza 8 bitami na kanał. Generator palety i emitery motywu pracują
+ * w Node (build, testy) i muszą trzymać pełną precyzję — inaczej rampa liczona z ziarna wracałaby
+ * z zaokrągleniem do sRGB przy każdym kroku.
+ */
+import { oklabToLinearSrgb, srgbToOklab, oklabToSrgb, TAU } from "./oklab.js";
+const DEG = 360 / TAU;
+export function oklabToOklch(lab) {
+    const c = Math.hypot(lab.a, lab.b);
+    // Szarość nie ma kąta — `atan2` zwróciłby dla niej wartość przypadkową, a stąd bierze się
+    // szarpnięcie barwą przy przejściu przez oś achromatyczną. Zero jest tu umowne, ale stabilne.
+    const h = c === 0 ? 0 : (Math.atan2(lab.b, lab.a) * DEG + 360) % 360;
+    return { l: lab.l, c, h };
+}
+export function oklchToOklab(color) {
+    const radians = (color.h / DEG) % TAU;
+    return { l: color.l, a: Math.cos(radians) * color.c, b: Math.sin(radians) * color.c };
+}
+export const srgbToOklch = (rgb) => oklabToOklch(srgbToOklab(rgb));
+export const oklchToSrgb = (color) => oklabToSrgb(oklchToOklab(color));
+/** Margines na błąd zaokrągleń — bez niego barwa dokładnie na krawędzi gamutu bywa odrzucana. */
+const GAMUT_EPSILON = 1e-4;
+/** Czy barwa mieści się w sRGB. Liczone na składowych liniowych, przed przycięciem. */
+export function isInGamut(color) {
+    const { r, g, b } = oklabToLinearSrgb(oklchToOklab(color));
+    const min = Math.min(r, g, b);
+    const max = Math.max(r, g, b);
+    return min >= -GAMUT_EPSILON && max <= 1 + GAMUT_EPSILON;
+}
+/** Poniżej tej różnicy nasycenia dalsze połowienie przedziału nic już nie zmienia w wyniku. */
+const GAMUT_PRECISION = 1e-4;
+/**
+ * Barwa sprowadzona do gamutu sRGB przez obniżenie samego nasycenia.
+ *
+ * Jasność i odcień zostają nietknięte, bo to one niosą tożsamość barwy: przyciętej po składowych
+ * RGB barwie marki potrafi się przesunąć odcień o kilkanaście stopni, a to już jest inny kolor.
+ * Obniżenie nasycenia daje najbliższą barwę, którą ekran faktycznie potrafi pokazać.
+ *
+ * Połowienie przedziału, nie wzór: granica gamutu w OKLCH jest kawałkami gładka i nie ma
+ * zamkniętej postaci, więc dwadzieścia kroków jest i krótsze do napisania, i pewniejsze.
+ */
+export function clampToGamut(color) {
+    if (isInGamut(color))
+        return color;
+    let low = 0;
+    let high = color.c;
+    while (high - low > GAMUT_PRECISION) {
+        const mid = (low + high) / 2;
+        if (isInGamut({ ...color, c: mid }))
+            low = mid;
+        else
+            high = mid;
+    }
+    return { ...color, c: low };
+}
+const NUMBER = String.raw `[+-]?(?:\d*\.\d+|\d+\.?)(?:e[+-]?\d+)?`;
+const OKLCH_RE = new RegExp(String.raw `^oklch\(\s*(${NUMBER})(%?)\s+(${NUMBER})(%?)\s+(${NUMBER})(?:deg)?` +
+    String.raw `(?:\s*/\s*(${NUMBER})(%?))?\s*\)$`, 'i');
+/** Procent w miejscu liczby: jasność i alfa liczą 100% = 1, nasycenie 100% = 0.4 (jak w CSS). */
+const scaled = (value, percent, fullScale) => percent ? (Number.parseFloat(value) / 100) * fullScale : Number.parseFloat(value);
+/**
+ * Zapis `oklch(L C H)` albo `oklch(L C H / A)` na składowe. Zwraca `null` na wszystkim innym —
+ * w tym na `none`, `color-mix()` i na łańcuchu `var()`, bo tych bez DOM i bez kontekstu kaskady
+ * nie da się uczciwie rozwiązać, a zgadywanie skończyłoby się kolorem, którego nikt nie wpisał.
+ */
+export function parseOklch(value) {
+    const match = OKLCH_RE.exec(value.trim());
+    if (!match)
+        return null;
+    const [, l, lPercent, c, cPercent, h, alpha, alphaPercent] = match;
+    const parsed = {
+        l: scaled(l, lPercent, 1),
+        c: scaled(c, cPercent, 0.4),
+        h: ((Number.parseFloat(h) % 360) + 360) % 360,
+    };
+    if (alpha !== undefined)
+        parsed.alpha = scaled(alpha, alphaPercent, 1);
+    return Number.isFinite(parsed.l) && Number.isFinite(parsed.c) && Number.isFinite(parsed.h) ? parsed : null;
+}
+/** Ucina zera na końcu części dziesiętnej: `0.500` → `0.5`, `1.000` → `1`. */
+const trim = (value, digits) => value.toFixed(digits).replace(/\.?0+$/, '') || '0';
+/**
+ * Składowe na zapis `oklch()` w formacie, w jakim tokeny są zapisane w źródłach: jasność
+ * i nasycenie na trzech miejscach, odcień całkowity, alfa tylko gdy mniejsza od 1.
+ *
+ * Trzy miejsca to nie ozdoba — przy dwóch sąsiednie stopnie rampy neutralnej zaczynają się
+ * zlewać w tę samą wartość.
+ */
+export function formatOklch(color) {
+    const chroma = color.c.toFixed(3);
+    // Barwa, której nasycenie zaokrągla się do zera, jest na papierze achromatyczna — a odcień
+    // achromatycznej barwy nie znaczy nic. Biel policzona z `#ffffff` niesie chromę rzędu 1e-8
+    // i wraz z nią jakiś kąt, więc bez tego dwie identyczne biele z różnych źródeł zapisałyby się
+    // różnie (`oklch(1.000 0.000 90)` i `oklch(1.000 0.000 0)`) i robiły fałszywy diff w motywie.
+    const hue = chroma === '0.000' ? 0 : Math.round(color.h);
+    const base = `${color.l.toFixed(3)} ${chroma} ${hue}`;
+    const alpha = color.alpha;
+    return alpha === undefined || alpha >= 1 ? `oklch(${base})` : `oklch(${base} / ${trim(alpha, 4)})`;
+}

package/dist/srgb.d.ts

@@ -0,0 +1,42 @@
+/**
+ * sRGB: składowe, zapis heksadecymalny i przejście przez gammę.
+ *
+ * To najniższa warstwa paczki — nic tu nie wie o OKLab ani o kontraście. Reszta modułów liczy
+ * na liniowych składowych (`toLinear`), bo zarówno macierze OKLab, jak i rachunek luminancji
+ * wymagają światła, a nie wartości po gammie.
+ */
+/** Kolor w sRGB, składowe 0–255. */
+export interface KptRgb {
+    r: number;
+    g: number;
+    b: number;
+}
+export declare const clamp255: (value: number) => number;
+/** Gamma sRGB → liniowo. */
+export declare const toLinear: (channel: number) => number;
+/** Liniowo → gamma sRGB. */
+export declare const toGamma: (value: number) => number;
+/**
+ * Zapis heksadecymalny (`#rgb` albo `#rrggbb`, z krzyżykiem lub bez) na składowe.
+ * Zwraca `null` na wszystkim innym — kolor przychodzi z wejścia komponentu albo z konfiguratora,
+ * więc śmieci są normalnym przypadkiem, a nie wyjątkiem.
+ */
+export declare function parseHexColor(hex: string): KptRgb | null;
+/**
+ * Dowolny zapis koloru CSS na składowe — także `oklch()`, `color-mix()` czy nazwa własna.
+ *
+ * Tokeny biblioteki są zapisane w OKLCH, a barwy trzeba czasem wymieszać, nie tylko podać dalej.
+ * Zamiast pisać własny parser każdej składni CSS, malujemy kolor na canvasie 1×1 i odczytujemy
+ * piksel: przeglądarka rozumie każdy zapis, który sama akceptuje, i nigdy nie rozejdzie się
+ * z tym, co widać na stronie.
+ *
+ * Zapis nieprawidłowy daje `null`, tak samo jak środowisko bez DOM — a bez DOM jest cały Node,
+ * więc emitery i testy muszą sobie radzić bez tej funkcji (od OKLCH jest `parseOklch`).
+ * `fillStyle` odrzuca nieprawidłową wartość po cichu, zostawiając poprzednią, więc sam odczyt
+ * piksela nie odróżniłby śmiecia od legalnej czerni — stąd dwa różne wartownicy: przy wartości
+ * nieprawidłowej każdy z nich zostaje na swoim miejscu i oba przebiegi dają inny wynik.
+ * Getter zwraca kolor już zserializowany, więc bramka nie potrzebuje odczytu piksela.
+ */
+export declare function readCssColor(value: string): KptRgb | null;
+/** Składowe na `#rrggbb`. */
+export declare function toHexColor(rgb: KptRgb): string;

package/dist/srgb.js

@@ -0,0 +1,84 @@
+/**
+ * sRGB: składowe, zapis heksadecymalny i przejście przez gammę.
+ *
+ * To najniższa warstwa paczki — nic tu nie wie o OKLab ani o kontraście. Reszta modułów liczy
+ * na liniowych składowych (`toLinear`), bo zarówno macierze OKLab, jak i rachunek luminancji
+ * wymagają światła, a nie wartości po gammie.
+ */
+export const clamp255 = (value) => (value < 0 ? 0 : value > 255 ? 255 : Math.round(value));
+/** Gamma sRGB → liniowo. */
+export const toLinear = (channel) => {
+    const value = channel / 255;
+    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
+};
+/** Liniowo → gamma sRGB. */
+export const toGamma = (value) => {
+    const encoded = value <= 0.0031308 ? 12.92 * value : 1.055 * value ** (1 / 2.4) - 0.055;
+    return clamp255(encoded * 255);
+};
+/**
+ * Zapis heksadecymalny (`#rgb` albo `#rrggbb`, z krzyżykiem lub bez) na składowe.
+ * Zwraca `null` na wszystkim innym — kolor przychodzi z wejścia komponentu albo z konfiguratora,
+ * więc śmieci są normalnym przypadkiem, a nie wyjątkiem.
+ */
+export function parseHexColor(hex) {
+    const value = hex.trim().replace(/^#/, '');
+    const full = value.length === 3 ? value.replace(/./g, (char) => char + char) : value;
+    if (!/^[0-9a-f]{6}$/i.test(full))
+        return null;
+    return {
+        r: Number.parseInt(full.slice(0, 2), 16),
+        g: Number.parseInt(full.slice(2, 4), 16),
+        b: Number.parseInt(full.slice(4, 6), 16),
+    };
+}
+/** Leniwy kontekst 1×1 — służy wyłącznie do pytania przeglądarki o znaczenie zapisu koloru. */
+let probe;
+/**
+ * Dowolny zapis koloru CSS na składowe — także `oklch()`, `color-mix()` czy nazwa własna.
+ *
+ * Tokeny biblioteki są zapisane w OKLCH, a barwy trzeba czasem wymieszać, nie tylko podać dalej.
+ * Zamiast pisać własny parser każdej składni CSS, malujemy kolor na canvasie 1×1 i odczytujemy
+ * piksel: przeglądarka rozumie każdy zapis, który sama akceptuje, i nigdy nie rozejdzie się
+ * z tym, co widać na stronie.
+ *
+ * Zapis nieprawidłowy daje `null`, tak samo jak środowisko bez DOM — a bez DOM jest cały Node,
+ * więc emitery i testy muszą sobie radzić bez tej funkcji (od OKLCH jest `parseOklch`).
+ * `fillStyle` odrzuca nieprawidłową wartość po cichu, zostawiając poprzednią, więc sam odczyt
+ * piksela nie odróżniłby śmiecia od legalnej czerni — stąd dwa różne wartownicy: przy wartości
+ * nieprawidłowej każdy z nich zostaje na swoim miejscu i oba przebiegi dają inny wynik.
+ * Getter zwraca kolor już zserializowany, więc bramka nie potrzebuje odczytu piksela.
+ */
+export function readCssColor(value) {
+    const direct = parseHexColor(value);
+    if (direct)
+        return direct;
+    if (typeof document === 'undefined')
+        return null;
+    if (probe === undefined) {
+        const canvas = document.createElement('canvas');
+        canvas.width = 1;
+        canvas.height = 1;
+        probe = canvas.getContext('2d', { willReadFrequently: true });
+    }
+    if (!probe)
+        return null;
+    probe.fillStyle = '#000000';
+    probe.fillStyle = value;
+    const first = probe.fillStyle;
+    probe.fillStyle = '#ffffff';
+    probe.fillStyle = value;
+    if (probe.fillStyle !== first)
+        return null;
+    // Sonda musi zaczynać od przezroczystości: barwa z kanałem alfa nałożyłaby się na poprzedni
+    // odczyt i wyszłaby mieszanka dwóch niezwiązanych ze sobą wywołań.
+    probe.clearRect(0, 0, 1, 1);
+    probe.fillRect(0, 0, 1, 1);
+    const [r, g, b] = probe.getImageData(0, 0, 1, 1).data;
+    return { r, g, b };
+}
+/** Składowe na `#rrggbb`. */
+export function toHexColor(rgb) {
+    const part = (value) => clamp255(value).toString(16).padStart(2, '0');
+    return `#${part(rgb.r)}${part(rgb.g)}${part(rgb.b)}`;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@konce-pt/color",
+  "version": "0.9.0",
+  "description": "Colour maths for Koncept UI — sRGB, OKLab and OKLCH conversions, hue-aware mixing, gamut mapping, WCAG and APCA contrast. Framework-free TypeScript, zero runtime dependencies.",
+  "license": "MIT",
+  "author": "konce.pt",
+  "homepage": "https://ui.konce.pt/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/konce-pt/koncept-ui.git",
+    "directory": "packages/color"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "color",
+    "colour",
+    "oklch",
+    "oklab",
+    "contrast",
+    "wcag",
+    "apca",
+    "gamut",
+    "design-system",
+    "koncept-ui",
+    "kpt"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "~6.0.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "node --test \"src/**/*.test.ts\"",
+    "clean": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\""
+  }
+}