@edc-motor/ui 0.5.19 → 0.5.21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edc-motor/ui",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "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,16 @@ 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 { createSwrGet, type SwrGetter } from './lib/swr'
 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,24 @@ 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'
+
+// Peticiones DE FONDO: con `edcBackground: true` en el config de axios, la
+// petición no cuenta para el velo — es relleno o refresco (catálogos con su
+// propia presentación de carga, revalidaciones SWR, sondeos), no «la página
+// aún no puede pintarse». Así el velo queda solo para las cargas de página.
+declare module 'axios' {
+  interface AxiosRequestConfig {
+    edcBackground?: boolean
+  }
+}
 
 export interface WatchSplashOptions {
   /** Cliente(s) axios cuyas peticiones marcan el arranque (createApi). */
@@ -34,53 +52,91 @@ 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) => {
-      inflight++
-      clearTimeout(quietTimer)
+      if (!config.edcBackground) {
+        inflight++
+        clearTimeout(quietTimer)
+      }
       return config
     })
     api.interceptors.response.use(
       (response) => {
-        if (--inflight <= 0) armQuiet()
+        if (!response.config.edcBackground && --inflight <= 0) armQuiet()
         return response
       },
-      (error) => {
-        if (--inflight <= 0) armQuiet()
+      (error: { config?: { edcBackground?: boolean } }) => {
+        if (!error?.config?.edcBackground && --inflight <= 0) armQuiet()
         return Promise.reject(error)
       },
     )
@@ -91,3 +147,56 @@ 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
+
+  // 250 ms: una API razonable responde antes y el velo ni aparece; por
+  // debajo saltaba en CADA navegación de producción (feo y alarmante).
+  const showDelayMs = options.showDelayMs ?? 250
+  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()
+  })
+}

package/src/lib/swr.ts

@@ -0,0 +1,73 @@
+import type { AxiosInstance, AxiosRequestConfig } from 'axios'
+
+// Caché SWR en MEMORIA para los GET de contenido de la web pública
+// (stale-while-revalidate): la primera visita a una URL espera a la red
+// (y el velo de navegación puede aparecer); las siguientes se sirven de la
+// memoria AL INSTANTE — sin velo, sin negro — mientras una revalidación DE
+// FONDO (edcBackground: no cuenta para el velo) trae lo fresco y solo
+// re-aplica si algo cambió. La memoria vive lo que la pestaña: nada que
+// invalidar entre sesiones.
+//
+// Uso: const swrGet = createSwrGet(api)  // una vez, junto al cliente
+//      await swrGet<Payload>('/pages/home', undefined, (data) => { ... })
+// El callback puede llegar DOS veces (caché y luego fresco): debe ser
+// idempotente y, si la vista pudo cambiar mientras tanto (requestId),
+// comprobar dentro que sigue vigente.
+
+export interface SwrGetter {
+  <T>(
+    url: string,
+    config: AxiosRequestConfig | undefined,
+    onData: (data: T, fresh: boolean) => void,
+  ): Promise<void>
+  /** Vacía la memoria (p. ej. al cerrar sesión, si el contenido depende de ella). */
+  clear(): void
+}
+
+export function createSwrGet(api: AxiosInstance): SwrGetter {
+  const memory = new Map<string, unknown>()
+
+  // La clave incluye los params por defecto del cliente (el `?locale` que
+  // inyecta el store de locales) además de los de la petición: la misma URL
+  // en otro idioma es OTRA entrada.
+  function keyFor(url: string, config?: AxiosRequestConfig): string {
+    const params: Record<string, unknown> = {
+      ...(api.defaults.params as Record<string, unknown> | undefined),
+      ...(config?.params as Record<string, unknown> | undefined),
+    }
+    const query = Object.keys(params)
+      .sort()
+      .map((k) => `${k}=${JSON.stringify(params[k])}`)
+      .join('&')
+    return `${url}?${query}`
+  }
+
+  async function run<T>(
+    url: string,
+    config: AxiosRequestConfig | undefined,
+    onData: (data: T, fresh: boolean) => void,
+  ): Promise<void> {
+    const key = keyFor(url, config)
+    if (memory.has(key)) {
+      const cached = memory.get(key) as T
+      onData(cached, false)
+      void api
+        .get<T>(url, { ...config, edcBackground: true })
+        .then(({ data }) => {
+          memory.set(key, data)
+          if (JSON.stringify(data) !== JSON.stringify(cached)) onData(data, true)
+        })
+        .catch(() => {
+          // la revalidación es oportunista: si falla, se queda lo cacheado
+        })
+      return
+    }
+    const { data } = await api.get<T>(url, config)
+    memory.set(key, data)
+    onData(data, true)
+  }
+
+  const getter = run as SwrGetter
+  getter.clear = () => memory.clear()
+  return getter
+}