@edc-motor/ui 0.5.19 → 0.5.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edc-motor/ui",
-  "version": "0.5.19",
+  "version": "0.5.20",
   "description": "EdC Motor — componentes públicos Vue 3 + tokens SCSS para webs de juegos de mesa (paquete fuente: lo compila el consumidor con Vite)",
   "license": "GPL-3.0-only",
   "type": "module",

package/src/index.ts

@@ -53,7 +53,15 @@ export { default as LocaleSelector } from './components/LocaleSelector.vue'
 export { default as AppBreadcrumbs, type Crumb } from './components/AppBreadcrumbs.vue'
 export { default as PreviewGrid, type PreviewGridItem } from './components/PreviewGrid.vue'
 export { createApi, type CreateApiOptions } from './lib/createApi'
-export { watchSplash, dismissSplash, type WatchSplashOptions } from './lib/splash'
+export {
+  watchSplash,
+  dismissSplash,
+  setupNavigationSplash,
+  type WatchSplashOptions,
+  type NavigationSplashOptions,
+  type SplashRouterLike,
+} from './lib/splash'
+export { readCache, writeCache } from './lib/localCache'
 export { useToast, type Toast } from './composables/useToast'
 export { useConfirm, type ConfirmOptions } from './composables/useConfirm'
 export { useTheme, type ThemeMode } from './composables/useTheme'

package/src/lib/localCache.ts

@@ -0,0 +1,23 @@
+// Caché ligera en localStorage para el ARRANQUE de las SPAs: la última
+// respuesta buena de settings/menús/locales se guarda y en la siguiente
+// visita se pinta AL INSTANTE con ella mientras se refresca en segundo
+// plano (patrón stale-while-revalidate). Todo va en try/catch: sin
+// localStorage (incógnito estricto, cuota llena) simplemente no hay caché
+// y la app funciona como siempre.
+
+export function readCache<T>(key: string): T | null {
+  try {
+    const raw = localStorage.getItem(key)
+    return raw ? (JSON.parse(raw) as T) : null
+  } catch {
+    return null
+  }
+}
+
+export function writeCache(key: string, value: unknown): void {
+  try {
+    localStorage.setItem(key, JSON.stringify(value))
+  } catch {
+    // llena o bloqueada: da igual, la caché es solo una mejora
+  }
+}

package/src/lib/splash.ts

@@ -1,18 +1,21 @@
 import type { AxiosInstance } from 'axios'
 
-// Splash de arranque. La SPA sirve un cascarón instantáneo y pide TODO lo
-// real (settings, menús, sesión, contenido de la vista) a la API después de
-// montar: hasta que responde, cada componente pinta su estado por defecto.
-// En local (API a ~1 ms) ese fotograma provisional no llega a verse; en
-// producción sí. El remedio: el index.html estático trae un velo a pantalla
-// completa (#edc-splash, HTML autosuficiente pintado desde el fotograma
-// cero, antes incluso de descargar el bundle) y este módulo lo retira
-// cuando el arranque termina de verdad.
+// Splash de arranque Y velo de navegación. La SPA sirve un cascarón
+// instantáneo y pide TODO lo real (settings, menús, sesión, contenido de la
+// vista) a la API después de montar: hasta que responde, cada componente
+// pinta su estado por defecto. En local (API a ~1 ms) ese fotograma
+// provisional no llega a verse; en producción sí. El remedio: el index.html
+// estático trae un velo a pantalla completa (#edc-splash, HTML
+// autosuficiente pintado desde el fotograma cero, antes incluso de
+// descargar el bundle) y este módulo lo retira cuando el arranque termina
+// de verdad — y lo REUTILIZA como estado de carga en las navegaciones SPA
+// lentas (setupNavigationSplash): la identidad de carga es siempre el
+// splash, nunca skeletons.
 //
 // ¿Y cuándo termina «de verdad»? En vez de instrumentar cada vista, se
-// observa el cliente axios: se cuentan las peticiones en vuelo y el splash
+// observa el cliente axios: se cuentan las peticiones en vuelo y el velo
 // cae en el PRIMER REPOSO DE RED (cero peticiones durante `quietMs`). Eso
-// cubre solo la cascada inicial —locales → settings → datos de la primera
+// cubre sola la cascada inicial —locales → settings → datos de la primera
 // vista, encadenados por microtareas que siempre ganan al temporizador— y
 // no exige tocar las vistas. Un tope (`maxWaitMs`) garantiza que una API
 // caída nunca deja el velo puesto.
@@ -21,9 +24,14 @@ import type { AxiosInstance } from 'axios'
 // del onMounted ya habrían salido sin contar):
 //
 //   watchSplash({ api })
+//   setupNavigationSplash(router) // opcional: velo también al navegar
 //   app.mount('#app')
+//
+// El index.html puede definir window.__edcSplashRefresh (p. ej. para
+// re-elegir el logo según el idioma guardado): se invoca en cada re-show.
 
 const SPLASH_ID = 'edc-splash'
+const DONE_CLASS = 'edc-splash--done'
 
 export interface WatchSplashOptions {
   /** Cliente(s) axios cuyas peticiones marcan el arranque (createApi). */
@@ -34,39 +42,75 @@ export interface WatchSplashOptions {
   maxWaitMs?: number
 }
 
-/** Retira el splash con su fundido (idempotente; sin splash, no hace nada). */
+/** Contrato mínimo del router (estructural: sin depender de vue-router). */
+export interface SplashRouterLike {
+  beforeEach(guard: () => void): unknown
+  afterEach(hook: () => void): unknown
+  onError?(handler: () => void): unknown
+}
+
+export interface NavigationSplashOptions {
+  /** Espera antes de ENSEÑAR el velo: una navegación que resuelve antes no
+   *  lo ve ni un frame (ms). */
+  showDelayMs?: number
+  /** Tope duro por navegación (ms). */
+  maxWaitMs?: number
+}
+
+// ---- contador de red compartido (lo alimenta watchSplash) ---------------
+let inflight = 0
+let quietMs = 200
+let quietTimer: ReturnType<typeof setTimeout> | undefined
+// Qué hacer al llegar el reposo: el arranque y cada navegación lo reasignan.
+let onQuiet: (() => void) | null = null
+
+function armQuiet() {
+  clearTimeout(quietTimer)
+  quietTimer = setTimeout(() => onQuiet?.(), quietMs)
+}
+
+function splashEl(): HTMLElement | null {
+  return document.getElementById(SPLASH_ID)
+}
+
+/** Retira el splash con su fundido (idempotente; sin splash, no hace nada).
+ *  El elemento se OCULTA, no se elimina: las navegaciones lo reutilizan. */
 export function dismissSplash(): void {
-  const el = document.getElementById(SPLASH_ID)
-  if (!el || el.classList.contains('edc-splash--done')) return
-  el.classList.add('edc-splash--done')
-  const remove = () => el.remove()
-  el.addEventListener('transitionend', remove, { once: true })
-  // Por si no hay transición (prefers-reduced-motion, CSS recortado).
-  setTimeout(remove, 600)
+  const el = splashEl()
+  if (!el || el.classList.contains(DONE_CLASS)) return
+  el.classList.add(DONE_CLASS)
+  // visibility al terminar el fundido: para el pulso del logo mientras el
+  // velo no se ve (el guard evita apagar un re-show que haya interrumpido).
+  const finish = () => {
+    if (el.classList.contains(DONE_CLASS)) el.style.visibility = 'hidden'
+  }
+  el.addEventListener('transitionend', finish, { once: true })
+  setTimeout(finish, 600)
+}
+
+/** Re-enseña el velo (fundido de entrada por la misma transición). */
+function showSplash(): void {
+  const el = splashEl()
+  if (!el) return
+  ;(window as unknown as { __edcSplashRefresh?: () => void }).__edcSplashRefresh?.()
+  el.style.visibility = ''
+  // reflow: sin él, quitar la clase en el mismo frame se salta la transición
+  void el.offsetWidth
+  el.classList.remove(DONE_CLASS)
 }
 
 /** Observa el arranque y retira el splash en el primer reposo de red. */
 export function watchSplash(options: WatchSplashOptions = {}): void {
   if (typeof document === 'undefined') return
-  if (!document.getElementById(SPLASH_ID)) return
+  if (!splashEl()) return
 
-  const quietMs = options.quietMs ?? 200
+  quietMs = options.quietMs ?? 200
   const maxWaitMs = options.maxWaitMs ?? 8000
   const apis = Array.isArray(options.api) ? options.api : options.api ? [options.api] : []
 
-  let inflight = 0
-  let quietTimer: ReturnType<typeof setTimeout> | undefined
-
-  const done = () => {
-    clearTimeout(quietTimer)
-    // Doble rAF: el render definitivo llega a pintarse BAJO el velo antes
-    // del fundido (sin esto el fundido podría destapar un frame a medias).
-    requestAnimationFrame(() => requestAnimationFrame(dismissSplash))
-  }
-  const armQuiet = () => {
-    clearTimeout(quietTimer)
-    quietTimer = setTimeout(done, quietMs)
-  }
+  // Doble rAF: el render definitivo llega a pintarse BAJO el velo antes
+  // del fundido (sin esto el fundido podría destapar un frame a medias).
+  onQuiet = () => requestAnimationFrame(() => requestAnimationFrame(dismissSplash))
 
   for (const api of apis) {
     api.interceptors.request.use((config) => {
@@ -91,3 +135,54 @@ export function watchSplash(options: WatchSplashOptions = {}): void {
   armQuiet()
   setTimeout(dismissSplash, maxWaitMs)
 }
+
+/**
+ * Velo de carga en las navegaciones SPA: si tras `showDelayMs` la
+ * navegación sigue pendiente o hay peticiones en vuelo, el splash vuelve a
+ * cubrir la ventana (tapando el «negro» de la vista sin datos) y cae en el
+ * siguiente reposo de red. Una navegación instantánea no lo ve ni un frame.
+ * Requiere watchSplash({ api }) antes (es quien alimenta el contador).
+ */
+export function setupNavigationSplash(
+  router: SplashRouterLike,
+  options: NavigationSplashOptions = {},
+): void {
+  if (typeof document === 'undefined') return
+  if (!splashEl()) return
+
+  const showDelayMs = options.showDelayMs ?? 120
+  const maxWaitMs = options.maxWaitMs ?? 8000
+
+  let navPending = false
+  let showTimer: ReturnType<typeof setTimeout> | undefined
+  let maxTimer: ReturnType<typeof setTimeout> | undefined
+
+  const hide = () => {
+    clearTimeout(showTimer)
+    clearTimeout(maxTimer)
+    requestAnimationFrame(() => requestAnimationFrame(dismissSplash))
+  }
+
+  router.beforeEach(() => {
+    navPending = true
+    onQuiet = hide
+    clearTimeout(showTimer)
+    showTimer = setTimeout(() => {
+      if (navPending || inflight > 0) showSplash()
+    }, showDelayMs)
+    clearTimeout(maxTimer)
+    maxTimer = setTimeout(hide, maxWaitMs)
+  })
+
+  router.afterEach(() => {
+    navPending = false
+    // Vista sin peticiones propias: el reposo ya está en curso → fundido.
+    if (inflight <= 0) armQuiet()
+  })
+
+  // Navegación abortada/errónea: no dejar el velo puesto.
+  router.onError?.(() => {
+    navPending = false
+    hide()
+  })
+}