@ulu/frontend-vue 0.6.33 → 0.6.35

package/lib/plugins/tour/api.js

@@ -2,7 +2,7 @@ import { markRaw } from "vue";
 
 /**
  * @typedef {Object} TourStep
- * @property {String} [target] - The CSS selector for the target element. If omitted, step renders as a modal.
+ * @property {String|Function|HTMLElement} [target] - The CSS selector, DOM element, or function returning either, for the target element. If omitted or resolves to falsy, step renders as a modal.
  * @property {String} [title] - The title text for the step.
  * @property {String|Array|Object} [titleClass] - Class to apply to the title.
  * @property {String|Array|Object} [pagerClass] - Class to apply to the pager footer.
@@ -13,6 +13,7 @@ import { markRaw } from "vue";
  * @property {Boolean} [hideFooter] - If true, hides the default tour footer (Next/Back buttons).
  * @property {String} [placement] - Floating UI placement string (e.g. 'bottom', 'right').
  * @property {Boolean} [highlight] - If true, darkens the backdrop around the target element.
+ * @property {Boolean|Function} [skip] - If true or returns true, this step will be skipped when navigating the tour.
  * @property {Object} [modalProps] - Props to pass to the modal (if target is omitted).
  * @property {Object} [popoverProps] - Props to pass to the popover (if target is present).
  * @property {Function} [onEnter] - Async hook called before the step is rendered.
@@ -35,59 +36,116 @@ export const createApi = (state) => ({
    * @param {String|Array|Object} [tour.modalTitleClass] - Global class applied to the title of modal steps.
    * @param {String|Array|Object} [tour.popoverTitleClass] - Global class applied to the title of popover steps.
    * @param {String|Array|Object} [tour.pagerClass] - Global class applied to the pager.
+   * @param {Function} [tour.onStart] - Async hook called before the tour starts.
    * @param {Function} [tour.onStop] - Async hook called when the tour is closed/finished.
    */
   async start(tour) {
-    if (!tour?.steps?.length) return;
-    await this._runHooks(tour.steps[0]);
-    state.active = markRaw(tour);
-    state.stepIndex = 0;
+    if (state.isTransitioning) return;
+    state.isTransitioning = true;
+    try {
+      if (!tour?.steps?.length) return;
+      if (typeof tour.onStart === 'function') {
+        await tour.onStart();
+      }
+
+      let startIndex = 0;
+      while (startIndex < tour.steps.length) {
+        const step = tour.steps[startIndex];
+        const shouldSkip = typeof step.skip === 'function' ? await step.skip() : step.skip;
+        if (!shouldSkip) break;
+        startIndex++;
+      }
+
+      if (startIndex >= tour.steps.length) {
+        if (typeof tour.onStop === 'function') await tour.onStop();
+        return;
+      }
+
+      await this._runHooks(tour.steps[startIndex]);
+      state.active = markRaw(tour);
+      state.stepIndex = startIndex;
+    } finally {
+      state.isTransitioning = false;
+    }
   },
   /**
    * Advances the tour to the next step, or stops if it is the last step
    */
   async next() {
+    if (state.isTransitioning) return;
     const active = state.active;
     if (!active) return;
     
-    if (state.stepIndex < active.steps.length - 1) {
-      await this._runLeaveHook(active.steps[state.stepIndex]);
-      const nextIndex = state.stepIndex + 1;
-      await this._runHooks(active.steps[nextIndex]);
-      state.stepIndex = nextIndex;
-    } else {
-      await this.stop();
+    state.isTransitioning = true;
+    try {
+      let nextIndex = state.stepIndex + 1;
+      while (nextIndex < active.steps.length) {
+        const step = active.steps[nextIndex];
+        const shouldSkip = typeof step.skip === 'function' ? await step.skip() : step.skip;
+        if (!shouldSkip) break;
+        nextIndex++;
+      }
+
+      if (nextIndex < active.steps.length) {
+        await this._runLeaveHook(active.steps[state.stepIndex]);
+        await this._runHooks(active.steps[nextIndex]);
+        state.stepIndex = nextIndex;
+      } else {
+        await this.stop(true);
+      }
+    } finally {
+      state.isTransitioning = false;
     }
   },
   /**
    * Returns the tour to the previous step
    */
   async prev() {
+    if (state.isTransitioning) return;
     const active = state.active;
     if (!active) return;
     
-    if (state.stepIndex > 0) {
-      await this._runLeaveHook(active.steps[state.stepIndex]);
-      const prevIndex = state.stepIndex - 1;
-      await this._runHooks(active.steps[prevIndex]);
-      state.stepIndex = prevIndex;
+    state.isTransitioning = true;
+    try {
+      let prevIndex = state.stepIndex - 1;
+      while (prevIndex >= 0) {
+        const step = active.steps[prevIndex];
+        const shouldSkip = typeof step.skip === 'function' ? await step.skip() : step.skip;
+        if (!shouldSkip) break;
+        prevIndex--;
+      }
+
+      if (prevIndex >= 0) {
+        await this._runLeaveHook(active.steps[state.stepIndex]);
+        await this._runHooks(active.steps[prevIndex]);
+        state.stepIndex = prevIndex;
+      }
+    } finally {
+      state.isTransitioning = false;
     }
   },
   /**
    * Stops and closes the current tour
+   * @param {Boolean} [internalBypass=false] - Used internally to bypass transition check
    */
-  async stop() {
-    const active = state.active;
-    if (active) {
-      if (active.steps[state.stepIndex]) {
-        await this._runLeaveHook(active.steps[state.stepIndex]);
-      }
-      if (typeof active.onStop === 'function') {
-        await active.onStop();
+  async stop(internalBypass = false) {
+    if (!internalBypass && state.isTransitioning) return;
+    state.isTransitioning = true;
+    try {
+      const active = state.active;
+      if (active) {
+        if (active.steps[state.stepIndex]) {
+          await this._runLeaveHook(active.steps[state.stepIndex]);
+        }
+        if (typeof active.onStop === 'function') {
+          await active.onStop();
+        }
       }
+      state.active = null;
+      state.stepIndex = 0;
+    } finally {
+      state.isTransitioning = false;
     }
-    state.active = null;
-    state.stepIndex = 0;
   },
   /**
    * Internal method to run asynchronous enter hooks on a step

package/lib/plugins/tour/index.js

@@ -9,7 +9,8 @@ import { useTour } from './useTour.js';
 export default function install(app) {
   const state = reactive({
     active: null,
-    stepIndex: 0
+    stepIndex: 0,
+    isTransitioning: false
   });
   
   const api = createApi(state);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ulu/frontend-vue",
-  "version": "0.6.33",
+  "version": "0.6.35",
   "description": "A modular, tree-shakeable Vue 3 component library for the Ulu Frontend theming system, plus general utilities for Vue development",
   "type": "module",
   "files": [