@teardown/dev-client 2.0.44

package/src/types.ts

@@ -0,0 +1,235 @@
+/**
+ * @teardown/dev-client type definitions
+ */
+
+import type { ImageSourcePropType } from "react-native";
+
+/**
+ * Dev client configuration options
+ */
+export interface DevClientConfig {
+	/** Whether to enable shake gesture for dev menu (default: true) */
+	enableShakeGesture?: boolean;
+
+	/** Whether to enable 3-finger tap for dev menu (default: true) */
+	enableThreeFingerTap?: boolean;
+
+	/** Splash screen configuration */
+	splash?: SplashScreenConfig;
+
+	/** Custom dev menu actions */
+	customMenuItems?: DevMenuItem[];
+
+	/** Metro bundler URL override */
+	bundlerUrl?: string;
+
+	/** Enable verbose logging (default: __DEV__) */
+	verbose?: boolean;
+}
+
+/**
+ * Splash screen configuration
+ */
+export interface SplashScreenConfig {
+	/** Background color (hex string, default: #ffffff) */
+	backgroundColor?: string;
+
+	/** Logo image source */
+	logo?: ImageSourcePropType;
+
+	/** Resize mode for logo (default: contain) */
+	resizeMode?: "contain" | "cover" | "center";
+
+	/** Minimum display time in ms (default: 500) */
+	minDisplayTime?: number;
+
+	/** Fade out duration in ms (default: 300) */
+	fadeOutDuration?: number;
+
+	/** Auto-hide when app is ready (default: true) */
+	autoHide?: boolean;
+}
+
+/**
+ * Dev menu item configuration
+ */
+export interface DevMenuItem {
+	/** Unique identifier for the menu item */
+	id: string;
+
+	/** Display label */
+	label: string;
+
+	/** Optional icon name */
+	icon?: string;
+
+	/** Action handler */
+	onPress: () => void | Promise<void>;
+
+	/** Show only in development (default: true) */
+	devOnly?: boolean;
+}
+
+/**
+ * Bundler connection status
+ */
+export interface BundlerStatus {
+	/** Whether connected to Metro bundler */
+	connected: boolean;
+
+	/** Current bundler URL */
+	url: string | null;
+
+	/** Error message if connection failed */
+	error: string | null;
+
+	/** Last successful connection timestamp */
+	lastConnectedAt: Date | null;
+}
+
+/**
+ * Dev menu state
+ */
+export interface DevMenuState {
+	/** Whether dev menu is visible */
+	isVisible: boolean;
+
+	/** Whether an action is in progress */
+	isLoading: boolean;
+
+	/** Current bundler status */
+	bundlerStatus: BundlerStatus;
+
+	/** Whether hot reloading is enabled */
+	hotReloadEnabled: boolean;
+
+	/** Whether fast refresh is enabled */
+	fastRefreshEnabled: boolean;
+}
+
+/**
+ * Dev menu actions
+ */
+export interface DevMenuActions {
+	/** Show the dev menu */
+	show: () => void;
+
+	/** Hide the dev menu */
+	hide: () => void;
+
+	/** Toggle dev menu visibility */
+	toggle: () => void;
+
+	/** Reload the app */
+	reload: () => Promise<void>;
+
+	/** Open debugger */
+	openDebugger: () => Promise<void>;
+
+	/** Toggle element inspector */
+	toggleElementInspector: () => Promise<void>;
+
+	/** Toggle performance monitor */
+	togglePerfMonitor: () => Promise<void>;
+
+	/** Set hot reload enabled state */
+	setHotReloadEnabled: (enabled: boolean) => Promise<void>;
+}
+
+/**
+ * Native module interface for dev settings
+ */
+export interface DevSettingsNativeModule {
+	/** Reload the JavaScript bundle */
+	reload(): void;
+
+	/** Open the debugger */
+	openDebugger(): void;
+
+	/** Toggle element inspector overlay */
+	toggleElementInspector(): void;
+
+	/** Set hot loading enabled state */
+	setHotLoadingEnabled(enabled: boolean): void;
+
+	/** Set fast refresh enabled state */
+	setFastRefreshEnabled(enabled: boolean): void;
+
+	/** Get current dev settings */
+	getDevSettings(): Promise<DevSettings>;
+
+	/** Open native dev menu */
+	openDevMenu(): void;
+}
+
+/**
+ * Current dev settings state from native
+ */
+export interface DevSettings {
+	/** Whether remote JS debugging is enabled */
+	isDebuggingRemotely: boolean;
+
+	/** Whether element inspector is shown */
+	isElementInspectorShown: boolean;
+
+	/** Whether hot loading is enabled */
+	isHotLoadingEnabled: boolean;
+
+	/** Whether fast refresh is enabled */
+	isFastRefreshEnabled: boolean;
+
+	/** Whether performance monitor is shown */
+	isPerfMonitorShown: boolean;
+}
+
+/**
+ * Splash screen control API
+ */
+export interface SplashScreenApi {
+	/** Hide the splash screen */
+	hide: (options?: { fade?: boolean }) => Promise<void>;
+
+	/** Show the splash screen (for manual control) */
+	show: () => Promise<void>;
+
+	/** Whether splash screen is currently visible */
+	isVisible: boolean;
+}
+
+/**
+ * Dev client context value
+ */
+export interface DevClientContextValue {
+	/** Current configuration */
+	config: DevClientConfig;
+
+	/** Dev menu state and actions */
+	devMenu: {
+		state: DevMenuState;
+		actions: DevMenuActions;
+		defaultItems: DevMenuItem[];
+	};
+
+	/** Splash screen API */
+	splashScreen: SplashScreenApi;
+
+	/** Bundler status */
+	bundlerStatus: BundlerStatus;
+}
+
+/**
+ * Options for getting bundler URL
+ */
+export interface GetBundlerUrlOptions {
+	/** Target platform */
+	platform: "ios" | "android";
+
+	/** Whether running on emulator/simulator */
+	isEmulator: boolean;
+
+	/** Custom port (default: 8081) */
+	port?: number;
+
+	/** URL override */
+	override?: string;
+}

package/src/utils/bundler-url.ts

@@ -0,0 +1,103 @@
+/**
+ * Bundler URL utilities
+ *
+ * Provides helpers for determining and validating Metro bundler URLs
+ * based on platform and environment.
+ */
+
+import type { GetBundlerUrlOptions } from "../types";
+
+/** Default Metro bundler port */
+export const DEFAULT_BUNDLER_PORT = 8081;
+
+/** Android emulator host - special IP that routes to host machine */
+const ANDROID_EMULATOR_HOST = "10.0.2.2";
+
+/** Default host for iOS and physical devices */
+const DEFAULT_HOST = "localhost";
+
+/**
+ * Get the default bundler URL based on platform and environment
+ *
+ * @param platform - Target platform (ios or android)
+ * @param isEmulator - Whether running on emulator/simulator
+ * @param port - Custom port (defaults to 8081)
+ * @returns The bundler URL string
+ *
+ * @example
+ * ```ts
+ * getDefaultBundlerUrl('ios', true); // http://localhost:8081
+ * getDefaultBundlerUrl('android', true); // http://10.0.2.2:8081
+ * getDefaultBundlerUrl('android', true, 9000); // http://10.0.2.2:9000
+ * ```
+ */
+export function getDefaultBundlerUrl(
+	platform: "ios" | "android",
+	isEmulator: boolean,
+	port: number = DEFAULT_BUNDLER_PORT
+): string {
+	// Android emulator needs special host to reach the host machine
+	const host = platform === "android" && isEmulator ? ANDROID_EMULATOR_HOST : DEFAULT_HOST;
+
+	return `http://${host}:${port}`;
+}
+
+/**
+ * Validate a bundler URL
+ *
+ * @param url - URL string to validate
+ * @returns true if the URL is valid for bundler connection
+ *
+ * @example
+ * ```ts
+ * isValidBundlerUrl('http://localhost:8081'); // true
+ * isValidBundlerUrl('https://bundler.example.com'); // true
+ * isValidBundlerUrl('not-a-url'); // false
+ * ```
+ */
+export function isValidBundlerUrl(url: string): boolean {
+	if (!url || url.trim() === "") {
+		return false;
+	}
+
+	try {
+		const parsed = new URL(url);
+		// Only allow http and https protocols
+		return parsed.protocol === "http:" || parsed.protocol === "https:";
+	} catch {
+		return false;
+	}
+}
+
+/**
+ * Get the bundler URL based on options
+ *
+ * Respects override URL if provided and valid, otherwise
+ * returns the appropriate default URL for the platform.
+ *
+ * @param options - Configuration options
+ * @returns The bundler URL string
+ *
+ * @example
+ * ```ts
+ * getBundlerUrl({ platform: 'ios', isEmulator: true });
+ * // Returns: http://localhost:8081
+ *
+ * getBundlerUrl({ platform: 'android', isEmulator: true, port: 9000 });
+ * // Returns: http://10.0.2.2:9000
+ *
+ * getBundlerUrl({ platform: 'ios', isEmulator: true, override: 'http://custom:8080' });
+ * // Returns: http://custom:8080
+ * ```
+ */
+export function getBundlerUrl(options: GetBundlerUrlOptions): string {
+	const { platform, isEmulator, port = DEFAULT_BUNDLER_PORT, override } = options;
+
+	// Use override if provided and valid
+	if (override && isValidBundlerUrl(override)) {
+		return override;
+	}
+
+	// Return default URL for platform
+	return getDefaultBundlerUrl(platform, isEmulator, port);
+}

package/src/utils/index.ts

@@ -0,0 +1,19 @@
+/**
+ * Utility exports
+ */
+
+export {
+	DEFAULT_BUNDLER_PORT,
+	getBundlerUrl,
+	getDefaultBundlerUrl,
+	isValidBundlerUrl,
+} from "./bundler-url";
+
+export {
+	currentPlatform,
+	isAndroid,
+	isDev,
+	isEmulator,
+	isIOS,
+	platformSelect,
+} from "./platform";

package/src/utils/platform.ts

@@ -0,0 +1,64 @@
+/**
+ * Platform detection utilities
+ */
+
+import { Platform } from "react-native";
+
+/**
+ * Current platform
+ */
+export const currentPlatform = Platform.OS as "ios" | "android";
+
+/**
+ * Whether running on iOS
+ */
+export const isIOS = Platform.OS === "ios";
+
+/**
+ * Whether running on Android
+ */
+export const isAndroid = Platform.OS === "android";
+
+/**
+ * Whether running in development mode
+ * Safe when __DEV__ is not defined (e.g. in test runners).
+ */
+export const isDev =
+	typeof globalThis !== "undefined" && "__DEV__" in globalThis
+		? (globalThis as typeof globalThis & { __DEV__: boolean }).__DEV__
+		: false;
+
+/**
+ * Detect if running on an emulator/simulator
+ *
+ * Note: This is a heuristic and may not be 100% accurate.
+ * For iOS, simulators have specific device names.
+ * For Android, emulators typically have specific fingerprints.
+ *
+ * @returns Promise resolving to true if likely on emulator
+ */
+export async function isEmulator(): Promise<boolean> {
+	// In development, we generally assume emulator for simplicity
+	// A more robust implementation would check device info
+	if (__DEV__) {
+		return true;
+	}
+
+	// In production, assume physical device
+	return false;
+}
+
+/**
+ * Get platform-specific value
+ *
+ * @param options - Object with ios and android values
+ * @returns The value for the current platform
+ *
+ * @example
+ * ```ts
+ * const color = platformSelect({ ios: 'blue', android: 'green' });
+ * ```
+ */
+export function platformSelect<T>(options: { ios: T; android: T }): T {
+	return Platform.select(options) as T;
+}