@react-devtools-plus/scan 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,304 @@
+import { Options } from 'react-scan';
+export { Options, ReactScanInternals, getOptions, onRender, scan, setOptions, useScan } from 'react-scan';
+
+/**
+ * Type definitions for React DevTools Scan integration
+ */
+
+/**
+ * Integration modes for React Scan
+ */
+type IntegrationMode = 'overlay' | 'panel' | 'both';
+/**
+ * Extended options for React DevTools Scan integration
+ */
+interface ReactDevtoolsScanOptions extends Options {
+    /**
+     * Integration mode - how scan should be displayed
+     * - 'overlay': Show as overlay on the page (default react-scan behavior)
+     * - 'panel': Integrate into DevTools panel
+     * - 'both': Show both overlay and panel integration
+     *
+     * @default 'overlay'
+     */
+    integrationMode?: IntegrationMode;
+    /**
+     * Whether to sync state with DevTools panel
+     *
+     * @default true
+     */
+    syncWithDevtools?: boolean;
+}
+/**
+ * Scan instance interface
+ */
+/**
+ * Performance metrics for a component
+ */
+interface ComponentPerformanceData {
+    componentName: string;
+    renderCount: number;
+    totalTime: number;
+    averageTime: number;
+    unnecessaryRenders: number;
+    lastRenderTime: number | null;
+}
+/**
+ * Aggregated performance summary
+ */
+interface PerformanceSummary {
+    totalRenders: number;
+    totalComponents: number;
+    unnecessaryRenders: number;
+    averageRenderTime: number;
+    slowestComponents: ComponentPerformanceData[];
+}
+/**
+ * Component info for selection
+ */
+interface ComponentInfo {
+    componentName: string;
+    fiber: any;
+    domElement: Element | null;
+}
+/**
+ * Change info for a single prop/state/context value
+ */
+interface ChangeInfo {
+    name: string;
+    previousValue: any;
+    currentValue: any;
+    count: number;
+}
+/**
+ * Aggregated changes for a component render
+ */
+interface AggregatedChanges {
+    propsChanges: ChangeInfo[];
+    stateChanges: ChangeInfo[];
+    contextChanges: ChangeInfo[];
+}
+/**
+ * Focused component render info with changes
+ */
+interface FocusedComponentRenderInfo {
+    componentName: string;
+    renderCount: number;
+    changes: AggregatedChanges;
+    timestamp: number;
+}
+interface ScanInstance {
+    /**
+     * Get current scan options
+     */
+    getOptions: () => ReactDevtoolsScanOptions;
+    /**
+     * Update scan options at runtime
+     */
+    setOptions: (options: Partial<ReactDevtoolsScanOptions>) => void;
+    /**
+     * Start scanning
+     */
+    start: () => void;
+    /**
+     * Stop scanning
+     */
+    stop: () => void;
+    /**
+     * Check if scanning is active
+     */
+    isActive: () => boolean;
+    /**
+     * Hide the React Scan toolbar
+     */
+    hideToolbar: () => void;
+    /**
+     * Show the React Scan toolbar
+     */
+    showToolbar: () => void;
+    /**
+     * Get toolbar visibility state
+     */
+    getToolbarVisibility: () => boolean;
+    /**
+     * Get performance data for all components
+     */
+    getPerformanceData: () => ComponentPerformanceData[];
+    /**
+     * Get aggregated performance summary
+     */
+    getPerformanceSummary: () => PerformanceSummary;
+    /**
+     * Clear all performance data
+     */
+    clearPerformanceData: () => void;
+    /**
+     * Start component inspection mode
+     */
+    startInspecting: () => void;
+    /**
+     * Stop component inspection mode
+     */
+    stopInspecting: () => void;
+    /**
+     * Check if inspection mode is active
+     */
+    isInspecting: () => boolean;
+    /**
+     * Focus on a specific component by fiber
+     */
+    focusComponent: (fiber: any) => void;
+    /**
+     * Get currently focused component
+     */
+    getFocusedComponent: () => ComponentInfo | null;
+    /**
+     * Subscribe to inspection state changes
+     */
+    onInspectStateChange: (callback: (state: any) => void) => () => void;
+    /**
+     * Get current FPS
+     */
+    getFPS: () => number;
+    /**
+     * Get focused component render info with changes
+     */
+    getFocusedComponentRenderInfo: () => FocusedComponentRenderInfo | null;
+    /**
+     * Subscribe to focused component changes (re-renders)
+     */
+    onFocusedComponentChange: (callback: (info: FocusedComponentRenderInfo) => void) => () => void;
+    /**
+     * Clear the focused component's change history
+     */
+    clearFocusedComponentChanges: () => void;
+    /**
+     * Set the focused component by name for render tracking
+     * This is used when inspectState.kind is not 'focused' but we still want to track renders
+     */
+    setFocusedComponentByName: (componentName: string) => void;
+    /**
+     * Get the component tree with render counts
+     */
+    getComponentTree: () => ComponentTreeNode[];
+    /**
+     * Clear component render count tracking
+     */
+    clearComponentTree: () => void;
+}
+/**
+ * Component tree node
+ */
+interface ComponentTreeNode {
+    id: string;
+    name: string;
+    type: string;
+    renderCount: number;
+    lastRenderTime: number;
+    averageTime?: number;
+    unnecessary?: number;
+    children: ComponentTreeNode[];
+    fiber?: any;
+}
+
+/**
+ * React Scan Plugin for React DevTools
+ *
+ * This plugin integrates React Scan into the React DevTools plugin system,
+ * providing performance monitoring and analysis capabilities.
+ */
+
+/**
+ * React Scan plugin configuration
+ */
+interface ScanPluginConfig extends ReactDevtoolsScanOptions {
+    /**
+     * Whether to auto-start scan on plugin load
+     * @default true
+     */
+    autoStart?: boolean;
+}
+/**
+ * Create React Scan plugin
+ *
+ * @param config - Plugin configuration
+ * @returns DevTools plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { createScanPlugin } from '@react-devtools-plus/scan/plugin';
+ *
+ * const scanPlugin = createScanPlugin({
+ *   enabled: true,
+ *   showToolbar: true,
+ *   autoStart: true,
+ * });
+ * ```
+ */
+declare function createScanPlugin(config?: ScanPluginConfig): any;
+/**
+ * Default React Scan plugin instance
+ */
+declare const scanPlugin: any;
+
+/**
+ * React DevTools Scan - Integration layer for react-scan
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Initialize React Scan with DevTools integration
+ *
+ * @param options - Configuration options for React Scan
+ * @returns Scan instance for further control
+ *
+ * @example
+ * ```typescript
+ * import { initScan } from '@react-devtools-plus/scan';
+ *
+ * // Initialize with default options
+ * const scanInstance = initScan();
+ *
+ * // Initialize with custom options
+ * const scanInstance = initScan({
+ *   enabled: true,
+ *   showToolbar: true,
+ *   animationSpeed: 'fast',
+ *   trackUnnecessaryRenders: true,
+ *   integrationMode: 'overlay'
+ * });
+ * ```
+ */
+declare function initScan(options?: ReactDevtoolsScanOptions): ScanInstance;
+/**
+ * Get the current scan instance
+ *
+ * @returns Current scan instance or null if not initialized
+ *
+ * @example
+ * ```typescript
+ * import { getScan } from '@react-devtools-plus/scan';
+ *
+ * const scanInstance = getScan();
+ * if (scanInstance) {
+ *   // Check if scan is active
+ *   scanInstance.isActive();
+ * }
+ * ```
+ */
+declare function getScan(): ScanInstance | null;
+/**
+ * Reset the scan instance (useful for testing)
+ *
+ * @example
+ * ```typescript
+ * import { resetScan } from '@react-devtools-plus/scan';
+ *
+ * // Reset for testing
+ * resetScan();
+ * ```
+ */
+declare function resetScan(): void;
+
+export { type IntegrationMode, type ReactDevtoolsScanOptions, type ScanInstance, type ScanPluginConfig, createScanPlugin, getScan, initScan, resetScan, scanPlugin };

package/dist/index.d.ts

@@ -0,0 +1,304 @@
+import { Options } from 'react-scan';
+export { Options, ReactScanInternals, getOptions, onRender, scan, setOptions, useScan } from 'react-scan';
+
+/**
+ * Type definitions for React DevTools Scan integration
+ */
+
+/**
+ * Integration modes for React Scan
+ */
+type IntegrationMode = 'overlay' | 'panel' | 'both';
+/**
+ * Extended options for React DevTools Scan integration
+ */
+interface ReactDevtoolsScanOptions extends Options {
+    /**
+     * Integration mode - how scan should be displayed
+     * - 'overlay': Show as overlay on the page (default react-scan behavior)
+     * - 'panel': Integrate into DevTools panel
+     * - 'both': Show both overlay and panel integration
+     *
+     * @default 'overlay'
+     */
+    integrationMode?: IntegrationMode;
+    /**
+     * Whether to sync state with DevTools panel
+     *
+     * @default true
+     */
+    syncWithDevtools?: boolean;
+}
+/**
+ * Scan instance interface
+ */
+/**
+ * Performance metrics for a component
+ */
+interface ComponentPerformanceData {
+    componentName: string;
+    renderCount: number;
+    totalTime: number;
+    averageTime: number;
+    unnecessaryRenders: number;
+    lastRenderTime: number | null;
+}
+/**
+ * Aggregated performance summary
+ */
+interface PerformanceSummary {
+    totalRenders: number;
+    totalComponents: number;
+    unnecessaryRenders: number;
+    averageRenderTime: number;
+    slowestComponents: ComponentPerformanceData[];
+}
+/**
+ * Component info for selection
+ */
+interface ComponentInfo {
+    componentName: string;
+    fiber: any;
+    domElement: Element | null;
+}
+/**
+ * Change info for a single prop/state/context value
+ */
+interface ChangeInfo {
+    name: string;
+    previousValue: any;
+    currentValue: any;
+    count: number;
+}
+/**
+ * Aggregated changes for a component render
+ */
+interface AggregatedChanges {
+    propsChanges: ChangeInfo[];
+    stateChanges: ChangeInfo[];
+    contextChanges: ChangeInfo[];
+}
+/**
+ * Focused component render info with changes
+ */
+interface FocusedComponentRenderInfo {
+    componentName: string;
+    renderCount: number;
+    changes: AggregatedChanges;
+    timestamp: number;
+}
+interface ScanInstance {
+    /**
+     * Get current scan options
+     */
+    getOptions: () => ReactDevtoolsScanOptions;
+    /**
+     * Update scan options at runtime
+     */
+    setOptions: (options: Partial<ReactDevtoolsScanOptions>) => void;
+    /**
+     * Start scanning
+     */
+    start: () => void;
+    /**
+     * Stop scanning
+     */
+    stop: () => void;
+    /**
+     * Check if scanning is active
+     */
+    isActive: () => boolean;
+    /**
+     * Hide the React Scan toolbar
+     */
+    hideToolbar: () => void;
+    /**
+     * Show the React Scan toolbar
+     */
+    showToolbar: () => void;
+    /**
+     * Get toolbar visibility state
+     */
+    getToolbarVisibility: () => boolean;
+    /**
+     * Get performance data for all components
+     */
+    getPerformanceData: () => ComponentPerformanceData[];
+    /**
+     * Get aggregated performance summary
+     */
+    getPerformanceSummary: () => PerformanceSummary;
+    /**
+     * Clear all performance data
+     */
+    clearPerformanceData: () => void;
+    /**
+     * Start component inspection mode
+     */
+    startInspecting: () => void;
+    /**
+     * Stop component inspection mode
+     */
+    stopInspecting: () => void;
+    /**
+     * Check if inspection mode is active
+     */
+    isInspecting: () => boolean;
+    /**
+     * Focus on a specific component by fiber
+     */
+    focusComponent: (fiber: any) => void;
+    /**
+     * Get currently focused component
+     */
+    getFocusedComponent: () => ComponentInfo | null;
+    /**
+     * Subscribe to inspection state changes
+     */
+    onInspectStateChange: (callback: (state: any) => void) => () => void;
+    /**
+     * Get current FPS
+     */
+    getFPS: () => number;
+    /**
+     * Get focused component render info with changes
+     */
+    getFocusedComponentRenderInfo: () => FocusedComponentRenderInfo | null;
+    /**
+     * Subscribe to focused component changes (re-renders)
+     */
+    onFocusedComponentChange: (callback: (info: FocusedComponentRenderInfo) => void) => () => void;
+    /**
+     * Clear the focused component's change history
+     */
+    clearFocusedComponentChanges: () => void;
+    /**
+     * Set the focused component by name for render tracking
+     * This is used when inspectState.kind is not 'focused' but we still want to track renders
+     */
+    setFocusedComponentByName: (componentName: string) => void;
+    /**
+     * Get the component tree with render counts
+     */
+    getComponentTree: () => ComponentTreeNode[];
+    /**
+     * Clear component render count tracking
+     */
+    clearComponentTree: () => void;
+}
+/**
+ * Component tree node
+ */
+interface ComponentTreeNode {
+    id: string;
+    name: string;
+    type: string;
+    renderCount: number;
+    lastRenderTime: number;
+    averageTime?: number;
+    unnecessary?: number;
+    children: ComponentTreeNode[];
+    fiber?: any;
+}
+
+/**
+ * React Scan Plugin for React DevTools
+ *
+ * This plugin integrates React Scan into the React DevTools plugin system,
+ * providing performance monitoring and analysis capabilities.
+ */
+
+/**
+ * React Scan plugin configuration
+ */
+interface ScanPluginConfig extends ReactDevtoolsScanOptions {
+    /**
+     * Whether to auto-start scan on plugin load
+     * @default true
+     */
+    autoStart?: boolean;
+}
+/**
+ * Create React Scan plugin
+ *
+ * @param config - Plugin configuration
+ * @returns DevTools plugin instance
+ *
+ * @example
+ * ```typescript
+ * import { createScanPlugin } from '@react-devtools-plus/scan/plugin';
+ *
+ * const scanPlugin = createScanPlugin({
+ *   enabled: true,
+ *   showToolbar: true,
+ *   autoStart: true,
+ * });
+ * ```
+ */
+declare function createScanPlugin(config?: ScanPluginConfig): any;
+/**
+ * Default React Scan plugin instance
+ */
+declare const scanPlugin: any;
+
+/**
+ * React DevTools Scan - Integration layer for react-scan
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Initialize React Scan with DevTools integration
+ *
+ * @param options - Configuration options for React Scan
+ * @returns Scan instance for further control
+ *
+ * @example
+ * ```typescript
+ * import { initScan } from '@react-devtools-plus/scan';
+ *
+ * // Initialize with default options
+ * const scanInstance = initScan();
+ *
+ * // Initialize with custom options
+ * const scanInstance = initScan({
+ *   enabled: true,
+ *   showToolbar: true,
+ *   animationSpeed: 'fast',
+ *   trackUnnecessaryRenders: true,
+ *   integrationMode: 'overlay'
+ * });
+ * ```
+ */
+declare function initScan(options?: ReactDevtoolsScanOptions): ScanInstance;
+/**
+ * Get the current scan instance
+ *
+ * @returns Current scan instance or null if not initialized
+ *
+ * @example
+ * ```typescript
+ * import { getScan } from '@react-devtools-plus/scan';
+ *
+ * const scanInstance = getScan();
+ * if (scanInstance) {
+ *   // Check if scan is active
+ *   scanInstance.isActive();
+ * }
+ * ```
+ */
+declare function getScan(): ScanInstance | null;
+/**
+ * Reset the scan instance (useful for testing)
+ *
+ * @example
+ * ```typescript
+ * import { resetScan } from '@react-devtools-plus/scan';
+ *
+ * // Reset for testing
+ * resetScan();
+ * ```
+ */
+declare function resetScan(): void;
+
+export { type IntegrationMode, type ReactDevtoolsScanOptions, type ScanInstance, type ScanPluginConfig, createScanPlugin, getScan, initScan, resetScan, scanPlugin };