@retoo/borda 0.0.2 → 0.1.1

package/dist/borda.umd.js

@@ -5384,6 +5384,8 @@ createHTML: (html) => {
 		BordaEvent["ON_TOUR_NEXT"] = "tour:next";
 		/** Fired when navigating to the previous step. */
 		BordaEvent["ON_TOUR_PREV"] = "tour:prev";
+		/** Fired when a step's target fails to resolve to a DOM element, just before the tour closes. */
+		BordaEvent["ON_TOUR_ERROR"] = "tour:error";
 		/** Fired when the ArrowRight key is pressed during an active tour. */
 		BordaEvent["ON_KEYBOARD_NEXT"] = "keyboard:next";
 		/** Fired when the ArrowLeft key is pressed during an active tour. */
@@ -6186,6 +6188,14 @@ createHTML: (html) => {
 	}
 	//#endregion
 	//#region src/entities/step/model/lib/resolveBordaStepTarget.ts
+	/** Runs `querySelector`, treating a malformed selector as "no match" instead of throwing. */
+	function queryTarget(selector) {
+		try {
+			return document.querySelector(selector);
+		} catch {
+			return null;
+		}
+	}
 	function buildSelector(query) {
 		const parts = [];
 		if (query.id) parts.push(`#${CSS.escape(query.id)}`);
@@ -6209,10 +6219,10 @@ createHTML: (html) => {
 	function resolveBordaStepTarget(target) {
 		if (!target) return null;
 		if (target instanceof HTMLElement) return target;
-		if (typeof target === "string") return document.querySelector(target);
+		if (typeof target === "string") return queryTarget(target);
 		const selector = buildSelector(target);
 		if (!selector) return null;
-		return document.querySelector(selector);
+		return queryTarget(selector);
 	}
 	//#endregion
 	//#region src/app/entrypoint/modules/borda-controller/lib/useBordaController.svelte.ts
@@ -6231,6 +6241,23 @@ createHTML: (html) => {
 		const hasNextStep = /* @__PURE__ */ user_derived(() => !get(isLastStep));
 		const hasPrevStep = /* @__PURE__ */ user_derived(() => get(stepIndex) > 0);
 		const tourConfig = /* @__PURE__ */ user_derived(() => config.getConfig().tour);
+		/**
+		* Verifies the current step's target resolved to a DOM element.
+		*
+		* Emits {@link BordaEvent.ON_TOUR_ERROR} followed by {@link BordaEvent.ON_TOUR_CLOSE}
+		* when it didn't, instead of leaving the widget rendering nothing for a step
+		* the user can't see or dismiss.
+		*
+		* @returns `true` when there is no step, or its target resolved; `false` when the tour was closed due to an error.
+		*/
+		function checkCurrentTarget() {
+			if (!get(step) || get(currentTarget)) return true;
+			const error = new BordaError(`Borda: target for step ${get(currentStep)} did not resolve to an element.`);
+			console.error(error);
+			eventEmitter.emit(BordaEvent.ON_TOUR_ERROR, error);
+			eventEmitter.emit(BordaEvent.ON_TOUR_CLOSE);
+			return false;
+		}
 		function apply() {
 			set(stepIndex, get(tourConfig)?.startStep ?? 0, true);
 			get(tourConfig)?.onStart?.();
@@ -6244,6 +6271,7 @@ createHTML: (html) => {
 			await entering?.prepareElement?.();
 			entering?.onBeforeHighlighted?.();
 			set(stepIndex, index, true);
+			if (!checkCurrentTarget()) return;
 			entering?.onHighlighted?.();
 			eventEmitter.emit(BordaEvent.ON_TOUR_STEP_CHANGE, get(currentStep));
 		}
@@ -6335,7 +6363,8 @@ createHTML: (html) => {
 				prev,
 				next,
 				finish
-			}
+			},
+			checkCurrentTarget
 		};
 	}
 	//#endregion
@@ -8416,11 +8445,9 @@ createHTML: (html) => {
 		const padding = /* @__PURE__ */ user_derived(getPadding);
 		const autoPlacement = /* @__PURE__ */ user_derived(getAutoPlacement);
 		const arrowSide = /* @__PURE__ */ user_derived(getArrowSide);
-		user_effect(() => {
+		/** Reads the live target/tooltip rects and writes the resolved position into state. */
+		function recompute() {
 			if (!get(target) || !get(tooltip)) return;
-			/** Re-run on scroll so auto-flip/shift recompute against the live viewport. */
-			scroll.x;
-			scroll.y;
 			const layout = useTooltipLayout({
 				target: get(target),
 				tooltip: get(tooltip),
@@ -8439,6 +8466,19 @@ createHTML: (html) => {
 			set(left, layout.position.left, true);
 			set(effectivePlacement, layout.placement, true);
 			set(arrowOffset, layout.arrowOffset, true);
+		}
+		user_effect(() => {
+			if (!get(tooltip)) return;
+			/** Re-run when the tooltip's own size changes (e.g. an image finishes loading). */
+			const observer = new ResizeObserver(recompute);
+			observer.observe(get(tooltip));
+			return () => observer.disconnect();
+		});
+		user_effect(() => {
+			/** Re-run on scroll so auto-flip/shift recompute against the live viewport. */
+			scroll.x;
+			scroll.y;
+			recompute();
 		});
 		return {
 			get top() {
@@ -8923,9 +8963,8 @@ createHTML: (html) => {
 			getDuration: () => $$props.animation.overlay.transitionDuration
 		});
 		useFocusTrap({ getContainer: () => get(bordaContainer)?.getElements()?.root ?? null });
-		const size = /* @__PURE__ */ user_derived(() => $$props.config.size);
-		const shape = /* @__PURE__ */ user_derived(() => $$props.config.shape);
 		const rootClasses = /* @__PURE__ */ user_derived(() => ["rb"]);
+		/** Container chrome isn't per-step content, so it always tracks the live config. */
 		const containerProps = /* @__PURE__ */ user_derived(() => ({
 			...$$props.config.container,
 			customClasses: {
@@ -8933,13 +8972,6 @@ createHTML: (html) => {
 				root: [$$props.config.container?.customClasses?.root, containerAnimator.classes]
 			}
 		}));
-		const tourOverlayProps = /* @__PURE__ */ user_derived(() => $$props.config.tourOverlay);
-		const tourTooltipProps = /* @__PURE__ */ user_derived(() => $$props.config.tourTooltip);
-		const tourImageProps = /* @__PURE__ */ user_derived(() => $$props.config.tourImage);
-		const tourButtonsProps = /* @__PURE__ */ user_derived(() => $$props.config.tourButtons);
-		const tourProgressProps = /* @__PURE__ */ user_derived(() => $$props.config.tourProgress);
-		const tourSkipProps = /* @__PURE__ */ user_derived(() => $$props.config.tourSkip);
-		const closeButtonProps = /* @__PURE__ */ user_derived(() => $$props.config.closeButton);
 		const tourTooltipAnimation = /* @__PURE__ */ user_derived(() => $$props.animation.isEnabled ? $$props.animation.tooltip : false);
 		const isAnimated = /* @__PURE__ */ user_derived(() => $$props.animation.isEnabled);
 		const hasGlide = /* @__PURE__ */ user_derived(() => $$props.animation.tooltip.transition === BordaTooltipTransition.GLIDE);
@@ -8947,7 +8979,22 @@ createHTML: (html) => {
 		const isStepSettling = /* @__PURE__ */ user_derived(() => $$props.scroll.isScrolling || overlayTransition.isActive);
 		/** In fade mode, hide the tooltip while the step settles, then fade it in at the new position. */
 		const isHidden = /* @__PURE__ */ user_derived(() => !get(hasGlide) && get(isAnimated) && get(isStepSettling) && !get(isShownOnScroll));
-		const step = /* @__PURE__ */ user_derived(() => $$props.controller.step);
+		/** Seeded once from the initial step so the first render has content; kept in sync by the effect below. */
+		let displayed = /* @__PURE__ */ state(proxy({
+			step: untrack(() => $$props.controller.step),
+			target: untrack(() => $$props.controller.currentTarget),
+			currentStep: untrack(() => $$props.controller.currentStep),
+			config: untrack(() => $$props.config)
+		}));
+		const size = /* @__PURE__ */ user_derived(() => get(displayed).config.size);
+		const shape = /* @__PURE__ */ user_derived(() => get(displayed).config.shape);
+		const tourOverlayProps = /* @__PURE__ */ user_derived(() => get(displayed).config.tourOverlay);
+		const tourTooltipProps = /* @__PURE__ */ user_derived(() => get(displayed).config.tourTooltip);
+		const tourImageProps = /* @__PURE__ */ user_derived(() => get(displayed).config.tourImage);
+		const tourButtonsProps = /* @__PURE__ */ user_derived(() => get(displayed).config.tourButtons);
+		const tourProgressProps = /* @__PURE__ */ user_derived(() => get(displayed).config.tourProgress);
+		const tourSkipProps = /* @__PURE__ */ user_derived(() => get(displayed).config.tourSkip);
+		const closeButtonProps = /* @__PURE__ */ user_derived(() => get(displayed).config.closeButton);
 		const tourComponents = /* @__PURE__ */ user_derived(() => {
 			const components = get(bordaTour)?.getComponents();
 			return {
@@ -8979,6 +9026,34 @@ createHTML: (html) => {
 			if ($$props.config.visibility?.isHidden) return;
 			$$props.scroll.scrollTo($$props.controller.currentTarget);
 		});
+		user_effect(() => {
+			if (!get(isHidden)) {
+				set(displayed, {
+					step: $$props.controller.step,
+					target: $$props.controller.currentTarget,
+					currentStep: $$props.controller.currentStep,
+					config: $$props.config
+				}, true);
+				return;
+			}
+			/**
+			* `step`/`currentTarget`/`currentStep`/`config` (incl. per-step overrides
+			* like `tourProgress`) are live and swap the instant the step index
+			* changes, so binding the tooltip/overlay to them directly would render
+			* the new step's content immediately — visible for a frame before the
+			* fade-out even starts. Keep showing the outgoing step's snapshot while
+			* it fades out, and only swap once it's actually invisible.
+			*/
+			const timeoutId = setTimeout(() => {
+				set(displayed, {
+					step: $$props.controller.step,
+					target: $$props.controller.currentTarget,
+					currentStep: $$props.controller.currentStep,
+					config: $$props.config
+				}, true);
+			}, $$props.animation.tooltip.exitDuration);
+			return () => clearTimeout(timeoutId);
+		});
 		onMount(() => {
 			$$props.mount();
 		});
@@ -8998,7 +9073,7 @@ createHTML: (html) => {
 					var consequent = ($$anchor) => {
 						bind_this(BordaTourOverlay($$anchor, spread_props({
 							get targetElement() {
-								return $$props.controller.currentTarget;
+								return get(displayed).target;
 							},
 							get isAnimated() {
 								return get(isAnimated);
@@ -9012,13 +9087,13 @@ createHTML: (html) => {
 					var consequent_1 = ($$anchor) => {
 						bind_this(BordaTour($$anchor, {
 							get step() {
-								return get(step);
+								return get(displayed).step;
 							},
 							get currentTarget() {
-								return $$props.controller.currentTarget;
+								return get(displayed).target;
 							},
 							get currentStep() {
-								return $$props.controller.currentStep;
+								return get(displayed).currentStep;
 							},
 							get totalSteps() {
 								return $$props.controller.totalSteps;
@@ -9082,7 +9157,7 @@ createHTML: (html) => {
 					append($$anchor, fragment_1);
 				};
 				if_block(node_1, ($$render) => {
-					if ($$props.controller.currentTarget && get(step)) $$render(consequent_2);
+					if ($$props.controller.currentTarget && $$props.controller.step) $$render(consequent_2);
 				});
 				append($$anchor, fragment);
 			},
@@ -9213,6 +9288,11 @@ createHTML: (html) => {
 								config.getConfig().tour?.onClose?.();
 								await unmount$1(instance);
 							});
+							eventEmitter.once(BordaEvent.ON_TOUR_ERROR, (error) => {
+								config.getConfig().tour?.onError?.(error);
+							});
+							/** Validate the initial step now that ON_TOUR_ERROR/ON_TOUR_CLOSE listeners above are registered. */
+							controller.checkCurrentTarget();
 							resolve(instance);
 						},
 						unmount: () => {
@@ -9255,7 +9335,7 @@ createHTML: (html) => {
 		}
 		return {
 			NAME: "@retoo/borda",
-			VERSION: "0.0.2",
+			VERSION: "0.1.1",
 			mount: mount$1,
 			unmount: unmount$1,
 			highlight: useBordaHighlight(mount$1).highlight

package/dist/index.d.ts

@@ -16,6 +16,8 @@ declare enum BordaEvent {
     ON_TOUR_NEXT = "tour:next",
     /** Fired when navigating to the previous step. */
     ON_TOUR_PREV = "tour:prev",
+    /** Fired when a step's target fails to resolve to a DOM element, just before the tour closes. */
+    ON_TOUR_ERROR = "tour:error",
     /** Fired when the ArrowRight key is pressed during an active tour. */
     ON_KEYBOARD_NEXT = "keyboard:next",
     /** Fired when the ArrowLeft key is pressed during an active tour. */
@@ -39,11 +41,11 @@ type BordaEventMap<T = unknown> = Map<BordaEvent, Set<BordaEventHandler<T>>>;
 /** Pub/sub event bus for communication between borda components. */
 interface BordaEventEmitter {
     /** Subscribe a handler to an event. */
-    on(eventName: BordaEvent, handler: BordaEventHandler): void;
+    on<T = unknown>(eventName: BordaEvent, handler: BordaEventHandler<T>): void;
     /** Subscribe a handler to an event; auto-unsubscribes after first call. */
-    once(eventName: BordaEvent, handler: BordaEventHandler): void;
+    once<T = unknown>(eventName: BordaEvent, handler: BordaEventHandler<T>): void;
     /** Unsubscribe a specific handler from an event. */
-    off(eventName: BordaEvent, handler: BordaEventHandler): void;
+    off<T = unknown>(eventName: BordaEvent, handler: BordaEventHandler<T>): void;
     /** Emit an event, calling all subscribed handlers with optional data. */
     emit<T>(eventName: BordaEvent, data?: T): void;
     /** Remove all handlers for a specific event. */
@@ -888,6 +890,8 @@ interface UseBordaControllerReturns {
     apply: () => void;
     /** Reactive public API for controlling the tour. */
     api: BordaControllerApi;
+    /** Verifies the current step's target resolved; closes the tour and returns `false` if not. */
+    checkCurrentTarget: () => boolean;
 }
 
 /**
@@ -1226,6 +1230,17 @@ interface BordaTourProgressRef {
     getElements: () => BordaTourProgressElements;
 }
 
+/**
+ * Base error class for all borda runtime errors.
+ *
+ * Using a named subclass makes borda errors easy to identify
+ * in stack traces and `instanceof` checks.
+ */
+declare class BordaError extends Error {
+    readonly name = "BordaError";
+    constructor(message: string);
+}
+
 /** Props for the BordaTour step composition component. */
 interface BordaTourProps {
     step: BordaStep;
@@ -1235,9 +1250,7 @@ interface BordaTourProps {
     size: ComponentSize;
     shape: ComponentShape;
     isSkipChecked: boolean;
-    /** Hides the tooltip (fade transition) while scrolling/transitioning between steps. */
     isHidden: boolean;
-    /** Enables position gliding of the tooltip between steps (glide transition). */
     hasGlide: boolean;
     tourTooltipAnimation: BordaTourTooltipAnimation | false;
     tourTooltipProps: Partial<BordaTourTooltipProps>;
@@ -1280,6 +1293,8 @@ interface BordaTourConfig {
     onFinish: () => void;
     /** Called when the tour is dismissed before completion (close button, backdrop or Escape), before the unmount animation. */
     onClose: () => void;
+    /** Called when a step's target fails to resolve to a DOM element, just before the tour closes. */
+    onError: (error: BordaError) => void;
     /**
      * Enable keyboard navigation: ArrowRight/ArrowLeft for next/prev, Escape to close.
      * Defaults to `true`. Set to `false` to disable all keyboard handling.

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@retoo/borda",
-	"version": "0.0.2",
+	"version": "0.1.1",
 	"description": "Embeddable onboarding widget for any website. Framework-agnostic, SSR-safe.",
 	"keywords": [
 		"embeddable",