@profitlich/template-toolkit 5.3.1 → 5.5.0

package/CLAUDE.craftcms.md

@@ -0,0 +1,15 @@
+### Craft CMS
+
+**CSP Nonce:** Beim Einbinden eines Scripts immer den Nonce mitgeben, sonst blockt die Content-Security-Policy es:
+
+```twig
+{% do craft.vite.register("src/modules/module-name/Module.js", false, { 'nonce': csp('script-src') }) %}
+```
+
+Dasselbe gilt für per `view.registerCss()` eingebettetes CSS: `{ nonce: csp('style-src') }`.
+
+**Project Config:** Feld- und Struktur-Änderungen können direkt in den YAML-Dateien unter `config/project/` gemacht werden, danach `ddev craft project-config/apply` (Kontrolle vorher mit `project-config/diff`). `allowAdminChanges` ist üblicherweise nur in der Dev-Umgebung aktiv, Änderungen über die Oberfläche gehen also ausschliesslich lokal.
+
+Project-Config-Änderungen lassen sich nicht sinnvoll auf mehrere Commits aufteilen, weil `project.yaml` mit seinem `dateModified` an allem hängt.
+
+**Templates sind generiert:** `templates/` entsteht aus `src/` (`ddev npm run copy`, während der Entwicklung `ddev npm run dev`) und ist gitignoriert. Änderungen gehören immer nach `src/`; eine Bearbeitung in `templates/` ist beim nächsten Copy-Lauf verloren.

package/CLAUDE.kirbycms.md

@@ -0,0 +1,5 @@
+### Kirby CMS
+
+*Gerüst — kirby-spezifische Konventionen hier eintragen.*
+
+Was hierher gehört: Regeln, die nur für Kirby-Projekte gelten (Snippet- und Template-Aufbau, Blueprints, Panel-Eigenheiten, Einbindung von Assets). Was für alle Projekte gilt, steht in `CLAUDE.project.md`; was nur die Toolkit-Entwicklung betrifft, in `CLAUDE.md`.

package/CLAUDE.project.md

@@ -0,0 +1,80 @@
+## Geerbte Konventionen
+
+Dieser Abschnitt stammt aus `@profitlich/template-toolkit` und wird bei jedem `copy`-Lauf aus der installierten Paketversion neu geschrieben. Änderungen hier gehen verloren.
+
+**Rangfolge:** Was **unterhalb** dieses Blocks steht, ist projektspezifisch und geht im Konfliktfall vor. Eine Abweichung ist erlaubt — sie soll nur als Abweichung sichtbar sein und nicht die geerbte Regel stillschweigend ersetzen.
+
+**Wohin gehört eine neue Regel?** Betrifft sie den Stack (ddev, Vite, SCSS-Funktionen, Build, Deployment), gehört sie ins Toolkit und wird mit dessen nächstem Release verteilt. Betrifft sie nur eine CMS-Sorte, gehört sie in deren Datei im Toolkit. Betrifft sie nur dieses Projekt, gehört sie unter diesen Block.
+
+### Stack
+
+- **ddev** — lokale Entwicklungsumgebung.
+- **npm immer über ddev** aufrufen: `ddev npm run dev`, `ddev npm install`, `ddev npm run release:staging`. Nie auf dem Host: Der Container legt die Node-Version über `nodejs_version` in `.ddev/config.yaml` fest, damit lokal dasselbe gebaut wird wie auf dem Server. Dass ein Build auf dem Host durchläuft, heisst nicht, dass er dort hingehört.
+- **Bricht ein Build mit `Killed` ab, ohne Fehlermeldung**, ist der Speicher der Colima-VM ausgegangen und nicht der Code kaputt: Die VM hat keinen Swap, der Linux-OOM-Killer schickt sofort `SIGKILL`. Prüfen mit `ddev exec free -m`; Abhilfe ist `colima stop && colima start --memory 8` oder das Schliessen speicherhungriger Programme — nicht das Ausweichen auf den Host.
+- **Vite** — Build-Tool für JS und SCSS.
+
+### JavaScript
+
+- **Klassen bevorzugen** mit private Fields per `#`-Prefix — nie Underscore-Konvention (`_field`).
+- **Singleton-Pattern** für Utilities, die global einmalig sind (analog zu `MediaQueries`, `MenuToggle`).
+
+### Custom Events und Data-Attributes
+
+- Zustandskommunikation zwischen Komponenten über `CustomEvent`, nicht direkte Methodenaufrufe.
+- Event-Namenskonvention: `event` + PascalCase → `eventMenuStatus`, `eventBodyScrolled`.
+- DOM-Zustand per `data-*`-Attribut, nie als CSS-Klassen-Toggle: `document.body.setAttribute('data-menu-active', 'true')`.
+
+### SCSS
+
+- Nie direkte `px`-, `vw`- oder `rem`-Werte — ausschliesslich Toolkit-Funktionen: `size()`, `columns()`, `font()`, `marginPadding()`.
+- `src/config.json` ist die einzige Quelle für Breakpoints, Layouts, Farben — nie im Code hardcodieren.
+- 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.
+
+#### 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.
+
+**Wichtig bei vwBasis "body"**: Werte aus `size()`, `columns()`, `marginPadding()` sind dann CSS-`calc()`-Ausdrücke. Sass kann sie ausserhalb eines `calc()`-Wrappers nicht arithmetisch kombinieren. Statt `($a - $b)` mit Sass-Parens → `calc($a - $b)`. Auch im Default-Modus ist diese Schreibweise unschädlich, also generell als Konvention nutzen.
+
+#### Capsize
+
+Optionale pixel-präzise Schriftpositionierung via `@capsizecss/core` (Em-Trims an `::before`/`::after`). Capsize wird zur Sass-Compile-Zeit über eine Custom-Function direkt aufgerufen — keine Algorithmus-Reimplementierung, Updates aus dem Capsize-Paket fliessen mit.
+
+Setup im Konsumenten:
+
+1. `@capsizecss/unpack` und `@capsizecss/core` als devDependency installieren.
+2. In `src/config.json` Top-Level-Feld `fonts` ergänzen: Map Name → Pfad zur Font-Datei.
+3. In `vite.config.js`:
+
+    ```js
+    import { createCapsizeFunctions } from '@profitlich/template-toolkit/vite/capsizeSassFunctions';
+    // defineConfig async:
+    const capsizeFunctions = await createCapsizeFunctions(configJson.fonts ?? {});
+    // dann: css.preprocessorOptions.scss.functions = capsizeFunctions;
+    ```
+
+4. Pro `@include font(...)` als 4. Argument den Font-Namen aus `fonts` mitgeben — Trims werden emittiert. Ohne Argument: kein Capsize-Output (Default).
+
+`font-weight` wird nicht mehr vom `font()`-Mixin gesetzt — direkt im CSS deklarieren (meist breakpoint-übergreifend).
+
+**SCSS-Organisation**: `scss/core/capsize.scss` enthält das `capsize`-Mixin (emittiert Pseudo-Elemente). `font()` in `layout.scss` ruft es intern auf, wenn das 4. Argument gesetzt ist. Du kannst das Mixin auch direkt nutzen, falls du Capsize ohne `font()` brauchst:
+
+```scss
+.foo { @include capsize("soehne", 40, 45); }
+```
+
+**Cap-Höhe als SCSS-Wert**: `capsize-cap-height($name, $fontSize)` liefert die Cap-Höhe als unitless Zahl (Design-Pixel). Nutzbar für eigene Berechnungen, z. B. paddings, die zum Grid passen sollen:
+
+```scss
+$cap: capsize-cap-height("soehne", 40);  // → font-spezifischer Wert
+padding-top: size($layout, 40 - $cap + 8);
+```
+
+### 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.
+
+### Bilder
+
+Kein `lazysizes`. Ausschliesslich natives `loading="lazy"`.

package/components/menu-toggle/MenuToggle.js

@@ -6,6 +6,7 @@ import './menu-toggle.scss';
  * @property {string}  menuSelector             CSS-Selektor (`querySelector`) des Menü-Containers.
  * @property {string}  menuLinkSelector         CSS-Selektor für Menü-Links, die das Menü beim Klick schliessen (z.B. '.menu-link').
  * @property {string}  menuItemSelector         CSS-Selektor des Menü-Wrappers; Klicks ausserhalb schliessen das Menü (z.B. '.menu').
+ * @property {boolean} [linkClickClosesMenu=true] Wenn `false`, bleibt das Menü beim Klick auf einen `menuLinkSelector`-Link offen. Default `true` = Menü schliesst beim Link-Klick.
  * @property {string} [shiftElementSelector]    Optional: CSS-Selektor des Elements, das beim Öffnen um die Scrollbar-Breite verschoben/verbreitert wird, damit z.B. ein fixierter Header nicht springt.
  * @property {number} [shiftDelay=0]            Verzögerung in Sekunden, bevor Scrollbar gemessen und Body fixiert wird – nützlich, wenn vorher noch eine CSS-Animation läuft, die die Scrollbar entfernt.
  * @property {boolean} [deferPositionFixed=false] Setzt `data-menu-fixed` erst nach `shiftDelay` statt sofort. Nötig, wenn das Fixieren eine laufende Öffnungs-Animation stören würde.
@@ -19,6 +20,7 @@ export class MenuToggle {
     #menu;
     #menuLinkSelector;
     #menuItemSelector;
+    #linkClickClosesMenu;
     #scrollbarWidth;
     #shiftElement;
     #shiftDelay;
@@ -40,6 +42,7 @@ export class MenuToggle {
         menuSelector,
         menuLinkSelector,
         menuItemSelector,
+        linkClickClosesMenu = true,
         shiftElementSelector = null,
         shiftDelay = 0,
         deferPositionFixed = false,
@@ -50,6 +53,7 @@ export class MenuToggle {
         this.#menu = document.querySelector(menuSelector);
         this.#menuLinkSelector = menuLinkSelector;
         this.#menuItemSelector = menuItemSelector;
+        this.#linkClickClosesMenu = linkClickClosesMenu;
         this.#shiftElement = shiftElementSelector ? document.querySelector(shiftElementSelector) : null;
         this.#shiftDelay = shiftDelay * 1000;
         this.#deferPositionFixed = deferPositionFixed;
@@ -71,7 +75,7 @@ export class MenuToggle {
         });
 
         this.#menu.addEventListener('click', (event) => {
-            if (this.isActive && event.target.matches(this.#menuLinkSelector)) {
+            if (this.#linkClickClosesMenu && this.isActive && event.target.matches(this.#menuLinkSelector)) {
                 this.#toggleMenu();
             }
         });

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@profitlich/template-toolkit",
-    "version": "5.3.1",
+    "version": "5.5.0",
     "description": "Shared SCSS layout system, JS utilities, components and build scripts for profitlich template repos",
     "type": "module",
     "sass": "scss/forward.scss",
@@ -27,6 +27,9 @@
         "./vite/capsizeSassFunctions": "./vite/capsizeSassFunctions.js"
     },
     "files": [
+        "CLAUDE.project.md",
+        "CLAUDE.craftcms.md",
+        "CLAUDE.kirbycms.md",
         "components/",
         "dev/",
         "scss/",

package/scripts/copy-files.js

@@ -2,6 +2,7 @@ import fs from 'fs-extra';
 import { glob } from 'glob';
 import path from 'path';
 import chokidar from 'chokidar';
+import { syncConventions } from './sync-conventions.js';
 
 /**
  * @typedef {Object} CopyTask
@@ -78,17 +79,28 @@ export function watchFiles(copyTasks, watchDir = 'src') {
  * Run the copy-files script.
  * Liest `process.argv[2]`: `dev` startet einmal `copyAll` und danach `watchFiles`,
  * `build` führt `copyAll` einmal aus.
+ *
+ * Übernimmt vorab die geerbten Konventionen in die `CLAUDE.md` des Projekts —
+ * hier statt in jedem Projekt einzeln verdrahtet, damit bestehende Projekte
+ * nichts anpassen müssen. Ohne Marken in der Zieldatei passiert nichts.
  * @param {CopyTask[]} copyTasks
  * @param {Object}   [options]
  * @param {string}   [options.watchDir='src'] - Im Dev-Mode beobachtetes Verzeichnis.
+ * @param {string}   [options.template] - Sorte für den Konventionsblock, z.B. `craftcms`.
+ * @param {boolean}  [options.syncConventions=true] - Konventionsblock schreiben.
  */
 export function run(copyTasks, options = {}) {
     const command = process.argv[2];
     const watchDir = options.watchDir || 'src';
 
+    const vorlauf = options.syncConventions === false
+        ? Promise.resolve()
+        : syncConventions({ template: options.template })
+            .catch(err => console.error('Konventionen nicht übernommen:', err));
+
     if (command === 'dev') {
-        copyAll(copyTasks).then(() => watchFiles(copyTasks, watchDir));
+        vorlauf.then(() => copyAll(copyTasks)).then(() => watchFiles(copyTasks, watchDir));
     } else if (command === 'build') {
-        copyAll(copyTasks);
+        vorlauf.then(() => copyAll(copyTasks));
     }
 }

package/scripts/sync-conventions.js

@@ -0,0 +1,89 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const paketWurzel = fileURLToPath(new URL('../', import.meta.url));
+const paketDatei = path.join(paketWurzel, 'package.json');
+
+const markeStart = '<!-- toolkit:start';
+const markeEnde = '<!-- toolkit:end -->';
+
+/**
+ * Schreibt die geerbten Konventionen in die `CLAUDE.md` des Projekts.
+ *
+ * Claude liest keine Dateien aus `node_modules`. Die Konventionen müssen also
+ * im Repo liegen — kopiert statt verlinkt. Ersetzt wird ausschliesslich der
+ * Bereich zwischen den Marken; alles davor und dahinter ist Projekteigentum
+ * und bleibt unangetastet.
+ *
+ * Der Block hängt an der *installierten* Toolkit-Version, nicht am neuesten
+ * Stand: Ein Projekt zieht Änderungen erst, wenn es die Version hebt und einmal
+ * baut. Die Änderung erscheint dann als git-Diff in der Projektdatei — sichtbar
+ * und überprüfbar, statt still.
+ *
+ * Fehlt die Zieldatei oder fehlen die Marken, passiert nichts. Das Skript legt
+ * bewusst nichts an: Ein Projekt ohne Marken hat sich gegen den Block
+ * entschieden, und diese Entscheidung zu überschreiben wäre schlimmer, als sie
+ * zu ignorieren.
+ *
+ * Zwei Quellen: `CLAUDE.project.md` gilt für alle Projekte, `CLAUDE.<template>.md`
+ * zusätzlich für die jeweilige Sorte. Getrennte Dateien, ein Transportweg — das
+ * Paket ist an eine Version gebunden, ein lokal geklontes Template-Repo dagegen
+ * kann veraltet sein, ohne dass es auffällt.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.target='CLAUDE.md'] - Zieldatei, relativ zum Projektverzeichnis.
+ * @param {string} [options.template] - Sorte, z.B. `craftcms` oder `kirbycms`.
+ * @returns {Promise<boolean>} `true`, wenn geschrieben wurde.
+ */
+export async function syncConventions(options = {}) {
+    const zielPfad = path.resolve(options.target ?? 'CLAUDE.md');
+
+    const quellDateien = [path.join(paketWurzel, 'CLAUDE.project.md')];
+    if (options.template) {
+        quellDateien.push(path.join(paketWurzel, `CLAUDE.${options.template}.md`));
+    }
+
+    const abschnitte = [];
+    for (const datei of quellDateien) {
+        // Ältere Toolkit-Versionen bringen die Dateien nicht mit; eine unbekannte
+        // Sorte soll den Lauf nicht abbrechen, sondern nur nichts beitragen
+        if (await fs.pathExists(datei)) {
+            abschnitte.push((await fs.readFile(datei, 'utf-8')).trim());
+        }
+    }
+
+    if (abschnitte.length === 0) return false;
+
+    if (!await fs.pathExists(zielPfad)) {
+        console.log(`ℹ️  ${path.basename(zielPfad)} nicht gefunden — Konventionen nicht übernommen.`);
+        return false;
+    }
+
+    const ziel = await fs.readFile(zielPfad, 'utf-8');
+    const start = ziel.indexOf(markeStart);
+    const ende = start === -1 ? -1 : ziel.indexOf(markeEnde, start);
+
+    if (start === -1 || ende === -1) {
+        console.log(`ℹ️  Keine Toolkit-Marken in ${path.basename(zielPfad)} — Konventionen nicht übernommen.`);
+        console.log(`   Einfügen, wo der Block stehen soll:  ${markeStart} -->  …  ${markeEnde}`);
+        return false;
+    }
+
+    const { version } = await fs.readJson(paketDatei);
+    const sorte = options.template ? ` + ${options.template}` : '';
+
+    const block = `${markeStart} ${version}${sorte} — erzeugt aus @profitlich/template-toolkit, nicht von Hand ändern -->\n`
+        + `${abschnitte.join('\n\n')}\n`
+        + markeEnde;
+
+    const neu = ziel.slice(0, start) + block + ziel.slice(ende + markeEnde.length);
+
+    // Nur schreiben, wenn sich etwas ändert — sonst stünde nach jedem Build eine
+    // veränderte Datei im git status, ohne dass sich der Inhalt unterscheidet
+    if (neu === ziel) return false;
+
+    await fs.writeFile(zielPfad, neu);
+    console.log(`🔄 ${path.basename(zielPfad)}: Konventionen aus Toolkit ${version} übernommen.`);
+    return true;
+}

package/scss/core/capsize.scss

@@ -1,14 +1,22 @@
+@use "sass:meta";
+
 // 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).
 @mixin capsize($name, $fontSize, $lineHeight) {
-    $pseudo: capsize-pseudo-elements($name, $fontSize, $lineHeight);
-    @each $selector-suffix, $props in $pseudo {
-        &#{$selector-suffix} {
-            @each $prop, $val in $props {
-                #{$prop}: $val;
+    // Capsize ist opt-in: ohne registrierte Custom-Function wird übersprungen,
+    // damit ein fehlender Vite-Setup nicht zu kryptischem Sass-Fehler führt.
+    @if not meta.function-exists("capsize-pseudo-elements") {
+        @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);
+        @each $selector-suffix, $props in $pseudo {
+            &#{$selector-suffix} {
+                @each $prop, $val in $props {
+                    #{$prop}: $val;
+                }
             }
         }
     }

package/scss/core/layout.scss

@@ -88,7 +88,12 @@ $mediaqueries: (
     line-height: size($layout, $lineHeight);
 
     @if ($capsize != null) {
-        @include capsize($capsize, $fontSize, $lineHeight);
+        // 4. Argument ist der Capsize-Font-Name (String). Frühere API hatte hier font-weight.
+        @if meta.type-of($capsize) != 'string' {
+            @warn "font(): 4. Argument (Capsize-Font-Name) muss ein String sein, erhalten #{meta.type-of($capsize)} \"#{$capsize}\". Vermutlich Altlast aus früherer API (font-weight). Capsize wird übersprungen.";
+        } @else {
+            @include capsize($capsize, $fontSize, $lineHeight);
+        }
     }
 
 }