@thg-agentic/hyper-personalisation-web 3.22.2 → 3.24.0

package/src/onsite/triggers.js

@@ -0,0 +1,165 @@
+/**
+ * When a form's trigger fires. Exit intent follows ouibounce and use-exit-intent (both MIT; the
+ * thresholds are ours, docs/design/onsite-capture-research.md §7):
+ *
+ * - desktop: armed `delay_ms` (5 s) after the start and once the pointer has been below the top
+ *   tenth of the viewport; fires when it leaves the document through the top edge, moving up, with
+ *   no field focused.
+ * - mobile: after 30% of the page has been scrolled, an upward flick of 120px or more at 0.5 px/ms
+ *   or faster within 300 ms (reaching for the address bar or back), or a return to the tab after
+ *   10 s or more away. Never on hide.
+ *
+ * Every watcher returns what stops it.
+ */
+
+const EXIT_ARM_MS = 5000;
+const FLICK_PX = 120;
+const FLICK_PX_PER_MS = 0.5;
+const FLICK_WINDOW_MS = 300;
+const EXIT_DEPTH = 0.3;
+const AWAY_MS = 10_000;
+const INPUTS = [
+	'mousemove',
+	'pointerdown',
+	'keydown',
+	'scroll',
+	'touchstart',
+	'wheel',
+];
+
+function listeners() {
+	const off = [];
+	const on = (target, type, handler, options = { passive: true }) => {
+		target.addEventListener(type, handler, options);
+		off.push(() => target.removeEventListener(type, handler, options));
+	};
+	const later = (fn, ms) => {
+		const id = setTimeout(fn, ms);
+		off.push(() => clearTimeout(id));
+	};
+	return {
+		on,
+		later,
+		stop: () => {
+			for (const f of off.splice(0)) f();
+		},
+	};
+}
+
+const depthOf = (win, doc) => {
+	const height = doc.documentElement.scrollHeight || 0;
+	return height > 0 ? (win.scrollY + win.innerHeight) / height : 0;
+};
+
+const typing = (doc) => {
+	const el = doc.activeElement;
+	return Boolean(
+		el &&
+			(/^(INPUT|TEXTAREA|SELECT)$/.test(el.tagName) || el.isContentEditable),
+	);
+};
+
+function desktopExit({ on, later }, fire, trigger, win, doc) {
+	let armed = false;
+	let below = false;
+	let lastY = null;
+	let dy = 0;
+	later(() => {
+		armed = true;
+	}, trigger.delay_ms ?? EXIT_ARM_MS);
+	on(doc, 'mousemove', (e) => {
+		if (e.clientY > win.innerHeight * 0.1) below = true;
+		if (lastY !== null) dy = e.clientY - lastY;
+		lastY = e.clientY;
+	});
+	on(doc, 'mouseout', (e) => {
+		if (
+			armed &&
+			below &&
+			!e.relatedTarget &&
+			e.clientY <= 0 &&
+			dy < 0 &&
+			!typing(doc)
+		)
+			fire('exit');
+	});
+}
+
+function mobileExit({ on, later }, fire, trigger, win, doc) {
+	let armed = false;
+	let reached = 0;
+	let lastY = win.scrollY;
+	let lastT = Date.now();
+	let run = null;
+	let hiddenAt = null;
+	later(() => {
+		armed = true;
+	}, trigger.delay_ms ?? EXIT_ARM_MS);
+	on(win, 'scroll', () => {
+		const y = win.scrollY;
+		const t = Date.now();
+		reached = Math.max(reached, depthOf(win, doc));
+		if (y < lastY) {
+			if (!run || t - run.t > FLICK_WINDOW_MS) run = { y: lastY, t: lastT };
+			const dist = run.y - y;
+			if (
+				armed &&
+				reached >= EXIT_DEPTH &&
+				dist >= FLICK_PX &&
+				dist / Math.max(1, t - run.t) >= FLICK_PX_PER_MS
+			)
+				fire('exit_scroll');
+		} else run = null;
+		lastY = y;
+		lastT = t;
+	});
+	on(doc, 'visibilitychange', () => {
+		if (doc.visibilityState === 'hidden') hiddenAt = Date.now();
+		else if (hiddenAt !== null && Date.now() - hiddenAt >= AWAY_MS)
+			fire('return');
+		if (doc.visibilityState !== 'hidden') hiddenAt = null;
+	});
+}
+
+/**
+ * Watch `trigger` and call `fire(reason)` when it fires. Inline and manual forms are opened by the
+ * runtime itself, so they watch nothing.
+ *
+ * @param {{ type: string, delay_ms?: number, depth?: number, seconds?: number }} trigger
+ * @param {(reason: string) => void} fire
+ * @param {{ device: 'desktop'|'mobile', win?: Window, doc?: Document }} env
+ */
+export function watch(trigger, fire, { device, win = window, doc = document }) {
+	const l = listeners();
+	const seconds = (trigger.seconds ?? 30) * 1000;
+	if (trigger.type === 'entry')
+		l.later(() => fire('entry'), trigger.delay_ms ?? 0);
+	if (trigger.type === 'time') l.later(() => fire('time'), seconds);
+	if (trigger.type === 'exit')
+		(device === 'mobile' ? mobileExit : desktopExit)(
+			l,
+			fire,
+			trigger,
+			win,
+			doc,
+		);
+	if (trigger.type === 'scroll') {
+		const depth = trigger.depth ?? 0.5;
+		l.on(win, 'scroll', () => depthOf(win, doc) >= depth && fire('scroll'));
+	}
+	if (trigger.type === 'idle') {
+		let id = null;
+		const reset = () => {
+			clearTimeout(id);
+			id = setTimeout(() => fire('idle'), seconds);
+		};
+		reset();
+		for (const type of INPUTS) l.on(type === 'scroll' ? win : doc, type, reset);
+		l.on(doc, 'visibilitychange', reset);
+		return () => {
+			clearTimeout(id);
+			l.stop();
+		};
+	}
+	return l.stop;
+}

package/src/onsite/wheel-loader.js

@@ -0,0 +1,5 @@
+/**
+ * The wheel, only for a form that spins: a bundler splits this import out of ./onsite, and the CDN
+ * build swaps this module for cdn/wheel-loader.js, which loads dist/onsite-wheel.min.js.
+ */
+export const loadWheel = () => import('./wheel.js');

package/src/onsite/wheel.js

@@ -0,0 +1,196 @@
+/**
+ * The spin-to-win wheel (`./onsite/wheel`), a chunk of its own: an SVG of the form's prize labels
+ * that only animates, in the theme's colours: the accent and its tints, a rim of lights, a hub and
+ * a pointer. The prize is drawn on the server (`POST /v1/offers/claim`), so the wheel is told where
+ * to stop; the segments are equal, and say nothing about the odds. The angle math is ours, after
+ * spin-wheel's spinToItem (CrazyTim, MIT).
+ */
+
+import { restAngle } from './rules.js';
+
+const NS = 'http://www.w3.org/2000/svg';
+const SPIN_MS = 4500;
+/** A label's room along its slice, in the wheel's units: from beside the hub to inside the rim. */
+const LABEL_FROM = 0.22;
+const LABEL_TO = 0.95;
+/** Its type: as large as fits up to the first, never under the second (about 11px on a 320px wheel). */
+const FONT_MAX = 0.105;
+const FONT_MIN = 0.082;
+/** A bold sans character's width, a little over the average, so a label is never cut. */
+const EM_PER_CHAR = 0.62;
+const LINE_HEIGHT = 1.15;
+const ACCENT = 'var(--hp-accent,#111)';
+const ON_ACCENT = 'var(--hp-on-accent,#fff)';
+const BG = 'var(--hp-bg,#fff)';
+const TEXT = 'var(--hp-text,#111)';
+
+function make(tag, attrs = {}) {
+	const node = document.createElementNS(NS, tag);
+	for (const [key, value] of Object.entries(attrs))
+		node.setAttribute(key, String(value));
+	return node;
+}
+
+/** Colours as style, not attributes, so the theme's custom properties resolve. */
+function paint(node, fill, stroke, opacity = 1) {
+	node.style.fill = fill;
+	if (opacity < 1) node.style.fillOpacity = String(opacity);
+	if (stroke) node.style.stroke = stroke;
+	return node;
+}
+
+const reducedMotion = () =>
+	globalThis.matchMedia?.('(prefers-reduced-motion: reduce)')?.matches === true;
+
+const point = (deg, r = 1) => {
+	const rad = ((deg - 90) * Math.PI) / 180;
+	return `${(r * Math.cos(rad)).toFixed(4)} ${(r * Math.sin(rad)).toFixed(4)}`;
+};
+
+/**
+ * How a prize label fits its slice: on one line at the largest size that fits; else on two, broken
+ * at the space nearest its middle; else shortened with an ellipsis at the smallest size. A slice's
+ * width near the hub bounds the size too, so many slices draw smaller type.
+ *
+ * @returns {{ lines: string[], size: number }}
+ */
+export function fitLabel(label, slices) {
+	const room = LABEL_TO - LABEL_FROM;
+	// The slice's width a third of the way out, where a long label's lines run: their height fits.
+	const across = 2 * 0.35 * Math.sin(Math.min(Math.PI / slices, Math.PI / 2));
+	const top = (lines) =>
+		Math.max(FONT_MIN, Math.min(FONT_MAX, across / (lines * LINE_HEIGHT)));
+	const sizeFor = (text) => room / (Math.max(1, text.length) * EM_PER_CHAR);
+	const one = sizeFor(label);
+	if (one >= FONT_MIN) return { lines: [label], size: Math.min(top(1), one) };
+	const spaces = [...label.matchAll(/ /g)].map((m) => m.index);
+	if (spaces.length) {
+		const middle = label.length / 2;
+		const at = spaces.reduce((a, b) =>
+			Math.abs(b - middle) < Math.abs(a - middle) ? b : a,
+		);
+		const lines = [label.slice(0, at), label.slice(at + 1)];
+		const size = Math.min(top(2), ...lines.map(sizeFor));
+		if (size >= FONT_MIN) return { lines, size };
+	}
+	const fits = Math.floor(room / (FONT_MIN * EM_PER_CHAR));
+	return { lines: [`${label.slice(0, fits - 1).trimEnd()}…`], size: FONT_MIN };
+}
+
+/**
+ * Draw the wheel for `prizes` (`[{ key, label }]`) into `container`. Null for fewer than two.
+ *
+ * @returns {{ spinTo(index: number): Promise<void>, remove(): void } | null}
+ */
+export function mountWheel(container, prizes) {
+	const labels = (Array.isArray(prizes) ? prizes : []).map((p) =>
+		String(p?.label ?? p?.key ?? ''),
+	);
+	const n = labels.length;
+	if (n < 2) return null;
+	const size = 360 / n;
+	const svg = make('svg', {
+		viewBox: '-1.2 -1.2 2.4 2.4',
+		role: 'img',
+		'aria-label': `Prize wheel: ${labels.join(', ')}`,
+	});
+	const wheel = make('g');
+	// Spun about its own box, the unit circle round 0 0. A view-box origin sits at the user space's
+	// 0 0, not the viewBox's corner, so 50% there is off centre and the wheel swings out of its rim.
+	wheel.style.transformBox = 'fill-box';
+	wheel.style.transformOrigin = '50% 50%';
+	// The accent, a tint of it over the background, and for an odd count a third tone, so no two
+	// neighbours match.
+	const tones = [
+		[1, ON_ACCENT],
+		[0.14, TEXT],
+		[0.72, ON_ACCENT],
+	];
+	wheel.append(paint(make('circle', { r: 1 }), BG));
+	const lights = [];
+	labels.forEach((label, i) => {
+		const [tone, ink] = tones[n % 2 === 1 && i === n - 1 ? 2 : i % 2];
+		wheel.append(
+			paint(
+				make('path', {
+					d: `M0 0L${point(i * size)}A1 1 0 ${size > 180 ? 1 : 0} 1 ${point((i + 1) * size)}Z`,
+					'stroke-width': 0.012,
+				}),
+				ACCENT,
+				BG,
+				tone,
+			),
+		);
+		// Along its slice's middle; on the left half turned about its own centre, so at rest no label
+		// reads upside down.
+		const angle = (i + 0.5) * size - 90;
+		const fit = fitLabel(label, n);
+		const text = paint(
+			make('text', {
+				transform: `rotate(${angle}) translate(${(LABEL_FROM + LABEL_TO) / 2} 0)${angle > 90 && angle < 270 ? ' rotate(180)' : ''}`,
+				'text-anchor': 'middle',
+				'dominant-baseline': 'central',
+				'font-size': fit.size.toFixed(4),
+				'font-weight': 700,
+				'aria-hidden': 'true',
+			}),
+			ink,
+		);
+		// Two lines sit either side of the slice's middle.
+		fit.lines.forEach((line, k) => {
+			const span = make('tspan', {
+				x: 0,
+				y: ((k - (fit.lines.length - 1) / 2) * fit.size * LINE_HEIGHT).toFixed(
+					4,
+				),
+			});
+			span.textContent = line;
+			text.append(span);
+		});
+		wheel.append(text);
+		for (const at of [i * size, (i + 0.5) * size]) {
+			const [cx, cy] = point(at, 1.075).split(' ');
+			lights.push(paint(make('circle', { cx, cy, r: 0.024 }), BG));
+		}
+	});
+	svg.append(
+		paint(make('circle', { r: 1.13 }), TEXT),
+		...lights,
+		wheel,
+		paint(make('circle', { r: 0.17, 'stroke-width': 0.035 }), BG, TEXT),
+		paint(make('circle', { r: 0.065 }), ACCENT),
+		paint(
+			make('path', {
+				d: 'M-0.12 -1.2L0.12 -1.2L0 -0.86Z',
+				'stroke-width': 0.03,
+				'stroke-linejoin': 'round',
+			}),
+			ACCENT,
+			BG,
+		),
+	);
+	container.append(svg);
+
+	return {
+		spinTo(index) {
+			const still = reducedMotion();
+			wheel.style.transition = still
+				? 'none'
+				: `transform ${SPIN_MS}ms cubic-bezier(.15,.7,.1,1)`;
+			wheel.style.transform = `rotate(${restAngle(index, labels.length, still ? 0 : 5)}deg)`;
+			if (still) return Promise.resolve();
+			return new Promise((resolve) => {
+				const done = setTimeout(resolve, SPIN_MS + 200);
+				wheel.addEventListener(
+					'transitionend',
+					() => {
+						clearTimeout(done);
+						resolve();
+					},
+					{ once: true },
+				);
+			});
+		},
+		remove: () => svg.remove(),
+	};
+}

package/src/onsite-facade.js

@@ -0,0 +1,123 @@
+/**
+ * `hp.onsite`: open (`show`) a form by hand, listen to the forms, keep the screen clear, or read why
+ * each form did or did not show, all callable before the onsite runtime has loaded. Listeners and
+ * suppressions wait on the page for the runtime. An `open` made before it started waits for it, and resolves with what
+ * the runtime did, or `false` once the page knows no runtime will start; nothing here throws.
+ */
+
+const CONTROLLER = Symbol.for('@thg-agentic/hyper-personalisation-web.onsite');
+const PENDING = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.pending',
+);
+const LISTENERS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.listeners',
+);
+const SUPPRESSED = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.suppressed',
+);
+const EVENTS = ['shown', 'submitted', 'apply', 'closed', 'held'];
+const MAX_PENDING = 10;
+
+const page = () => (typeof window === 'undefined' ? null : window);
+
+/** No onsite runtime will start on this page: every `open` waiting for one resolves `false`. */
+export function dropPendingOpens() {
+	try {
+		for (const { resolve } of page()?.[PENDING]?.splice(0) ?? [])
+			resolve(false);
+	} catch {
+		/* never into the page */
+	}
+}
+
+export const onsite = Object.freeze({
+	/** Show the form on `slot` now, if its rules allow it. Resolves to whether it was shown. */
+	open(slot) {
+		try {
+			const w = page();
+			if (!w || typeof slot !== 'string') return Promise.resolve(false);
+			if (w[CONTROLLER]) return w[CONTROLLER].open(slot);
+			w[PENDING] ??= [];
+			if (w[PENDING].length < MAX_PENDING)
+				return new Promise((resolve) => w[PENDING].push({ slot, resolve }));
+		} catch {
+			/* never into the page */
+		}
+		return Promise.resolve(false);
+	},
+	/** The same as `open`, by the name the console's snippets use. */
+	show(slot) {
+		return onsite.open(slot);
+	},
+	/**
+	 * Listen to the forms: `shown`, `submitted` (`{ coupon }`: the claimed code for a form that
+	 * spins, else null), `apply` (`{ coupon }`: a reminder's code to apply), `closed`
+	 * (`{ reason }`) and `held` (a held-out visitor's trigger fired: the site shows what it shows
+	 * without HP). Each detail carries the `slot`, `arm` and `format`. Returns a function that
+	 * stops listening.
+	 */
+	on(name, fn) {
+		try {
+			const w = page();
+			if (!w || !EVENTS.includes(name) || typeof fn !== 'function')
+				return () => {};
+			w[LISTENERS] ??= {};
+			(w[LISTENERS][name] ??= new Set()).add(fn);
+			return () => w[LISTENERS][name].delete(fn);
+		} catch {
+			return () => {};
+		}
+	},
+	/** Keep the screen clear, for `reason`: a form showing goes, quietly, and none shows until every reason is lifted. */
+	suppress(reason = 'page') {
+		try {
+			const w = page();
+			if (!w) return;
+			(w[SUPPRESSED] ??= new Set()).add(String(reason));
+			w[CONTROLLER]?.suppress();
+		} catch {
+			/* never into the page */
+		}
+	},
+	/** Lift `reason`, or every reason when none is given. */
+	unsuppress(reason) {
+		try {
+			const set = page()?.[SUPPRESSED];
+			if (reason === undefined) set?.clear();
+			else set?.delete(String(reason));
+		} catch {
+			/* never into the page */
+		}
+	},
+	/**
+	 * Each form's state, as `debug`, once the page knows whether onsite forms run on it: when the
+	 * runtime has started, or `[]` once none will (not opted in, no live form, the chunk failed).
+	 */
+	ready() {
+		try {
+			const w = page();
+			if (!w) return Promise.resolve([]);
+			if (w[CONTROLLER]) return Promise.resolve(onsite.debug());
+			w[PENDING] ??= [];
+			if (w[PENDING].length < MAX_PENDING)
+				return new Promise((resolve) =>
+					// Settled when the runtime starts (it opens no form for no slot) or none will.
+					w[PENDING].push({
+						slot: null,
+						resolve: () => resolve(onsite.debug()),
+					}),
+				);
+		} catch {
+			/* never into the page */
+		}
+		return Promise.resolve([]);
+	},
+	/** Each form's eligibility on this page, and why: `[]` until the runtime has started. */
+	debug() {
+		try {
+			return page()?.[CONTROLLER]?.debug() ?? [];
+		} catch {
+			return [];
+		}
+	},
+});

package/src/onsite-loader.js

@@ -0,0 +1,5 @@
+/**
+ * The onsite runtime, as a separate chunk: a bundler splits this import out of the core, and the
+ * CDN build swaps this module for cdn/onsite-loader.js, which loads dist/onsite.min.js.
+ */
+export const loadOnsite = () => import('./onsite/index.js');

package/src/settings.js

@@ -156,6 +156,22 @@ function readAnonymousId(raw) {
 		: null;
 }
 
+/**
+ * The live onsite forms (`hp.onsite`), or null when there are none. Only the shape is checked here:
+ * ./onsite reads each form itself, so the core never grows with the forms' rules.
+ */
+function readOnsite(raw) {
+	const forms = Array.isArray(raw?.forms) ? raw.forms.filter(isObject) : [];
+	if (forms.length === 0) return null;
+	return {
+		forms,
+		capture: isObject(raw.capture) ? raw.capture : null,
+		...(Number.isInteger(raw.overlay_gap_minutes)
+			? { overlay_gap_minutes: raw.overlay_gap_minutes }
+			: {}),
+	};
+}
+
 /**
  * Whether a 2xx body is a settings answer at all: an `hp` block saying on or off. Anything else (a
  * captive portal's page, a proxy's error) is no answer, so the last good settings and what was
@@ -174,6 +190,7 @@ export function isSettingsAnswer(body) {
 export function readSettings(body) {
 	const hp = isObject(body) ? body.hp : null;
 	if (!isObject(hp) || hp.enabled !== true) return DISABLED;
+	const onsite = readOnsite(hp.onsite);
 	return {
 		enabled: true,
 		propertyId:
@@ -192,6 +209,7 @@ export function readSettings(body) {
 		// The share of visitors sent for (3.18). Anything that is not a share sends for everyone.
 		sampleRate: isFraction(hp.sampleRate) ? hp.sampleRate : 1,
 		debug: readDebug(hp.debug),
+		...(onsite && { onsite }),
 		plan:
 			isObject(body.plan) && isObject(body.plan.track)
 				? { track: body.plan.track }

package/src/spec-version.js

@@ -1,4 +1,4 @@
 // Generated from the spec by scripts/build-types.mjs. DO NOT EDIT: run `pnpm run build:types`.
 
 /** The event specification this SDK emits, stamped on every event as context.spec.version. */
-export const SPEC_VERSION = '1.16';
+export const SPEC_VERSION = '1.18';

package/src/storage-scope.js

@@ -59,6 +59,11 @@ export const DEFAULT_STORAGE_NAMES = Object.freeze({
 	 * (`?hp_debug=`), checked against the settings on every page (3.18).
 	 */
 	debug: 'thg_hp_debug',
+	/**
+	 * localStorage and sessionStorage, per property: onsite forms' opaque counters per slot (shown,
+	 * last closed, submitted) and a subscribed flag. Never contact data (onsite).
+	 */
+	onsite: 'thg_hp_onsite',
 });
 
 /**

package/src/version.js

@@ -1,2 +1,2 @@
-export const VERSION = '3.22.2';
+export const VERSION = '3.24.0';
 export const LIB = '@thg-agentic/hyper-personalisation-web';

package/types/bootstrap.d.ts

@@ -19,6 +19,7 @@ import type {
 	PageType,
 	StorageNames,
 } from './index';
+import type { OnsiteFacade, OnsiteOptions, OnsiteSettings } from './onsite';
 
 /** Everything the page itself configures: the rest is the tenant's, and comes from settings. */
 export interface HpConfig {
@@ -68,6 +69,8 @@ export interface SettingsResponse {
 			string,
 			{ share: number; salt: string; readoutSlots?: string[] }
 		>;
+		/** The live onsite forms (ADR 0064). Started only for a page that passes `onsite`. */
+		onsite?: OnsiteSettings;
 	};
 }
 
@@ -148,6 +151,17 @@ export interface BootstrapOptions {
 	settings?: SettingsResponse;
 	/** createAnalytics options that are functions, e.g. getRecommendations or getExtensions. */
 	extend?: Partial<AnalyticsOptions>;
+	/**
+	 * Onsite forms: `true` (or the options) loads `./onsite` as a separate chunk when the settings
+	 * have a live form, and starts it. Absent or false: never loaded.
+	 */
+	onsite?: boolean | OnsiteOptions;
+}
+
+/** The client bootstrap resolves to: the lower-level client, plus `onsite`. */
+export interface BootstrappedClient extends AnalyticsClient {
+	/** Open a form by hand, or read why each form did or did not show (`[]` before it started). */
+	onsite: OnsiteFacade;
 }
 
 /**
@@ -157,7 +171,7 @@ export interface BootstrapOptions {
 export declare function bootstrap(
 	config: HpConfig,
 	options: BootstrapOptions,
-): Promise<AnalyticsClient | null>;
+): Promise<BootstrappedClient | null>;
 /** Every reason the config and options cannot be used; empty when they can. */
 export declare function validateConfig(
 	config: unknown,