react-native-debug-toolkit 2.0.0 → 2.2.0

package/README.md

@@ -1,20 +1,24 @@
 # React Native Debug Toolkit
 
+[中文文档](README.zh-CN.md)
+
 A dev-only floating debug panel for React Native — inspect network, console, state, navigation and more, right on your device.
 
 > Zero impact on production builds (`__DEV__` only).
 
+## Preview
+
+![demo](demo.gif)
 ## Features
 
-- **Network** — Inspect fetch / Axios requests & responses, copy as cURL
+- **Network** — Auto-intercepts fetch; axios via `axiosInstance` config, inspect requests & responses, copy as cURL
 - **Console** — Capture `console.log / info / warn / error`
 - **Zustand** — Log state transitions via middleware
 - **Navigation** — Track route changes
 - **Track** — Record custom analytics events
 - **Environment** — Switch API hosts on the fly
-- **Clipboard** — Inspect clipboard content
-- **Third-party** — Launch FLEX / DoraemonKit
-- **Export** — Share debug data via system share sheet
+- **Clipboard** — Paste text and copy to computer
+- **Log Persistence** — Network, Console, Track logs survive app restarts (requires AsyncStorage)
 
 ## Installation
 
@@ -28,76 +32,75 @@ Optional — clipboard copy support:
 npm install @react-native-clipboard/clipboard
 ```
 
+Optional — FAB position & last tab persistence:
+
+```bash
+npm install @react-native-async-storage/async-storage
+```
+
+Without AsyncStorage these features degrade gracefully to in-memory state.
+
 ## Quick Start
 
 ```tsx
-import { useEffect } from 'react';
-import { initializeDebugToolkit } from 'react-native-debug-toolkit';
+import { DebugView } from 'react-native-debug-toolkit';
 
 function App() {
-  useEffect(() => {
-    const toolkit = initializeDebugToolkit();
-    return () => toolkit?.destroy();
-  }, []);
-
-  return <AppContent />;
+  return (
+    <DebugView>
+      <AppContent />
+    </DebugView>
+  );
 }
 ```
 
-That's it. All features are enabled by default.
+A floating debug button appears in dev mode. Tap to open the panel, tap × or swipe down to close.
 
-## Configuration
+Network (fetch), console, navigation, zustand, track, and clipboard are enabled by default. To capture axios requests, pass your axios instance via the `axiosInstance` config option.
 
-Pass a config object to customize features:
+Disable specific features:
 
 ```tsx
-initializeDebugToolkit({
-  features: {
-    network:  { maxLogs: 100, blacklist: ['/auth'] },
-    console:  true,
-    zustand:  true,
-    track:    true,
-    environment: [
-      { id: 'dev',  label: 'Dev',  host: 'dev-api.example.com', color: '#34C759' },
-      { id: 'prod', label: 'Prod', host: 'api.example.com',     color: '#FF3B30' },
-    ],
-  },
-  enabled: true,  // force enable (default: __DEV__)
-});
+<DebugView features={{ clipboard: false, zustand: false }}>
+  <AppContent />
+</DebugView>
 ```
 
-Set any feature to `false` to disable it.
-
-### Per-feature options
+## Common Patterns
 
-| Feature | Options |
-|---------|---------|
-| `network` | `maxLogs`, `blacklist` |
-| `console` | `maxLogs` |
-| `zustand` | `maxLogs` |
-| `navigation` | `maxLogs` |
-| `track` | `maxLogs` |
-| `environment` | `EnvironmentConfig[]` |
-| `thirdPartyLibs` | — |
-| `clipboard` | — |
+### Navigation Tracking
 
-All `maxLogs` default to **200**.
+```tsx
+import { useRef } from 'react';
+import { DebugView } from 'react-native-debug-toolkit';
+import { NavigationContainer } from '@react-navigation/native';
 
-## Usage Examples
+function App() {
+  const navRef = useRef(null);
+  return (
+    <DebugView navigationRef={navRef}>
+      <NavigationContainer ref={navRef}>
+        <AppContent />
+      </NavigationContainer>
+    </DebugView>
+  );
+}
+```
 
-### Axios interceptor
+### Environment Switching
 
 ```tsx
-import { createNetworkFeature } from 'react-native-debug-toolkit';
-import axios from 'axios';
-
-const network = createNetworkFeature({ maxLogs: 100 });
-network.setupAxiosInterceptors(axios);
-
-initializeDebugToolkit({ features: { network, console: true } });
+<DebugView
+  environments={[
+    { id: 'dev',  label: 'Dev',  host: 'dev-api.example.com', color: '#34C759' },
+    { id: 'prod', label: 'Prod', host: 'api.example.com',     color: '#FF3B30' },
+  ]}
+>
+  <AppContent />
+</DebugView>
 ```
 
-### Zustand middleware
+### Zustand Middleware
 
 ```tsx
 import { zustandLogMiddleware } from 'react-native-debug-toolkit';
@@ -106,21 +109,12 @@ const useStore = create(
   zustandLogMiddleware((set) => ({
     count: 0,
     increment: () => set((s) => ({ count: s.count + 1 }), false, 'increment'),
+    //                          ↑ merge  ↑ action name (shown in debug panel)
   }))
 );
 ```
 
-### Navigation logging
-
-```tsx
-import { useNavigationLogger } from 'react-native-debug-toolkit';
-
-const ref = useRef(null);
-useNavigationLogger(ref);
-// pass ref to <NavigationContainer ref={ref}>
-```
-
-### Custom events
+### Custom Events
 
 ```tsx
 import { addTrackLog } from 'react-native-debug-toolkit';
@@ -128,73 +122,40 @@ import { addTrackLog } from 'react-native-debug-toolkit';
 addTrackLog({ eventName: 'button_click', buttonId: 'submit' });
 ```
 
-### Export debug data
-
-Tap **Export** in the panel header, or call programmatically:
-
-```tsx
-import { exportDebugData } from 'react-native-debug-toolkit';
-
-await exportDebugData(data, 'network');
-```
-
-### Copy to computer
+### Network Blacklist & Axios
 
 ```tsx
-import { copyToComputer } from 'react-native-debug-toolkit';
-
-await copyToComputer(jsonString);
-```
-
-## API
-
-### `initializeDebugToolkit(config?)`
+import axios from 'axios';
 
-```ts
-initializeDebugToolkit(config?: {
-  features?: FeatureConfigs;
-  enabled?: boolean;
-  doraemonProductId?: string;
-}): DebugToolkitAPI | null;
+const api = axios.create({ baseURL: 'https://api.example.com' });
+
+<DebugView
+  features={{
+    network: {
+      maxLogs: 100,
+      blacklist: ['/analytics', /\/healthcheck$/],
+      axiosInstance: api,
+    },
+  }}
+>
+  <AppContent />
+</DebugView>
 ```
 
-### `DebugToolkitAPI`
-
-| Method | Description |
-|--------|-------------|
-| `showPanel()` / `hidePanel()` | Toggle visibility |
-| `clearAll()` | Clear all data |
-| `addFeature(f)` / `removeFeature(name)` | Manage features at runtime |
-| `destroy()` | Full teardown |
-| `features` | Active features (read-only) |
+## Imperative API
 
-### Custom feature
+For programmatic control outside React (notifications, deep links, dev-only buttons):
 
 ```tsx
-import type { DebugFeature } from 'react-native-debug-toolkit';
-
-const myFeature: DebugFeature<MyData> = {
-  name: 'myFeature',
-  label: 'My Feature',
-  setup:     () => { /* start capturing */ },
-  getData:   () => myDataArray,
-  cleanup:   () => { /* stop capturing */ },
-  clear:     () => { /* reset data */ },
-  subscribe: (cb) => { emitter.on('change', cb); return () => emitter.off('change', cb); },
-  renderContent: MyFeatureTab,
-};
-
-initializeDebugToolkit({ features: { myFeature } });
-```
+import { DebugToolkit } from 'react-native-debug-toolkit';
 
-### Utilities
+DebugToolkit.openPanel();
+DebugToolkit.clearAll();
+DebugToolkit.showLauncher();
+DebugToolkit.hideLauncher();
+```
 
-| Export | Description |
-|--------|-------------|
-| `safeStringify(value, space?)` | JSON stringify with circular-ref protection |
-| `exportDebugData(data, name)` | Share via system sheet |
-| `copyToComputer(content, options?)` | Copy content to computer |
-| `logToComputer(...args)` | Log to computer console |
+Full API: `DebugToolkit` is a singleton with `openPanel`, `closePanel`, `togglePanel`, `clearAll`, `showLauncher`, `hideLauncher`, `addFeature`, `removeFeature`, `destroy`, `features`, `panelOpen`. See TypeScript types for details.
 
 ## Peer Dependencies
 
@@ -203,6 +164,7 @@ initializeDebugToolkit({ features: { myFeature } });
 | react | >= 18.0.0 | Yes |
 | react-native | >= 0.72.0 | Yes |
 | @react-native-clipboard/clipboard | >= 1.0.0 | No |
+| @react-native-async-storage/async-storage | >= 1.0.0 | No |
 
 ## License
 

package/README.zh-CN.md

@@ -0,0 +1,171 @@
+# React Native Debug Toolkit
+
+[English](README.md)
+
+一个仅用于开发的 React Native 浮动调试面板 — 在设备上直接查看网络请求、控制台日志、状态变化、导航事件等。
+
+> 生产环境零影响（仅在 `__DEV__` 模式下运行）。
+
+## 预览
+
+![demo](demo.gif)
+## 功能
+
+- **Network** — 自动拦截 fetch；axios 通过 `axiosInstance` 配置，查看请求与响应，复制为 cURL
+- **Console** — 捕获 `console.log / info / warn / error`
+- **Zustand** — 通过中间件记录状态变化
+- **Navigation** — 追踪路由切换
+- **Track** — 记录自定义埋点事件
+- **Environment** — 运行时切换 API 环境
+- **Clipboard** — 粘贴文本并复制到电脑
+- **日志持久化** — Network、Console、Track 日志在应用重启后保留（需要 AsyncStorage）
+
+## 安装
+
+```bash
+npm install react-native-debug-toolkit
+```
+
+可选 — 剪贴板复制支持：
+
+```bash
+npm install @react-native-clipboard/clipboard
+```
+
+可选 — FAB 位置与上次 Tab 持久化：
+
+```bash
+npm install @react-native-async-storage/async-storage
+```
+
+未安装 AsyncStorage 时，这些功能会优雅降级为内存态。
+
+## 快速开始
+
+```tsx
+import { DebugView } from 'react-native-debug-toolkit';
+
+function App() {
+  return (
+    <DebugView>
+      <AppContent />
+    </DebugView>
+  );
+}
+```
+
+开发模式下出现浮动调试按钮。点击打开面板，点击 × 或下滑关闭。
+
+网络（fetch）、控制台、导航、Zustand、埋点和剪贴板默认启用。如需捕获 axios 请求，通过 `axiosInstance` 配置项传入你的 axios 实例。
+
+禁用特定功能：
+
+```tsx
+<DebugView features={{ clipboard: false, zustand: false }}>
+  <AppContent />
+</DebugView>
+```
+
+## 常用模式
+
+### 导航追踪
+
+```tsx
+import { useRef } from 'react';
+import { DebugView } from 'react-native-debug-toolkit';
+import { NavigationContainer } from '@react-navigation/native';
+
+function App() {
+  const navRef = useRef(null);
+  return (
+    <DebugView navigationRef={navRef}>
+      <NavigationContainer ref={navRef}>
+        <AppContent />
+      </NavigationContainer>
+    </DebugView>
+  );
+}
+```
+
+### 环境切换
+
+```tsx
+<DebugView
+  environments={[
+    { id: 'dev',  label: 'Dev',  host: 'dev-api.example.com', color: '#34C759' },
+    { id: 'prod', label: 'Prod', host: 'api.example.com',     color: '#FF3B30' },
+  ]}
+>
+  <AppContent />
+</DebugView>
+```
+
+### Zustand 中间件
+
+```tsx
+import { zustandLogMiddleware } from 'react-native-debug-toolkit';
+
+const useStore = create(
+  zustandLogMiddleware((set) => ({
+    count: 0,
+    increment: () => set((s) => ({ count: s.count + 1 }), false, 'increment'),
+    //                          ↑ merge  ↑ action 名称（显示在调试面板）
+  }))
+);
+```
+
+### 自定义事件
+
+```tsx
+import { addTrackLog } from 'react-native-debug-toolkit';
+
+addTrackLog({ eventName: 'button_click', buttonId: 'submit' });
+```
+
+### 网络黑名单 & Axios
+
+```tsx
+import axios from 'axios';
+
+const api = axios.create({ baseURL: 'https://api.example.com' });
+
+<DebugView
+  features={{
+    network: {
+      maxLogs: 100,
+      blacklist: ['/analytics', /\/healthcheck$/],
+      axiosInstance: api,
+    },
+  }}
+>
+  <AppContent />
+</DebugView>
+```
+
+## 命令式 API
+
+用于 React 外部的编程控制（通知、深度链接、开发专用按钮）：
+
+```tsx
+import { DebugToolkit } from 'react-native-debug-toolkit';
+
+DebugToolkit.openPanel();
+DebugToolkit.clearAll();
+DebugToolkit.showLauncher();
+DebugToolkit.hideLauncher();
+```
+
+完整 API：`DebugToolkit` 是单例，提供 `openPanel`、`closePanel`、`togglePanel`、`clearAll`、`showLauncher`、`hideLauncher`、`addFeature`、`removeFeature`、`destroy`、`features`、`panelOpen`。详见 TypeScript 类型定义。
+
+## 对等依赖
+
+| 包 | 版本 | 必需 |
+|----|------|------|
+| react | >= 18.0.0 | 是 |
+| react-native | >= 0.72.0 | 是 |
+| @react-native-clipboard/clipboard | >= 1.0.0 | 否 |
+| @react-native-async-storage/async-storage | >= 1.0.0 | 否 |
+
+## 许可证
+
+MIT