rn-backstage 1.0.0

package/src/components/TabBar.tsx

@@ -0,0 +1,150 @@
+import React, { useCallback, useRef, useEffect } from 'react'
+import {
+  Animated,
+  LayoutChangeEvent,
+  ScrollView,
+  StyleSheet,
+  Text,
+  TouchableOpacity,
+  View,
+} from 'react-native'
+import { DarkTheme, MonospaceFont } from '../constants'
+
+// ─── Types ───────────────────────────────────────────────────────────────────
+
+interface Tab {
+  key: string
+  title: string
+  icon?: string
+}
+
+interface TabBarProps {
+  tabs: Tab[]
+  activeTab: string
+  onTabChange: (key: string) => void
+}
+
+// ─── Component ───────────────────────────────────────────────────────────────
+
+export const TabBar: React.FC<TabBarProps> = ({ tabs, activeTab, onTabChange }) => {
+  const indicatorAnim = useRef(new Animated.Value(0)).current
+  const tabWidths = useRef<Record<string, number>>({})
+  const tabOffsets = useRef<Record<string, number>>({})
+  const scrollRef = useRef<ScrollView>(null)
+
+  // Animate indicator when active tab changes
+  useEffect(() => {
+    const offset = tabOffsets.current[activeTab] || 0
+    Animated.spring(indicatorAnim, {
+      toValue: offset,
+      useNativeDriver: true,
+      friction: 8,
+      tension: 60,
+    }).start()
+  }, [activeTab, indicatorAnim])
+
+  const handleTabLayout = useCallback(
+    (key: string) => (e: LayoutChangeEvent) => {
+      const { x, width } = e.nativeEvent.layout
+      tabWidths.current[key] = width
+      tabOffsets.current[key] = x
+
+      // Re-animate if this is the active tab
+      if (key === activeTab) {
+        indicatorAnim.setValue(x)
+      }
+    },
+    [activeTab, indicatorAnim],
+  )
+
+  const activeWidth = tabWidths.current[activeTab] || 80
+
+  return (
+    <View style={styles.container}>
+      <ScrollView
+        ref={scrollRef}
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        contentContainerStyle={styles.scrollContent}
+      >
+        {tabs.map(tab => {
+          const isActive = tab.key === activeTab
+          return (
+            <TouchableOpacity
+              key={tab.key}
+              onPress={() => onTabChange(tab.key)}
+              onLayout={handleTabLayout(tab.key)}
+              style={styles.tab}
+              activeOpacity={0.7}
+              testID={`backstage.tab.${tab.key}`}
+            >
+              {tab.icon && (
+                <Text style={[styles.tabIcon, isActive && styles.tabIconActive]}>{tab.icon}</Text>
+              )}
+              <Text style={[styles.tabText, isActive && styles.tabTextActive]}>{tab.title}</Text>
+            </TouchableOpacity>
+          )
+        })}
+
+        {/* Animated underline */}
+        <Animated.View
+          style={[
+            styles.indicator,
+            {
+              width: activeWidth,
+              transform: [{ translateX: indicatorAnim }],
+            },
+          ]}
+        />
+      </ScrollView>
+    </View>
+  )
+}
+
+// ─── Styles ──────────────────────────────────────────────────────────────────
+
+const styles = StyleSheet.create({
+  container: {
+    borderBottomWidth: 1,
+    borderBottomColor: DarkTheme.border,
+  },
+  scrollContent: {
+    flexDirection: 'row',
+    position: 'relative',
+    paddingBottom: 0,
+  },
+  tab: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'center',
+    paddingHorizontal: 20,
+    paddingVertical: 14,
+    minWidth: 80,
+  },
+  tabIcon: {
+    fontSize: 14,
+    marginRight: 6,
+    opacity: 0.5,
+  },
+  tabIconActive: {
+    opacity: 1,
+  },
+  tabText: {
+    fontFamily: MonospaceFont,
+    fontSize: 13,
+    fontWeight: '600',
+    color: DarkTheme.textMuted,
+    textTransform: 'uppercase',
+    letterSpacing: 1,
+  },
+  tabTextActive: {
+    color: DarkTheme.accent,
+  },
+  indicator: {
+    position: 'absolute',
+    bottom: 0,
+    height: 2,
+    backgroundColor: DarkTheme.accent,
+    borderRadius: 1,
+  },
+})

package/src/constants.ts

@@ -0,0 +1,82 @@
+import { Dimensions, Platform } from 'react-native'
+import type { BackstageTheme } from './types'
+
+// ─── Metrics ─────────────────────────────────────────────────────────────────
+
+const { width: screenWidth, height: screenHeight } = Dimensions.get('window')
+
+export const Metrics = {
+  screenWidth,
+  screenHeight,
+  isIOS: Platform.OS === 'ios',
+  pillWidth: 72,
+  pillHeight: 32,
+  panelBorderRadius: 20,
+  tabBarHeight: 48,
+  headerHeight: 52,
+  sectionSpacing: 16,
+  contentPadding: 16,
+}
+
+// ─── Dark Theme ──────────────────────────────────────────────────────────────
+
+export const DarkTheme: BackstageTheme = {
+  background: '#0D0D12',
+  surface: '#16161E',
+  surfaceElevated: '#1E1E2A',
+  border: '#2A2A3A',
+  text: '#E8E8ED',
+  textSecondary: '#A0A0B0',
+  textMuted: '#606075',
+  accent: '#7C5CFC',
+  accentDim: 'rgba(124, 92, 252, 0.15)',
+  error: '#FF4D6A',
+  errorDim: 'rgba(255, 77, 106, 0.12)',
+  warning: '#FFB224',
+  warningDim: 'rgba(255, 178, 36, 0.12)',
+  success: '#34D399',
+  info: '#38BDF8',
+  infoDim: 'rgba(56, 189, 248, 0.12)',
+  debugColor: '#A78BFA',
+  debugDim: 'rgba(167, 139, 250, 0.12)',
+}
+
+// ─── Max Logs ────────────────────────────────────────────────────────────────
+
+export const DEFAULT_MAX_LOGS = 500
+
+// ─── Monospace Font ──────────────────────────────────────────────────────────
+
+export const MonospaceFont = Platform.select({
+  ios: 'Menlo',
+  default: 'monospace',
+})
+
+// ─── Test IDs ────────────────────────────────────────────────────────────────
+
+export const TestIDs = {
+  floatingPill: 'backstage.floating-pill',
+  panel: 'backstage.panel',
+  header: {
+    container: 'backstage.header',
+    title: 'backstage.header.title',
+    closeButton: 'backstage.header.close',
+  },
+  tabBar: 'backstage.tab-bar',
+  tabs: {
+    info: 'backstage.tab.info',
+    logs: 'backstage.tab.logs',
+  },
+  infoTab: {
+    section: 'backstage.info',
+    deviceInfo: 'backstage.info.device',
+    stateTree: 'backstage.info.state-tree',
+    quickActions: 'backstage.info.quick-actions',
+  },
+  logsTab: {
+    section: 'backstage.logs',
+    searchInput: 'backstage.logs.search',
+    copyButton: 'backstage.logs.copy',
+    list: 'backstage.logs.list',
+  },
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { Backstage } from './Backstage'
+
+export type {
+  BackstageProps,
+  BackstageRef,
+  BackstageTab,
+  BackstageStyleOverrides,
+  BackstageTheme,
+  QuickAction,
+  AppInfoItem,
+  LogEntry,
+} from './types'
+
+export { LogLevel } from './types'

package/src/log-interceptor.ts

@@ -0,0 +1,137 @@
+import { LogLevel } from './types'
+import type { LogEntry } from './types'
+import { formatLogMessage } from './utils/stringify'
+import { DEFAULT_MAX_LOGS } from './constants'
+
+// ─── Original Console Methods ────────────────────────────────────────────────
+
+const originalConsole = {
+  log: console.log,
+  debug: console.debug,
+  info: console.info,
+  warn: console.warn,
+  error: console.error,
+}
+
+type LogCallback = (entry: LogEntry) => void
+
+let activeCallback: LogCallback | null = null
+let isInstalled = false
+
+// ─── Helpers ─────────────────────────────────────────────────────────────────
+
+function generateId(): string {
+  return `${Date.now()}_${Math.random().toString(36).substring(2, 9)}`
+}
+
+function createLogEntry(level: LogLevel, message: unknown, optionalParams: unknown[]): LogEntry {
+  const formattedMessage = formatLogMessage(message, optionalParams)
+  const hasObjectData =
+    (typeof message === 'object' && message !== null) ||
+    optionalParams.some(p => typeof p === 'object' && p !== null)
+
+  return {
+    id: generateId(),
+    level,
+    message: formattedMessage,
+    data: hasObjectData ? { message, params: optionalParams } : undefined,
+    timestamp: Date.now(),
+  }
+}
+
+function shouldLog(message: unknown, filters: string[]): boolean {
+  if (filters.length === 0) return true
+
+  const messageStr =
+    typeof message === 'string'
+      ? message.toLowerCase()
+      : typeof message === 'object' && message !== null
+        ? JSON.stringify(message).toLowerCase()
+        : String(message).toLowerCase()
+
+  return !filters.some(filter => messageStr.includes(filter.toLowerCase()))
+}
+
+// ─── Install / Uninstall ─────────────────────────────────────────────────────
+
+export function installInterceptor(callback: LogCallback, filters: string[] = []): void {
+  if (isInstalled) {
+    // Just update callback if already installed
+    activeCallback = callback
+    return
+  }
+
+  activeCallback = callback
+  isInstalled = true
+
+  const levels: Array<[LogLevel, keyof typeof originalConsole]> = [
+    [LogLevel.log, 'log'],
+    [LogLevel.debug, 'debug'],
+    [LogLevel.info, 'info'],
+    [LogLevel.warn, 'warn'],
+    [LogLevel.error, 'error'],
+  ]
+
+  for (const [level, method] of levels) {
+    console[method] = (message?: unknown, ...optionalParams: unknown[]) => {
+      // Always forward to original console
+      originalConsole[method](message, ...optionalParams)
+
+      // Check filters
+      if (!shouldLog(message, filters)) return
+
+      // Create log entry and notify
+      if (activeCallback) {
+        const entry = createLogEntry(level, message, optionalParams)
+        activeCallback(entry)
+      }
+    }
+  }
+}
+
+export function uninstallInterceptor(): void {
+  if (!isInstalled) return
+
+  console.log = originalConsole.log
+  console.debug = originalConsole.debug
+  console.info = originalConsole.info
+  console.warn = originalConsole.warn
+  console.error = originalConsole.error
+
+  activeCallback = null
+  isInstalled = false
+}
+
+// ─── Log Buffer ──────────────────────────────────────────────────────────────
+
+export class LogBuffer {
+  private logs: LogEntry[] = []
+  private maxSize: number
+
+  constructor(maxSize = DEFAULT_MAX_LOGS) {
+    this.maxSize = maxSize
+  }
+
+  push(entry: LogEntry): void {
+    this.logs.unshift(entry)
+    if (this.logs.length > this.maxSize) {
+      this.logs = this.logs.slice(0, this.maxSize)
+    }
+  }
+
+  getAll(): LogEntry[] {
+    return [...this.logs]
+  }
+
+  clear(): void {
+    this.logs = []
+  }
+
+  get hasErrors(): boolean {
+    return this.logs.some(log => log.level === LogLevel.error)
+  }
+
+  get size(): number {
+    return this.logs.length
+  }
+}

package/src/types.ts

@@ -0,0 +1,147 @@
+import type { ReactNode } from 'react'
+import type { StyleProp, TextStyle, ViewStyle } from 'react-native'
+
+// ─── Log Types ───────────────────────────────────────────────────────────────
+
+export enum LogLevel {
+  log = 'log',
+  debug = 'debug',
+  info = 'info',
+  warn = 'warn',
+  error = 'error',
+}
+
+export interface LogEntry {
+  id: string
+  level: LogLevel
+  message: string
+  data?: unknown
+  timestamp: number
+}
+
+// ─── App Info ────────────────────────────────────────────────────────────────
+
+export interface AppInfoItem {
+  label: string
+  value: string
+}
+
+// ─── Quick Actions ───────────────────────────────────────────────────────────
+
+export interface QuickAction {
+  title: string
+  onPress: () => void
+  closeOnPress?: boolean
+  icon?: string
+  destructive?: boolean
+  testID?: string
+}
+
+// ─── Extensible Tabs ─────────────────────────────────────────────────────────
+
+export interface BackstageTab {
+  key: string
+  title: string
+  icon?: string
+  render: () => ReactNode
+}
+
+// ─── Theme ───────────────────────────────────────────────────────────────────
+
+export interface BackstageTheme {
+  background: string
+  surface: string
+  surfaceElevated: string
+  border: string
+  text: string
+  textSecondary: string
+  textMuted: string
+  accent: string
+  accentDim: string
+  error: string
+  errorDim: string
+  warning: string
+  warningDim: string
+  success: string
+  info: string
+  infoDim: string
+  debugColor: string
+  debugDim: string
+}
+
+// ─── Main Props ──────────────────────────────────────────────────────────────
+
+export interface BackstageProps {
+  /** Whether the floating pill trigger is visible. Default: true */
+  visible?: boolean
+
+  /** App version string (e.g., "1.2.3") */
+  appVersion?: string
+
+  /** Build number (e.g., "42") */
+  buildNumber?: string
+
+  /** Bundle identifier (e.g., "com.example.app") */
+  bundleId?: string
+
+  /** Additional device/app information rows */
+  deviceInfo?: AppInfoItem[]
+
+  /** State object to display in the tree viewer (Redux store, Zustand, etc.) */
+  state?: Record<string, unknown>
+
+  /** Custom action buttons in the Info tab */
+  quickActions?: QuickAction[]
+
+  /** Maximum number of logs to retain in memory. Default: 500 */
+  maxLogs?: number
+
+  /** Log messages containing these strings will be excluded */
+  logFilters?: string[]
+
+  /** Callback triggered when user copies logs */
+  onCopyLogs?: (logs: string) => void
+
+  /** Additional custom tabs beyond Info and Logs */
+  extraTabs?: BackstageTab[]
+
+  /** Extra content rendered at the bottom of the Info tab */
+  children?: ReactNode
+
+  /** Custom styles overrides */
+  styles?: BackstageStyleOverrides
+
+  /** Initial X position for the floating pill */
+  initialX?: number
+
+  /** Initial Y position for the floating pill */
+  initialY?: number
+
+  /** Text displayed on the floating pill. Defaults to appVersion or "DEV" */
+  pillText?: string
+}
+
+export interface BackstageStyleOverrides {
+  pillStyle?: StyleProp<ViewStyle>
+  pillTextStyle?: StyleProp<TextStyle>
+  panelStyle?: StyleProp<ViewStyle>
+  headerTitleStyle?: StyleProp<TextStyle>
+  sectionTitleStyle?: StyleProp<TextStyle>
+  infoLabelStyle?: StyleProp<TextStyle>
+  infoValueStyle?: StyleProp<TextStyle>
+  actionButtonStyle?: StyleProp<ViewStyle>
+  actionButtonTitleStyle?: StyleProp<TextStyle>
+  logTimestampStyle?: StyleProp<TextStyle>
+  logMessageStyle?: StyleProp<TextStyle>
+}
+
+// ─── Ref Methods ─────────────────────────────────────────────────────────────
+
+export interface BackstageRef {
+  /** Open the backstage panel */
+  open: () => void
+  /** Close the backstage panel */
+  close: () => void
+  /** Clear all captured logs */
+  clearLogs: () => void
+}

package/src/utils/formatTimestamp.ts

@@ -0,0 +1,22 @@
+/**
+ * Formats a timestamp (Date.now()) into a human-readable local time string.
+ * Format: "h:mm:ss.SSS AM/PM"
+ * No external dependencies — uses native Date API.
+ */
+export function formatTimestamp(timestamp: number): string {
+  const date = new Date(timestamp)
+  let hours = date.getHours()
+  const minutes = date.getMinutes()
+  const seconds = date.getSeconds()
+  const milliseconds = date.getMilliseconds()
+  const ampm = hours >= 12 ? 'PM' : 'AM'
+
+  hours = hours % 12
+  hours = hours || 12
+
+  const mm = minutes.toString().padStart(2, '0')
+  const ss = seconds.toString().padStart(2, '0')
+  const ms = milliseconds.toString().padStart(3, '0')
+
+  return `${hours}:${mm}:${ss}.${ms} ${ampm}`
+}

package/src/utils/stringify.ts

@@ -0,0 +1,90 @@
+/**
+ * Safely stringifies a value, handling circular references and Error objects.
+ */
+export function safeStringify(value: unknown, indent = 2): string {
+  if (value === undefined) return 'undefined'
+  if (value === null) return 'null'
+
+  if (value instanceof Error) {
+    return JSON.stringify(
+      {
+        name: value.name,
+        message: value.message,
+        stack: value.stack,
+      },
+      null,
+      indent,
+    )
+  }
+
+  const seen = new WeakSet()
+
+  try {
+    return JSON.stringify(
+      value,
+      (_key, val) => {
+        if (typeof val === 'object' && val !== null) {
+          if (seen.has(val)) {
+            return '[Circular]'
+          }
+          seen.add(val)
+        }
+        if (typeof val === 'bigint') {
+          return val.toString()
+        }
+        if (typeof val === 'function') {
+          return `[Function: ${val.name || 'anonymous'}]`
+        }
+        if (typeof val === 'symbol') {
+          return val.toString()
+        }
+        return val
+      },
+      indent,
+    )
+  } catch {
+    return String(value)
+  }
+}
+
+/**
+ * Formats a console message and its optional params into a single string.
+ */
+export function formatLogMessage(message: unknown, optionalParams?: unknown[]): string {
+  const parts: string[] = []
+
+  if (message instanceof Error) {
+    parts.push(`${message.name}: ${message.message}`)
+  } else if (typeof message === 'object' && message !== null) {
+    parts.push(safeStringify(message, 0))
+  } else if (typeof message === 'string') {
+    // Strip console color formatting (%c)
+    parts.push(message.replace(/%c/g, '').trim())
+  } else {
+    parts.push(String(message))
+  }
+
+  if (optionalParams && optionalParams.length > 0) {
+    for (const param of optionalParams) {
+      if (typeof param === 'string' && isColorString(param)) {
+        continue // skip css color strings from console.log('%c ...', 'color: ...')
+      }
+      if (typeof param === 'object' && param !== null) {
+        parts.push(safeStringify(param, 0))
+      } else {
+        parts.push(String(param))
+      }
+    }
+  }
+
+  return parts.join(' ')
+}
+
+function isColorString(str: string): boolean {
+  return (
+    str.includes('color:') ||
+    str.includes('background:') ||
+    str.includes('font-') ||
+    /^#[0-9A-Fa-f]{3,8}$/.test(str.trim())
+  )
+}