@antelopejs/dms-marketing 0.2.2

package/frontend-vue/app/composables/useSnapshotFrame.ts

@@ -0,0 +1,183 @@
+import { computed, onBeforeUnmount, ref, watch, type Ref } from 'vue'
+
+/**
+ * Geometry of a page snapshot rendered in a same-origin, script-less frame.
+ *
+ * The frame is `srcdoc`, sandboxed without scripts and with the console's
+ * origin, so its document is ours to read: no handshake, no timeout, no
+ * silence to diagnose. The size is still taken from at most ONE reading,
+ * with the frame pinned at a probe viewport until then: sizing the frame
+ * from a reading taken through it runs away, every `100vh` section growing
+ * one tick at a time, exactly as it would with a live page. Once published,
+ * later growth is ignored until `reset()`.
+ */
+
+/** Fallback document height when nothing measured it. */
+export const DEFAULT_RENDER_HEIGHT = 3200
+
+/** Floor on any render height, measured or typed. */
+export const MIN_RENDER_HEIGHT = 400
+
+/** Ceilings on the drawn surface: the canvas allocates width × height × 4 B. */
+export const MAX_RENDER_HEIGHT = 20000
+export const MAX_RENDER_WIDTH = 4000
+
+/** Post-load growth worth waiting for: web fonts swapping in. */
+const SETTLE_MS = 300
+
+const SRCDOC_URL = 'about:srcdoc'
+
+/**
+ * `off` — no frame mounted.
+ * `pending` — a frame is up, nothing published yet; it stays at probe size.
+ * `measured` — a size was published; geometry comes from the snapshot.
+ */
+export type SnapshotTier = 'off' | 'pending' | 'measured'
+
+/** What the overlay asks the snapshot to locate for it. */
+export interface AnchorRequest {
+  selector: string
+  nth: number
+}
+
+/** Box of one anchor, in the snapshot document's own coordinates. */
+export interface AnchorBox extends AnchorRequest {
+  x: number
+  y: number
+  width: number
+  height: number
+}
+
+export function useSnapshotFrame(frame: Ref<HTMLIFrameElement | null>) {
+  /** Published size — the caller may size the frame from this, once. */
+  const measuredWidth = ref<number | null>(null)
+  const measuredHeight = ref<number | null>(null)
+
+  /** Published or given up on: no further reading may be taken. */
+  let closed = false
+  let settleTimer: ReturnType<typeof setTimeout> | null = null
+  let watchedFrame: HTMLIFrameElement | null = null
+
+  function clearTimer(): void {
+    if (settleTimer !== null) {
+      clearTimeout(settleTimer)
+      settleTimer = null
+    }
+  }
+
+  /** The srcdoc document, never the blank one a fresh frame starts on. */
+  function frameDocument(): Document | null {
+    const doc = frame.value?.contentDocument ?? null
+    return doc && doc.URL === SRCDOC_URL ? doc : null
+  }
+
+  function publish(): void {
+    const doc = frameDocument()
+    if (closed || !doc) {
+      return
+    }
+    closed = true
+    clearTimer()
+    const root = doc.documentElement
+    // Reported as measured, not clamped: a document too large to draw is a
+    // decision for the caller, and silently shrinking it here would misplace
+    // every click by the ratio it was shrunk.
+    measuredWidth.value = Math.max(root.scrollWidth, 1)
+    measuredHeight.value = Math.max(root.scrollHeight, MIN_RENDER_HEIGHT)
+  }
+
+  function onFrameLoad(): void {
+    const doc = frameDocument()
+    if (!doc || closed) {
+      return
+    }
+    void (doc.fonts?.ready ?? Promise.resolve()).then(() => {
+      if (closed) {
+        return
+      }
+      clearTimer()
+      settleTimer = setTimeout(publish, SETTLE_MS)
+    })
+  }
+
+  /**
+   * Stop reading without publishing. The caller uses this when it resizes
+   * the frame by hand (a typed height): from then on every reading measures
+   * that layout, not the snapshot's.
+   */
+  function close(): void {
+    closed = true
+    clearTimer()
+  }
+
+  /** Start over: forget the size and wait for the frame to load. */
+  function reset(): void {
+    clearTimer()
+    closed = false
+    measuredWidth.value = null
+    measuredHeight.value = null
+
+    watchedFrame?.removeEventListener('load', onFrameLoad)
+    watchedFrame = frame.value
+    watchedFrame?.addEventListener('load', onFrameLoad)
+    if (frameDocument()?.readyState === 'complete') {
+      onFrameLoad()
+    }
+  }
+
+  /**
+   * Where a set of anchors sits in the snapshot. `nth` is strict: a document
+   * that no longer has that match must not project the click onto a sibling
+   * of the same selector — no box means the caller keeps the click's
+   * document fractions. Read after the frame has settled at its final size;
+   * boxes taken while it is being resized measure the wrong layout.
+   */
+  function measureAnchors(anchors: AnchorRequest[]): AnchorBox[] {
+    const doc = frameDocument()
+    const view = doc?.defaultView
+    if (!doc || !view) {
+      return []
+    }
+    const boxes: AnchorBox[] = []
+    for (const anchor of anchors) {
+      let matches: NodeListOf<Element>
+      try {
+        matches = doc.querySelectorAll(anchor.selector)
+      }
+      catch {
+        continue
+      }
+      const box = matches[anchor.nth]?.getBoundingClientRect()
+      if (!box || box.width <= 0 || box.height <= 0) {
+        continue
+      }
+      boxes.push({
+        ...anchor,
+        x: box.left + view.scrollX,
+        y: box.top + view.scrollY,
+        width: box.width,
+        height: box.height,
+      })
+    }
+    return boxes
+  }
+
+  onBeforeUnmount(() => {
+    watchedFrame?.removeEventListener('load', onFrameLoad)
+    watchedFrame = null
+    clearTimer()
+  })
+
+  // A new frame is a new reading: the ref is only set once the iframe is
+  // actually rendered, which the caller does conditionally and keyed.
+  watch(frame, reset, { immediate: true })
+
+  const tier = computed<SnapshotTier>(() => {
+    if (!frame.value) {
+      return 'off'
+    }
+    return measuredHeight.value !== null ? 'measured' : 'pending'
+  })
+
+  return { measuredWidth, measuredHeight, tier, reset, close, measureAnchors }
+}

package/frontend-vue/app/plugins/funnel-steps-data-type.client.ts

@@ -0,0 +1,46 @@
+import { defineComponent, h } from 'vue'
+import { defineDmsPlugin } from '#dms/frontend-module'
+import FunnelStepsInput from '../components/FunnelStepsInput.vue'
+import type { FunnelStepDraft } from '../composables/useFunnelSteps'
+import { parseFunnelStepsValue } from '../composables/useFunnelSteps'
+
+const MAX_PREVIEW_STEPS = 3
+
+function renderStepsPreview(value: unknown): string {
+  const steps = parseFunnelStepsValue(value)
+  if (!steps.length) {
+    return '—'
+  }
+  const items = steps.slice(0, MAX_PREVIEW_STEPS).map((step) => step.value)
+  const remaining = steps.length - MAX_PREVIEW_STEPS
+  const tail = remaining > 0 ? ` +${remaining}` : ''
+  return `${items.join(' → ')}${tail}`
+}
+
+const FunnelStepsDisplay = defineComponent({
+  name: 'FunnelStepsDisplay',
+  props: {
+    modelValue: {
+      type: [Array, String] as unknown as () => FunnelStepDraft[] | string | null,
+      default: null,
+    },
+  },
+  setup(props) {
+    return () =>
+      h(FunnelStepsInput, {
+        modelValue: props.modelValue,
+        disabled: true,
+      })
+  },
+})
+
+export default defineDmsPlugin(() => {
+  const { registerDataType } = useDataTypes()
+  registerDataType({
+    id: 'marketing_funnel_steps',
+    displayComponent: FunnelStepsDisplay,
+    formatter: {
+      default: (value: unknown) => renderStepsPreview(value),
+    },
+  })
+})

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

@@ -0,0 +1,18 @@
+import type { Component } from 'vue'
+import { resolveDmsComponent } from '#dms/frontend-module'
+
+/**
+ * A DMS core component addressed by name.
+ *
+ * The core frontend module registers its components before any other module's
+ * entry runs, so a name that does not resolve is a programming error rather
+ * than a state worth rendering around — and the callers hand the result to
+ * APIs that take a component, not an optional one.
+ */
+export function dmsComponent(name: string): Component {
+  const component = resolveDmsComponent(name)
+  if (!component) {
+    throw new Error(`Unknown DMS component: ${name}`)
+  }
+  return component
+}

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

@@ -0,0 +1,41 @@
+/**
+ * The heat ramp shared by the click heatmap and the scroll-depth overlay, so
+ * the two overlays read as one scale.
+ *
+ * Literal colors on purpose: this is a data scale, not interface chrome. The
+ * theme carries semantic tokens (primary, error, muted…) but no sequential
+ * ramp, and "red means hot" derives from none of them.
+ */
+
+export type HeatRgb = readonly [number, number, number]
+
+/** Position on the 0-1 ramp → color, linearly interpolated in between. */
+export const HEAT_STOPS: ReadonlyArray<readonly [number, HeatRgb]> = [
+  [0.0, [0, 80, 255]],
+  [0.4, [0, 200, 255]],
+  [0.6, [80, 220, 60]],
+  [0.8, [255, 220, 0]],
+  [1.0, [255, 40, 0]],
+]
+
+export function heatRgba(rgb: HeatRgb, alpha: number): string {
+  return `rgba(${rgb[0]}, ${rgb[1]}, ${rgb[2]}, ${alpha})`
+}
+
+export function heatColorAt(fraction: number, alpha: number): string {
+  const bounded = Math.min(Math.max(fraction, 0), 1)
+  let low = HEAT_STOPS[0]!
+  let high = HEAT_STOPS[HEAT_STOPS.length - 1]!
+  for (let i = 0; i < HEAT_STOPS.length - 1; i++) {
+    if (bounded >= HEAT_STOPS[i]![0] && bounded <= HEAT_STOPS[i + 1]![0]) {
+      low = HEAT_STOPS[i]!
+      high = HEAT_STOPS[i + 1]!
+      break
+    }
+  }
+  const span = high[0] - low[0]
+  const mix = span > 0 ? (bounded - low[0]) / span : 0
+  const channel = (index: number) =>
+    Math.round(low[1][index]! + (high[1][index]! - low[1][index]!) * mix)
+  return heatRgba([channel(0), channel(1), channel(2)], alpha)
+}

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

@@ -0,0 +1,63 @@
+/**
+ * Viewport-relative units of a snapshot, rewritten to the pixels they
+ * resolved to in the visitor's viewport.
+ *
+ * The snapshot frame is as tall as the whole document, so inside it `100vh`
+ * is the document height, not a screen: every `min-height: 70vh` section
+ * grows to 70 % of the page and the rest is pushed past the frame's edge.
+ * No frame can be told otherwise; the stylesheet can. Only declaration
+ * values are rewritten — a Tailwind arbitrary value puts `100vh` in the
+ * selector too (`.h-\[100vh\]`), and rewriting it there would orphan the
+ * rule — and a colon escaped with a backslash (`.md\:h-full`) is a selector
+ * character, not the start of a value.
+ *
+ * Horizontal units are left alone: the frame is laid out at the chosen
+ * width, so `vw` already means what it should.
+ */
+
+export interface SnapshotViewport {
+  width: number
+  height: number
+}
+
+const VIEWPORT_UNIT = /(-?(?:\d+\.?\d*|\.\d+))(dvh|svh|lvh|vh|vmin|vmax)(?![\w-])/g
+const DECLARATION_VALUE = /((?<!\\):)([^;{}]*)/g
+const STYLE_BLOCK = /(<style\b[^>]*>)([\s\S]*?)(<\/style>)/gi
+const STYLE_ATTRIBUTE = /(\sstyle=")([^"]*)(")/gi
+
+function pixelsOf(amount: string, unit: string, viewport: SnapshotViewport): number {
+  const base = unit.endsWith('vh')
+    ? viewport.height
+    : unit === 'vmin'
+      ? Math.min(viewport.width, viewport.height)
+      : Math.max(viewport.width, viewport.height)
+  return Math.round(Number.parseFloat(amount) * base) / 100
+}
+
+function rewriteValue(value: string, viewport: SnapshotViewport): string {
+  return value.replace(
+    VIEWPORT_UNIT,
+    (_match, amount: string, unit: string) => `${pixelsOf(amount, unit, viewport)}px`,
+  )
+}
+
+function rewriteDeclarations(css: string, viewport: SnapshotViewport): string {
+  return css.replace(
+    DECLARATION_VALUE,
+    (_match, colon: string, value: string) => colon + rewriteValue(value, viewport),
+  )
+}
+
+export function rewriteViewportUnits(html: string, viewport: SnapshotViewport): string {
+  return html
+    .replace(
+      STYLE_BLOCK,
+      (_match, open: string, css: string, close: string) =>
+        open + rewriteDeclarations(css, viewport) + close,
+    )
+    .replace(
+      STYLE_ATTRIBUTE,
+      (_match, open: string, css: string, close: string) =>
+        open + rewriteDeclarations(css, viewport) + close,
+    )
+}

package/frontend-vue/dms.frontend.ts

@@ -0,0 +1,35 @@
+import { defineAsyncComponent, type Component } from 'vue'
+import type { DmsFrontendModule } from '#dms/frontend-module'
+import funnelStepsDataType from './app/plugins/funnel-steps-data-type.client'
+
+interface VueModule {
+  default: Component
+}
+
+/**
+ * Every component of this module is addressed by name from the backend: the
+ * pages declare `CustomComponent('DmsMarketing<Name>')` and the DataTypes
+ * resolve their inputs the same way. Registering the whole directory under
+ * that prefix keeps the two sides in sync without a manual list.
+ */
+const components = import.meta.glob<VueModule>('./app/components/**/*.vue')
+
+const frontendModule: DmsFrontendModule = {
+  setup(sdk) {
+    for (const [path, loader] of Object.entries(components).sort()) {
+      const name = path
+        .split('/')
+        .at(-1)!
+        .replace(/\.vue$/, '')
+      sdk.registerComponent(
+        `DmsMarketing${name}`,
+        defineAsyncComponent(async () => (await loader()).default),
+      )
+    }
+    // Client-only: the display it registers carries callables, which the SSR
+    // payload strips.
+    sdk.registerPlugin(funnelStepsDataType, { clientOnly: true })
+  },
+}
+
+export default frontendModule

package/frontend-vue/eslint.config.mjs

@@ -0,0 +1,16 @@
+import vue from 'eslint-plugin-vue'
+import ts from 'typescript-eslint'
+
+export default [
+  { ignores: ['node_modules/**', 'dist/**'] },
+  ...vue.configs['flat/essential'],
+  {
+    files: ['**/*.ts', '**/*.vue'],
+    languageOptions: { parserOptions: { parser: ts.parser } },
+    rules: {
+      curly: ['error', 'all'],
+      'vue/multi-word-component-names': 'off',
+    },
+  },
+  { files: ['**/*.ts'], languageOptions: { parser: ts.parser } },
+]