@profitlich/template-toolkit 5.5.1 → 5.8.0

package/CLAUDE.project.md

@@ -22,7 +22,78 @@ Dieser Abschnitt stammt aus `@profitlich/template-toolkit` und wird bei jedem `c
 
 - 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')`.
+- DOM-**Zustand** per `data-*`-Attribut, nie als CSS-Klassen-Toggle: `document.body.setAttribute('data-menu-active', 'true')`.
+
+Das betrifft den Zustand eines Elements. Wie ein Skript seine Elemente überhaupt **findet**, regelt der nächste Abschnitt.
+
+### Wie JavaScript seine Elemente findet
+
+Zwei Fragen, die leicht durcheinandergeraten:
+
+*Welches Skript lädt diese Seite?* → immer `craft.vite.register` im Template, das das Markup rendert. Gilt unabhängig von allem Folgenden.
+
+*Woran erkennt das Skript seine Elemente?* → dafür gilt:
+
+> **Wer entscheidet, dort steht es.** Entscheidet der Code, steht der Selektor im Code. Entscheidet der Inhalt, steht es im Markup.
+
+**Klassen-Selektor**, wenn das Verhalten untrennbar zur Komponente gehört — jedes Element dieser Klasse verhält sich immer so, es gibt nichts zu entscheiden:
+
+```js
+new Subcategory('.subcategory');
+new HoverImages('.client-list__link');
+```
+
+**`data`-Attribut**, sobald eine der beiden Bedingungen zutrifft:
+
+1. **Die Redaktion entscheidet, ob.** Ein CMS-Feld schaltet das Verhalten — `module.fixiert` → `data-sticky`, `module.raster` → `data-grid-type`. Der Code kann das nicht wissen.
+2. **Das Element trägt einen Wert**, den das Skript braucht — `data-hover-image`, `data-categories`, `data-map-zoom`.
+
+Fallen beide zusammen, ist der Selektor das Attribut:
+
+```js
+new Grid('[data-grid-type]');
+```
+
+Nicht überall Attribute: Ein `data-swiper="true"` an jeder `.subcategory` wäre eine zweite Stelle zum Ändern und suggeriert eine Wahlmöglichkeit, die es nicht gibt. Nicht überall Selektoren: Redaktionelle Entscheidungen und Werte pro Element kann der Code nicht kennen.
+
+### Entry oder Klassendatei
+
+Eine JS-Datei ist das eine oder das andere, nie beides:
+
+- **Entry** — initialisiert sich selbst auf `DOMContentLoaded` und wird von keinem Modul importiert. Geladen durch `craft.vite.register`.
+- **Klassendatei** — wird importiert und tut nichts, bis jemand sie konstruiert.
+
+Vermischt man beides, wird ein Import zur versteckten Ladeanweisung: Er sieht ungenutzt aus, ist aber das Einzige, was die Funktion startet. Wer ihn entfernt — oder ein Linter, der ihn meldet — legt sie lautlos still.
+
+### Debug-Code
+
+Debug-Code bleibt im Quelltext — man braucht ihn beim nächsten Mal wieder. Er darf nur die **Produktion** nicht erreichen; auf Dev **und Staging** bleibt er vollständig erhalten.
+
+Dafür zwei Hebel, je nach Fall:
+
+- **`console.*`** — entfernt Terser beim Produktions-Build über `drop_console: mode === 'production'` in der `vite.config.js`. Kein Zutun nötig.
+- **Alles andere** (Debug-Ausgaben ins DOM, Messungen, Overlays) — in `if (__DEBUG__) { … }` einschliessen. Vite ersetzt die Konstante zur Bauzeit per `define: { __DEBUG__: mode !== 'production' }`; daraus wird `if (false)`, und der Minifier wirft den Zweig weg.
+
+An `mode` hängen, **nicht** an `import.meta.env.DEV` — Letzteres ist auf Staging bereits `false` und würde den Debug-Code dort verschlucken.
+
+**Debug-Funktionen auf Modulebene schreiben, nicht als private Klassenmethoden.** Der Minifier entfernt zwar in beiden Fällen den Aufruf, schüttelt ungenutzte private Klassenmethoden aber nicht ab — deren Rumpf bliebe im Produktions-Bundle liegen. Als Funktion verschwindet er vollständig.
+
+Ganze Dateien, die nur der Entwicklung dienen, werden gar nicht erst geladen: `{% if craft.app.env != 'production' %}` um die Registrierung, wie bei `Dev.js`.
+
+**Debug-Anzeigen schaltbar machen** — nicht dauerhaft einblenden. Die Dev-Toolbar nimmt dafür projekteigene Checkboxen entgegen:
+
+```js
+// src/Dev.js
+initDev(config, {
+    toggles: [{ key: 'navigateSpace', name: 'Navigate Space' }],
+});
+```
+
+Der Wert steht danach als `body[data-dev-navigate-space="true"]` bereit — für reine CSS-Anzeigen genügt das, weiteres JS braucht es nicht. Module, die auf den Wechsel *reagieren* müssen statt ihn nur darzustellen, hören auf `eventDevToggle` und lesen `event.detail.key` und `event.detail.value`.
+
+Der Schalter ersetzt nicht `__DEBUG__`, er ergänzt es: `__DEBUG__` entscheidet, ob der Code überhaupt ausgeliefert wird, der Schalter, ob man ihn gerade sehen will.
+
+Ist ESLint eingerichtet, braucht `__DEBUG__` einen Eintrag unter `languageOptions.globals`, sonst meldet `no-undef`.
 
 ### SCSS
 

package/dev/Dev.js

@@ -1,16 +1,20 @@
 import { Toolbar } from './toolbar/Toolbar.js';
 
 let _config = {};
+let _options = {};
 
 /**
  * Hinterlegt die Projekt-Config für die Dev-Toolbar.
  * @param {Object} [config={}] - Inhalt von `src/config.json` des Projekts.
+ * @param {import('./toolbar/Toolbar.js').ToolbarOptions} [options={}] - Projekteigene
+ *   Ergänzungen der Toolbar, derzeit `toggles`.
  */
-export function initDev(config = {}) {
+export function initDev(config = {}, options = {}) {
     _config = config;
+    _options = options;
 }
 
 document.addEventListener('DOMContentLoaded', () => {
-    new Toolbar();
+    new Toolbar(_options);
     console.info('Dev initialized.');
 });

package/dev/toolbar/Toolbar.js

@@ -2,6 +2,22 @@ import GUI from 'lil-gui';
 import { MediaQueries } from '../../utils/MediaQueries.js';
 import './toolbar.scss';
 
+/**
+ * Beschreibt eine projekteigene Checkbox in der Dev-Toolbar.
+ * @typedef {Object} ToolbarToggle
+ * @property {string} key - Schlüssel im State und in `localStorage.devTools`.
+ * @property {string} name - Beschriftung in der Toolbar.
+ * @property {string} [attribute] - Data-Attribut am `<body>`. Ohne Angabe aus dem
+ *   Schlüssel abgeleitet: `navigateSpace` → `data-dev-navigate-space`.
+ * @property {boolean} [default=false] - Startwert, solange nichts gespeichert ist.
+ */
+
+/**
+ * Optionen, mit denen ein Projekt die Toolbar erweitert.
+ * @typedef {Object} ToolbarOptions
+ * @property {ToolbarToggle[]} [toggles=[]] - Zusätzliche Checkboxen.
+ */
+
 /**
  * Dev-Toolbar (lil-gui) mit Grid-Overlay, Bildgrössen- und Inhaltstyp-Labels.
  * State wird in `localStorage.devTools` persistiert. Toggle via `Ctrl`.
@@ -12,10 +28,19 @@ export class Toolbar {
     #state;
     #pictureElements;
     #contentTypeContainer;
+    #toggles;
+
+    /**
+     * @param {ToolbarOptions} [options={}] - Projekteigene Ergänzungen.
+     */
+    constructor(options = {}) {
+        this.#toggles = options.toggles ?? [];
 
-    constructor() {
         // State aus localStorage laden
         const defaults = { visible: false, grid: 'aus', imageSize: false, sizes: false, contentType: false };
+        for (const toggle of this.#toggles) {
+            defaults[toggle.key] = toggle.default ?? false;
+        }
         const saved = localStorage.getItem('devTools');
         this.#state = saved ? { ...defaults, ...JSON.parse(saved) } : defaults;
 
@@ -51,6 +76,14 @@ export class Toolbar {
             .name('Inhaltstypen')
             .onChange(() => this.#onStateChange());
 
+        // Projekteigene Schalter ans Ende, damit die Reihenfolge der festen
+        // Einträge über alle Projekte hinweg gleich bleibt
+        for (const toggle of this.#toggles) {
+            this.#gui.add(this.#state, toggle.key)
+                .name(toggle.name)
+                .onChange(() => this.#onStateChange());
+        }
+
         // State anwenden
         this.#applyState();
 
@@ -76,6 +109,7 @@ export class Toolbar {
     #applyState() {
         document.body.setAttribute('data-dev-grid', this.#state.grid);
         document.body.setAttribute('data-dev-content-types', this.#state.contentType);
+        this.#applyToggles();
         this.#updateImageSize();
         this.#updateSizes();
         this.#updateContentTypeLabels();
@@ -95,6 +129,25 @@ export class Toolbar {
         });
     }
 
+    /**
+     * Schreibt jeden projekteigenen Schalter als Data-Attribut ans `<body>` und
+     * meldet ihn zusätzlich per Event.
+     *
+     * Beides, weil beide Seiten gebraucht werden: Das Attribut genügt für reines
+     * CSS und gilt auch für Listener, die es zum Zeitpunkt des Umschaltens noch
+     * nicht gab; das Event erreicht Module, die auf den Wechsel reagieren müssen,
+     * statt ihn nur darzustellen.
+     */
+    #applyToggles() {
+        for (const toggle of this.#toggles) {
+            const value = this.#state[toggle.key];
+            document.body.setAttribute(toggleAttribute(toggle), String(value));
+            document.dispatchEvent(new CustomEvent('eventDevToggle', {
+                detail: { key: toggle.key, value },
+            }));
+        }
+    }
+
     #saveState() {
         localStorage.setItem('devTools', JSON.stringify(this.#state));
     }
@@ -159,3 +212,14 @@ export class Toolbar {
         }
     }
 }
+
+/**
+ * Liefert das Data-Attribut eines Schalters — die explizite Angabe, sonst aus dem
+ * Schlüssel abgeleitet: `navigateSpace` → `data-dev-navigate-space`.
+ * @param {ToolbarToggle} toggle
+ * @returns {string}
+ */
+function toggleAttribute(toggle) {
+    return toggle.attribute
+        ?? `data-dev-${toggle.key.replace(/[A-Z]/g, (char) => `-${char.toLowerCase()}`)}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@profitlich/template-toolkit",
-    "version": "5.5.1",
+    "version": "5.8.0",
     "description": "Shared SCSS layout system, JS utilities, components and build scripts for profitlich template repos",
     "type": "module",
     "sass": "scss/forward.scss",