@lovalingo/lovalingo 0.5.15 → 0.5.17

package/dist/components/LovalingoProvider.js

@@ -16,10 +16,75 @@ import { LanguageSwitcher } from './LanguageSwitcher';
 const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
 const LOADING_BG_STORAGE_PREFIX = "Lovalingo_loading_bg_color";
 const BRANDING_STORAGE_PREFIX = "Lovalingo_branding_enabled";
+const EDIT_MODE_PARAM = "edit_mode";
+const EDIT_KEY_PARAM = "edit_key";
 // Why: run initial load before first paint on the client to avoid a prehide flash; useEffect on SSR.
 const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+const DEFAULT_PATH_NORMALIZATION = { enabled: true };
+const EDIT_MODE_VALUES = new Set(["1", "true", "yes", "on"]);
+const EDIT_UI_ATTR = "data-lovalingo-edit-ui";
+const EDIT_HIGHLIGHT_ID = "lovalingo-edit-highlight";
+const EDIT_HINT_ID = "lovalingo-edit-hint";
+function readEditParams() {
+    if (typeof window === "undefined")
+        return { enabled: false, editKey: null };
+    const params = new URLSearchParams(window.location.search);
+    const rawFlag = (params.get(EDIT_MODE_PARAM) || params.get("editMode") || "").trim().toLowerCase();
+    const enabled = EDIT_MODE_VALUES.has(rawFlag);
+    const editKey = (params.get(EDIT_KEY_PARAM) || params.get("editKey") || "").trim() || null;
+    return { enabled, editKey };
+}
+function cssEscape(value) {
+    const esc = typeof window !== "undefined" && window?.CSS?.escape;
+    if (typeof esc === "function")
+        return esc(value);
+    return value.replace(/[ !"#$%&'()*+,.\/:;<=>?@[\\\]^`{|}~]/g, "\\$&");
+}
+// Why: build stable, short selectors for exclusions without requiring IDs.
+function buildCssSelector(element, maxDepth = 5) {
+    if (!element || !element.tagName)
+        return null;
+    if (element.id)
+        return `#${cssEscape(element.id)}`;
+    const parts = [];
+    let node = element;
+    let depth = 0;
+    while (node && depth < maxDepth) {
+        const tag = node.tagName.toLowerCase();
+        if (!tag || tag === "html")
+            break;
+        let part = tag;
+        const nodeTag = node.tagName;
+        const classes = Array.from(node.classList || [])
+            .filter(Boolean)
+            .filter((cls) => !cls.startsWith("lovalingo-"))
+            .slice(0, 2);
+        if (classes.length > 0) {
+            part += `.${classes.map(cssEscape).join(".")}`;
+        }
+        const parentEl = node.parentElement;
+        if (parentEl) {
+            const siblings = Array.from(parentEl.children).filter((child) => child instanceof HTMLElement && child.tagName === nodeTag);
+            if (siblings.length > 1) {
+                part += `:nth-of-type(${siblings.indexOf(node) + 1})`;
+            }
+        }
+        parts.unshift(part);
+        const selector = parts.join(" > ");
+        try {
+            if (document.querySelectorAll(selector).length === 1)
+                return selector;
+        }
+        catch {
+            // ignore invalid selector attempts
+        }
+        node = parentEl;
+        depth += 1;
+    }
+    return parts.join(" > ") || null;
+}
 export const LovalingoProvider = ({ children, apiKey: apiKeyProp, publicAnonKey, defaultLocale, locales, apiBase = 'https://cdn.lovalingo.com', routing = 'path', // Default to path mode (SEO-friendly, recommended)
-autoPrefixLinks = true, overlayBgColor, autoApplyRules = true, switcherPosition = 'bottom-right', switcherOffsetY = 20, switcherTheme = 'dark', editMode: initialEditMode = false, editKey = 'KeyE', pathNormalization = { enabled: true }, // Enable by default
+autoPrefixLinks = true, overlayBgColor, autoApplyRules = true, switcherPosition = 'bottom-right', switcherOffsetY = 20, switcherTheme = 'dark', editMode: initialEditMode = false, editKey = 'KeyE', pathNormalization = DEFAULT_PATH_NORMALIZATION, // Enable by default
 mode = 'dom', // Default to legacy DOM mode for backward compatibility
 sitemap = true, // Default: true - Auto-inject sitemap link tag
 seo = true, // Default: true - Can be disabled per project entitlements
@@ -44,7 +109,19 @@ navigateRef, // For path mode routing
     const allLocales = useMemo(() => {
         const base = rawLocales.includes(defaultLocale) ? rawLocales : [defaultLocale, ...rawLocales];
         return Array.from(new Set(base));
-    }, [defaultLocale, localesKey, rawLocales]);
+    }, [defaultLocale, localesKey]);
+    const pathNormalizationKey = (() => {
+        const enabled = pathNormalization?.enabled !== false;
+        const rules = Array.isArray(pathNormalization?.rules) ? pathNormalization.rules : [];
+        // Why: callers often pass inline objects/arrays; derive a stable key to prevent request storms from re-initializing effects.
+        const rulesKey = rules.map((r) => `${r.pattern}=>${r.replacement}:${r.includeSubpaths ? 1 : 0}`).join("|");
+        return `${enabled ? 1 : 0}:${rulesKey}`;
+    })();
+    const stablePathNormalization = useMemo(() => {
+        const enabled = pathNormalization?.enabled !== false;
+        const rules = Array.isArray(pathNormalization?.rules) ? pathNormalization.rules : undefined;
+        return rules ? { enabled, rules } : { enabled };
+    }, [pathNormalizationKey]);
     // Why: read locale synchronously from the URL to avoid an initial default-locale render (EN → FR flash) before effects run.
     const [locale, setLocaleState] = useState(() => {
         if (typeof window === "undefined")
@@ -73,17 +150,20 @@ navigateRef, // For path mode routing
         }
         return defaultLocale;
     });
-    const [editMode, setEditMode] = useState(initialEditMode);
-    const enhancedPathConfig = useMemo(() => (routing === "path" ? { ...pathNormalization, supportedLocales: allLocales } : pathNormalization), [allLocales, pathNormalization, routing]);
-    const apiRef = useRef(new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig));
+    const initialEditParams = readEditParams();
+    const [editMode, setEditMode] = useState(initialEditMode || initialEditParams.enabled);
+    const [editSecretKey] = useState(initialEditParams.editKey);
+    const enhancedPathConfig = useMemo(() => (routing === "path" ? { ...stablePathNormalization, supportedLocales: allLocales } : stablePathNormalization), [allLocales, routing, stablePathNormalization]);
+    const apiRef = useRef(new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig, editSecretKey ?? undefined));
     useEffect(() => {
-        apiRef.current = new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig);
-    }, [apiBase, enhancedPathConfig, resolvedApiKey]);
+        apiRef.current = new LovalingoAPI(resolvedApiKey, apiBase, enhancedPathConfig, editSecretKey ?? undefined);
+    }, [apiBase, editSecretKey, enhancedPathConfig, resolvedApiKey]);
     const routingConfig = useContext(LangRoutingContext);
     const [entitlements, setEntitlements] = useState(() => apiRef.current.getEntitlements());
     const { trackPageviewOnce } = usePageviewTracking({ apiRef, resolvedApiKey });
     const lastNormalizedPathRef = useRef("");
     const historyPatchedRef = useRef(false);
+    const editSavingRef = useRef(false);
     const originalHistoryRef = useRef(null);
     const onNavigateRef = useRef(() => undefined);
     const isInternalNavigationRef = useRef(false);
@@ -115,6 +195,18 @@ navigateRef, // For path mode routing
         catch {
             // ignore
         }
+        // Why: default to the site's existing background to reduce a visible white flash on non-white themes.
+        try {
+            const bodyBg = window.getComputedStyle(document.body).backgroundColor;
+            if (bodyBg && bodyBg !== "transparent" && bodyBg !== "rgba(0, 0, 0, 0)")
+                return bodyBg;
+            const htmlBg = window.getComputedStyle(document.documentElement).backgroundColor;
+            if (htmlBg && htmlBg !== "transparent" && htmlBg !== "rgba(0, 0, 0, 0)")
+                return htmlBg;
+        }
+        catch {
+            // ignore
+        }
         return "#ffffff";
     }, [loadingBgStorageKey, overlayBgColor]);
     const setCachedLoadingBgColor = useCallback((color) => {
@@ -526,6 +618,11 @@ navigateRef, // For path mode routing
     useEffect(() => {
         detectLocaleRef.current = detectLocale;
     }, [detectLocale]);
+    useEffect(() => {
+        if (editMode && !editSecretKey) {
+            warnDebug('[Lovalingo] Edit Mode is active but no edit_key was provided in the URL.');
+        }
+    }, [editMode, editSecretKey]);
     // Initialize
     useIsomorphicLayoutEffect(() => {
         const initialLocale = detectLocaleRef.current();
@@ -591,10 +688,149 @@ navigateRef, // For path mode routing
         setEditMode(prev => !prev);
     }, []);
     const excludeElement = useCallback(async (selector) => {
-        await apiRef.current.saveExclusion(selector, 'css');
+        if (!editSecretKey) {
+            warnDebug('[Lovalingo] Edit Mode is active but no edit_key was provided in the URL.');
+            return;
+        }
+        // Why: store exclusions on the normalized path so they apply across locales.
+        const pagePath = lastNormalizedPathRef.current || processPath(window.location.pathname, enhancedPathConfig);
+        await apiRef.current.saveExclusion({
+            selector,
+            type: 'css',
+            pagePath,
+            editKey: editSecretKey,
+        });
         const exclusions = await apiRef.current.fetchExclusions();
         setMarkerEngineExclusions(exclusions);
-    }, []);
+    }, [editSecretKey, enhancedPathConfig]);
+    useEffect(() => {
+        if (typeof window === "undefined")
+            return;
+        const existingHighlight = document.getElementById(EDIT_HIGHLIGHT_ID);
+        const existingHint = document.getElementById(EDIT_HINT_ID);
+        if (!editMode) {
+            existingHighlight?.remove();
+            existingHint?.remove();
+            return;
+        }
+        const highlight = existingHighlight ||
+            (() => {
+                const node = document.createElement("div");
+                node.id = EDIT_HIGHLIGHT_ID;
+                node.setAttribute(EDIT_UI_ATTR, "true");
+                node.setAttribute("data-lovalingo-exclude", "true");
+                node.style.position = "fixed";
+                node.style.pointerEvents = "none";
+                node.style.zIndex = "2147483646";
+                node.style.border = "2px solid #22c55e";
+                node.style.background = "rgba(34, 197, 94, 0.12)";
+                node.style.borderRadius = "8px";
+                node.style.boxSizing = "border-box";
+                node.style.transition = "transform 80ms ease, width 80ms ease, height 80ms ease";
+                node.style.display = "none";
+                document.body.appendChild(node);
+                return node;
+            })();
+        const hint = existingHint ||
+            (() => {
+                const node = document.createElement("div");
+                node.id = EDIT_HINT_ID;
+                node.setAttribute(EDIT_UI_ATTR, "true");
+                node.setAttribute("data-lovalingo-exclude", "true");
+                node.style.position = "fixed";
+                node.style.left = "12px";
+                node.style.bottom = "12px";
+                node.style.zIndex = "2147483647";
+                node.style.background = "rgba(10, 10, 10, 0.85)";
+                node.style.color = "#ffffff";
+                node.style.fontSize = "12px";
+                node.style.lineHeight = "1.4";
+                node.style.padding = "8px 10px";
+                node.style.borderRadius = "8px";
+                node.style.border = "1px solid rgba(255, 255, 255, 0.15)";
+                node.style.pointerEvents = "none";
+                node.style.maxWidth = "280px";
+                node.textContent = "Edit Mode: click an element to exclude. Press Esc to exit.";
+                document.body.appendChild(node);
+                return node;
+            })();
+        let rafId = null;
+        let pendingTarget = null;
+        const previousCursor = document.body.style.cursor;
+        document.body.style.cursor = "crosshair";
+        const updateHighlight = () => {
+            rafId = null;
+            if (!pendingTarget) {
+                highlight.style.display = "none";
+                return;
+            }
+            const rect = pendingTarget.getBoundingClientRect();
+            if (rect.width <= 0 || rect.height <= 0) {
+                highlight.style.display = "none";
+                return;
+            }
+            highlight.style.display = "block";
+            highlight.style.width = `${rect.width}px`;
+            highlight.style.height = `${rect.height}px`;
+            highlight.style.transform = `translate(${rect.left}px, ${rect.top}px)`;
+        };
+        const onMove = (event) => {
+            const rawTarget = event.target;
+            const target = rawTarget instanceof HTMLElement ? rawTarget : rawTarget instanceof Node ? rawTarget.parentElement : null;
+            if (!target || target.closest(`[${EDIT_UI_ATTR}="true"]`)) {
+                pendingTarget = null;
+            }
+            else if (target === document.body || target === document.documentElement) {
+                pendingTarget = null;
+            }
+            else {
+                pendingTarget = target;
+            }
+            if (rafId !== null)
+                return;
+            rafId = window.requestAnimationFrame(updateHighlight);
+        };
+        const onClick = async (event) => {
+            const rawTarget = event.target;
+            const target = rawTarget instanceof HTMLElement ? rawTarget : rawTarget instanceof Node ? rawTarget.parentElement : null;
+            if (!target || target.closest(`[${EDIT_UI_ATTR}="true"]`))
+                return;
+            event.preventDefault();
+            event.stopPropagation();
+            event.stopImmediatePropagation();
+            const selector = buildCssSelector(target);
+            if (!selector)
+                return;
+            if (editSavingRef.current)
+                return;
+            editSavingRef.current = true;
+            try {
+                await excludeElement(selector);
+            }
+            finally {
+                editSavingRef.current = false;
+            }
+        };
+        const onKeyDown = (event) => {
+            if (event.key === "Escape") {
+                event.preventDefault();
+                setEditMode(false);
+            }
+        };
+        document.addEventListener("mousemove", onMove, true);
+        document.addEventListener("click", onClick, true);
+        document.addEventListener("keydown", onKeyDown, true);
+        return () => {
+            document.removeEventListener("mousemove", onMove, true);
+            document.removeEventListener("click", onClick, true);
+            document.removeEventListener("keydown", onKeyDown, true);
+            if (rafId !== null)
+                window.cancelAnimationFrame(rafId);
+            highlight.remove();
+            hint.remove();
+            document.body.style.cursor = previousCursor;
+        };
+    }, [editMode, excludeElement, setEditMode]);
     const contextValue = {
         locale,
         setLocale,

package/dist/utils/api.d.ts

@@ -81,11 +81,13 @@ export declare class LovalingoAPI {
     private apiKey;
     private apiBase;
     private pathConfig?;
+    private editKey?;
     private entitlements;
-    constructor(apiKey: string, apiBase: string, pathConfig?: PathNormalizationConfig);
+    constructor(apiKey: string, apiBase: string, pathConfig?: PathNormalizationConfig, editKey?: string);
     private hasApiKey;
     private buildPathParam;
     private warnMissingApiKey;
+    private warnMissingEditKey;
     private logActivationRequired;
     private isActivationRequiredPayload;
     private isActivationRequiredResponse;
@@ -105,5 +107,11 @@ export declare class LovalingoAPI {
     fetchBootstrap(localeHint: string, pathOrUrl?: string): Promise<BootstrapResponse | null>;
     fetchExclusions(): Promise<Exclusion[]>;
     fetchDomRules(targetLocale: string): Promise<DomRule[]>;
-    saveExclusion(selector: string, type: 'css' | 'xpath'): Promise<void>;
+    saveExclusion(args: {
+        selector: string;
+        type: 'css' | 'xpath';
+        pagePath?: string;
+        editKey?: string;
+        description?: string;
+    }): Promise<void>;
 }

package/dist/utils/api.js

@@ -1,10 +1,11 @@
 import { warnDebug, errorDebug } from './logger';
 export class LovalingoAPI {
-    constructor(apiKey, apiBase, pathConfig) {
+    constructor(apiKey, apiBase, pathConfig, editKey) {
         this.entitlements = null;
         this.apiKey = apiKey;
         this.apiBase = apiBase;
         this.pathConfig = pathConfig;
+        this.editKey = editKey;
     }
     hasApiKey() {
         return typeof this.apiKey === 'string' && this.apiKey.trim().length > 0;
@@ -30,6 +31,9 @@ export class LovalingoAPI {
         // Avoid hard-crashing apps; make the failure mode obvious.
         warnDebug(`[Lovalingo] Missing public project key: ${action} was skipped. Pass publicAnonKey to <LovalingoProvider ...> (or set VITE_LOVALINGO_PUBLIC_ANON_KEY).`);
     }
+    warnMissingEditKey(action) {
+        warnDebug(`[Lovalingo] Missing edit key: ${action} was skipped. Open the edit link from the dashboard to continue.`);
+    }
     logActivationRequired(context, response) {
         errorDebug(`[Lovalingo] ${context} blocked (HTTP ${response.status}). ` +
             `This project is not activated yet. ` +
@@ -338,16 +342,30 @@ export class LovalingoAPI {
             return [];
         }
     }
-    async saveExclusion(selector, type) {
+    async saveExclusion(args) {
         try {
             if (!this.hasApiKey()) {
                 this.warnMissingApiKey('saveExclusion');
                 return;
             }
+            const editKey = (args.editKey || this.editKey || "").trim();
+            if (!editKey) {
+                this.warnMissingEditKey('saveExclusion');
+                return;
+            }
+            // Why: persist exclusions against a normalized path to keep locales in sync.
+            const pagePath = (args.pagePath || this.buildPathParam()).toString();
             const response = await fetch(`${this.apiBase}/functions/v1/exclusions?key=${this.apiKey}`, {
                 method: 'POST',
                 headers: { 'Content-Type': 'application/json' },
-                body: JSON.stringify({ selector, type }),
+                body: JSON.stringify({
+                    key: this.apiKey,
+                    edit_key: editKey,
+                    page_path: pagePath,
+                    selector_type: args.type,
+                    selector_value: args.selector,
+                    description: args.description,
+                }),
             });
             if (response.status === 403) {
                 this.logActivationRequired('saveExclusion', response);

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.5.13";
+export declare const VERSION = "0.5.16";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.5.13";
+export const VERSION = "0.5.16";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lovalingo/lovalingo",
-  "version": "0.5.15",
+  "version": "0.5.17",
   "description": "React translation runtime with i18n routing, deterministic bundles + DOM rules, and zero-flash rendering.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",