@buoy-gg/route-events 1.7.2

package/lib/commonjs/expoRouterStore.js

@@ -0,0 +1,104 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getExpoRouterStore = getExpoRouterStore;
+exports.getRouteNodeMetadata = getRouteNodeMetadata;
+exports.loadRouteNode = loadRouteNode;
+let cachedStore = null;
+let cachedStoreSource = null;
+let importError = null;
+let hasLoggedMissingStore = false;
+let hasLoggedMissingRouteNode = false;
+let lastRouteNodeTimestamp = null;
+function logOnce(message, error) {
+  if (__DEV__) {
+    if (error) {
+      console.error(`[RouteEvents] ${message}`, error);
+    } else {
+      console.warn(`[RouteEvents] ${message}`);
+    }
+  }
+}
+
+/**
+ * Attempt to require the expo-router store from known locations.
+ * Returns null (with a logged error in dev) when expo-router is not available.
+ *
+ * Note: The store uses getters that read from an internal storeRef.
+ * The storeRef gets populated when Expo Router's useStore() hook runs.
+ * So we cache the store reference but its property values update over time.
+ */
+function getExpoRouterStore() {
+  if (cachedStore) {
+    return cachedStore;
+  }
+  const loadFromBuild = () => {
+    try {
+      const module = require("expo-router/build/global-state/router-store");
+      if (module?.store) {
+        cachedStore = module.store;
+        cachedStoreSource = "build";
+        importError = null;
+        hasLoggedMissingStore = false;
+        return true;
+      }
+    } catch (error) {
+      importError = error;
+    }
+    return false;
+  };
+  const loadFromSrc = () => {
+    try {
+      const module = require("expo-router/src/global-state/router-store");
+      if (module?.store) {
+        cachedStore = module.store;
+        cachedStoreSource = "src";
+        importError = null;
+        hasLoggedMissingStore = false;
+        return true;
+      }
+    } catch (error) {
+      importError = error;
+    }
+    return false;
+  };
+  if (loadFromBuild() || loadFromSrc()) {
+    return cachedStore;
+  }
+  if (!hasLoggedMissingStore) {
+    logOnce("Unable to load expo-router internals. @buoy-gg/route-events requires expo-router >= 2.0.0. Install expo-router and ensure it is configured before using the Routes tab.", importError ?? undefined);
+    hasLoggedMissingStore = true;
+  }
+  return null;
+}
+
+/**
+ * Returns the current RouteNode tree (if available).
+ * Logs a helpful warning in development when the tree is missing even though
+ * the navigation ref is ready.
+ */
+function loadRouteNode() {
+  const store = getExpoRouterStore();
+  if (!store) {
+    return null;
+  }
+  if (store.routeNode) {
+    hasLoggedMissingRouteNode = false;
+    lastRouteNodeTimestamp = Date.now();
+    return store.routeNode;
+  }
+  const isReady = store.navigationRef?.isReady?.();
+  if (__DEV__ && !hasLoggedMissingRouteNode && isReady) {
+    logOnce("Expo Router route tree is unavailable. Ensure your app directory is configured and that expo-router is initialized before opening the Route Events devtool.");
+    hasLoggedMissingRouteNode = true;
+  }
+  return null;
+}
+function getRouteNodeMetadata() {
+  return {
+    source: cachedStoreSource,
+    lastLoadedAt: lastRouteNodeTimestamp
+  };
+}

package/lib/commonjs/index.js

@@ -0,0 +1,99 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+Object.defineProperty(exports, "NavigationStack", {
+  enumerable: true,
+  get: function () {
+    return _NavigationStack.NavigationStack;
+  }
+});
+Object.defineProperty(exports, "RouteEventsModalWithTabs", {
+  enumerable: true,
+  get: function () {
+    return _RouteEventsModalWithTabs.RouteEventsModalWithTabs;
+  }
+});
+Object.defineProperty(exports, "RouteObserver", {
+  enumerable: true,
+  get: function () {
+    return _RouteObserver.RouteObserver;
+  }
+});
+Object.defineProperty(exports, "RouteParser", {
+  enumerable: true,
+  get: function () {
+    return _RouteParser.RouteParser;
+  }
+});
+Object.defineProperty(exports, "RouteTracker", {
+  enumerable: true,
+  get: function () {
+    return _RouteTracker.RouteTracker;
+  }
+});
+Object.defineProperty(exports, "RoutesSitemap", {
+  enumerable: true,
+  get: function () {
+    return _RoutesSitemap.RoutesSitemap;
+  }
+});
+Object.defineProperty(exports, "createRouteEventsTool", {
+  enumerable: true,
+  get: function () {
+    return _preset.createRouteEventsTool;
+  }
+});
+Object.defineProperty(exports, "routeEventsToolPreset", {
+  enumerable: true,
+  get: function () {
+    return _preset.routeEventsToolPreset;
+  }
+});
+Object.defineProperty(exports, "routeObserver", {
+  enumerable: true,
+  get: function () {
+    return _RouteObserver.routeObserver;
+  }
+});
+Object.defineProperty(exports, "useNavigationStack", {
+  enumerable: true,
+  get: function () {
+    return _useNavigationStack.useNavigationStack;
+  }
+});
+Object.defineProperty(exports, "useParentRoutes", {
+  enumerable: true,
+  get: function () {
+    return _useRouteSitemap.useParentRoutes;
+  }
+});
+Object.defineProperty(exports, "useRoute", {
+  enumerable: true,
+  get: function () {
+    return _useRouteSitemap.useRoute;
+  }
+});
+Object.defineProperty(exports, "useRouteObserver", {
+  enumerable: true,
+  get: function () {
+    return _useRouteObserver.useRouteObserver;
+  }
+});
+Object.defineProperty(exports, "useRouteSitemap", {
+  enumerable: true,
+  get: function () {
+    return _useRouteSitemap.useRouteSitemap;
+  }
+});
+var _RouteEventsModalWithTabs = require("./components/RouteEventsModalWithTabs");
+var _preset = require("./preset");
+var _RouteTracker = require("./RouteTracker");
+var _RoutesSitemap = require("./components/RoutesSitemap");
+var _NavigationStack = require("./components/NavigationStack");
+var _RouteObserver = require("./RouteObserver");
+var _useRouteObserver = require("./useRouteObserver");
+var _RouteParser = require("./RouteParser");
+var _useRouteSitemap = require("./useRouteSitemap");
+var _useNavigationStack = require("./useNavigationStack");

package/lib/commonjs/package.json

@@ -0,0 +1 @@
+{"type":"commonjs"}

package/lib/commonjs/preset.js

@@ -0,0 +1,83 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.createRouteEventsTool = createRouteEventsTool;
+exports.routeEventsToolPreset = void 0;
+var _floatingToolsCore = require("@buoy-gg/floating-tools-core");
+var _RouteEventsModalWithTabs = require("./components/RouteEventsModalWithTabs");
+var _jsxRuntime = require("react/jsx-runtime");
+/**
+ * Pre-configured route events tool for FloatingDevTools
+ *
+ * This preset provides a zero-config way to add route tracking to your dev tools.
+ * Just import and spread it into your apps array!
+ *
+ * @example
+ * ```tsx
+ * import { routeEventsToolPreset } from '@buoy-gg/route-events';
+ *
+ * const installedApps = [
+ *   routeEventsToolPreset, // That's it!
+ *   // ...other tools
+ * ];
+ * ```
+ */
+
+/**
+ * Pre-configured route events tool for FloatingDevTools.
+ * Includes:
+ * - Route sitemap browser
+ * - Event timeline with filtering
+ * - Navigation stack visualization
+ * - Automatic route tracking (no setup needed)
+ */
+const routeEventsToolPreset = exports.routeEventsToolPreset = {
+  id: "route-events",
+  name: "ROUTES",
+  description: "Route tracking & navigation inspector",
+  slot: "both",
+  icon: ({
+    size
+  }) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_floatingToolsCore.RoutesIcon, {
+    size: size
+  }),
+  component: _RouteEventsModalWithTabs.RouteEventsModalWithTabs,
+  props: {
+    enableSharedModalDimensions: false
+  }
+};
+
+/**
+ * Create a custom route events tool configuration.
+ * Use this if you want to override default settings.
+ *
+ * @example
+ * ```tsx
+ * import { createRouteEventsTool } from '@buoy-gg/route-events';
+ *
+ * const myRouteTool = createRouteEventsTool({
+ *   name: "MY ROUTES",
+ *   color: "#a78bfa",
+ *   enableSharedModalDimensions: true,
+ * });
+ * ```
+ */
+function createRouteEventsTool(options) {
+  return {
+    id: options?.id || "route-events",
+    name: options?.name || "ROUTES",
+    description: options?.description || "Route tracking & navigation inspector",
+    slot: "both",
+    icon: ({
+      size
+    }) => /*#__PURE__*/(0, _jsxRuntime.jsx)(_floatingToolsCore.RoutesIcon, {
+      size: size
+    }),
+    component: _RouteEventsModalWithTabs.RouteEventsModalWithTabs,
+    props: {
+      enableSharedModalDimensions: options?.enableSharedModalDimensions !== undefined ? options.enableSharedModalDimensions : false
+    }
+  };
+}

package/lib/commonjs/useNavigationStack.js

@@ -0,0 +1,241 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useNavigationStack = useNavigationStack;
+var _react = require("react");
+var _native = require("@react-navigation/native");
+var _expoRouter = require("expo-router");
+/**
+ * useNavigationStack - Hook to access current navigation stack state
+ *
+ * Provides real-time access to the navigation stack from Expo Router,
+ * showing what screens are currently mounted in memory and which is visible.
+ *
+ * Data source: @react-navigation/native
+ */
+
+// ============================================================================
+// Type Definitions
+// ============================================================================
+
+// ============================================================================
+// Main Hook
+// ============================================================================
+
+/**
+ * Recursively collect all routes from the navigation state tree
+ */
+function collectRoutesFromState(state, depth = 0, parentPath = "") {
+  if (!state || !state.routes) return [];
+  const routes = [];
+  for (let i = 0; i < state.routes.length; i++) {
+    const route = state.routes[i];
+    const isFocused = i === state.index;
+
+    // Build the path
+    let pathname = route.name;
+    if (route.name === "index") {
+      pathname = "/";
+    } else if (!pathname.startsWith("/")) {
+      pathname = `/${pathname}`;
+    }
+
+    // Add parent path
+    if (parentPath && parentPath !== "/") {
+      pathname = `${parentPath}${pathname}`;
+    }
+
+    // Add params to pathname for dynamic routes
+    if (route.params) {
+      const paramEntries = Object.entries(route.params);
+      if (paramEntries.length > 0) {
+        pathname = pathname.replace(/\[([^\]]+)\]/g, (match, param) => {
+          return route.params[param] || match;
+        });
+      }
+    }
+    routes.push({
+      key: route.key,
+      name: route.name,
+      path: pathname,
+      params: route.params || {},
+      state: route.state
+    });
+
+    // If this route has nested state and is focused, recurse
+    if (isFocused && route.state) {
+      const nestedRoutes = collectRoutesFromState(route.state, depth + 1, pathname);
+      routes.push(...nestedRoutes);
+    }
+  }
+  return routes;
+}
+
+/**
+ * Access the current navigation stack from Expo Router
+ *
+ * @example
+ * ```tsx
+ * const { stack, focusedRoute, goBack, popToTop } = useNavigationStack();
+ *
+ * // Display stack
+ * stack.map(item => (
+ *   <View key={item.key}>
+ *     <Text>{item.pathname}</Text>
+ *     {item.isFocused && <Text>VISIBLE</Text>}
+ *   </View>
+ * ));
+ * ```
+ */
+function useNavigationStack() {
+  const [isLoaded, setIsLoaded] = (0, _react.useState)(false);
+  const [error, setError] = (0, _react.useState)(null);
+  const navigation = (0, _native.useNavigation)();
+
+  // Subscribe to navigation state changes - this will cause re-renders when state updates
+  const navigationState = (0, _native.useNavigationState)(state => state);
+
+  // Mark as loaded once we have navigation
+  (0, _react.useEffect)(() => {
+    setIsLoaded(true);
+  }, []);
+
+  // Transform navigation state into display items
+  const stack = (0, _react.useMemo)(() => {
+    if (!navigationState) return [];
+    try {
+      const routes = collectRoutesFromState(navigationState);
+
+      // Filter out internal Expo Router routes (layouts, __root, etc.)
+      const filteredRoutes = routes.filter(route => {
+        // Remove __root and other internal routes
+        if (route.name.startsWith("__")) return false;
+        if (route.name.includes("_layout")) return false;
+        if (route.name.startsWith("+not-found")) return false;
+        return true;
+      });
+
+      // If we filtered everything out, just keep the last route
+      const finalRoutes = filteredRoutes.length > 0 ? filteredRoutes : routes.slice(-1);
+
+      // The last route in the collected list is the focused one
+      return finalRoutes.map((route, index) => {
+        // Clean up pathname by removing /__root prefix
+        let cleanPath = route.path || `/${route.name}`;
+        cleanPath = cleanPath.replace(/^\/__root/, "");
+        // Ensure we always have at least a /
+        if (!cleanPath || cleanPath === "") {
+          cleanPath = "/";
+        }
+        return {
+          key: route.key,
+          name: route.name,
+          pathname: cleanPath,
+          params: route.params || {},
+          isFocused: index === finalRoutes.length - 1,
+          index,
+          canPop: index > 0
+        };
+      });
+    } catch (err) {
+      console.error("Error transforming navigation state:", err);
+      return [];
+    }
+  }, [navigationState]);
+
+  // Get focused route
+  const focusedRoute = (0, _react.useMemo)(() => {
+    return stack.find(item => item.isFocused) || null;
+  }, [stack]);
+
+  // Helper properties
+  const stackDepth = stack.length;
+  const isAtRoot = stackDepth <= 1;
+
+  // Manual refresh (no-op since we're using React Navigation's state)
+  const refresh = () => {
+    // Navigation state updates automatically via useNavigationState
+  };
+
+  // Navigation actions
+  const navigateToIndex = index => {
+    if (index >= stack.length || index < 0) {
+      return;
+    }
+    const targetRoute = stack[index];
+    if (!targetRoute) {
+      return;
+    }
+
+    // Use router directly from expo-router
+    if (!_expoRouter.router) {
+      return;
+    }
+    try {
+      _expoRouter.router.navigate(targetRoute.pathname);
+    } catch (err) {
+      console.error("Failed to navigate:", err);
+    }
+  };
+  const popToIndex = index => {
+    if (index >= stack.length || index < 0) {
+      return;
+    }
+    const currentIndex = stack.length - 1;
+    const popCount = currentIndex - index;
+    if (popCount <= 0) {
+      return;
+    }
+
+    // Use router directly from expo-router
+    if (!_expoRouter.router) {
+      return;
+    }
+    try {
+      // Pop multiple times
+      for (let i = 0; i < popCount; i++) {
+        _expoRouter.router.back();
+      }
+    } catch (err) {
+      console.error("Failed to pop:", err);
+    }
+  };
+  const goBack = () => {
+    if (isAtRoot) {
+      return;
+    }
+
+    // Use router directly from expo-router
+    if (!_expoRouter.router) {
+      return;
+    }
+    try {
+      _expoRouter.router.back();
+    } catch (err) {
+      console.error("Failed to go back:", err);
+    }
+  };
+  const popToTop = () => {
+    if (isAtRoot) {
+      return;
+    }
+
+    // Pop to index 0 (root)
+    popToIndex(0);
+  };
+  return {
+    stack,
+    focusedRoute,
+    stackDepth,
+    isAtRoot,
+    isLoaded,
+    error,
+    refresh,
+    navigateToIndex,
+    popToIndex,
+    goBack,
+    popToTop
+  };
+}

package/lib/commonjs/useRouteObserver.js

@@ -0,0 +1,73 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useRouteObserver = useRouteObserver;
+var _react = require("react");
+var _expoRouter = require("expo-router");
+var _RouteObserver = require("./RouteObserver");
+/**
+ * useRouteObserver - React hook for observing route changes
+ *
+ * Uses public Expo Router hooks to track route changes and emits them
+ * to the global RouteObserver singleton.
+ */
+
+/**
+ * Hook to observe route changes in Expo Router
+ * Automatically emits events to the global RouteObserver
+ *
+ * @param callback - Optional function to call on route changes (in addition to the observer)
+ *
+ * @example
+ * ```tsx
+ * // Just track routes (no custom callback)
+ * useRouteObserver();
+ *
+ * // Track routes with custom callback
+ * useRouteObserver((event) => {
+ *   // Handle route change
+ *   analytics.trackPageView(event.pathname);
+ * });
+ * ```
+ */
+function useRouteObserver(callback) {
+  const pathname = (0, _expoRouter.usePathname)();
+  const segments = (0, _expoRouter.useSegments)();
+  const params = (0, _expoRouter.useGlobalSearchParams)();
+  const callbackRef = (0, _react.useRef)(callback);
+  const previousPathnameRef = (0, _react.useRef)(undefined);
+  const previousTimestampRef = (0, _react.useRef)(undefined);
+
+  // Update ref when callback changes
+  (0, _react.useEffect)(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  // Trigger observer and callback whenever route changes
+  (0, _react.useEffect)(() => {
+    const now = Date.now();
+    const timeSincePrevious = previousTimestampRef.current ? now - previousTimestampRef.current : undefined;
+    const event = {
+      pathname,
+      params: params,
+      segments: segments,
+      timestamp: now,
+      previousPathname: previousPathnameRef.current,
+      timeSincePrevious
+    };
+
+    // Update refs for next navigation
+    previousPathnameRef.current = pathname;
+    previousTimestampRef.current = now;
+
+    // Emit to the global observer (this notifies the modal)
+    _RouteObserver.routeObserver.emit(event);
+
+    // Also call the custom callback if provided
+    if (callbackRef.current) {
+      callbackRef.current(event);
+    }
+  }, [pathname, segments, params]);
+}