react-native-network-lens 0.0.0-stage → 0.1.0

package/src/components/JsonTree/model.ts

@@ -0,0 +1,264 @@
+/**
+ * Pure helpers that turn a JSON value into a flat list of visible rows, the way
+ * a browser devtools console renders objects. Keeping this free of React makes it
+ * easy to test and lets the UI virtualise the rows with a FlatList.
+ */
+
+export type JsonValueType =
+  'object' | 'array' | 'string' | 'number' | 'boolean' | 'null' | 'undefined';
+
+export interface JsonRow {
+  /** Stable identifier: JSON-pointer-like path, e.g. `$.data.items[2].id` */
+  path: string;
+  key: string | null;
+  depth: number;
+  type: JsonValueType;
+  value: unknown;
+  expandable: boolean;
+  expanded: boolean;
+  childCount: number;
+}
+
+export const typeOf = (value: unknown): JsonValueType => {
+  if (value === null) return 'null';
+  if (Array.isArray(value)) return 'array';
+  const t = typeof value;
+  if (t === 'object') return 'object';
+  if (t === 'string') return 'string';
+  if (t === 'number' || t === 'bigint') return 'number';
+  if (t === 'boolean') return 'boolean';
+  return 'undefined';
+};
+
+export const isExpandable = (value: unknown): boolean => {
+  const type = typeOf(value);
+  if (type === 'array') return (value as unknown[]).length > 0;
+  if (type === 'object') return Object.keys(value as object).length > 0;
+  return false;
+};
+
+export const childEntries = (value: unknown): [string, unknown][] => {
+  if (Array.isArray(value))
+    return value.map((item, index) => [String(index), item]);
+  if (value && typeof value === 'object')
+    return Object.entries(value as object);
+  return [];
+};
+
+export const childPath = (
+  parent: string,
+  key: string,
+  parentIsArray: boolean
+) => (parentIsArray ? `${parent}[${key}]` : `${parent}.${key}`);
+
+export const ROOT_PATH = '$';
+
+/**
+ * Walks the value and returns the rows that are currently visible given the set
+ * of expanded paths.
+ */
+export const flattenJson = (
+  value: unknown,
+  expanded: ReadonlySet<string>
+): JsonRow[] => {
+  const rows: JsonRow[] = [];
+  const visit = (
+    node: unknown,
+    key: string | null,
+    path: string,
+    depth: number
+  ) => {
+    const type = typeOf(node);
+    const expandable = isExpandable(node);
+    const isExpanded = expandable && expanded.has(path);
+    const children = expandable ? childEntries(node) : [];
+    rows.push({
+      path,
+      key,
+      depth,
+      type,
+      value: node,
+      expandable,
+      expanded: isExpanded,
+      childCount: children.length,
+    });
+    if (isExpanded) {
+      const isArray = type === 'array';
+      for (const [childKey, childValue] of children) {
+        visit(
+          childValue,
+          childKey,
+          childPath(path, childKey, isArray),
+          depth + 1
+        );
+      }
+    }
+  };
+  visit(value, null, ROOT_PATH, 0);
+  return rows;
+};
+
+/** Paths of every expandable node up to (and including) `maxDepth`. */
+export const pathsToDepth = (value: unknown, maxDepth: number): Set<string> => {
+  const result = new Set<string>();
+  const visit = (node: unknown, path: string, depth: number) => {
+    if (!isExpandable(node)) return;
+    if (depth > maxDepth) return;
+    result.add(path);
+    const isArray = Array.isArray(node);
+    for (const [key, child] of childEntries(node)) {
+      visit(child, childPath(path, key, isArray), depth + 1);
+    }
+  };
+  visit(value, ROOT_PATH, 0);
+  return result;
+};
+
+export const allPaths = (value: unknown): Set<string> =>
+  pathsToDepth(value, Number.POSITIVE_INFINITY);
+
+/** Paths of every expandable node in the whole tree below `path` (inclusive). */
+export const subtreePaths = (value: unknown, path: string): Set<string> => {
+  const result = new Set<string>();
+  const visit = (node: unknown, nodePath: string) => {
+    if (!isExpandable(node)) return;
+    result.add(nodePath);
+    const isArray = Array.isArray(node);
+    for (const [key, child] of childEntries(node))
+      visit(child, childPath(nodePath, key, isArray));
+  };
+  visit(value, path);
+  return result;
+};
+
+/** Looks a node up by path, walking from the root. */
+export const getAtPath = (root: unknown, path: string): unknown => {
+  if (path === ROOT_PATH) return root;
+  const segments = path
+    .slice(ROOT_PATH.length)
+    .split(/\.|\[|\]/)
+    .filter(Boolean);
+  let current: unknown = root;
+  for (const segment of segments) {
+    if (current === null || typeof current !== 'object') return undefined;
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+};
+
+export interface SearchHit {
+  path: string;
+  /** Ancestor paths that must be expanded for the hit to be visible. */
+  ancestors: string[];
+}
+
+const primitiveText = (value: unknown): string => {
+  if (typeof value === 'string') return value;
+  if (value === null) return 'null';
+  if (value === undefined) return 'undefined';
+  return String(value);
+};
+
+/**
+ * Finds every node whose key or primitive value contains `query` (case-insensitive).
+ * Returns hits in document order along with the ancestors to expand.
+ */
+export const searchJson = (value: unknown, query: string): SearchHit[] => {
+  const needle = query.trim().toLowerCase();
+  if (!needle) return [];
+  const hits: SearchHit[] = [];
+  const visit = (
+    node: unknown,
+    key: string | null,
+    path: string,
+    ancestors: string[]
+  ) => {
+    const keyMatches = key !== null && key.toLowerCase().includes(needle);
+    const expandable = isExpandable(node);
+    const valueMatches =
+      !expandable && primitiveText(node).toLowerCase().includes(needle);
+    if (keyMatches || valueMatches) hits.push({ path, ancestors });
+    if (expandable) {
+      const isArray = Array.isArray(node);
+      const nextAncestors = [...ancestors, path];
+      for (const [childKey, child] of childEntries(node)) {
+        visit(
+          child,
+          childKey,
+          childPath(path, childKey, isArray),
+          nextAncestors
+        );
+      }
+    }
+  };
+  visit(value, null, ROOT_PATH, []);
+  return hits;
+};
+
+const MAX_PREVIEW_ITEMS = 5;
+const MAX_STRING_PREVIEW = 60;
+
+export const previewString = (
+  value: string,
+  max = MAX_STRING_PREVIEW
+): string => (value.length > max ? `${value.slice(0, max)}…` : value);
+
+/** Short inline summary used for collapsed objects/arrays, like `{id, name, …}`. */
+export const collapsedPreview = (value: unknown): string => {
+  if (Array.isArray(value)) {
+    if (value.length === 0) return '[]';
+    const items = value
+      .slice(0, MAX_PREVIEW_ITEMS)
+      .map((item) => inlineValue(item));
+    const more = value.length > MAX_PREVIEW_ITEMS ? ', …' : '';
+    return `(${value.length}) [${items.join(', ')}${more}]`;
+  }
+  if (value && typeof value === 'object') {
+    const keys = Object.keys(value as object);
+    if (keys.length === 0) return '{}';
+    const shown = keys.slice(0, MAX_PREVIEW_ITEMS).join(', ');
+    const more = keys.length > MAX_PREVIEW_ITEMS ? ', …' : '';
+    return `{${shown}${more}}`;
+  }
+  return inlineValue(value);
+};
+
+export const inlineValue = (value: unknown): string => {
+  switch (typeOf(value)) {
+    case 'array':
+      return `Array(${(value as unknown[]).length})`;
+    case 'object':
+      return '{…}';
+    case 'string':
+      return `"${previewString(value as string, 24)}"`;
+    case 'null':
+      return 'null';
+    case 'undefined':
+      return 'undefined';
+    default:
+      return String(value);
+  }
+};
+
+/** Rough character count of a row, used to size the horizontal scroll area. */
+export const rowCharCount = (row: JsonRow, indentChars: number): number => {
+  const keyPart = row.key === null ? 0 : row.key.length + 2;
+  let valuePart: number;
+  if (row.expandable) {
+    valuePart = row.expanded
+      ? row.type === 'array'
+        ? `Array(${row.childCount})`.length
+        : `Object (${row.childCount})`.length
+      : collapsedPreview(row.value).length;
+  } else {
+    valuePart = Math.min(displayValue(row.value).length, MAX_VALUE_CHARS);
+  }
+  return row.depth * indentChars + 2 + keyPart + valuePart;
+};
+
+export const MAX_VALUE_CHARS = 400;
+
+export const displayValue = (value: unknown): string => {
+  if (typeof value === 'string') return `"${value}"`;
+  return primitiveText(value);
+};

package/src/components/NetworkLens.tsx

@@ -0,0 +1,176 @@
+import {
+  forwardRef,
+  useCallback,
+  useEffect,
+  useImperativeHandle,
+  useMemo,
+  useState,
+  type ReactNode,
+} from 'react';
+import { BackHandler, Share, StyleSheet, View } from 'react-native';
+import { setLensBackHandler } from '../backHandler';
+import { createHar } from '../core/har';
+import logger from '../core/loggerSingleton';
+import {
+  useLoggerEnabled,
+  useLoggerPaused,
+  useNetworkRequests,
+} from '../hooks';
+import { ThemeContext, useTheme, type ThemeInput } from '../theme';
+import RequestDetails from './RequestDetails/RequestDetails';
+import RequestList from './RequestList/RequestList';
+import type { ActionItem } from './ui';
+
+export interface NetworkLensProps {
+  /**
+   * Render nothing when `false`, e.g. `enabled={__DEV__ || featureFlag}`.
+   * @default true
+   */
+  enabled?: boolean;
+  /** `'light' | 'dark' | 'auto'` or a partial theme object. @default 'auto' */
+  theme?: ThemeInput;
+  /** Newest first (`desc`) or oldest first (`asc`). @default 'desc' */
+  sort?: 'asc' | 'desc';
+  /** Single-line rows. @default false */
+  compact?: boolean;
+  /** Limit the number of rows rendered. */
+  maxRows?: number;
+  /**
+   * Hook up your clipboard library to get "Copy" buttons, e.g.
+   * `copyToClipboard={Clipboard.setString}`.
+   */
+  copyToClipboard?: (text: string) => void;
+  /** Rendered above the request list's search bar (the overlay uses it for its title bar). */
+  header?: ReactNode;
+}
+
+export interface NetworkLensHandle {
+  /** Returns to the list if a request is open. Returns `true` when it handled the action. */
+  goBack: () => boolean;
+}
+
+const NetworkLens = forwardRef<NetworkLensHandle, NetworkLensProps>(
+  function NetworkLensRoot(
+    {
+      enabled = true,
+      theme = 'auto',
+      sort = 'desc',
+      compact = false,
+      maxRows,
+      copyToClipboard,
+      header,
+    },
+    ref
+  ) {
+    if (!enabled) return null;
+    return (
+      <ThemeContext.Provider value={theme}>
+        <Inspector
+          ref={ref}
+          sort={sort}
+          compact={compact}
+          maxRows={maxRows}
+          copyToClipboard={copyToClipboard}
+          header={header}
+        />
+      </ThemeContext.Provider>
+    );
+  }
+);
+
+type InspectorProps = Required<Pick<NetworkLensProps, 'sort' | 'compact'>> &
+  Pick<NetworkLensProps, 'maxRows' | 'copyToClipboard' | 'header'>;
+
+const Inspector = forwardRef<NetworkLensHandle, InspectorProps>(
+  function InspectorInner(
+    { sort, compact, maxRows, copyToClipboard, header },
+    ref
+  ) {
+    const theme = useTheme();
+    const requests = useNetworkRequests();
+    const loggingEnabled = useLoggerEnabled();
+    const paused = useLoggerPaused();
+    const [selectedId, setSelectedId] = useState<string | null>(null);
+
+    const selected = useMemo(
+      () =>
+        selectedId === null
+          ? undefined
+          : (requests.find((r) => r.id === selectedId) ??
+            logger.getRequest(selectedId)),
+      [requests, selectedId]
+    );
+
+    const goBack = useCallback(() => {
+      if (selectedId === null) return false;
+      setSelectedId(null);
+      return true;
+    }, [selectedId]);
+
+    useImperativeHandle(ref, () => ({ goBack }), [goBack]);
+
+    // Android hardware back and the optional `getBackHandler()` integration.
+    useEffect(() => {
+      if (selectedId === null) return undefined;
+      setLensBackHandler(goBack);
+      const subscription = BackHandler.addEventListener(
+        'hardwareBackPress',
+        goBack
+      );
+      return () => {
+        subscription.remove();
+        setLensBackHandler(undefined);
+      };
+    }, [selectedId, goBack]);
+
+    const menuActions = useMemo<ActionItem[]>(
+      () => [
+        {
+          label: paused ? 'Resume capturing' : 'Pause capturing',
+          onPress: () => logger.setPaused(!paused),
+        },
+        {
+          label: 'Export all as HAR',
+          onPress: async () => {
+            const har = await createHar(logger.getRequests());
+            Share.share({ message: JSON.stringify(har) }).catch(
+              () => undefined
+            );
+          },
+        },
+        { label: 'Clear requests', onPress: logger.clear, destructive: true },
+      ],
+      [paused]
+    );
+
+    return (
+      <View
+        style={[styles.container, { backgroundColor: theme.colors.background }]}
+      >
+        {selected ? (
+          <RequestDetails
+            request={selected}
+            onClose={goBack}
+            copyToClipboard={copyToClipboard}
+          />
+        ) : (
+          <RequestList
+            requests={requests}
+            sort={sort}
+            compact={compact}
+            maxRows={maxRows}
+            paused={paused}
+            loggingEnabled={loggingEnabled}
+            onPressItem={setSelectedId}
+            menuActions={menuActions}
+            header={header}
+          />
+        )}
+      </View>
+    );
+  }
+);
+
+const styles = StyleSheet.create({ container: { flex: 1 } });
+
+export default NetworkLens;

package/src/components/NetworkLensOverlay.tsx

@@ -0,0 +1,187 @@
+import { useRef, useState } from 'react';
+import {
+  Modal,
+  Platform,
+  Pressable,
+  StatusBar,
+  StyleSheet,
+  Text,
+  View,
+  type ViewStyle,
+} from 'react-native';
+import { useLoggerEnabled, useNetworkRequests } from '../hooks';
+import { ThemeContext, useTheme, type ThemeInput } from '../theme';
+import NetworkLens, {
+  type NetworkLensHandle,
+  type NetworkLensProps,
+} from './NetworkLens';
+import { IconButton } from './ui';
+
+export interface NetworkLensOverlayProps extends Omit<
+  NetworkLensProps,
+  'enabled' | 'theme' | 'header'
+> {
+  /**
+   * Render nothing when `false`, e.g.
+   * `<NetworkLensOverlay enabled={__DEV__ || flags.networkInspector} />`
+   * @default true
+   */
+  enabled?: boolean;
+  theme?: ThemeInput;
+  /** Corner for the floating button. @default 'bottom-right' */
+  position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+  /** Distance from the screen edges in px. @default { x: 16, y: 32 } */
+  offset?: { x?: number; y?: number };
+  /** Controlled visibility of the inspector sheet. */
+  visible?: boolean;
+  onVisibleChange?: (visible: boolean) => void;
+  /** Hide the floating button when you open the sheet from your own dev menu. */
+  hideButton?: boolean;
+  /** Title of the inspector sheet. @default 'Network' */
+  title?: string;
+}
+
+/**
+ * Drop-in overlay: a floating badge with the number of captured requests that
+ * opens the inspector in a modal. Place it once near the root of your app.
+ */
+const NetworkLensOverlay = ({
+  enabled = true,
+  theme = 'auto',
+  ...props
+}: NetworkLensOverlayProps) => {
+  if (!enabled) return null;
+  return (
+    <ThemeContext.Provider value={theme}>
+      <Overlay {...props} theme={theme} />
+    </ThemeContext.Provider>
+  );
+};
+
+const Overlay = ({
+  theme,
+  position = 'bottom-right',
+  offset,
+  visible,
+  onVisibleChange,
+  hideButton,
+  title = 'Network',
+  ...lensProps
+}: Omit<NetworkLensOverlayProps, 'enabled'> & { theme: ThemeInput }) => {
+  const t = useTheme();
+  const lensRef = useRef<NetworkLensHandle>(null);
+  const [internalVisible, setInternalVisible] = useState(false);
+  const open = visible ?? internalVisible;
+  const setOpen = (next: boolean) => {
+    if (visible === undefined) setInternalVisible(next);
+    onVisibleChange?.(next);
+  };
+
+  const requests = useNetworkRequests();
+  const loggingEnabled = useLoggerEnabled();
+  const hasErrors = requests.some(
+    (r) => r.state === 'failed' || r.status >= 400
+  );
+
+  const placement: ViewStyle = {
+    [position.startsWith('bottom') ? 'bottom' : 'top']: offset?.y ?? 32,
+    [position.endsWith('right') ? 'right' : 'left']: offset?.x ?? 16,
+  };
+
+  const header = (
+    <View style={styles.header}>
+      <Text style={[styles.title, { color: t.colors.text }]}>{title}</Text>
+      <IconButton
+        glyph="✕"
+        accessibilityLabel="Close network inspector"
+        onPress={() => setOpen(false)}
+      />
+    </View>
+  );
+
+  return (
+    <>
+      {!hideButton && (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={`Open network inspector, ${requests.length} requests`}
+          onPress={() => setOpen(true)}
+          style={({ pressed }) => [
+            styles.fab,
+            placement,
+            {
+              backgroundColor: hasErrors
+                ? t.colors.statusBad
+                : t.colors.primary,
+            },
+            pressed && styles.fabPressed,
+          ]}
+        >
+          <Text style={[styles.fabCount, { color: t.colors.onPrimary }]}>
+            {loggingEnabled ? requests.length : '•'}
+          </Text>
+          <Text style={[styles.fabCaption, { color: t.colors.onPrimary }]}>
+            NET
+          </Text>
+        </Pressable>
+      )}
+      <Modal
+        visible={open}
+        animationType="slide"
+        presentationStyle={Platform.OS === 'ios' ? 'pageSheet' : 'fullScreen'}
+        onRequestClose={() => {
+          // Android back button: step back inside the inspector first, then close.
+          if (!lensRef.current?.goBack()) setOpen(false);
+        }}
+      >
+        <View style={[styles.sheet, { backgroundColor: t.colors.surface }]}>
+          <NetworkLens
+            ref={lensRef}
+            {...lensProps}
+            theme={theme}
+            header={header}
+          />
+        </View>
+      </Modal>
+    </>
+  );
+};
+
+const styles = StyleSheet.create({
+  fab: {
+    position: 'absolute',
+    width: 56,
+    height: 56,
+    borderRadius: 28,
+    alignItems: 'center',
+    justifyContent: 'center',
+    elevation: 6,
+    shadowColor: '#000',
+    shadowOpacity: 0.25,
+    shadowRadius: 6,
+    shadowOffset: { width: 0, height: 3 },
+    zIndex: 9999,
+  },
+  fabPressed: { opacity: 0.8 },
+  fabCount: { fontSize: 15, fontWeight: '800', fontVariant: ['tabular-nums'] },
+  fabCaption: {
+    fontSize: 9,
+    fontWeight: '700',
+    letterSpacing: 1,
+    marginTop: -2,
+  },
+  sheet: {
+    flex: 1,
+    paddingTop: Platform.OS === 'android' ? (StatusBar.currentHeight ?? 0) : 0,
+  },
+  header: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    justifyContent: 'space-between',
+    paddingLeft: 8,
+    paddingBottom: 6,
+  },
+  title: { fontSize: 17, fontWeight: '700' },
+});
+
+export default NetworkLensOverlay;