@maple-dev/browser 0.9.0 → 0.10.0

package/dist/react.d.mts

@@ -0,0 +1,88 @@
+import { Component, ErrorInfo, ReactNode } from "react";
+//#region src/react.d.ts
+export interface MapleErrorBoundaryFallbackProps {
+  readonly error: unknown;
+  /** Clear the error and render the children again. */
+  readonly reset: () => void;
+}
+export interface MapleErrorBoundaryProps {
+  readonly children?: ReactNode;
+  /** Rendered instead of the children after an error. Default: nothing. */
+  readonly fallback?: ReactNode | ((props: MapleErrorBoundaryFallbackProps) => ReactNode);
+  /** Called after the error is reported. */
+  readonly onError?: (error: unknown, info: ErrorInfo) => void;
+}
+interface MapleErrorBoundaryState {
+  readonly failed: boolean;
+  readonly error: unknown;
+}
+/** Reports render errors below it to Maple once, then renders `fallback`. */
+export declare class MapleErrorBoundary extends Component<MapleErrorBoundaryProps, MapleErrorBoundaryState> {
+  state: MapleErrorBoundaryState;
+  static getDerivedStateFromError(error: unknown): MapleErrorBoundaryState;
+  componentDidCatch(error: unknown, info: ErrorInfo): void;
+  private readonly reset;
+  render(): ReactNode;
+}
+/**
+ * For React 19's `createRoot(el, { onCaughtError, onUncaughtError, onRecoverableError })`:
+ * reports what React caught, with its component stack. Errors already reported
+ * (by a `MapleErrorBoundary`, say) are not reported twice.
+ */
+export declare function mapleReactErrorHandler(source?: string): (error: unknown, info: {
+  readonly componentStack?: string | null | undefined;
+}) => void;
+/** A React Router data router (`createBrowserRouter` and friends), as far as Maple reads it. */
+export interface ReactRouterLike {
+  readonly state: ReactRouterState;
+  subscribe(listener: (state: ReactRouterState) => void): () => void;
+}
+export interface ReactRouterState {
+  readonly initialized: boolean;
+  readonly location: {
+    readonly pathname: string;
+  };
+  readonly navigation: {
+    readonly state: string;
+    readonly location?: {
+      readonly pathname: string;
+    } | undefined;
+  };
+  readonly matches: ReadonlyArray<{
+    readonly route: {
+      readonly path?: string | undefined;
+    };
+  }>;
+}
+/**
+ * Span each navigation of a React Router data router, from the moment it starts
+ * loading until its loaders settle, named by route template. The first is the
+ * page load. Returns an unsubscribe.
+ */
+export declare function instrumentReactRouter(router: ReactRouterLike): () => void;
+/** A TanStack Router instance, as far as Maple reads it. */
+export interface TanStackRouterLike {
+  readonly state: {
+    readonly status: string;
+    readonly location: {
+      readonly pathname: string;
+    };
+    readonly matches: ReadonlyArray<{
+      readonly fullPath?: string | undefined;
+      readonly routeId: string;
+    }>;
+  };
+  subscribe(eventType: "onBeforeNavigate" | "onResolved", listener: (event: {
+    readonly toLocation: {
+      readonly pathname: string;
+    };
+    readonly pathChanged: boolean;
+  }) => void): () => void;
+}
+/**
+ * Span each TanStack Router navigation from `onBeforeNavigate` to `onResolved`,
+ * named by the leaf route's full path (`/projects/$projectId`). Search-only
+ * changes are not navigations. The first is the page load. Returns an unsubscribe.
+ */
+export declare function instrumentTanStackRouter(router: TanStackRouterLike): () => void;
+//#endregion

package/dist/react.mjs

@@ -0,0 +1,130 @@
+import { t as MapleBrowser } from "./src-Bzmp8rVr.mjs";
+import { Component } from "react";
+//#region src/react.ts
+/** Component stacks can run to hundreds of lines; the top of it names the failing tree. */
+const MAX_COMPONENT_STACK = 2e3;
+function reportReactError(error, componentStack, source) {
+	MapleBrowser.captureException(error, {
+		name: "react.render_error",
+		attributes: {
+			"maple.exception.source": source,
+			...componentStack ? { "maple.react.component_stack": componentStack.trim().slice(0, MAX_COMPONENT_STACK) } : void 0
+		}
+	});
+}
+/** Reports render errors below it to Maple once, then renders `fallback`. */
+var MapleErrorBoundary = class extends Component {
+	state = {
+		failed: false,
+		error: void 0
+	};
+	static getDerivedStateFromError(error) {
+		return {
+			failed: true,
+			error
+		};
+	}
+	componentDidCatch(error, info) {
+		reportReactError(error, info.componentStack, "react.error_boundary");
+		this.props.onError?.(error, info);
+	}
+	reset = () => {
+		this.setState({
+			failed: false,
+			error: void 0
+		});
+	};
+	render() {
+		if (!this.state.failed) return this.props.children ?? null;
+		const { fallback } = this.props;
+		return typeof fallback === "function" ? fallback({
+			error: this.state.error,
+			reset: this.reset
+		}) : fallback ?? null;
+	}
+};
+/**
+* For React 19's `createRoot(el, { onCaughtError, onUncaughtError, onRecoverableError })`:
+* reports what React caught, with its component stack. Errors already reported
+* (by a `MapleErrorBoundary`, say) are not reported twice.
+*/
+function mapleReactErrorHandler(source = "react.root") {
+	return (error, info) => reportReactError(error, info.componentStack, source);
+}
+/** `/projects/:id/settings`, from the matched routes' own path segments. */
+function reactRouterTemplate(state) {
+	let template = "";
+	for (const match of state.matches) {
+		const path = match.route.path;
+		if (!path) continue;
+		template = path.startsWith("/") ? path : `${template.replace(/\/$/, "")}/${path}`;
+	}
+	return template || "/";
+}
+/**
+* Span each navigation of a React Router data router, from the moment it starts
+* loading until its loaders settle, named by route template. The first is the
+* page load. Returns an unsubscribe.
+*/
+function instrumentReactRouter(router) {
+	let open = false;
+	let pathname = router.state.location.pathname;
+	const start = (path) => {
+		MapleBrowser.startNavigation(path);
+		open = true;
+	};
+	const end = (state) => {
+		if (!open) return;
+		MapleBrowser.endNavigation(reactRouterTemplate(state));
+		open = false;
+	};
+	start(pathname);
+	if (router.state.initialized && router.state.navigation.state === "idle") end(router.state);
+	return router.subscribe((state) => {
+		const target = state.navigation.location?.pathname;
+		if (state.navigation.state !== "idle" && target !== void 0) {
+			if (target !== pathname) start(target);
+			pathname = target;
+			return;
+		}
+		if (!state.initialized) return;
+		if (!open && state.location.pathname !== pathname) start(state.location.pathname);
+		pathname = state.location.pathname;
+		end(state);
+	});
+}
+/**
+* Span each TanStack Router navigation from `onBeforeNavigate` to `onResolved`,
+* named by the leaf route's full path (`/projects/$projectId`). Search-only
+* changes are not navigations. The first is the page load. Returns an unsubscribe.
+*/
+function instrumentTanStackRouter(router) {
+	/** The path of the navigation in flight, if any. */
+	let open;
+	const template = () => {
+		const leaf = router.state.matches.at(-1);
+		return leaf?.fullPath || leaf?.routeId || "/";
+	};
+	open = router.state.location.pathname;
+	MapleBrowser.startNavigation(open);
+	if (router.state.status === "idle" && router.state.matches.length > 0) {
+		MapleBrowser.endNavigation(template());
+		open = void 0;
+	}
+	const stopBefore = router.subscribe("onBeforeNavigate", (event) => {
+		if (!event.pathChanged || event.toLocation.pathname === open) return;
+		open = event.toLocation.pathname;
+		MapleBrowser.startNavigation(open);
+	});
+	const stopResolved = router.subscribe("onResolved", () => {
+		if (open === void 0) return;
+		MapleBrowser.endNavigation(template());
+		open = void 0;
+	});
+	return () => {
+		stopBefore();
+		stopResolved();
+	};
+}
+//#endregion
+export { MapleErrorBoundary, instrumentReactRouter, instrumentTanStackRouter, mapleReactErrorHandler };