@sunboard/react 0.4.0 → 0.6.0

package/dist/index.mjs

@@ -27,12 +27,64 @@ function resolveIdentities(prop) {
 function detectAnalyticsIdentities() {
 	const identities = {};
 	if (typeof window === "undefined") return identities;
-	const posthogId = probe(() => {
+	const posthogId = detectPosthogId();
+	if (posthogId) identities.posthog = posthogId;
+	return identities;
+}
+function detectPosthogId() {
+	const fromInstance = probe(() => {
 		const posthog = window.posthog;
 		return typeof posthog?.get_distinct_id === "function" ? posthog.get_distinct_id() : void 0;
 	});
-	if (posthogId) identities.posthog = posthogId;
-	return identities;
+	if (fromInstance) return fromInstance;
+	const candidates = [...posthogCandidatesFromLocalStorage(), ...posthogCandidatesFromCookie()];
+	let best;
+	for (const candidate of candidates) if (!best || candidate.lastActivity > best.lastActivity) best = candidate;
+	return best?.distinctId;
+}
+const POSTHOG_PERSISTENCE_KEY = /^ph_.+_posthog$/;
+function posthogCandidatesFromLocalStorage() {
+	const found = [];
+	try {
+		const storage = window.localStorage;
+		for (let index = 0; index < storage.length; index += 1) {
+			const key = storage.key(index);
+			if (!key || !POSTHOG_PERSISTENCE_KEY.test(key)) continue;
+			const candidate = parsePosthogPersistence(() => storage.getItem(key));
+			if (candidate) found.push(candidate);
+		}
+	} catch {}
+	return found;
+}
+function posthogCandidatesFromCookie() {
+	const found = [];
+	try {
+		for (const entry of document.cookie.split(";")) {
+			const separator = entry.indexOf("=");
+			if (separator === -1) continue;
+			const name = entry.slice(0, separator).trim();
+			if (!POSTHOG_PERSISTENCE_KEY.test(name)) continue;
+			const candidate = parsePosthogPersistence(() => decodeURIComponent(entry.slice(separator + 1)));
+			if (candidate) found.push(candidate);
+		}
+	} catch {}
+	return found;
+}
+/** One persistence entry -> candidate; malformed entries parse to nothing. */
+function parsePosthogPersistence(read) {
+	try {
+		const raw = read();
+		if (!raw) return;
+		const parsed = JSON.parse(raw);
+		if (typeof parsed.distinct_id !== "string" || parsed.distinct_id.length === 0) return;
+		const sesid = parsed.$sesid;
+		return {
+			distinctId: parsed.distinct_id,
+			lastActivity: Array.isArray(sesid) && typeof sesid[0] === "number" ? sesid[0] : 0
+		};
+	} catch {
+		return;
+	}
 }
 /** Run a probe, keeping only non-empty string results and swallowing throws. */
 function probe(read) {
@@ -96,28 +148,32 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 	}, [user, ownedAttributes]);
 	const [completedStepKeys, setCompletedStepKeys] = useState(() => /* @__PURE__ */ new Set());
 	const [completedTourKeys, setCompletedTourKeys] = useState(() => /* @__PURE__ */ new Set());
+	const [dismissedTooltipKeys, setDismissedTooltipKeys] = useState(() => /* @__PURE__ */ new Set());
 	const [activeTourState, setActiveTourState] = useState(null);
+	const [requestedTooltipKey, setRequestedTooltipKey] = useState(null);
+	const seenTooltipKeys = useRef(/* @__PURE__ */ new Set());
 	const lastNavigatedTourStep = useRef(null);
 	const storageKey = !hostedMode && resolvedSpec && user ? completedToursStorageKey(resolvedSpec.key, user.id) : null;
+	const tooltipStorageKey = !hostedMode && resolvedSpec && user ? dismissedTooltipsStorageKey(resolvedSpec.key, user.id) : null;
 	const experienceKey = activeSurvey?.key ?? activeExperience?.key ?? resolvedSpec?.key ?? null;
 	const versionId = activeSurvey?.version.id ?? activeExperience?.version.id ?? null;
 	useEffect(() => {
 		setCompletedStepKeys(/* @__PURE__ */ new Set());
 		setActiveTourState(null);
+		setRequestedTooltipKey(null);
+		seenTooltipKeys.current = /* @__PURE__ */ new Set();
 		lastNavigatedTourStep.current = null;
-		if (!storageKey) {
-			setCompletedTourKeys(/* @__PURE__ */ new Set());
-			return;
-		}
-		setCompletedTourKeys(readCompletedTours(storageKey));
+		setCompletedTourKeys(storageKey ? readStoredKeys(storageKey) : /* @__PURE__ */ new Set());
+		setDismissedTooltipKeys(tooltipStorageKey ? readStoredKeys(tooltipStorageKey) : /* @__PURE__ */ new Set());
 	}, [
 		resolvedSpec?.key,
 		storageKey,
+		tooltipStorageKey,
 		user?.id
 	]);
 	useEffect(() => {
 		if (!hostedMode || !activeExperience) return;
-		applyProgress(activeExperience.progress, setCompletedStepKeys, setCompletedTourKeys);
+		applyProgress(activeExperience.progress, setCompletedStepKeys, setCompletedTourKeys, setDismissedTooltipKeys);
 	}, [activeExperience, hostedMode]);
 	const effectiveCompletedStepKeys = useMemo(() => {
 		if (!hostedMode || !activeExperience) return completedStepKeys;
@@ -135,6 +191,14 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 		completedTourKeys,
 		hostedMode
 	]);
+	const effectiveDismissedTooltipKeys = useMemo(() => {
+		if (!hostedMode || !activeExperience) return dismissedTooltipKeys;
+		return mergeKeys(dismissedTooltipKeys, activeExperience.progress.dismissedTooltipKeys);
+	}, [
+		activeExperience,
+		dismissedTooltipKeys,
+		hostedMode
+	]);
 	useEffect(() => {
 		if (!resolvedSpec) return;
 		const tourCompletedStepKeys = (resolvedSpec.checklist?.steps ?? []).filter((step) => step.completeWhen?.tour && effectiveCompletedTourKeys.has(step.completeWhen.tour)).map((step) => step.key);
@@ -191,7 +255,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 		setCompletedTourKeys((current) => {
 			const next = new Set(current);
 			next.add(tourKey);
-			if (storageKey) writeCompletedTours(storageKey, next);
+			if (storageKey) writeStoredKeys(storageKey, next);
 			return next;
 		});
 	}, [storageKey]);
@@ -217,7 +281,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 				user: toRuntimeUser(user),
 				versionId: versionId ?? void 0
 			});
-			if (response.progress) applyProgress(response.progress, setCompletedStepKeys, setCompletedTourKeys);
+			if (response.progress) applyProgress(response.progress, setCompletedStepKeys, setCompletedTourKeys, setDismissedTooltipKeys);
 		} catch {
 			networkOk = false;
 		}
@@ -371,7 +435,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 				tourKey,
 				user: toRuntimeUser(user),
 				versionId: versionId ?? void 0
-			})).progress, setCompletedStepKeys, setCompletedTourKeys);
+			})).progress, setCompletedStepKeys, setCompletedTourKeys, setDismissedTooltipKeys);
 		} catch {}
 	}, [
 		client,
@@ -416,10 +480,106 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 		resolvedSpec,
 		user
 	]);
+	const openTooltip = useCallback(async (tooltipKey) => {
+		if (resolvedLoading || !resolvedSpec) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		if (!user) return {
+			ok: false,
+			reason: "missing-user"
+		};
+		if (!resolvedSpec.tooltips[tooltipKey]) return {
+			ok: false,
+			reason: "missing-tooltip"
+		};
+		setRequestedTooltipKey(tooltipKey);
+		return { ok: true };
+	}, [
+		resolvedLoading,
+		resolvedSpec,
+		user
+	]);
+	const dismissTooltip = useCallback(async (tooltipKey, options) => {
+		if (resolvedLoading || !resolvedSpec) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		if (!user) return {
+			ok: false,
+			reason: "missing-user"
+		};
+		if (!resolvedSpec.tooltips[tooltipKey]) return {
+			ok: false,
+			reason: "missing-tooltip"
+		};
+		const via = options?.via ?? "close";
+		setRequestedTooltipKey((current) => current === tooltipKey ? null : current);
+		setDismissedTooltipKeys((current) => {
+			const next = mergeKeys(current, [tooltipKey]);
+			if (tooltipStorageKey && next !== current) writeStoredKeys(tooltipStorageKey, next);
+			return next;
+		});
+		if (hostedMode && client && experienceKey) client.dismissTooltip({
+			experienceKey,
+			origin: currentOrigin,
+			route: currentRoute,
+			tooltipKey,
+			user: toRuntimeUser(user),
+			versionId: versionId ?? void 0,
+			via
+		}).catch(() => {});
+		return { ok: true };
+	}, [
+		client,
+		currentOrigin,
+		currentRoute,
+		experienceKey,
+		hostedMode,
+		resolvedLoading,
+		resolvedSpec,
+		tooltipStorageKey,
+		user,
+		versionId
+	]);
+	const markTooltipSeen = useCallback((tooltipKey) => {
+		if (!resolvedSpec?.tooltips[tooltipKey] || seenTooltipKeys.current.has(tooltipKey)) return;
+		seenTooltipKeys.current.add(tooltipKey);
+		if (hostedMode && client && experienceKey && user) client.recordTooltipSeen({
+			experienceKey,
+			origin: currentOrigin,
+			route: currentRoute,
+			tooltipKey,
+			user: toRuntimeUser(user),
+			versionId: versionId ?? void 0
+		}).catch(() => {});
+	}, [
+		client,
+		currentOrigin,
+		currentRoute,
+		experienceKey,
+		hostedMode,
+		resolvedSpec,
+		user,
+		versionId
+	]);
 	const startChecklistStep = useCallback(async (step) => {
 		if (step.action?.type === "startTour") return startTour(step.action.tour);
+		if (step.action?.type === "openTooltip") {
+			const tooltipKey = step.action.tooltip;
+			const destination = resolvedSpec?.tooltips[tooltipKey]?.route ?? step.route;
+			if (destination && !routeMatches(destination, currentRoute)) await navigateWithFallback(destination, navigate);
+			return openTooltip(tooltipKey);
+		}
 		await navigateToStep(step);
-	}, [navigateToStep, startTour]);
+	}, [
+		currentRoute,
+		navigate,
+		navigateToStep,
+		openTooltip,
+		resolvedSpec,
+		startTour
+	]);
 	const visibleHotspots = useMemo(() => {
 		if (!resolvedSpec || activeTour) return [];
 		return Object.entries(resolvedSpec.hotspots).filter(([, hotspot]) => routeMatches(hotspot.route, currentRoute)).filter(([, hotspot]) => hotspot.repeatable || !effectiveCompletedTourKeys.has(hotspot.action.tour)).map(([key, hotspot]) => ({
@@ -432,6 +592,29 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 		currentRoute,
 		resolvedSpec
 	]);
+	const visibleTooltips = useMemo(() => {
+		if (!resolvedSpec || activeTour) return [];
+		const requestedTooltip = requestedTooltipKey ? resolvedSpec.tooltips[requestedTooltipKey] : void 0;
+		if (requestedTooltipKey && requestedTooltip) {
+			if (!routeMatches(requestedTooltip.route, currentRoute)) return [];
+			return [{
+				key: requestedTooltipKey,
+				requested: true,
+				tooltip: requestedTooltip
+			}];
+		}
+		return Object.entries(resolvedSpec.tooltips).filter(([key, tooltip]) => routeMatches(tooltip.route, currentRoute) && !effectiveDismissedTooltipKeys.has(key)).map(([key, tooltip]) => ({
+			key,
+			requested: false,
+			tooltip
+		}));
+	}, [
+		activeTour,
+		currentRoute,
+		effectiveDismissedTooltipKeys,
+		requestedTooltipKey,
+		resolvedSpec
+	]);
 	const value = useMemo(() => ({
 		spec: resolvedSpec,
 		user: effectiveUser,
@@ -449,7 +632,12 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 		advanceTour,
 		navigateToStep,
 		startChecklistStep,
-		visibleHotspots
+		visibleHotspots,
+		dismissedTooltipKeys: effectiveDismissedTooltipKeys,
+		visibleTooltips,
+		openTooltip,
+		dismissTooltip,
+		markTooltipSeen
 	}), [
 		resolvedSpec,
 		effectiveUser,
@@ -467,7 +655,12 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, route, n
 		advanceTour,
 		navigateToStep,
 		startChecklistStep,
-		visibleHotspots
+		visibleHotspots,
+		effectiveDismissedTooltipKeys,
+		visibleTooltips,
+		openTooltip,
+		dismissTooltip,
+		markTooltipSeen
 	]);
 	return /* @__PURE__ */ jsx(SunboardContext.Provider, {
 		value,
@@ -531,8 +724,16 @@ function useSunboardBootstrap(client, options) {
 				survey: null
 			});
 		});
+		const cancelLateCapture = scheduleLateIdentityCapture({
+			client,
+			identitiesRef,
+			origin,
+			sent: identities,
+			user
+		});
 		return () => {
 			controller.abort();
+			cancelLateCapture();
 		};
 	}, [
 		client,
@@ -543,9 +744,46 @@ function useSunboardBootstrap(client, options) {
 	]);
 	return state;
 }
-function applyProgress(progress, setSteps, setTours) {
+/** Late-capture probe cadence: ~10s of 1s ticks covers slow analytics init. */
+const IDENTITY_CAPTURE_INTERVAL_MS = 1e3;
+const IDENTITY_CAPTURE_MAX_ATTEMPTS = 10;
+/**
+* Keep probing for analytics-provider ids the bootstrap missed, and push the
+* first find through `identify`. One send per bootstrap: after a successful
+* capture the poll stops; the next bootstrap (new user/session) starts fresh.
+*/
+function scheduleLateIdentityCapture(options) {
+	const { client, identitiesRef, origin, sent, user } = options;
+	let attempts = 0;
+	const timer = setInterval(() => {
+		attempts += 1;
+		if (identitiesRef.current === false) {
+			clearInterval(timer);
+			return;
+		}
+		const detected = resolveIdentities(identitiesRef.current);
+		if (!detected || !hasUnsentIdentity(detected, sent)) {
+			if (attempts >= IDENTITY_CAPTURE_MAX_ATTEMPTS) clearInterval(timer);
+			return;
+		}
+		clearInterval(timer);
+		client.identify({
+			identities: detected,
+			user: toRuntimeUser(user),
+			...origin ? { origin } : {}
+		}).catch((error) => {
+			if (isDevEnvironment()) console.warn("[sunboard] late identity capture failed", error);
+		});
+	}, IDENTITY_CAPTURE_INTERVAL_MS);
+	return () => clearInterval(timer);
+}
+function hasUnsentIdentity(detected, sent) {
+	return Object.entries(detected).some(([provider, id]) => sent?.[provider] !== id);
+}
+function applyProgress(progress, setSteps, setTours, setDismissedTooltips) {
 	setSteps((current) => mergeKeys(current, progress.completedStepKeys));
 	setTours((current) => mergeKeys(current, progress.completedTourKeys));
+	setDismissedTooltips?.((current) => mergeKeys(current, progress.dismissedTooltipKeys));
 }
 function mergeKeys(current, incoming) {
 	if (incoming.length === 0) return current;
@@ -569,6 +807,9 @@ function toRuntimeUser(user) {
 function completedToursStorageKey(specKey, userId) {
 	return `sunboard:${specKey}:${userId}:completed-tours`;
 }
+function dismissedTooltipsStorageKey(specKey, userId) {
+	return `sunboard:${specKey}:${userId}:dismissed-tooltips`;
+}
 function getBrowserRoute() {
 	if (typeof window === "undefined") return "/";
 	return `${window.location.pathname}${window.location.search}`;
@@ -577,7 +818,7 @@ function getBrowserOrigin() {
 	if (typeof window === "undefined") return;
 	return window.location.origin;
 }
-function readCompletedTours(storageKey) {
+function readStoredKeys(storageKey) {
 	if (typeof window === "undefined") return /* @__PURE__ */ new Set();
 	try {
 		const rawValue = window.localStorage.getItem(storageKey);
@@ -588,10 +829,10 @@ function readCompletedTours(storageKey) {
 		return /* @__PURE__ */ new Set();
 	}
 }
-function writeCompletedTours(storageKey, tourKeys) {
+function writeStoredKeys(storageKey, keys) {
 	if (typeof window === "undefined") return;
 	try {
-		window.localStorage.setItem(storageKey, JSON.stringify([...tourKeys].sort()));
+		window.localStorage.setItem(storageKey, JSON.stringify([...keys].sort()));
 	} catch {}
 }
 
@@ -644,7 +885,8 @@ function useSunboard() {
 //#region src/hooks/useChecklist.ts
 function actionLabelFor(step) {
 	if (step.action?.type === "startTour") return "Start";
-	if (step.action || step.route) return "Open";
+	if (step.action?.type === "openTooltip") return "Show me";
+	if (step.route) return "Open";
 }
 function interpolateOptional$1(text, user) {
 	if (!text) return void 0;
@@ -1019,6 +1261,109 @@ function Hotspot({ hotspot, hotspotKey }) {
 	}) });
 }
 
+//#endregion
+//#region src/components/SunboardTooltips.tsx
+/**
+* Renders at most one tooltip: the first visible candidate whose target
+* resolves. A candidate whose selector never appears is skipped for the rest
+* of the session (without recording a dismissal — the user rejected nothing),
+* so one stale selector can't block the tooltips behind it.
+*/
+function SunboardTooltips() {
+	const { visibleTooltips } = useSunboard();
+	const [skippedKeys, setSkippedKeys] = useState(() => /* @__PURE__ */ new Set());
+	const active = visibleTooltips.find(({ key }) => !skippedKeys.has(key)) ?? null;
+	if (!active) return null;
+	return /* @__PURE__ */ jsx(Tooltip, {
+		onTargetMissing: () => setSkippedKeys((current) => new Set(current).add(active.key)),
+		requested: active.requested,
+		tooltip: active.tooltip,
+		tooltipKey: active.key
+	}, active.key);
+}
+function Tooltip({ tooltip, tooltipKey, requested, onTargetMissing }) {
+	const { dismissTooltip, markTooltipSeen, startTour } = useSunboard();
+	const arrowRef = useRef(null);
+	const title = useInterpolated(tooltip.title);
+	const body = useInterpolated(tooltip.body);
+	const actionLabel = useInterpolated(tooltip.actionLabel) ?? "Show me how";
+	const target = useTargetElement(tooltip.target, true);
+	const { context, refs, floatingStyles, update } = useFloating({
+		placement: tooltip.placement,
+		middleware: [
+			offset(12),
+			flip(),
+			shift({ padding: 12 }),
+			arrow({ element: arrowRef })
+		],
+		whileElementsMounted: autoUpdate
+	});
+	useEffect(() => {
+		if (!target.timedOut) return;
+		onTargetMissing();
+	}, [target.timedOut]);
+	useEffect(() => {
+		if (!target.element) return;
+		refs.setReference(target.element);
+		update();
+		markTooltipSeen(tooltipKey);
+	}, [
+		markTooltipSeen,
+		refs,
+		target.element,
+		tooltipKey,
+		update
+	]);
+	if (!target.element) return null;
+	return /* @__PURE__ */ jsx(FloatingPortal, { children: /* @__PURE__ */ jsxs("section", {
+		"aria-label": title,
+		className: "sunboard-tooltip",
+		"data-sunboard-tooltip": tooltipKey,
+		"data-requested": requested,
+		ref: refs.setFloating,
+		role: "dialog",
+		style: floatingStyles,
+		children: [
+			/* @__PURE__ */ jsx(FloatingArrow, {
+				className: "sunboard-tooltip-arrow",
+				context,
+				fill: "var(--sunboard-tour-background)",
+				ref: arrowRef,
+				stroke: "var(--sunboard-tour-border)",
+				strokeWidth: 1,
+				tipRadius: 2
+			}),
+			/* @__PURE__ */ jsx("button", {
+				"aria-label": `Dismiss ${title}`,
+				className: "sunboard-tooltip-close",
+				onClick: () => void dismissTooltip(tooltipKey),
+				type: "button",
+				children: "x"
+			}),
+			/* @__PURE__ */ jsx("h2", {
+				className: "sunboard-tooltip-title",
+				children: title
+			}),
+			body ? /* @__PURE__ */ jsx("p", {
+				className: "sunboard-tooltip-body",
+				children: body
+			}) : null,
+			tooltip.action ? /* @__PURE__ */ jsx("div", {
+				className: "sunboard-tooltip-actions",
+				children: /* @__PURE__ */ jsx("button", {
+					className: "sunboard-tooltip-action",
+					onClick: () => {
+						dismissTooltip(tooltipKey, { via: "action" });
+						startTour(tooltip.action.tour);
+					},
+					type: "button",
+					children: actionLabel
+				})
+			}) : null
+		]
+	}) });
+}
+
 //#endregion
 //#region src/components/SunboardTour.tsx
 function SunboardTour() {
@@ -1428,9 +1773,45 @@ const Sunboard = Object.assign(SunboardChecklist, {
 	Checklist: SunboardChecklist,
 	Survey: SunboardSurvey,
 	Hotspots: SunboardHotspots,
+	Tooltips: SunboardTooltips,
 	Tour: SunboardTour
 });
 
 //#endregion
-export { Sunboard, SunboardChecklist, SunboardHotspots, SunboardProvider, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardSurvey, SunboardTour, useChecklist, useSunboard, useSurvey };
+//#region src/hooks/useTooltips.ts
+/**
+* Headless counterpart of `<SunboardTooltips>`: the same visibility, seen,
+* dismissal, and engagement semantics with rendering left to the host.
+*/
+function useTooltips() {
+	const { user, visibleTooltips, markTooltipSeen, dismissTooltip, startTour } = useSunboard();
+	return {
+		tooltips: useMemo(() => visibleTooltips.map(({ key, tooltip, requested }) => ({
+			key,
+			title: interpolateTokens(tooltip.title, user ?? null),
+			body: tooltip.body ? interpolateTokens(tooltip.body, user ?? null) : void 0,
+			target: tooltip.target,
+			placement: tooltip.placement,
+			hasAction: Boolean(tooltip.action),
+			actionLabel: tooltip.actionLabel ? interpolateTokens(tooltip.actionLabel, user ?? null) : void 0,
+			requested
+		})), [user, visibleTooltips]),
+		markSeen: markTooltipSeen,
+		dismiss: (key) => {
+			dismissTooltip(key);
+		},
+		engage: useCallback((key) => {
+			const entry = visibleTooltips.find((candidate) => candidate.key === key);
+			dismissTooltip(key, { via: "action" });
+			if (entry?.tooltip.action) startTour(entry.tooltip.action.tour);
+		}, [
+			dismissTooltip,
+			startTour,
+			visibleTooltips
+		])
+	};
+}
+
+//#endregion
+export { Sunboard, SunboardChecklist, SunboardHotspots, SunboardProvider, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardSurvey, SunboardTooltips, SunboardTour, useChecklist, useSunboard, useSurvey, useTooltips };
 //# sourceMappingURL=index.mjs.map