@goliapkg/sentori-react 0.3.0 → 0.4.0

package/lib/SentoriTrace.d.ts

@@ -0,0 +1,39 @@
+import { type ReactNode } from 'react';
+/**
+ * Wrap a subtree so its mount-to-unmount lifespan becomes a
+ * `react.render` span. Useful for measuring how long a heavy
+ * component sat on screen — a data table, a chart, a Suspense'd
+ * data fetch:
+ *
+ *     <TraceRender op="react.render" name="OrdersTable">
+ *       <OrdersTable />
+ *     </TraceRender>
+ *
+ * Implementation notes:
+ *
+ * - The span opens when the component renders for the first time
+ *   (in the body of the function, before children render — so child
+ *   spans pick this one up as their parent via `activeSpan()` if
+ *   they're synchronous; React renders top-down but yields between
+ *   commits, so async children won't necessarily attribute to this
+ *   span unless they wrap with `withSpan`).
+ * - The span closes in a `useEffect` cleanup. That runs at unmount
+ *   in normal mode, or twice in StrictMode (mount-unmount-mount).
+ *   StrictMode double-invocation just emits the span twice; this is
+ *   a known dev-mode artifact and matches how React's profiler
+ *   accounts for it.
+ * - Re-renders due to prop / state change do NOT restart the span.
+ *   The mount/unmount boundary is the lifespan. Callers wanting
+ *   per-render timing should use `useRenderTrace` instead (TODO).
+ */
+export declare function TraceRender({ children, data, name, op, tags, }: {
+    children: ReactNode;
+    /** Span data, attached at finish time. */
+    data?: Record<string, unknown>;
+    /** Defaults to `op`. */
+    name?: string;
+    /** Defaults to `react.render`. */
+    op?: string;
+    tags?: Record<string, string>;
+}): ReactNode;
+//# sourceMappingURL=SentoriTrace.d.ts.map

package/lib/SentoriTrace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentoriTrace.d.ts","sourceRoot":"","sources":["../src/SentoriTrace.tsx"],"names":[],"mappings":"AAAA,OAAO,EAA8B,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAIlE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,wBAAgB,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,EAAmB,EACnB,IAAI,GACL,EAAE;IACD,QAAQ,EAAE,SAAS,CAAA;IACnB,0CAA0C;IAC1C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,wBAAwB;IACxB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kCAAkC;IAClC,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAC9B,GAAG,SAAS,CA6BZ"}

package/lib/SentoriTrace.js

@@ -0,0 +1,55 @@
+import { useEffect, useMemo, useRef } from 'react';
+import { startSpan } from '@goliapkg/sentori-core';
+/**
+ * Wrap a subtree so its mount-to-unmount lifespan becomes a
+ * `react.render` span. Useful for measuring how long a heavy
+ * component sat on screen — a data table, a chart, a Suspense'd
+ * data fetch:
+ *
+ *     <TraceRender op="react.render" name="OrdersTable">
+ *       <OrdersTable />
+ *     </TraceRender>
+ *
+ * Implementation notes:
+ *
+ * - The span opens when the component renders for the first time
+ *   (in the body of the function, before children render — so child
+ *   spans pick this one up as their parent via `activeSpan()` if
+ *   they're synchronous; React renders top-down but yields between
+ *   commits, so async children won't necessarily attribute to this
+ *   span unless they wrap with `withSpan`).
+ * - The span closes in a `useEffect` cleanup. That runs at unmount
+ *   in normal mode, or twice in StrictMode (mount-unmount-mount).
+ *   StrictMode double-invocation just emits the span twice; this is
+ *   a known dev-mode artifact and matches how React's profiler
+ *   accounts for it.
+ * - Re-renders due to prop / state change do NOT restart the span.
+ *   The mount/unmount boundary is the lifespan. Callers wanting
+ *   per-render timing should use `useRenderTrace` instead (TODO).
+ */
+export function TraceRender({ children, data, name, op = 'react.render', tags, }) {
+    // Lazy-init via useMemo so the span is created exactly once across
+    // re-renders. Returning the handle from useMemo also means the
+    // effect cleanup captures the same reference.
+    const span = useMemo(() => startSpan(op, { data, name: name ?? op, tags }), 
+    // We deliberately do NOT include op/name/data/tags in deps —
+    // changing them after first render shouldn't reopen the span;
+    // the lifespan is "this component instance", not "these props".
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    []);
+    // The handle is alive across renders but should not be exposed to
+    // child components (they make their own spans). We hold it via ref
+    // so React's strict-mode-friendly invariants are preserved.
+    const spanRef = useRef(span);
+    spanRef.current = span;
+    useEffect(() => {
+        return () => {
+            // Finish on unmount. Second call is a no-op (SpanHandle's
+            // own contract), so StrictMode double-effects don't double-push.
+            spanRef.current?.finish({ status: 'ok' });
+            spanRef.current = null;
+        };
+    }, []);
+    return children;
+}
+//# sourceMappingURL=SentoriTrace.js.map

package/lib/SentoriTrace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SentoriTrace.js","sourceRoot":"","sources":["../src/SentoriTrace.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAkB,MAAM,OAAO,CAAA;AAElE,OAAO,EAAE,SAAS,EAAmB,MAAM,wBAAwB,CAAA;AAEnE;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,MAAM,UAAU,WAAW,CAAC,EAC1B,QAAQ,EACR,IAAI,EACJ,IAAI,EACJ,EAAE,GAAG,cAAc,EACnB,IAAI,GAUL;IACC,mEAAmE;IACnE,+DAA+D;IAC/D,8CAA8C;IAC9C,MAAM,IAAI,GAAG,OAAO,CAClB,GAAG,EAAE,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE,EAAE,IAAI,EAAE,CAAC;IACrD,6DAA6D;IAC7D,8DAA8D;IAC9D,gEAAgE;IAChE,uDAAuD;IACvD,EAAE,CACH,CAAA;IAED,kEAAkE;IAClE,mEAAmE;IACnE,4DAA4D;IAC5D,MAAM,OAAO,GAAG,MAAM,CAAoB,IAAI,CAAC,CAAA;IAC/C,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;IAEtB,SAAS,CAAC,GAAG,EAAE;QACb,OAAO,GAAG,EAAE;YACV,0DAA0D;YAC1D,iEAAiE;YACjE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;YACzC,OAAO,CAAC,OAAO,GAAG,IAAI,CAAA;QACxB,CAAC,CAAA;IACH,CAAC,EAAE,EAAE,CAAC,CAAA;IAEN,OAAO,QAAQ,CAAA;AACjB,CAAC"}

package/lib/index.d.ts

@@ -1,5 +1,7 @@
 export { SentoriProvider } from './SentoriProvider.js';
 export { SentoriErrorBoundary } from './SentoriErrorBoundary.js';
+export { SentoriSuspense } from './SentoriSuspense.js';
+export { TraceRender } from './SentoriTrace.js';
 export { useSentori, useCaptureError } from './hooks.js';
 export type { Breadcrumb, BreadcrumbType, CaptureExtras, SentoriContextValue, SentoriReactConfig, Tags, User, } from './types.js';
 //# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAExD,YAAY,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,IAAI,EACJ,IAAI,GACL,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAExD,YAAY,EACV,UAAU,EACV,cAAc,EACd,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,IAAI,EACJ,IAAI,GACL,MAAM,YAAY,CAAA"}

package/lib/index.js

@@ -1,4 +1,6 @@
 export { SentoriProvider } from './SentoriProvider.js';
 export { SentoriErrorBoundary } from './SentoriErrorBoundary.js';
+export { SentoriSuspense } from './SentoriSuspense.js';
+export { TraceRender } from './SentoriTrace.js';
 export { useSentori, useCaptureError } from './hooks.js';
 //# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAC/C,OAAO,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@goliapkg/sentori-react",
-  "version": "0.3.0",
-  "description": "React adapter for Sentori — Provider, ErrorBoundary (resetKeys + render-prop), Suspense, react-router breadcrumbs, and hooks built on @goliapkg/sentori-javascript.",
+  "version": "0.4.0",
+  "description": "React adapter for Sentori — Provider, ErrorBoundary (resetKeys + render-prop), Suspense, TraceRender, react-router breadcrumbs + auto-tracing.",
   "license": "MIT",
   "homepage": "https://sentori.golia.jp",
   "repository": {
@@ -29,6 +29,10 @@
     "./router": {
       "types": "./lib/router.d.ts",
       "default": "./lib/router.js"
+    },
+    "./trace": {
+      "types": "./lib/SentoriTrace.d.ts",
+      "default": "./lib/SentoriTrace.js"
     }
   },
   "files": [
@@ -52,8 +56,8 @@
     }
   },
   "dependencies": {
-    "@goliapkg/sentori-core": "0.1.0",
-    "@goliapkg/sentori-javascript": "0.2.0"
+    "@goliapkg/sentori-core": "0.3.0",
+    "@goliapkg/sentori-javascript": "0.3.0"
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^17",

package/src/SentoriTrace.tsx

@@ -0,0 +1,76 @@
+import { useEffect, useMemo, useRef, type ReactNode } from 'react'
+
+import { startSpan, type SpanHandle } from '@goliapkg/sentori-core'
+
+/**
+ * Wrap a subtree so its mount-to-unmount lifespan becomes a
+ * `react.render` span. Useful for measuring how long a heavy
+ * component sat on screen — a data table, a chart, a Suspense'd
+ * data fetch:
+ *
+ *     <TraceRender op="react.render" name="OrdersTable">
+ *       <OrdersTable />
+ *     </TraceRender>
+ *
+ * Implementation notes:
+ *
+ * - The span opens when the component renders for the first time
+ *   (in the body of the function, before children render — so child
+ *   spans pick this one up as their parent via `activeSpan()` if
+ *   they're synchronous; React renders top-down but yields between
+ *   commits, so async children won't necessarily attribute to this
+ *   span unless they wrap with `withSpan`).
+ * - The span closes in a `useEffect` cleanup. That runs at unmount
+ *   in normal mode, or twice in StrictMode (mount-unmount-mount).
+ *   StrictMode double-invocation just emits the span twice; this is
+ *   a known dev-mode artifact and matches how React's profiler
+ *   accounts for it.
+ * - Re-renders due to prop / state change do NOT restart the span.
+ *   The mount/unmount boundary is the lifespan. Callers wanting
+ *   per-render timing should use `useRenderTrace` instead (TODO).
+ */
+export function TraceRender({
+  children,
+  data,
+  name,
+  op = 'react.render',
+  tags,
+}: {
+  children: ReactNode
+  /** Span data, attached at finish time. */
+  data?: Record<string, unknown>
+  /** Defaults to `op`. */
+  name?: string
+  /** Defaults to `react.render`. */
+  op?: string
+  tags?: Record<string, string>
+}): ReactNode {
+  // Lazy-init via useMemo so the span is created exactly once across
+  // re-renders. Returning the handle from useMemo also means the
+  // effect cleanup captures the same reference.
+  const span = useMemo(
+    () => startSpan(op, { data, name: name ?? op, tags }),
+    // We deliberately do NOT include op/name/data/tags in deps —
+    // changing them after first render shouldn't reopen the span;
+    // the lifespan is "this component instance", not "these props".
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [],
+  )
+
+  // The handle is alive across renders but should not be exposed to
+  // child components (they make their own spans). We hold it via ref
+  // so React's strict-mode-friendly invariants are preserved.
+  const spanRef = useRef<null | SpanHandle>(span)
+  spanRef.current = span
+
+  useEffect(() => {
+    return () => {
+      // Finish on unmount. Second call is a no-op (SpanHandle's
+      // own contract), so StrictMode double-effects don't double-push.
+      spanRef.current?.finish({ status: 'ok' })
+      spanRef.current = null
+    }
+  }, [])
+
+  return children
+}

package/src/__tests__/SentoriTrace.test.tsx

@@ -0,0 +1,103 @@
+import { clearSpans, drainSpans } from '@goliapkg/sentori-core'
+import { cleanup, render } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, test } from 'bun:test'
+
+import { TraceRender } from '../SentoriTrace.js'
+
+beforeEach(() => clearSpans())
+afterEach(() => {
+  cleanup()
+  clearSpans()
+})
+
+describe('TraceRender', () => {
+  test('renders children', () => {
+    const { getByText } = render(
+      <TraceRender name="page">
+        <span>hello</span>
+      </TraceRender>,
+    )
+    expect(getByText('hello')).toBeDefined()
+  })
+
+  test('opens a react.render span on mount, finishes on unmount', () => {
+    const { unmount } = render(
+      <TraceRender name="OrdersTable">
+        <div>orders</div>
+      </TraceRender>,
+    )
+
+    // Span is open but not yet pushed to buffer.
+    expect(drainSpans()).toHaveLength(0)
+
+    unmount()
+
+    const spans = drainSpans()
+    expect(spans).toHaveLength(1)
+    expect(spans[0]?.op).toBe('react.render')
+    expect(spans[0]?.name).toBe('OrdersTable')
+    expect(spans[0]?.status).toBe('ok')
+    expect(spans[0]?.durationMs).toBeGreaterThanOrEqual(0)
+  })
+
+  test('custom op + tags + data flow through to finished span', () => {
+    const { unmount } = render(
+      <TraceRender
+        data={{ rowCount: 42 }}
+        name="dashboard mount"
+        op="react.mount"
+        tags={{ route: 'dashboard' }}
+      >
+        <div />
+      </TraceRender>,
+    )
+    unmount()
+
+    const sp = drainSpans()[0]!
+    expect(sp.op).toBe('react.mount')
+    expect(sp.name).toBe('dashboard mount')
+    expect(sp.tags).toMatchObject({ route: 'dashboard' })
+    expect(sp.data).toEqual({ rowCount: 42 })
+  })
+
+  test('name defaults to op when omitted', () => {
+    const { unmount } = render(
+      <TraceRender op="react.mount">
+        <div />
+      </TraceRender>,
+    )
+    unmount()
+
+    expect(drainSpans()[0]?.name).toBe('react.mount')
+  })
+
+  test('multiple sequential mounts emit independent spans', () => {
+    const first = render(<TraceRender name="a"><div /></TraceRender>)
+    first.unmount()
+    const second = render(<TraceRender name="b"><div /></TraceRender>)
+    second.unmount()
+
+    const spans = drainSpans()
+    expect(spans).toHaveLength(2)
+    expect(spans.map((s) => s.name).sort()).toEqual(['a', 'b'])
+  })
+
+  test('re-render with new props does NOT restart the span', () => {
+    const { rerender, unmount } = render(
+      <TraceRender name="first">
+        <div />
+      </TraceRender>,
+    )
+    rerender(
+      <TraceRender name="second-name-ignored">
+        <div />
+      </TraceRender>,
+    )
+    unmount()
+
+    const spans = drainSpans()
+    expect(spans).toHaveLength(1)
+    // First-render name wins (lifespan is the component instance).
+    expect(spans[0]?.name).toBe('first')
+  })
+})

package/src/index.ts

@@ -1,5 +1,7 @@
 export { SentoriProvider } from './SentoriProvider.js'
 export { SentoriErrorBoundary } from './SentoriErrorBoundary.js'
+export { SentoriSuspense } from './SentoriSuspense.js'
+export { TraceRender } from './SentoriTrace.js'
 export { useSentori, useCaptureError } from './hooks.js'
 
 export type {