@profitlich/template-toolkit 5.4.0 → 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/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@profitlich/template-toolkit",
-    "version": "5.4.0",
+    "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;
+}