react-native-debug-toolkit 0.6.3 → 2.0.0

package/src/features/ZustandLogFeature.ts

@@ -0,0 +1,127 @@
+import { ZustandLogTab } from '../components/ZustandLogTab';
+import type { DebugFeature, ZustandLogEntry } from '../types';
+import { createEventChannel } from '../utils/createEventChannel';
+import { createObservableStore } from '../utils/createObservableStore';
+
+type ZustandLogPayload = Omit<ZustandLogEntry, 'id'>;
+
+const DEFAULT_MAX_LOGS = 200;
+const zustandChannel = createEventChannel<ZustandLogPayload>();
+
+export const addZustandLog = (
+  action: string,
+  prevState: unknown,
+  nextState: unknown,
+  actionCompleteTime?: number,
+  storeName?: string,
+): void => {
+  zustandChannel.emit({
+    timestamp: Date.now(),
+    action,
+    prevState,
+    nextState,
+    actionCompleteTime,
+    storeName,
+  });
+};
+
+type ZustandSetState<T> = (
+  partial: T | Partial<T> | ((state: T) => Partial<T> | T),
+  replace?: boolean | undefined,
+  action?: string | { type: unknown } | undefined,
+) => void;
+
+type ZustandGetState<T> = () => T;
+
+interface ZustandStoreApi<T> {
+  getState: () => T;
+  setState: ZustandSetState<T>;
+  subscribe: (listener: (state: T, prevState: T) => void) => () => void;
+  name?: string;
+}
+
+type ZustandConfig<T> = (
+  set: ZustandSetState<T>,
+  get: ZustandGetState<T>,
+  api: ZustandStoreApi<T>,
+) => T;
+
+/**
+ * Zustand middleware that logs all state changes to the debug toolkit.
+ *
+ * Usage:
+ * ```ts
+ * const useStore = create(zustandLogMiddleware((set) => ({ ... })))
+ * ```
+ */
+export const zustandLogMiddleware = <T>(config: ZustandConfig<T>) => (
+  set: ZustandSetState<T>,
+  get: ZustandGetState<T>,
+  api: ZustandStoreApi<T>,
+) =>
+  config(
+    (args: Parameters<ZustandSetState<T>>[0], replace?: boolean, actionName?: string | { type: unknown }) => {
+      const prevState = get();
+      const startTime = Date.now();
+      set(args, replace, actionName);
+      const duration = Date.now() - startTime;
+      const label = typeof actionName === 'string'
+        ? actionName
+        : typeof args === 'function' ? 'setState' : 'object-set';
+      addZustandLog(
+        label,
+        prevState,
+        get(),
+        duration,
+        api.name,
+      );
+    },
+    get,
+    api,
+  );
+
+export interface ZustandFeatureConfig {
+  /** Maximum number of zustand state changes to keep (default: 200) */
+  maxLogs?: number;
+}
+
+export const createZustandLogFeature = (config?: ZustandFeatureConfig): DebugFeature<ZustandLogEntry> => {
+  const maxLogs = config?.maxLogs ?? DEFAULT_MAX_LOGS;
+  const logStore = createObservableStore<ZustandLogEntry>();
+  let nextId = 0;
+  let unsubscribeLogs: (() => void) | null = null;
+  let initialized = false;
+
+  return {
+    name: 'zustand',
+    label: 'Zustand',
+    renderContent: ZustandLogTab,
+    setup: () => {
+      if (initialized) {
+        return;
+      }
+
+      unsubscribeLogs = zustandChannel.subscribe((entry) => {
+        logStore.push(
+          {
+            ...entry,
+            id: String(nextId++),
+          },
+          maxLogs,
+        );
+      });
+      initialized = true;
+    },
+    getData: () => logStore.getData(),
+    clear: () => {
+      logStore.clear();
+    },
+    cleanup: () => {
+      unsubscribeLogs?.();
+      unsubscribeLogs = null;
+      logStore.clear();
+      initialized = false;
+    },
+    subscribe: (listener) => logStore.subscribe(listener),
+  };
+};

package/src/hooks/useNavigationLogger.ts

@@ -0,0 +1,107 @@
+import { useEffect, useRef } from 'react';
+import { addNavigationLog } from '../features/NavigationLogFeature';
+import { safeStringify } from '../utils/safeStringify';
+
+interface NavigationContainerRef {
+  getCurrentRoute?: () => { name?: string } | undefined;
+  getRootState?: () => unknown;
+  addListener: (event: string, callback: () => void) => () => void;
+}
+
+function getActiveRouteName(state: unknown): string {
+  let currentState = state as
+    | {
+        index?: number;
+        routes?: Array<{ name?: string; state?: unknown }>;
+      }
+    | undefined;
+
+  while (currentState?.routes && typeof currentState.index === 'number') {
+    const route = currentState.routes[currentState.index];
+    if (!route) {
+      return '';
+    }
+    if (!route.state) {
+      return route.name ?? '';
+    }
+    currentState = route.state as typeof currentState;
+  }
+
+  return '';
+}
+
+
+/**
+ * Hook to automatically log React Navigation events.
+ *
+ * Usage:
+ * ```tsx
+ * const navigationRef = useRef<NavigationContainerRef>(null);
+ * useNavigationLogger(navigationRef);
+ * return <NavigationContainer ref={navigationRef}>...</NavigationContainer>;
+ * ```
+ */
+export function useNavigationLogger(navigationRef: React.RefObject<NavigationContainerRef | null>) {
+  const previousRouteNameRef = useRef('');
+
+  useEffect(() => {
+    let timeoutId: ReturnType<typeof setTimeout> | undefined;
+    let unsubscribe: (() => void) | undefined;
+    let disposed = false;
+
+    const attachListener = () => {
+      if (disposed) {
+        return;
+      }
+
+      const ref = navigationRef.current;
+      if (!ref || typeof ref.addListener !== 'function') {
+        timeoutId = setTimeout(attachListener, 250);
+        return;
+      }
+
+      const currentRouteName =
+        ref.getCurrentRoute?.()?.name ||
+        getActiveRouteName(ref.getRootState?.());
+      if (currentRouteName) {
+        previousRouteNameRef.current = currentRouteName;
+      }
+
+      unsubscribe = ref.addListener('state', () => {
+        try {
+          const navState = ref.getRootState?.();
+          const nextRouteName =
+            ref.getCurrentRoute?.()?.name ||
+            getActiveRouteName(navState);
+
+          if (!nextRouteName || nextRouteName === previousRouteNameRef.current) {
+            return;
+          }
+
+          addNavigationLog(
+            'navigate',
+            previousRouteNameRef.current,
+            nextRouteName,
+            undefined,
+            undefined,
+            safeStringify(navState),
+          );
+
+          previousRouteNameRef.current = nextRouteName;
+        } catch {
+          // Navigation state may not be ready
+        }
+      });
+    };
+
+    attachListener();
+
+    return () => {
+      disposed = true;
+      if (timeoutId) {
+        clearTimeout(timeoutId);
+      }
+      unsubscribe?.();
+    };
+  }, [navigationRef]);
+}

package/src/hooks/useSlideDetailAnimation.ts

@@ -0,0 +1,45 @@
+import { useEffect, useRef } from 'react';
+import { Animated } from 'react-native';
+
+/**
+ * Shared slide-in/out animation for tab detail views.
+ * Returns animated styles for the detail overlay and the list behind it.
+ */
+export function useSlideDetailAnimation<T>(
+  selected: T | null,
+): {
+  detailTranslateX: Animated.AnimatedInterpolation<number>;
+  listTranslateX: Animated.AnimatedInterpolation<number>;
+  listOpacity: Animated.AnimatedInterpolation<number>;
+} {
+  const slideAnim = useRef(new Animated.Value(0)).current;
+  const listSlideAnim = useRef(new Animated.Value(0)).current;
+
+  useEffect(() => {
+    if (selected) {
+      listSlideAnim.setValue(0);
+      Animated.parallel([
+        Animated.spring(slideAnim, { toValue: 1, friction: 9, tension: 60, useNativeDriver: true }),
+        Animated.spring(listSlideAnim, { toValue: 1, friction: 9, tension: 60, useNativeDriver: true }),
+      ]).start();
+    } else {
+      slideAnim.setValue(0);
+      listSlideAnim.setValue(0);
+    }
+  }, [selected, slideAnim, listSlideAnim]);
+
+  const detailTranslateX = slideAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [300, 0],
+  });
+  const listTranslateX = listSlideAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [0, -60],
+  });
+  const listOpacity = listSlideAnim.interpolate({
+    inputRange: [0, 1],
+    outputRange: [1, 0],
+  });
+
+  return { detailTranslateX, listTranslateX, listOpacity };
+}

package/src/index.ts

@@ -0,0 +1,52 @@
+// Core
+export { DebugToolkit } from './core/DebugToolkit';
+export { DebugToolkitProvider, useDebugToolkit } from './core/DebugToolkitProvider';
+export { initializeDebugToolkit, isDebugMode } from './initialize';
+export type { InitializeOptions, FeatureConfigs } from './initialize';
+
+// Feature factories
+export { createNetworkFeature } from './features/NetworkFeature';
+export type { NetworkFeatureAPI, NetworkFeatureConfig } from './features/NetworkFeature';
+export { createConsoleLogFeature } from './features/ConsoleLogFeature';
+export type { ConsoleFeatureConfig } from './features/ConsoleLogFeature';
+export { createZustandLogFeature, zustandLogMiddleware, addZustandLog } from './features/ZustandLogFeature';
+export type { ZustandFeatureConfig } from './features/ZustandLogFeature';
+export { createNavigationLogFeature, addNavigationLog } from './features/NavigationLogFeature';
+export type { NavigationFeatureConfig } from './features/NavigationLogFeature';
+export { createTrackFeature, addTrackLog } from './features/TrackFeature';
+export type { TrackFeatureConfig, TrackEventData } from './features/TrackFeature';
+export { createThirdPartyLibsFeature } from './features/ThirdPartyLibsFeature';
+export { createEnvironmentFeature } from './features/EnvironmentFeature';
+export type { EnvironmentFeatureAPI } from './features/EnvironmentFeature';
+export { createClipboardFeature } from './features/ClipboardFeature';
+
+// Hooks
+export { useNavigationLogger } from './hooks/useNavigationLogger';
+export { useSlideDetailAnimation } from './hooks/useSlideDetailAnimation';
+
+// Utilities
+export { safeStringify } from './utils/safeStringify';
+export { copyToComputer, logToComputer, fmt } from './utils/copyToComputer';
+export type { CopyResult, CopyOptions, CopyMethod } from './utils/copyToComputer';
+
+// Types
+export type {
+  BuiltInFeatureName,
+  DebugFeature,
+  DebugFeatureFactory,
+  DebugFeatureInput,
+  DebugFeatureRenderProps,
+  DebugToolkitConfig,
+  DebugToolkitAPI,
+  NetworkLogEntry,
+  ConsoleLogEntry,
+  ZustandLogEntry,
+  NavigationLogEntry,
+  TrackLogEntry,
+  ThirdPartyLib,
+  EnvironmentConfig,
+  EnvironmentState,
+} from './types';
+
+// Default export for convenience
+export { initializeDebugToolkit as default } from './initialize';

package/src/initialize.ts

@@ -0,0 +1,214 @@
+import { DebugToolkit } from './core/DebugToolkit';
+import { createNetworkFeature } from './features/NetworkFeature';
+import type { NetworkFeatureConfig } from './features/NetworkFeature';
+import { createConsoleLogFeature } from './features/ConsoleLogFeature';
+import type { ConsoleFeatureConfig } from './features/ConsoleLogFeature';
+import { createZustandLogFeature } from './features/ZustandLogFeature';
+import type { ZustandFeatureConfig } from './features/ZustandLogFeature';
+import { createNavigationLogFeature } from './features/NavigationLogFeature';
+import type { NavigationFeatureConfig } from './features/NavigationLogFeature';
+import { createTrackFeature } from './features/TrackFeature';
+import type { TrackFeatureConfig } from './features/TrackFeature';
+import { createThirdPartyLibsFeature } from './features/ThirdPartyLibsFeature';
+import { createEnvironmentFeature } from './features/EnvironmentFeature';
+import { createClipboardFeature } from './features/ClipboardFeature';
+import { NativeDebugLibs } from './native/NativeDebugLibs';
+import type {
+  BuiltInFeatureName,
+  DebugFeature,
+  DebugFeatureInput,
+} from './types';
+
+export const isDebugMode = __DEV__;
+
+/** Feature-specific configuration map */
+export interface FeatureConfigs {
+  network?: boolean | NetworkFeatureConfig;
+  console?: boolean | ConsoleFeatureConfig;
+  zustand?: boolean | ZustandFeatureConfig;
+  navigation?: boolean | NavigationFeatureConfig;
+  track?: boolean | TrackFeatureConfig;
+  thirdPartyLibs?: boolean;
+  environment?: Parameters<typeof createEnvironmentFeature>[0];
+  clipboard?: boolean;
+}
+
+export interface InitializeOptions {
+  doraemonProductId?: string;
+  enabled?: boolean;
+}
+
+/** Registry mapping feature names to creator functions */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+const featureRegistry: Record<BuiltInFeatureName, (config?: any) => DebugFeature<any>> = {
+  network: createNetworkFeature,
+  console: createConsoleLogFeature,
+  zustand: createZustandLogFeature,
+  navigation: createNavigationLogFeature,
+  track: createTrackFeature,
+  thirdPartyLibs: createThirdPartyLibsFeature,
+  environment: createEnvironmentFeature,
+  clipboard: createClipboardFeature,
+};
+
+const DEFAULT_FEATURES: BuiltInFeatureName[] = [
+  'network',
+  'console',
+  'navigation',
+  'zustand',
+  'track',
+  'thirdPartyLibs',
+  'clipboard',
+];
+
+function resolveFeatures(
+  features: DebugFeatureInput[],
+): DebugFeature<any>[] {
+  return features.reduce<DebugFeature<any>[]>((resolvedFeatures, identifier) => {
+    let feature: DebugFeature<any> | null = null;
+
+    if (typeof identifier === 'string') {
+      const creator = featureRegistry[identifier as BuiltInFeatureName];
+      if (!creator) {
+        console.warn(`[DebugToolkit] Unknown feature: "${identifier}"`);
+        return resolvedFeatures;
+      }
+      feature = creator();
+    } else if (typeof identifier === 'function') {
+      try {
+        feature = identifier();
+      } catch (error) {
+        console.error('[DebugToolkit] Feature creator failed:', error);
+        return resolvedFeatures;
+      }
+    } else if (identifier && typeof identifier === 'object' && identifier.name) {
+      feature = identifier;
+    } else {
+      console.warn('[DebugToolkit] Invalid feature identifier:', identifier);
+      return resolvedFeatures;
+    }
+
+    if (feature) {
+      resolvedFeatures.push(feature);
+    }
+
+    return resolvedFeatures;
+  }, []);
+}
+
+/**
+ * Resolve feature configs to DebugFeature instances.
+ */
+function resolveFeatureConfigs(configs: FeatureConfigs): DebugFeature<any>[] {
+  const features: DebugFeature<any>[] = [];
+
+  const entries = Object.entries(configs) as [BuiltInFeatureName, unknown][];
+
+  for (const [name, config] of entries) {
+    // Skip false/explicitly disabled
+    if (config === false) continue;
+
+    const creator = featureRegistry[name];
+    if (!creator) {
+      console.warn(`[DebugToolkit] Unknown feature: "${name}"`);
+      continue;
+    }
+
+    // config === true or undefined → use defaults
+    if (config === true || config === undefined) {
+      features.push(creator());
+    } else if (typeof config === 'object') {
+      features.push(creator(config as Record<string, unknown>));
+    }
+  }
+
+  return features;
+}
+
+/**
+ * Initialize the debug toolkit.
+ *
+ * @param featuresOrOptions - Either an array of feature inputs (legacy), or a full config object.
+ * @param options - Options when using legacy array mode.
+ *
+ * @example
+ * // Legacy mode (still supported)
+ * initializeDebugToolkit(['network', 'console'], { enabled: true });
+ *
+ * // Config object mode (recommended)
+ * initializeDebugToolkit({
+ *   features: {
+ *     network: { maxLogs: 100 },
+ *     console: true,
+ *     track: true,
+ *     environment: { environments: [...] },
+ *   },
+ *   enabled: true,
+ * });
+ */
+export function initializeDebugToolkit(
+  featuresOrOptions?: DebugFeatureInput[] | {
+    features?: FeatureConfigs;
+    enabled?: boolean;
+    doraemonProductId?: string;
+  },
+  options: InitializeOptions = {},
+): DebugToolkit | null {
+  // Determine which mode we're in
+  let resolvedFeatures: DebugFeature<any>[];
+  let enabled: boolean;
+  let doraemonProductId: string | undefined;
+
+  if (Array.isArray(featuresOrOptions)) {
+    // Legacy mode
+    resolvedFeatures = resolveFeatures(featuresOrOptions);
+    enabled = options.enabled ?? isDebugMode;
+    doraemonProductId = options.doraemonProductId;
+  } else if (featuresOrOptions && typeof featuresOrOptions === 'object' && !('name' in featuresOrOptions)) {
+    // Config object mode
+    const config = featuresOrOptions;
+    enabled = config.enabled ?? isDebugMode;
+    doraemonProductId = config.doraemonProductId;
+
+    if (config.features) {
+      resolvedFeatures = resolveFeatureConfigs(config.features);
+    } else {
+      resolvedFeatures = resolveFeatures(DEFAULT_FEATURES);
+    }
+  } else {
+    // Default - no args or single feature
+    resolvedFeatures = resolveFeatures(
+      featuresOrOptions ? [featuresOrOptions as DebugFeatureInput] : DEFAULT_FEATURES,
+    );
+    enabled = options.enabled ?? isDebugMode;
+    doraemonProductId = options.doraemonProductId;
+  }
+
+  try {
+    const toolkit = DebugToolkit.getInstance(enabled);
+    toolkit.setEnabled(enabled);
+
+    if (!enabled) {
+      toolkit.reset();
+      return toolkit;
+    }
+
+    // Initialize native debug libs if configured
+    if (doraemonProductId) {
+      NativeDebugLibs.installDoraemonKit(doraemonProductId);
+    }
+
+    toolkit.replaceFeatures(resolvedFeatures);
+
+    if (toolkit.hasFeatures()) {
+      toolkit.showPanel();
+    } else {
+      toolkit.hidePanel();
+    }
+
+    return toolkit;
+  } catch (error) {
+    console.error('[DebugToolkit] Initialization failed:', error);
+    return null;
+  }
+}

package/src/native/NativeDebugLibs.ts

@@ -0,0 +1,74 @@
+import { NativeModules, Platform } from 'react-native';
+
+interface RNDebugLibsType {
+  showExplorer?(): void;
+  hideExplorer?(): void;
+  toggleExplorer?(): void;
+  installDoraemonKit?(productId: string): void;
+  showDoraemonKit?(): void;
+  hideDoraemonKit?(): void;
+}
+
+interface BuildTypeModuleType {
+  getBuildType(): Promise<string | null>;
+  getBuildTypeSync(): string | null;
+}
+
+const RNDebugLibs: RNDebugLibsType = NativeModules.RNDebugLibs ?? {};
+const BuildTypeModule: BuildTypeModuleType | null = NativeModules.BuildTypeModule ?? null;
+
+export const NativeDebugLibs = {
+  getBuildType(): Promise<string | null> {
+    if (BuildTypeModule) {
+      return BuildTypeModule.getBuildType();
+    }
+    return Promise.resolve(null);
+  },
+
+  getBuildTypeSync(): string | null {
+    if (BuildTypeModule) {
+      return BuildTypeModule.getBuildTypeSync();
+    }
+    return null;
+  },
+
+  isDebugBuild(): boolean {
+    if (BuildTypeModule) {
+      return BuildTypeModule.getBuildTypeSync() === 'debug';
+    }
+    // Fallback: assume __DEV__ is the source of truth
+    return __DEV__;
+  },
+
+  // FLEX (iOS only)
+  showExplorer(): void {
+    if (Platform.OS === 'ios' && RNDebugLibs.showExplorer) {
+      RNDebugLibs.showExplorer();
+    }
+  },
+
+  hideExplorer(): void {
+    if (Platform.OS === 'ios' && RNDebugLibs.hideExplorer) {
+      RNDebugLibs.hideExplorer();
+    }
+  },
+
+  // DoraemonKit
+  installDoraemonKit(productId: string): void {
+    if (RNDebugLibs.installDoraemonKit) {
+      RNDebugLibs.installDoraemonKit(productId);
+    }
+  },
+
+  showDoraemonKit(): void {
+    if (RNDebugLibs.showDoraemonKit) {
+      RNDebugLibs.showDoraemonKit();
+    }
+  },
+
+  hideDoraemonKit(): void {
+    if (RNDebugLibs.hideDoraemonKit) {
+      RNDebugLibs.hideDoraemonKit();
+    }
+  },
+};