veo-sdk 0.4.2 → 0.5.1

package/dist/index.cjs

@@ -615,12 +615,12 @@ function buildButtonBlock(block, doc, callbacks) {
   applyBlockStyle(btn, block.style, "button");
   btn.addEventListener("click", () => {
     const action = block.action ?? "dismiss";
-    const url = action === "url" && typeof block.url === "string" && isSafeUrl(block.url) ? block.url : void 0;
+    const target = action === "url" && typeof block.url === "string" && isSafeUrl(block.url) ? block.url : action === "guide" && typeof block.targetGuideId === "string" && block.targetGuideId ? block.targetGuideId : void 0;
     const meta = {
       ...typeof block.id === "string" && block.id ? { buttonId: block.id } : {},
       ...typeof block.text === "string" && block.text ? { buttonText: block.text } : {}
     };
-    callbacks.onCtaClick(action, url, Object.keys(meta).length ? meta : void 0);
+    callbacks.onCtaClick(action, target, Object.keys(meta).length ? meta : void 0);
   });
   return btn;
 }
@@ -1259,10 +1259,22 @@ var init_styles = __esm({
   padding: 3px 9px;
   white-space: nowrap;
 }
+.veo-badge--text {
+  color: var(--veo-primary);
+  font-weight: 600;
+  white-space: nowrap;
+  text-decoration: underline dotted;
+  text-underline-offset: 3px;
+}
 .veo-badge--image img { display: block; border-radius: 4px; object-fit: cover; }
 /* El tooltip del badge usa strategy fixed (el host vive dentro del flujo del
-   cliente; un absoluto se recortar\xEDa con overflow de ancestros). */
-.veo-badge-tooltip { position: fixed; }
+   cliente; un absoluto se recortar\xEDa con overflow de ancestros). Su ancho es
+   personalizable v\xEDa var dedicada (--veo-width no sirve: el :host la define
+   en 420px siempre y pisar\xEDa el default de 300px de los tooltips). */
+.veo-badge-tooltip {
+  position: fixed;
+  max-width: var(--veo-badge-tip-width, 300px);
+}
 @keyframes veo-badge-pulse {
   0% { box-shadow: 0 0 0 0 color-mix(in srgb, var(--veo-primary) 45%, transparent); }
   70% { box-shadow: 0 0 0 7px transparent; }
@@ -1439,7 +1451,7 @@ function readBadgeConfig(step) {
   const raw = step.style?.badge;
   if (!raw || typeof raw !== "object") return { kind: "icon" };
   const b = raw;
-  const kind = b.kind === "dot" || b.kind === "pill" || b.kind === "image" || b.kind === "icon" ? b.kind : "icon";
+  const kind = b.kind === "dot" || b.kind === "pill" || b.kind === "text" || b.kind === "image" || b.kind === "icon" ? b.kind : "icon";
   return {
     kind,
     icon: typeof b.icon === "string" ? b.icon : null,
@@ -1470,6 +1482,12 @@ function buildBadgeElement(config, doc) {
       if (config.color) btn.style.background = config.color;
       break;
     }
+    case "text": {
+      btn.textContent = config.text?.slice(0, 32) || "Nuevo";
+      btn.style.fontSize = `${clamp2(Math.round(size * 0.7), 9, 28)}px`;
+      if (config.color) btn.style.color = config.color;
+      break;
+    }
     case "image": {
       if (config.imageUrl && isSafeUrl(config.imageUrl)) {
         const img = doc.createElement("img");
@@ -1531,6 +1549,13 @@ var init_badge_renderer = __esm({
         const { host, root } = this.createHost();
         const ownerDocument = root.ownerDocument ?? document;
         this.applyDesign(step.style);
+        const tipWidth = step.style?.width;
+        if (typeof tipWidth === "number" && Number.isFinite(tipWidth)) {
+          host.style.setProperty(
+            "--veo-badge-tip-width",
+            `${Math.min(720, Math.max(220, tipWidth))}px`
+          );
+        }
         this.trigger = step.style?.badgeTrigger === "click" ? "click" : "hover";
         const rawSide = step.style?.tooltipPlacement;
         this.side = rawSide === "bottom" || rawSide === "left" || rawSide === "right" ? rawSide : "top";
@@ -1554,20 +1579,14 @@ var init_badge_renderer = __esm({
           });
         };
         const buildTooltipContent = (s) => buildStepContent(s, ownerDocument, {
-          onCtaClick: (action, url, meta) => {
+          onCtaClick: (action, target, meta) => {
             emit("cta_clicked", meta);
-            if (action === "url" && url) window.open(url, "_blank", "noopener,noreferrer");
-            if (action === "dismiss") {
-              emit("dismissed");
-              context.onClose();
-              return;
-            }
+            if (action === "url" && target) window.open(target, "_blank", "noopener,noreferrer");
             this.closeTooltip();
+            if (action === "guide" && target) context.onOpenGuide?.(target);
           },
-          onDismiss: () => {
-            emit("dismissed");
-            context.onClose();
-          }
+          // La ✕ también cierra solo el tooltip (nunca el badge, nunca dismissed).
+          onDismiss: () => this.closeTooltip()
         });
         const content = buildTooltipContent(step);
         tooltip.appendChild(content);
@@ -1820,7 +1839,10 @@ var init_banner_renderer = __esm({
           ownerDocument,
           context.nav.callbacks
         ) : buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         banner.appendChild(content);
@@ -1835,7 +1857,10 @@ var init_banner_renderer = __esm({
           this.liveContainer = banner;
           this.liveContent = content;
           this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-            onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+            onCtaClick: (action, target, meta) => {
+              dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+              if (action === "guide" && target) context.onOpenGuide?.(target);
+            },
             onDismiss: () => dismiss("dismissed")
           });
           this.liveKey = this.liveKeyOf(step);
@@ -2496,7 +2521,10 @@ var init_inline_renderer = __esm({
           context.onClose();
         };
         const content = buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         card.appendChild(content);
@@ -2505,7 +2533,10 @@ var init_inline_renderer = __esm({
         this.liveContent = content;
         this.liveKey = `${selector}|${position}`;
         this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         context.onInteraction({ guideId: context.guide.guideId, stepIndex: 0, action: "shown" });
@@ -2565,7 +2596,10 @@ var init_modal_renderer = __esm({
           ownerDocument,
           context.nav.callbacks
         ) : buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         card.appendChild(content);
@@ -2575,7 +2609,10 @@ var init_modal_renderer = __esm({
           this.liveContainer = card;
           this.liveContent = content;
           this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-            onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+            onCtaClick: (action, target, meta) => {
+              dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+              if (action === "guide" && target) context.onOpenGuide?.(target);
+            },
             onDismiss: () => dismiss("dismissed")
           });
         }
@@ -2640,8 +2677,9 @@ var init_tooltip_renderer = __esm({
           context.onClose();
         };
         const content = buildStepContent(step, ownerDocument, {
-          onCtaClick: (action, url, meta) => {
-            dismiss("cta_clicked", action === "url" ? url : void 0, meta);
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
           },
           onDismiss: () => dismiss("dismissed")
         });
@@ -2674,7 +2712,10 @@ var init_tooltip_renderer = __esm({
         this.liveContent = content;
         this.liveKey = selector;
         this.liveBuild = (s) => buildStepContent(s, ownerDocument, {
-          onCtaClick: (action, url, meta) => dismiss("cta_clicked", action === "url" ? url : void 0, meta),
+          onCtaClick: (action, target, meta) => {
+            dismiss("cta_clicked", action === "url" ? target : void 0, meta);
+            if (action === "guide" && target) context.onOpenGuide?.(target);
+          },
           onDismiss: () => dismiss("dismissed")
         });
         context.onInteraction({
@@ -2891,6 +2932,10 @@ var init_guide_preview = __esm({
             onClose: () => this.close(),
             onTrack: () => {
             },
+            // Encadenado en preview: no-op — el editor no puede montar otra guía
+            // guardada; el click igual cierra la preview actual (vía onCtaClick).
+            onOpenGuide: () => {
+            },
             // Preview de forms: por defecto simula el envío SIN escribir props;
             // el caller puede pasar `formSubmit` real (link de preview).
             onFormSubmit: this.input?.formSubmit ?? (() => Promise.resolve(true)),
@@ -5333,6 +5378,12 @@ var GuidesController = class {
     this.resolveCache = null;
     /** Resolución idéntica en vuelo, para coalescer llamadas concurrentes. */
     this.inflightResolve = null;
+    /**
+     * Disparadores por interacción armados (`on_click`/`on_hover`): guideId →
+     * desarme del listener. Se re-arman desde cero en cada `checkGuides` (el
+     * resolve fresco manda) y se limpian en `destroy()`.
+     */
+    this.armedTriggers = /* @__PURE__ */ new Map();
     this.debug = config.debug === true;
     this.apiUrl = config.apiUrl;
     this.apiKey = config.apiKey;
@@ -5390,26 +5441,80 @@ var GuidesController = class {
       return;
     }
     if (this.debug) console.log(`[veo] guides: ${guides.length} eligible at ${pageUrl}`);
+    this.disarmTriggers();
     for (const guide of guides) {
-      if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) {
-        if (this.debug) console.log(`[veo] guides: filtered locally guideId=${guide.guideId}`);
-        continue;
-      }
-      if (this.activeByGuideId.has(guide.guideId)) {
-        if (this.debug) console.log(`[veo] guides: already shown guideId=${guide.guideId}`);
+      const trigger = guide.activationRules.trigger;
+      if ((trigger === "on_click" || trigger === "on_hover") && guide.activationRules.selector) {
+        this.armInteractionTrigger(guide, endUserId, sessionId, pageUrl);
         continue;
       }
-      if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
-        if (this.walkthroughState.hasActive()) {
-          if (this.debug)
-            console.log(`[veo] guides: walkthrough ${guide.guideId} skipped (another active)`);
-          continue;
-        }
-        await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
-        continue;
+      await this.showGuide(guide, endUserId, sessionId, pageUrl);
+    }
+  }
+  /**
+   * Muestra una guía elegible (filtro de frecuencia + dedupe + dispatch por
+   * tipo). Cuerpo original del loop de `checkGuides`, extraído para que los
+   * disparadores por interacción pasen por LOS MISMOS chequeos al disparar.
+   */
+  async showGuide(guide, endUserId, sessionId, pageUrl) {
+    if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) {
+      if (this.debug) console.log(`[veo] guides: filtered locally guideId=${guide.guideId}`);
+      return;
+    }
+    if (this.activeByGuideId.has(guide.guideId)) {
+      if (this.debug) console.log(`[veo] guides: already shown guideId=${guide.guideId}`);
+      return;
+    }
+    if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
+      if (this.walkthroughState.hasActive()) {
+        if (this.debug)
+          console.log(`[veo] guides: walkthrough ${guide.guideId} skipped (another active)`);
+        return;
       }
-      this.runSingleStepRender(guide, sessionId, pageUrl);
+      await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
+      return;
     }
+    this.runSingleStepRender(guide, sessionId, pageUrl);
+  }
+  /**
+   * Arma un disparador por interacción: la guía NO se muestra al cargar, sino
+   * cuando el usuario hace click / pasa el mouse sobre `activationRules.selector`.
+   * Listener DELEGADO en `document` (fase captura, sin preventDefault — el click
+   * original de la app sigue funcionando). Al disparar se desarma y la guía pasa
+   * por `showGuide` (mismos chequeos de frecuencia/dedupe). Tras cerrarse, el
+   * próximo pageview/identify la re-arma — hover/click vuelve a mostrarla
+   * mientras la frecuencia lo permita.
+   */
+  armInteractionTrigger(guide, endUserId, sessionId, pageUrl) {
+    if (this.frequencyCache.shouldFilter(guide.guideId, guide.displayFrequency)) return;
+    if (this.activeByGuideId.has(guide.guideId)) return;
+    if (this.armedTriggers.has(guide.guideId)) return;
+    const selector = guide.activationRules.selector;
+    const eventName = guide.activationRules.trigger === "on_hover" ? "mouseover" : "click";
+    const onFire = (e) => {
+      const target = e.target;
+      if (!(target instanceof Element)) return;
+      try {
+        if (!target.closest(selector)) return;
+      } catch {
+        return;
+      }
+      disarm();
+      void this.showGuide(guide, endUserId, sessionId, pageUrl);
+    };
+    const disarm = () => {
+      document.removeEventListener(eventName, onFire, true);
+      this.armedTriggers.delete(guide.guideId);
+    };
+    document.addEventListener(eventName, onFire, true);
+    this.armedTriggers.set(guide.guideId, disarm);
+    if (this.debug)
+      console.log(`[veo] guides: armed ${eventName} trigger for ${guide.guideId} on ${selector}`);
+  }
+  /** Desarma todos los disparadores por interacción pendientes. */
+  disarmTriggers() {
+    for (const disarm of this.armedTriggers.values()) disarm();
+    this.armedTriggers.clear();
   }
   /**
    * `resolve` con cache de corta duración + coalescing:
@@ -5460,6 +5565,7 @@ ${pageUrl}`;
       this.activeWalkthroughRenderer = null;
       this.activeWalkthroughGuide = null;
     }
+    this.disarmTriggers();
     this.dispatched.clear();
     this.resolveCache = null;
     this.inflightResolve = null;
@@ -5492,8 +5598,11 @@ ${pageUrl}`;
       this.client.track(eventName, properties);
     };
     const onFormSubmit = (answers) => this.submitFormResponse(guide.guideId, answers);
+    const onOpenGuide = (targetGuideId) => {
+      void this.openGuideById(targetGuideId, sessionId, pageUrl);
+    };
     try {
-      void renderer.render({ guide, onInteraction, onClose, onTrack, onFormSubmit });
+      void renderer.render({ guide, onInteraction, onClose, onTrack, onFormSubmit, onOpenGuide });
     } catch (err) {
       if (this.debug) console.error("[veo] renderer.render threw:", err);
       this.activeRenderers.delete(renderer);
@@ -5502,6 +5611,28 @@ ${pageUrl}`;
       }
     }
   }
+  /**
+   * Abre una guía POR ID, disparada desde el botón de otra guía (encadenado).
+   * Ignora las URL rules y el trigger (el autor lo pidió explícitamente desde
+   * un botón); respeta el dedupe de guías activas y el flujo normal de
+   * tracking. 404/red → no-op (la guía destino pudo borrarse).
+   */
+  async openGuideById(guideId, sessionId, pageUrl) {
+    if (this.activeByGuideId.has(guideId)) return;
+    const guide = await this.resolver.fetchById(guideId);
+    if (!guide) {
+      if (this.debug) console.warn(`[veo] guides: chained guide ${guideId} not found`);
+      return;
+    }
+    const endUserId = this.client.getEndUserId() ?? this.client.getAnonymousId();
+    if (guide.guideType === "walkthrough" && guide.guideSteps.length > 1) {
+      if (!this.walkthroughState.hasActive()) {
+        await this.startWalkthrough(guide, endUserId, sessionId, pageUrl);
+      }
+      return;
+    }
+    this.runSingleStepRender(guide, sessionId, pageUrl);
+  }
   /**
    * Si hay un walkthrough persistido, intenta pintar el step actual en
    * la página actual. Retorna `true` si lo intentó (sea éxito o cancel),