react-native-element-inspector 0.1.0

package/src/ElementInspector.tsx

@@ -0,0 +1,119 @@
+import type { ReactNode } from 'react';
+import { useCallback, useState } from 'react';
+import { StyleSheet, View } from 'react-native';
+import { FLOATING_PANEL, Z_INDEX } from './constants';
+import { ElementHighlighter } from './ElementHighlighter';
+import { FloatingPanel, type PanelState } from './floatingPanel';
+import { useDebouncedCallback, useLayoutSnapshot, useTapToSelect } from './hooks';
+
+export interface ElementInspectorProps {
+  /** Only enable in dev mode. Pass `__DEV__` here. */
+  enabled?: boolean;
+  children: ReactNode;
+}
+
+/**
+ * Root wrapper component. Wrap your app root with this.
+ * In production (enabled=false), renders children with zero overhead.
+ */
+export const ElementInspector = ({ enabled = false, children }: ElementInspectorProps) => {
+  const [isInspecting, setIsInspecting] = useState(false);
+  const [highlightVisible, setHighlightVisible] = useState(false);
+  const { snapshot, buildSnapshot } = useLayoutSnapshot();
+  const { selected, matches, selectedIndex, handleTap, cycleNext, cyclePrevious, clearSelection } =
+    useTapToSelect(snapshot);
+
+  const hideHighlight = useDebouncedCallback(
+    () => setHighlightVisible(false),
+    FLOATING_PANEL.HIGHLIGHT_FLASH_MS,
+  );
+  const flashHighlight = useCallback(() => {
+    setHighlightVisible(true);
+    hideHighlight();
+  }, [hideHighlight]);
+
+  if (!enabled) {
+    return <>{children}</>;
+  }
+
+  // Derive panel state from inspector state
+  const panelState: PanelState = isInspecting ? (selected ? 'expanded' : 'handle') : 'bubble';
+
+  const toggleInspect = async () => {
+    if (isInspecting) {
+      setIsInspecting(false);
+      clearSelection();
+    } else {
+      try {
+        await buildSnapshot();
+        setIsInspecting(true);
+      } catch (error) {
+        // biome-ignore lint/suspicious/noConsole: dev tool — errors should be visible
+        console.warn('[ElementInspector] Snapshot failed:', error);
+      }
+    }
+  };
+
+  const handleClose = () => {
+    if (selected) {
+      // Expanded → handle (deselect element, stay in inspect mode)
+      clearSelection();
+    } else {
+      // Handle → bubble (exit inspect mode)
+      setIsInspecting(false);
+    }
+  };
+
+  return (
+    <View style={styles.container}>
+      {children}
+
+      {/* Transparent tap-capture overlay — only active in inspect mode */}
+      {isInspecting && (
+        <View
+          style={styles.tapOverlay}
+          onStartShouldSetResponder={() => true}
+          onResponderRelease={(event) => {
+            handleTap(event);
+            flashHighlight();
+          }}
+        />
+      )}
+
+      {/* Persistent outline — always visible while element is selected */}
+      {isInspecting && selected && <ElementHighlighter element={selected} outlineOnly />}
+
+      {/* Full box model highlight — flashes on select/cycle, then auto-hides */}
+      {highlightVisible && <ElementHighlighter element={selected} />}
+
+      {/* Floating panel — bubble / handle / expanded */}
+      <FloatingPanel
+        panelState={panelState}
+        selected={selected}
+        matches={matches}
+        selectedIndex={selectedIndex}
+        onToggleInspect={toggleInspect}
+        onCycleNext={() => {
+          cycleNext();
+          flashHighlight();
+        }}
+        onCyclePrevious={() => {
+          cyclePrevious();
+          flashHighlight();
+        }}
+        onClose={handleClose}
+      />
+    </View>
+  );
+};
+
+const styles = StyleSheet.create({
+  container: {
+    flex: 1,
+  },
+  tapOverlay: {
+    ...StyleSheet.absoluteFillObject,
+    backgroundColor: 'transparent',
+    zIndex: Z_INDEX.TAP_OVERLAY,
+  },
+});

package/src/components/Checkbox.tsx

@@ -0,0 +1,41 @@
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+
+interface CheckboxProps {
+  checked: boolean;
+  onToggle: () => void;
+}
+
+export const Checkbox = ({ checked, onToggle }: CheckboxProps) => (
+  <Pressable onPress={onToggle} hitSlop={6} style={styles.pressable}>
+    <View style={[styles.box, checked && styles.checked]}>
+      {checked && <Text style={styles.tick}>✓</Text>}
+    </View>
+  </Pressable>
+);
+
+const styles = StyleSheet.create({
+  pressable: {
+    justifyContent: 'center',
+    alignItems: 'center',
+    marginRight: 6,
+  },
+  box: {
+    width: 12,
+    height: 12,
+    borderRadius: 2,
+    borderWidth: 1.5,
+    borderColor: '#555',
+    justifyContent: 'center',
+    alignItems: 'center',
+  },
+  checked: {
+    backgroundColor: '#4FC3F7',
+    borderColor: '#4FC3F7',
+  },
+  tick: {
+    fontSize: 9,
+    lineHeight: 11,
+    color: '#fff',
+    fontWeight: '700',
+  },
+});

package/src/components/index.ts

@@ -0,0 +1 @@
+export { Checkbox } from './Checkbox';

package/src/constants/colors.ts

@@ -0,0 +1,18 @@
+/** Chrome DevTools-style box model colors */
+export const BOX_MODEL_COLORS = {
+  margin: 'rgba(246, 178, 107, 0.4)',
+  marginLabel: '#F6B26B',
+  border: 'rgba(255, 217, 102, 0.3)',
+  borderLabel: '#FFD966',
+  padding: 'rgba(147, 196, 125, 0.4)',
+  paddingLabel: '#6AA84F',
+  content: 'rgba(79, 195, 247, 0.3)',
+  contentLabel: '#4A90D9',
+  outline: '#4FC3F7',
+} as const;
+
+/** VS Code-style syntax colors for the editable style property list */
+export const EDITABLE_VALUE_COLORS = {
+  key: { text: '#9CDCFE', underline: 'rgba(156, 220, 254, 0.4)' },
+  value: { text: '#CE9178', underline: 'rgba(206, 145, 120, 0.4)' },
+} as const;

package/src/constants/index.ts

@@ -0,0 +1,9 @@
+export { BOX_MODEL_COLORS, EDITABLE_VALUE_COLORS } from './colors';
+export {
+  EDITABLE_VALUE,
+  FLOATING_PANEL,
+  INSPECTOR_BUBBLE,
+  MEASURE_TIMEOUT_MS,
+  MONOSPACE_FONT,
+  Z_INDEX,
+} from './ui';

package/src/constants/ui.ts

@@ -0,0 +1,51 @@
+import { Platform } from 'react-native';
+
+/** Cross-platform monospace font family */
+export const MONOSPACE_FONT = Platform.select({ ios: 'Menlo', default: 'monospace' });
+
+/** Z-index layering for inspector UI elements */
+export const Z_INDEX = {
+  HIGHLIGHT: 9997,
+  TAP_OVERLAY: 9998,
+  FLOATING_PANEL: 10000,
+} as const;
+
+/** Timeout for fiber measure() calls (ms) */
+export const MEASURE_TIMEOUT_MS = 3000;
+
+/** Floating panel dimensions and animation config */
+export const FLOATING_PANEL = {
+  BUBBLE_SIZE: 48,
+  HANDLE_WIDTH: 180,
+  HANDLE_HEIGHT: 44,
+  PANEL_WIDTH: 280,
+  PANEL_HEIGHT: 320,
+  PANEL_BODY_HEIGHT: 220,
+  TAP_THRESHOLD: 5,
+  EDGE_MARGIN: 12,
+  TOP_SAFE_AREA: 50,
+  BOTTOM_SAFE_AREA: 40,
+  SNAP_FRICTION: 7,
+  SNAP_TENSION: 40,
+  EXPAND_DURATION: 250,
+  HIGHLIGHT_FLASH_MS: 1500,
+} as const;
+
+/** Validation constraints for editable style values */
+export const EDITABLE_VALUE = {
+  VALID_STYLE_KEY: /^[a-zA-Z][a-zA-Z0-9]*$/,
+  MAX_VALUE_LENGTH: 200,
+} as const;
+
+/** InspectorBubble sizing and animation trail config */
+export const INSPECTOR_BUBBLE = {
+  SIZE: 48,
+  SWEEP_WIDTH: 2.5,
+  CENTER_DOT_SIZE: 8,
+  TRAIL_ARMS: [
+    { key: 'sweep', offsetDeg: 0, opacity: 0.9 },
+    { key: 'trail-1', offsetDeg: -18, opacity: 0.45 },
+    { key: 'trail-2', offsetDeg: -36, opacity: 0.3 },
+    { key: 'trail-3', offsetDeg: -54, opacity: 0.2 },
+  ],
+} as const;

package/src/fiber/FiberAdapter.ts

@@ -0,0 +1,153 @@
+import { MEASURE_TIMEOUT_MS } from '../constants';
+import { flattenStyles } from '../utils/flattenStyles';
+import { type FiberNode, HOST_COMPONENT_TAG } from './types';
+
+/**
+ * Unified API for all fiber tree access.
+ * Abstracts away React version differences.
+ */
+export const FiberAdapter = {
+  /**
+   * Get the fiber root from the React DevTools global hook.
+   * Returns null if the hook is not available (production build).
+   */
+  getFiberRoot: (): FiberNode | null => {
+    const hook = (globalThis as Record<string, unknown>).__REACT_DEVTOOLS_GLOBAL_HOOK__ as
+      | {
+          renderers?: Map<number, unknown>;
+          getFiberRoots?: (id: number) => Set<{ current: FiberNode }>;
+        }
+      | undefined;
+
+    if (!(hook?.renderers && hook.getFiberRoots)) return null;
+
+    // Try each renderer ID — the RN renderer isn't always ID 1
+    for (const rendererId of hook.renderers.keys()) {
+      const roots = hook.getFiberRoots(rendererId);
+      if (!roots || roots.size === 0) continue;
+
+      const root = roots.values().next().value;
+      if (root?.current) return root.current;
+    }
+
+    return null;
+  },
+
+  /**
+   * Walk the fiber tree and collect all host component fibers with their depth.
+   * Depth is needed later for z-ordering in the layout snapshot.
+   */
+  walkHostFibers: (root: FiberNode): Array<{ fiber: FiberNode; depth: number }> => {
+    const hostFibers: Array<{ fiber: FiberNode; depth: number }> = [];
+
+    const walk = (fiber: FiberNode | null, depth: number) => {
+      let current = fiber;
+      while (current) {
+        if (current.tag === HOST_COMPONENT_TAG) {
+          hostFibers.push({ fiber: current, depth });
+        }
+
+        walk(current.child, depth + 1);
+        current = current.sibling;
+      }
+    };
+
+    walk(root.child, 0);
+    return hostFibers;
+  },
+
+  /**
+   * Get the flattened style object from a fiber's props.
+   */
+  getStyle: (fiber: FiberNode): Record<string, unknown> | null => {
+    return flattenStyles(fiber.memoizedProps?.style);
+  },
+
+  /**
+   * Get the source file location from a fiber's debug info.
+   */
+  getSource: (fiber: FiberNode): { fileName: string; lineNumber: number } | null => {
+    return fiber._debugSource ?? null;
+  },
+
+  /**
+   * Get the display name of the component.
+   */
+  getComponentName: (fiber: FiberNode): string => {
+    if (typeof fiber.type === 'string') return fiber.type;
+    if (typeof fiber.type === 'function')
+      return fiber.type.displayName ?? fiber.type.name ?? 'Unknown';
+    return 'Unknown';
+  },
+
+  /**
+   * Measure a fiber's native view on screen.
+   * Returns a promise with { x, y, width, height }.
+   */
+  measure: (fiber: FiberNode): Promise<{ x: number; y: number; width: number; height: number }> => {
+    type MeasureCallback = (
+      x: number,
+      y: number,
+      width: number,
+      height: number,
+      pageX: number,
+      pageY: number,
+    ) => void;
+    type Measurable = { measure?: (cb: MeasureCallback) => void };
+
+    return new Promise((resolve, reject) => {
+      const stateNode = fiber.stateNode as
+        | (Measurable & {
+            canonical?: Measurable & { publicInstance?: Measurable };
+          })
+        | null;
+
+      // Old arch: stateNode.measure()
+      // Fabric: stateNode.canonical.publicInstance.measure()
+      const target = stateNode?.measure
+        ? stateNode
+        : (stateNode?.canonical?.publicInstance ?? stateNode?.canonical);
+
+      if (!target?.measure) {
+        reject(new Error('Fiber stateNode does not support measure()'));
+        return;
+      }
+
+      const timeoutId = setTimeout(() => {
+        reject(new Error('measure() timed out'));
+      }, MEASURE_TIMEOUT_MS);
+
+      target.measure((_x, _y, width, height, pageX, pageY) => {
+        clearTimeout(timeoutId);
+        resolve({ x: pageX, y: pageY, width, height });
+      });
+    });
+  },
+
+  /**
+   * Replace the style on a fiber using the devtools hook.
+   * Caller is responsible for building the final style object.
+   * Works on both old arch and Fabric.
+   */
+  setStyle: (fiber: FiberNode, style: unknown): boolean => {
+    const hook = (globalThis as Record<string, unknown>).__REACT_DEVTOOLS_GLOBAL_HOOK__ as
+      | {
+          renderers?: Map<
+            number,
+            { overrideProps?: (fiber: FiberNode, path: string[], value: unknown) => void }
+          >;
+        }
+      | undefined;
+
+    if (!hook?.renderers) return false;
+
+    for (const renderer of hook.renderers.values()) {
+      if (renderer?.overrideProps) {
+        renderer.overrideProps(fiber, ['style'], style);
+        return true;
+      }
+    }
+
+    return false;
+  },
+};

package/src/fiber/detectVersion.ts

@@ -0,0 +1,19 @@
+/**
+ * Detect the React version at runtime from the renderer.
+ * Used to load the correct fiber adapter if needed.
+ */
+export const detectReactVersion = (): { major: number; minor: number } | null => {
+  const hook = (globalThis as Record<string, unknown>).__REACT_DEVTOOLS_GLOBAL_HOOK__ as
+    | { renderers?: Map<number, { version?: string }> }
+    | undefined;
+
+  if (!hook?.renderers) return null;
+
+  for (const renderer of hook.renderers.values()) {
+    if (!renderer?.version) continue;
+    const [major, minor] = renderer.version.split('.').map(Number);
+    return { major: major ?? 0, minor: minor ?? 0 };
+  }
+
+  return null;
+};

package/src/fiber/index.ts

@@ -0,0 +1,4 @@
+export { detectReactVersion } from './detectVersion';
+export { FiberAdapter } from './FiberAdapter';
+export type { FiberNode, MeasuredElement } from './types';
+export { HOST_COMPONENT_TAG } from './types';

package/src/fiber/types.ts

@@ -0,0 +1,36 @@
+/** React component function with optional display name. */
+type ComponentFunction = ((...args: never[]) => unknown) & {
+  displayName?: string;
+  name?: string;
+};
+
+/** Minimal fiber node type — only the fields we access. */
+export interface FiberNode {
+  tag: number;
+  type: string | ComponentFunction;
+  memoizedProps: Record<string, unknown>;
+  stateNode: unknown;
+  child: FiberNode | null;
+  sibling: FiberNode | null;
+  return: FiberNode | null;
+  _debugSource?: {
+    fileName: string;
+    lineNumber: number;
+    columnNumber?: number;
+  };
+  _debugOwner?: FiberNode;
+}
+
+/** Host component fiber tag — View, Text, Image, etc. */
+export const HOST_COMPONENT_TAG = 5;
+
+export interface MeasuredElement {
+  fiber: FiberNode;
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+  depth: number;
+  zIndex: number;
+  componentName: string;
+}

package/src/floatingPanel/AddPropertyRow.tsx

@@ -0,0 +1,102 @@
+import { useState } from 'react';
+import { Pressable, StyleSheet, Text, View } from 'react-native';
+import { MONOSPACE_FONT } from '../constants';
+import { EditableValue } from './EditableValue';
+
+interface AddPropertyRowProps {
+  onAdd: (key: string, value: unknown) => void;
+  onCancel: () => void;
+}
+
+/** Inline two-step row for adding a new style property: type key → type value → applied. */
+export const AddPropertyRow = ({ onAdd, onCancel }: AddPropertyRowProps) => {
+  const [key, setKey] = useState('');
+  const [waitingForValue, setWaitingForValue] = useState(false);
+
+  if (!waitingForValue) {
+    return (
+      <View style={styles.row}>
+        <View style={styles.content}>
+          <EditableValue
+            value=''
+            displayValue=''
+            onSubmit={(newKey) => {
+              const trimmed = String(newKey).trim();
+              if (!trimmed) {
+                onCancel();
+                return;
+              }
+              setKey(trimmed);
+              setWaitingForValue(true);
+            }}
+            variant='key'
+            initialEditing
+          />
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.row}>
+      <View style={styles.content}>
+        <Text style={styles.pendingKey}>{key}:</Text>
+        <EditableValue
+          value=''
+          displayValue=''
+          onSubmit={(newValue) => {
+            const trimmed = String(newValue).trim();
+            if (!trimmed) {
+              onCancel();
+              return;
+            }
+            onAdd(key, newValue);
+          }}
+          variant='value'
+          initialEditing
+        />
+      </View>
+    </View>
+  );
+};
+
+interface AddPropertyButtonProps {
+  onPress: () => void;
+}
+
+/** Dim "+ add property" button shown at the bottom of the style list. */
+export const AddPropertyButton = ({ onPress }: AddPropertyButtonProps) => (
+  <Pressable style={styles.button} onPress={onPress} hitSlop={6}>
+    <Text style={styles.buttonText}>+ add property</Text>
+  </Pressable>
+);
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    paddingVertical: 5,
+    paddingHorizontal: 8,
+    borderRadius: 4,
+  },
+  content: {
+    flex: 1,
+    flexDirection: 'row',
+    justifyContent: 'space-between',
+    alignItems: 'center',
+  },
+  pendingKey: {
+    color: '#9CDCFE',
+    fontSize: 13,
+    fontFamily: MONOSPACE_FONT,
+  },
+  button: {
+    paddingVertical: 6,
+    paddingHorizontal: 8,
+  },
+  buttonText: {
+    color: '#666',
+    fontSize: 12,
+    fontFamily: MONOSPACE_FONT,
+  },
+});

package/src/floatingPanel/CloseButton.tsx

@@ -0,0 +1,34 @@
+import { StyleSheet, Text, TouchableOpacity } from 'react-native';
+
+interface CloseButtonProps {
+  onPress: () => void;
+}
+
+/** Reusable red-tinted circular close button used across panel states. */
+export const CloseButton = ({ onPress }: CloseButtonProps) => (
+  <TouchableOpacity
+    onPress={onPress}
+    hitSlop={{ top: 8, bottom: 8, left: 8, right: 8 }}
+    style={styles.button}
+    activeOpacity={0.6}
+  >
+    <Text style={styles.text}>✕</Text>
+  </TouchableOpacity>
+);
+
+const styles = StyleSheet.create({
+  button: {
+    width: 22,
+    height: 22,
+    borderRadius: 11,
+    backgroundColor: 'rgba(255, 59, 48, 0.15)',
+    alignItems: 'center',
+    justifyContent: 'center',
+  },
+  text: {
+    color: '#FF3B30',
+    fontSize: 13,
+    fontWeight: '600',
+    lineHeight: 14,
+  },
+});