react-native-debug-toolkit 0.6.4 → 2.0.0

package/src/types/index.ts

@@ -0,0 +1,138 @@
+import type { ComponentType } from 'react';
+
+export type DebugFeatureListener = () => void;
+
+export type BuiltInFeatureName =
+  | 'network'
+  | 'console'
+  | 'zustand'
+  | 'navigation'
+  | 'track'
+  | 'thirdPartyLibs'
+  | 'environment'
+  | 'clipboard';
+
+export interface DebugFeatureRenderProps<TData = unknown> {
+  data: TData[];
+  feature: DebugFeature<TData>;
+}
+
+export type DebugFeatureRenderer<TData = unknown> = ComponentType<
+  DebugFeatureRenderProps<TData>
+>;
+
+export type DebugFeatureFactory = () => DebugFeature<any>;
+
+export type DebugFeatureInput =
+  | BuiltInFeatureName
+  | DebugFeature<any>
+  | DebugFeatureFactory;
+
+/** Base interface all debug features must implement */
+export interface DebugFeature<TData = unknown> {
+  name: string;
+  label: string;
+  setup: () => void;
+  getData: () => TData[];
+  clear?: () => void;
+  cleanup: () => void;
+  subscribe?: (listener: DebugFeatureListener) => () => void;
+  renderContent?: DebugFeatureRenderer<TData>;
+  badge?: () => { label: string; color: string } | null;
+}
+
+export interface NetworkLogEntry {
+  id: string;
+  timestamp: number;
+  duration?: number;
+  request: {
+    url: string;
+    method: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+  };
+  response?: {
+    status: number;
+    statusText?: string;
+    headers?: Record<string, string>;
+    data?: unknown;
+    success?: boolean;
+  };
+  error?: string;
+}
+
+export interface ConsoleLogEntry {
+  id: string;
+  timestamp: number;
+  level: 'log' | 'info' | 'warn' | 'error';
+  data: unknown[];
+}
+
+export interface ZustandLogEntry {
+  id: string;
+  timestamp: number;
+  action: string;
+  prevState: unknown;
+  nextState: unknown;
+  actionCompleteTime?: number;
+  storeName?: string;
+}
+
+export interface NavigationLogEntry {
+  id: string;
+  timestamp: number;
+  action: string;
+  from: string;
+  to: string;
+  startTime?: number;
+  duration?: number;
+  debugLog?: string;
+}
+
+export interface TrackLogEntry {
+  id: string;
+  timestamp: number;
+  eventName: string;
+  [key: string]: unknown;
+}
+
+export interface ThirdPartyLib {
+  id: string;
+  name: string;
+  description: string;
+  platform: 'ios' | 'android' | 'both';
+  actions: Array<{
+    id: string;
+    label: string;
+    onPress: () => void;
+  }>;
+}
+
+export interface EnvironmentConfig {
+  id: string;
+  label: string;
+  host: string;
+  color?: string;
+}
+
+export interface EnvironmentState {
+  environments: EnvironmentConfig[];
+  currentEnvironmentId: string | null;
+}
+
+export interface DebugToolkitConfig {
+  features?: DebugFeatureInput[];
+  enabled?: boolean;
+  /** Maximum number of log entries per feature (default: 200) */
+  maxLogsPerFeature?: number;
+}
+
+export interface DebugToolkitAPI {
+  readonly features: ReadonlyArray<DebugFeature<any>>;
+  addFeature: (feature: DebugFeature<any>) => void;
+  removeFeature: (name: string) => void;
+  showPanel: () => void;
+  hidePanel: () => void;
+  clearAll: () => void;
+  destroy: () => void;
+}

package/src/utils/constants.ts

@@ -0,0 +1,91 @@
+import { Dimensions } from 'react-native';
+
+const { width: screenWidth, height: screenHeight } = Dimensions.get('window');
+
+export const Layout = {
+  screenWidth,
+  screenHeight,
+  iconSize: 52,
+} as const;
+
+// Apple iOS System Color Palette
+export const Colors = {
+  // System
+  primary: '#007AFF',
+  text: '#1C1C1E',
+  textSecondary: '#8E8E93',
+  textLight: '#C7C7CC',
+  border: '#E5E5EA',
+  opaqueSeparator: '#C6C6C8',
+  background: '#F2F2F7',
+  surface: '#FFFFFF',
+
+  // Semantic
+  success: '#34C759',
+  error: '#FF3B30',
+  warning: '#FF9500',
+  info: '#5AC8FA',
+
+  // iOS Accent Colors
+  blue: '#007AFF',
+  green: '#34C759',
+  indigo: '#5856D6',
+  orange: '#FF9500',
+  pink: '#FF2D55',
+  purple: '#AF52DE',
+  red: '#FF3B30',
+  teal: '#5AC8FA',
+  yellow: '#FFCC00',
+
+  // HTTP Method Colors
+  get: '#007AFF',
+  post: '#34C759',
+  put: '#FF9500',
+  delete: '#FF3B30',
+  patch: '#5AC8FA',
+} as const;
+
+export const getMethodColor = (method: string): string => {
+  switch (method.toUpperCase()) {
+    case 'GET': return Colors.get;
+    case 'POST': return Colors.post;
+    case 'PUT': return Colors.put;
+    case 'DELETE': return Colors.delete;
+    case 'PATCH': return Colors.patch;
+    default: return Colors.textSecondary;
+  }
+};
+
+// iOS 8pt Grid Spacing
+export const Spacing = {
+  xs: 4,
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 20,
+  xxl: 24,
+} as const;
+
+// iOS Border Radius
+export const Radius = {
+  sm: 8,
+  md: 12,
+  lg: 16,
+  xl: 20,
+  full: 999,
+} as const;
+
+// iOS Typography Scale
+export const Typography = {
+  largeTitle: { fontSize: 34, fontWeight: '700' as const },
+  title1: { fontSize: 28, fontWeight: '700' as const },
+  title2: { fontSize: 22, fontWeight: '700' as const },
+  title3: { fontSize: 20, fontWeight: '600' as const },
+  headline: { fontSize: 17, fontWeight: '600' as const },
+  body: { fontSize: 17, fontWeight: '400' as const },
+  callout: { fontSize: 16, fontWeight: '400' as const },
+  subheadline: { fontSize: 15, fontWeight: '400' as const },
+  footnote: { fontSize: 13, fontWeight: '400' as const },
+  caption1: { fontSize: 12, fontWeight: '400' as const },
+  caption2: { fontSize: 11, fontWeight: '400' as const },
+} as const;

package/src/utils/copyToComputer.ts

@@ -0,0 +1,104 @@
+type ClipboardModule = { setString: (value: string) => void };
+
+let clipboardModule: ClipboardModule | null = null;
+let clipboardChecked = false;
+
+function getClipboardModule(): ClipboardModule | null {
+  if (clipboardChecked) return clipboardModule;
+  clipboardChecked = true;
+  try {
+    // Check native module exists first — getEnforcing() inside the clipboard
+    // package throws a fatal Invariant Violation that bypasses try/catch.
+    const { TurboModuleRegistry } = require('react-native');
+    if (!TurboModuleRegistry.get('RNCClipboard')) {
+      return null;
+    }
+    clipboardModule = require('@react-native-clipboard/clipboard').default;
+  } catch {
+    clipboardModule = null;
+  }
+  return clipboardModule;
+}
+
+export type CopyMethod = 'clipboard' | 'console' | 'none';
+
+export interface CopyResult {
+  success: boolean;
+  method: CopyMethod;
+}
+
+export interface CopyOptions {
+  /** Descriptive label for console.log identification */
+  label?: string;
+  /** If true, only copy to clipboard without console.log */
+  silent?: boolean;
+}
+
+const MAX_LOG_SIZE = 10 * 1024; // 10KB
+
+/**
+ * Format data for copying (pretty JSON or raw string).
+ */
+export function fmt(data: unknown): string {
+  if (!data) return '';
+  try {
+    return JSON.stringify(typeof data === 'string' ? JSON.parse(data) : data, null, 2);
+  } catch {
+    return String(data);
+  }
+}
+
+/**
+ * Log content to console (Metro terminal / DevTools) with a structured prefix.
+ * ConsoleLogFeature intercepts console.log but still calls the original first,
+ * so output reliably appears in Metro terminal.
+ */
+export function logToComputer(content: string, label?: string): void {
+  try {
+    const header = label ? `[DebugToolkit:Copy] ─── ${label} ───` : '[DebugToolkit:Copy] ─── Content ───';
+    console.log(header);
+
+    if (content.length > MAX_LOG_SIZE) {
+      console.log(content.slice(0, MAX_LOG_SIZE));
+      console.log(`[DebugToolkit:Copy] ... truncated (${content.length} bytes total)`);
+    } else {
+      console.log(content);
+    }
+
+    console.log('[DebugToolkit:Copy] ─── END ───');
+  } catch {
+    // Silently fail — console may not be available in all environments
+  }
+}
+
+/**
+ * Copy content to computer via the best available method.
+ *
+ * 1. Attempts device clipboard (if @react-native-clipboard/clipboard is installed)
+ * 2. Always console.logs with structured prefix (appears in Metro terminal)
+ * 3. Returns result indicating what succeeded
+ */
+export function copyToComputer(content: string, options?: CopyOptions): CopyResult {
+  let method: CopyMethod = 'none';
+
+  // Try clipboard
+  try {
+    const clipboard = getClipboardModule();
+    if (clipboard) {
+      clipboard.setString(content);
+      method = 'clipboard';
+    }
+  } catch {
+    // Clipboard may fail, continue
+  }
+
+  // Always log to computer console (unless silent)
+  if (!options?.silent) {
+    logToComputer(content, options?.label);
+    if (method === 'none') {
+      method = 'console';
+    }
+  }
+
+  return { success: true, method };
+}

package/src/utils/createEventChannel.ts

@@ -0,0 +1,22 @@
+export type EventListener<TEvent> = (event: TEvent) => void;
+
+export interface EventChannel<TEvent> {
+  emit: (event: TEvent) => void;
+  subscribe: (listener: EventListener<TEvent>) => () => void;
+}
+
+export function createEventChannel<TEvent>(): EventChannel<TEvent> {
+  const listeners = new Set<EventListener<TEvent>>();
+
+  return {
+    emit: (event) => {
+      listeners.forEach((listener) => listener(event));
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/utils/createObservableStore.ts

@@ -0,0 +1,42 @@
+export type StoreListener = () => void;
+
+export interface ObservableStore<T> {
+  getData: () => T[];
+  push: (item: T, maxEntries?: number) => void;
+  clear: () => void;
+  subscribe: (listener: StoreListener) => () => void;
+}
+
+export function createObservableStore<T>(): ObservableStore<T> {
+  let data: T[] = [];
+  const listeners = new Set<StoreListener>();
+
+  const notify = () => {
+    listeners.forEach((listener) => listener());
+  };
+
+  return {
+    getData: () => data,
+    push: (item, maxEntries) => {
+      if (maxEntries && data.length >= maxEntries) {
+        data = [...data.slice(data.length - maxEntries + 1), item];
+      } else {
+        data = [...data, item];
+      }
+      notify();
+    },
+    clear: () => {
+      if (data.length === 0) {
+        return;
+      }
+      data = [];
+      notify();
+    },
+    subscribe: (listener) => {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+  };
+}

package/src/utils/safeStringify.ts

@@ -0,0 +1,25 @@
+/**
+ * Safely stringify a value to JSON, handling circular references
+ * and values that can't be serialized.
+ */
+export function safeStringify(value: unknown, space?: number): string {
+  try {
+    const seen = new WeakSet();
+
+    return JSON.stringify(
+      value,
+      (_, val) => {
+        if (typeof val === 'object' && val !== null) {
+          if (seen.has(val)) {
+            return '[Circular]';
+          }
+          seen.add(val);
+        }
+        return val;
+      },
+      space,
+    );
+  } catch {
+    return String(value);
+  }
+}

package/.cursor/rules/react-native.mdc

@@ -1,41 +0,0 @@
----
-description: 
-globs: 
-alwaysApply: false
----
-
-  You are an expert in TypeScript, React Native, Expo, and Mobile App Development.
-  
-  Code Style and Structure:
-  - Write concise, type-safe TypeScript code.
-  - Use functional components and hooks over class components.
-  - Ensure components are modular, reusable, and maintainable.
-  - Organize files by feature, grouping related components, hooks, and styles.
-  
-  Naming Conventions:
-  - Use camelCase for variable and function names (e.g., `isFetchingData`, `handleUserInput`).
-  - Use PascalCase for component names (e.g., `UserProfile`, `ChatScreen`).
-  
-  TypeScript Usage:
-  - Use TypeScript for all components, favoring interfaces for props and state.
-  - Enable strict typing in `tsconfig.json`.
-  - Avoid using `any`; strive for precise types.
-  - Utilize `React.FC` for defining functional components with props.
-  
-  Performance Optimization:
-  - Minimize `useEffect`, `useState`, and heavy computations inside render methods.
-  - Use `React.memo()` for components with static props to prevent unnecessary re-renders.
-  - Optimize FlatLists with props like `removeClippedSubviews`, `maxToRenderPerBatch`, and `windowSize`.
-  - Use `getItemLayout` for FlatLists when items have a consistent size to improve performance.
-  - Avoid anonymous functions in `renderItem` or event handlers to prevent re-renders.
-  
-  UI and Styling:
-  - Use consistent styling, either through `StyleSheet.create()` or Styled Components.
-  - Ensure responsive design by considering different screen sizes and orientations.
-  - Optimize image handling using libraries designed for React Native
-  
-  Best Practices:
-  - Follow React Native's threading model to ensure smooth UI performance.
-  - Utilize CodePush Build and Updates for continuous deployment and Over-The-Air (OTA) updates.
-  - Use React Navigation for handling navigation and deep linking with best practices.
-      

package/README.zh-CN.md

@@ -1,230 +0,0 @@
-
-
-
-# React Native Debug Toolkit 使用文档
-
-一个简单但功能强大的React Native调试工具包，提供便捷的开发期浮动界面。
-
-## 安装
-
-```bash
-npm install react-native-debug-toolkit
-# 或
-yarn add react-native-debug-toolkit
-```
-
-### iOS 额外设置
-
-该工具包使用FLEX和DoraemonKit提供iOS调试功能。请按以下步骤正确集成：
-
-1. 确保项目中已安装CocoaPods
-2. 在Podfile中添加以下依赖：
-
-```ruby
-pod 'FLEX', :configurations => ['Debug']   
-pod 'DoraemonKit/Core', :git => 'https://github.com/superzcj/DoKit.git', :configurations => ['Debug'] #必选
-```
-
-3. 在`didFinishLaunchingWithOptions`方法中的AppDelegate.m文件中添加以下代码：
-
-```objc
-#ifdef DEBUG
-#import <DoraemonKit/DoraemonManager.h>
-#endif
-
-  #ifdef DEBUG
-  DoraemonManager *doKit = [DoraemonManager shareInstance];
-  doKit.autoDock = false;
-  [doKit install];
-  [doKit hiddenDoraemon];
-  #endif
-```
-
-4. 在iOS目录中运行pod install：
-
-```bash
-cd ios && pod install
-```
-
-### Android 额外设置
-
-1. 在`android/settings.gradle`中添加以下内容：
-
-```gradle
-include ':react-native-debug-toolkit'
-project(':react-native-debug-toolkit').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-debug-toolkit/android')
-```
-
-2. 在`android/app/build.gradle`中添加以下依赖：
-
-```gradle
-dependencies {
-    // 其他依赖...
-    
-    debugImplementation 'io.github.didi.dokit:dokitx:3.7.1'
-    releaseImplementation 'io.github.didi.dokit:dokitx-no-op:3.7.1'
-    debugImplementation 'com.android.volley:volley:1.2.0'
-    
-    implementation project(':react-native-debug-toolkit')
-}
-```
-
-3. 在`MainApplication.kt`中初始化DoKit：
-
-```kotlin
-import com.didichuxing.doraemonkit.DoKit 
-import com.reactnative.debuglibs.RNDebugLibsPackage
-
-// 在getPackages方法内
-add(RNDebugLibsPackage())
-
- // 在onCreate方法内
-if (BuildConfig.DEBUG) {
-    DoKit.Builder(this)
-        .build()
-    DoKit.hide()
-}
-```
-
-## 使用方法
-
-将调试工具包添加到您的应用程序中非常简单，只需一行代码即可启用所有功能：
-
-```javascript
-// 在App.js或其他初始化文件中
-import React, { useEffect } from 'react';
-import { initializeDebugToolkit, isDebugMode } from 'react-native-debug-toolkit';
-
-function App() {
-  useEffect(() => {
-    if (isDebugMode) {
-      // 使用所有默认功能初始化
-      initializeDebugToolkit();
-      
-      // 或选择特定的内置功能
-      // initializeDebugToolkit(['network', 'console', 'zustand', 'navigation', 'thirdPartyLibs']);
-    }
-    
-    return () => {
-      // 自动清理
-    };
-  }, []);
-  
-  return <YourApp />;
-}
-```
-
-就这么简单！现在您的应用程序将在开发模式下显示一个浮动的调试面板，让您可以访问所有调试功能。
-
-## 内置功能
-
-通过上面的一行代码初始化，您将自动获得以下所有调试功能：
-
-- **网络监控**：跟踪和检查所有网络请求和响应
-- **控制台日志**：在应用内查看所有控制台日志输出
-- **Zustand状态**：监控Zustand状态管理（如果您的应用使用Zustand）
-- **导航跟踪**：自动记录应用内的导航事件
-- **第三方调试工具**：快速访问原生调试工具（iOS的FLEX，iOS和Android的DoraemonKit）
-
-## 集成
-
-### 高级Axios网络跟踪
-
-对于使用Axios的项目，您可以启用更详细的网络请求跟踪：
-
-```javascript
-import axios from 'axios';
-import { createNetworkFeature, isDebugMode } from 'react-native-debug-toolkit';
-
-// 获取网络功能实例并设置Axios拦截器
-if (isDebugMode) {
-  const networkFeature = createNetworkFeature();
-  networkFeature.setupAxiosInterceptors(axios);
-  
-  // 可选：排除敏感URL（如认证接口）
-  networkFeature.addUrlToBlacklist('api.example.com/auth');
-  networkFeature.addUrlToBlacklist(/password/i); // 支持正则表达式
-}
-```
-
-### 监控Zustand状态（如果您使用Zustand）
-
-如果您的应用使用Zustand进行状态管理，只需添加中间件即可跟踪所有状态变化：
-
-```javascript
-import { create } from 'zustand';
-import { zustandLogMiddleware } from 'react-native-debug-toolkit';
-
-// 只需添加zustandLogMiddleware来包装您的store
-const useStore = create(
-  zustandLogMiddleware(
-    (set) => ({
-      count: 0,
-      increment: () => set((state) => ({ count: state.count + 1 })),
-      decrement: () => set((state) => ({ count: state.count - 1 })),
-    })
-  )
-);
-```
-
-### 导航跟踪（React Navigation）
-
-如果您使用React Navigation，添加导航跟踪只需一步：
-
-```javascript
-import React, { useRef } from 'react';
-import { NavigationContainer } from '@react-navigation/native';
-import { useNavigationLogger } from 'react-native-debug-toolkit';
-
-function AppNavigator() {
-  const navigationRef = useRef(null);
-  
-  // 添加这一行来启用导航日志
-  useNavigationLogger(navigationRef);
-  
-  return (
-    <NavigationContainer ref={navigationRef}>
-      {/* 您的导航配置 */}
-    </NavigationContainer>
-  );
-}
-```
-
-## 自定义配置
-
-如果您不需要所有功能，可以选择性地启用特定功能：
-
-```javascript
-// 只启用网络和控制台日志功能
-initializeDebugToolkit(['network', 'console']);
-
-// 或者指定一组自定义功能
-initializeDebugToolkit([
-  'network',
-  'console', 
-  'zustand', 
-  'navigation',
-  'thirdPartyLibs'
-]);
-```
-
-## 常见问题排除
-
-### 调试面板不显示
-- 确保您在开发模式下（`isDebugMode`为true）
-- 检查是否正确调用了`initializeDebugToolkit()`
-
-### iOS功能不工作
-- 确认您已将FLEX和DoraemonKit添加到Podfile
-- 在修改后重新运行`pod install`
-- 确保您正在运行Debug构建版本
-
-### 网络请求未被捕获
-- 对于Axios，请确保调用了`setupAxiosInterceptors(axios)`
-- 对于fetch请求，工具包会自动拦截，无需额外配置
-
-### 应用性能问题
-- 此调试工具包仅适用于开发阶段，请确保生产构建中未包含
-- 如果开发模式下性能受影响，可以尝试只启用特定功能     
-
-