@retoo/borda 0.0.1 → 0.1.0

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
@@ -9213,6 +9242,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 +9289,7 @@ createHTML: (html) => {
 		}
 		return {
 			NAME: "@retoo/borda",
-			VERSION: "0.0.1",
+			VERSION: "0.1.0",
 			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.1",
+	"version": "0.1.0",
 	"description": "Embeddable onboarding widget for any website. Framework-agnostic, SSR-safe.",
 	"keywords": [
 		"embeddable",