@profitlich/template-toolkit 6.0.0 → 6.1.0

package/CLAUDE.project.md

@@ -102,6 +102,22 @@ Ist ESLint eingerichtet, braucht `__DEBUG__` einen Eintrag unter `languageOption
 - Jedes Modul/Snippet hat eine eigene `.js`-Datei, die das zugehörige SCSS importiert — auch wenn sie sonst keine Logik enthält.
 - Keine globalen Styles in Modul- oder Snippet-SCSS-Dateien.
 
+#### Grundregel und Breakpoint-Blöcke
+
+**In einen `mediaquery()`-Block gehört nur, was sich pro Breakpoint unterscheidet** – in der Praxis fast nur Aufrufe mit `$layout`. Feste Werte wie `display: flex` oder `position: fixed` stehen einmal in der Grundregel oben in der Datei. Einen Breakpoint-Block nie als Kopie eines anderen anlegen: Genau so wandern feste Werte in alle drei Blöcke.
+
+Gleich *geschriebene* `$layout`-Aufrufe wie `font($layout, 14, 20)` sind keine Wiederholung – sie ergeben pro Breakpoint andere Werte und bleiben in den Blöcken.
+
+Das PostCSS-Plugin `@profitlich/template-toolkit/vite/postcssBreakpointDry` meldet beim Build und im Dev-Server, wo es trotzdem passiert ist: Deklarationen, die mit gleichem Selektor und Wert in Media-Queries stehen, die zusammen alle Breiten abdecken, und solche, die nur die Grundregel wiederholen. Es warnt nur. Eingebunden in `postcss.config.js`:
+
+```js
+import postcssBreakpointDry from '@profitlich/template-toolkit/vite/postcssBreakpointDry';
+
+export default {
+    plugins: [postcssBreakpointDry()],
+};
+```
+
 #### vw-Basis
 
 Per Default skalieren vw-basierte Werte mit der Viewport-Breite inkl. Scrollbar (`100vw`). Mit `"vwBasis": "body"` als Top-Level-Feld in `src/config.json` skalieren sie stattdessen mit der scrollbar-freien Body-Breite — sinnvoll, wenn Layout-Elemente in `%` gesetzt sind und Schriften/Abstände exakt mit diesen mitskalieren sollen. Dafür im Projekt `VwBody.getInstance()` (aus `@profitlich/template-toolkit/utils/VwBody`) aufrufen — setzt die Custom Property `--vw-body` per JS. Default-Verhalten ohne Feld unverändert.
@@ -142,6 +158,28 @@ $cap: capsize-cap-height("soehne", 40);  // → font-spezifischer Wert
 padding-top: size($layout, 40 - $cap + 8);
 ```
 
+**Capsize und Breakpoints**: Die Trims sind em-Werte und hängen nur von der Schrift und vom Verhältnis Zeilenhöhe/Schriftgrösse ab, nicht von `$layout`. Bekommt ein Selektor in allen Breakpoints Capsize, gehört der gleichbleibende Teil in die Grundregel. Zwei Fälle:
+
+- **Gleiches Verhältnis in allen Breakpoints** (z. B. überall 14/20): `capsize()` einmal in der Grundregel, in den Breakpoints `font()` ohne 4. Argument.
+
+    ```scss
+    .foo { @include capsize("soehne", 14, 20); }
+    @include mediaquery(tablet) using ($layout) {
+        .foo { @include font($layout, 14, 20); }
+    }
+    ```
+
+- **Verschiedene Verhältnisse** (z. B. 40/70, 56/120, 111/120): `capsize-base` in der Grundregel. Es schreibt `content` und `display` der Pseudo-Elemente einmal. `font()` mit Capsize-Font gibt danach für denselben Selektor nur noch die Trims aus. Die Verschachtelung muss in Grundregel und Breakpoint gleich sein, sonst greift die Zuordnung nicht, und es wird wie bisher alles ausgegeben.
+
+    ```scss
+    .foo { @include capsize-base; }
+    @include mediaquery(tablet) using ($layout) {
+        .foo { @include font($layout, 56, 120, "soehne"); }   // → nur Trims
+    }
+    ```
+
+Beides nur, wenn **jeder** Breakpoint Capsize bekommt. Sonst entstehen in den übrigen Pseudo-Elemente ohne Trims, die in einem Flex- oder Grid-Container als zusätzliche Items mitlaufen.
+
 ### Vite Entry
 
 Einen neuen Entry in `rollupOptions.input` eintragen **nur wenn** das Script per Twig/PHP-Tag direkt eingebunden wird. Wird es von einem anderen Script importiert, braucht es keinen eigenen Entry.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@profitlich/template-toolkit",
-    "version": "6.0.0",
+    "version": "6.1.0",
     "description": "Shared SCSS layout system, JS utilities, components and build scripts for profitlich template repos",
     "type": "module",
     "sass": "scss/forward.scss",
@@ -24,7 +24,8 @@
         "./scripts/copy-files": "./scripts/copy-files.js",
         "./scripts/deploy": "./scripts/deploy.js",
         "./vite/jsonToScss": "./vite/jsonToScss.js",
-        "./vite/capsizeSassFunctions": "./vite/capsizeSassFunctions.js"
+        "./vite/capsizeSassFunctions": "./vite/capsizeSassFunctions.js",
+        "./vite/postcssBreakpointDry": "./vite/postcssBreakpointDry.js"
     },
     "files": [
         "CLAUDE.project.md",

package/scss/core/capsize.scss

@@ -1,10 +1,19 @@
+@use "sass:map";
 @use "sass:meta";
 
+// Selektoren, deren fester Capsize-Teil per capsize-base bereits in der
+// Grundregel steht. Jede SCSS-Datei ist eine eigene Sass-Kompilation, die Map
+// gilt also nur innerhalb einer Datei.
+$_base-selectors: ();
+
 // Emittiert die Capsize-Pseudo-Elemente (::before/::after mit Em-Trims)
 // für den aktuellen Selektor. Die Inhalte (welche Pseudo-Elemente, welche
 // Properties) kommen vollständig aus @capsizecss/core via der
 // Sass-Custom-Function capsize-pseudo-elements (registriert im
 // vite/capsizeSassFunctions.js des Toolkits).
+//
+// Steht für den Selektor capsize-base in der Grundregel, entfallen hier die
+// festen Properties, und es bleiben nur die Trims.
 @mixin capsize($name, $fontSize, $lineHeight) {
     // Capsize ist opt-in: ohne registrierte Custom-Function wird übersprungen,
     // damit ein fehlender Vite-Setup nicht zu kryptischem Sass-Fehler führt.
@@ -12,12 +21,45 @@
         @warn "Capsize ist nicht eingerichtet: Custom-Function capsize-pseudo-elements fehlt. Siehe template-toolkit/CLAUDE.md, Abschnitt Capsize. Aufruf für \"#{$name}\" wird übersprungen.";
     } @else {
         $pseudo: capsize-pseudo-elements($name, $fontSize, $lineHeight);
+        $static: ();
+        @if map.has-key($_base-selectors, "#{&}") {
+            $static: capsize-static-properties();
+        }
+
         @each $selector-suffix, $props in $pseudo {
+            $skip: ();
+            @if map.has-key($static, $selector-suffix) {
+                $skip: map.get($static, $selector-suffix);
+            }
+
+            &#{$selector-suffix} {
+                @each $prop, $val in $props {
+                    @if not map.has-key($skip, $prop) {
+                        #{$prop}: $val;
+                    }
+                }
+            }
+        }
+    }
+}
+
+// Emittiert den festen Teil der Capsize-Pseudo-Elemente (content, display)
+// einmal in der Grundregel. Die Aufrufe von capsize() bzw. font() mit
+// Capsize-Font in den Breakpoint-Blöcken geben danach nur noch die Trims aus.
+//
+// Nur verwenden, wenn der Selektor in allen Breakpoints Capsize bekommt –
+// sonst entstehen dort Pseudo-Elemente ohne Trims.
+@mixin capsize-base {
+    @if not meta.function-exists("capsize-static-properties") {
+        @warn "Capsize ist nicht eingerichtet: Custom-Function capsize-static-properties fehlt. Siehe template-toolkit/CLAUDE.md, Abschnitt Capsize. capsize-base wird übersprungen.";
+    } @else {
+        @each $selector-suffix, $props in capsize-static-properties() {
             &#{$selector-suffix} {
                 @each $prop, $val in $props {
                     #{$prop}: $val;
                 }
             }
         }
+        $_base-selectors: map.set($_base-selectors, "#{&}", true) !global;
     }
 }

package/vite/capsizeSassFunctions.js

@@ -60,6 +60,33 @@ export async function createCapsizeFunctions(fontFiles) {
             return new sass.SassMap(OrderedMap(entries));
         },
 
+        // Liefert pro Pseudo-Element die Properties, die nicht von Schriftgrösse
+        // und Zeilenhöhe abhängen (heute content und display). Ermittelt aus zwei
+        // Aufrufen mit verschiedenem Verhältnis: Was in beiden gleich bleibt, ist
+        // fest. So bestimmt Capsize das Schema, nicht eine Liste im Toolkit.
+        'capsize-static-properties()': () => {
+            const fontMetrics = Object.values(metrics)[0];
+            if (!fontMetrics) {
+                throw new Error('capsize-static-properties: Keine Font-Metriken geladen.');
+            }
+
+            const narrow = createStyleObject({ fontSize: 10, leading: 12, fontMetrics });
+            const wide = createStyleObject({ fontSize: 10, leading: 30, fontMetrics });
+
+            const entries = [];
+            for (const [key, val] of Object.entries(narrow)) {
+                if (!key.startsWith('::')) continue;
+                const fixed = Object.fromEntries(
+                    Object.entries(val).filter(([prop, value]) => wide[key]?.[prop] === value)
+                );
+                entries.push([
+                    new sass.SassString(key, { quotes: false }),
+                    _objToSassMap(fixed),
+                ]);
+            }
+            return new sass.SassMap(OrderedMap(entries));
+        },
+
         'capsize-cap-height($name, $fontSize)': (args) => {
             const name = args[0].assertString('name').text;
             const fontSize = args[1].assertNumber('fontSize').value;

package/vite/postcssBreakpointDry.js

@@ -0,0 +1,134 @@
+import path from 'node:path';
+
+/**
+ * PostCSS-Plugin, das Wiederholungen über Breakpoint-Blöcke hinweg meldet.
+ *
+ * Läuft auf dem kompilierten CSS jeder SCSS-Datei. Verschachtelung ist dort
+ * aufgelöst und `$layout`-Werte sind ausgerechnet. Gewarnt wird in zwei Fällen:
+ *
+ * - Eine Deklaration steht mit gleichem Selektor und gleichem Wert in
+ *   Media-Queries, die zusammen alle Breiten abdecken (typisch: smartphone,
+ *   tablet und desktop). Sie gehört in die Grundregel.
+ * - Eine Deklaration in einer Media-Query wiederholt, was die Grundregel für
+ *   denselben Selektor bereits setzt.
+ *
+ * Das Plugin warnt nur und bricht den Build nie ab. Dateien aus `node_modules`
+ * werden übersprungen.
+ *
+ * @returns {import('postcss').Plugin}
+ */
+export default function postcssBreakpointDry() {
+    return {
+        postcssPlugin: 'postcss-breakpoint-dry',
+        OnceExit(root, { result }) {
+            const file = root.source?.input.file ?? '';
+            if (/[\\/]node_modules[\\/]/.test(file)) return;
+            // Vite nennt bei PostCSS-Warnungen die Datei nicht, darum steht sie in der Meldung
+            const location = file ? `${path.relative(process.cwd(), file)}: ` : '';
+
+            // Selektor|Eigenschaft → Wert, jeweils der letzte Stand der Grundregeln
+            const base = new Map();
+            // Selektor|Eigenschaft → [{ value, interval, decl, baseValue }]
+            const media = new Map();
+
+            root.each((node) => {
+                if (node.type === 'rule') {
+                    eachDecl(node, (key, value) => base.set(key, value));
+                    return;
+                }
+                if (node.type !== 'atrule' || node.name !== 'media') return;
+
+                // Unbekannte Bedingungen wie (hover: hover) lassen sich nicht auf Breiten abbilden
+                const interval = parseInterval(node.params);
+                if (!interval) return;
+
+                node.each((rule) => {
+                    if (rule.type !== 'rule') return;
+                    eachDecl(rule, (key, value, decl) => {
+                        if (!media.has(key)) media.set(key, []);
+                        media.get(key).push({ value, interval, decl, baseValue: base.get(key) });
+                    });
+                });
+            });
+
+            for (const [key, entries] of media) {
+                // Setzt eine andere Media-Query denselben Selektor anders, hängt das
+                // Ergebnis an der Reihenfolge – kein eindeutiger Fall
+                const values = new Set(entries.map((entry) => entry.value));
+                if (values.size > 1) continue;
+
+                const [selector, prop] = key.split('|');
+                const { value, decl } = entries[0];
+                // Pseudo-Elemente stammen meist aus font() mit Capsize-Font, behoben wird dort
+                const hint = /::?(before|after)\b/.test(selector) ? ' (bei Capsize: capsize() bzw. capsize-base in die Grundregel)' : '';
+
+                if (entries.every((entry) => entry.baseValue === value)) {
+                    decl.warn(result, `${location}${selector} { ${prop}: ${value} } wiederholt die Grundregel und kann aus den Media-Queries entfallen${hint}`);
+                } else if (coversAllWidths(entries.map((entry) => entry.interval))) {
+                    decl.warn(result, `${location}${selector} { ${prop}: ${value} } steht in Media-Queries, die zusammen alle Breiten abdecken, und gehört in die Grundregel${hint}`);
+                }
+            }
+        },
+    };
+}
+
+postcssBreakpointDry.postcss = true;
+
+/** Ruft `callback` für jede direkte Deklaration einer Regel auf, mit normalisiertem Schlüssel und Wert. */
+function eachDecl(rule, callback) {
+    const selector = rule.selectors.map((part) => part.replace(/\s+/g, ' ').trim()).join(', ');
+    rule.each((decl) => {
+        if (decl.type !== 'decl') return;
+        const value = decl.value.replace(/\s+/g, ' ').trim() + (decl.important ? ' !important' : '');
+        callback(`${selector}|${decl.prop}`, value, decl);
+    });
+}
+
+/**
+ * Liest eine Media-Query als Breitenbereich in ganzen px, in der Form
+ * `(min-width: 740px)` oder `(width >= 740px)`. Liefert `null` für alles andere –
+ * etwa Listen, Medientypen oder weitere Merkmale wie `(hover: hover)`.
+ */
+function parseInterval(params) {
+    if (params.includes(',')) return null;
+
+    const interval = { min: 0, max: Infinity };
+    for (const condition of params.split(/\s+and\s+/i)) {
+        const bound = parseBound(condition.trim());
+        if (!bound) return null;
+        if (bound.min !== undefined) interval.min = Math.max(interval.min, bound.min);
+        if (bound.max !== undefined) interval.max = Math.min(interval.max, bound.max);
+    }
+    return interval;
+}
+
+function parseBound(condition) {
+    const legacy = condition.match(/^\(\s*(min|max)-width\s*:\s*(\d+)px\s*\)$/i);
+    if (legacy) {
+        const px = Number(legacy[2]);
+        return legacy[1].toLowerCase() === 'min' ? { min: px } : { max: px };
+    }
+
+    const range = condition.match(/^\(\s*width\s*(<=|>=|<|>)\s*(\d+)px\s*\)$/i);
+    if (range) {
+        const px = Number(range[2]);
+        switch (range[1]) {
+            case '>=': return { min: px };
+            case '>': return { min: px + 1 };
+            case '<=': return { max: px };
+            case '<': return { max: px - 1 };
+        }
+    }
+    return null;
+}
+
+/** Prüft, ob die Bereiche lückenlos von 0 bis unendlich reichen. */
+function coversAllWidths(intervals) {
+    let reached = 0;
+    for (const { min, max } of [...intervals].sort((a, b) => a.min - b.min)) {
+        // max-width: 739px und min-width: 740px schliessen lückenlos aneinander an
+        if (min > reached) return false;
+        reached = Math.max(reached, max + 1);
+    }
+    return reached === Infinity;
+}