@buoy-gg/route-events 1.7.2

package/lib/commonjs/useRouteSitemap.js

@@ -0,0 +1,234 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useParentRoutes = useParentRoutes;
+exports.useRoute = useRoute;
+exports.useRouteSitemap = useRouteSitemap;
+var _react = require("react");
+var _RouteParser = require("./RouteParser");
+var _expoRouterStore = require("./expoRouterStore");
+/**
+ * useRouteSitemap - React hooks for accessing parsed route information
+ *
+ * Provides access to the Expo Router route tree with parsing, filtering,
+ * and search capabilities.
+ */
+
+// Type-only definition to avoid Metro resolution issues
+
+/**
+ * Extract all routes from the navigation state recursively
+ * This builds a RouteNode-like structure from React Navigation's state
+ */
+function buildRouteNodeFromNavigationState(state) {
+  if (!state || !state.routes) return null;
+
+  // Find the app directory structure from the navigation state
+  // The root route usually contains the file-based routing structure
+  const rootRoute = state.routes?.[0];
+  if (!rootRoute) return null;
+
+  // Build a simple route node structure
+  // This will work with the RouteParser
+  const routeNode = {
+    type: 'route',
+    route: '',
+    dynamic: null,
+    children: [],
+    contextKey: '_app'
+  };
+
+  // Recursively collect all routes from the state
+  function collectRoutes(navState, parent, pathPrefix = '') {
+    if (!navState || !navState.routes) return;
+    navState.routes.forEach(route => {
+      const routeName = route.name;
+
+      // Skip internal routes
+      if (routeName.startsWith('__') || routeName.includes('_layout') || routeName.startsWith('+not-found')) {
+        return;
+      }
+
+      // Create a route node
+      const node = {
+        type: routeName === 'index' ? 'route' : 'route',
+        route: routeName === 'index' ? '' : routeName,
+        dynamic: routeName.includes('[') ? [routeName.match(/\[([^\]]+)\]/)?.[1] || ''] : null,
+        children: [],
+        contextKey: `app/${routeName}`
+      };
+      parent.children.push(node);
+
+      // If this route has nested state, recurse
+      if (route.state) {
+        collectRoutes(route.state, node, `${pathPrefix}/${routeName}`);
+      }
+    });
+  }
+  collectRoutes(state, routeNode);
+  return routeNode.children.length > 0 ? routeNode : null;
+}
+
+// ============================================================================
+// Hook Options & Return Types
+// ============================================================================
+
+// ============================================================================
+// Main Hook
+// ============================================================================
+
+/**
+ * Hook to access and parse Expo Router's route tree
+ *
+ * @example
+ * ```tsx
+ * const { routes, groups, stats, filteredRoutes } = useRouteSitemap({
+ *   searchQuery: 'pokemon',
+ *   sortBy: 'path',
+ *   autoRefresh: true
+ * });
+ * ```
+ */
+function useRouteSitemap(options = {}) {
+  const {
+    searchQuery = "",
+    sortBy = "path",
+    autoRefresh = false,
+    refreshInterval = 1000
+  } = options;
+  const [routeTreeState, setRouteTreeState] = (0, _react.useState)(() => {
+    const node = (0, _expoRouterStore.loadRouteNode)();
+    const metadata = (0, _expoRouterStore.getRouteNodeMetadata)();
+    return {
+      node,
+      version: 0,
+      lastUpdatedAt: metadata.lastLoadedAt,
+      source: metadata.source
+    };
+  });
+  const routeNode = routeTreeState.node;
+  const routeNodeVersion = routeTreeState.version;
+  const lastUpdatedAt = routeTreeState.lastUpdatedAt;
+  const source = routeTreeState.source;
+  const refresh = (0, _react.useCallback)(() => {
+    setRouteTreeState(previous => {
+      const node = (0, _expoRouterStore.loadRouteNode)();
+      const metadata = (0, _expoRouterStore.getRouteNodeMetadata)();
+      return {
+        node,
+        version: previous.version + 1,
+        lastUpdatedAt: metadata.lastLoadedAt,
+        source: metadata.source
+      };
+    });
+  }, []);
+
+  // When the route tree isn't available yet (e.g., Expo Router still mounting),
+  // poll until it becomes ready. Use a more aggressive retry since the store
+  // is a singleton that gets populated asynchronously.
+  (0, _react.useEffect)(() => {
+    if (routeNode) {
+      return;
+    }
+    let retryCount = 0;
+    const maxRetries = 100; // 10 seconds max
+
+    const poll = () => {
+      retryCount++;
+      refresh();
+      if (retryCount < maxRetries) {
+        timeoutRef = setTimeout(poll, 100);
+      }
+    };
+    let timeoutRef = setTimeout(poll, 100);
+    return () => clearTimeout(timeoutRef);
+  }, [routeNode, refresh]);
+
+  // Optional auto-refresh hook for callers that want periodic updates
+  (0, _react.useEffect)(() => {
+    if (!autoRefresh) return;
+    const interval = setInterval(refresh, refreshInterval);
+    return () => clearInterval(interval);
+  }, [autoRefresh, refreshInterval, refresh]);
+  const isLoaded = !!routeNode;
+
+  // Parse routes
+  const routes = (0, _react.useMemo)(() => {
+    if (!routeNode) return [];
+    return _RouteParser.RouteParser.parseRouteTree(routeNode);
+  }, [routeNode, routeNodeVersion]);
+
+  // Sort routes
+  const sortedRoutes = (0, _react.useMemo)(() => {
+    return _RouteParser.RouteParser.sortRoutes(routes, sortBy);
+  }, [routes, sortBy]);
+
+  // Filter routes by search query
+  const filteredRoutes = (0, _react.useMemo)(() => {
+    if (!searchQuery) return sortedRoutes;
+    return _RouteParser.RouteParser.filterRoutes(sortedRoutes, searchQuery);
+  }, [sortedRoutes, searchQuery]);
+
+  // Organize into groups
+  const groups = (0, _react.useMemo)(() => {
+    return _RouteParser.RouteParser.organizeRoutes(filteredRoutes);
+  }, [filteredRoutes]);
+
+  // Calculate stats
+  const stats = (0, _react.useMemo)(() => {
+    return _RouteParser.RouteParser.getRouteStats(routes);
+  }, [routes]);
+
+  // Helper functions
+  const findRoute = path => _RouteParser.RouteParser.findRouteByPath(routes, path);
+  const getParents = path => _RouteParser.RouteParser.getParentRoutes(routes, path);
+  return {
+    routes: sortedRoutes,
+    groups,
+    stats,
+    filteredRoutes,
+    isLoaded,
+    refresh,
+    findRoute,
+    getParents,
+    lastUpdatedAt,
+    source
+  };
+}
+
+// ============================================================================
+// Helper Hooks
+// ============================================================================
+
+/**
+ * Get a specific route by path
+ *
+ * @example
+ * ```tsx
+ * const pokemonRoute = useRoute('/pokemon/[id]');
+ * ```
+ */
+function useRoute(path) {
+  const {
+    findRoute
+  } = useRouteSitemap();
+  return (0, _react.useMemo)(() => findRoute(path), [findRoute, path]);
+}
+
+/**
+ * Get all parent routes for a given path
+ *
+ * @example
+ * ```tsx
+ * const parents = useParentRoutes('/pokemon/[id]');
+ * // Returns: [{ path: '/pokemon', ... }]
+ * ```
+ */
+function useParentRoutes(path) {
+  const {
+    getParents
+  } = useRouteSitemap();
+  return (0, _react.useMemo)(() => getParents(path), [getParents, path]);
+}

package/lib/commonjs/utils/safeExpoRouter.js

@@ -0,0 +1,129 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.getSafeRouter = getSafeRouter;
+exports.isExpoRouterAvailable = isExpoRouterAvailable;
+exports.useSafeGlobalSearchParams = useSafeGlobalSearchParams;
+exports.useSafePathname = useSafePathname;
+exports.useSafeRouter = useSafeRouter;
+exports.useSafeSegments = useSafeSegments;
+/**
+ * Safe wrapper for expo-router
+ *
+ * Provides optional imports for expo-router hooks and utilities.
+ * Falls back to no-op implementations when expo-router is not installed.
+ */
+
+let expoRouter = null;
+let isAvailable = false;
+let checkedAvailability = false;
+function checkExpoRouterAvailability() {
+  if (checkedAvailability) return isAvailable;
+  try {
+    expoRouter = require("expo-router");
+    isAvailable = expoRouter != null;
+  } catch (error) {
+    isAvailable = false;
+    expoRouter = null;
+  }
+  checkedAvailability = true;
+  return isAvailable;
+}
+
+// ============================================================================
+// No-op implementations when expo-router is not available
+// ============================================================================
+
+function noOpUseRouter() {
+  return {
+    push: () => console.warn("[route-events] expo-router not installed: push() unavailable"),
+    replace: () => console.warn("[route-events] expo-router not installed: replace() unavailable"),
+    back: () => console.warn("[route-events] expo-router not installed: back() unavailable"),
+    canGoBack: () => false,
+    setParams: () => console.warn("[route-events] expo-router not installed: setParams() unavailable"),
+    navigate: () => console.warn("[route-events] expo-router not installed: navigate() unavailable")
+  };
+}
+function noOpUsePathname() {
+  return "/";
+}
+function noOpUseSegments() {
+  return [];
+}
+function noOpUseGlobalSearchParams() {
+  return {};
+}
+
+// ============================================================================
+// Safe hook exports
+// ============================================================================
+
+function useSafeRouter() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUseRouter();
+  }
+  try {
+    return expoRouter.useRouter();
+  } catch (error) {
+    console.warn("[route-events] Failed to use expo-router.useRouter:", error);
+    return noOpUseRouter();
+  }
+}
+function useSafePathname() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUsePathname();
+  }
+  try {
+    return expoRouter.usePathname();
+  } catch (error) {
+    console.warn("[route-events] Failed to use expo-router.usePathname:", error);
+    return noOpUsePathname();
+  }
+}
+function useSafeSegments() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUseSegments();
+  }
+  try {
+    return expoRouter.useSegments();
+  } catch (error) {
+    console.warn("[route-events] Failed to use expo-router.useSegments:", error);
+    return noOpUseSegments();
+  }
+}
+function useSafeGlobalSearchParams() {
+  if (!checkExpoRouterAvailability()) {
+    return noOpUseGlobalSearchParams();
+  }
+  try {
+    return expoRouter.useGlobalSearchParams();
+  } catch (error) {
+    console.warn("[route-events] Failed to use expo-router.useGlobalSearchParams:", error);
+    return noOpUseGlobalSearchParams();
+  }
+}
+
+// ============================================================================
+// Router instance getter (for imperative navigation)
+// ============================================================================
+
+function getSafeRouter() {
+  if (!checkExpoRouterAvailability()) {
+    return null;
+  }
+  try {
+    return expoRouter.router || null;
+  } catch (error) {
+    return null;
+  }
+}
+
+// ============================================================================
+// Availability check
+// ============================================================================
+
+function isExpoRouterAvailable() {
+  return checkExpoRouterAvailability();
+}

package/lib/commonjs/utils/safeReactNavigation.js

@@ -0,0 +1,104 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.isReactNavigationAvailable = isReactNavigationAvailable;
+exports.useSafeNavigation = useSafeNavigation;
+exports.useSafeNavigationState = useSafeNavigationState;
+var _react = require("react");
+/**
+ * Safe wrapper for @react-navigation/native
+ *
+ * Provides optional imports for React Navigation hooks.
+ * Falls back to no-op implementations when @react-navigation/native is not installed.
+ */
+
+let reactNavigation = null;
+let isAvailable = false;
+let checkedAvailability = false;
+function checkReactNavigationAvailability() {
+  if (checkedAvailability) return isAvailable;
+  try {
+    reactNavigation = require("@react-navigation/native");
+    isAvailable = reactNavigation != null;
+  } catch (error) {
+    isAvailable = false;
+    reactNavigation = null;
+  }
+  checkedAvailability = true;
+  return isAvailable;
+}
+
+// ============================================================================
+// No-op implementations when @react-navigation/native is not available
+// ============================================================================
+
+function noOpUseNavigation() {
+  return (0, _react.useMemo)(() => ({
+    navigate: () => console.warn("[route-events] @react-navigation/native not installed: navigate() unavailable"),
+    goBack: () => console.warn("[route-events] @react-navigation/native not installed: goBack() unavailable"),
+    canGoBack: () => false,
+    reset: () => console.warn("[route-events] @react-navigation/native not installed: reset() unavailable"),
+    setParams: () => console.warn("[route-events] @react-navigation/native not installed: setParams() unavailable"),
+    dispatch: () => console.warn("[route-events] @react-navigation/native not installed: dispatch() unavailable"),
+    isFocused: () => true,
+    addListener: () => () => {},
+    removeListener: () => {},
+    getParent: () => undefined,
+    getState: () => undefined,
+    getId: () => undefined
+  }), []);
+}
+function noOpUseNavigationState(selector) {
+  return (0, _react.useMemo)(() => {
+    // Return a minimal state structure
+    const emptyState = {
+      key: "default",
+      index: 0,
+      routeNames: [],
+      routes: [],
+      type: "stack"
+    };
+    try {
+      return selector ? selector(emptyState) : emptyState;
+    } catch {
+      return emptyState;
+    }
+  }, [selector]);
+}
+
+// ============================================================================
+// Safe hook exports
+// ============================================================================
+
+function useSafeNavigation() {
+  if (!checkReactNavigationAvailability()) {
+    return noOpUseNavigation();
+  }
+  try {
+    return reactNavigation.useNavigation();
+  } catch (error) {
+    console.warn("[route-events] Failed to use @react-navigation/native.useNavigation:", error);
+    return noOpUseNavigation();
+  }
+}
+function useSafeNavigationState(selector) {
+  if (!checkReactNavigationAvailability()) {
+    return noOpUseNavigationState(selector);
+  }
+  try {
+    return reactNavigation.useNavigationState(selector);
+  } catch (error) {
+    console.warn("[route-events] Failed to use @react-navigation/native.useNavigationState:", error);
+    return noOpUseNavigationState(selector);
+  }
+}
+
+// ============================================================================
+// Availability check
+// ============================================================================
+
+function isReactNavigationAvailable() {
+  return checkReactNavigationAvailability();
+}

package/lib/module/RouteObserver.js

@@ -0,0 +1,49 @@
+"use strict";
+
+/**
+ * RouteObserver - Tracks route changes in Expo Router
+ *
+ * Note: This is a simple event emitter that works with the useRouteObserver hook
+ * The actual route tracking happens in the hook using public Expo Router APIs
+ */
+
+export class RouteObserver {
+  listeners = new Set();
+
+  /**
+   * Emit a route change event
+   * Called by the useRouteObserver hook
+   */
+  emit(event) {
+    // Notify all listeners
+    this.listeners.forEach(listener => {
+      try {
+        listener(event);
+      } catch (error) {
+        console.error("[RouteObserver] Error in listener:", error);
+      }
+    });
+  }
+
+  /**
+   * Add listener for route changes
+   * @returns Cleanup function to remove the listener
+   */
+  addListener(callback) {
+    this.listeners.add(callback);
+    return () => this.listeners.delete(callback);
+  }
+
+  /**
+   * Remove a specific listener
+   */
+  removeListener(callback) {
+    this.listeners.delete(callback);
+  }
+}
+
+/**
+ * Singleton instance of RouteObserver
+ * Use this for all route tracking to ensure events are centralized
+ */
+export const routeObserver = new RouteObserver();