@profitlich/template-toolkit 4.2.0 → 5.2.0

package/components/menu-toggle/MenuToggle.js

@@ -1,16 +1,30 @@
 import './menu-toggle.scss';
 
+/**
+ * @typedef {Object} MenuToggleOptions
+ * @property {string}  menuButtonSelector       CSS-Selektor (`querySelector`) des Buttons, der das Menü öffnet/schliesst.
+ * @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 {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.
+ * @property {boolean} [lockScroll=true]        Wenn `false`, bleibt das fixierende Element scrollbar; kein Scrollbar-Ausgleich und kein Shift. Für Menüs, die nur einen Teil der Seite bedecken und Hintergrund-Scroll erlauben sollen.
+ * @property {string} [fixElementSelector]      Optional: CSS-Selektor des Elements, das beim Öffnen fixiert wird (`position: fixed`, Scrollbar-Ausgleich, Scroll-Position-Trick). Default: `document.body`.
+ */
+
 export class MenuToggle {
     static #instance;
     #menuButton;
     #menu;
     #menuLinkSelector;
-    #menuItemClass;
+    #menuItemSelector;
     #scrollbarWidth;
     #shiftElement;
     #shiftDelay;
     #deferPositionFixed;
-    #fixBody;
+    #lockScroll;
+    #fixElement;
     #y;
     #bodyClickHandler;
     #resizeHandler;
@@ -18,34 +32,28 @@ export class MenuToggle {
     isActive;
 
     /**
-     * @param {Object}  options
-     * @param {string}  options.menuButtonId        ID des Buttons, der das Menü öffnet/schliesst.
-     * @param {string}  options.menuId              ID des Menü-Containers.
-     * @param {string}  options.menuLinkSelector    Selektor für Menü-Links, die das Menü beim Klick schliessen (z.B. '.menu-link').
-     * @param {string}  options.menuItemClass       Klassenname (ohne Punkt) des Menü-Wrappers; Klicks ausserhalb schliessen das Menü.
-     * @param {string?} options.shiftElementId      Optional: Element, das beim Öffnen um die Scrollbar-Breite verschoben/verbreitert wird, damit z.B. ein fixierter Header nicht springt.
-     * @param {number}  options.shiftDelay          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.
-     * @param {boolean} options.deferPositionFixed  Setzt `data-menu-fixed` erst nach `shiftDelay` statt sofort. Nötig, wenn das Fixieren eine laufende Öffnungs-Animation stören würde.
-     * @param {boolean} options.fixBody             Wenn `false`, bleibt der Body scrollbar; kein Scrollbar-Ausgleich und kein Shift. Für Menüs, die nur einen Teil der Seite bedecken und Hintergrund-Scroll erlauben sollen.
+     * @param {MenuToggleOptions} options
      */
     constructor({
-        menuButtonId,
-        menuId,
+        menuButtonSelector,
+        menuSelector,
         menuLinkSelector,
-        menuItemClass,
-        shiftElementId = null,
+        menuItemSelector,
+        shiftElementSelector = null,
         shiftDelay = 0,
         deferPositionFixed = false,
-        fixBody = true,
+        lockScroll = true,
+        fixElementSelector = null,
     }) {
-        this.#menuButton = document.getElementById(menuButtonId);
-        this.#menu = document.getElementById(menuId);
+        this.#menuButton = document.querySelector(menuButtonSelector);
+        this.#menu = document.querySelector(menuSelector);
         this.#menuLinkSelector = menuLinkSelector;
-        this.#menuItemClass = menuItemClass;
-        this.#shiftElement = shiftElementId ? document.getElementById(shiftElementId) : null;
+        this.#menuItemSelector = menuItemSelector;
+        this.#shiftElement = shiftElementSelector ? document.querySelector(shiftElementSelector) : null;
         this.#shiftDelay = shiftDelay * 1000;
         this.#deferPositionFixed = deferPositionFixed;
-        this.#fixBody = fixBody;
+        this.#lockScroll = lockScroll;
+        this.#fixElement = fixElementSelector ? document.querySelector(fixElementSelector) : document.body;
         this.#scrollbarWidth = 0;
         this.isActive = false;
         this.#y = 0;
@@ -68,13 +76,20 @@ export class MenuToggle {
 
         this.#setBodyAttribute('data-menu-active', 'false');
         this.#setBodyAttribute('data-menu-moving', 'false');
-        this.#setBodyAttribute('data-menu-fixed', 'false');
+        this.#fixElement.setAttribute('data-menu-fixed', 'false');
     }
 
+    /**
+     * Holt die Singleton-Instanz. Beim ersten Aufruf müssen die Pflicht-Optionen
+     * (`menuButtonSelector`, `menuSelector`, `menuLinkSelector`, `menuItemSelector`)
+     * gesetzt sein; spätere Aufrufe ignorieren übergebene Optionen.
+     * @param {MenuToggleOptions} [options]
+     * @returns {MenuToggle}
+     */
     static getInstance(options) {
         if (!MenuToggle.#instance) {
-            if (!options || !options.menuButtonId || !options.menuId || !options.menuLinkSelector || !options.menuItemClass) {
-                throw new Error("MenuToggle muss beim ersten Aufruf mit menuButtonId, menuId, menuLinkSelector und menuItemClass initialisiert werden.");
+            if (!options || !options.menuButtonSelector || !options.menuSelector || !options.menuLinkSelector || !options.menuItemSelector) {
+                throw new Error("MenuToggle muss beim ersten Aufruf mit menuButtonSelector, menuSelector, menuLinkSelector und menuItemSelector initialisiert werden.");
             }
             MenuToggle.#instance = new MenuToggle(options);
         }
@@ -87,14 +102,14 @@ export class MenuToggle {
             document.body.removeEventListener('click', this.#bodyClickHandler);
             window.removeEventListener('resize', this.#resizeHandler);
             this.#setBodyAttribute('data-menu-active', 'false');
-            if (this.#fixBody) {
-                this.#setBodyAttribute('data-menu-fixed', 'false');
+            if (this.#lockScroll) {
+                this.#fixElement.setAttribute('data-menu-fixed', 'false');
                 if (this.#shiftElement) {
                     this.#shiftElement.style.marginRight = '';
                     this.#shiftElement.style.width = '';
                 }
-                document.body.style.paddingRight = '';
-                document.body.style.top = '';
+                this.#fixElement.style.paddingRight = '';
+                this.#fixElement.style.top = '';
                 window.scrollTo(0, this.#y);
             }
             this.#toggleEscape(false);
@@ -102,19 +117,19 @@ export class MenuToggle {
             this.isActive = true;
             document.body.addEventListener('click', this.#bodyClickHandler);
             this.#setBodyAttribute('data-menu-active', 'true');
-            if (this.#fixBody) {
+            if (this.#lockScroll) {
                 window.addEventListener('resize', this.#resizeHandler);
                 this.#setBodyAttribute('data-menu-moving', 'true');
                 if (!this.#deferPositionFixed) {
-                    this.#setBodyAttribute('data-menu-fixed', 'true');
+                    this.#fixElement.setAttribute('data-menu-fixed', 'true');
                 }
                 setTimeout(() => {
                     this.#scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
                     this.#y = window.scrollY;
-                    document.body.style.paddingRight = `${this.#scrollbarWidth}px`;
-                    document.body.style.top = `-${this.#y}px`;
+                    this.#fixElement.style.paddingRight = `${this.#scrollbarWidth}px`;
+                    this.#fixElement.style.top = `-${this.#y}px`;
                     if (this.#deferPositionFixed) {
-                        this.#setBodyAttribute('data-menu-fixed', 'true');
+                        this.#fixElement.setAttribute('data-menu-fixed', 'true');
                     }
                     if (this.#shiftElement) {
                         const marginOriginal = parseFloat(window.getComputedStyle(this.#menuButton).marginRight);
@@ -138,7 +153,7 @@ export class MenuToggle {
     }
 
     #onBodyClick(event) {
-        if (this.isActive && !event.target.closest('.' + this.#menuItemClass)) {
+        if (this.isActive && !event.target.closest(this.#menuItemSelector)) {
             this.#toggleMenu();
         }
     }

package/components/menu-toggle/menu-toggle.scss

@@ -1,16 +1,12 @@
-body {
-
-    &[data-menu-fixed="true"] {
-        position: fixed;
-        width: 100%;
-    }
+[data-menu-fixed="true"] {
+    position: fixed;
+    width: 100%;
+}
 
-    &[data-menu-active="true"] {
-        // Bedeckt das Menü nur einen Teil der Seite, ist also ein Teil der Seite weiterhin zu sehen,
-        // soll die Maus Interaktionen ausserhalb des Menüs ignorieren
-        .main {
-            pointer-events: none;
-        }
+body[data-menu-active="true"] {
+    // Bedeckt das Menü nur einen Teil der Seite, ist also ein Teil der Seite weiterhin zu sehen,
+    // soll die Maus Interaktionen ausserhalb des Menüs ignorieren
+    .main {
+        pointer-events: none;
     }
-
 }

package/components/mux-player/MuxPlayer.js

@@ -1,6 +1,16 @@
 import '@mux/mux-player';
 import './mux-player.scss';
 
+/**
+ * @typedef {Object} MuxPlayerOptions
+ * @property {boolean} [loop=false]            Wiederholt das Video nach Ende.
+ * @property {boolean} [noLowRes=false]        Setzt `minResolution` anhand der physischen Container-Grösse, damit auf hochauflösenden Displays keine zu kleine Auflösung gespielt wird.
+ * @property {((player: HTMLElement, container: HTMLElement) => void)} [onPlayerCreated] Callback, der nach jedem Lazy-Load-Setup aufgerufen wird (unabhängig von Autoplay).
+ * @property {boolean} [disableTracking=false] Setzt das `disable-tracking`-Attribut am Player — verhindert das Mux-Data-Tracking.
+ * @property {string}  [envKey]                Mux-Data-Env-Key. Nur wirksam, wenn `disableTracking=false`.
+ * @property {Object}  [metadata]              Mux-Data-Metadata-Objekt. Nur wirksam, wenn `envKey` gesetzt ist.
+ */
+
 /**
  * Lädt Mux-Videos lazy und steuert Autoplay per IntersectionObserver.
  *
@@ -30,6 +40,9 @@ export class MuxPlayer {
     #envKey;
     #metadata;
 
+    /**
+     * @param {MuxPlayerOptions} [options]
+     */
     constructor({
         loop = false,
         noLowRes = false,

package/dev/Dev.js

@@ -3,7 +3,8 @@ import { Toolbar } from './toolbar/Toolbar.js';
 let _config = {};
 
 /**
-* @param {Object} config - Aus config.json des Projekts
+ * Hinterlegt die Projekt-Config für die Dev-Toolbar.
+ * @param {Object} [config={}] - Inhalt von `src/config.json` des Projekts.
  */
 export function initDev(config = {}) {
     _config = config;

package/dev/toolbar/Toolbar.js

@@ -2,6 +2,10 @@ import GUI from 'lil-gui';
 import { MediaQueries } from '../../utils/MediaQueries.js';
 import './toolbar.scss';
 
+/**
+ * Dev-Toolbar (lil-gui) mit Grid-Overlay, Bildgrössen- und Inhaltstyp-Labels.
+ * State wird in `localStorage.devTools` persistiert. Toggle via `Ctrl`.
+ */
 export class Toolbar {
     #mediaQueries = MediaQueries.getInstance();
     #gui;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@profitlich/template-toolkit",
-    "version": "4.2.0",
+    "version": "5.2.0",
     "description": "Shared SCSS layout system, JS utilities, components and build scripts for profitlich template repos",
     "type": "module",
     "sass": "scss/forward.scss",
@@ -45,7 +45,7 @@
     },
     "peerDependencies": {
         "@capsizecss/core": ">=4.0.0",
-        "@capsizecss/unpack": ">=2.0.0",
+        "@capsizecss/unpack": ">=4.0.0",
         "@mux/mux-player": ">=3.0.0"
     },
     "peerDependenciesMeta": {

package/scripts/copy-files.js

@@ -3,6 +3,14 @@ import { glob } from 'glob';
 import path from 'path';
 import chokidar from 'chokidar';
 
+/**
+ * @typedef {Object} CopyTask
+ * @property {string} name - Anzeigename des Tasks (für Logs).
+ * @property {string} src  - Glob-Pattern der Quelldateien.
+ * @property {string} dest - Zielverzeichnis.
+ * @property {string} base - Basis-Pfad; relative Pfade werden ausgehend davon erhalten.
+ */
+
 async function runTask(task) {
     const files = await glob(task.src, { nodir: true, dot: true });
     if (files.length === 0) return;
@@ -14,6 +22,11 @@ async function runTask(task) {
     }
 }
 
+/**
+ * Leert alle Ziel-Verzeichnisse und kopiert anschliessend alle Quelldateien
+ * jedes Tasks parallel ins jeweilige Ziel.
+ * @param {CopyTask[]} copyTasks
+ */
 export async function copyAll(copyTasks) {
     console.log('🚀 Starting initial copy of all files...');
     // empty folders to prevent orphaned files
@@ -25,6 +38,11 @@ export async function copyAll(copyTasks) {
     console.log('✅ Initial copy complete.');
 }
 
+/**
+ * Beobachtet `watchDir` und führt bei jeder Änderung `copyAll` aus.
+ * @param {CopyTask[]} copyTasks
+ * @param {string} [watchDir='src']
+ */
 export function watchFiles(copyTasks, watchDir = 'src') {
     console.log(`👀 Watching for file changes in ${watchDir}/`);
 
@@ -58,9 +76,11 @@ export function watchFiles(copyTasks, watchDir = 'src') {
 
 /**
  * Run the copy-files script.
- * @param {Array} copyTasks - array of { name, src, dest, base } objects
- * @param {object} [options] - optional settings
- * @param {string} [options.watchDir] - directory to watch (default: 'src')
+ * Liest `process.argv[2]`: `dev` startet einmal `copyAll` und danach `watchFiles`,
+ * `build` führt `copyAll` einmal aus.
+ * @param {CopyTask[]} copyTasks
+ * @param {Object}   [options]
+ * @param {string}   [options.watchDir='src'] - Im Dev-Mode beobachtetes Verzeichnis.
  */
 export function run(copyTasks, options = {}) {
     const command = process.argv[2];

package/scripts/deploy.js

@@ -6,6 +6,20 @@ import fs from 'fs/promises';
 import readline from 'readline';
 import cliProgress from 'cli-progress';
 
+/**
+ * @typedef {Object} UploadTask
+ * @property {string}   name           - Anzeigename des Tasks (für Logs).
+ * @property {string}   localPattern   - Glob-Pattern der hochzuladenden Dateien.
+ * @property {string}   localBase      - Basis-Pfad; relative Pfade werden auf den `remoteDir` gemappt.
+ * @property {string}   remoteDir      - Ziel-Verzeichnis auf dem FTP-Server.
+ * @property {string|string[]} [ignore] - Glob-Pattern, die vom Upload ausgeschlossen werden.
+ */
+
+/**
+ * @typedef {Object} DeployOptions
+ * @property {number} [parallel=3] - Anzahl paralleler FTP-Verbindungen. `1` deaktiviert Parallelität.
+ */
+
 // Helper for making sure the upload progress bars go to 100%
 const delay = ms => new Promise(resolve => setTimeout(resolve, ms));
 
@@ -35,6 +49,13 @@ async function createClient(accessOptions) {
     return client;
 }
 
+/**
+ * Lädt die in `uploadTasks` definierten Dateien per FTP hoch.
+ * Liest `FTP_HOST_<MODE>`, `FTP_USER_<MODE>`, `FTP_PASSWORD_<MODE>` aus dem env.
+ * @param {'staging'|'production'} mode
+ * @param {UploadTask[]} uploadTasks
+ * @param {DeployOptions} [options]
+ */
 export async function runDeploy(mode, uploadTasks, options = {}) {
     const parallel = options.parallel ?? 3;
     const modeUpper = mode.toUpperCase();
@@ -198,8 +219,10 @@ export async function runDeploy(mode, uploadTasks, options = {}) {
 
 /**
  * Run the deploy script.
- * @param {Array} uploadTasks - array of { name, localPattern, localBase, remoteDir, ignore? }
- * @param {Object} options - { parallel: number } (default: { parallel: 3 })
+ * Liest `process.argv[2]` (`'staging'` oder `'production'`) als Mode.
+ * Im Production-Mode wird vorher um Bestätigung gefragt.
+ * @param {UploadTask[]} uploadTasks
+ * @param {DeployOptions} [options]
  */
 export function run(uploadTasks, options = {}) {
     const mode = process.argv[2];

package/utils/BodyScrolled.js

@@ -1,7 +1,7 @@
 /**
- * after scroll set body attribute data-scrolled to true
+ * Setzt beim ersten Scroll-Event das Body-Attribut `data-body-scrolled="true"`
+ * und feuert das Custom-Event `eventBodyScrolled`. Einmal pro Seitenaufruf.
  */
-
 export class BodyScrolled {
     static #instance;
 
@@ -22,6 +22,10 @@ export class BodyScrolled {
 
     }
 
+    /**
+     * Holt die Singleton-Instanz und initialisiert beim ersten Aufruf den Scroll-Listener.
+     * @returns {BodyScrolled}
+     */
     static getInstance() {
         if (!BodyScrolled.#instance) {
             BodyScrolled.#instance = new BodyScrolled();

package/utils/MailAdresses.js

@@ -1,8 +1,15 @@
+/**
+ * Setzt `href` und Linktext aller Elemente mit `data-eml="local-part"` auf
+ * `local-part@domain` (Spam-Schutz: Adresse erst per JS zusammengesetzt).
+ */
 export class MailAdresses {
     static #instance;
 
     #domain;
 
+    /**
+     * @param {string} domain - Domain-Teil der E-Mail-Adressen (z.B. 'example.com')
+     */
     constructor(domain) {
         this.#domain = domain;
         this.init();
@@ -18,6 +25,11 @@ export class MailAdresses {
         });
     }
 
+    /**
+     * Holt die Singleton-Instanz. Beim ersten Aufruf muss `domain` übergeben werden.
+     * @param {string} [domain]
+     * @returns {MailAdresses}
+     */
     static getInstance(domain) {
         if (!MailAdresses.#instance) {
             MailAdresses.#instance = new MailAdresses(domain);

package/utils/MediaQueries.js

@@ -1,6 +1,11 @@
-/**Media queries
- * https://kinsta.com/blog/javamediaqueryipt-media-query/
- * option 3 on the linked page
+/**
+ * Verwaltet Layout-Wechsel anhand von Breakpoints. Setzt `data-layout` am Body
+ * und feuert das Custom-Event `eventLayoutchange` bei jedem Wechsel.
+ * Siehe https://kinsta.com/blog/javamediaqueryipt-media-query/ (Option 3).
+ *
+ * @typedef {Object<string, number|null>} BreakpointsConfig
+ *   Map: Layout-Name → minimale Viewport-Breite in Pixeln (oder `null` für das kleinste Layout).
+ *   Reihenfolge der Keys bestimmt die Layout-Priorität (späteres Match überschreibt früheres).
  */
 
 export class MediaQueries {
@@ -8,6 +13,9 @@ export class MediaQueries {
     layout = 'desktop';
     #breakpoints;
 
+    /**
+     * @param {BreakpointsConfig} breakpoints
+     */
     constructor(breakpoints) {
         this.#breakpoints = breakpoints;
         this.layout = 'desktop';
@@ -15,6 +23,11 @@ export class MediaQueries {
         this.#matchmedia();
     }
 
+    /**
+     * Holt die Singleton-Instanz. Beim ersten Aufruf müssen `breakpoints` übergeben werden.
+     * @param {BreakpointsConfig} [breakpoints]
+     * @returns {MediaQueries}
+     */
     static getInstance(breakpoints) {
         if (!MediaQueries.#instance) {
             if (!breakpoints) {

package/utils/Vh100.js

@@ -1,8 +1,8 @@
 /**
- * 100vh problem
+ * Setzt die CSS Custom Property `--vh` auf 1% der aktuellen Viewport-Höhe und
+ * aktualisiert bei Resize. Workaround für mobiles 100vh.
  * https://css-tricks.com/the-trick-to-viewport-units-on-mobile/
  */
-
 export class Vh100 {
     static #instance;
     vh = 0;
@@ -22,6 +22,10 @@ export class Vh100 {
         document.documentElement.style.setProperty('--vh', `${this.vh}px`);
     }
 
+    /**
+     * Holt die Singleton-Instanz und initialisiert beim ersten Aufruf den Resize-Listener.
+     * @returns {Vh100}
+     */
     static getInstance() {
         if (!Vh100.#instance) {
             Vh100.#instance = new Vh100();

package/utils/VwBody.js

@@ -18,6 +18,10 @@ export class VwBody {
         document.documentElement.style.setProperty('--vw-body', `${this.vw}px`);
     }
 
+    /**
+     * Holt die Singleton-Instanz und initialisiert beim ersten Aufruf den Resize-Listener.
+     * @returns {VwBody}
+     */
     static getInstance() {
         if (!VwBody.#instance) {
             VwBody.#instance = new VwBody();

package/utils/images-loaded/ImagesLoaded.js

@@ -9,6 +9,11 @@ export class ImagesLoaded {
     #attributeName;
     #attributeValue;
 
+    /**
+     * @param {string} selector              CSS-Selektor der zu beobachtenden `<img>`-Elemente.
+     * @param {string} [loadedAttribute='data-loaded']  Attribut, das den Ladestatus signalisiert.
+     * @param {string} [loadedValue='true']  Wert, der bei erfolgreichem Laden gesetzt wird.
+     */
     constructor(selector, loadedAttribute = 'data-loaded', loadedValue = 'true') {
         this.#selector = selector;
         this.#attributeName = loadedAttribute;

package/vite/capsizeSassFunctions.js

@@ -1,4 +1,4 @@
-import { fromFile } from '@capsizecss/unpack';
+import { fromFile } from '@capsizecss/unpack/fs';
 import { createStyleObject, getCapHeight } from '@capsizecss/core';
 import * as sass from 'sass';
 import { OrderedMap } from 'immutable';

package/vite/jsonToScss.js

@@ -1,3 +1,12 @@
+/**
+ * Wandelt ein JSON-Objekt in SCSS-Variablen-Deklarationen um.
+ * Top-Level-Keys werden zu `$key: value;`-Zeilen, verschachtelte Objekte zu
+ * Sass-Maps `(key: value, ...)`. Hex-Farben werden ohne Quotes ausgegeben.
+ * Der Key `README` wird übersprungen.
+ *
+ * @param {Object} json - Quell-Objekt (z.B. Inhalt von `src/config.json`).
+ * @returns {string} SCSS-Source mit einer `$variable: ...;`-Zeile pro Top-Level-Key.
+ */
 export function jsonToScss(json) {
     const toValue = (v) => {
         if (typeof v === 'object' && v !== null) {