@konce-pt/backdrop 0.8.5

package/dist/wave.js

@@ -0,0 +1,107 @@
+import { kptHash01 } from "./hash.js";
+/** Dłuższy bok bufora, w którym liczy się efekt (px). */
+export const KPT_WAVE_RESOLUTION = 160;
+/** Najmniejsza liczba próbek na bok bufora — chyba że sam obszar jest mniejszy. */
+export const KPT_WAVE_MIN_SIDE = 72;
+/** Szerokość wstęgi jako ułamek wysokości kadru. */
+export const KPT_WAVE_BAND = 0.34;
+/** Wykładnik opadania od linii środkowej; 2 to krzywa Gaussa. */
+export const KPT_WAVE_SOFTNESS = 2;
+/** Jak mocno faluje linia środkowa, w ułamkach wysokości kadru. */
+export const KPT_WAVE_AMPLITUDE = 0.16;
+/** Kąt, pod jakim prąd przecina kadr (stopnie). */
+export const KPT_WAVE_ROTATION = 12;
+/** Ile rampy barw przypada na jednostkę długości wzdłuż wstęgi. */
+export const KPT_WAVE_SPREAD = 0.55;
+/** Ile rampy barw przesuwa się na sekundę przy `speed = 1`. */
+export const KPT_WAVE_DRIFT = 0.07;
+/** Ile harmonicznych składa się na linię środkową. */
+const HARMONICS = 3;
+const TAU = Math.PI * 2;
+const DEG = TAU / 360;
+/**
+ * Wymiary bufora pod zadany obszar.
+ *
+ * Wstęga nie ma detalu — jest samą miękkością — więc liczenie jej w pełnej rozdzielczości canvasu
+ * byłoby płaceniem za piksele, które i tak zostaną rozmyte. Bufor o dłuższym boku
+ * `KPT_WAVE_RESOLUTION` daje kilkanaście tysięcy pikseli na klatkę, a rozmycie robi za darmo
+ * interpolacja przeglądarki przy skalowaniu go w górę.
+ *
+ * Krótszy bok ma osobną podłogę `KPT_WAVE_MIN_SIDE`. W szerokim kadrze proporcjonalne skalowanie
+ * zostawiłoby kilkadziesiąt wierszy, a po obróceniu wstęgi o kąt bliski prostemu krzywa biegłaby
+ * właśnie wzdłuż tej osi i zaczynała się łamać. Bufor nie musi trzymać proporcji kadru —
+ * próbkowanie chodzi po współrzędnych znormalizowanych, a geometrię niesie `aspect` w ustawieniach.
+ */
+export function waveBuffer(width, height, resolution = KPT_WAVE_RESOLUTION) {
+    if (width <= 0 || height <= 0)
+        return { cols: 0, rows: 0 };
+    const longest = Math.max(width, height);
+    const scale = Math.min(1, Math.max(1, resolution) / longest);
+    const fit = (size) => Math.max(1, Math.round(size * scale), Math.min(Math.round(size), KPT_WAVE_MIN_SIDE));
+    return { cols: fit(width), rows: fit(height) };
+}
+/**
+ * Rozkłada ustawienia na wartości, które w pętli po pikselach są już tylko odczytywane.
+ *
+ * Domyślne wartości, sinus i cosinus kąta oraz harmoniczne liczą się raz — przy zmianie wejść
+ * albo rozmiaru — bo inaczej szłyby kilkanaście tysięcy razy na klatkę.
+ */
+export function resolveWave(options) {
+    const width = Math.max(0, options.width);
+    const height = Math.max(0, options.height);
+    const angle = (options.rotation ?? KPT_WAVE_ROTATION) * DEG;
+    const seed = options.seed ?? 0;
+    // Wagi opadają z numerem harmonicznej i sumują się do jedynki, żeby `amplitude` znaczyło
+    // to samo niezależnie od tego, ile ich jest.
+    const weights = Array.from({ length: HARMONICS }, (_, index) => 1 / (index + 1.6));
+    const total = weights.reduce((sum, weight) => sum + weight, 0);
+    return {
+        aspect: height > 0 ? width / height : 1,
+        cos: Math.cos(angle),
+        sin: Math.sin(angle),
+        band: Math.max(0.01, options.band ?? KPT_WAVE_BAND),
+        softness: Math.max(0.5, options.softness ?? KPT_WAVE_SOFTNESS),
+        amplitude: Math.max(0, options.amplitude ?? KPT_WAVE_AMPLITUDE),
+        spread: options.spread ?? KPT_WAVE_SPREAD,
+        drift: options.drift ?? KPT_WAVE_DRIFT,
+        harmonics: weights.map((weight, index) => ({
+            // Częstotliwości rosną nierówno, żeby suma nie wpadła w powtarzalny wzór.
+            frequency: 2.1 + index * 1.7,
+            rate: 0.3 + kptHash01(index, 1, seed) * 0.45,
+            phase: kptHash01(index, 2, seed) * TAU,
+            weight: weight / total,
+        })),
+    };
+}
+/** Współrzędna wzdłuż wstęgi po obrocie kadru o `-rotation`. */
+const along = (u, v, settings) => (u - 0.5) * settings.aspect * settings.cos + (v - 0.5) * settings.sin;
+/** Współrzędna w poprzek wstęgi. */
+const across = (u, v, settings) => -(u - 0.5) * settings.aspect * settings.sin + (v - 0.5) * settings.cos;
+/**
+ * Jasność wstęgi w punkcie `(u, v)` znormalizowanego kadru, w chwili `time` (sekundy).
+ *
+ * Linia środkowa to suma harmonicznych o niewspółmiernych częstotliwościach — stąd prąd faluje
+ * bez powtarzalnego wzoru. Od niej jasność opada krzywą Gaussa, więc w całym kadrze nie ma ani
+ * jednej twardej krawędzi; to właśnie odróżnia prąd światła od paska.
+ */
+export function waveIntensity(u, v, time, settings) {
+    const s = along(u, v, settings);
+    const t = across(u, v, settings);
+    let center = 0;
+    for (const harmonic of settings.harmonics) {
+        center += harmonic.weight * Math.sin(s * harmonic.frequency + time * harmonic.rate + harmonic.phase);
+    }
+    center *= settings.amplitude;
+    const distance = Math.abs(t - center) / settings.band;
+    return Math.exp(-(distance ** settings.softness));
+}
+/**
+ * Miejsce na rampie barw (0–1) dla punktu `(u, v)` w chwili `time`.
+ *
+ * Barwy przesuwają się wzdłuż wstęgi, nie w poprzek — dlatego liczy się tylko współrzędna `s`.
+ * Wynik zawsze zawija się do 0–1, więc rosnący czas nie wyprowadza go poza rampę.
+ */
+export function waveRamp(u, v, time, settings) {
+    const position = along(u, v, settings) * settings.spread + time * settings.drift;
+    return position - Math.floor(position);
+}

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@konce-pt/backdrop",
+  "version": "0.8.5",
+  "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, 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/backdrop"
+  },
+  "bugs": {
+    "url": "https://gitlab.com/konce-pt/koncept-ui/-/issues"
+  },
+  "keywords": [
+    "backdrop",
+    "background",
+    "canvas",
+    "animation",
+    "hero",
+    "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})\""
+  }
+}