@thg-agentic/hyper-personalisation-web 3.31.0 → 3.34.0

package/src/onsite/values.js

@@ -0,0 +1,218 @@
+/**
+ * Shopper values in a form's text (ADR 0064 as amended 2026-11-03): a heading's or a paragraph's
+ * value nodes, `{ v, fallback, format? }`, filled in the browser from what this page already
+ * knows: the basket in this visit, the name the page gave (`hp.onsite.values`), and the shopper's
+ * own answers. Each is drawn as text, never markup; a value this page does not know shows its
+ * fallback, or with the block's `missing: "hide"` the block is not shown. Its own chunk, loaded
+ * only for a form whose text has a value.
+ */
+
+import { money } from './money.js';
+import { holdsValue, MAX_DEPTH } from './rich-text.js';
+
+const VALUES = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-values',
+);
+/** The longest a value shows, its ellipsis included. */
+const MAX = 60;
+// Built from a string so the bundle stays ASCII whatever charset a CDN serves it with: esbuild
+// writes a literal's characters as they are.
+// biome-ignore lint/complexity/useRegexLiterals: a literal is bundled as non-ASCII characters.
+const UNSEEN = new RegExp(
+	'[\\u0000-\\u001f\\u007f-\\u009f\\u200b-\\u200f\\u202a-\\u202e\\u2060-\\u206f\\ufeff]',
+	'g',
+);
+/**
+ * How a value shows when its node names no format: the first of its catalogue `formats` and its
+ * `plural` (spec/onsite/values.json; a test holds the two the same). Text otherwise.
+ */
+export const DEFAULTS = {
+	basket_value: { style: 'money' },
+	basket_items: { style: 'number', plural: { one: 'item', other: 'items' } },
+};
+/** The prefix of an answer's key (the catalogue's `answers.prefix`). */
+export const ANSWER_PREFIX = 'answer.';
+/** The values only the page knows, given to `hp.onsite.values` or `startOnsite`. */
+export const PAGE = ['first_name'];
+const UNITS = [
+	['year', 31536e6],
+	['month', 2592e6],
+	['week', 6048e5],
+	['day', 864e5],
+	['hour', 36e5],
+	['minute', 6e4],
+];
+
+/** A value as the text it shows: one line, without controls, at most MAX characters. */
+export function clean(value) {
+	const chars = [
+		...String(value).replace(UNSEEN, '').replace(/\s+/g, ' ').trim(),
+	];
+	return chars.length > MAX
+		? `${chars
+				.slice(0, MAX - 1)
+				.join('')
+				.trimEnd()}…`
+		: chars.join('');
+}
+
+/** `lang` when the browser takes it as a locale, else the browser's own. */
+function localeOf(lang) {
+	try {
+		return Intl.getCanonicalLocales(lang || [])[0];
+	} catch {
+		return undefined;
+	}
+}
+
+/** The `Intl` formatters made so far, by kind, language and options: one each for a page. */
+const formatters = new Map();
+const formatter = (key, make) => {
+	if (!formatters.has(key)) formatters.set(key, make());
+	return formatters.get(key);
+};
+
+/**
+ * `raw` as text in `style`: a number, money in `currency`, a date, a time from now, or text; with
+ * `plural` (`{ one, other }`) a number is followed by the word for it. Null when it cannot be.
+ */
+export function formatValue(raw, style, { lang, currency, plural, now } = {}) {
+	if (raw === null || raw === undefined || raw === '') return null;
+	try {
+		if (style === 'date' || style === 'relative') {
+			const at = typeof raw === 'number' ? raw : Date.parse(raw);
+			if (!Number.isFinite(at)) return null;
+			if (style === 'date')
+				return formatter(
+					`date ${lang}`,
+					() => new Intl.DateTimeFormat(lang, { dateStyle: 'medium' }),
+				).format(at);
+			const gap = at - (now ?? Date.now());
+			const [unit, ms] = UNITS.find(([, ms]) => Math.abs(gap) >= ms) ?? [
+				'minute',
+				6e4,
+			];
+			return formatter(
+				`relative ${lang}`,
+				() => new Intl.RelativeTimeFormat(lang, { numeric: 'auto' }),
+			).format(Math.round(gap / ms), unit);
+		}
+		if (style !== 'number' && style !== 'money') return clean(raw) || null;
+		if (typeof raw !== 'number' || !Number.isFinite(raw)) return null;
+		const numbers =
+			style === 'money'
+				? formatter(`money ${lang} ${currency}`, () => money(lang, currency))
+				: formatter(`number ${lang}`, () => new Intl.NumberFormat(lang));
+		// An unknown currency: the value is not known, so its fallback shows.
+		if (!numbers) return null;
+		const text = numbers.format(raw);
+		if (!plural) return text;
+		const one =
+			formatter(`plural ${lang}`, () => new Intl.PluralRules(lang)).select(
+				raw,
+			) === 'one';
+		return clean(`${text} ${(one ? plural.one : plural.other) ?? ''}`);
+	} catch {
+		// An unknown locale: the value is not known.
+		return null;
+	}
+}
+
+/**
+ * The fill the renderer runs on each block it draws: a heading or paragraph with its values as
+ * text, or `false` when one is not known and the block says `missing: "hide"`; any other block,
+ * and one without values, as it was. `access.values()` is what the client knows of this visit;
+ * `given` the page's own values from `startOnsite`, which `hp.onsite.values` replaces.
+ *
+ * @param {{ locale?: string, questions?: Array<{ key: string, options?: Array<{ value: string, label: string }> }> }} form
+ * @param {{ values?: () => { basket_value?: number|null, basket_items?: number|null, currency?: string|null, answers?: Record<string, string[]>|null } }} access
+ * @param {Record<string, unknown>} [given]
+ */
+export function fillFor(form, access, given) {
+	const lang = localeOf(
+		form.locale || globalThis.document?.documentElement.lang,
+	);
+	const questions = new Map(
+		(Array.isArray(form.questions) ? form.questions : []).map((q) => [
+			q?.key,
+			q,
+		]),
+	);
+	// What the page knows, read once for the blocks of a step: they are filled together.
+	let known = null;
+	const read = () => {
+		if (!known) {
+			const page = globalThis.window?.[VALUES] ?? given ?? {};
+			known = { ...access.values?.() };
+			for (const key of PAGE)
+				if (typeof page[key] === 'string') known[key] = page[key];
+			queueMicrotask(() => {
+				known = null;
+			});
+		}
+		return known;
+	};
+
+	/** A choice question's answer as its options' labels: this form's, else the ones kept. */
+	const answer = (key, asked) => {
+		const q = questions.get(key);
+		const { answers } = read();
+		// Answers are shown back only where they may be kept: under personalisation consent.
+		if (!q || !answers) return null;
+		const chosen = asked?.[key] ?? answers[key];
+		const labels = (Array.isArray(chosen) ? chosen : []).flatMap((value) => {
+			const label = q.options?.find((o) => o?.value === value)?.label;
+			return typeof label === 'string' && label ? [clean(label)] : [];
+		});
+		if (!labels.length) return null;
+		try {
+			return formatter(
+				`list ${lang}`,
+				() => new Intl.ListFormat(lang, { type: 'conjunction' }),
+			).format(labels);
+		} catch {
+			// A browser without Intl.ListFormat (Safari before 14.1).
+			return labels.join(', ');
+		}
+	};
+
+	const resolve = (node, asked) => {
+		const key = node.v;
+		const set =
+			node.format && typeof node.format === 'object'
+				? node.format
+				: DEFAULTS[key];
+		const raw = key.startsWith(ANSWER_PREFIX)
+			? answer(key.slice(ANSWER_PREFIX.length), asked)
+			: read()[key];
+		return formatValue(raw, set?.style ?? 'text', {
+			lang,
+			currency: read().currency,
+			plural: set?.plural,
+		});
+	};
+
+	return (block, asked) => {
+		if (
+			(block?.t !== 'heading' && block?.t !== 'text') ||
+			!holdsValue(block.text)
+		)
+			return block;
+		let missed = false;
+		const walk = (text, depth) => {
+			if (typeof text === 'string' || depth > MAX_DEPTH) return text;
+			if (Array.isArray(text)) return text.map((t) => walk(t, depth + 1));
+			if (!text || typeof text !== 'object') return text;
+			if (typeof text.v === 'string') {
+				const value = resolve(text, asked);
+				if (value === null) missed = true;
+				return value ?? clean(text.fallback ?? '');
+			}
+			const tag =
+				'b' in text ? 'b' : 'i' in text ? 'i' : 'a' in text ? 'a' : null;
+			return tag ? { ...text, [tag]: walk(text[tag], depth + 1) } : text;
+		};
+		const text = walk(block.text, 0);
+		return missed && block.missing === 'hide' ? false : { ...block, text };
+	};
+}

package/src/onsite-facade.js

@@ -1,6 +1,7 @@
 /**
- * `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
+ * `hp.onsite`: open (`show`) a form by hand, listen to the forms, keep the screen clear, give a form's
+ * text what the page knows of the shopper, 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.
  */
@@ -15,11 +16,30 @@ const LISTENERS = Symbol.for(
 const SUPPRESSED = Symbol.for(
 	'@thg-agentic/hyper-personalisation-web.onsite.suppressed',
 );
+const PAGE_VALUES = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-values',
+);
+const PAGE_FACTS = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-facts',
+);
+/** The runtime's listeners for what the page says: its facts, or the product it is about. */
+const PAGE_SAID = Symbol.for(
+	'@thg-agentic/hyper-personalisation-web.onsite.page-said',
+);
 const EVENTS = ['shown', 'submitted', 'apply', 'closed', 'held', 'nothing'];
 const MAX_PENDING = 10;
 
 const page = () => (typeof window === 'undefined' ? null : window);
 
+/** The page said what it is about (facts, or a Product Viewed): the runtime judges again what waited. */
+export function pageSaid() {
+	try {
+		for (const heard of page()?.[PAGE_SAID] ?? []) heard();
+	} catch {
+		/* never into the page */
+	}
+}
+
 /** No onsite runtime will start on this page: every `open` waiting for one resolves `false`. */
 export function dropPendingOpens() {
 	try {
@@ -93,6 +113,41 @@ export const onsite = Object.freeze({
 			/* never into the page */
 		}
 	},
+	/**
+	 * What the page knows of the shopper for a form's text: `{ first_name }`. Kept in this page's
+	 * memory only and drawn as text in a form that shows it; never sent, stored or logged. Each call
+	 * replaces the last, and `values({})` forgets it (a sign-out).
+	 */
+	values(given) {
+		try {
+			const w = page();
+			if (w)
+				w[PAGE_VALUES] = given && typeof given === 'object' ? { ...given } : {};
+		} catch {
+			/* never into the page */
+		}
+	},
+	/**
+	 * What this page says about itself, for forms limited by page facts:
+	 * `{ next_day_eligible: true }`, each value true or false, a number or words. Kept in memory for
+	 * this page's path only (a single-page app's next page starts with none); a form's request sends
+	 * only the facts its rules read, never logged.
+	 * Each call replaces the last (call it again when the shopper picks another size), and
+	 * `facts({})` forgets.
+	 */
+	facts(given) {
+		try {
+			const w = page();
+			if (w)
+				w[PAGE_FACTS] = {
+					path: w.location?.pathname,
+					facts: given && typeof given === 'object' ? { ...given } : {},
+				};
+		} catch {
+			/* never into the page */
+		}
+		pageSaid();
+	},
 	/**
 	 * 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).

package/src/session/record.js

@@ -1,3 +1,4 @@
+import { currencyCode } from '../context.js';
 import { bump, categoryKey, pathPrefix } from './category.js';
 import { readSignals, writeSignals } from './signals.js';
 
@@ -64,6 +65,18 @@ const basketOf = (products) =>
 		),
 	].slice(0, RECENT_LIMIT);
 
+/**
+ * How many items a cart event's lines hold: a whole positive quantity as it is, a line without one
+ * or with a fractional one (a weight) once, and one of zero, below or not a number not at all.
+ */
+export const basketItemsOf = (products) =>
+	products.reduce((n, p) => {
+		const q = p?.quantity;
+		if (q === undefined || q === null) return n + 1;
+		if (typeof q !== 'number' || !Number.isFinite(q) || q <= 0) return n;
+		return n + (Number.isInteger(q) ? q : 1);
+	}, 0);
+
 /**
  * Fold one CDP event into the session signals.
  *
@@ -192,6 +205,11 @@ export function recordSessionEvent(eventName, properties, campaign) {
 			// Its lines are the basket as it now stands, merges and removals included.
 			if (Array.isArray(properties?.products))
 				s.basketProducts = basketOf(products);
+			s.basketItems = Array.isArray(properties?.products)
+				? basketItemsOf(products)
+				: null;
+			// The basket's own currency, so its value is never shown in another.
+			s.basketCurrency = currencyCode(properties?.currency);
 			const value = properties?.value;
 			s.basketValue =
 				typeof value === 'number' && Number.isFinite(value) && value >= 0

package/src/session/signals.js

@@ -91,6 +91,10 @@ function emptySignals() {
 		// The last Cart Updated's `value`, in its currency. Unknown (so every rule on it fails closed)
 		// until the visit sends one: a basket carried over from an earlier visit is not zero.
 		basketValue: null,
+		// How many items the last Cart Updated's lines hold; unknown until one lists them.
+		basketItems: null,
+		// The last Cart Updated's `currency`, the one its value is in; unknown when it named none.
+		basketCurrency: null,
 		recentSearches: [],
 		// Shown-and-ignored counts, kept apart from `recentProducts` so a rail's own impressions never
 		// read as interest. The threshold that makes them meaningful lives server-side in `fatigue.ts`.

package/src/version.js

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

package/types/onsite-preview.d.ts

@@ -34,6 +34,19 @@ export interface PreviewOptions {
 	prizes?: Array<{ key: string; label: string }>;
 	/** The basket a progress block is drawn against; 32 when left out. */
 	basketValue?: number;
+	/** The form's daily cut-off as the settings carry it (`window.daily`), which a `daily` countdown counts to. */
+	daily?: DailyCutoff;
+	/**
+	 * A returning shopper's values for the text's shopper values (`answers` by question, as option
+	 * values); null or left out, every value shows its fallback, as a new visitor sees it.
+	 */
+	values?: {
+		first_name?: string;
+		basket_value?: number;
+		basket_items?: number;
+		currency?: string;
+		answers?: Record<string, string[]>;
+	} | null;
 }
 
 export interface OnsitePreview {
@@ -56,3 +69,30 @@ export declare function mountPreview(
 
 /** The countries a phone field's country code picker offers, by ISO code, with their calling codes. */
 export declare const CALLING_CODES: Readonly<Record<string, string>>;
+
+/**
+ * A shopper value as the SDK draws it in a form's text: a number, money in `currency`, a date, a
+ * time from now or text, in `lang`; with `plural`, a number followed by its word. Null when it
+ * cannot be shown (an unknown currency, not a number).
+ */
+export declare function formatValue(
+	raw: unknown,
+	style: 'number' | 'money' | 'date' | 'relative' | 'text',
+	options?: {
+		lang?: string;
+		currency?: string | null;
+		plural?: { one: string; other: string };
+		now?: number;
+	},
+): string | null;
+
+/**
+ * A form's daily cut-off as the settings carry it (`window.daily`): the moments it falls, which the
+ * server works out in the shop's time zone, and a `daily` countdown counts to the first ahead.
+ */
+export interface DailyCutoff {
+	/** The cut-offs, epoch milliseconds, earliest first, up to 8 days on from when they were listed. */
+	next: readonly number[];
+	/** The form shows only while the next cut-off is at most this many hours away. */
+	within_hours?: number;
+}

package/types/onsite.d.ts

@@ -1,12 +1,51 @@
 import type { AnalyticsClient } from './index';
 
-/** RichText: plain text, bold, italic and https links. No markup: anything else is dropped. */
+/**
+ * RichText: plain text, bold, italic, https links and shopper values. No markup: anything else is
+ * dropped.
+ */
 export type RichText =
 	| string
 	| Array<
-			string | { b: RichText } | { i: RichText } | { a: RichText; href: string }
+			| string
+			| { b: RichText }
+			| { i: RichText }
+			| { a: RichText; href: string }
+			| OnsiteValueNode
 	  >;
 
+/**
+ * A shopper value in a heading's or a paragraph's text (3.32): filled in the browser as text, never
+ * markup, at most 60 characters. `v` is a key of spec/onsite/values.json: `basket_value`,
+ * `basket_items`, `first_name` (the page's, `hp.onsite.values`) or `answer.<question>` (the label
+ * of the shopper's answer, under personalisation consent). Unknown, it shows `fallback`, or with
+ * the block's `missing: "hide"` the block is not shown. Never inside a link.
+ */
+export interface OnsiteValueNode {
+	v: string;
+	fallback: string;
+	format?: {
+		style: 'number' | 'money' | 'date' | 'relative' | 'text';
+		/** After a number, the word for its count: `{ one: 'item', other: 'items' }`. */
+		plural?: { one: string; other: string };
+	};
+}
+
+/** What a page says about itself, for forms limited by page facts (3.34). */
+export type OnsitePageFacts = Record<string, boolean | number | string>;
+
+/** One rule on a page fact: `is` / `is_not` one of `values`, or `at_least` / `at_most` a number. */
+export interface OnsitePageFactRule {
+	fact: string;
+	op: 'is' | 'is_not' | 'at_least' | 'at_most';
+	values: Array<boolean | number | string>;
+}
+
+/** What the page knows of the shopper for a form's text. Never sent, stored or logged. */
+export interface OnsitePageValues {
+	first_name?: string;
+}
+
 export type OnsiteFormat =
 	| 'popup'
 	| 'sheet'
@@ -56,11 +95,26 @@ export interface OnsiteForm {
 		match: 'is' | 'contains';
 		values: string[];
 	}>;
+	/**
+	 * Shown only where the page says so (3.34): rules on the facts it gave with `hp.onsite.facts`.
+	 * Every rule must hold; a fact the page did not give meets none.
+	 */
+	page_facts?: OnsitePageFactRule[];
+	/** Shown only on the pages of chosen products (3.34): the server checks the page's product. */
+	products?: true;
 	/** Shown only with personalisation consent, and only to members as the server decides. */
 	audiences?: string[];
 	exclude_subscribed?: boolean;
 	caps?: { per_session?: number; lifetime?: number; after_close_days?: number };
-	window?: { starts_at?: string; ends_at?: string };
+	/**
+	 * Its dates and its daily cut-off: with one, it shows only while one of its listed cut-offs is
+	 * still ahead and, with `within_hours`, only that close to it (3.33).
+	 */
+	window?: {
+		starts_at?: string;
+		ends_at?: string;
+		daily?: import('./onsite-preview').DailyCutoff;
+	};
 	/**
 	 * The form's language, BCP 47 (`en-IE`): its phone field starts on this region's country code,
 	 * and a birthday's day and month follow its order and month names. Absent: the page's `lang`.
@@ -171,6 +225,8 @@ export interface OnsiteOptions {
 	/** Log why each form did or did not show. Also on with `?hp_debug=onsite` or the SDK's debug. */
 	debug?: boolean;
 	fetch?: typeof fetch;
+	/** What the page knows of the shopper for a form's text; `hp.onsite.values` replaces it. */
+	values?: OnsitePageValues;
 }
 
 /**
@@ -208,6 +264,7 @@ export type OnsiteNothingCode =
 	| 'no-code'
 	| 'renderer-failed'
 	| 'products-failed'
+	| 'values-failed'
 	| 'error';
 
 /** One form's state on this page, and why. */
@@ -291,6 +348,19 @@ export interface OnsiteFacade {
 	suppress(reason?: string): void;
 	/** Lift `reason`, or every reason. */
 	unsuppress(reason?: string): void;
+	/**
+	 * What the page knows of the shopper for a form's text (3.32), `{ first_name }`: in this page's
+	 * memory only, never sent, stored or logged. Each call replaces the last; `values({})` forgets.
+	 */
+	values(given: OnsitePageValues): void;
+	/**
+	 * What this page says about itself (3.34), such as `{ next_day_eligible: true }`: kept in memory
+	 * for this page's path only; a form's decision request sends only the facts its rules read,
+	 * never logged. Each call replaces the last; call it again when the shopper picks another size.
+	 * `facts({})` forgets. Names are lower case, digits and underscores; values true or false, a
+	 * number or words; at most 20.
+	 */
+	facts(given: OnsitePageFacts): void;
 	/** Each form's state once the page knows whether onsite forms run on it; `[]` when none will. */
 	ready(): Promise<OnsiteTrace[]>;
 	debug(): OnsiteTrace[];