@konce-pt/backdrop 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@konce-pt/backdrop",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Animated backdrop core for Koncept UI — canvas renderers plus the maths behind two effects: a density-ramped grid of squares and a flowing current of light with an OKLCH colour ramp. Framework-free TypeScript; the colour maths lives in @konce-pt/color.",
   "license": "MIT",
   "author": "konce.pt",
@@ -37,7 +37,7 @@
     }
   },
   "dependencies": {
-    "@konce-pt/color": "0.9.0"
+    "@konce-pt/color": "0.10.0"
   },
   "devDependencies": {
     "typescript": "~6.0.3"

package/dist/color.d.ts

@@ -1,101 +0,0 @@
-/**
- * Barwy wstęgi. Mieszanie idzie po współrzędnych biegunowych OKLab (czyli OKLCH), nie po
- * składowych sRGB ani nawet nie po prostokątnym OKLab.
- *
- * 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 — a takie są w rampie
- * wstęgi — i tak przecina oś achromatyczną: w połowie przejścia z niebieskiego w żółty zostaje
- * szarość dokładnie tam, gdzie wstęga świeci najmocniej. Dopiero rozbicie na jasność, nasycenie
- * i kąt odcienia pozwala obejść koło dookoła z zachowanym nasyceniem.
- *
- * Konwersje wg modelu OKLab Björna Ottossona.
- */
-/** Kolor w sRGB, składowe 0–255. */
-export interface KptRgb {
-    r: number;
-    g: number;
-    b: number;
-}
-/** Kolor w OKLab: jasność `l` oraz para składowych chromatycznych. */
-export interface KptOklab {
-    l: number;
-    a: number;
-    b: 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 wstęgi trzeba 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. `fillStyle` odrzuca taką
- * wartość po cichu, zostawiając poprzednią, więc sam odczyt piksela nie odróżniłby śmiecia od
- * legalnej czerni — stąd dwa różne wartowniki: 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;
-export declare function srgbToOklab(rgb: KptRgb): KptOklab;
-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 wstęgi: paleta biblioteki jest neutralna, więc zamiast sięgać
- * po tokeny statusowe (`info`, `success`) do celów dekoracyjnych, dwie towarzyszące barwy
- * wyprowadzamy z koloru wiodącego. Wstęga zostaje w kolorach aplikacji niezależnie od motywu.
- */
-export declare function shiftHue(rgb: KptRgb, degrees: number): KptRgb;
-/**
- * Kolor na zamkniętej rampie `colors` w miejscu `position`.
- *
- * Rampa jest cykliczna: ostatni przystanek wraca do pierwszego, bo barwy przesuwają się wzdłuż
- * wstęgi bez końca i szew w środku kadru 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;
-/**
- * Jasność względna wg WCAG (0 = czerń, 1 = biel).
- *
- * To nie to samo co jasność OKLab: OKLab opisuje, jak jasno barwa *wygląda*, a ta liczba mówi,
- * ile z niej wychodzi światła — i tylko na niej stoi rachunek kontrastu, którym rozstrzygamy,
- * czy na danym tle czytelniejszy jest napis ciemny czy jasny.
- */
-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;

package/dist/color.js

@@ -1,228 +0,0 @@
-/**
- * Barwy wstęgi. Mieszanie idzie po współrzędnych biegunowych OKLab (czyli OKLCH), nie po
- * składowych sRGB ani nawet nie po prostokątnym OKLab.
- *
- * 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 — a takie są w rampie
- * wstęgi — i tak przecina oś achromatyczną: w połowie przejścia z niebieskiego w żółty zostaje
- * szarość dokładnie tam, gdzie wstęga świeci najmocniej. Dopiero rozbicie na jasność, nasycenie
- * i kąt odcienia pozwala obejść koło dookoła z zachowanym nasyceniem.
- *
- * Konwersje wg modelu OKLab Björna Ottossona.
- */
-const TAU = Math.PI * 2;
-const clamp255 = (value) => (value < 0 ? 0 : value > 255 ? 255 : Math.round(value));
-/** Gamma sRGB → liniowo. */
-const toLinear = (channel) => {
-    const value = channel / 255;
-    return value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4;
-};
-/** Liniowo → gamma sRGB. */
-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 wstęgi trzeba 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. `fillStyle` odrzuca taką
- * wartość po cichu, zostawiając poprzednią, więc sam odczyt piksela nie odróżniłby śmiecia od
- * legalnej czerni — stąd dwa różne wartowniki: 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)}`;
-}
-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,
-    };
-}
-export function oklabToSrgb(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: toGamma(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
-        g: toGamma(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
-        b: toGamma(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
-    };
-}
-/**
- * Obrót odcienia o zadany kąt (stopnie) przy zachowanej jasności i nasyceniu.
- *
- * Stąd biorą się domyślne barwy wstęgi: paleta biblioteki jest neutralna, więc zamiast sięgać
- * po tokeny statusowe (`info`, `success`) do celów dekoracyjnych, dwie towarzyszące barwy
- * wyprowadzamy z koloru wiodącego. Wstęga 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. */
-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ę wzdłuż
- * wstęgi bez końca i szew w środku kadru 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) });
-}
-/**
- * Jasność względna wg WCAG (0 = czerń, 1 = biel).
- *
- * To nie to samo co jasność OKLab: OKLab opisuje, jak jasno barwa *wygląda*, a ta liczba mówi,
- * ile z niej wychodzi światła — i tylko na niej stoi rachunek kontrastu, którym rozstrzygamy,
- * czy na danym tle czytelniejszy jest napis ciemny czy jasny.
- */
-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;
-}