@syntrologie/adapt-overlays 2.4.1 → 2.5.1

package/dist/executors/tour.js

@@ -0,0 +1,335 @@
+/**
+ * Tour Executor
+ *
+ * Orchestrates sequential tour steps with cross-page state persistence.
+ * Tours can span multiple pages and resume after navigation.
+ *
+ * Each step contains an inner action (modal, tooltip) that gets executed.
+ * The tour listens for CTA click events to advance to the next step.
+ */
+/** Storage key for active tour state */
+const ACTIVE_TOUR_KEY = 'syntro_active_tour';
+/** Track active tour executors to prevent duplicates */
+const activeTours = new Map();
+/**
+ * Get active tour state from localStorage
+ */
+function getTourState(tourId) {
+    try {
+        const data = localStorage.getItem(ACTIVE_TOUR_KEY);
+        if (!data)
+            return null;
+        const state = JSON.parse(data);
+        // Only return if it matches the requested tour
+        if (state.tourId !== tourId)
+            return null;
+        return state;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Save tour state to localStorage
+ */
+function saveTourState(state) {
+    try {
+        localStorage.setItem(ACTIVE_TOUR_KEY, JSON.stringify(state));
+    }
+    catch {
+        // Storage may be full or unavailable
+    }
+}
+/**
+ * Clear tour state from localStorage
+ */
+function clearTourState() {
+    try {
+        localStorage.removeItem(ACTIVE_TOUR_KEY);
+    }
+    catch {
+        // Ignore errors
+    }
+}
+/**
+ * Get current route/path
+ */
+function getCurrentRoute() {
+    return window.location.pathname;
+}
+/**
+ * Check if a step matches the current route
+ */
+function stepMatchesRoute(step) {
+    if (!step.route)
+        return true;
+    const currentRoute = getCurrentRoute();
+    // Simple pattern matching - step.route can be exact path or glob pattern
+    if (step.route.includes('*')) {
+        const pattern = new RegExp(`^${step.route.replace(/\*/g, '.*')}$`);
+        return pattern.test(currentRoute);
+    }
+    return currentRoute === step.route;
+}
+/**
+ * Execute a tour action
+ *
+ * Tours orchestrate a sequence of steps, persisting state to localStorage
+ * to support cross-page navigation. Each step contains an action to execute
+ * and optionally defines transitions based on action events.
+ */
+export const executeTour = async (action, context) => {
+    const { tourId, steps, startStep, autoStart = true } = action;
+    if (steps.length === 0) {
+        throw new Error(`Tour "${tourId}" has no steps`);
+    }
+    // Self-guard: if this tour is already running, return no-op
+    // This prevents duplicate modals when applyBatch is called multiple times
+    if (activeTours.has(tourId)) {
+        return {
+            cleanup: async () => {
+                // Delegate to the original tour's cleanup
+                const existing = activeTours.get(tourId);
+                if (existing) {
+                    await existing.cleanup();
+                }
+            },
+        };
+    }
+    // Check if we can execute inner actions
+    if (!context.applyAction) {
+        throw new Error('Tour executor requires applyAction in context');
+    }
+    // Get or initialize tour state
+    let state = getTourState(tourId);
+    const isResumingTour = !!state;
+    // If not resuming and autoStart is false, don't start the tour
+    if (!isResumingTour && !autoStart) {
+        return {
+            cleanup: () => { },
+        };
+    }
+    if (!state) {
+        state = {
+            tourId,
+            currentStepId: startStep || steps[0].id,
+            startedAt: Date.now(),
+        };
+        saveTourState(state);
+    }
+    // Find the current step
+    let currentStepIndex = steps.findIndex((s) => s.id === state.currentStepId);
+    if (currentStepIndex === -1) {
+        // Step not found, use startStep or first step
+        const initialStepId = startStep || steps[0].id;
+        currentStepIndex = steps.findIndex((s) => s.id === initialStepId);
+        if (currentStepIndex === -1)
+            currentStepIndex = 0;
+        state.currentStepId = steps[currentStepIndex].id;
+        saveTourState(state);
+    }
+    const currentStep = steps[currentStepIndex];
+    // Check if current step matches the route
+    if (!stepMatchesRoute(currentStep)) {
+        // Current page doesn't match this step's route
+        // Tour is "waiting" for navigation to the correct page
+        context.publishEvent('tour.waiting_for_route', {
+            tourId,
+            stepId: currentStep.id,
+            expectedRoute: currentStep.route,
+            currentRoute: getCurrentRoute(),
+        });
+        // Return a no-op that cleans up when tour ends
+        return {
+            cleanup: () => { },
+        };
+    }
+    // Track state
+    let isDestroyed = false;
+    let currentActionHandle = null;
+    let eventUnsubscribe = null;
+    let routeWatcher = null;
+    /**
+     * Clean up current step
+     */
+    const cleanupCurrentStep = async () => {
+        if (eventUnsubscribe) {
+            eventUnsubscribe();
+            eventUnsubscribe = null;
+        }
+        if (currentActionHandle?.isApplied()) {
+            await currentActionHandle.revert();
+            currentActionHandle = null;
+        }
+    };
+    /**
+     * Advance to the next step
+     */
+    const advanceToStep = async (nextStepId) => {
+        if (isDestroyed)
+            return;
+        // Clean up current step
+        await cleanupCurrentStep();
+        if (nextStepId === 'end') {
+            // Tour complete
+            clearTourState();
+            context.publishEvent('tour.completed', {
+                tourId,
+                totalSteps: steps.length,
+            });
+            isDestroyed = true;
+            return;
+        }
+        // Find next step
+        const nextStep = steps.find((s) => s.id === nextStepId);
+        if (!nextStep) {
+            console.error(`[Tour] Step "${nextStepId}" not found`);
+            return;
+        }
+        // Update state
+        state.currentStepId = nextStepId;
+        saveTourState(state);
+        context.publishEvent('tour.step_changed', {
+            tourId,
+            previousStepId: currentStep.id,
+            nextStepId,
+        });
+        // If the next step has a different route, let navigation happen
+        if (nextStep.route && nextStep.route !== getCurrentRoute()) {
+            context.publishEvent('tour.awaiting_navigation', {
+                tourId,
+                stepId: nextStepId,
+                targetRoute: nextStep.route,
+            });
+            // Tour will resume when page reloads and this executor runs again
+            return;
+        }
+        // Execute the next step's action
+        await executeStep(nextStep);
+    };
+    /**
+     * Execute a step's inner action and set up event listeners
+     */
+    const executeStep = async (step) => {
+        if (isDestroyed)
+            return;
+        context.publishEvent('tour.step_started', {
+            tourId,
+            stepId: step.id,
+            stepIndex: steps.findIndex((s) => s.id === step.id),
+            totalSteps: steps.length,
+        });
+        // Execute the inner action
+        try {
+            currentActionHandle = await context.applyAction(step.action);
+        }
+        catch (error) {
+            console.error(`[Tour] Failed to execute step "${step.id}":`, error);
+            context.publishEvent('tour.step_failed', {
+                tourId,
+                stepId: step.id,
+                error: String(error),
+            });
+            return;
+        }
+        // Subscribe to CTA click events if there are transitions defined
+        if (step.onAction && context.subscribeEvent) {
+            eventUnsubscribe = context.subscribeEvent('action.modal_cta_clicked', (props) => {
+                const actionId = props?.actionId;
+                if (actionId && step.onAction) {
+                    const nextStepId = step.onAction[actionId];
+                    if (nextStepId) {
+                        advanceToStep(nextStepId);
+                    }
+                }
+            });
+            // Also listen for tooltip CTA clicks
+            const tooltipUnsubscribe = context.subscribeEvent('action.tooltip_cta_clicked', (props) => {
+                const actionId = props?.actionId;
+                if (actionId && step.onAction) {
+                    const nextStepId = step.onAction[actionId];
+                    if (nextStepId) {
+                        advanceToStep(nextStepId);
+                    }
+                }
+            });
+            // Combine unsubscribes
+            const originalUnsubscribe = eventUnsubscribe;
+            eventUnsubscribe = () => {
+                originalUnsubscribe();
+                tooltipUnsubscribe();
+            };
+        }
+    };
+    // Set up route change watcher for SPAs
+    const setupRouteWatcher = () => {
+        let lastPath = getCurrentRoute();
+        const checkRoute = () => {
+            const currentPath = getCurrentRoute();
+            if (currentPath !== lastPath) {
+                lastPath = currentPath;
+                context.publishEvent('tour.route_changed', {
+                    tourId,
+                    newRoute: currentPath,
+                });
+            }
+        };
+        // Use NavigationMonitor if available (single patch point),
+        // otherwise fall back to direct History API patching (legacy)
+        if (context.subscribeNavigation) {
+            return context.subscribeNavigation(() => checkRoute());
+        }
+        // Legacy: direct History API patching
+        window.addEventListener('popstate', checkRoute);
+        const origPushState = history.pushState.bind(history);
+        const origReplaceState = history.replaceState.bind(history);
+        history.pushState = (...args) => {
+            origPushState(...args);
+            queueMicrotask(checkRoute);
+        };
+        history.replaceState = (...args) => {
+            origReplaceState(...args);
+            queueMicrotask(checkRoute);
+        };
+        return () => {
+            window.removeEventListener('popstate', checkRoute);
+            history.pushState = origPushState;
+            history.replaceState = origReplaceState;
+        };
+    };
+    routeWatcher = setupRouteWatcher();
+    // Publish tour started/resumed event
+    if (!isResumingTour) {
+        context.publishEvent('tour.started', {
+            tourId,
+            totalSteps: steps.length,
+            startStepId: state.currentStepId,
+        });
+    }
+    else {
+        context.publishEvent('tour.resumed', {
+            tourId,
+            stepId: state.currentStepId,
+        });
+    }
+    // Execute the current step
+    await executeStep(currentStep);
+    // Create cleanup function
+    const cleanup = async () => {
+        isDestroyed = true;
+        // Remove from active tours
+        activeTours.delete(tourId);
+        await cleanupCurrentStep();
+        if (routeWatcher) {
+            routeWatcher();
+        }
+        // Don't clear tour state on cleanup - allow resume
+        context.publishEvent('tour.paused', {
+            tourId,
+            stepId: state.currentStepId,
+        });
+    };
+    // Register this tour as active
+    activeTours.set(tourId, { cleanup });
+    return { cleanup };
+};

package/dist/modal.d.ts

@@ -2,6 +2,8 @@
  * Modal Executor
  *
  * Displays a centered modal dialog with optional CTA buttons.
+ * Uses CSS custom properties (var()) directly in inline styles so theming
+ * is live — no timing dependency on when ThemeProvider injects vars.
  */
 import type { ActionExecutor, ModalAction } from './types';
 /**

package/dist/modal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"modal.d.ts","sourceRoot":"","sources":["../src/modal.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,OAAO,KAAK,EAAE,cAAc,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAC;AAE3E;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,WAAW,CAyNpD,CAAC"}
+{"version":3,"file":"modal.d.ts","sourceRoot":"","sources":["../src/modal.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,KAAK,EAAE,cAAc,EAAkB,WAAW,EAAE,MAAM,SAAS,CAAC;AAW3E;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,WAAW,CA0NpD,CAAC"}

package/dist/modal.js

@@ -2,9 +2,18 @@
  * Modal Executor
  *
  * Displays a centered modal dialog with optional CTA buttons.
+ * Uses CSS custom properties (var()) directly in inline styles so theming
+ * is live — no timing dependency on when ThemeProvider injects vars.
  */
-import { base } from '@syntro/design-system/tokens';
 import { sanitizeHtml } from './sanitizer';
+// CSS var shorthands with fallbacks (mirrors tooltip/toast pattern)
+const V = {
+    bg: 'var(--sc-overlay-background, #ffffff)',
+    title: 'var(--sc-overlay-title-color, var(--sc-overlay-text-color, #111827))',
+    text: 'var(--sc-overlay-text-color, #4b5563)',
+    accent: 'var(--sc-color-primary, #4f46e5)',
+    radius: 'var(--sc-border-radius, 12px)',
+};
 /**
  * Execute a modal action
  */
@@ -36,8 +45,8 @@ export const executeModal = async (action, context) => {
     transform: translate(-50%, -50%) scale(0.95);
     max-width: ${sizeMap[size]};
     width: 90%;
-    background: ${base.white};
-    border-radius: 12px;
+    background: ${V.bg};
+    border-radius: ${V.radius};
     box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
     z-index: 2147483646;
     opacity: 0;
@@ -47,9 +56,9 @@ export const executeModal = async (action, context) => {
     // Build modal HTML content
     let html = '';
     if (content.title) {
-        html += `<h2 class="syntro-modal-title" style="margin: 0 0 12px 0; font-size: 18px; font-weight: 600; color: #111827;">${sanitizeHtml(content.title)}</h2>`;
+        html += `<h2 class="syntro-modal-title" style="margin: 0 0 12px 0; font-size: 18px; font-weight: 600; color: ${V.title};">${sanitizeHtml(content.title)}</h2>`;
     }
-    html += `<div class="syntro-modal-body" style="color: #4b5563; line-height: 1.5;">${sanitizeHtml(content.body)}</div>`;
+    html += `<div class="syntro-modal-body" style="color: ${V.text}; line-height: 1.5;">${sanitizeHtml(content.body)}</div>`;
     // Add close button if enabled
     if (dismiss?.closeButton !== false) {
         html += `
@@ -61,7 +70,8 @@ export const executeModal = async (action, context) => {
         border: none;
         cursor: pointer;
         padding: 4px;
-        color: #6b7280;
+        color: ${V.text};
+        opacity: 0.6;
       " aria-label="Close">
         <svg width="20" height="20" viewBox="0 0 20 20" fill="currentColor">
           <path fill-rule="evenodd" d="M4.293 4.293a1 1 0 011.414 0L10 8.586l4.293-4.293a1 1 0 111.414 1.414L11.414 10l4.293 4.293a1 1 0 01-1.414 1.414L10 11.414l-4.293 4.293a1 1 0 01-1.414-1.414L8.586 10 4.293 5.707a1 1 0 010-1.414z" clip-rule="evenodd"/>
@@ -86,8 +96,8 @@ export const executeModal = async (action, context) => {
             cursor: pointer;
             transition: background 150ms ease;
             ${isPrimary
-                ? 'background: #4f46e5; color: white; border: none;'
-                : 'background: white; color: #374151; border: 1px solid #d1d5db;'}
+                ? `background: ${V.accent}; color: white; border: none;`
+                : `background: transparent; color: ${V.accent}; border: 1px solid currentColor; opacity: 0.7;`}
           "
         >
           ${sanitizeHtml(btn.label)}

package/dist/runtime.d.ts

@@ -1,11 +1,13 @@
 /**
  * Adaptive Overlays - Runtime Module
  *
- * Visual overlay actions: highlight, pulse, badge, tooltip.
+ * Visual overlay actions: highlight, pulse, badge, tooltip, celebrations.
  */
+import { executeTour } from './executors/tour';
 import { executeModal } from './modal';
 import type { ActionExecutor, BadgeAction, HighlightAction, PulseAction, TooltipAction } from './types';
-export { executeModal };
+export { executeModal, executeTour };
+export type { TourAction, TourStep, WorkflowMeta } from './tour-types';
 /**
  * Execute a highlight action
  */
@@ -41,6 +43,12 @@ export declare const executors: readonly [{
 }, {
     readonly kind: "overlays:modal";
     readonly executor: ActionExecutor<import("./types").ModalAction>;
+}, {
+    readonly kind: "core:tour";
+    readonly executor: ActionExecutor<import("./tour-types").TourAction>;
+}, {
+    readonly kind: "overlays:celebrate";
+    readonly executor: ActionExecutor<import("./types").CelebrateAction>;
 }];
 /**
  * App runtime manifest.
@@ -65,6 +73,21 @@ export declare const runtime: {
     }, {
         readonly kind: "overlays:modal";
         readonly executor: ActionExecutor<import("./types").ModalAction>;
+    }, {
+        readonly kind: "core:tour";
+        readonly executor: ActionExecutor<import("./tour-types").TourAction>;
+    }, {
+        readonly kind: "overlays:celebrate";
+        readonly executor: ActionExecutor<import("./types").CelebrateAction>;
     }];
+    widgets: {
+        id: string;
+        component: import("./WorkflowWidget").MountableWidget;
+        metadata: {
+            name: string;
+            icon: string;
+            description: string;
+        };
+    }[];
 };
 //# sourceMappingURL=runtime.d.ts.map

package/dist/runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAEX,eAAe,EACf,WAAW,EACX,aAAa,EACd,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,YAAY,EAAE,CAAC;AAMxB;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,eAAe,CA8B5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,WAAW,CAqDpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,WAAW,CA8EpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,aAAa,CAoFxD,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;EAMZ,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;CAMnB,CAAC"}
+{"version":3,"file":"runtime.d.ts","sourceRoot":"","sources":["../src/runtime.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAGvC,OAAO,KAAK,EACV,cAAc,EACd,WAAW,EAEX,eAAe,EACf,WAAW,EACX,aAAa,EACd,MAAM,SAAS,CAAC;AAIjB,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,CAAC;AAGrC,YAAY,EAAE,UAAU,EAAE,QAAQ,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAMvE;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,cAAc,CAAC,eAAe,CA2D5D,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,WAAW,CAyGpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,cAAc,CAAC,WAAW,CA+FpD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,cAAc,EAAE,cAAc,CAAC,aAAa,CAwFxD,CAAC;AAMF;;;GAGG;AACH,eAAO,MAAM,SAAS;;;;;;;;;;;;;;;;;;;;;EAQZ,CAAC;AAEX;;GAEG;AACH,eAAO,MAAM,OAAO;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAkBnB,CAAC"}