typescript-overlay-essentials 1.6.1 → 2.0.0

package/dist/TutorialOverlay.css

@@ -0,0 +1,94 @@
+.overlay-essentials-tutorial-headline {
+    white-space: pre-line;
+    word-break: break-word;
+    text-align: center;
+}
+
+.overlay-essentials-tutorial-message {
+    white-space: pre-line;
+    word-break: break-word;
+}
+
+.overlay-essentials-tutorial-overlay {
+    position: fixed;
+    top: 0;
+    left: 0;
+    width: 100vw;
+    height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    z-index: 10000;
+    inset: 0;
+
+    &.overlay-essentials-darken {
+        background-color: rgba(0, 0, 0, 0.6);
+    }
+}
+
+.overlay-essentials-tutorial-highlight-hole {
+    position: fixed;
+    border-radius: 8px;
+    pointer-events: none;
+
+    z-index: 10000;
+
+    border: 2px solid white;
+
+    box-shadow:
+        0 0 0 4px rgba(255,255,255,0.25),
+        0 0 0 9999px rgba(0,0,0,0.6);
+}
+
+
+.overlay-essentials-tutorial-box {
+    background-color: var(--Hellgrau, white);
+    color: var(--HellSchwarz,#2c2c2c);
+    padding: 2rem;
+    border-radius: 12px;
+    box-shadow: 0 8px 20px rgba(0, 0, 0, 0.5);
+    max-width: 500px;
+    width: 90%;
+    animation: fadeIn 0.3s ease-in-out;
+    z-index: 10001;
+}
+
+@keyframes fadeIn {
+    from {
+        opacity: 0;
+        transform: scale(0.95);
+    }
+
+    to {
+        opacity: 1;
+        transform: scale(1);
+    }
+}
+
+.overlay-essentials-tutorial-box div {
+    margin-bottom: 0.5em;
+}
+
+.overlay-essentials-tutorial-box .headline {
+    margin-bottom: 0.75em;
+}
+
+.overlay-essentials-tutorial-box .tutorial-buttons {
+    display: flex;
+    justify-content: center;
+    gap: 1rem;
+    margin-top: 1.5rem;
+}
+
+.overlay-essentials-tutorial-box .tutorial-buttons button {
+    font-size: 85%;
+    padding: 0.5rem 1.1rem;
+}
+
+/* ==== Dark Mode Support ==== */
+[visual-theme="dark"] {
+    .tutorial-box {
+        background-color: var(--HellSchwarz,#2c2c2c);
+        color: white;
+    }
+}

package/dist/TutorialOverlay.d.ts

@@ -0,0 +1,26 @@
+import { CSSProperties, Dispatch, SetStateAction } from 'react';
+import './TutorialOverlay.css';
+export interface Steps {
+    headline: React.ReactNode;
+    message: React.ReactNode;
+    attachToObject?: string | HTMLElement;
+    command?: string;
+    backCommand?: string;
+    waitFor?: number;
+    dontHighlightObject?: boolean;
+}
+export interface TutorialState {
+    steps: Steps[];
+    currentCommand?: string;
+    proceedButtonText?: React.ReactNode;
+    completeButtonText?: React.ReactNode;
+    backButtonText?: React.ReactNode;
+    cancelButtonText?: React.ReactNode;
+    completeCommand?: string;
+    cancelCommand?: string;
+    style?: CSSProperties;
+}
+export declare function TutorialOverlay({ state, setState }: {
+    state: TutorialState;
+    setState: Dispatch<SetStateAction<TutorialState>>;
+}): React.ReactElement;

package/dist/TutorialOverlay.js

@@ -0,0 +1,195 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState, useRef } from 'react';
+import './TutorialOverlay.css';
+const defaultTutorialState = {
+    steps: [
+    // {
+    // headline: undefined,
+    // message: undefined,
+    // attachToObject: undefined,
+    // command: undefined,
+    // backCommand: undefined,
+    // dontHighlightObject: undefined,
+    // }
+    ],
+    currentCommand: undefined,
+    proceedButtonText: undefined,
+    completeButtonText: undefined,
+    backButtonText: undefined,
+    cancelButtonText: undefined,
+    completeCommand: undefined,
+    cancelCommand: undefined,
+    style: undefined,
+};
+const TIMEOUT_OVERLAY_WAIT_FOR_COMMAND_EXECUTION_MS = 100;
+// Wobei alle Attribute grundsätzlich optional sind:
+// - steps: Ist ein Array, welches alle Schritte des Tutorials im Format {message: string, attachToObject: JSX.Element, dontHighlightObject: boolean} angibt.
+//          - headline: Eine fett hinterlegte Überschrift für diesen Schritt (optional)
+//          - message: Die in diesem Schritt angezeigte Nachricht
+//          - attachToObject: Die HTML-ID des Objekts im Dokument oder ein HTMLElement neben dem die Nachricht angezeigt werden soll (optional, sonst in der Mitte des Bildschirms)
+//          - command: Ein String, der an einer Stelle gesetzt und an anderer Stelle ausgelesen werden kann, um z.B. Funktionsaufrufe zu triggern beim BETRETEN des steps (optional)
+//          - backCommand: Wie command. Aber gedacht für den Fall, dass AUS diesem Schritt ZURÜCKgegangen wird. Soll also rückgängig machen, was in command passiert ist (optional)
+//          - waitFor: Ein int, der angibt wie viele ms nach dem ausführen des Commands /bzw. backCommands) gewartet werden soll, bis zum nächsten Step gewechselt wird (optional, standard 100)
+//          - dontHighlightObject: Gibt an, ob die standardmäßige hervoerhebung des Objekts aufgehoben werden soll (also das NICHT visuell in den Vordergrund gezogen wird, vor das Overlay) (optional)
+// - currentCommand: Wird bei jedem Schritt aktualisiert, damit von außen auf einen Command reagiert werden kann
+// - completeCommand: ist der Command, auf den currentCommand nach Bestätigung des "Abschließen" Buttons auf der letzten Seite gesetzt wird
+// - cancelCommand: ist der Command, auf den currentCommand nach Abbruch auf der ersten Seite gesetzt wird ODER beim abbrechen in einem beliebigen Step durch ESC-Taste
+// - proceedButtonText: ist der Text der auf dem Fortfahren Button stehen soll (ohne Angabe wird "Weiter" verwendet)
+// - completeButtonText: ist der Text der auf dem Abschließenden Button stehen soll (ohne Angabe wird "Abschließen" verwendet)
+// - backButtonText: ist der Text der auf dem Zurück Button stehen soll (ohne Angabe wird "Zurück" verwendet)
+// - cancelButtonText: ist der Text der auf dem Abbrechen Button stehen soll (ohne Angabe wird "Überspringen" verwendet)
+// - style: ist der Style des Tutorial-Overlays (Standardmäßig unverändert)
+export function TutorialOverlay({ state, setState }) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m, _o;
+    // Wird verwendet um das Tutorial-Overlay ein- und auszublenden
+    const [showTutorial, setShowTutorial] = useState(false);
+    // Wird verwendet um die Position des Textes zu bestimmen
+    const [tutorialPos, setTutorialPos] = useState(null);
+    const [highlightElementRect, setHighlightElementRect] = useState(null);
+    // Wird verwendet um zu tracken bei welchem Schritt des Tutorials der Nutzer ist
+    const [tutorialStep, setTutorialStep] = useState(0);
+    const proceedButtonRef = useRef(null);
+    // Sobald der State von außen aktualisiert wird triggert diese Funktion
+    // Die setzt showTutorial auf true
+    useEffect(() => {
+        var _a, _b, _c, _d;
+        setTutorialStep(0);
+        setHighlightElementRect(null);
+        setTutorialPos(null);
+        if ((state === null || state === void 0 ? void 0 : state.steps) !== undefined && state.steps.length > 0) {
+            const attachElement = typeof ((_a = state === null || state === void 0 ? void 0 : state.steps[0]) === null || _a === void 0 ? void 0 : _a.attachToObject) === "string"
+                ? document.getElementById((_b = state === null || state === void 0 ? void 0 : state.steps[0]) === null || _b === void 0 ? void 0 : _b.attachToObject)
+                : (_c = state === null || state === void 0 ? void 0 : state.steps[0]) === null || _c === void 0 ? void 0 : _c.attachToObject;
+            if (attachElement instanceof HTMLElement) {
+                showTutorialAtElement(attachElement, (_d = state.steps[0].dontHighlightObject) !== null && _d !== void 0 ? _d : false);
+            }
+            else {
+                setShowTutorial(true);
+            }
+            setTimeout(() => { var _a; (_a = proceedButtonRef.current) === null || _a === void 0 ? void 0 : _a.focus(); }, 500);
+        }
+        else {
+            setShowTutorial(false);
+        }
+    }, [state === null || state === void 0 ? void 0 : state.steps]);
+    useEffect(() => {
+        if (showTutorial) {
+            document.body.style.overflow = "hidden";
+        }
+        return () => {
+            document.body.style.overflow = "";
+        };
+    }, [showTutorial]);
+    const showTutorialAtElement = (e, dontHighlightElement) => {
+        var rect = e.getBoundingClientRect();
+        const viewportHeight = window.innerHeight;
+        // Element ist höher als der sichtbare Bereich
+        if (rect.height > viewportHeight) {
+            e.scrollIntoView({ behavior: "instant", block: "start" });
+            // Etwas nach unten scrollen, damit das Element nicht direkt am oberen Rand klebt
+            window.scrollBy({ top: -viewportHeight * 0.3, behavior: "instant" });
+        }
+        else {
+            e.scrollIntoView({ behavior: "instant", block: "center" });
+        }
+        rect = e.getBoundingClientRect();
+        // 25 rem
+        const tooltipWidth = 31 * parseFloat(getComputedStyle(document.documentElement).fontSize);
+        const showLeft = rect.right + tooltipWidth > window.innerWidth;
+        setTutorialPos({
+            showLeft,
+            px_left: showLeft
+                ? rect.left - tooltipWidth - parseFloat(getComputedStyle(document.documentElement).fontSize)
+                : rect.right + parseFloat(getComputedStyle(document.documentElement).fontSize),
+            px_top: rect.top
+        });
+        if (!dontHighlightElement) {
+            setHighlightElementRect({
+                left: rect.left,
+                top: rect.top,
+                width: rect.width,
+                height: rect.height
+            });
+        }
+        else {
+            setHighlightElementRect(null);
+        }
+        setShowTutorial(true);
+    };
+    return showTutorial ?
+        _jsxs("div", { className: "overlay-essentials-tutorial-overlay" + (highlightElementRect === null ? " overlay-essentials-darken" : ""), children: [_jsx("div", { className: "overlay-essentials-overlay-essentials-tutorial-highlight-hole", style: highlightElementRect === null
+                        ? {
+                            display: "none"
+                        } : {
+                        left: `${(_a = highlightElementRect === null || highlightElementRect === void 0 ? void 0 : highlightElementRect.left) !== null && _a !== void 0 ? _a : 0}px`,
+                        top: `${(_b = highlightElementRect === null || highlightElementRect === void 0 ? void 0 : highlightElementRect.top) !== null && _b !== void 0 ? _b : 0}px`,
+                        width: `${(_c = highlightElementRect === null || highlightElementRect === void 0 ? void 0 : highlightElementRect.width) !== null && _c !== void 0 ? _c : 0}px`,
+                        height: `${(_d = highlightElementRect === null || highlightElementRect === void 0 ? void 0 : highlightElementRect.height) !== null && _d !== void 0 ? _d : 0}px`,
+                    } }), _jsxs("div", { className: "overlay-essentials-overlay-essentials-tutorial-box", style: {
+                        ...(tutorialPos
+                            ? {
+                                position: "fixed",
+                                left: tutorialPos.px_left,
+                                top: tutorialPos.px_top,
+                                transform: 'none'
+                            }
+                            : {}),
+                        ...((state === null || state === void 0 ? void 0 : state.style) != null ? state.style : {})
+                    }, role: "dialog", "aria-modal": "true", "aria-labelledby": (state === null || state === void 0 ? void 0 : state.steps[tutorialStep].headline) != null ? "tutorial-headline" : undefined, "aria-label": ((_e = state === null || state === void 0 ? void 0 : state.steps[tutorialStep]) === null || _e === void 0 ? void 0 : _e.headline) != null ? undefined : "Tutorial", "aria-describedby": "tutorial-message", onKeyDown: (event) => {
+                        var _a;
+                        if (event.key === "Escape") {
+                            const nextCommand = (_a = state.cancelCommand) !== null && _a !== void 0 ? _a : null;
+                            setState((prev) => ({ ...prev, currentCommand: nextCommand !== null && nextCommand !== void 0 ? nextCommand : undefined }));
+                        }
+                    }, children: [_jsx("div", { id: "overlay-essentials-overlay-essentials-tutorial-headline", className: "overlay-essentials-overlay-essentials-tutorial-headline", children: _jsxs("strong", { children: [(_g = (_f = state === null || state === void 0 ? void 0 : state.steps[tutorialStep]) === null || _f === void 0 ? void 0 : _f.headline) !== null && _g !== void 0 ? _g : "", " ", tutorialStep + 1, "/", state.steps.length] }) }), _jsx("div", { id: "overlay-essentials-overlay-essentials-tutorial-message", className: "overlay-essentials-overlay-essentials-tutorial-message", children: (_j = (_h = state === null || state === void 0 ? void 0 : state.steps[tutorialStep]) === null || _h === void 0 ? void 0 : _h.message) !== null && _j !== void 0 ? _j : "" }), _jsxs("div", { className: "overlay-essentials-tutorial-buttons", children: [_jsx("button", { onClick: () => {
+                                        var _a, _b, _c, _d;
+                                        if (tutorialStep > 0) {
+                                            const nextCommand = (_b = (_a = state.steps[tutorialStep]) === null || _a === void 0 ? void 0 : _a.backCommand) !== null && _b !== void 0 ? _b : null;
+                                            setState((prev) => ({ ...prev, currentCommand: nextCommand !== null && nextCommand !== void 0 ? nextCommand : undefined }));
+                                            setTimeout(() => {
+                                                var _a, _b, _c;
+                                                const attachTo = (_a = state === null || state === void 0 ? void 0 : state.steps[tutorialStep - 1]) === null || _a === void 0 ? void 0 : _a.attachToObject;
+                                                const attachElement = typeof attachTo === "string"
+                                                    ? document.getElementById(attachTo)
+                                                    : (_b = state === null || state === void 0 ? void 0 : state.steps[tutorialStep - 1]) === null || _b === void 0 ? void 0 : _b.attachToObject;
+                                                if (attachElement instanceof HTMLElement) {
+                                                    showTutorialAtElement(attachElement, (_c = state.steps[tutorialStep - 1].dontHighlightObject) !== null && _c !== void 0 ? _c : false);
+                                                }
+                                                else {
+                                                    setTutorialPos(null);
+                                                    setHighlightElementRect(null);
+                                                }
+                                                setTutorialStep(prev => prev - 1);
+                                            }, nextCommand != null ? ((_c = state === null || state === void 0 ? void 0 : state.steps[tutorialStep - 1].waitFor) !== null && _c !== void 0 ? _c : TIMEOUT_OVERLAY_WAIT_FOR_COMMAND_EXECUTION_MS) : 0);
+                                        }
+                                        else {
+                                            const nextCommand = (_d = state.cancelCommand) !== null && _d !== void 0 ? _d : null;
+                                            setState((prev) => ({ ...prev, currentCommand: nextCommand !== null && nextCommand !== void 0 ? nextCommand : undefined, steps: [] }));
+                                        }
+                                    }, type: "button", className: "px-4 py-2 bg-gray-300 rounded " + (tutorialStep > 0 ? "overlay-essentials-back-button" : "overlay-essentials-cancel-button"), children: tutorialStep > 0 ? ((_k = state === null || state === void 0 ? void 0 : state.backButtonText) !== null && _k !== void 0 ? _k : "Zurück") : ((_l = state === null || state === void 0 ? void 0 : state.cancelButtonText) !== null && _l !== void 0 ? _l : "Überspringen") }), _jsx("button", { onClick: () => {
+                                        var _a, _b, _c, _d;
+                                        if (tutorialStep + 1 < state.steps.length) {
+                                            const nextCommand = (_b = (_a = state.steps[tutorialStep + 1]) === null || _a === void 0 ? void 0 : _a.command) !== null && _b !== void 0 ? _b : null;
+                                            setState((prev) => ({ ...prev, currentCommand: nextCommand !== null && nextCommand !== void 0 ? nextCommand : undefined }));
+                                            setTimeout(() => {
+                                                var _a, _b, _c;
+                                                const attachTo = (_a = state === null || state === void 0 ? void 0 : state.steps[tutorialStep + 1]) === null || _a === void 0 ? void 0 : _a.attachToObject;
+                                                const attachElement = typeof attachTo === "string"
+                                                    ? document.getElementById(attachTo)
+                                                    : (_b = state === null || state === void 0 ? void 0 : state.steps[tutorialStep + 1]) === null || _b === void 0 ? void 0 : _b.attachToObject;
+                                                if (attachElement instanceof HTMLElement) {
+                                                    showTutorialAtElement(attachElement, (_c = state.steps[tutorialStep + 1].dontHighlightObject) !== null && _c !== void 0 ? _c : false);
+                                                }
+                                                else {
+                                                    setTutorialPos(null);
+                                                    setHighlightElementRect(null);
+                                                }
+                                                setTutorialStep(prev => prev + 1);
+                                            }, nextCommand != null ? (_c = state === null || state === void 0 ? void 0 : state.steps[tutorialStep + 1].waitFor) !== null && _c !== void 0 ? _c : TIMEOUT_OVERLAY_WAIT_FOR_COMMAND_EXECUTION_MS : 0);
+                                        }
+                                        else {
+                                            const nextCommand = (_d = state.completeCommand) !== null && _d !== void 0 ? _d : null;
+                                            setState((prev) => ({ ...prev, currentCommand: nextCommand !== null && nextCommand !== void 0 ? nextCommand : undefined, steps: [] }));
+                                        }
+                                    }, ref: proceedButtonRef, type: "button", className: "px-4 py-2 bg-blue-600 text-white rounded " + (tutorialStep > 0 ? "overlay-essentials-proceed-button" : "overlay-essentials-complete-button"), children: tutorialStep < state.steps.length - 1 ? ((_m = state === null || state === void 0 ? void 0 : state.proceedButtonText) !== null && _m !== void 0 ? _m : "Weiter") : ((_o = state === null || state === void 0 ? void 0 : state.completeButtonText) !== null && _o !== void 0 ? _o : "Abschließen") })] })] })] }) : _jsx(_Fragment, {});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typescript-overlay-essentials",
-  "version": "1.6.1",
+  "version": "2.0.0",
   "description": "Eine kleine Ansammlung an praktischen Tools, die out of the Box genutzt werden können. Alle enthaltenen Overlays können als Reaktion auf etwas geöffnet werden und schließen sich danach automatisch. Es beinhaltet: \\n - [ConfirmationBox]: Ein Overlay mit einer ConfirmationBox (Fortfahren / Abbrechen), \\n - [InfoOverlay]: ein simples Overlay mit einer Informationsbox die man bestätigen kann, \\n - [InfoOverlayWithInput]: Ein Overlay bei dem ein User zusätzlich ein Freitext-Feld zur Eingabe hat, \\n - [LoadingOverlay]: Ein simples Overlay mit einer Lade-animation und optionalem Ladetext, \\n - [MultipleChoiceOverlay]: Ein simples Overlay bei dem ein Nutzer aus mehreren gegebenen Aktionen auswählen kann, \\n - [MultipleRadioOverlay]: Ein simples Overlay bei dem ein Nutzer genau eine aus mehreren gegebenen Aktionen auswählen kann, \\n - [Toast]: Ein simpler Toast der für kurze Zeit grün hinterlegt in der oberen rechten Ecke des Bildschirms angezeigt wird, \\n - [ToggleSwitch]: Eine Auswahl aus zwei Optionen aus denen ein Nutzer wählen kann in der Darstellung (Option 1 | Option 2), \\n - [Dropdown]: Ein simples Dropdown-Menü (auf Basis von react-select), welches einfacherer zu Konfigurieren ist und einige default-Einstellungen hat, \\n - [InputFilter]: Ein Tool was genutzt werden kann um auf einem Inputfeld einen Regex-Filter anzuwenden und dem User so nur Eingaben erlaubt die dem Filter entsprechen.",
   "keywords": [
     "typescript",