@dotrino/install 0.1.1 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dotrino/install",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Botón de \"Instalar app\" (PWA) unificado del ecosistema Dotrino: Web Component <dotrino-install> que captura beforeinstallprompt temprano, maneja iOS con un modal de instrucciones (sin alert) y se oculta si ya está instalada. Vue o vanilla. Sin JS de terceros ni cookies, bilingüe es/en.",
   "type": "module",
   "main": "src/index.js",

package/src/index.d.ts

@@ -1,11 +1,39 @@
-export type InstallOutcome = 'accepted' | 'dismissed' | 'instructions' | 'installed'
+export type InstallOutcome = 'accepted' | 'dismissed' | 'instructions' | 'installed' | 'relaunch'
+export type InstallContext = 'installed' | 'native' | 'ios' | 'relaunch' | 'none'
 
 /** ¿La app ya corre como instalada (display-mode standalone) o se instaló ya? */
 export function isAppInstalled(): boolean
 
+/** Atajo legible de `isAppInstalled()`. */
+export function isStandalone(): boolean
+
 /** Detección de iOS/iPadOS (incluye el iPad que se reporta como Mac). */
 export function isIOS(): boolean
 
+/** Detección de Android. */
+export function isAndroid(): boolean
+
+/** Nombre del parámetro marcador ("pwa-install"). */
+export const INSTALL_PARAM: string
+
+/** ¿La URL trae el marcador `?pwa-install=1` (tras relanzar en Chrome)? */
+export function hasInstallFlag(param?: string): boolean
+
+/** ¿La app fue abierta desde el hub instalado (el home le puso `?hub=1`)? */
+export function isEmbeddedHub(): boolean
+
+/**
+ * `intent://` que reabre la app en Chrome (no el Custom Tab/webview embebido)
+ * con `?pwa-install=1`, con fallback a https. Solo útil en Android. null si falla.
+ */
+export function chromeInstallUrl(param?: string): string | null
+
+/**
+ * Estado de cara a la UI: 'installed' | 'native' (prompt nativo) | 'ios'
+ * (instrucciones Safari) | 'relaunch' (Android embebido → abrir en Chrome) | 'none'.
+ */
+export function installContext(): InstallContext
+
 /** ¿Tiene sentido ofrecer instalar? (prompt nativo disponible, o iOS, y no instalada). */
 export function canInstall(): boolean
 
@@ -26,8 +54,11 @@ export const HOME_DEFAULT: string
 
 /**
  * Custom element del botón de instalar (`<dotrino-install>`).
- * Atributos: `lang` ("es"|"en"), `label` (texto), `icon` ("false" oculta el icono).
- * Eventos: `cc-install` (cancelable), `cc-install-result` (detail.outcome).
+ * Atributos: `lang` ("es"|"en"), `label` (texto), `icon` ("false" oculta el icono),
+ * `app-name` y `app-icon` (título e icono del overlay grande de instalación).
+ * En Android dentro de un Custom Tab (sin prompt nativo) el botón relanza la app
+ * en Chrome; al llegar con `?pwa-install=1` muestra un overlay grande centrado.
+ * Eventos: `cc-install` (cancelable), `cc-install-result` (detail.outcome, incluye 'relaunch').
  */
 export class DotrinoInstall extends HTMLElement {
   /** Dispara la instalación desde JS (igual que el click del usuario). */

package/src/index.js

@@ -7,7 +7,7 @@
  * recurrentes que aquí se arreglan de una vez:
  *
  *   1. El evento `beforeinstallprompt` se dispara MUY pronto (a veces antes de
- *      montar el componente). Si lo escuchás dentro de onMounted lo perdés y el
+ *      montar el componente). Si lo escuchas dentro de onMounted lo pierdes y el
  *      botón nunca aparece. Aquí lo capturamos a nivel de módulo, en import.
  *   2. iOS/Safari NO dispara `beforeinstallprompt` y no hay API de instalación:
  *      la única vía es "Compartir → Añadir a pantalla de inicio". Mostramos esas
@@ -24,7 +24,7 @@
  *   <dotrino-install></dotrino-install>
  *   <dotrino-install lang="en" label="Install"></dotrino-install>
  *
- * Uso programático (si querés tu propio botón) — ver también ./vue:
+ * Uso programático (si quieres tu propio botón) — ver también ./vue:
  *   import { canInstall, promptInstall, onInstallStateChange } from '@dotrino/install'
  *   if (canInstall()) showMyButton()
  *   await promptInstall()   // dispara el prompt nativo o el modal iOS/fallback
@@ -41,6 +41,7 @@ const HOME_DEFAULT = 'https://dotrino.com'
 
 let _deferred = null      // el BeforeInstallPromptEvent diferido (o null)
 let _installed = false    // se marcó appinstalled en esta sesión
+let _settled = false      // pasó el margen de espera del prompt nativo
 const _subs = new Set()   // suscriptores a cambios de estado (re-render)
 
 function _emit () {
@@ -49,6 +50,13 @@ function _emit () {
   }
 }
 
+// Tras un margen sin prompt nativo (Android), asumimos contexto embebido (Custom
+// Tab abierto desde otra PWA): ahí Chrome NO dispara `beforeinstallprompt`, así
+// que en vez de ocultar el botón ofreceremos relanzar en Chrome (ver más abajo).
+if (typeof window !== 'undefined') {
+  try { setTimeout(() => { _settled = true; _emit() }, 1400) } catch (_) {}
+}
+
 function _onBIP (e) {
   // Evita que el navegador muestre su mini-infobar; nosotros decidimos cuándo.
   try { e.preventDefault() } catch (_) {}
@@ -91,6 +99,70 @@ export function isIOS () {
   return false
 }
 
+/** ¿Corre como app instalada (standalone)? Atajo legible. */
+export function isStandalone () {
+  return isAppInstalled()
+}
+
+/** Detección de Android. */
+export function isAndroid () {
+  try { return /Android/i.test(navigator.userAgent || '') } catch (_) { return false }
+}
+
+const INSTALL_PARAM = 'pwa-install'
+const HUB_PARAM = 'hub'
+
+/** ¿La URL trae el marcador de "abrir para instalar" (tras relanzar en Chrome)? */
+export function hasInstallFlag (param = INSTALL_PARAM) {
+  try { return new URLSearchParams(location.search).has(param) } catch (_) { return false }
+}
+
+/**
+ * ¿La app fue abierta DESDE el hub instalado (el home le puso `?hub=1`)? En ese
+ * caso corre embebida en un Custom Tab que puede reportarse como standalone; este
+ * marcador es la señal fiable de "estoy embebido, ofrece instalar en Chrome".
+ */
+export function isEmbeddedHub () {
+  try { return new URLSearchParams(location.search).has(HUB_PARAM) } catch (_) { return false }
+}
+
+/**
+ * Construye un `intent://` que reabre ESTA misma app en **Chrome** (no en el
+ * Custom Tab/webview embebido) con el marcador `?pwa-install=1`, con fallback a
+ * la URL https normal si Chrome no está. Solo tiene sentido en Android.
+ */
+export function chromeInstallUrl (param = INSTALL_PARAM) {
+  try {
+    const u = new URL(location.href)
+    u.searchParams.delete(HUB_PARAM) // el marcador del hub no debe viajar a Chrome
+    u.searchParams.set(param, '1')
+    const target = `${u.host}${u.pathname}${u.search}`
+    const fallback = encodeURIComponent(u.toString())
+    return `intent://${target}#Intent;scheme=https;package=com.android.chrome;S.browser_fallback_url=${fallback};end`
+  } catch (_) { return null }
+}
+
+/**
+ * Estado de instalación de cara a la UI:
+ *  - 'installed'  ya instalada / standalone → no ofrecer.
+ *  - 'native'     hay prompt nativo (Chrome instalable) → instalar de un toque.
+ *  - 'ios'        iOS/Safari → instrucciones "Añadir a pantalla de inicio".
+ *  - 'relaunch'   Android sin prompt nativo (probable Custom Tab embebido) →
+ *                 relanzar en Chrome con `chromeInstallUrl()`.
+ *  - 'none'       nada que ofrecer (todavía esperando, o navegador sin soporte).
+ */
+export function installContext () {
+  // Prompt nativo (Chrome real) siempre gana.
+  if (_deferred) return 'native'
+  // Embebido desde el hub (Android): ofrecer relanzar en Chrome AUNQUE el Custom
+  // Tab se reporte como standalone (por eso esto va ANTES de isAppInstalled()).
+  if (isEmbeddedHub() && isAndroid()) return 'relaunch'
+  if (isAppInstalled()) return 'installed'
+  if (isIOS()) return 'ios'
+  if (_settled && isAndroid()) return 'relaunch'
+  return 'none'
+}
+
 /**
  * ¿Tiene sentido ofrecer instalar? true si hay prompt nativo disponible, o si es
  * iOS (instalable a mano vía Compartir), siempre que NO esté ya instalada.
@@ -153,7 +225,12 @@ const I18N = {
     iosStep2: 'Elige «Añadir a pantalla de inicio»',
     otherIntro: 'Tu navegador no permite la instalación con un toque. Para instalarla:',
     otherStep: 'Abre el menú del navegador y elige «Instalar app» (o «Añadir a pantalla de inicio»).',
-    close: 'Cerrar'
+    close: 'Cerrar',
+    bigTitle: 'Instala la app',
+    bigTitleNamed: (n) => `Instala ${n}`,
+    bigSub: 'Acceso directo en tu pantalla de inicio, sin tienda de apps.',
+    preparing: 'Preparando…',
+    notNow: 'Ahora no'
   },
   en: {
     install: 'Install App',
@@ -163,7 +240,12 @@ const I18N = {
     iosStep2: 'Choose “Add to Home Screen”',
     otherIntro: 'Your browser can’t install with one tap. To install it:',
     otherStep: 'Open the browser menu and choose “Install app” (or “Add to Home Screen”).',
-    close: 'Close'
+    close: 'Close',
+    bigTitle: 'Install the app',
+    bigTitleNamed: (n) => `Install ${n}`,
+    bigSub: 'A shortcut on your home screen, no app store.',
+    preparing: 'Preparing…',
+    notNow: 'Not now'
   }
 }
 
@@ -263,25 +345,47 @@ const STYLE = `
     flex: none; width: 24px; height: 24px; border-radius: 50%;
     display: inline-flex; align-items: center; justify-content: center;
     font-size: 13px; font-weight: 700;
-    background: var(--cc-install-accent, #84cc16); color: #14110f;
+    background: var(--cc-install-accent, #84cc16); color: var(--cc-install-accent-color, #14110f);
   }
   .steps svg { width: 20px; height: 20px; flex: none; }
   .card .ok {
     all: unset; box-sizing: border-box; cursor: pointer;
     display: block; width: 100%; text-align: center;
     padding: 11px; border-radius: 12px; font-weight: 700;
-    background: var(--cc-install-accent, #84cc16); color: #14110f;
+    background: var(--cc-install-accent, #84cc16); color: var(--cc-install-accent-color, #14110f);
   }
   .card .ok:focus-visible { outline: 2px solid currentColor; outline-offset: 2px; }
+
+  /* Overlay grande y centrado: aparece al llegar con ?pwa-install=1 (relanzado en Chrome). */
+  .big { text-align: center; }
+  .big .app-icon { width: 72px; height: 72px; border-radius: 18px; margin: 2px auto 14px; display: block; }
+  .big h2 { font-size: 20px; }
+  .big .sub { margin: 0 0 18px; opacity: .8; }
+  .big .cta {
+    all: unset; box-sizing: border-box; cursor: pointer;
+    display: flex; align-items: center; justify-content: center; gap: 8px;
+    width: 100%; padding: 14px; border-radius: 14px; font-weight: 800; font-size: 16px;
+    background: var(--cc-install-accent, #84cc16); color: var(--cc-install-accent-color, #14110f);
+  }
+  .big .cta[disabled] { opacity: .6; cursor: default; }
+  .big .cta svg { width: 20px; height: 20px; }
+  .big .manual { margin: 14px 2px 0; font-size: 14px; opacity: .85; }
+  .big .dismiss {
+    all: unset; box-sizing: border-box; cursor: pointer;
+    display: block; width: 100%; text-align: center;
+    margin-top: 10px; padding: 8px; font-weight: 600; opacity: .7;
+  }
 `
 
 class DotrinoInstall extends HTMLElement {
-  static get observedAttributes () { return ['lang', 'label', 'icon'] }
+  static get observedAttributes () { return ['lang', 'label', 'icon', 'app-name', 'app-icon'] }
 
   constructor () {
     super()
     this.attachShadow({ mode: 'open' })
-    this._modalOpen = false
+    this._modalOpen = false   // modal de instrucciones (iOS/fallback)
+    this._bigOpen = false     // overlay grande de instalación (?pwa-install=1)
+    this._bigManual = false   // el overlay grande pasó a instrucciones manuales
     this._unsub = null
     this._onState = this._render.bind(this)
     this._onKey = this._onKey.bind(this)
@@ -289,12 +393,52 @@ class DotrinoInstall extends HTMLElement {
 
   connectedCallback () {
     this._unsub = onInstallStateChange(this._onState)
+    // Si llegamos con el marcador (relanzados en Chrome para instalar), abrimos
+    // el overlay grande centrado. Solo el primero monta el overlay (singleton).
+    if (hasInstallFlag() && !isAppInstalled() && !DotrinoInstall._bigClaimed) {
+      DotrinoInstall._bigClaimed = true
+      this._bigOpen = true
+      try { document.addEventListener('keydown', this._onKey) } catch (_) {}
+      // Si en unos segundos no hay prompt nativo, ofrecemos la vía manual.
+      setTimeout(() => {
+        if (this._bigOpen && !hasNativePrompt() && !isAppInstalled()) { this._bigManual = true; this._render() }
+      }, 4000)
+    }
     this._render()
   }
 
   disconnectedCallback () {
     if (this._unsub) { this._unsub(); this._unsub = null }
     try { document.removeEventListener('keydown', this._onKey) } catch (_) {}
+    if (this._portal) { try { this._portal.remove() } catch (_) {} this._portal = null; this._portalShadow = null }
+  }
+
+  /* Los modales (instrucciones / overlay grande) usan position:fixed para
+     centrarse en la ventana. Si el <dotrino-install> vive dentro de un ancestro
+     con `backdrop-filter`/`transform` (topbars), ese ancestro se vuelve el bloque
+     contenedor del fixed y el modal se descoloca. Por eso los renderizamos en un
+     PORTAL colgado de <body>, con su propio shadow root y el tema copiado. */
+  _portalRoot () {
+    if (!this._portal) {
+      this._portal = document.createElement('div')
+      this._portal.setAttribute('data-dotrino-install-portal', '')
+      this._portalShadow = this._portal.attachShadow({ mode: 'open' })
+      try {
+        const cs = getComputedStyle(this)
+        for (const v of ['--cc-install-accent', '--cc-install-modal-bg', '--cc-install-modal-color']) {
+          const val = cs.getPropertyValue(v)
+          if (val && val.trim()) this._portal.style.setProperty(v, val.trim())
+        }
+      } catch (_) {}
+      document.body.appendChild(this._portal)
+    }
+    return this._portalShadow
+  }
+
+  _renderPortal (innerHTML) {
+    const root = this._portalRoot()
+    root.innerHTML = innerHTML ? `<style>${STYLE}</style>${innerHTML}` : ''
+    return root
   }
 
   attributeChangedCallback () {
@@ -302,39 +446,68 @@ class DotrinoInstall extends HTMLElement {
   }
 
   _render () {
-    const show = canInstall()
-    // Oculta el host por completo cuando no hay nada que ofrecer (no ocupa espacio).
-    this.hidden = !show
-    if (!show && !this._modalOpen) {
-      this.shadowRoot.innerHTML = ''
-      return
-    }
+    const ctx = installContext()                 // installed|native|ios|relaunch|none
+    const showBtn = ctx === 'native' || ctx === 'ios' || ctx === 'relaunch'
+    // Oculta el host por completo cuando no hay botón ni modal abierto.
+    this.hidden = !showBtn && !this._modalOpen && !this._bigOpen
+    if (this.hidden) { this.shadowRoot.innerHTML = ''; return }
 
     const lang = resolveLang(this.getAttribute('lang'))
     const t = I18N[lang]
     const label = this.getAttribute('label') != null ? this.getAttribute('label') : t.install
     const showIcon = (this.getAttribute('icon') || '').toLowerCase() !== 'false'
 
+    // Botón pequeño en el shadow propio (inline en la topbar).
     let html = `<style>${STYLE}</style>`
-    html += `<button class="trigger" type="button" part="button" aria-label="${label || t.install}">`
-    if (showIcon) html += `<span class="ico" part="icon">${ICON_DOWNLOAD}</span>`
-    html += `<span class="lbl" part="label">${label}</span></button>`
-
-    if (this._modalOpen) html += this._modalHTML(lang)
-
+    if (showBtn) {
+      html += `<button class="trigger" type="button" part="button" aria-label="${label || t.install}">`
+      if (showIcon) html += `<span class="ico" part="icon">${ICON_DOWNLOAD}</span>`
+      html += `<span class="lbl" part="label">${label}</span></button>`
+    }
     this.shadowRoot.innerHTML = html
     const btn = this.shadowRoot.querySelector('button.trigger')
-    if (btn) btn.addEventListener('click', () => this._activate())
-
-    if (this._modalOpen) {
-      const close = () => this._closeModal()
-      const backdrop = this.shadowRoot.querySelector('.backdrop')
-      const okBtn = this.shadowRoot.querySelector('.ok')
-      if (backdrop) backdrop.addEventListener('click', (e) => { if (e.target === backdrop) close() })
-      if (okBtn) okBtn.addEventListener('click', close)
+    if (btn) btn.addEventListener('click', () => this._activate(ctx))
+
+    // Modales en el PORTAL (body), para que el fixed se centre en la ventana.
+    if (this._bigOpen) {
+      const root = this._renderPortal(this._bigHTML(lang))
+      const backdrop = root.querySelector('.backdrop')
+      if (backdrop) backdrop.addEventListener('click', (e) => { if (e.target === backdrop) this._closeBig() })
+      root.querySelector('.dismiss')?.addEventListener('click', () => this._closeBig())
+      root.querySelector('.cta')?.addEventListener('click', () => this._bigInstall())
+    } else if (this._modalOpen) {
+      const root = this._renderPortal(this._modalHTML(lang))
+      const backdrop = root.querySelector('.backdrop')
+      const okBtn = root.querySelector('.ok')
+      if (backdrop) backdrop.addEventListener('click', (e) => { if (e.target === backdrop) this._closeModal() })
+      if (okBtn) okBtn.addEventListener('click', () => this._closeModal())
+    } else if (this._portalShadow) {
+      this._renderPortal('') // limpia el portal cuando no hay modal
     }
   }
 
+  /** Overlay grande y centrado de instalación (al llegar con ?pwa-install=1). */
+  _bigHTML (lang) {
+    const t = I18N[lang]
+    const name = this.getAttribute('app-name')
+    const icon = this.getAttribute('app-icon')
+    const title = name ? t.bigTitleNamed(name) : t.bigTitle
+    const ready = hasNativePrompt()
+    let body
+    if (this._bigManual) {
+      const step = isIOS() ? `${t.iosStep1} → ${t.iosStep2}` : t.otherStep
+      body = `<p class="manual">${step}</p>`
+    } else {
+      body = `<button class="cta" type="button" ${ready ? '' : 'disabled'}>${ICON_DOWNLOAD}` +
+        `<span>${ready ? t.install : t.preparing}</span></button>`
+    }
+    return `<div class="backdrop" part="modal" role="dialog" aria-modal="true" aria-label="${title}">` +
+      `<div class="card big" part="modal-card">` +
+      (icon ? `<img class="app-icon" src="${icon}" alt="" width="72" height="72" />` : '') +
+      `<h2>${title}</h2><p class="sub">${t.bigSub}</p>${body}` +
+      `<button class="dismiss" type="button">${t.notNow}</button></div></div>`
+  }
+
   _modalHTML (lang) {
     const t = I18N[lang]
     let steps
@@ -350,10 +523,19 @@ class DotrinoInstall extends HTMLElement {
       `<button class="ok" type="button">${t.close}</button></div></div>`
   }
 
-  async _activate () {
+  async _activate (ctx) {
     const ev = new CustomEvent('cc-install', { bubbles: true, composed: true, cancelable: true })
     if (!this.dispatchEvent(ev)) return // la app canceló para hacer lo suyo
 
+    // Contexto embebido (Custom Tab desde otra PWA): no hay prompt nativo, así que
+    // relanzamos la app en Chrome, donde la instalación sí funciona.
+    if (ctx === 'relaunch') {
+      const url = chromeInstallUrl()
+      this.dispatchEvent(new CustomEvent('cc-install-result', { bubbles: true, composed: true, detail: { outcome: 'relaunch' } }))
+      if (url) { try { location.href = url } catch (_) {} }
+      return
+    }
+
     const outcome = await promptInstall()
     if (outcome === 'instructions') {
       this._openModal()
@@ -364,6 +546,22 @@ class DotrinoInstall extends HTMLElement {
     this._render()
   }
 
+  /** Botón grande del overlay: dispara el prompt nativo; si no hay, instrucciones. */
+  async _bigInstall () {
+    if (!hasNativePrompt()) { this._bigManual = true; this._render(); return }
+    const outcome = await promptInstall()
+    this.dispatchEvent(new CustomEvent('cc-install-result', { bubbles: true, composed: true, detail: { outcome } }))
+    if (outcome === 'accepted' || outcome === 'installed') this._closeBig()
+    else if (outcome === 'instructions') { this._bigManual = true; this._render() }
+    else this._render()
+  }
+
+  _closeBig () {
+    this._bigOpen = false
+    try { document.removeEventListener('keydown', this._onKey) } catch (_) {}
+    this._render()
+  }
+
   _openModal () {
     this._modalOpen = true
     try { document.addEventListener('keydown', this._onKey) } catch (_) {}
@@ -377,7 +575,9 @@ class DotrinoInstall extends HTMLElement {
   }
 
   _onKey (e) {
-    if (e.key === 'Escape') this._closeModal()
+    if (e.key !== 'Escape') return
+    if (this._bigOpen) this._closeBig()
+    else this._closeModal()
   }
 
   /** Dispara la instalación desde JS de la app (igual que el click). */
@@ -388,4 +588,6 @@ if (typeof customElements !== 'undefined' && !customElements.get('dotrino-instal
   customElements.define('dotrino-install', DotrinoInstall)
 }
 
-export { DotrinoInstall, HOME_DEFAULT }
+DotrinoInstall._bigClaimed = false
+
+export { DotrinoInstall, HOME_DEFAULT, INSTALL_PARAM }