npm - @lovalingo/lovalingo - Versions diffs - 0.5.0 → 0.5.1 - Mend

@lovalingo/lovalingo 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (7) hide show

package/README.md +11 -0
package/dist/components/AixsterProvider.js +58 -10
package/dist/components/LangLink.js +0 -6
package/dist/components/LangRouter.js +1 -7
package/dist/hooks/useLangNavigate.js +0 -6
package/dist/types.d.ts +1 -0
package/package.json +1 -1

package/README.md CHANGED Viewed

@@ -205,6 +205,7 @@ Lovalingo includes a floating language switcher.
   publicAnonKey="aix_xxx"
   defaultLocale="en"
   locales={["en", "de", "fr"]}
+  overlayBgColor="#ffffff" // optional: background during the no-flash prehide phase (default: #ffffff)
   switcherPosition="bottom-right"
   switcherOffsetY={20}
   switcherTheme="light" // "dark" | "light" (default: "dark")
@@ -213,6 +214,16 @@ Lovalingo includes a floating language switcher.
 </LovalingoProvider>
 ```
+## Overlay Background (No-Flash UX)
+Lovalingo may briefly hide the page while it loads translations to avoid a visible EN→DE flash.
+Set `overlayBgColor` to match your app background so the fallback looks seamless:
+```tsx
+<LovalingoProvider overlayBgColor="#0b0b0b" ... />
+```
 ## SEO (Canonical + hreflang)
 Lovalingo can keep `<head>` SEO signals in sync with the active locale:

package/dist/components/AixsterProvider.js CHANGED Viewed

@@ -11,8 +11,10 @@ const LOCALE_STORAGE_KEY = 'Lovalingo_locale';
 const LOADING_BG_STORAGE_PREFIX = "Lovalingo_loading_bg_color";
 const BRANDING_STORAGE_PREFIX = "Lovalingo_branding_enabled";
 const CRITICAL_CACHE_PREFIX = "Lovalingo_critical_v0_3";
+// Why: avoid long blank screens on blocked/untranslated routes by always revealing the original page quickly.
+const PREHIDE_FAILSAFE_MS = 1700;
 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, 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 = { enabled: true }, // 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
@@ -75,12 +77,15 @@ navigateRef, // For path mode routing
     }, [apiBase, enhancedPathConfig, resolvedApiKey]);
     const [entitlements, setEntitlements] = useState(() => apiRef.current.getEntitlements());
     const lastPageviewRef = useRef("");
+    const lastNormalizedPathRef = useRef("");
     const historyPatchedRef = useRef(false);
     const originalHistoryRef = useRef(null);
     const onNavigateRef = useRef(() => undefined);
     const retryTimeoutRef = useRef(null);
+    const loadingFailsafeTimeoutRef = useRef(null);
     const isNavigatingRef = useRef(false);
     const isInternalNavigationRef = useRef(false);
+    const inFlightLoadKeyRef = useRef(null);
     const translationCacheRef = useRef(new Map());
     const exclusionsCacheRef = useRef(null);
     const domRulesCacheRef = useRef(new Map());
@@ -109,6 +114,9 @@ navigateRef, // For path mode routing
         prevBodyBg: "",
     });
     const getCachedLoadingBgColor = useCallback(() => {
+        const configured = (overlayBgColor || "").toString().trim();
+        if (/^#[0-9a-fA-F]{6}$/.test(configured))
+            return configured;
         try {
             const cached = localStorage.getItem(loadingBgStorageKey) || "";
             if (/^#[0-9a-fA-F]{6}$/.test(cached.trim()))
@@ -118,7 +126,7 @@ navigateRef, // For path mode routing
             // ignore
         }
         return "#ffffff";
-    }, [loadingBgStorageKey]);
+    }, [loadingBgStorageKey, overlayBgColor]);
     const setCachedLoadingBgColor = useCallback((color) => {
         const next = (color || "").toString().trim();
         if (!/^#[0-9a-fA-F]{6}$/.test(next))
@@ -130,6 +138,13 @@ navigateRef, // For path mode routing
             // ignore
         }
     }, [loadingBgStorageKey]);
+    useEffect(() => {
+        // Why: make `overlayBgColor` the source of truth while keeping the existing cache key for backwards compatibility.
+        const configured = (overlayBgColor || "").toString().trim();
+        if (!/^#[0-9a-fA-F]{6}$/.test(configured))
+            return;
+        setCachedLoadingBgColor(configured);
+    }, [overlayBgColor, setCachedLoadingBgColor]);
     const setCachedBrandingEnabled = useCallback((enabled) => {
         try {
             localStorage.setItem(brandingStorageKey, enabled === false ? "0" : "1");
@@ -176,12 +191,10 @@ navigateRef, // For path mode routing
             body.style.backgroundColor = bgColor;
         }
         if (state.timeoutId != null) {
-            window.clearTimeout(state.timeoutId);
+            return;
         }
-        // Why: avoid leaving the page hidden forever if the network is blocked or the project has no translations yet.
-        state.timeoutId = window.setTimeout(() => {
-            disablePrehide();
-        }, 2500);
+        // Why: avoid a "perma-hide" when navigation events repeatedly re-trigger prehide and keep extending the timeout.
+        state.timeoutId = window.setTimeout(() => disablePrehide(), PREHIDE_FAILSAFE_MS);
     }, []);
     const disablePrehide = useCallback(() => {
         if (typeof document === "undefined")
@@ -266,6 +279,7 @@ navigateRef, // For path mode routing
         apiBase,
         routing,
         autoPrefixLinks,
+        overlayBgColor,
         switcherPosition,
         switcherOffsetY,
         switcherTheme,
@@ -501,6 +515,10 @@ navigateRef, // For path mode routing
             clearTimeout(retryTimeoutRef.current);
             retryTimeoutRef.current = null;
         }
+        if (loadingFailsafeTimeoutRef.current != null) {
+            window.clearTimeout(loadingFailsafeTimeoutRef.current);
+            loadingFailsafeTimeoutRef.current = null;
+        }
         // If switching to default locale, clear translations and translate with empty map
         // This will show original text using stored data-Lovalingo-original-html
         if (targetLocale === defaultLocale) {
@@ -513,6 +531,10 @@ navigateRef, // For path mode routing
         const currentPath = window.location.pathname + window.location.search;
         const normalizedPath = processPath(window.location.pathname, enhancedPathConfig);
         const cacheKey = `${targetLocale}:${normalizedPath}`;
+        if (inFlightLoadKeyRef.current === cacheKey) {
+            return;
+        }
+        inFlightLoadKeyRef.current = cacheKey;
         // Check if we have cached translations for this locale + path
         const cachedEntry = translationCacheRef.current.get(cacheKey);
         const cachedExclusions = exclusionsCacheRef.current;
@@ -553,12 +575,20 @@ navigateRef, // For path mode routing
             }, 500);
             disablePrehide();
             isNavigatingRef.current = false;
+            if (inFlightLoadKeyRef.current === cacheKey) {
+                inFlightLoadKeyRef.current = null;
+            }
             return;
         }
         // CACHE MISS - Fetch from API
         logDebug(`[Lovalingo] Fetching translations for ${targetLocale} on ${normalizedPath}`);
         setIsLoading(true);
         enablePrehide(getCachedLoadingBgColor());
+        // Why: never keep the app hidden/blocked for longer than the UX budget; show the original content if translations aren't ready fast.
+        loadingFailsafeTimeoutRef.current = window.setTimeout(() => {
+            disablePrehide();
+            setIsLoading(false);
+        }, PREHIDE_FAILSAFE_MS);
         try {
             if (previousLocale && previousLocale !== defaultLocale) {
                 logDebug(`[Lovalingo] Switching from ${previousLocale} to ${targetLocale}`);
@@ -673,7 +703,14 @@ navigateRef, // For path mode routing
         }
         finally {
             setIsLoading(false);
+            if (loadingFailsafeTimeoutRef.current != null) {
+                window.clearTimeout(loadingFailsafeTimeoutRef.current);
+                loadingFailsafeTimeoutRef.current = null;
+            }
             isNavigatingRef.current = false;
+            if (inFlightLoadKeyRef.current === cacheKey) {
+                inFlightLoadKeyRef.current = null;
+            }
         }
     }, [
         applySeoBundle,
@@ -694,15 +731,25 @@ navigateRef, // For path mode routing
         onNavigateRef.current = () => {
             trackPageviewOnce(window.location.pathname + window.location.search);
             const nextLocale = detectLocale();
+            const normalizedPath = processPath(window.location.pathname, enhancedPathConfig);
+            const normalizedPathChanged = normalizedPath !== lastNormalizedPathRef.current;
+            lastNormalizedPathRef.current = normalizedPath;
+            // Why: bundles are path-scoped, so SPA navigations within the same locale must trigger a reload for the new route.
+            if (normalizedPathChanged && nextLocale !== defaultLocale && !isInternalNavigationRef.current) {
+                void loadData(nextLocale, locale);
+                return;
+            }
             if (nextLocale !== locale) {
                 setLocaleState(nextLocale);
-                void loadData(nextLocale, locale);
+                if (!isInternalNavigationRef.current) {
+                    void loadData(nextLocale, locale);
+                }
             }
             else if (mode === "dom" && nextLocale !== defaultLocale) {
                 applyActiveTranslations(document.body);
             }
         };
-    }, [defaultLocale, detectLocale, loadData, locale, mode, trackPageviewOnce]);
+    }, [defaultLocale, detectLocale, enhancedPathConfig, loadData, locale, mode, trackPageviewOnce]);
     // SPA router hook-in: patch History API once (prevents stacked wrappers → request storms).
     useEffect(() => {
         if (typeof window === "undefined")
@@ -801,6 +848,7 @@ navigateRef, // For path mode routing
     // Initialize
     useEffect(() => {
         const initialLocale = detectLocale();
+        lastNormalizedPathRef.current = processPath(window.location.pathname, enhancedPathConfig);
         // Track initial page (fallback discovery for pages not present in the routes feed).
         trackPageviewOnce(window.location.pathname + window.location.search);
         // Always prefetch artifacts for the initial locale (pipeline-produced translations + rules).
@@ -820,7 +868,7 @@ navigateRef, // For path mode routing
                 clearTimeout(retryTimeoutRef.current);
             }
         };
-    }, [detectLocale, loadData, editKey, trackPageviewOnce]);
+    }, [detectLocale, enhancedPathConfig, loadData, editKey, trackPageviewOnce]);
     // Auto-inject sitemap link tag
     useEffect(() => {
         if (sitemap && resolvedApiKey && isSeoActive()) {

package/dist/components/LangLink.js CHANGED Viewed

@@ -2,12 +2,6 @@ import React from 'react';
 import { Link } from 'react-router-dom';
 import { useLang } from '../hooks/useLang';
 const NON_LOCALIZED_APP_PATHS = new Set([
-    'auth',
-    'login',
-    'signup',
-    'sign-in',
-    'sign-up',
-    'register',
     'robots.txt',
     'sitemap.xml',
 ]);

package/dist/components/LangRouter.js CHANGED Viewed

@@ -2,12 +2,6 @@ import React, { useEffect } from 'react';
 import { BrowserRouter, Routes, Route, Navigate, Outlet, useLocation, useNavigate } from 'react-router-dom';
 import { LangContext } from '../context/LangContext';
 const NON_LOCALIZED_APP_PATHS = new Set([
-    '/auth',
-    '/login',
-    '/signup',
-    '/sign-in',
-    '/sign-up',
-    '/register',
     '/robots.txt',
     '/sitemap.xml',
 ]);
@@ -35,7 +29,7 @@ function NavigateExporter({ navigateRef }) {
  */
 function LangGuard({ defaultLang, lang }) {
     const location = useLocation();
-    // If the URL is language-prefixed but the underlying route is non-localized (auth/login/signup),
+    // If the URL is language-prefixed but the underlying route is non-localized (e.g. robots/sitemap),
     // redirect to the canonical non-localized path.
     const prefix = `/${lang}`;
     const restPath = location.pathname.startsWith(prefix) ? location.pathname.slice(prefix.length) || '/' : location.pathname;

package/dist/hooks/useLangNavigate.js CHANGED Viewed

@@ -3,12 +3,6 @@ import { useCallback } from 'react';
 import { useLang } from './useLang';
 //Globally excluded paths.
 const NON_LOCALIZED_APP_PATHS = new Set([
-    'auth',
-    'login',
-    'signup',
-    'sign-in',
-    'sign-up',
-    'register',
     'robots.txt',
     'sitemap.xml',
 ]);

package/dist/types.d.ts CHANGED Viewed

@@ -10,6 +10,7 @@ export interface LovalingoConfig {
     apiBase?: string;
     routing?: 'query' | 'path';
     autoPrefixLinks?: boolean;
+    overlayBgColor?: string;
     switcherPosition?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
     switcherOffsetY?: number;
     switcherTheme?: 'dark' | 'light';

package/package.json CHANGED Viewed

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