@burdenoff/fe-libs 2026.510.126

package/dist/shared/tours/ToursContext.js

@@ -0,0 +1,443 @@
+import { useGatewayClient as e } from "../graphql/GatewayContext.js";
+import "../../shared-graphql.js";
+import { useAuth as t } from "../providers/shell/AuthProvider.js";
+import { useActiveContext as n } from "../providers/shell/ActiveContextProvider.js";
+import { useAppShell as r } from "../providers/shell/AppShellContext.js";
+import { useLogger as i } from "../logger/useLogger.js";
+import "../../shared-logger.js";
+import { detectDeviceType as a } from "./types.js";
+import { createContext as o, useCallback as s, useContext as c, useEffect as l, useMemo as u, useRef as d, useState as f } from "react";
+import { jsx as p } from "react/jsx-runtime";
+import { gql as m } from "@apollo/client/core";
+import { useLocation as h } from "react-router-dom";
+//#region src/shared/tours/ToursContext.tsx
+var g = m`
+  fragment ToursCoreFields on Tour {
+    id
+    context {
+      workspaceId
+    }
+    name
+    slug
+    description
+    productId
+    moduleId
+    pageId
+    status
+    isActive
+    triggerType
+    triggerConfig
+    mobileConfig
+    tabletConfig
+    desktopConfig
+    priority
+    displayOrder
+  }
+`, _ = m`
+  fragment ToursStepFields on Tour {
+    steps {
+      id
+      tourId
+      title
+      content
+      stepOrder
+      targetSelector
+      placement
+      targetSelectorMobile
+      targetSelectorTablet
+      targetSelectorDesktop
+      customData
+      actions
+      requireInteraction
+      waitForSelector
+      waitForEvent
+      waitForTimeout
+      skipConditions
+      media {
+        id
+        position
+        mediaId
+        media {
+          id
+          name
+          type
+          cdnUrl
+          mimeType
+          altText
+          caption
+        }
+      }
+    }
+  }
+`, v = m`
+  ${g}
+  ${_}
+  query GetToursForContext($context: TourContextInput!) {
+    toursForContext(context: $context) {
+      ...ToursCoreFields
+      myProgress {
+        id
+        status
+      }
+      ...ToursStepFields
+    }
+  }
+`, y = m`
+  ${g}
+  ${_}
+  query GetToursForContextFallback($context: TourContextInput!) {
+    toursForContext(context: $context) {
+      ...ToursCoreFields
+      ...ToursStepFields
+    }
+  }
+`;
+function b(e) {
+	let t = e instanceof Error || typeof e == "object" && e && "message" in e && typeof e.message == "string" ? e.message : "";
+	return t.includes("myProgress") ? t.includes("Cannot query field") || t.includes("Unknown field") : !1;
+}
+var x = m`
+  mutation StartTour($tourId: ID!, $userId: ID!, $deviceType: DeviceType) {
+    startTour(tourId: $tourId, userId: $userId, deviceType: $deviceType) {
+      id
+      tourId
+      userId
+      status
+      currentStepId
+      completedSteps
+      startedAt
+      completedAt
+      lastViewedAt
+    }
+  }
+`, S = m`
+  mutation CompleteTour($tourId: ID!, $userId: ID!) {
+    completeTour(tourId: $tourId, userId: $userId) {
+      id
+      tourId
+      userId
+      status
+      currentStepId
+      completedSteps
+      startedAt
+      completedAt
+      lastViewedAt
+    }
+  }
+`, ee = m`
+  mutation SkipTour($tourId: ID!, $userId: ID!) {
+    skipTour(tourId: $tourId, userId: $userId) {
+      id
+      tourId
+      userId
+      status
+      currentStepId
+      completedSteps
+      startedAt
+      completedAt
+      lastViewedAt
+    }
+  }
+`, te = m`
+  mutation CompleteStep($tourId: ID!, $stepId: ID!, $userId: ID!) {
+    completeStep(tourId: $tourId, stepId: $stepId, userId: $userId) {
+      id
+      tourId
+      userId
+      status
+      currentStepId
+      completedSteps
+      startedAt
+      completedAt
+      lastViewedAt
+    }
+  }
+`, ne = m`
+  mutation TrackTourEvent($input: RecordTourAnalyticsInput!) {
+    trackTourEvent(input: $input) {
+      id
+      tourId
+      eventType
+      stepId
+      stepOrder
+      timestamp
+    }
+  }
+`, C = [
+	"The client has been stopped",
+	"QueryManager stopped",
+	"This Apollo Client has been destroyed",
+	"aborted"
+];
+function re(e) {
+	if (!(e instanceof Error)) return !1;
+	let t = e.message;
+	return e.name === "InvariantError" || t.startsWith("Invariant Violation") ? C.some((e) => t.includes(e)) : !1;
+}
+function w(e, t) {
+	let n = e.split("/").filter(Boolean);
+	return n.length === 0 ? t : n[0];
+}
+function T() {
+	let e = a();
+	return e === "mobile" ? "MOBILE" : e === "tablet" ? "TABLET" : "DESKTOP";
+}
+function E() {
+	let e = "bf-tour-session-id";
+	try {
+		let t = sessionStorage.getItem(e);
+		if (t) return t;
+		let n = typeof crypto < "u" && typeof crypto.randomUUID == "function" ? crypto.randomUUID() : `tour-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+		return sessionStorage.setItem(e, n), n;
+	} catch {
+		return `tour-session-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+	}
+}
+function D(e, t, n, r) {
+	let i = e.split("/").filter(Boolean), a = r ? r(e) : w(e, n);
+	return i.length === 0 ? {
+		moduleId: t,
+		pageId: a
+	} : i[0] === t ? {
+		moduleId: t,
+		pageId: i[1] ?? n
+	} : {
+		moduleId: i[0],
+		pageId: a
+	};
+}
+var O = o(null);
+function k({ children: a, defaultPageId: o = "home", getPageIdFromPath: c, disabled: m = !1 }) {
+	let g = h(), _ = e("global"), { workspaceId: C } = n(), { user: w } = t(), { productSlug: k } = r(), A = i("ToursContext"), j = C ?? void 0, M = m || g.pathname.startsWith("/devportal"), { moduleId: N, pageId: P } = u(() => D(g.pathname, k, o, c), [
+		o,
+		c,
+		g.pathname,
+		k
+	]), [F, I] = f([]), [L, R] = f(!1), [z, B] = f(null), V = d(void 0), H = d(!1), U = d(!0), W = d(0), G = d(!0);
+	l(() => (U.current = !0, () => {
+		U.current = !1;
+	}), []);
+	let K = s(async (e = !1) => {
+		if (M) {
+			U.current && (I([]), R(!1), B(null));
+			return;
+		}
+		if (!_) return;
+		let t = A.child("fetch", {
+			productSlug: k,
+			moduleId: N,
+			pageId: P,
+			workspaceId: j
+		}), n = T(), r = [
+			k,
+			N,
+			P,
+			j,
+			n,
+			w?.id ?? "anonymous"
+		].join("::");
+		if (!e && H.current && V.current === r) return;
+		U.current && (R(!0), B(null));
+		let i = ++W.current;
+		try {
+			let e = { context: {
+				productId: k,
+				moduleId: N,
+				pageId: P,
+				workspaceId: j,
+				deviceType: n
+			} }, a = "network-only", o, s = G.current ? v : y;
+			try {
+				o = await _.query({
+					query: s,
+					variables: e,
+					fetchPolicy: a,
+					errorPolicy: "none"
+				});
+				let n = o.errors;
+				s === v && n?.some((e) => b(e)) && (G.current = !1, t.warn("[ToursContext] Gateway returned a Tour.myProgress validation error — falling back to query without progress chips until the backend field is published."), o = await _.query({
+					query: y,
+					variables: e,
+					fetchPolicy: a,
+					errorPolicy: "none"
+				}));
+			} catch (n) {
+				if (s === v && b(n)) G.current = !1, t.warn("[ToursContext] Gateway does not expose Tour.myProgress yet — falling back to query without progress chips until the backend field is published."), o = await _.query({
+					query: y,
+					variables: e,
+					fetchPolicy: a,
+					errorPolicy: "none"
+				});
+				else throw n;
+			}
+			let c = (o.data?.toursForContext ?? []).filter((e, t, n) => n.findIndex((t) => t.id === e.id) === t);
+			U.current && i === W.current && (I(c), V.current = r, H.current = !0);
+		} catch (e) {
+			if (!U.current || i !== W.current || re(e)) return;
+			let n = e instanceof Error ? e : /* @__PURE__ */ Error("Failed to fetch tours");
+			t.error("Failed to fetch tours for context", n), B(n), I([]);
+		} finally {
+			U.current && i === W.current && R(!1);
+		}
+	}, [
+		M,
+		_,
+		A,
+		N,
+		P,
+		k,
+		j,
+		w?.id
+	]), q = d(w?.id);
+	l(() => {
+		q.current !== w?.id && (q.current = w?.id, H.current = !1, V.current = void 0, U.current && I([]));
+	}, [w?.id]), l(() => {
+		K();
+	}, [K]);
+	let J = s(() => {
+		K(!0);
+	}, [K]), Y = u(() => F.filter((e) => e.isActive && e.steps?.length > 0).sort((e, t) => (t.priority ?? 0) - (e.priority ?? 0)), [F]), X = u(() => Y.find((e) => e.triggerType === "AUTO_FIRST_VISIT" || e.triggerType === "AUTO_ALWAYS") ?? null, [Y]), Z = s(async (e, t, n) => {
+		if (!(!_ || !w?.id)) try {
+			if (t === "started") {
+				await _.mutate({
+					mutation: x,
+					variables: {
+						tourId: e,
+						userId: w.id,
+						deviceType: T()
+					}
+				});
+				return;
+			}
+			if (t === "completed") {
+				await _.mutate({
+					mutation: S,
+					variables: {
+						tourId: e,
+						userId: w.id
+					}
+				});
+				return;
+			}
+			await _.mutate({
+				mutation: ee,
+				variables: {
+					tourId: e,
+					userId: w.id
+				}
+			});
+		} catch {}
+	}, [_, w?.id]), Q = s(async (e, t) => {
+		if (!(!_ || !w?.id || !t)) try {
+			await _.mutate({
+				mutation: te,
+				variables: {
+					tourId: e,
+					stepId: t,
+					userId: w.id
+				}
+			});
+		} catch {}
+	}, [_, w?.id]), $ = s(async (e, t, n) => {
+		if (!(!_ || !w?.id)) try {
+			await _.mutate({
+				mutation: ne,
+				variables: { input: {
+					tourId: t,
+					userId: w.id,
+					sessionId: E(),
+					eventType: e,
+					stepId: n?.stepId,
+					stepOrder: n?.stepOrder,
+					productId: k,
+					moduleId: N,
+					pageId: P,
+					deviceType: T(),
+					userAgent: typeof navigator < "u" ? navigator.userAgent : void 0,
+					duration: n?.duration,
+					metadata: n?.metadata,
+					context: j ? {
+						workspaceId: j,
+						productId: k,
+						moduleId: N,
+						pageId: P
+					} : {
+						productId: k,
+						moduleId: N,
+						pageId: P
+					}
+				} }
+			});
+		} catch {}
+	}, [
+		_,
+		N,
+		P,
+		k,
+		w?.id,
+		j
+	]), ie = u(() => ({
+		tours: F,
+		pageTours: Y,
+		loading: L,
+		error: z,
+		refetch: J,
+		trackProgress: Z,
+		recordStepCompletion: Q,
+		trackEvent: $,
+		autoStartTour: X,
+		moduleId: N,
+		pageId: P
+	}), [
+		F,
+		X,
+		z,
+		L,
+		N,
+		P,
+		Y,
+		Q,
+		J,
+		$,
+		Z
+	]);
+	return /* @__PURE__ */ p(O.Provider, {
+		value: ie,
+		children: a
+	});
+}
+function A() {
+	let e = c(O);
+	if (!e) throw Error("useToursContext must be used within a ToursProvider");
+	return e;
+}
+function j() {
+	return c(O) || {
+		tours: [],
+		pageTours: [],
+		loading: !1,
+		error: null,
+		refetch: () => {},
+		trackProgress: async () => {},
+		recordStepCompletion: async () => {},
+		trackEvent: async () => {},
+		autoStartTour: null,
+		moduleId: void 0,
+		pageId: void 0
+	};
+}
+function M() {
+	let e = A();
+	return {
+		tours: e.pageTours,
+		loading: e.loading,
+		error: e.error,
+		refetch: e.refetch,
+		trackProgress: e.trackProgress
+	};
+}
+function N() {
+	return A().autoStartTour;
+}
+//#endregion
+export { k as ToursProvider, N as useAutoStartTour, j as useSafeToursContext, M as useTours, A as useToursContext };

package/dist/shared/tours/index.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Tour Player Module
+ * Provides components and hooks for displaying interactive product tours
+ *
+ * @example
+ * ```tsx
+ * import { TourPlayerProvider, TourPlayer, usePlayTour } from '@burdenoff/fe-libs/shared/tours';
+ *
+ * // Wrap your app with the provider
+ * function App() {
+ *   return (
+ *     <TourPlayerProvider
+ *       onTourComplete={(tour) => console.log('Completed:', tour.name)}
+ *       onTourSkip={(tour, step) => console.log('Skipped at step:', step)}
+ *     >
+ *       <YourApp />
+ *     </TourPlayerProvider>
+ *   );
+ * }
+ *
+ * // In your component, start a tour
+ * function SomeComponent() {
+ *   const playTour = usePlayTour();
+ *
+ *   const myTour = {
+ *     id: 'welcome-tour',
+ *     name: 'Welcome Tour',
+ *     steps: [
+ *       { id: 's1', title: 'Welcome', content: 'Welcome to our app!', targetSelector: '#header' },
+ *       { id: 's2', title: 'Sidebar', content: 'This is the sidebar', targetSelector: '#sidebar' },
+ *     ],
+ *   };
+ *
+ *   return <button onClick={() => playTour(myTour)}>Start Tour</button>;
+ * }
+ * ```
+ */
+export { TourPlayerProvider, useTourPlayerContext, useStartTour, useStopTour, useIsTourPlaying, } from './TourPlayerProvider';
+export { TourPlayer, usePlayTour, TourTriggerButton } from './TourPlayer';
+export { TourSpotlight } from './TourSpotlight';
+export { TourTooltip } from './TourTooltip';
+export { useTourPlayer } from './useTourPlayer';
+export type { Tour, TourStep, TourStepMedia, TourStatus, TourTriggerType, StepPlacement, MediaType, MediaPosition, DeviceType, TourPlayerState, TourPlayerActions, TourPlayerContextValue, TourPlayerProviderProps, TourTooltipProps, TourSpotlightProps, } from './types';
+export { getResponsiveSelector, detectDeviceType } from './types';
+export { ToursProvider, useToursContext, useSafeToursContext, useTours, useAutoStartTour, } from './ToursContext';
+export type { ToursContextValue, ToursProviderProps } from './ToursContext';
+export { TourTrigger } from './TourTrigger';
+export { TourInitializer } from './TourInitializer';
+//# sourceMappingURL=index.d.ts.map

package/dist/shared/tours/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/shared/tours/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EACL,kBAAkB,EAClB,oBAAoB,EACpB,YAAY,EACZ,WAAW,EACX,gBAAgB,GACjB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC1E,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAG5C,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGhD,YAAY,EACV,IAAI,EACJ,QAAQ,EACR,aAAa,EACb,UAAU,EACV,eAAe,EACf,aAAa,EACb,SAAS,EACT,aAAa,EACb,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,sBAAsB,EACtB,uBAAuB,EACvB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,SAAS,CAAC;AAGjB,OAAO,EAAE,qBAAqB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAGlE,OAAO,EACL,aAAa,EACb,eAAe,EACf,mBAAmB,EACnB,QAAQ,EACR,gBAAgB,GACjB,MAAM,gBAAgB,CAAC;AACxB,YAAY,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAG5E,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/shared/tours/types.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Tour Player Types
+ * Defines types for the tour player component
+ */
+export type TourStatus = "DRAFT" | "PUBLISHED" | "ARCHIVED" | "SCHEDULED";
+/**
+ * TourUserStatus — per-user progress states for a tour.
+ * Mirrors `enum TourUserStatus` in
+ * `global-tours-svc/prisma/schema/tours.prisma`. Keep these in sync with
+ * the backend when adding/removing values — the Tour.myProgress resolver
+ * returns the raw Prisma enum, so a client-side divergence surfaces as
+ * a silent string mismatch at render time (unknown statuses fall through
+ * to `null` in STATUS_CHIP_CONFIG) rather than a runtime error. Tracked
+ * in Linear BOFF-2233.
+ */
+export type TourUserStatus = "NOT_STARTED" | "IN_PROGRESS" | "COMPLETED" | "SKIPPED" | "DISMISSED";
+/**
+ * Tour user progress (subset of backend TourUserProgress fields that the
+ * client actually uses to render chips + filters). Matches the selection
+ * set in `GET_TOURS_FOR_CONTEXT` on `Tour.myProgress` — add fields here
+ * AND to the query fragment when the client needs more of the progress
+ * row. Backend source of truth:
+ * `global-tours-svc/src/modules/tours/resolvers/tour/tour.type.ts`.
+ */
+export interface TourUserProgressSummary {
+    id: string;
+    status: TourUserStatus;
+}
+export type TourTriggerType = "MANUAL" | "AUTO_FIRST_VISIT" | "AUTO_ALWAYS" | "ON_EVENT" | "SCHEDULED";
+export type StepPlacement = "AUTO" | "TOP" | "BOTTOM" | "LEFT" | "RIGHT" | "CENTER";
+export type MediaType = "IMAGE" | "VIDEO" | "AUDIO" | "DOCUMENT";
+export type MediaPosition = "HEADER" | "INLINE" | "BODY" | "FOOTER";
+/**
+ * Tour step for the player
+ */
+export interface TourStep {
+    id: string;
+    tourId: string;
+    title: string;
+    content: string;
+    stepOrder: number;
+    targetSelector?: string;
+    placement: StepPlacement;
+    targetSelectorMobile?: string;
+    targetSelectorTablet?: string;
+    targetSelectorDesktop?: string;
+    customData?: Record<string, unknown>;
+    actions?: Record<string, unknown>;
+    requireInteraction?: boolean;
+    waitForSelector?: string;
+    waitForEvent?: string;
+    waitForTimeout?: number;
+    skipConditions?: Record<string, unknown>;
+    media?: TourStepMedia[];
+}
+/**
+ * Tour step media attachment
+ */
+export interface TourStepMedia {
+    id: string;
+    mediaId: string;
+    position: MediaPosition;
+    displayOrder: number;
+    media: {
+        id: string;
+        name: string;
+        type: MediaType;
+        cdnUrl?: string;
+        mimeType: string;
+        altText?: string;
+        caption?: string;
+    };
+}
+/**
+ * Tour for the player
+ */
+export interface Tour {
+    id: string;
+    context?: {
+        workspaceId?: string;
+        userId?: string;
+        organizationId?: string;
+        projectId?: string;
+        productId?: string;
+        moduleId?: string;
+        pageId?: string;
+    };
+    name: string;
+    slug: string;
+    description?: string;
+    productId: string;
+    moduleId?: string;
+    pageId?: string;
+    status: TourStatus;
+    isActive: boolean;
+    triggerType: TourTriggerType;
+    triggerConfig?: Record<string, unknown>;
+    mobileConfig?: Record<string, unknown>;
+    tabletConfig?: Record<string, unknown>;
+    desktopConfig?: Record<string, unknown>;
+    priority: number;
+    displayOrder: number;
+    steps: TourStep[];
+    /**
+     * Current authenticated user's progress for this tour, or null if they
+     * haven't interacted yet. Populated by the backend field resolver
+     * `Tour.myProgress` (TOUR-P2-020). Used by TourTrigger to render per-tour
+     * status chips inline in the dropdown.
+     */
+    myProgress?: TourUserProgressSummary | null;
+}
+/**
+ * Tour player state
+ */
+export interface TourPlayerState {
+    isPlaying: boolean;
+    currentTour: Tour | null;
+    currentStepIndex: number;
+    isPaused: boolean;
+    isCompleted: boolean;
+    isSkipped: boolean;
+}
+/**
+ * Tour player actions
+ */
+export interface TourPlayerActions {
+    startTour: (tour: Tour) => void;
+    stopTour: () => void;
+    nextStep: () => void;
+    previousStep: () => void;
+    goToStep: (index: number) => void;
+    pauseTour: () => void;
+    resumeTour: () => void;
+    skipTour: () => void;
+    completeTour: () => void;
+}
+/**
+ * Tour player context value
+ */
+export interface TourPlayerContextValue extends TourPlayerState, TourPlayerActions {
+    currentStep: TourStep | null;
+    totalSteps: number;
+    progress: number;
+    canGoNext: boolean;
+    canGoPrevious: boolean;
+}
+/**
+ * Tour player provider props
+ */
+export interface TourPlayerProviderProps {
+    children: React.ReactNode;
+    /**
+     * Callback when a tour starts
+     */
+    onTourStart?: (tour: Tour) => void;
+    /**
+     * Callback when a tour completes
+     */
+    onTourComplete?: (tour: Tour) => void;
+    /**
+     * Callback when a tour is skipped
+     */
+    onTourSkip?: (tour: Tour, stepIndex: number) => void;
+    /**
+     * Callback when a step changes
+     */
+    onStepChange?: (tour: Tour, stepIndex: number) => void;
+    /**
+     * Callback when a step is completed before advancing or finishing
+     */
+    onStepComplete?: (tour: Tour, stepIndex: number) => void;
+    /**
+     * Custom z-index for the overlay
+     */
+    zIndex?: number;
+}
+/**
+ * Tour tooltip props
+ */
+export interface TourTooltipProps {
+    step: TourStep;
+    stepIndex: number;
+    totalSteps: number;
+    onNext: () => void;
+    onPrevious: () => void;
+    onSkip: () => void;
+    onComplete: () => void;
+    canGoNext: boolean;
+    canGoPrevious: boolean;
+    isLastStep: boolean;
+    placement: StepPlacement;
+    targetRect: DOMRect | null;
+}
+/**
+ * Tour spotlight props
+ */
+export interface TourSpotlightProps {
+    targetRect: DOMRect | null;
+    padding?: number;
+    borderRadius?: number;
+    zIndex?: number;
+}
+/**
+ * Device type for responsive selectors
+ */
+export type DeviceType = "mobile" | "tablet" | "desktop";
+/**
+ * Get the appropriate selector based on device type
+ */
+export declare function getResponsiveSelector(step: TourStep, deviceType: DeviceType): string | undefined;
+/**
+ * Detect current device type based on screen width
+ */
+export declare function detectDeviceType(): DeviceType;
+//# sourceMappingURL=types.d.ts.map