Utils Handler

Der Utils Handler stellt eine Sammlung wiederverwendbarer Hilfsfunktionen für typische Interaktionen im Frontend bereit. Ziel ist es, wiederkehrende Aufgaben wie Scroll-Erkennung, Tastatur-Shortcuts, Outside-Clicks oder Touch-Gesten über eine einheitliche API zugänglich zu machen, ohne diese Logiken in jedem Projektteil erneut implementieren zu müssen. Alle Methoden arbeiten unabhängig voneinander und können flexibel kombiniert werden, um komplexe Interaktionslogiken abzubilden – beispielsweise in dynamischen Oberflächen, modularen Komponenten oder Single-Page-Anwendungen.

Initialisierung

document.addEventListener('kryzo:ready', async ({ detail: { UTILS } }) => {
    /* Ab hier stellen alle UTILS Funktionen zur Verfügung */
});

Tooltips

Tooltips dienen zur kontextbezogenen Anzeige zusätzlicher Informationen bei Interaktionen wie Hover oder Fokus. Sie werden automatisch aus dem title-Attribut generiert und dynamisch positioniert, abhängig vom verfügbaren Platz im Viewport.

Notwendige CSS Variablen

background: color-mix(in srgb, var(--color), var(--background-color) 90%);
--tooltip-color:        var(--color);
--tooltip-font-size:    0.75rem
--tooltip-padding:      0.3rem 0.5rem;
--tooltip-radius:       0.3rem;

HTML Code

Hover me

Einbindung

/*
    Der Tooltip richtet sich automatisch aus.
    Wenn der Platz für die Anzeige nicht ausreicht, wird
    automatisch eine freie Position für den Tooltip gewählt.
*/
const elements = document.querySelectorAll('[title]');
UTILS.tooltips(elements);

Beispiel

Hover me

scrollNearEnd

Die scrollNearEnd-Methode erkennt, wenn sich ein scrollbarer Container oder der globale Viewport dem unteren Ende nähert. Über einen konfigurierbaren offset kann definiert werden, wie früh vor dem tatsächlichen Ende der Callback ausgelöst wird. Ideal für Lazy Loading, Infinite Scroll oder nachgeladene Inhalte in dynamischen UI-Layouts.

Verwendung

/*
    offset
    - Nummer (px)
    - default: 300
*/
        
// Document direkt oder DOM Element
const element = document;

UTILS.scrollNearEnd(element, {
    offset: 500,
    callback: function () {
        console.log('near end');
    }
});

shortcutEvents

Die shortcut-Methode registriert globale oder elementbasierte Tastatur-Shortcuts und löst ein Callback aus, sobald die definierte Tastenkombination erkannt wird. Unterstützt werden Modifier-Tasten wie ctrl, shift, alt und meta. Die Bindung erfolgt auf dem angegebenen Element oder standardmäßig auf dem Dokument und kann über die zurückgegebene Cleanup-Funktion entfernt werden.

Verwendung

/* 
    element
    - DOM-Element oder document
    - Scope, in dem der Shortcut aktiv ist

    options.keys
    - String (oder später erweiterbar)
    - Tastenkombination im Format:
        'ctrl+s'
        'ctrl+shift+p'
        'alt+enter'
        'escape'

    options.callback
    - Funktion die ausgeführt wird, wenn Shortcut erkannt wurde    

    Sondertasten:
    - ctrl   → Strg (Windows/Linux)
    - shift  → Shift
    - alt    → Alt
    - meta   → Cmd (Mac) / Windows-Key

    Tasten
    - Alle e.key Werte (DOM KeyboardEvent):

    Cleanup:

    Die Funktion gibt eine Destroy-Funktion zurück:
    const destroy = UTILS.shortcut(document, {
        keys: 'ctrl+s',
        callback: save
    });

    // später:
    destroy();

*/

// Document direkt oder DOM Element
// Wenn Document: Event feuert immer
// Wenn DOM Element: Zustand muss „aktiver UI-Kontext“ sein, nicht DOM-Fokus

const element = document;

UTILS.shortcut(element, {
    keys: 'ctrl+s',
    callback: function () {
        console.log('CTRL+S fired');
    }
});

clickOutside

Die clickOutside-Methode bindet eine globale Pointer-Erkennung an das Dokument und löst ein Callback aus, sobald außerhalb des angegebenen Elements geklickt wird. Optional können über ignore gezielt Selektoren definiert werden, die trotz Outside-Klicks keine Aktion auslösen.

Verwendung

/* Element selektieren */
const menu = document.querySelector('menu');

/* Wenn Klick außerhalb des Elemente, Funktion ausführen */
UTILS.clickOutside(menu, {
    ignore: ['button#close', '.hiernicht'],     // Elemente ausschließen, welche nicht darauf reagieren sollen
    callback: function () {                     // Auszuführende Funktion, wenn außerhalb Klick erfolgt
        console.log('close menu');
    }
});

touchEvents

Die Touch-Events-Funktion vereinfacht die Verarbeitung typischer Gesten auf Touch-Geräten und stellt eine einheitliche API für mobile Interaktionen bereit. Anstatt komplexe touchstart, touchmove und touchend-Events manuell auszuwerten, können häufig benötigte Gesten direkt über entsprechende Callback-Funktionen verarbeitet werden. Die Registrierung kann sowohl global auf dem gesamten Dokument als auch gezielt auf einzelnen DOM-Elementen erfolgen. Dies ermöglicht die Umsetzung von Touch-Navigationen, Bildergalerien, Slidern, Dashboards, Mobile-Menüs oder individuellen Gestensteuerungen innerhalb eigener Komponenten.

Die Erkennung erfolgt automatisch und berücksichtigt typische Konflikte zwischen verschiedenen Gestentypen, sodass Swipe-, Pinch- und Touch-Interaktionen zuverlässig voneinander getrennt verarbeitet werden können. Zusätzlich werden die Mausgesten swipe-left, swipe-right, swipe-up, swipe-down, press, doubletap und hold unterstützt.

Verwendung

/* document oder element via querySelector an Element direkt binden */
var element = document;
/*
    "on" Definitionen:
    - swipe-left, swipe-right, swipe-up, swipe-down
    - pinch, press, doubletap, hold
*/
UTILS.touch(element, {
    'swipe-right': () => { console.log('Swipe Right erkannt'); },
    'swipe-left':  () => { console.log('Swipe Left erkannt');  },
    'swipe-up':    () => { console.log('Swipe Up erkannt');    },
    'swipe-down':  () => { console.log('Swipe Down erkannt');  },
    'pinch':       (e, data) => { console.log('Pinch erkannt'); },
    'press':       () => { console.log('Press erkannt');       },
    'doubletap':   () => { console.log('Doubletap erkannt');   },
    'hold':        () => { console.log('Hold erkannt');        },
});

Beispiel

Warte auf Touch Aktion

inViewport

Die inViewport-Funktion ermöglicht das Reagieren auf Sichtbarkeitsänderungen von DOM-Elementen innerhalb des Viewports. Sie basiert auf einer effizienten Beobachtung der Elemente und eignet sich insbesondere für scrollbasierte Interaktionen und zustandsabhängige UI-Logiken.

Beispiel: CSS Animation starten, wenn in Viewport

CSS Animation

.shake{
    animation: shake 0.82s cubic-bezier(.36,.07,.19,.97) both;
    transform: translate3d(0, 0, 0);
    backface-visibility: hidden;
    perspective: 1000px;
}

@keyframes shake {
    10%, 90% { transform: translate3d(-1px, 0, 0); }
    20%, 80% { transform: translate3d(2px, 0, 0); }
    30%, 50%, 70% { transform: translate3d(-4px, 0, 0); }
    40%, 60% { transform: translate3d(4px, 0, 0); }
}

Elemente an Viewport binden

/* HTML NodeList der Elemente erfassen */
const animateElements = document.querySelectorAll('.animate');

UTILS.inViewport(animateElements,{
    threshold: 0.2, /* 20% des Elements müssen sichtbar sein, um die Animation zu starten */
    in: (el) => { /* Funktion ausführen, wenn Element in den Viewport kommt */
        el.classList.add('shake'); /* Fügt Animations - CSS Klasse zum dem Element hinzu */
    },
    out: (el) => { /* Funktion ausführen, wenn Element außerhalb des Viewports ist */
        /*
            Wenn gesetzt, wird die Animation jedesmal gestartet,
            wenn es erneut in den Viewport kommt
        */
        el.classList.remove('shake');
    }
});

PWA

Die PWA-Funktion stellt eine einfache Möglichkeit zur Konfiguration der Progressive-Web-App-Eigenschaften bereit. Sie erzeugt die notwendigen Metadaten für Manifest, Theme-Konfiguration und App-Identität direkt aus der Kryzo-Engine heraus, ohne manuelle Manifest-Dateien pflegen zu müssen. Damit lassen sich Webanwendungen schnell als installierbare PWA bereitstellen und konsistent über alle unterstützten Plattformen hinweg konfigurieren.

Initialisierung

UTILS.pwa({
    backgroundColor: '#FFFFFF',                     // Hintergrundfarbe
    themeColor:      '#8E5BF1',                     // Primäre Farbe des Projekts
    name:            'Kryzo',                       // Name der PWA
    description:     '...',                         // Beschreibung des Projekts
    baseUrl:         'https://domain.de/',          // Genaue Url zum Projekt
    icon:            'https://domain.de/icon.png',  // Genaue Url zum Icon (512x512)
});