@pushwoosh/websdk-common 6.18.0 → 6.19.0

package/inbox/helpers.js

@@ -0,0 +1,150 @@
+import { INBOX_KNOWN_LAYOUTS, INBOX_MAX_CAROUSEL_SLIDES, INBOX_MONTHS, INBOX_WIDGET_DEFAULT_APPEARANCE, INBOX_WIDGET_STYLE_PREFIX, INBOX_WIDGET_STYLE_VARIABLES } from './constants';
+const MINUTE = 60 * 1000;
+const HOUR = 60 * MINUTE;
+const DAY = 24 * HOUR;
+const RULE_BREAKERS = /[;{}]/;
+/** Picks the content to render: explicit `content` wins, otherwise the `language` entry of `localizedContent` with default/en/first fallbacks. */
+export function pickInboxLocalizedContent(content, localizedContent, language) {
+  if (content) {
+    return content;
+  }
+  if (!localizedContent) {
+    return null;
+  }
+  const keys = Object.keys(localizedContent);
+  if (keys.length === 0) {
+    return null;
+  }
+  if (language && localizedContent[language]) {
+    return localizedContent[language];
+  }
+  return localizedContent.default || localizedContent.en || localizedContent[keys[0]];
+}
+/** Slides a cell draws: the ones with an image, at most {@link INBOX_MAX_CAROUSEL_SLIDES}. */
+export function getInboxValidSlides(slides) {
+  return (Array.isArray(slides) ? slides : []).filter(slide => !!slide && !!slide.imageUrl).slice(0, INBOX_MAX_CAROUSEL_SLIDES);
+}
+/** Hero image of the banner/captioned layouts: the banner, with the icon standing in when none was sent. */
+export function getInboxHeroUrl(content) {
+  return content.bannerUrl || content.iconUrl || '';
+}
+/** Resolves the layout a cell draws: the requested one when it can render, the heuristic for unknown ones, classic otherwise. */
+export function resolveInboxLayout(content) {
+  const hasTitle = !!content.title;
+  const hasBody = !!content.body;
+  const hero = getInboxHeroUrl(content);
+  let requested = content.layoutType;
+  if (!INBOX_KNOWN_LAYOUTS.includes(requested)) {
+    if (content.bannerUrl && !hasTitle) {
+      requested = 'banner';
+    } else if (content.bannerUrl && hasTitle && hasBody) {
+      requested = 'captioned';
+    } else {
+      requested = 'classic';
+    }
+  }
+  switch (requested) {
+    case 'banner':
+      return hero ? 'banner' : 'classic';
+    case 'captioned':
+      return hero && hasTitle && hasBody ? 'captioned' : 'classic';
+    case 'carousel':
+      return hasTitle && hasBody && getInboxValidSlides(content.carousel).length > 0 ? 'carousel' : 'classic';
+    default:
+      return 'classic';
+  }
+}
+/** True when the content has nothing to render yet, so a preview shows the layout placeholder. */
+export function isInboxContentEmpty(content) {
+  return !content.title && !content.body && !content.iconUrl && !content.bannerUrl && getInboxValidSlides(content.carousel).length === 0;
+}
+/** The layout whose placeholder an empty preview shows: the requested one when known, else classic. */
+export function getInboxEmptyLayout(content) {
+  const requested = content.layoutType;
+  return INBOX_KNOWN_LAYOUTS.includes(requested) ? requested : 'classic';
+}
+/** Title/body pair of the mobile cells: in classic the body stands in for a missing title, as the mobile SDKs draw it. */
+export function getInboxMobileTexts(content, layout) {
+  if (layout === 'classic') {
+    return {
+      title: content.title || content.body || '',
+      body: content.title && content.body || ''
+    };
+  }
+  return {
+    title: content.title || '',
+    body: content.body || ''
+  };
+}
+/** The colored initial a classic cell shows when there is no icon. */
+export function getInboxIconInitial(content) {
+  return (content.title || content.body || '?').trim().charAt(0).toUpperCase() || '?';
+}
+/** Date label of a web widget message: relative within a day of `now`, then `D Mon YYYY, H:mm` in local time. */
+export function formatInboxMessageTime(sendDate, now = Date.now()) {
+  const date = new Date(sendDate);
+  const gap = now - date.getTime();
+  if (gap <= MINUTE) {
+    return 'Just now';
+  }
+  if (gap < HOUR) {
+    return `${Math.floor(gap / MINUTE)} minutes ago`;
+  }
+  if (gap < DAY) {
+    return `${Math.floor(gap / HOUR)} hours ago`;
+  }
+  const minutes = `0${date.getMinutes()}`.slice(-2);
+  return `${date.getDate()} ${INBOX_MONTHS[date.getMonth()]} ${date.getFullYear()}, ${date.getHours()}:${minutes}`;
+}
+/** Newest first. */
+export function compareInboxBySendDate(one, two) {
+  return new Date(two).getTime() - new Date(one).getTime();
+}
+/** Full appearance from a partial one; the arrow border follows a visible widget border unless set explicitly. */
+export function resolveInboxWidgetAppearance(appearance) {
+  const {
+    borderColor
+  } = appearance || {};
+  return {
+    ...INBOX_WIDGET_DEFAULT_APPEARANCE,
+    arrowBorderColor: borderColor && borderColor !== 'transparent' ? borderColor : INBOX_WIDGET_DEFAULT_APPEARANCE.arrowBorderColor,
+    ...appearance
+  };
+}
+/** One appearance value as its CSS custom property value; `null` leaves it unset so the stylesheet default applies. */
+export function formatInboxStyleValue(type, value) {
+  switch (type) {
+    case 'size':
+      {
+        if (value === null || value === undefined || value === '') {
+          return null;
+        }
+        const size = Number(value);
+        return Number.isFinite(size) ? `${size}px` : null;
+      }
+    case 'number':
+      {
+        const parsed = parseFloat(String(value));
+        return Number.isFinite(parsed) ? String(parsed) : null;
+      }
+    default:
+      {
+        const text = String(value ?? '').trim();
+        return text && !RULE_BREAKERS.test(text) ? text : null;
+      }
+  }
+}
+/** The `--pw-inbox-*` custom properties of an appearance, ready for a `style` object or `setProperty`. */
+export function inboxWidgetStyleVariables(appearance) {
+  const variables = {};
+  INBOX_WIDGET_STYLE_VARIABLES.forEach(({
+    name,
+    type
+  }) => {
+    const formatted = formatInboxStyleValue(type, appearance[name]);
+    if (formatted !== null) {
+      variables[`--${INBOX_WIDGET_STYLE_PREFIX}-${name}`] = formatted;
+    }
+  });
+  return variables;
+}

package/inbox/index.d.ts

@@ -0,0 +1,6 @@
+export { InboxWidgetReader, InboxWebCell, inboxWidgetPreviewFrame } from './InboxWidgetReader';
+export { InboxCellPreview } from './InboxCellPreview';
+export { pickInboxLocalizedContent, getInboxValidSlides, getInboxHeroUrl, resolveInboxLayout, isInboxContentEmpty, getInboxEmptyLayout, getInboxMobileTexts, getInboxIconInitial, formatInboxMessageTime, compareInboxBySendDate, resolveInboxWidgetAppearance, formatInboxStyleValue, inboxWidgetStyleVariables, } from './helpers';
+export { INBOX_MAX_CAROUSEL_SLIDES, INBOX_KNOWN_LAYOUTS, INBOX_WIDGET_STYLE_PREFIX, INBOX_MONTHS, INBOX_WIDGET_STYLE_VARIABLES, INBOX_WIDGET_DEFAULT_APPEARANCE, INBOX_WIDGET_CSS, } from './constants';
+export type { InboxWebCellProps } from './InboxWidgetReader';
+export type { InboxLayout, InboxSlide, InboxCellContent, InboxWidgetMessage, InboxWidgetPosition, InboxWidgetAppearance, InboxWidgetStyleName, InboxWidgetStyleType, InboxWidgetStyleVariable, InboxWidgetReaderMode, InboxWidgetReaderProps, InboxCellPlatform, InboxCellPreviewProps, } from './types';

package/inbox/index.js

@@ -0,0 +1,4 @@
+export { InboxWidgetReader, InboxWebCell, inboxWidgetPreviewFrame } from './InboxWidgetReader';
+export { InboxCellPreview } from './InboxCellPreview';
+export { pickInboxLocalizedContent, getInboxValidSlides, getInboxHeroUrl, resolveInboxLayout, isInboxContentEmpty, getInboxEmptyLayout, getInboxMobileTexts, getInboxIconInitial, formatInboxMessageTime, compareInboxBySendDate, resolveInboxWidgetAppearance, formatInboxStyleValue, inboxWidgetStyleVariables } from './helpers';
+export { INBOX_MAX_CAROUSEL_SLIDES, INBOX_KNOWN_LAYOUTS, INBOX_WIDGET_STYLE_PREFIX, INBOX_MONTHS, INBOX_WIDGET_STYLE_VARIABLES, INBOX_WIDGET_DEFAULT_APPEARANCE, INBOX_WIDGET_CSS } from './constants';

package/inbox/types.d.ts

@@ -0,0 +1,126 @@
+import { type ReactNode } from 'react';
+/** Cell layout of an inbox message. */
+export type InboxLayout = 'classic' | 'captioned' | 'banner' | 'carousel';
+/** One carousel slide of an inbox message. */
+export interface InboxSlide {
+    /** Slide image URL; a slide without it is dropped. */
+    imageUrl?: string;
+    /** Caption overlaid at the bottom of the slide. */
+    caption?: string;
+    /** Where a tap on the slide goes; the host validates it before navigating. */
+    link?: string;
+}
+/** Content of one inbox cell, in the shape both the Control Panel and the WebSDK map their data to. */
+export interface InboxCellContent {
+    /** Cell title. */
+    title?: string;
+    /** Cell text. */
+    body?: string;
+    /** Small avatar icon URL; without it classic renders a colored initial. */
+    iconUrl?: string;
+    /** The campaign's own banner for the banner/captioned layouts. */
+    bannerUrl?: string;
+    /** Requested layout; unknown or absent values fall back to the heuristic of {@link resolveInboxLayout}. */
+    layoutType?: string;
+    /** Carousel slides; only the first valid ones are rendered. */
+    carousel?: InboxSlide[];
+}
+/** One message of the web inbox widget. */
+export interface InboxWidgetMessage extends InboxCellContent {
+    /** Message code, rendered as `data-pw-inbox-message-id`. */
+    code: string;
+    /** Send date as an ISO string (UTC). */
+    sendDate: string;
+    /** The message was seen in the widget. */
+    isRead: boolean;
+    /** The message action was performed. */
+    isActionPerformed: boolean;
+}
+/** Position of the widget relative to its trigger. */
+export type InboxWidgetPosition = 'left' | 'right' | 'top' | 'bottom';
+/** Appearance of the web inbox widget; every color and size is also a `--pw-inbox-<name>` CSS custom property. */
+export interface InboxWidgetAppearance {
+    title: string;
+    bgColor: string;
+    textColor: string;
+    fontFamily: string;
+    borderRadius: number;
+    borderColor: string;
+    badgeBgColor: string;
+    badgeTextColor: string;
+    widgetWidth: number;
+    zIndex: number;
+    messageTitleColor: string;
+    timeTextColor: string;
+    emptyInboxTitle: string;
+    emptyInboxText: string;
+    emptyInboxIconUrl: string;
+    emptyInboxTitleColor: string;
+    emptyInboxTextColor: string;
+    arrowBorderColor: string;
+    /** Keep the pre-3.75 look of the classic cell; the other layouts are unaffected. */
+    legacyClassicCell: boolean;
+    unreadDotColor: string;
+    avatarBgColor: string;
+    avatarTextColor: string;
+    avatarSize: number;
+    mediaRadius: number;
+    slideCaptionColor: string;
+    slideScrimColor: string;
+    pagerDotActiveColor: string;
+    pagerDotColor: string;
+}
+/** Appearance keys exposed as `--pw-inbox-<name>` CSS custom properties. */
+export type InboxWidgetStyleName = Exclude<keyof InboxWidgetAppearance, 'title' | 'emptyInboxTitle' | 'emptyInboxText' | 'emptyInboxIconUrl' | 'legacyClassicCell'>;
+/** How an appearance value is formatted into its CSS custom property. */
+export type InboxWidgetStyleType = 'number' | 'color' | 'string' | 'size';
+/** One CSS custom property of the widget. */
+export interface InboxWidgetStyleVariable {
+    name: InboxWidgetStyleName;
+    type: InboxWidgetStyleType;
+}
+/** `live` renders into the host's `.pw-inbox-widget` element; `preview` draws the widget box itself, inline. */
+export type InboxWidgetReaderMode = 'live' | 'preview';
+/** Props of {@link InboxWidgetReader}. */
+export interface InboxWidgetReaderProps {
+    mode: InboxWidgetReaderMode;
+    /** Messages in display order. */
+    messages: InboxWidgetMessage[];
+    /** Appearance; missing keys take {@link INBOX_WIDGET_DEFAULT_APPEARANCE}. */
+    appearance?: Partial<InboxWidgetAppearance>;
+    /** Reference time for the relative dates, ms since epoch (default: now). */
+    now?: number;
+    /** A tap on a message outside its remove icon, pager and slide link. */
+    onMessageClick?: (code: string) => void;
+    /** A tap on the remove icon of a message. */
+    onMessageRemove?: (code: string) => void;
+    /** A tap on a slide that carries a link. */
+    onSlideLinkClick?: (code: string, link: string) => void;
+}
+/** Platform skin of {@link InboxCellPreview}. */
+export type InboxCellPlatform = 'ios' | 'android' | 'web';
+/** Props of {@link InboxCellPreview}. */
+export interface InboxCellPreviewProps {
+    /** Platform skin (default `ios`). */
+    platform?: InboxCellPlatform;
+    /** Content to draw; empty content draws the placeholder of the requested layout. */
+    content?: InboxCellContent | null;
+    /** Date label of the mobile cells (default `12:12`); the web cell derives it from `sendDate`. */
+    dateLabel?: string;
+    /** Send date of the web cell (default: now). */
+    sendDate?: string;
+    /** Draw the unread dot (default `true`). */
+    unread?: boolean;
+    /** Show the loading placeholder. */
+    isLoading?: boolean;
+    /** Title of the empty placeholder. */
+    emptyTitle?: ReactNode;
+    /** Description of the empty placeholder. */
+    emptyDescription?: ReactNode;
+    /** Renders the title/body of the mobile cells (e.g. a rich-text viewer); plain text by default. */
+    renderText?: (text: string) => ReactNode;
+    /** Appearance of the web cell. */
+    appearance?: Partial<InboxWidgetAppearance>;
+    /** CSS width of the preview (default `100%`). */
+    width?: string | number;
+}

package/inbox/types.js

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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pushwoosh/websdk-common",
-  "version": "6.18.0",
-  "description": "Code shared by the Pushwoosh WebSDK and the Control Panel, one entry point per module (web-popups: web popup model and renderer; subscription-widget: push subscription widget model and renderer)",
+  "version": "6.19.0",
+  "description": "Code shared by the Pushwoosh WebSDK and the Control Panel, one entry point per module (web-popups: web popup model and renderer; subscription-widget: push subscription widget model and renderer; inbox: web inbox widget and inbox cell previews)",
   "main": "index.js",
   "module": "index.js",
   "types": "index.d.ts",
@@ -18,6 +18,10 @@
       "types": "./subscription-widget/index.d.ts",
       "default": "./subscription-widget/index.js"
     },
+    "./inbox": {
+      "types": "./inbox/index.d.ts",
+      "default": "./inbox/index.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": false,