@webmate-studio/builder 0.2.135 → 0.2.137

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webmate-studio/builder",
-  "version": "0.2.135",
+  "version": "0.2.137",
   "type": "module",
   "description": "Webmate Studio Component Builder",
   "keywords": [

package/src/design-tokens-v2.js

@@ -8,73 +8,117 @@
  * Dokumentation: webmate-studio/docs/DESIGN-TOKEN-SCHEMA-V2.md
  */
 
-// ─── Farbskala-Generierung ──────────────────────────────────────────────────
+// ─── OKLCH-Farbskala-Generierung ────────────────────────────────────────────
 
 /**
- * Generiert eine 12-Stufen-Farbskala aus einer Basisfarbe.
+ * Preset-Kurven für die Chroma-Verteilung über die 12 Stufen.
+ * stdDev = Breite der Gaußkurve (wie weit Sättigung von der Base ausstrahlt)
+ * chromaScale = globaler Sättigungsmultiplikator
+ */
+export const COLOR_SCALE_PRESETS = {
+	vivid:   { label: 'Leuchtend', stdDev: 28, chromaScale: 1.0 },
+	natural: { label: 'Natürlich', stdDev: 20, chromaScale: 0.85 },
+	soft:    { label: 'Pastellig', stdDev: 13, chromaScale: 0.7 },
+	muted:   { label: 'Gedämpft', stdDev: 18, chromaScale: 0.5 },
+};
+
+/**
+ * Generiert eine 12-Stufen-Farbskala aus einer Basisfarbe im OKLCH-Farbraum.
  * Stufe 9 = Basisfarbe. Stufen 1-8 heller, 10-12 dunkler.
  *
- * Für Neutral-Töne (niedrige Sättigung) wird die Sättigung automatisch
- * stark gedämpft, damit echte Grautöne entstehen statt verfärbter Pastelltöne.
+ * Verwendet OKLCH für perceptuell gleichmäßige Helligkeitsverteilung —
+ * garantiert monoton abnehmende Helligkeit von Stufe 1 bis 12.
+ *
+ * @param {string} baseHex - Basisfarbe als Hex-String
+ * @param {object} [curve] - Optionale Kurvenparameter: { preset: 'natural' } oder { preset: 'custom', stdDev, chromaScale }
  */
-export function generateColorScale(baseHex) {
-	const rgb = hexToRgb(baseHex);
-	if (!rgb) return null;
+export function generateColorScale(baseHex, curve) {
+	const base = hexToOklch(baseHex);
+	if (!base) return null;
+
+	// Kurvenparameter bestimmen
+	const presetName = curve?.preset || 'natural';
+	const preset = COLOR_SCALE_PRESETS[presetName];
+	const stdDev = curve?.preset === 'custom' ? (curve.stdDev ?? 20) : (preset?.stdDev ?? 20);
+	const chromaScale = curve?.preset === 'custom' ? (curve.chromaScale ?? 0.85) : (preset?.chromaScale ?? 0.85);
+
+	// Neutral-Erkennung: Basis mit niedriger Chroma
+	const isNeutral = base.c < 0.04;
+
+	// Lightness-Rampe adaptiv an Base-Lightness
+	const L = buildLightnessRamp(base.l);
+
+	// Wurde die Base-Lightness geclampt? (extrem helle/dunkle Farben)
+	const baseClamped = Math.abs(L[8] - base.l) > 0.01;
+
+	const scale = {};
+	for (let i = 0; i < 12; i++) {
+		const step = i + 1;
+		if (step === 9 && !baseClamped) {
+			// Step 9 = exakte Base-Farbe (wenn nicht geclampt)
+			scale[step] = baseHex;
+			continue;
+		}
 
-	const hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
+		// Chroma über Gaußkurve berechnen
+		let c;
+		if (isNeutral) {
+			c = base.c * 0.3;
+		} else if (step === 9) {
+			// Geclampt: volle Base-Chroma bei korrigierter Lightness
+			c = base.c;
+		} else {
+			c = computeChroma(L[i], L[8], base.c, stdDev, chromaScale);
+		}
 
-	// Neutral-Erkennung: Basis mit niedriger Sättigung (<15%)
-	// bekommt deutlich reduzierte Sättigung über die gesamte Skala
-	const isNeutral = hsl.s < 15;
-	const sFactor = isNeutral ? 0.3 : 1; // Sättigung auf 30% für Neutraltöne
+		const mapped = gamutMapOklch(L[i], c, base.h);
+		scale[step] = oklchToHex(mapped.l, mapped.c, mapped.h);
+	}
 
-	return {
-		1: hslToHex(hsl.h, Math.max(hsl.s * 0.15 * sFactor, isNeutral ? 0 : 2), 97),
-		2: hslToHex(hsl.h, Math.max(hsl.s * 0.2 * sFactor, isNeutral ? 0.5 : 3), 95),
-		3: hslToHex(hsl.h, Math.max(hsl.s * 0.3 * sFactor, isNeutral ? 1 : 5), 91),
-		4: hslToHex(hsl.h, Math.max(hsl.s * 0.4 * sFactor, isNeutral ? 1.5 : 7), 86),
-		5: hslToHex(hsl.h, Math.max(hsl.s * 0.5 * sFactor, isNeutral ? 2 : 9), 80),
-		6: hslToHex(hsl.h, hsl.s * 0.65 * sFactor, 70),
-		7: hslToHex(hsl.h, hsl.s * 0.8 * sFactor, 58),
-		8: hslToHex(hsl.h, hsl.s * 0.9 * sFactor, 48),
-		9: baseHex,
-		10: hslToHex(hsl.h, Math.min(hsl.s * 1.05 * sFactor, 100), Math.max(hsl.l - 8, 10)),
-		11: hslToHex(hsl.h, Math.min(hsl.s * 0.9 * sFactor, 100), Math.max(hsl.l - 20, 15)),
-		12: hslToHex(hsl.h, Math.min(hsl.s * 0.7 * sFactor, 80), Math.max(hsl.l - 35, 8)),
-	};
+	// Neutral Step 1 = reines Weiß
+	if (isNeutral) {
+		scale[1] = '#ffffff';
+	}
+
+	return scale;
 }
 
 /**
- * Generiert eine invertierte 12-Stufen-Skala für Dark Mode.
+ * Generiert eine invertierte 12-Stufen-Skala für Dark Mode im OKLCH-Farbraum.
  * Stufe 1 = dunkelster Wert, Stufe 12 = hellster.
  */
-export function generateDarkColorScale(baseHex) {
-	const rgb = hexToRgb(baseHex);
-	if (!rgb) return null;
-
-	const hsl = rgbToHsl(rgb.r, rgb.g, rgb.b);
-
-	// Neutral-Erkennung: gleiche Logik wie generateColorScale
-	const isNeutral = hsl.s < 15;
-	const sFactor = isNeutral ? 0.3 : 1;
+export function generateDarkColorScale(baseHex, curve) {
+	const base = hexToOklch(baseHex);
+	if (!base) return null;
+
+	const presetName = curve?.preset || 'natural';
+	const preset = COLOR_SCALE_PRESETS[presetName];
+	const stdDev = curve?.preset === 'custom' ? (curve.stdDev ?? 20) : (preset?.stdDev ?? 20);
+	const chromaScale = curve?.preset === 'custom' ? (curve.chromaScale ?? 0.85) : (preset?.chromaScale ?? 0.85);
+
+	const isNeutral = base.c < 0.04;
+
+	// Dark Mode: Base etwas heller für bessere Sichtbarkeit
+	const darkBaseL = Math.min(base.l + 0.08, 0.65);
+
+	// Lightness-Rampe adaptiv (invertiert für Dark Mode)
+	const L = buildDarkLightnessRamp(darkBaseL);
+
+	const scale = {};
+	for (let i = 0; i < 12; i++) {
+		const step = i + 1;
+		let c;
+		if (isNeutral) {
+			c = base.c * 0.3;
+		} else {
+			c = computeChroma(L[i], L[8], base.c, stdDev, chromaScale);
+		}
 
-	// Dark Mode: Basis etwas heller für bessere Sichtbarkeit
-	const darkBase = hslToHex(hsl.h, Math.min(hsl.s * 1.1 * sFactor, 100), Math.min(hsl.l + 10, 65));
+		const mapped = gamutMapOklch(L[i], c, base.h);
+		scale[step] = oklchToHex(mapped.l, mapped.c, mapped.h);
+	}
 
-	return {
-		1: hslToHex(hsl.h, Math.max(hsl.s * 0.3 * sFactor, isNeutral ? 0 : 5), 8),
-		2: hslToHex(hsl.h, Math.max(hsl.s * 0.35 * sFactor, isNeutral ? 0.5 : 6), 12),
-		3: hslToHex(hsl.h, Math.max(hsl.s * 0.45 * sFactor, isNeutral ? 1 : 8), 18),
-		4: hslToHex(hsl.h, Math.max(hsl.s * 0.55 * sFactor, isNeutral ? 1.5 : 10), 24),
-		5: hslToHex(hsl.h, Math.max(hsl.s * 0.6 * sFactor, isNeutral ? 2 : 12), 30),
-		6: hslToHex(hsl.h, hsl.s * 0.65 * sFactor, 38),
-		7: hslToHex(hsl.h, hsl.s * 0.75 * sFactor, 48),
-		8: hslToHex(hsl.h, hsl.s * 0.85 * sFactor, 58),
-		9: darkBase,
-		10: hslToHex(hsl.h, Math.min(hsl.s * 1.0 * sFactor, 100), Math.min(hsl.l + 20, 75)),
-		11: hslToHex(hsl.h, Math.min(hsl.s * 0.7 * sFactor, 80), Math.min(hsl.l + 35, 85)),
-		12: hslToHex(hsl.h, Math.min(hsl.s * 0.4 * sFactor, 50), Math.min(hsl.l + 50, 95)),
-	};
+	return scale;
 }
 
 /**
@@ -165,6 +209,274 @@ function hslToHex(h, s, l) {
 	return rgbToHex((r + m) * 255, (g + m) * 255, (b + m) * 255);
 }
 
+// ─── OKLCH-Hilfsfunktionen ──────────────────────────────────────────────────
+
+/**
+ * Baut eine strikt monoton fallende Lightness-Rampe für 12 Stufen.
+ * Steps 1-8 werden zwischen topL und baseL verteilt (Ease-Out-Kurve).
+ * Steps 10-12 werden zwischen baseL und bottomL verteilt.
+ * Step 9 = baseL (exakt).
+ *
+ * Funktioniert auch bei extremen Base-Werten (sehr hell/dunkel):
+ * - Die Rampe wird auf den verfügbaren Bereich komprimiert
+ * - Monotonie ist durch die Konstruktion garantiert
+ */
+function buildLightnessRamp(baseL) {
+	const topL = 0.985;    // Step 1: fast Weiß
+	const bottomL = 0.25;  // Step 12: dunkelster Wert
+
+	// Base clampen: min. 0.30 damit 3 dunkle Stufen Platz haben,
+	// max. 0.80 damit 8 helle Stufen genug Abstand in sRGB haben
+	const safeBaseL = Math.max(0.30, Math.min(0.80, baseL));
+
+	// Steps 1-8: Von topL nach safeBaseL + Lücke
+	// Die Lücke stellt sicher, dass Step 8 immer heller als Step 9 ist
+	const gap = Math.max(0.02, (topL - safeBaseL) * 0.05);
+	const step8Target = safeBaseL + gap;
+	const range = topL - step8Target;
+
+	// Feste Verteilungs-Gewichte: Steps 1-2 bleiben nahe Weiß,
+	// dann beschleunigter Abstieg zur Base. Inspiriert von Radix' Lightness-Verteilung.
+	const weights = [0.0, 0.04, 0.10, 0.20, 0.34, 0.50, 0.70, 0.92];
+	const lightSteps = weights.map(w => topL - w * range);
+
+	// Steps 10-12: nach unten von Base weg
+	const darkRange = safeBaseL - bottomL;
+	const step10L = safeBaseL - darkRange * 0.12;
+	const step11L = safeBaseL - darkRange * 0.55;
+	const step12L = bottomL;
+
+	const ramp = [
+		...lightSteps,  // Steps 1-8
+		safeBaseL,      // Step 9
+		step10L,        // Step 10
+		step11L,        // Step 11
+		step12L,        // Step 12
+	];
+
+	// Finale Sicherheit: strikt monoton fallend
+	for (let i = 1; i < ramp.length; i++) {
+		if (ramp[i] >= ramp[i - 1]) {
+			ramp[i] = ramp[i - 1] - 0.003;
+		}
+	}
+
+	return ramp;
+}
+
+/**
+ * Baut eine strikt monoton steigende Lightness-Rampe für Dark Mode.
+ * Steps 1-8: dunkel → darkBaseL, Steps 10-12: darkBaseL → hell.
+ */
+function buildDarkLightnessRamp(darkBaseL) {
+	const bottomL = 0.14;
+	const topL = 0.94;
+
+	const safeBaseL = Math.max(0.22, Math.min(0.85, darkBaseL));
+
+	const gap = Math.max(0.02, (safeBaseL - bottomL) * 0.05);
+	const step8Target = safeBaseL - gap;
+	const range = step8Target - bottomL;
+
+	const weights = [0.0, 0.04, 0.10, 0.20, 0.34, 0.50, 0.70, 0.92];
+	const darkSteps = weights.map(w => bottomL + w * range);
+
+	const lightRange = topL - safeBaseL;
+	const step10L = safeBaseL + lightRange * 0.15;
+	const step11L = safeBaseL + lightRange * 0.55;
+	const step12L = topL;
+
+	const ramp = [
+		...darkSteps,
+		safeBaseL,
+		step10L,
+		step11L,
+		step12L,
+	];
+
+	for (let i = 1; i < ramp.length; i++) {
+		if (ramp[i] <= ramp[i - 1]) {
+			ramp[i] = ramp[i - 1] + 0.003;
+		}
+	}
+
+	return ramp;
+}
+
+/**
+ * Chroma-Berechnung für eine Stufe: Gaußkurve × Lightness-Begrenzung.
+ *
+ * Die Gaußkurve bestimmt den gewünschten Chroma-Anteil basierend auf der
+ * Distanz zur Base-Lightness. Zusätzlich wird die Chroma durch einen
+ * Lightness-Faktor begrenzt: Je näher an Weiß (L=1) oder Schwarz (L=0),
+ * desto weniger Chroma ist physisch/visuell sinnvoll.
+ *
+ * Das sorgt dafür, dass Steps 1-2 fast weiß und Steps 11-12 fast schwarz
+ * sind — wie bei Radix Colors.
+ */
+function computeChroma(stepL, baseL, baseC, stdDev, chromaScale) {
+	// Gaußkurve: Peak bei baseL
+	const diff = baseL - stepL;
+	const gaussian = Math.exp((-25 / stdDev) * diff * diff);
+
+	// Lightness-Begrenzung: Wie viel Chroma ist bei dieser Lightness sinnvoll?
+	// Bei L=0 oder L=1 → 0, bei L≈0.5-0.7 → Maximum
+	// Formel: sin-artige Kurve die bei L=0 und L=1 null ist
+	const lightnessLimit = Math.pow(Math.sin(stepL * Math.PI), 1.2);
+
+	return baseC * gaussian * lightnessLimit * chromaScale;
+}
+
+
+/**
+ * Hex → OKLCH Konvertierung.
+ * Pfad: Hex → sRGB → Linear RGB → OKLab → OKLCH
+ */
+function hexToOklch(hex) {
+	const rgb = hexToRgb(hex);
+	if (!rgb) return null;
+
+	// sRGB → Linear RGB (Gamma-Dekodierung)
+	const lr = srgbToLinear(rgb.r / 255);
+	const lg = srgbToLinear(rgb.g / 255);
+	const lb = srgbToLinear(rgb.b / 255);
+
+	// Linear RGB → OKLab
+	const lab = linearRgbToOklab(lr, lg, lb);
+
+	// OKLab → OKLCH
+	const c = Math.sqrt(lab.a * lab.a + lab.b * lab.b);
+	let h = Math.atan2(lab.b, lab.a) * 180 / Math.PI;
+	if (h < 0) h += 360;
+
+	return { l: lab.l, c, h };
+}
+
+/**
+ * OKLCH → Hex Konvertierung.
+ * Pfad: OKLCH → OKLab → Linear RGB → sRGB → Hex
+ */
+function oklchToHex(l, c, h) {
+	// OKLCH → OKLab
+	const hRad = h * Math.PI / 180;
+	const a = c * Math.cos(hRad);
+	const b = c * Math.sin(hRad);
+
+	// OKLab → Linear RGB
+	const lin = oklabToLinearRgb(l, a, b);
+
+	// Linear RGB → sRGB (Gamma-Kodierung)
+	const sr = Math.round(linearToSrgb(lin.r) * 255);
+	const sg = Math.round(linearToSrgb(lin.g) * 255);
+	const sb = Math.round(linearToSrgb(lin.b) * 255);
+
+	return rgbToHex(
+		Math.max(0, Math.min(255, sr)),
+		Math.max(0, Math.min(255, sg)),
+		Math.max(0, Math.min(255, sb))
+	);
+}
+
+/**
+ * Gamut-Mapping: Reduziert Chroma bis die Farbe in sRGB darstellbar ist.
+ * Behält Lightness und Hue bei.
+ */
+function gamutMapOklch(l, c, h) {
+	// Triviale Fälle
+	if (c <= 0) return { l, c: 0, h };
+	if (isInSrgbGamut(l, c, h)) return { l, c, h };
+
+	// Binary Search: Chroma reduzieren
+	let low = 0;
+	let high = c;
+	for (let i = 0; i < 20; i++) {
+		const mid = (low + high) / 2;
+		if (isInSrgbGamut(l, mid, h)) {
+			low = mid;
+		} else {
+			high = mid;
+		}
+	}
+	return { l, c: low, h };
+}
+
+/**
+ * Prüft ob eine OKLCH-Farbe innerhalb des sRGB-Gamuts liegt.
+ */
+function isInSrgbGamut(l, c, h) {
+	const hRad = h * Math.PI / 180;
+	const a = c * Math.cos(hRad);
+	const b = c * Math.sin(hRad);
+	const lin = oklabToLinearRgb(l, a, b);
+	const eps = -0.001; // Kleine Toleranz für Rundungsfehler
+	return lin.r >= eps && lin.r <= 1.001 &&
+	       lin.g >= eps && lin.g <= 1.001 &&
+	       lin.b >= eps && lin.b <= 1.001;
+}
+
+/**
+ * Linear RGB → OKLab (Bjorn Ottosson, 2020)
+ */
+function linearRgbToOklab(r, g, b) {
+	// Linear RGB → LMS (via M1 Matrix)
+	const l_ = 0.4122214708 * r + 0.5363325363 * g + 0.0514459929 * b;
+	const m_ = 0.2119034982 * r + 0.6806995451 * g + 0.1073969566 * b;
+	const s_ = 0.0883024619 * r + 0.2817188376 * g + 0.6299787005 * b;
+
+	// Kubikwurzel
+	const l = Math.cbrt(l_);
+	const m = Math.cbrt(m_);
+	const s = Math.cbrt(s_);
+
+	// LMS → OKLab (via M2 Matrix)
+	return {
+		l: 0.2104542553 * l + 0.7936177850 * m - 0.0040720468 * s,
+		a: 1.9779984951 * l - 2.4285922050 * m + 0.4505937099 * s,
+		b: 0.0259040371 * l + 0.7827717662 * m - 0.8086757660 * s,
+	};
+}
+
+/**
+ * OKLab → Linear RGB (Inverse von linearRgbToOklab)
+ */
+function oklabToLinearRgb(L, a, b) {
+	// OKLab → LMS (inverse M2)
+	const l = L + 0.3963377774 * a + 0.2158037573 * b;
+	const m = L - 0.1055613458 * a - 0.0638541728 * b;
+	const s = L - 0.0894841775 * a - 1.2914855480 * b;
+
+	// LMS kubisch
+	const l3 = l * l * l;
+	const m3 = m * m * m;
+	const s3 = s * s * s;
+
+	// LMS → Linear RGB (inverse M1)
+	return {
+		r:  4.0767416621 * l3 - 3.3077115913 * m3 + 0.2309699292 * s3,
+		g: -1.2684380046 * l3 + 2.6097574011 * m3 - 0.3413193965 * s3,
+		b: -0.0041960863 * l3 - 0.7034186147 * m3 + 1.7076147010 * s3,
+	};
+}
+
+/**
+ * sRGB Gamma-Dekodierung (sRGB → Linear)
+ */
+function srgbToLinear(c) {
+	return c <= 0.04045 ? c / 12.92 : Math.pow((c + 0.055) / 1.055, 2.4);
+}
+
+/**
+ * sRGB Gamma-Kodierung (Linear → sRGB)
+ */
+function linearToSrgb(c) {
+	if (c <= 0) return 0;
+	if (c >= 1) return 1;
+	return c <= 0.0031308 ? 12.92 * c : 1.055 * Math.pow(c, 1 / 2.4) - 0.055;
+}
+
+
+// ─── Legacy Farb-Hilfsfunktionen (HSL, Luminanz) ───────────────────────────
+
 function relativeLuminance(r, g, b) {
 	const [rs, gs, bs] = [r, g, b].map(c => {
 		c = c / 255;
@@ -187,6 +499,8 @@ function contrastRatio(l1, l2) {
  * Brand-Welten (primary, secondary, accent) + Status-Welten (success, warning, error, info) + Neutral.
  */
 export const COLOR_WORLDS = ['primary', 'secondary', 'accent', 'success', 'warning', 'error', 'info', 'neutral'];
+export const BRAND_COLOR_WORLDS = ['primary', 'secondary', 'accent', 'neutral'];
+export const STATUS_COLOR_WORLDS = ['success', 'warning', 'error', 'info'];
 export const SEMANTIC_COLOR_WORLDS = ['primary', 'secondary', 'accent', 'success', 'warning', 'error', 'info'];
 
 /**
@@ -296,34 +610,42 @@ export const defaultDesignTokensV2 = {
 	colors: {
 		primary: {
 			base: '#1E40AF',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#1E40AF')
 		},
 		secondary: {
 			base: '#6366F1',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#6366F1')
 		},
 		accent: {
 			base: '#8B5CF6',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#8B5CF6')
 		},
 		success: {
 			base: '#16A34A',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#16A34A')
 		},
 		warning: {
 			base: '#D97706',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#D97706')
 		},
 		error: {
 			base: '#DC2626',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#DC2626')
 		},
 		info: {
 			base: '#2563EB',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#2563EB')
 		},
 		neutral: {
-			base: '#6B7280', // Kühles Grau — gibt dem Design System seinen Charakter
+			base: '#6B7280',
+			curve: { preset: 'natural' },
 			scale: generateColorScale('#6B7280')
 		}
 	},