@pushwoosh/dumb-components 1.1.220 → 1.1.221

package/EmailTemplatePreview/EmailTemplatePreview.d.ts

@@ -2,9 +2,11 @@ import { type ReactElement } from 'react';
 import type { PreviewIframeProps } from './types';
 /**
  * Renders an email HTML template in a sandboxed iframe, resolving Liquid, localization
- * and placeholder values before display.
+ * and placeholder values before display. With `clickMap` it also draws click counts over
+ * the anchors they were recorded on, see {@link decorateClickMap}.
  *
  * @example
  * <EmailTemplatePreview template={html} localization={l10n} values={vars} scale={0.5} />
+ * <EmailTemplatePreview template={html} localization={l10n} values={vars} clickMap={{ items }} />
  */
 export declare function EmailTemplatePreview(props: PreviewIframeProps): ReactElement;

package/EmailTemplatePreview/EmailTemplatePreview.js

@@ -1,8 +1,10 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { Liquid } from 'liquidjs';
-import { useMemo, useState } from 'react';
+import { useCallback, useMemo, useState } from 'react';
+import { decorateClickMap } from './clickMap';
 import { replaceLocalization, replacePlaceholders } from './helpers';
 import { IframeStyled } from './styles';
+import { SandboxedHtmlFrame } from '../SandboxedHtmlFrame';
 import { LIGHT_ISLAND_PROPS } from '../shared/lightIsland';
 const createLiquidInstance = () => {
   const liquidInstance = new Liquid();
@@ -21,10 +23,12 @@ const createLiquidInstance = () => {
 };
 /**
  * Renders an email HTML template in a sandboxed iframe, resolving Liquid, localization
- * and placeholder values before display.
+ * and placeholder values before display. With `clickMap` it also draws click counts over
+ * the anchors they were recorded on, see {@link decorateClickMap}.
  *
  * @example
  * <EmailTemplatePreview template={html} localization={l10n} values={vars} scale={0.5} />
+ * <EmailTemplatePreview template={html} localization={l10n} values={vars} clickMap={{ items }} />
  */
 export function EmailTemplatePreview(props) {
   const {
@@ -33,8 +37,14 @@ export function EmailTemplatePreview(props) {
     height,
     template,
     localization,
-    values
+    values,
+    clickMap,
+    onReady
   } = props;
+  const clickMapItems = clickMap?.items;
+  const clickMapActiveKey = clickMap?.activeKey;
+  const clickMapOnSelect = clickMap?.onSelect;
+  const clickMapOnPlaced = clickMap?.onPlaced;
   const [liquidInstance] = useState(createLiquidInstance);
   const src = useMemo(() => {
     let withDynamicContent = template;
@@ -47,15 +57,28 @@ export function EmailTemplatePreview(props) {
       return withDynamicContent;
     }
   }, [template, localization, values, liquidInstance]);
+  const handleReady = useCallback(frameDocument => {
+    const cleanups = [onReady?.(frameDocument), clickMapItems && decorateClickMap(frameDocument, {
+      items: clickMapItems,
+      activeKey: clickMapActiveKey,
+      scale,
+      onSelect: clickMapOnSelect,
+      onPlaced: clickMapOnPlaced
+    })];
+    return () => {
+      cleanups.forEach(cleanup => cleanup?.());
+    };
+  }, [onReady, clickMapItems, clickMapActiveKey, clickMapOnSelect, clickMapOnPlaced, scale]);
   return _jsx(IframeStyled, {
     ...LIGHT_ISLAND_PROPS,
     "$scale": scale,
     "$width": width,
     "$height": height,
-    children: _jsx("iframe", {
-      srcDoc: src,
-      sandbox: "allow-same-origin",
-      title: "preview"
+    children: _jsx(SandboxedHtmlFrame, {
+      mode: "inspectable",
+      title: "preview",
+      html: src,
+      onReady: handleReady
     })
   });
 }

package/EmailTemplatePreview/__tests__/clickMap.test.d.ts

@@ -0,0 +1 @@
+export {};

package/EmailTemplatePreview/__tests__/clickMap.test.js

@@ -0,0 +1,107 @@
+import { CLICK_MAP_BADGE_ATTRIBUTE, decorateClickMap, matchClickMapItems } from '../clickMap';
+const PROMO = 'http://spartak.com/matchtowin';
+const TICKETS = 'https://tickets.spartak.com/zones/18956';
+const HTML = `
+  <a href="${PROMO}?utm_source=email&amp;utm_content=img"><img src="banner.png" alt=""></a>
+  <p>Подробности на <a href="${PROMO}?utm_source=email">странице акции</a>.</p>
+  <a href="${PROMO}?utm_source=email"><strong>Перейти на страницу акции</strong></a>
+  <a href="${TICKETS}?utm_source=email">Купить билеты</a>
+  <a href="${TICKETS}?utm_source=email">Купить билеты</a>
+  <a href="[% param.url_unsub %]">Отписаться</a>
+`;
+const item = (key, link, title, clicks) => ({
+  key,
+  link,
+  title,
+  clicks
+});
+function createDocument() {
+  const frameDocument = document.implementation.createHTMLDocument('preview');
+  frameDocument.body.innerHTML = HTML;
+  return frameDocument;
+}
+describe('matchClickMapItems', () => {
+  it('tells anchors with the same link apart by their text and lands image links on the text-less anchor', () => {
+    const frameDocument = createDocument();
+    const items = [item('button', PROMO, 'Перейти на страницу акции', 1631), item('text', PROMO, 'странице акции', 398), item('image', PROMO, '', 172)];
+    const {
+      matches,
+      placement
+    } = matchClickMapItems(frameDocument, items);
+    expect(placement).toEqual({
+      placed: ['button', 'text', 'image'],
+      pooled: [],
+      unplaced: []
+    });
+    expect(matches.map(({
+      anchor,
+      items: matched
+    }) => [anchor.textContent?.trim(), matched.map(row => row.key)])).toEqual([['Перейти на страницу акции', ['button']], ['странице акции', ['text']], ['', ['image']]]);
+  });
+  it('ignores the query string of both sides when matching links', () => {
+    const {
+      placement
+    } = matchClickMapItems(createDocument(), [item('text', `${PROMO}?utm_source=other&x=1`, 'странице акции', 1)]);
+    expect(placement.placed).toEqual(['text']);
+  });
+  it('pools a row over every anchor that shares link and text', () => {
+    const {
+      matches,
+      placement
+    } = matchClickMapItems(createDocument(), [item('tickets', TICKETS, 'Купить билеты', 258)]);
+    expect(placement).toEqual({
+      placed: [],
+      pooled: ['tickets'],
+      unplaced: []
+    });
+    expect(matches).toHaveLength(2);
+  });
+  it('falls back to every anchor of the link when the recorded text matches none of them', () => {
+    const {
+      matches,
+      placement
+    } = matchClickMapItems(createDocument(), [item('promo', PROMO, 'Use this template →', 10)]);
+    expect(placement.pooled).toEqual(['promo']);
+    expect(matches).toHaveLength(3);
+  });
+  it('reports rows whose link is not in the template as unplaced', () => {
+    const {
+      matches,
+      placement
+    } = matchClickMapItems(createDocument(), [item('gone', 'https://old.example.com/', 'x', 5)]);
+    expect(placement).toEqual({
+      placed: [],
+      pooled: [],
+      unplaced: ['gone']
+    });
+    expect(matches).toHaveLength(0);
+  });
+});
+describe('decorateClickMap', () => {
+  it('draws one badge per matched anchor, highlights the active row and cleans up after itself', () => {
+    const frameDocument = createDocument();
+    const onPlaced = jest.fn();
+    const onSelect = jest.fn();
+    const items = [item('button', PROMO, 'Перейти на страницу акции', 1631), item('image', PROMO, '', 172), item('gone', 'https://old.example.com/', 'x', 5)];
+    const cleanup = decorateClickMap(frameDocument, {
+      items,
+      activeKey: 'button',
+      onPlaced,
+      onSelect
+    });
+    const badges = [...frameDocument.querySelectorAll(`[${CLICK_MAP_BADGE_ATTRIBUTE}]`)];
+    expect(badges.map(badge => [badge.getAttribute(CLICK_MAP_BADGE_ATTRIBUTE), badge.textContent])).toEqual([['button', '1.6K'], ['image', '172']]);
+    expect(badges[0].style.backgroundColor).not.toBe(badges[1].style.backgroundColor);
+    expect(frameDocument.querySelector('a strong')?.parentElement?.style.outline).toContain('solid');
+    expect(onPlaced).toHaveBeenCalledWith({
+      placed: ['button', 'image'],
+      pooled: [],
+      unplaced: ['gone']
+    });
+    badges[1].click();
+    expect(onSelect).toHaveBeenCalledWith('image');
+    cleanup();
+    expect(frameDocument.querySelectorAll(`[${CLICK_MAP_BADGE_ATTRIBUTE}]`)).toHaveLength(0);
+    expect(frameDocument.querySelector('a strong')?.parentElement?.style.outline).toBe('');
+  });
+});

package/EmailTemplatePreview/clickMap.d.ts

@@ -0,0 +1,25 @@
+import type { EmailClickMapItem, EmailClickMapPlacement } from './types';
+/** An anchor of the rendered template together with the rows recorded on it. */
+export type EmailClickMapMatch = {
+    anchor: HTMLAnchorElement;
+    items: EmailClickMapItem[];
+};
+/** Outcome of {@link matchClickMapItems}. */
+export type EmailClickMapMatchResult = {
+    matches: EmailClickMapMatch[];
+    placement: EmailClickMapPlacement;
+};
+/** Options of {@link decorateClickMap}. */
+export type EmailClickMapDecorateOptions = {
+    items: EmailClickMapItem[];
+    activeKey?: string | null;
+    scale?: number;
+    onSelect?: (key: string) => void;
+    onPlaced?: (placement: EmailClickMapPlacement) => void;
+};
+/** Attribute every badge carries, so tests and consumers can find them. */
+export declare const CLICK_MAP_BADGE_ATTRIBUTE = "data-pw-click-map-badge";
+/** Lands click-tracking rows on template anchors by (link, text), falling back to every anchor of the link. */
+export declare function matchClickMapItems(document: Document, items: EmailClickMapItem[]): EmailClickMapMatchResult;
+/** Draws click-count badges over matched anchors, outlines `activeKey`; returns a cleanup. */
+export declare function decorateClickMap(document: Document, options: EmailClickMapDecorateOptions): () => void;

package/EmailTemplatePreview/clickMap.js

@@ -0,0 +1,128 @@
+/** Attribute every badge carries, so tests and consumers can find them. */
+export const CLICK_MAP_BADGE_ATTRIBUTE = 'data-pw-click-map-badge';
+const ACTIVE_COLOR = '#00b2ff';
+const IDLE_COLOR = 'rgba(36, 48, 66, 0.82)';
+const compactNumber = new Intl.NumberFormat('en', {
+  notation: 'compact',
+  maximumFractionDigits: 1
+});
+const stripQuery = url => url.split('?')[0].trim();
+const normalizeText = text => text.replace(/\s+/g, ' ').trim();
+const anchorText = anchor => normalizeText(anchor.textContent ?? '');
+const anchorLink = anchor => stripQuery(anchor.getAttribute('href') ?? '');
+/** Lands click-tracking rows on template anchors by (link, text), falling back to every anchor of the link. */
+export function matchClickMapItems(document, items) {
+  const anchorsByLink = new Map();
+  document.querySelectorAll('a[href]').forEach(anchor => {
+    const link = anchorLink(anchor);
+    if (link) {
+      anchorsByLink.set(link, [...(anchorsByLink.get(link) ?? []), anchor]);
+    }
+  });
+  const itemsByAnchor = new Map();
+  const placement = {
+    placed: [],
+    pooled: [],
+    unplaced: []
+  };
+  items.forEach(item => {
+    const candidates = anchorsByLink.get(stripQuery(item.link)) ?? [];
+    const title = normalizeText(item.title);
+    const exact = candidates.filter(anchor => anchorText(anchor) === title);
+    const targets = exact.length > 0 ? exact : candidates;
+    if (targets.length === 0) {
+      placement.unplaced.push(item.key);
+      return;
+    }
+    (targets.length === 1 ? placement.placed : placement.pooled).push(item.key);
+    targets.forEach(anchor => {
+      itemsByAnchor.set(anchor, [...(itemsByAnchor.get(anchor) ?? []), item]);
+    });
+  });
+  return {
+    matches: [...itemsByAnchor].map(([anchor, matched]) => ({
+      anchor,
+      items: matched
+    })),
+    placement
+  };
+}
+function anchorRect(anchor) {
+  const rects = [anchor, ...anchor.querySelectorAll('img')].map(node => node.getBoundingClientRect());
+  const top = Math.min(...rects.map(rect => rect.top));
+  const left = Math.min(...rects.map(rect => rect.left));
+  const right = Math.max(...rects.map(rect => rect.right));
+  const bottom = Math.max(...rects.map(rect => rect.bottom));
+  return new DOMRect(left, top, right - left, bottom - top);
+}
+function createBadge(document, match, options) {
+  const scale = options.scale ?? 1;
+  const keys = match.items.map(item => item.key);
+  const isActive = options.activeKey != null && keys.includes(options.activeKey);
+  const clicks = match.items.reduce((sum, item) => sum + item.clicks, 0);
+  const badge = document.createElement('span');
+  badge.setAttribute(CLICK_MAP_BADGE_ATTRIBUTE, keys.join(' '));
+  badge.textContent = compactNumber.format(clicks);
+  badge.title = match.items.map(item => `${item.title || item.link}: ${item.clicks}`).join('\n');
+  Object.assign(badge.style, {
+    position: 'absolute',
+    zIndex: '2147483647',
+    transform: 'translateY(-50%)',
+    padding: `${3 * scale}px ${8 * scale}px`,
+    borderRadius: '999px',
+    backgroundColor: isActive ? ACTIVE_COLOR : IDLE_COLOR,
+    color: '#fff',
+    font: `600 ${12 * scale}px/1 sans-serif`,
+    whiteSpace: 'nowrap',
+    boxShadow: '0 1px 3px rgba(0, 0, 0, 0.3)',
+    cursor: options.onSelect ? 'pointer' : 'default',
+    userSelect: 'none'
+  });
+  badge.addEventListener('click', event => {
+    event.preventDefault();
+    event.stopPropagation();
+    options.onSelect?.(keys[0]);
+  });
+  return badge;
+}
+/** Draws click-count badges over matched anchors, outlines `activeKey`; returns a cleanup. */
+export function decorateClickMap(document, options) {
+  const view = document.defaultView;
+  const {
+    matches,
+    placement
+  } = matchClickMapItems(document, options.items);
+  const badges = matches.map(match => createBadge(document, match, options));
+  const outlined = matches.filter(match => options.activeKey != null && match.items.some(item => item.key === options.activeKey)).map(match => [match.anchor, match.anchor.style.outline]);
+  const isInlineText = anchor => view?.getComputedStyle(anchor).display === 'inline' && !anchor.querySelector('img');
+  const layout = () => {
+    const maxRight = document.documentElement.clientWidth;
+    matches.forEach((match, index) => {
+      const badge = badges[index];
+      const rect = anchorRect(match.anchor);
+      const right = Math.min(rect.right, maxRight);
+      const inline = isInlineText(match.anchor);
+      const left = inline ? Math.min(right, maxRight - badge.offsetWidth) : right - badge.offsetWidth;
+      const top = inline ? rect.top + rect.height / 2 : rect.top;
+      badge.style.top = `${top + (view?.scrollY ?? 0)}px`;
+      badge.style.left = `${left + (view?.scrollX ?? 0)}px`;
+    });
+  };
+  badges.forEach(badge => document.body.appendChild(badge));
+  outlined.forEach(([anchor]) => {
+    anchor.style.outline = `${2 * (options.scale ?? 1)}px solid ${ACTIVE_COLOR}`;
+  });
+  layout();
+  options.onPlaced?.(placement);
+  const observer = view && 'ResizeObserver' in view ? new view.ResizeObserver(layout) : undefined;
+  observer?.observe(document.documentElement);
+  view?.addEventListener('resize', layout);
+  return () => {
+    observer?.disconnect();
+    view?.removeEventListener('resize', layout);
+    badges.forEach(badge => badge.remove());
+    outlined.forEach(([anchor, outline]) => {
+      anchor.style.outline = outline;
+    });
+  };
+}

package/EmailTemplatePreview/index.d.ts

@@ -1,3 +1,5 @@
 export { EmailTemplatePreview } from './EmailTemplatePreview';
 export { NoEmailTemplatePreview } from './components/NoEmailTemplatePreview';
 export { replaceLocalization, replacePlaceholders } from './helpers';
+export { matchClickMapItems, decorateClickMap, CLICK_MAP_BADGE_ATTRIBUTE, type EmailClickMapMatch, type EmailClickMapMatchResult, type EmailClickMapDecorateOptions, } from './clickMap';
+export type { EmailClickMapItem, EmailClickMapPlacement, EmailClickMapProps, PreviewIframeProps, } from './types';

package/EmailTemplatePreview/index.js

@@ -1,3 +1,4 @@
 export { EmailTemplatePreview } from './EmailTemplatePreview';
 export { NoEmailTemplatePreview } from './components/NoEmailTemplatePreview';
-export { replaceLocalization, replacePlaceholders } from './helpers';
+export { replaceLocalization, replacePlaceholders } from './helpers';
+export { matchClickMapItems, decorateClickMap, CLICK_MAP_BADGE_ATTRIBUTE } from './clickMap';

package/EmailTemplatePreview/types.d.ts

@@ -1,3 +1,32 @@
+/** One click-tracking row to be drawn over the anchor it was recorded on. */
+export type EmailClickMapItem = {
+    /** Row identity, passed back through {@link EmailClickMapProps.onSelect}. */
+    key: string;
+    /** Destination URL as recorded by click tracking; the query string is ignored when matching. */
+    link: string;
+    /** Anchor text recorded with the click; empty for image links. */
+    title: string;
+    clicks: number;
+};
+/** How the rows of {@link EmailClickMapProps.items} landed on the rendered template. */
+export type EmailClickMapPlacement = {
+    /** Keys drawn on exactly one anchor. */
+    placed: string[];
+    /** Keys drawn on several anchors that share link and text, so the count repeats. */
+    pooled: string[];
+    /** Keys with no matching anchor in the current template. */
+    unplaced: string[];
+};
+/** Click counts to overlay on the rendered email, see {@link EmailTemplatePreview}. */
+export type EmailClickMapProps = {
+    items: EmailClickMapItem[];
+    /** Key whose badge and anchor are highlighted. */
+    activeKey?: string | null;
+    /** Called with the key of the badge the user clicked. */
+    onSelect?: (key: string) => void;
+    /** Called after every layout with the placement outcome. */
+    onPlaced?: (placement: EmailClickMapPlacement) => void;
+};
 /** Props of {@link EmailTemplatePreview}. */
 export type PreviewIframeProps = {
     /** CSS `transform: scale()` factor applied to the rendered email. */
@@ -12,4 +41,8 @@ export type PreviewIframeProps = {
     localization: Record<string, string>;
     /** Placeholder values resolved by {@link replacePlaceholders}. */
     values: Record<string, any>;
+    /** Click counts drawn over the anchors of the rendered template. */
+    clickMap?: EmailClickMapProps;
+    /** Called with the frame document once rendered; may return a cleanup run before the next call. */
+    onReady?: (document: Document) => void | (() => void);
 };

package/index.d.ts

@@ -32,7 +32,7 @@ export { Tooltip, type TooltipPosition, TooltipTrigger } from './Tooltip';
 export { Tab, TabBar, TabPanel, Tabs, type TabCode } from './Tabs';
 export { Link, type LinkPropsWithoutAs, type LinkPropsWithAsTag, type LinkPropsWithAsComponent, } from './Link';
 export { StatisticCard } from './StatisticCard';
-export { EmailTemplatePreview, NoEmailTemplatePreview, replaceLocalization, replacePlaceholders } from './EmailTemplatePreview';
+export { EmailTemplatePreview, NoEmailTemplatePreview, replaceLocalization, replacePlaceholders, matchClickMapItems, decorateClickMap, CLICK_MAP_BADGE_ATTRIBUTE, type EmailClickMapItem, type EmailClickMapPlacement, type EmailClickMapProps, type PreviewIframeProps, } from './EmailTemplatePreview';
 export { PushPreview } from './PushPreview';
 export { WhatsAppPreview } from './WhatsAppPreview';
 export type { WhatsAppAttachment, WhatsAppAttachmentKind, WhatsAppMessage, WhatsAppMessageDirection, WhatsAppMessageStatus, WhatsAppPreviewProps, } from './WhatsAppPreview';

package/index.js

@@ -32,7 +32,7 @@ export { Tooltip, TooltipTrigger } from './Tooltip';
 export { Tab, TabBar, TabPanel, Tabs } from './Tabs';
 export { Link } from './Link';
 export { StatisticCard } from './StatisticCard';
-export { EmailTemplatePreview, NoEmailTemplatePreview, replaceLocalization, replacePlaceholders } from './EmailTemplatePreview';
+export { EmailTemplatePreview, NoEmailTemplatePreview, replaceLocalization, replacePlaceholders, matchClickMapItems, decorateClickMap, CLICK_MAP_BADGE_ATTRIBUTE } from './EmailTemplatePreview';
 export { PushPreview } from './PushPreview';
 export { WhatsAppPreview } from './WhatsAppPreview';
 export { Toast, ToastProvider, useToast } from './Toast';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/dumb-components",
-  "version": "1.1.220",
+  "version": "1.1.221",
   "description": "React components to build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",