@buoy-gg/debug-borders 2.0.2

package/README.md

@@ -0,0 +1,334 @@
+# @buoy/debug-borders
+
+A visual layout debugging tool for React Native that highlights components with colored borders and labels. Features three display modes, smart filtering to show only meaningful components, and tap-to-inspect functionality. Works with Expo, React Native CLI, and supports both the new architecture (Fabric) and legacy architecture.
+
+## Features
+
+- **Three Display Modes**: Cycle through Off → Borders → Labels with a single tap
+- **Smart Filtering**: Only shows borders/labels for components with `testID` or `accessibilityLabel`
+- **Tap-to-Inspect**: Tap any label to see detailed component information in a modal
+- **Color-Coded Labels**: Labels match border colors based on identifier type (testID = green, accessibilityLabel = pink)
+- **Label Stacking**: Overlapping labels automatically stack upward like a menu
+- **Hidden Screen Detection**: Automatically hides borders on inactive screens in stack navigators
+- **DevTools Aware**: Hides borders when DevTools modals are open
+- **Real-Time Updates**: Automatically tracks layout changes (updates every 2 seconds)
+- **Touch-Through**: Borders don't interfere with touch interactions
+- **Performance Optimized**: Minimal impact (~30ms to measure 400+ components)
+
+## Installation
+
+```bash
+npm install @buoy/debug-borders
+# or
+pnpm add @buoy/debug-borders
+# or
+yarn add @buoy/debug-borders
+```
+
+## Quick Start
+
+```tsx
+import { debugBordersToolPreset, DebugBordersStandaloneOverlay } from '@buoy/debug-borders';
+import { FloatingDevTools } from '@buoy/core';
+
+const installedApps = [
+  debugBordersToolPreset, // Add the tool to your menu
+  // ...your other tools
+];
+
+function App() {
+  return (
+    <>
+      <FloatingDevTools
+        apps={installedApps}
+        environment="local"
+        userRole="admin"
+      />
+
+      {/* IMPORTANT: Render overlay at root level */}
+      <DebugBordersStandaloneOverlay />
+
+      {/* Your app content */}
+      <YourAppContent />
+    </>
+  );
+}
+```
+
+**Done!** Tap the BORDERS icon in the floating menu to cycle through modes.
+
+## Display Modes
+
+The tool cycles through three modes when you tap the icon:
+
+| Mode | Icon Color | Description |
+|------|------------|-------------|
+| **Off** | Gray | No borders displayed |
+| **Borders** | Green | Rainbow-colored borders for all components (depth-based colors) |
+| **Labels** | Cyan | Borders + labels only for components with `testID` or `accessibilityLabel` |
+
+### Labels Mode Features
+
+In Labels mode, the tool provides focused debugging:
+
+- **Only shows components with identifiers** - Components with `testID` or `accessibilityLabel` get borders and labels
+- **Color-coded by identifier type**:
+  - 🟢 Green = `testID`
+  - 🩷 Pink = `accessibilityLabel`
+- **Labels positioned above boxes** - Easy to read without obscuring content
+- **Automatic stacking** - Overlapping labels stack upward like a menu
+- **Tap to inspect** - Tap any label to see full component details
+
+## Tap-to-Inspect Modal
+
+Tap any label in Labels mode to open a detailed inspection modal showing:
+
+### Identifiers
+- `testID` (green)
+- `accessibilityLabel` (pink)
+- `nativeID` (amber)
+- `key`
+
+### Component Info
+- Component Name (the React component that rendered this)
+- Parent Component
+- Display Name (friendly name like "View", "Text")
+- Native View Type (e.g., "RCTView", "RCTText")
+- Fiber Tag
+
+### Position & Size
+- X, Y coordinates
+- Width, Height
+- Depth in component tree
+
+### Accessibility
+- Role
+- Hint
+- State (displayed with interactive DataViewer)
+
+### Styles
+- Full computed styles (displayed with interactive DataViewer)
+
+## Usage Examples
+
+### Basic Usage with Preset
+
+```tsx
+import { debugBordersToolPreset, DebugBordersStandaloneOverlay } from '@buoy/debug-borders';
+
+// Add to your FloatingDevTools apps array
+const installedApps = [debugBordersToolPreset];
+
+// Render overlay at root level
+<DebugBordersStandaloneOverlay />
+
+// Tap the BORDERS icon to cycle: Off → Borders → Labels → Off
+```
+
+### Custom Configuration
+
+```tsx
+import { createDebugBordersTool, DebugBordersStandaloneOverlay } from '@buoy/debug-borders';
+
+const customBordersTool = createDebugBordersTool({
+  name: "LAYOUT",
+  description: "Layout visualizer",
+  offColor: "#9ca3af",      // Gray when off
+  bordersColor: "#ec4899",  // Pink in borders mode
+  labelsColor: "#8b5cf6",   // Purple in labels mode
+  id: "custom-borders",
+});
+
+const installedApps = [customBordersTool];
+```
+
+### Programmatic Control
+
+```tsx
+import { DebugBordersManager, DebugBordersStandaloneOverlay } from '@buoy/debug-borders';
+
+// Get current mode
+const mode = DebugBordersManager.getMode(); // "off" | "borders" | "labels"
+
+// Set specific mode
+DebugBordersManager.setMode("borders");
+DebugBordersManager.setMode("labels");
+DebugBordersManager.setMode("off");
+
+// Cycle to next mode
+DebugBordersManager.cycle(); // off → borders → labels → off
+
+// Check if labels should be shown
+const showLabels = DebugBordersManager.showLabels(); // true when mode is "labels"
+
+// Subscribe to mode changes
+const unsubscribe = DebugBordersManager.subscribe((mode) => {
+  console.log('Mode changed to:', mode);
+});
+
+// Clean up
+unsubscribe();
+```
+
+## API Reference
+
+### Preset
+
+#### `debugBordersToolPreset`
+
+Pre-configured tool for FloatingDevTools. Shows only in the floating menu (not the dial).
+
+```tsx
+import { debugBordersToolPreset } from '@buoy/debug-borders';
+
+const installedApps = [debugBordersToolPreset];
+```
+
+### Functions
+
+#### `createDebugBordersTool(options?)`
+
+Create a custom debug borders tool configuration.
+
+**Options:**
+- `name?: string` - Tool name (default: "BORDERS")
+- `description?: string` - Tool description
+- `offColor?: string` - Icon color when off (default: "#6b7280" gray)
+- `bordersColor?: string` - Icon color in borders mode (default: "#10b981" green)
+- `labelsColor?: string` - Icon color in labels mode (default: "#06b6d4" cyan)
+- `id?: string` - Custom tool ID (default: "debug-borders")
+
+### Components
+
+#### `<DebugBordersStandaloneOverlay />`
+
+The main overlay component that renders borders and labels. **Must be rendered at root level.**
+
+```tsx
+import { DebugBordersStandaloneOverlay } from '@buoy/debug-borders';
+
+<DebugBordersStandaloneOverlay />
+```
+
+**Note:** This component must be rendered at the root level of your app, outside all modals and navigation containers, for borders to appear on top of everything.
+
+### Manager API
+
+#### `DebugBordersManager`
+
+Global state manager for controlling debug borders.
+
+**Methods:**
+- `getMode(): "off" | "borders" | "labels"` - Get current display mode
+- `setMode(mode)` - Set display mode
+- `cycle()` - Cycle to next mode (off → borders → labels → off)
+- `showLabels(): boolean` - Check if labels should be shown (mode === "labels")
+- `subscribe(callback: (mode) => void): () => void` - Subscribe to mode changes
+
+## How It Works
+
+### Smart Filtering
+
+The tool intelligently filters what it displays:
+
+1. **Hidden Screen Detection** - Skips components in inactive screens (React Navigation stack)
+2. **SVG Filtering** - Excludes SVG elements (RNSVG* components)
+3. **DevTools Filtering** - Excludes FloatingDevTools, modals, and other dev tool components
+4. **Identifier Filtering** (Labels mode) - Only shows components with `testID` or `accessibilityLabel`
+
+### Label Positioning
+
+Labels are positioned above their component boxes and automatically stack when they would overlap:
+
+```
+┌─────────────────────────────────────┐
+│ [submitButton]                      │  ← Labels stack upward
+│ [formContainer]                     │
+├─────────────────────────────────────┤
+│                                     │
+│        Component Content            │
+│                                     │
+└─────────────────────────────────────┘
+```
+
+### Color Scheme
+
+**Borders Mode** - Colors based on nesting depth using golden angle (137.5°):
+| Depth | Color |
+|-------|-------|
+| 0 | Red-Orange |
+| 1 | Green |
+| 2 | Blue |
+| 3+ | Continues with golden angle |
+
+**Labels Mode** - Colors based on identifier type:
+| Identifier | Color |
+|------------|-------|
+| testID | Green (#10b981) |
+| accessibilityLabel | Pink (#ec4899) |
+| componentName | Purple (#a855f7) |
+| nativeID | Amber (#f59e0b) |
+| viewType (fallback) | Gray (#6b7280) |
+
+## Performance
+
+- **Measurement Time:** ~30ms for 400+ components
+- **Update Frequency:** Every 2 seconds when enabled
+- **Memory Impact:** Minimal (only stores rectangle data)
+- **Runtime Impact:** Zero when disabled
+- **Label Positioning:** O(n²) worst case, optimized with early exits
+
+## Compatibility
+
+- React Native >= 0.70.0
+- Fabric (New Architecture)
+- Paper (Legacy Architecture)
+- Expo
+- React Native CLI
+
+## Troubleshooting
+
+### Borders not showing?
+
+1. Make sure `DebugBordersStandaloneOverlay` is rendered at root level
+2. Tap the icon to cycle modes - you may be in "off" mode
+3. In Labels mode, borders only show for components with `testID` or `accessibilityLabel`
+4. Verify you're in development mode (`__DEV__` is true)
+
+### Labels overlapping content?
+
+Labels are positioned above component boxes. If they still overlap, they automatically stack upward. Very dense UIs may have many stacked labels.
+
+### Can't tap labels?
+
+Make sure you're in Labels mode (cyan icon). In Borders mode, labels aren't shown and tapping doesn't work.
+
+### Modal not scrolling?
+
+The inspection modal uses the standard JsModal component. Swipe up to expand it or drag the handle to resize.
+
+## Structure
+
+```
+debug-borders/
+├── src/
+│   ├── index.tsx              # Main exports
+│   ├── preset.tsx             # Preset configuration
+│   └── debug-borders/
+│       ├── components/
+│       │   └── DebugBordersStandaloneOverlay.tsx
+│       └── utils/
+│           ├── DebugBordersManager.js    # State manager (3 modes)
+│           ├── fiberTreeTraversal.js     # Fiber traversal + filtering
+│           ├── componentMeasurement.js   # Component measurements
+│           ├── componentInfo.js          # Label extraction
+│           ├── labelPositioning.js       # Overlap resolution
+│           ├── ViewTypeMapper.ts         # Native → friendly names
+│           └── colorGeneration.js        # Color generation
+├── package.json
+└── README.md
+```
+
+## License
+
+MIT

package/lib/commonjs/debug-borders/components/DebugBordersModal.js

@@ -0,0 +1,234 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.DebugBordersModal = DebugBordersModal;
+var _react = _interopRequireWildcard(require("react"));
+var _reactNative = require("react-native");
+var _sharedUi = require("@buoy-gg/shared-ui");
+var _jsxRuntime = require("react/jsx-runtime");
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+const DebugBordersManager = require("../utils/DebugBordersManager");
+
+/**
+ * Modal component for controlling debug borders.
+ * This allows developers to toggle visual layout debugging borders on/off.
+ */
+function DebugBordersModal({
+  visible,
+  onClose
+}) {
+  const [enabled, setEnabled] = (0, _react.useState)(false);
+  const [componentCount, setComponentCount] = (0, _react.useState)(0);
+
+  // Subscribe to manager state
+  (0, _react.useEffect)(() => {
+    const unsubscribe = DebugBordersManager.subscribe(setEnabled);
+    setEnabled(DebugBordersManager.isEnabled());
+    return unsubscribe;
+  }, []);
+
+  // Track component count when enabled
+  (0, _react.useEffect)(() => {
+    if (!enabled) {
+      setComponentCount(0);
+      return;
+    }
+
+    // Update component count periodically
+    const updateCount = () => {
+      try {
+        const {
+          getAllHostComponentInstances
+        } = require("../utils/fiberTreeTraversal");
+        const instances = getAllHostComponentInstances();
+        setComponentCount(instances.length);
+      } catch (error) {
+        console.error("[DebugBorders] Error getting component count:", error);
+      }
+    };
+
+    // Initial count
+    setTimeout(updateCount, 600);
+
+    // Update every 2 seconds
+    const interval = setInterval(updateCount, 2000);
+    return () => clearInterval(interval);
+  }, [enabled]);
+  const handleToggle = () => {
+    DebugBordersManager.toggle();
+  };
+  if (!visible) return null;
+  return /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+    style: styles.container,
+    children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+      style: styles.content,
+      children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.title,
+        children: "Debug Borders"
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+        style: styles.description,
+        children: "Visualize component layout structure with colored borders"
+      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.statusRow,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.statusLabel,
+          children: "Status:"
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.StatusBadge, {
+          status: enabled ? "active" : "inactive"
+        })]
+      }), enabled && componentCount > 0 && /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.statsRow,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.statsLabel,
+          children: "Components Tracked:"
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.statsValue,
+          children: componentCount
+        })]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.View, {
+        style: styles.toggleContainer,
+        children: /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.TouchableOpacity, {
+          style: [styles.button, enabled && styles.buttonActive],
+          onPress: handleToggle,
+          accessibilityRole: "button",
+          accessibilityLabel: `Debug borders ${enabled ? "enabled" : "disabled"}`,
+          accessibilityHint: "Tap to toggle debug borders",
+          children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.Layers, {
+            size: 40,
+            color: enabled ? _sharedUi.macOSColors.semantic.success : _sharedUi.macOSColors.text.secondary
+          }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+            style: [styles.buttonText, enabled && styles.buttonTextActive],
+            children: enabled ? "Disable Borders" : "Enable Borders"
+          })]
+        })
+      }), /*#__PURE__*/(0, _jsxRuntime.jsxs)(_reactNative.View, {
+        style: styles.infoBox,
+        children: [/*#__PURE__*/(0, _jsxRuntime.jsx)(_sharedUi.StatusIndicator, {
+          status: enabled ? "success" : "info",
+          size: "small"
+        }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.infoText,
+          children: enabled ? "Borders update every 2 seconds. Tap button to disable." : "Tap button to show colored borders around all components."
+        })]
+      }), /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.TouchableOpacity, {
+        style: styles.closeButton,
+        onPress: onClose,
+        children: /*#__PURE__*/(0, _jsxRuntime.jsx)(_reactNative.Text, {
+          style: styles.closeButtonText,
+          children: "Close"
+        })
+      })]
+    })
+  });
+}
+const styles = _reactNative.StyleSheet.create({
+  container: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+    backgroundColor: "rgba(0, 0, 0, 0.5)"
+  },
+  content: {
+    backgroundColor: _sharedUi.macOSColors.background.card,
+    borderRadius: 16,
+    padding: 32,
+    width: "85%",
+    maxWidth: 420,
+    alignItems: "center"
+  },
+  title: {
+    fontSize: 24,
+    fontWeight: "700",
+    color: _sharedUi.macOSColors.text.primary,
+    marginBottom: 8
+  },
+  description: {
+    fontSize: 14,
+    color: _sharedUi.macOSColors.text.secondary,
+    textAlign: "center",
+    marginBottom: 24
+  },
+  statusRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    marginBottom: 16,
+    gap: 8
+  },
+  statusLabel: {
+    fontSize: 14,
+    color: _sharedUi.macOSColors.text.secondary,
+    fontWeight: "600"
+  },
+  statsRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    marginBottom: 16,
+    gap: 8
+  },
+  statsLabel: {
+    fontSize: 14,
+    color: _sharedUi.macOSColors.text.secondary,
+    fontWeight: "600"
+  },
+  statsValue: {
+    fontSize: 16,
+    color: _sharedUi.macOSColors.text.primary,
+    fontWeight: "700"
+  },
+  toggleContainer: {
+    alignItems: "center",
+    justifyContent: "center",
+    marginBottom: 24
+  },
+  button: {
+    alignItems: "center",
+    justifyContent: "center",
+    padding: 24,
+    borderRadius: 16,
+    backgroundColor: _sharedUi.macOSColors.background.hover,
+    borderWidth: 2,
+    borderColor: _sharedUi.macOSColors.border.default,
+    minWidth: 200
+  },
+  buttonActive: {
+    borderColor: _sharedUi.macOSColors.semantic.success,
+    backgroundColor: `${_sharedUi.macOSColors.semantic.success}15`
+  },
+  buttonText: {
+    marginTop: 12,
+    fontSize: 16,
+    fontWeight: "600",
+    color: _sharedUi.macOSColors.text.secondary
+  },
+  buttonTextActive: {
+    color: _sharedUi.macOSColors.semantic.success
+  },
+  infoBox: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    backgroundColor: _sharedUi.macOSColors.background.hover,
+    padding: 12,
+    borderRadius: 8,
+    marginBottom: 24,
+    gap: 8
+  },
+  infoText: {
+    flex: 1,
+    fontSize: 12,
+    color: _sharedUi.macOSColors.text.secondary,
+    lineHeight: 16
+  },
+  closeButton: {
+    paddingVertical: 12,
+    paddingHorizontal: 32,
+    backgroundColor: _sharedUi.macOSColors.semantic.info,
+    borderRadius: 8
+  },
+  closeButtonText: {
+    color: _sharedUi.macOSColors.text.primary,
+    fontSize: 16,
+    fontWeight: "600"
+  }
+});