@sunboard/react 0.1.3 → 0.2.0

package/dist/index.mjs

@@ -142,7 +142,10 @@ function isAllowedLocalPreviewUrl(url) {
 function isSunboardSpecLike(value) {
 	if (!value || typeof value !== "object") return false;
 	const candidate = value;
-	return typeof candidate.key === "string" && typeof candidate.name === "string" && typeof candidate.type === "string" && typeof candidate.checklist === "object" && Array.isArray(candidate.checklist?.steps);
+	if (typeof candidate.key !== "string" || typeof candidate.name !== "string" || typeof candidate.type !== "string") return false;
+	const hasChecklist = typeof candidate.checklist === "object" && Array.isArray(candidate.checklist?.steps);
+	const hasSurvey = typeof candidate.survey === "object" && Array.isArray(candidate.survey?.steps);
+	return hasChecklist || hasSurvey;
 }
 
 //#endregion
@@ -163,27 +166,44 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 			sdkVersion: SDK_VERSION
 		});
 	}, [apiUrl, publishableKey]);
+	const [bootstrapNonce, setBootstrapNonce] = useState(0);
+	const refreshBootstrap = useCallback(() => {
+		setBootstrapNonce((nonce) => nonce + 1);
+	}, []);
 	const bootstrap = useSunboardBootstrap(client, {
 		enabled: !specProp && preview.source !== "preview" && !preview.loading,
 		environment,
+		nonce: bootstrapNonce,
 		origin: currentOrigin,
 		route: currentRoute,
 		user
 	});
 	const activeExperience = bootstrap.experience;
-	const hostedSpec = activeExperience?.spec ?? null;
+	const activeSurvey = bootstrap.survey;
+	const hostedSpec = activeSurvey?.spec ?? activeExperience?.spec ?? null;
 	const resolvedSpec = specProp ?? preview.spec ?? hostedSpec;
 	const resolvedLoading = loadingProp ?? (preview.loading || bootstrap.loading);
 	const resolvedMode = modeProp ?? (preview.source === "preview" ? "preview" : "production");
 	const hostedMode = client !== null && !specProp && preview.source !== "preview";
+	const ownedAttributes = bootstrap.attributes;
+	const effectiveUser = useMemo(() => {
+		if (!user || !ownedAttributes || Object.keys(ownedAttributes).length === 0) return user;
+		return {
+			...user,
+			properties: {
+				...user.properties ?? {},
+				...ownedAttributes
+			}
+		};
+	}, [user, ownedAttributes]);
 	const [completedStepKeys, setCompletedStepKeys] = useState(() => /* @__PURE__ */ new Set());
 	const [completedTourKeys, setCompletedTourKeys] = useState(() => /* @__PURE__ */ new Set());
 	const [activeTourState, setActiveTourState] = useState(null);
 	const [tourError, setTourError] = useState(null);
 	const lastNavigatedTourStep = useRef(null);
 	const storageKey = !hostedMode && resolvedSpec && user ? completedToursStorageKey(resolvedSpec.key, user.id) : null;
-	const experienceKey = activeExperience?.key ?? resolvedSpec?.key ?? null;
-	const versionId = activeExperience?.version.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);
@@ -221,7 +241,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 	]);
 	useEffect(() => {
 		if (!resolvedSpec) return;
-		const tourCompletedStepKeys = resolvedSpec.checklist.steps.filter((step) => step.completeWhen?.tour && effectiveCompletedTourKeys.has(step.completeWhen.tour)).map((step) => step.key);
+		const tourCompletedStepKeys = (resolvedSpec.checklist?.steps ?? []).filter((step) => step.completeWhen?.tour && effectiveCompletedTourKeys.has(step.completeWhen.tour)).map((step) => step.key);
 		if (tourCompletedStepKeys.length === 0) return;
 		setCompletedStepKeys((current) => mergeKeys(current, tourCompletedStepKeys));
 	}, [effectiveCompletedTourKeys, resolvedSpec]);
@@ -270,8 +290,8 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 		hostedMode,
 		user?.id
 	]);
-	const totalSteps = resolvedSpec?.checklist.steps.length ?? 0;
-	const completedCount = resolvedSpec?.checklist.steps.filter((step) => effectiveCompletedStepKeys.has(step.key)).length ?? 0;
+	const totalSteps = resolvedSpec?.checklist?.steps.length ?? 0;
+	const completedCount = resolvedSpec?.checklist?.steps.filter((step) => effectiveCompletedStepKeys.has(step.key)).length ?? 0;
 	const completeTour = useCallback((tourKey) => {
 		setCompletedTourKeys((current) => {
 			const next = new Set(current);
@@ -289,7 +309,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 			ok: false,
 			reason: "missing-user"
 		};
-		const matchingStepKeys = resolvedSpec.checklist.steps.filter((step) => step.completeWhen?.event === eventName).map((step) => step.key);
+		const matchingStepKeys = (resolvedSpec.checklist?.steps ?? []).filter((step) => step.completeWhen?.event === eventName).map((step) => step.key);
 		if (matchingStepKeys.length > 0) setCompletedStepKeys((current) => mergeKeys(current, matchingStepKeys));
 		let networkOk = true;
 		if (hostedMode && client && experienceKey) try {
@@ -332,6 +352,56 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 		user,
 		versionId
 	]);
+	const submitSurvey = useCallback(async (answers) => {
+		if (resolvedLoading || !resolvedSpec) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		if (!user) return {
+			ok: false,
+			reason: "missing-user"
+		};
+		if (resolvedSpec.type !== "survey" || !resolvedSpec.survey) return {
+			ok: false,
+			reason: "not-survey"
+		};
+		if (resolvedMode === "preview") return { ok: true };
+		if (!hostedMode || !client || !experienceKey) return {
+			ok: false,
+			reason: "not-ready"
+		};
+		try {
+			await client.submitSurvey({
+				answers,
+				environment,
+				experienceKey,
+				origin: currentOrigin,
+				route: currentRoute,
+				user: toRuntimeUser(user),
+				versionId: versionId ?? void 0
+			});
+		} catch {
+			return {
+				ok: false,
+				reason: "network-error"
+			};
+		}
+		refreshBootstrap();
+		return { ok: true };
+	}, [
+		client,
+		currentOrigin,
+		currentRoute,
+		environment,
+		experienceKey,
+		hostedMode,
+		refreshBootstrap,
+		resolvedLoading,
+		resolvedMode,
+		resolvedSpec,
+		user,
+		versionId
+	]);
 	const navigateToStep = useCallback(async (step) => {
 		if (!step.route) return;
 		await navigateWithFallback(step.route, navigate);
@@ -486,7 +556,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 	}, []);
 	const value = useMemo(() => ({
 		spec: resolvedSpec,
-		user,
+		user: effectiveUser,
 		loading: resolvedLoading,
 		mode: resolvedMode,
 		route: currentRoute,
@@ -497,6 +567,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 		activeTour,
 		tourError,
 		track,
+		submitSurvey,
 		startTour,
 		dismissTour,
 		advanceTour,
@@ -506,7 +577,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 		visibleHotspots
 	}), [
 		resolvedSpec,
-		user,
+		effectiveUser,
 		resolvedLoading,
 		resolvedMode,
 		currentRoute,
@@ -517,6 +588,7 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 		activeTour,
 		tourError,
 		track,
+		submitSurvey,
 		startTour,
 		dismissTour,
 		advanceTour,
@@ -531,24 +603,30 @@ function SunboardProvider({ spec: specProp, user, loading: loadingProp, mode: mo
 	});
 }
 function useSunboardBootstrap(client, options) {
-	const { enabled, environment, origin, route, user } = options;
+	const { enabled, environment, nonce, origin, route, user } = options;
 	const [state, setState] = useState({
+		attributes: null,
 		experience: null,
-		loading: false
+		loading: false,
+		survey: null
 	});
 	const warnedSdkAdvisory = useRef(false);
 	useEffect(() => {
-		if (!client || !enabled || !user?.id) {
+		if (!client || !enabled || !user?.id || isPreviewPage()) {
 			setState({
+				attributes: null,
 				experience: null,
-				loading: false
+				loading: false,
+				survey: null
 			});
 			return;
 		}
 		const controller = new AbortController();
 		setState({
+			attributes: null,
 			experience: null,
-			loading: true
+			loading: true,
+			survey: null
 		});
 		client.bootstrap({
 			environment,
@@ -557,21 +635,25 @@ function useSunboardBootstrap(client, options) {
 			user: toRuntimeUser(user)
 		}).then((response) => {
 			if (controller.signal.aborted) return;
-			if (response.experiences.length === 0 && isDevEnvironment()) console.warn(`[sunboard] bootstrap returned no active experiences for route "${route}" in environment "${environment}". Check the dashboard for an enabled deployment whose trigger.route matches.`);
+			if (response.experiences.length === 0 && !response.survey && isDevEnvironment()) console.warn(`[sunboard] bootstrap returned no active experiences for route "${route}" in environment "${environment}". Check the dashboard for an enabled deployment whose trigger.route matches.`);
 			if (response.sdkAdvisory && isDevEnvironment() && !warnedSdkAdvisory.current) {
 				warnedSdkAdvisory.current = true;
 				console.warn(`[sunboard] ${response.sdkAdvisory.message}`);
 			}
 			setState({
+				attributes: response.attributes ?? null,
 				experience: response.experiences[0] ?? null,
-				loading: false
+				loading: false,
+				survey: response.survey ?? null
 			});
 		}).catch((error) => {
 			if (controller.signal.aborted) return;
 			if (isDevEnvironment()) console.warn("[sunboard] bootstrap failed", error);
 			setState({
+				attributes: null,
 				experience: null,
-				loading: false
+				loading: false,
+				survey: null
 			});
 		});
 		return () => {
@@ -581,6 +663,7 @@ function useSunboardBootstrap(client, options) {
 		client,
 		enabled,
 		environment,
+		nonce,
 		origin,
 		user?.id
 	]);
@@ -601,6 +684,10 @@ function isDevEnvironment() {
 	if (typeof process === "undefined" || !process.env) return false;
 	return process.env.NODE_ENV !== "production";
 }
+function isPreviewPage() {
+	if (typeof window === "undefined") return false;
+	return new URLSearchParams(window.location.search).get("sunboard_preview") === "1";
+}
 function toRuntimeUser(user) {
 	return {
 		email: user.email ?? void 0,
@@ -690,7 +777,7 @@ function actionLabelFor(step) {
 	if (step.action?.type === "startTour") return "Start";
 	if (step.action || step.route) return "Open";
 }
-function interpolateOptional(text, user) {
+function interpolateOptional$1(text, user) {
 	if (!text) return void 0;
 	return interpolateTokens(text, user) || void 0;
 }
@@ -712,17 +799,17 @@ function useChecklist() {
 	const sawIncompleteFirst = observationRef.current?.sawIncomplete ?? false;
 	const dismissed = dismissedKey !== null && dismissedKey === observationKey;
 	const rawSteps = useMemo(() => spec?.checklist?.steps ?? [], [spec]);
-	const title = useMemo(() => interpolateOptional(spec?.title, user ?? null), [spec?.title, user]);
-	const subtitle = useMemo(() => interpolateOptional(spec?.subtitle, user ?? null), [spec?.subtitle, user]);
+	const title = useMemo(() => interpolateOptional$1(spec?.title, user ?? null), [spec?.title, user]);
+	const subtitle = useMemo(() => interpolateOptional$1(spec?.subtitle, user ?? null), [spec?.subtitle, user]);
 	const completion = useMemo(() => {
 		const raw = spec?.completion;
 		if (!raw) return void 0;
-		const interpolatedTitle = interpolateOptional(raw.title, user ?? null);
+		const interpolatedTitle = interpolateOptional$1(raw.title, user ?? null);
 		if (!interpolatedTitle) return void 0;
 		return {
 			title: interpolatedTitle,
-			subtitle: interpolateOptional(raw.subtitle, user ?? null),
-			message: interpolateOptional(raw.message, user ?? null),
+			subtitle: interpolateOptional$1(raw.subtitle, user ?? null),
+			message: interpolateOptional$1(raw.message, user ?? null),
 			dismissAfterMs: raw.dismissAfterMs
 		};
 	}, [spec?.completion, user]);
@@ -768,6 +855,140 @@ function useChecklist() {
 	};
 }
 
+//#endregion
+//#region src/hooks/useSurvey.ts
+function interpolateOptional(text, user) {
+	if (!text) return void 0;
+	return interpolateTokens(text, user) || void 0;
+}
+function answered(value) {
+	if (value === void 0 || value === null) return false;
+	if (typeof value === "string") return value.trim().length > 0;
+	if (Array.isArray(value)) return value.length > 0;
+	return true;
+}
+function useSurvey() {
+	const { spec, user, loading, submitSurvey } = useSunboard();
+	const [answers, setAnswers] = useState({});
+	const [submitting, setSubmitting] = useState(false);
+	const [submitted, setSubmitted] = useState(false);
+	const [error, setError] = useState(null);
+	const [stepIndex, setStepIndex] = useState(0);
+	const isSurvey = Boolean(spec && spec.type === "survey" && spec.survey);
+	const ready = !loading && !!user && isSurvey;
+	const title = useMemo(() => interpolateOptional(spec?.title, user ?? null), [spec?.title, user]);
+	const subtitle = useMemo(() => interpolateOptional(spec?.subtitle, user ?? null), [spec?.subtitle, user]);
+	const steps = useMemo(() => {
+		return (spec?.survey?.steps ?? []).map((step) => ({
+			title: interpolateOptional(step.title, user ?? null),
+			subtitle: interpolateOptional(step.subtitle, user ?? null),
+			questions: step.questions.map((question) => ({
+				key: question.key,
+				prompt: interpolateTokens(question.prompt, user ?? null),
+				type: question.type,
+				required: question.required,
+				options: (question.options ?? []).map((option) => ({
+					value: option.value,
+					label: interpolateTokens(option.label, user ?? null)
+				}))
+			}))
+		}));
+	}, [spec?.survey, user]);
+	const questions = useMemo(() => steps.flatMap((step) => step.questions), [steps]);
+	const signature = questions.map((question) => question.key).join("|");
+	const signatureRef = useRef(signature);
+	if (signatureRef.current !== signature) {
+		signatureRef.current = signature;
+		if (stepIndex !== 0) setStepIndex(0);
+	}
+	const totalSteps = steps.length;
+	const safeIndex = totalSteps > 0 ? Math.min(stepIndex, totalSteps - 1) : 0;
+	const currentStep = steps[safeIndex];
+	const setAnswer = useCallback((key, value) => {
+		setAnswers((current) => ({
+			...current,
+			[key]: value
+		}));
+	}, []);
+	const toggleAnswer = useCallback((key, value) => {
+		setAnswers((current) => {
+			const existing = Array.isArray(current[key]) ? current[key] : [];
+			const next$1 = existing.includes(value) ? existing.filter((item) => item !== value) : [...existing, value];
+			return {
+				...current,
+				[key]: next$1
+			};
+		});
+	}, []);
+	const isAnswered = useCallback((key) => answered(answers[key]), [answers]);
+	const canSubmit = useMemo(() => {
+		if (!ready || submitting) return false;
+		return questions.filter((question) => question.required).every((question) => answered(answers[question.key]));
+	}, [
+		answers,
+		questions,
+		ready,
+		submitting
+	]);
+	const canAdvance = useMemo(() => {
+		if (!currentStep) return false;
+		return currentStep.questions.filter((question) => question.required).every((question) => answered(answers[question.key]));
+	}, [answers, currentStep]);
+	const submit = useCallback(async () => {
+		if (!canSubmit) return;
+		setSubmitting(true);
+		setError(null);
+		const result = await submitSurvey(answers);
+		setSubmitting(false);
+		if (result.ok) {
+			setSubmitted(true);
+			return;
+		}
+		setError(result.reason === "network-error" ? "Something went wrong. Please try again." : "Survey is not ready.");
+	}, [
+		answers,
+		canSubmit,
+		submitSurvey
+	]);
+	const isLastStep = totalSteps === 0 || safeIndex >= totalSteps - 1;
+	const isFirstStep = safeIndex === 0;
+	const next = useCallback(() => {
+		if (isLastStep) submit();
+		else setStepIndex(safeIndex + 1);
+	}, [
+		isLastStep,
+		safeIndex,
+		submit
+	]);
+	const back = useCallback(() => {
+		setStepIndex((current) => Math.max(0, current - 1));
+	}, []);
+	return {
+		visible: ready && !submitted,
+		title,
+		subtitle,
+		questions,
+		steps,
+		stepIndex: safeIndex,
+		totalSteps,
+		currentStep,
+		progress: totalSteps > 0 ? (safeIndex + 1) / totalSteps * 100 : 0,
+		isFirstStep,
+		isLastStep,
+		canAdvance,
+		next,
+		back,
+		answers,
+		setAnswer,
+		toggleAnswer,
+		isAnswered,
+		canSubmit,
+		submitting,
+		error,
+		submit
+	};
+}
+
 //#endregion
 //#region src/icons/index.tsx
 const CheckIcon = () => {
@@ -1254,12 +1475,130 @@ function SunboardChecklist() {
 		]
 	});
 }
+function SunboardSurvey() {
+	const { visible, title, subtitle, currentStep, stepIndex, totalSteps, progress, isFirstStep, isLastStep, canAdvance, canSubmit, next, back, answers, setAnswer, toggleAnswer, submitting, error } = useSurvey();
+	if (!visible || !title || !currentStep) return null;
+	const showProgress = totalSteps > 1;
+	return /* @__PURE__ */ jsx("div", {
+		className: "sunboard-survey-overlay",
+		children: /* @__PURE__ */ jsxs("section", {
+			className: "sunboard-survey-card",
+			role: "dialog",
+			"aria-modal": "true",
+			"aria-label": `${title} survey`,
+			children: [
+				/* @__PURE__ */ jsxs("div", {
+					className: "sunboard-survey-head",
+					children: [subtitle ? /* @__PURE__ */ jsx("p", {
+						className: "sunboard-eyebrow",
+						children: subtitle
+					}) : null, /* @__PURE__ */ jsx("h2", {
+						className: "sunboard-title",
+						children: title
+					})]
+				}),
+				showProgress ? /* @__PURE__ */ jsxs("div", {
+					className: "sunboard-survey-progress-row",
+					children: [/* @__PURE__ */ jsxs("p", {
+						className: "sunboard-survey-stepcount",
+						children: [
+							"Step ",
+							stepIndex + 1,
+							" of ",
+							totalSteps
+						]
+					}), /* @__PURE__ */ jsx("div", {
+						className: "sunboard-progress",
+						role: "progressbar",
+						"aria-label": `${title} progress`,
+						"aria-valuemin": 1,
+						"aria-valuemax": totalSteps,
+						"aria-valuenow": stepIndex + 1,
+						children: /* @__PURE__ */ jsx("div", {
+							className: "sunboard-progress-fill",
+							style: { width: `${progress}%` }
+						})
+					})]
+				}) : null,
+				/* @__PURE__ */ jsxs("form", {
+					className: "sunboard-survey-form",
+					onSubmit: (event) => {
+						event.preventDefault();
+						next();
+					},
+					children: [
+						currentStep.title ? /* @__PURE__ */ jsx("p", {
+							className: "sunboard-survey-step-title",
+							children: currentStep.title
+						}) : null,
+						/* @__PURE__ */ jsx("ol", {
+							className: "sunboard-survey-questions",
+							children: currentStep.questions.map((question) => /* @__PURE__ */ jsxs("li", {
+								className: "sunboard-survey-question",
+								children: [/* @__PURE__ */ jsxs("p", {
+									className: "sunboard-survey-prompt",
+									children: [question.prompt, question.required ? /* @__PURE__ */ jsx("span", {
+										"aria-hidden": "true",
+										className: "sunboard-survey-required",
+										children: " *"
+									}) : null]
+								}), question.type === "text" ? /* @__PURE__ */ jsx("input", {
+									className: "sunboard-survey-input",
+									type: "text",
+									value: typeof answers[question.key] === "string" ? answers[question.key] : "",
+									required: question.required,
+									"aria-label": question.prompt,
+									onChange: (event) => setAnswer(question.key, event.target.value)
+								}) : /* @__PURE__ */ jsx("div", {
+									className: "sunboard-survey-options",
+									role: "group",
+									"aria-label": question.prompt,
+									children: question.options.map((option) => {
+										const selected = question.type === "multi-select" ? Array.isArray(answers[question.key]) && answers[question.key].includes(option.value) : answers[question.key] === option.value;
+										return /* @__PURE__ */ jsx("button", {
+											className: "sunboard-survey-option",
+											type: "button",
+											"aria-pressed": selected,
+											"data-selected": selected ? "true" : "false",
+											onClick: () => question.type === "multi-select" ? toggleAnswer(question.key, option.value) : setAnswer(question.key, option.value),
+											children: option.label
+										}, option.value);
+									})
+								})]
+							}, question.key))
+						}),
+						error ? /* @__PURE__ */ jsx("p", {
+							className: "sunboard-survey-error",
+							role: "alert",
+							children: error
+						}) : null,
+						/* @__PURE__ */ jsxs("div", {
+							className: "sunboard-survey-nav",
+							children: [!isFirstStep ? /* @__PURE__ */ jsx("button", {
+								className: "sunboard-survey-back",
+								type: "button",
+								onClick: back,
+								children: "Back"
+							}) : /* @__PURE__ */ jsx("span", {}), /* @__PURE__ */ jsx("button", {
+								className: "sunboard-survey-submit",
+								type: "submit",
+								disabled: isLastStep ? !canSubmit : !canAdvance,
+								children: isLastStep ? submitting ? "Submitting…" : "Finish" : "Continue"
+							})]
+						})
+					]
+				})
+			]
+		})
+	});
+}
 const Sunboard = Object.assign(SunboardChecklist, {
 	Checklist: SunboardChecklist,
+	Survey: SunboardSurvey,
 	Hotspots: SunboardHotspots,
 	Tour: SunboardTour
 });
 
 //#endregion
-export { Sunboard, SunboardChecklist, SunboardHotspots, SunboardProvider, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardTour, useChecklist, useSunboard, useSunboardPreviewSpec };
+export { Sunboard, SunboardChecklist, SunboardHotspots, SunboardProvider, SunboardRuntimeApiError, SunboardRuntimeClient, SunboardSurvey, SunboardTour, useChecklist, useSunboard, useSunboardPreviewSpec, useSurvey };
 //# sourceMappingURL=index.mjs.map