@antelopejs/dms-marketing 0.6.1 → 0.7.0

package/frontend-vue/app/utils/fill-height.ts

@@ -0,0 +1,141 @@
+/**
+ * Height that lets an element fill what is left of its scroll viewport: the
+ * viewport's height, minus where the element starts and minus whatever the
+ * page lays out after it (a note, the shell's bottom padding), so the page
+ * itself has nothing left to scroll. All in the scroll content's
+ * coordinates, so the answer does not move as the page scrolls.
+ *
+ * What follows the element is measured from the layout itself, never from
+ * the scroll content's height: once the content is shorter than the
+ * viewport, `scrollHeight` is the viewport's height, the empty space below
+ * the element would read as content after it, and the element could never
+ * grow with the window.
+ */
+
+/** Below this the panes stop shrinking and the page scrolls instead. */
+export const MIN_FILL_HEIGHT = 480
+
+export interface FillGeometry {
+  /** Height of the scroll viewport (the window, or the shell's panel). */
+  viewHeight: number
+  /** Where the element starts in the scroll content. */
+  top: number
+  /** What the content lays out after the element (see trailingExtent). */
+  trailing: number
+}
+
+export function fillHeight(geometry: FillGeometry): number {
+  return Math.max(
+    Math.floor(geometry.viewHeight - geometry.top - geometry.trailing),
+    MIN_FILL_HEIGHT,
+  )
+}
+
+/** One step from the element up to the scroll root: a box and its parent. */
+export interface TrailingLevel {
+  /** Bottom of the box's border box. */
+  bottom: number
+  /** The box's bottom margin, what it adds when nothing follows it. */
+  marginBottom: number
+  /** Bottoms (margin included) of the in-flow siblings after the box. */
+  following: number[]
+  /** The parent's bottom padding and border. */
+  closing: number
+}
+
+/**
+ * What the content lays out after the element: at each level, how far the
+ * box's following siblings reach past its own bottom, and the parent's
+ * closing padding. Each level is counted from the box's actual bottom, so a
+ * box stretched to the viewport (`min-height: 100%`) adds nothing for its
+ * empty space, and the sum does not depend on the viewport's height.
+ */
+export function trailingExtent(levels: TrailingLevel[]): number {
+  let trailing = 0
+  for (const level of levels) {
+    trailing +=
+      level.following.length > 0
+        ? Math.max(Math.max(...level.following) - level.bottom, 0)
+        : level.marginBottom
+    trailing += level.closing
+  }
+  return trailing
+}
+
+const SCROLLING = new Set(['auto', 'scroll', 'overlay'])
+
+/** The element's scroll viewport: an app shell scrolls a panel, a plain
+ * page the document. */
+function scrollViewport(element: HTMLElement): HTMLElement | null {
+  for (let node = element.parentElement; node; node = node.parentElement) {
+    if (SCROLLING.has(getComputedStyle(node).overflowY)) {
+      return node
+    }
+  }
+  return null
+}
+
+function px(value: string): number {
+  return Number.parseFloat(value) || 0
+}
+
+function inFlow(style: CSSStyleDeclaration): boolean {
+  return (
+    style.display !== 'none' &&
+    style.position !== 'absolute' &&
+    style.position !== 'fixed'
+  )
+}
+
+/** The levels from the element up to the scroll root (the viewport, or the
+ * document element), read off the page. */
+function trailingLevels(element: Element, root: Element): TrailingLevel[] {
+  const levels: TrailingLevel[] = []
+  for (let node = element; node !== root && node.parentElement;) {
+    const parent: Element = node.parentElement
+    const following: number[] = []
+    for (let next = node.nextElementSibling; next;) {
+      const style = getComputedStyle(next)
+      if (inFlow(style)) {
+        following.push(
+          next.getBoundingClientRect().bottom + px(style.marginBottom),
+        )
+      }
+      next = next.nextElementSibling
+    }
+    const parentStyle = getComputedStyle(parent)
+    levels.push({
+      bottom: node.getBoundingClientRect().bottom,
+      marginBottom: px(getComputedStyle(node).marginBottom),
+      following,
+      // A scroll viewport's border is outside its clientHeight.
+      closing:
+        px(parentStyle.paddingBottom) +
+        (parent === root && root !== document.documentElement
+          ? 0
+          : px(parentStyle.borderBottomWidth)),
+    })
+    node = parent
+  }
+  return levels
+}
+
+/** fillHeight for an element on screen. */
+export function measureFillHeight(element: HTMLElement): number {
+  const box = element.getBoundingClientRect()
+  const viewport = scrollViewport(element)
+  if (!viewport) {
+    const root = document.documentElement
+    return fillHeight({
+      viewHeight: window.innerHeight,
+      top: box.top + window.scrollY,
+      trailing: trailingExtent(trailingLevels(element, root)),
+    })
+  }
+  const origin = viewport.getBoundingClientRect().top - viewport.scrollTop
+  return fillHeight({
+    viewHeight: viewport.clientHeight,
+    top: box.top - origin,
+    trailing: trailingExtent(trailingLevels(element, viewport)),
+  })
+}

package/frontend-vue/app/utils/format.ts

@@ -75,14 +75,33 @@ const RELATIVE_STEPS: [Intl.RelativeTimeFormatUnit, number][] = [
   ['year', Number.POSITIVE_INFINITY],
 ]
 
-/** "12 seconds ago", "4 minutes ago" — the age of the last event. */
+/**
+ * Under this age an event reads "now": the server stamps events on its clock,
+ * which may run a few seconds ahead of the reader's.
+ */
+export const JUST_NOW_MS = 5 * MS_PER_SECOND
+
+/** Whether an event at `at` reads "just now", including one stamped ahead. */
+export function isJustNow(at: number, now: number): boolean {
+  return now - at < JUST_NOW_MS
+}
+
+/**
+ * "12 seconds ago", "4 minutes ago" — the age of the last event; "12 sec ago"
+ * with the `short` style. Never in the future: an age under `JUST_NOW_MS`, or
+ * a timestamp ahead of `now`, reads "now".
+ */
 export function formatRelativeTime(
   at: number,
   now: number,
   locale: string,
+  style: Intl.RelativeTimeFormatStyle = 'long',
 ): string {
+  const format = new Intl.RelativeTimeFormat(locale, { numeric: 'auto', style })
+  if (isJustNow(at, now)) {
+    return format.format(0, 'second')
+  }
   let value = Math.round((at - now) / MS_PER_SECOND)
-  const format = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' })
   for (const [unit, size] of RELATIVE_STEPS) {
     if (Math.abs(value) < size) {
       return format.format(value, unit)

package/frontend-vue/app/utils/funnel-draft.ts

@@ -15,6 +15,16 @@ export const MIN_VARIATIONS = 2
 export const MAX_VARIATIONS = 8
 export const MAX_EXPERIMENT_KEY_LENGTH = 64
 
+/**
+ * The windows the builder offers as one click, in hours. A funnel is matched
+ * within one session, which ends after 30 minutes without activity: a window
+ * of days would change nothing (FB-11). Each preset's label states the hours
+ * it saves, so the form shows what the funnel stores.
+ */
+export const WINDOW_PRESET_HOURS = [1, 24] as const
+/** A new funnel's window, as the backend defaults it. */
+export const DEFAULT_WINDOW_HOURS = 24
+
 /** The slug page code passes to `dmsMarketing.variation(…)`, both for the
  * experiment and its arms: it starts with a letter or a digit. */
 const EXPERIMENT_KEY_PATTERN = /^[a-z0-9][a-z0-9_-]*$/
@@ -100,6 +110,18 @@ export function templateSteps(raw: unknown): StepValue[] {
     .slice(0, MAX_STEPS)
 }
 
+/**
+ * A stored funnel as the builder opens it: `?split=1` (the report's "Split
+ * into A/B test") turns its split on; a funnel that already carries one keeps
+ * it either way.
+ */
+export function withRequestedSplit(
+  draft: FunnelDraftValues,
+  raw: unknown,
+): FunnelDraftValues {
+  return raw === '1' ? { ...draft, split: true } : draft
+}
+
 /** Whether a window is an hour count the server stores as is. */
 export function isWindowHours(hours: number | string): hours is number {
   return (

package/frontend-vue/app/utils/heatmap.ts

@@ -27,6 +27,23 @@ export function normalizePagePath(typed: string): string | undefined {
   }
 }
 
+/**
+ * The selected path's row in the list just read, else the row it `kept`
+ * while a filter hides it. The caller drops what it kept when the list is
+ * read for another scope (workspace, days): there the path has its own
+ * figures, or none.
+ */
+export function selectedPageRow<Row extends { path: string }>(
+  list: readonly Row[],
+  path: string | undefined,
+  kept: Row | undefined,
+): Row | undefined {
+  return (
+    list.find((page) => page.path === path) ??
+    (kept?.path === path ? kept : undefined)
+  )
+}
+
 /** What a heatmap reset deletes or deleted. */
 export interface HeatmapDataCounts {
   events: number

package/frontend-vue/app/utils/page-snapshot.ts

@@ -0,0 +1,75 @@
+import type {
+  MarketingPageSnapshotSummary,
+  MarketingSnapshotLayout,
+} from '../composables/useMarketingApi'
+import { formatRelativeTime, formatShortDate } from './format'
+
+/** The `t` of useI18n, as far as these helpers call it. */
+type Translate = (
+  key: string,
+  named?: Record<string, unknown>,
+  plural?: number,
+) => string
+
+const PREFIX = 'page.marketing.pages.row_snapshot'
+
+/** What a row of the pages list says of its path's snapshot. */
+export interface PageSnapshotBadge {
+  icon: string
+  label: string
+  /** The full sentence, for the tooltip and assistive technology. */
+  title: string
+  /** Muted when there is nothing to show. */
+  muted: boolean
+}
+
+function layoutNames(layouts: MarketingSnapshotLayout[], t: Translate): string {
+  return layouts
+    .map((layout) =>
+      t(`page.marketing.pages.preview.layout_${layout}`).toLowerCase(),
+    )
+    .join(', ')
+}
+
+/**
+ * The row's snapshot mark: its age, or that the page has none or is too
+ * heavy. `undefined` is a site with snapshots off — the rows say nothing,
+ * the preview's strip says why.
+ */
+export function pageSnapshotBadge(
+  snapshot: MarketingPageSnapshotSummary | null | undefined,
+  now: number,
+  t: Translate,
+  locale: string,
+): PageSnapshotBadge | null {
+  if (snapshot === undefined) {
+    return null
+  }
+  if (snapshot === null) {
+    return {
+      icon: 'i-ph-camera-slash',
+      label: t(`${PREFIX}.none`),
+      title: t(`${PREFIX}.none_title`),
+      muted: true,
+    }
+  }
+  const date = formatShortDate(snapshot.capturedAt, locale)
+  if (snapshot.tooHeavy) {
+    return {
+      icon: 'i-ph-file-x',
+      label: t(`${PREFIX}.too_heavy`),
+      title: t(`${PREFIX}.too_heavy_title`, { date }),
+      muted: true,
+    }
+  }
+  return {
+    icon: 'i-ph-camera',
+    label: formatRelativeTime(snapshot.capturedAt, now, locale, 'short'),
+    title: t(
+      `${PREFIX}.title`,
+      { date, layouts: layoutNames(snapshot.layouts, t) },
+      snapshot.layouts.length,
+    ),
+    muted: false,
+  }
+}

package/frontend-vue/app/utils/snapshot-options.ts

@@ -0,0 +1,148 @@
+/**
+ * Changing a site's snapshot options deletes its snapshots on the server
+ * (`PUT /api/marketing/websites/:id`): off means forgotten, and a mask
+ * setting only holds for captures taken under it. Every place offering the
+ * options asks first, with the same words.
+ */
+
+/** The `t` of useI18n, as far as these helpers call it. */
+type Translate = (
+  key: string,
+  named?: Record<string, unknown>,
+  plural?: number,
+) => string
+
+interface SnapshotOptions {
+  snapshotsEnabled: boolean
+  snapshotMaskText?: boolean
+}
+
+type SnapshotPatch = Partial<SnapshotOptions>
+
+/** Whether saving `patch` changes an option the server discards on. */
+export function changesSnapshotOptions(
+  website: SnapshotOptions,
+  patch: Partial<SnapshotOptions>,
+): boolean {
+  return (
+    (patch.snapshotsEnabled !== undefined &&
+      patch.snapshotsEnabled !== website.snapshotsEnabled) ||
+    (patch.snapshotMaskText !== undefined &&
+      patch.snapshotMaskText !== (website.snapshotMaskText ?? false))
+  )
+}
+
+/**
+ * Whether saving `patch` asks first: any change of those options, holding
+ * snapshots or not — a site with none yet still changes what every later
+ * capture keeps, and the question must come wherever the option is
+ * toggled. Turning snapshots on for a site holding none is the exception:
+ * there is nothing to lose and nothing to warn about. `count` is the
+ * site's snapshots, null when it could not be read.
+ */
+export function asksBeforeSnapshotChange(
+  website: SnapshotOptions,
+  patch: Partial<SnapshotOptions>,
+  count: number | null,
+): boolean {
+  if (!changesSnapshotOptions(website, patch)) {
+    return false
+  }
+  const enabling = patch.snapshotsEnabled === true && !website.snapshotsEnabled
+  return !(enabling && count === 0)
+}
+
+/** What confirming a snapshot option change needs from its page. */
+export interface SnapshotChangeSteps {
+  /** The site's snapshots; null when they could not be counted. */
+  count: () => Promise<number | null>
+  /** Resolves true when the person goes ahead. */
+  confirm: (
+    options: ReturnType<typeof snapshotDiscardConfirmation>,
+  ) => Promise<boolean>
+  t: Translate
+}
+
+/**
+ * Whether `patch` may be saved: counted, then asked when
+ * asksBeforeSnapshotChange says so. Nothing is saved on a refusal, so a
+ * control bound to the website keeps showing what the website holds.
+ */
+export async function confirmSnapshotChange(
+  website: SnapshotOptions,
+  patch: SnapshotPatch,
+  steps: SnapshotChangeSteps,
+): Promise<boolean> {
+  if (!changesSnapshotOptions(website, patch)) {
+    return true
+  }
+  const count = await steps.count().catch(() => null)
+  if (!asksBeforeSnapshotChange(website, patch, count)) {
+    return true
+  }
+  return steps.confirm(snapshotDiscardConfirmation(steps.t, count))
+}
+
+/**
+ * The two option checkboxes of the heatmap preview's menu. Bound to the
+ * website, never to a local copy: a declined change leaves them as they
+ * were, and a saved one shows once the website comes back updated.
+ */
+export function snapshotOptionItems(
+  website: SnapshotOptions | null,
+  change: (patch: SnapshotPatch) => void,
+  t: Translate,
+) {
+  const enabled = website?.snapshotsEnabled ?? false
+  return [
+    {
+      type: 'checkbox' as const,
+      label: t('page.marketing.pages.preview.snapshots_enabled'),
+      checked: enabled,
+      onUpdateChecked: (value: boolean): void =>
+        change({ snapshotsEnabled: value }),
+    },
+    {
+      type: 'checkbox' as const,
+      label: t('page.marketing.pages.preview.mask_text'),
+      checked: website?.snapshotMaskText === true,
+      disabled: !enabled,
+      onUpdateChecked: (value: boolean): void =>
+        change({ snapshotMaskText: value }),
+    },
+  ]
+}
+
+/**
+ * The confirmation asked before such a change; `count` is the site's
+ * snapshots, null when it could not be read — the change still discards
+ * whatever there is, so the question is asked without the number — and 0
+ * when there are none to discard, the question then being the setting.
+ */
+export function snapshotDiscardConfirmation(
+  t: Translate,
+  count: number | null,
+) {
+  const prefix = 'page.marketing.websites.discard_confirm'
+  if (count === 0) {
+    return {
+      title: t(`${prefix}.title_none`),
+      description: t(`${prefix}.description_none`),
+      confirmLabel: t(`${prefix}.confirm_none`),
+      cancelLabel: t(`${prefix}.cancel_none`),
+      color: 'warning' as const,
+      icon: 'i-ph-camera',
+    }
+  }
+  return {
+    title: t(`${prefix}.title`),
+    description:
+      count === null
+        ? t(`${prefix}.description_unknown`)
+        : t(`${prefix}.description`, { count }, count),
+    confirmLabel: t(`${prefix}.confirm`),
+    cancelLabel: t(`${prefix}.cancel`),
+    color: 'warning' as const,
+    icon: 'i-ph-warning',
+  }
+}

package/frontend-vue/app/utils/snapshotScrollRoot.ts

@@ -0,0 +1,93 @@
+/**
+ * The inner scroll container of a snapshot, unrolled.
+ *
+ * An app shell keeps its document still and scrolls a panel instead; the
+ * capture marks that panel `data-marketing-scroll-root` (see
+ * static/snapshot.js). Rendered as captured, the panel stays clipped at the
+ * visitor's window height and everything below the fold is out of reach —
+ * the frame does not scroll, and no click below the first screen has
+ * anything under it. Unrolled, the panel and every ancestor that pinned its
+ * height let it grow: the document becomes as tall as the content, which is
+ * what the tracker's click fractions and scroll depths are measured against.
+ *
+ * Only the vertical axis is released. A horizontal clip stays (as `clip`,
+ * which unlike `hidden` does not turn the box back into a scroll container),
+ * and only a column flexbox has its items' basis touched — in a row, the
+ * basis is a width.
+ */
+
+export const SCROLL_ROOT_ATTRIBUTE = 'data-marketing-scroll-root'
+
+/** The few computed properties the unrolling reads. */
+export interface UnrollStyle {
+  position: string
+  overflowX: string
+  display: string
+  flexDirection: string
+}
+
+/** The part of an element the unrolling touches. */
+export interface UnrollElement {
+  parentElement: UnrollElement | null
+  style: { setProperty(name: string, value: string, priority: string): void }
+}
+
+function important(element: UnrollElement, name: string, value: string): void {
+  element.style.setProperty(name, value, 'important')
+}
+
+function isColumnFlex(style: UnrollStyle | null): boolean {
+  return (
+    !!style &&
+    (style.display === 'flex' || style.display === 'inline-flex') &&
+    style.flexDirection.startsWith('column')
+  )
+}
+
+/**
+ * Releases `root` and its ancestors; `computed` reads an element's style as
+ * the page laid it out.
+ */
+export function unrollScrollRoot<E extends UnrollElement>(
+  root: E,
+  computed: (element: E) => UnrollStyle,
+): void {
+  for (
+    let element: E | null = root;
+    element;
+    element = element.parentElement as E | null
+  ) {
+    const style = computed(element)
+    const parent = element.parentElement as E | null
+    important(element, 'height', 'auto')
+    important(element, 'max-height', 'none')
+    important(element, 'overflow-y', 'visible')
+    if (style.overflowX !== 'visible') {
+      important(element, 'overflow-x', 'clip')
+    }
+    // A fixed box adds nothing to the document's scroll height, and one
+    // pinned at both ends (`inset: 0`) keeps the window's height.
+    if (style.position === 'fixed' || style.position === 'absolute') {
+      important(element, 'position', 'absolute')
+      important(element, 'bottom', 'auto')
+    }
+    if (parent && isColumnFlex(computed(parent))) {
+      important(element, 'flex-basis', 'auto')
+      important(element, 'flex-shrink', '0')
+    }
+  }
+}
+
+/** Unrolls the marked scroll root of a rendered snapshot, if it has one —
+ *  a capture taken where the document scrolls has none and is left as is. */
+export function unrollSnapshotScrollRoot(doc: Document): boolean {
+  const view = doc.defaultView
+  const root = doc.querySelector<HTMLElement>(`[${SCROLL_ROOT_ATTRIBUTE}]`)
+  if (!view || !root) {
+    return false
+  }
+  unrollScrollRoot<HTMLElement>(root, (element) =>
+    view.getComputedStyle(element),
+  )
+  return true
+}

package/frontend-vue/app/utils/website-card.ts

@@ -0,0 +1,93 @@
+/**
+ * The Websites page's cards: a row of the websites table, as its list route
+ * answers it (the stored fields and, merged in, the card the backend
+ * computed), read into the card the card component and the settings modal
+ * draw. Pure, so the mapping is testable without the table.
+ */
+
+import type {
+  MarketingRejectedSource,
+  MarketingWebsiteCard,
+} from '../composables/useMarketingApi'
+import type { WebsiteState } from '../composables/useMarketingContext'
+
+/** A row of the websites table, whatever it carries. */
+export type WebsiteRow = Record<string, unknown>
+
+const WEBSITE_STATES: readonly WebsiteState[] = [
+  'live',
+  'imported',
+  'waiting',
+  'paused',
+]
+
+function text(value: unknown): string {
+  return typeof value === 'string' ? value : ''
+}
+
+function count(value: unknown): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : 0
+}
+
+function epoch(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) {
+    return value
+  }
+  if (typeof value === 'string' && value) {
+    const parsed = Date.parse(value)
+    return Number.isNaN(parsed) ? null : parsed
+  }
+  return null
+}
+
+function hosts(value: unknown): string[] {
+  return Array.isArray(value)
+    ? value.filter((host): host is string => typeof host === 'string')
+    : []
+}
+
+function refused(value: unknown): MarketingRejectedSource[] {
+  return Array.isArray(value)
+    ? value.filter(
+        (source): source is MarketingRejectedSource =>
+          typeof source === 'object' &&
+          source !== null &&
+          typeof (source as MarketingRejectedSource).hostname === 'string',
+      )
+    : []
+}
+
+/**
+ * The state the row's card shows. The backend sends it with the card; a row
+ * read without it (its card missing) falls back on the stored switch, and
+ * waits for its first pageview otherwise.
+ */
+function stateOf(row: WebsiteRow): WebsiteState {
+  const state = row.state as WebsiteState
+  if (WEBSITE_STATES.includes(state)) {
+    return state
+  }
+  return row.trackingEnabled === false ? 'paused' : 'waiting'
+}
+
+/** The card of a websites table row, every field defaulted. */
+export function websiteCardOf(row: WebsiteRow): MarketingWebsiteCard {
+  return {
+    id: text(row._id) || text(row.id),
+    name: text(row.name),
+    domain: text(row.domain),
+    state: stateOf(row),
+    lastActivityAt: epoch(row.lastActivityAt),
+    extraDomains: hosts(row.extraDomains),
+    snapshotsEnabled: row.snapshotsEnabled === true,
+    snapshotMaskText: row.snapshotMaskText === true,
+    createdAt: epoch(row.createdAt) ?? 0,
+    sessions: count(row.sessions),
+    pages: count(row.pages),
+    funnels: count(row.funnels),
+    snapshots: count(row.snapshots),
+    sampleRate: count(row.sampleRate),
+    rejected: refused(row.rejected),
+    dashboard: row.dashboard === true,
+  }
+}