react-tooltip 6.0.0-beta.1179.rc.2 → 6.0.0-beta.1179.rc.3

package/README.md

@@ -42,6 +42,32 @@ or
 yarn add react-tooltip
 ```
 
+## React Compatibility
+
+`react-tooltip` supports React `16.14.0` and newer through peer dependencies, including React 17, 18, and 19.
+
+The project is currently validated against React 19, but the published package remains compatible with older supported React versions.
+
+| React version | Supported |
+| ------------- | --------- |
+| 16.14+        | Yes       |
+| 17.x          | Yes       |
+| 18.x          | Yes       |
+| 19.x          | Yes       |
+
+## Server Components
+
+`react-tooltip` is a client-side library. It uses hooks, DOM observers, browser events, and layout measurement, so the tooltip component itself must run inside a client component boundary.
+
+This works well in frameworks such as Next.js with Server Components, but you should render `<Tooltip />` from a client component and attach your tooltip attributes or selectors from elements rendered under that client boundary.
+
+If you are using React Server Components, the practical rule is simple:
+
+- server components can render the anchor markup
+- client components should render and control `react-tooltip`
+
+In Next.js, the usual pattern is to export the tooltip from a small wrapper file marked with `'use client'`.
+
 ## Sponsors
 
 ### Gold Sponsors 🌟

package/benchmarks/aggregate-benchmarks.mjs

@@ -0,0 +1,258 @@
+import { readdir, readFile, writeFile } from 'fs/promises'
+import path from 'path'
+import { fileURLToPath } from 'url'
+import minimist from 'minimist'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const resultsDir = path.join(__dirname, 'results')
+
+const args = minimist(process.argv.slice(2))
+const latest = Number(args.latest ?? 3)
+const useAll = Boolean(args.all)
+const generationArg = args.generation
+const useAllGenerations = Boolean(args['all-generations'])
+const explicitFiles = args._.map((inputPath) => path.resolve(inputPath))
+
+function aggregateNumbers(values) {
+  const sorted = values
+    .filter((value) => typeof value === 'number' && Number.isFinite(value))
+    .sort((left, right) => left - right)
+
+  if (sorted.length === 0) {
+    return {
+      median: null,
+      p95: null,
+      min: null,
+      max: null,
+      mean: null,
+      standardDeviation: null,
+      spreadPercent: null,
+      sampleCount: 0,
+    }
+  }
+
+  const middle = Math.floor(sorted.length / 2)
+  const median =
+    sorted.length % 2 === 0
+      ? (sorted[middle - 1] + sorted[middle]) / 2
+      : sorted[middle]
+  const mean = sorted.reduce((total, value) => total + value, 0) / sorted.length
+  const variance =
+    sorted.reduce((total, value) => total + (value - mean) ** 2, 0) / sorted.length
+  const standardDeviation = Math.sqrt(variance)
+  const p95 = sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * 0.95) - 1)]
+
+  return {
+    median,
+    p95,
+    min: sorted[0],
+    max: sorted[sorted.length - 1],
+    mean,
+    standardDeviation,
+    spreadPercent: median === 0 ? null : ((p95 - median) / Math.abs(median)) * 100,
+    sampleCount: sorted.length,
+  }
+}
+
+function formatMs(value) {
+  return typeof value === 'number' ? `${value.toFixed(2)} ms` : '—'
+}
+
+function formatBytes(value) {
+  return typeof value === 'number' ? `${(value / 1024).toFixed(1)} KiB` : '—'
+}
+
+function formatPercent(value) {
+  return typeof value === 'number' ? `${value.toFixed(1)}%` : '—'
+}
+
+function timestampId() {
+  return new Date().toISOString().replace(/[:.]/g, '-')
+}
+
+function getRunGeneration(run) {
+  return Number.isInteger(run?.benchmarkVersion) ? run.benchmarkVersion : 0
+}
+
+async function resolveInputFiles() {
+  if (explicitFiles.length > 0) {
+    return explicitFiles
+  }
+
+  const entries = await readdir(resultsDir)
+  const scalingEntries = entries
+    .filter((entry) => entry.endsWith('.json'))
+    .filter((entry) => entry.startsWith('scaling-'))
+    .map((entry) => path.join(resultsDir, entry))
+    .sort()
+
+  if (useAll) {
+    return scalingEntries
+  }
+
+  return scalingEntries.slice(-latest)
+}
+
+function resolveGenerationSelection(runs) {
+  if (useAllGenerations) {
+    return {
+      selectedRuns: runs,
+      generationLabel: 'all benchmark generations',
+    }
+  }
+
+  if (generationArg !== undefined) {
+    const requestedGeneration =
+      generationArg === 'latest' ? Math.max(...runs.map(getRunGeneration)) : Number(generationArg)
+
+    if (!Number.isInteger(requestedGeneration)) {
+      throw new Error(`Invalid --generation value: ${generationArg}`)
+    }
+
+    return {
+      selectedRuns: runs.filter((run) => getRunGeneration(run) === requestedGeneration),
+      generationLabel:
+        generationArg === 'latest'
+          ? `latest benchmark generation (${requestedGeneration})`
+          : `benchmark generation ${requestedGeneration}`,
+    }
+  }
+
+  return {
+    selectedRuns: runs,
+    generationLabel: 'all benchmark generations',
+  }
+}
+
+function buildMarkdownReport(result) {
+  const lines = [
+    '# Aggregated React Tooltip Scaling Benchmark',
+    '',
+    `- Timestamp: ${result.timestamp}`,
+    `- Input files: ${result.inputFiles.length}`,
+    `- Selection: ${result.selection}`,
+    `- Generation filter: ${result.generationFilter}`,
+    `- Counts: ${result.counts.join(', ')}`,
+    '',
+    '| Count | V5 mount | V6 mount | Mount delta | Mount spread | V5 unmount | V6 unmount | Unmount delta | Unmount spread | V5 mount mem | V6 mount mem | Mount mem delta | Mount mem spread | V5 unmount mem | V6 unmount mem | Unmount mem delta | Unmount mem spread | Samples | V5 timeouts | V6 timeouts |',
+    '| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |',
+  ]
+
+  result.summary.forEach((row) => {
+    lines.push(
+      `| ${row.count} | ${formatMs(row.v5.mount.median)} | ${formatMs(row.v6.mount.median)} | ${formatMs(row.mountDeltaMs)} | ${formatPercent(row.mountDeltaSpreadPercent)} | ${formatMs(row.v5.unmount.median)} | ${formatMs(row.v6.unmount.median)} | ${formatMs(row.unmountDeltaMs)} | ${formatPercent(row.unmountDeltaSpreadPercent)} | ${formatBytes(row.v5.mountMemory.median)} | ${formatBytes(row.v6.mountMemory.median)} | ${formatBytes(row.mountMemoryDeltaBytes)} | ${formatPercent(row.mountMemoryDeltaSpreadPercent)} | ${formatBytes(row.v5.unmountMemory.median)} | ${formatBytes(row.v6.unmountMemory.median)} | ${formatBytes(row.unmountMemoryDeltaBytes)} | ${formatPercent(row.unmountMemoryDeltaSpreadPercent)} | ${row.sampleCount} | ${row.v5.timeoutCount} | ${row.v6.timeoutCount} |`,
+    )
+  })
+
+  return `${lines.join('\n')}\n`
+}
+
+async function main() {
+  const inputFiles = await resolveInputFiles()
+
+  if (inputFiles.length === 0) {
+    throw new Error('No benchmark result files were found to aggregate.')
+  }
+
+  const allRuns = await Promise.all(
+    inputFiles.map(async (inputFile) => JSON.parse(await readFile(inputFile, 'utf8'))),
+  )
+  const { selectedRuns: runs, generationLabel } = resolveGenerationSelection(allRuns)
+
+  if (runs.length === 0) {
+    throw new Error('No benchmark result files matched the requested generation filter.')
+  }
+
+  const counts = Array.from(
+    new Set(runs.flatMap((run) => run.counts ?? [])),
+  ).sort((left, right) => left - right)
+
+  const summary = counts.map((count) => {
+    const rows = runs
+      .map((run) => run.summary?.find((entry) => entry.count === count))
+      .filter(Boolean)
+
+    const aggregateVersion = (version) => ({
+      mount: aggregateNumbers(rows.map((row) => row[version]?.mount?.median)),
+      unmount: aggregateNumbers(rows.map((row) => row[version]?.unmount?.median)),
+      mountMemory: aggregateNumbers(rows.map((row) => row[version]?.mountMemory?.median)),
+      unmountMemory: aggregateNumbers(rows.map((row) => row[version]?.unmountMemory?.median)),
+      timeoutCount: rows.reduce(
+        (total, row) => total + (row[version]?.timeoutCount ?? 0),
+        0,
+      ),
+    })
+
+    const v5 = aggregateVersion('v5')
+    const v6 = aggregateVersion('v6')
+    const sampleCount = Math.max(v5.mount.sampleCount, v6.mount.sampleCount)
+
+    const mountDeltaMs =
+      typeof v5.mount.median === 'number' && typeof v6.mount.median === 'number'
+        ? v6.mount.median - v5.mount.median
+        : null
+    const unmountDeltaMs =
+      typeof v5.unmount.median === 'number' && typeof v6.unmount.median === 'number'
+        ? v6.unmount.median - v5.unmount.median
+        : null
+    const mountMemoryDeltaBytes =
+      typeof v5.mountMemory.median === 'number' && typeof v6.mountMemory.median === 'number'
+        ? v6.mountMemory.median - v5.mountMemory.median
+        : null
+    const unmountMemoryDeltaBytes =
+      typeof v5.unmountMemory.median === 'number' && typeof v6.unmountMemory.median === 'number'
+        ? v6.unmountMemory.median - v5.unmountMemory.median
+        : null
+
+    return {
+      count,
+      sampleCount,
+      v5,
+      v6,
+      mountDeltaMs,
+      unmountDeltaMs,
+      mountMemoryDeltaBytes,
+      unmountMemoryDeltaBytes,
+      mountDeltaSpreadPercent:
+        typeof v5.mount.spreadPercent === 'number' && typeof v6.mount.spreadPercent === 'number'
+          ? Math.max(v5.mount.spreadPercent, v6.mount.spreadPercent)
+          : null,
+      unmountDeltaSpreadPercent:
+        typeof v5.unmount.spreadPercent === 'number' && typeof v6.unmount.spreadPercent === 'number'
+          ? Math.max(v5.unmount.spreadPercent, v6.unmount.spreadPercent)
+          : null,
+      mountMemoryDeltaSpreadPercent:
+        typeof v5.mountMemory.spreadPercent === 'number' && typeof v6.mountMemory.spreadPercent === 'number'
+          ? Math.max(v5.mountMemory.spreadPercent, v6.mountMemory.spreadPercent)
+          : null,
+      unmountMemoryDeltaSpreadPercent:
+        typeof v5.unmountMemory.spreadPercent === 'number' && typeof v6.unmountMemory.spreadPercent === 'number'
+          ? Math.max(v5.unmountMemory.spreadPercent, v6.unmountMemory.spreadPercent)
+          : null,
+    }
+  })
+
+  const result = {
+    id: `aggregate-scaling-${timestampId()}`,
+    timestamp: new Date().toISOString(),
+    selection: useAll ? 'all scaling runs' : `latest ${latest} scaling run(s)`,
+    generationFilter: generationLabel,
+    inputFiles: runs.map((run, index) => inputFiles[allRuns.indexOf(run)] ?? inputFiles[index]),
+    counts,
+    summary,
+  }
+
+  const jsonPath = path.join(resultsDir, `${result.id}.json`)
+  const markdownPath = path.join(resultsDir, `${result.id}.md`)
+
+  await writeFile(jsonPath, `${JSON.stringify(result, null, 2)}\n`, 'utf8')
+  await writeFile(markdownPath, buildMarkdownReport(result), 'utf8')
+
+  console.log(`Saved aggregate benchmark results to ${jsonPath}`)
+  console.log(`Saved aggregate benchmark report to ${markdownPath}`)
+}
+
+main().catch((error) => {
+  console.error(error)
+  process.exitCode = 1
+})

package/benchmarks/fixture/app.tsx

@@ -0,0 +1,278 @@
+import React, { useEffect, useMemo, useState } from 'react'
+import { flushSync } from 'react-dom'
+import { createRoot } from 'react-dom/client'
+import { Tooltip as TooltipV5 } from '../../docs/node_modules/react-tooltip/dist/react-tooltip.mjs'
+import { Tooltip as TooltipV6 } from '../../dist/react-tooltip.esm.js'
+
+type BenchmarkVersion = 'v5' | 'v6'
+
+type RenderMode = 'shared'
+
+type FixtureState = {
+  version: BenchmarkVersion
+  count: number
+  renderMode: RenderMode
+}
+
+type ScenarioSample = {
+  count: number
+  mountDurationMs: number | null
+  unmountDurationMs: number | null
+  mountMemoryDeltaBytes: number | null
+  unmountMemoryDeltaBytes: number | null
+  timedOut: boolean
+}
+
+type ScenarioResult = {
+  version: BenchmarkVersion
+  renderMode: RenderMode
+  samplesByCount: ScenarioSample[]
+}
+
+type BenchmarkHarness = {
+  runScalingBenchmark: (args: {
+    version: BenchmarkVersion
+    counts: number[]
+    timeoutMs: number
+    repeats: number
+    warmups: number
+    renderMode: RenderMode
+    onProgress?: (message: string) => void
+  }) => Promise<ScenarioResult>
+}
+
+declare global {
+  interface Window {
+    __reactTooltipBenchmark?: BenchmarkHarness
+    __REACT_DEVTOOLS_GLOBAL_HOOK__?: {
+      isDisabled?: boolean
+    }
+    gc?: () => void
+  }
+}
+
+window.__REACT_DEVTOOLS_GLOBAL_HOOK__ = {
+  isDisabled: true,
+}
+
+function readUsedHeapBytes() {
+  const performanceWithMemory = window.performance as Performance & {
+    memory?: {
+      usedJSHeapSize: number
+    }
+  }
+
+  return performanceWithMemory.memory?.usedJSHeapSize ?? null
+}
+
+function nextFrame() {
+  return new Promise<void>((resolve) => {
+    window.requestAnimationFrame(() => resolve())
+  })
+}
+
+async function collectGarbage() {
+  if (typeof window.gc === 'function') {
+    window.gc()
+    await nextFrame()
+    window.gc()
+    await nextFrame()
+  }
+}
+
+async function readStableHeapBytes() {
+  await collectGarbage()
+  return readUsedHeapBytes()
+}
+
+async function waitUntil(predicate: () => boolean, timeoutMs: number) {
+  const startedAt = window.performance.now()
+
+  while (window.performance.now() - startedAt < timeoutMs) {
+    if (predicate()) {
+      return true
+    }
+    await nextFrame()
+  }
+
+  return false
+}
+
+function BenchmarkFixture({ version, count }: FixtureState) {
+  const TooltipComponent = version === 'v5' ? TooltipV5 : TooltipV6
+  const tooltipId = `benchmark-tooltip-${version}`
+
+  const anchorIds = useMemo(
+    () => Array.from({ length: count }, (_, index) => `anchor-${version}-${index}`),
+    [count, version],
+  )
+
+  useEffect(() => {
+    document.body.setAttribute('data-benchmark-count', String(count))
+    document.body.setAttribute('data-benchmark-version', version)
+  }, [count, version])
+
+  return (
+    <div className="benchmark-surface" aria-hidden="true">
+      <div className="anchor-grid">
+        {anchorIds.map((id, index) => (
+          <button
+            key={id}
+            id={id}
+            className="anchor"
+            data-tooltip-id={tooltipId}
+            data-tooltip-content={`Anchor ${index}`}
+            type="button"
+          >
+            {index}
+          </button>
+        ))}
+      </div>
+      <TooltipComponent id={tooltipId} />
+    </div>
+  )
+}
+
+const rootNode = document.getElementById('root')
+
+if (!rootNode) {
+  throw new Error('Benchmark root element was not found.')
+}
+
+const benchmarkRoot = createRoot(rootNode)
+
+function renderFixture(nextState: FixtureState) {
+  return new Promise<void>((resolve) => {
+    flushSync(() => {
+      benchmarkRoot.render(<BenchmarkFixture {...nextState} />)
+    })
+    resolve()
+  })
+}
+
+function unmountFixture() {
+  return new Promise<void>((resolve) => {
+    flushSync(() => {
+      benchmarkRoot.render(<></>)
+    })
+    resolve()
+  })
+}
+
+async function runScalingBenchmark({
+  version,
+  counts,
+  timeoutMs,
+  repeats,
+  warmups,
+  renderMode,
+  onProgress,
+}: {
+  version: BenchmarkVersion
+  counts: number[]
+  timeoutMs: number
+  repeats: number
+  warmups: number
+  renderMode: RenderMode
+  onProgress?: (message: string) => void
+}): Promise<ScenarioResult> {
+  const samplesByCount: ScenarioSample[] = []
+
+  for (const count of counts) {
+    for (let warmupIndex = 0; warmupIndex < warmups; warmupIndex += 1) {
+      onProgress?.(`count=${count} warmup ${warmupIndex + 1}/${warmups}`)
+      await renderFixture({
+        version,
+        count: 0,
+        renderMode,
+      })
+      await nextFrame()
+      await renderFixture({
+        version,
+        count,
+        renderMode,
+      })
+      await waitUntil(
+        () => document.querySelectorAll('[data-tooltip-id]').length === count,
+        timeoutMs,
+      )
+      await nextFrame()
+      await unmountFixture()
+      await nextFrame()
+    }
+
+    for (let repeatIndex = 0; repeatIndex < repeats; repeatIndex += 1) {
+      onProgress?.(`count=${count} repeat ${repeatIndex + 1}/${repeats}`)
+      await renderFixture({
+        version,
+        count: 0,
+        renderMode,
+      })
+      await nextFrame()
+
+      const mountMemoryBefore = await readStableHeapBytes()
+      const mountStartedAt = window.performance.now()
+
+      await renderFixture({
+        version,
+        count,
+        renderMode,
+      })
+
+      const mountReady = await waitUntil(() => {
+        return document.querySelectorAll('[data-tooltip-id]').length === count
+      }, timeoutMs)
+
+      await nextFrame()
+
+      const mountEndedAt = window.performance.now()
+
+      const mountMemoryAfter = await readStableHeapBytes()
+      const unmountMemoryBefore = mountMemoryAfter
+      const unmountStartedAt = window.performance.now()
+
+      await unmountFixture()
+
+      const unmountReady = await waitUntil(() => {
+        return document.querySelectorAll('[data-tooltip-id]').length === 0
+      }, timeoutMs)
+
+      await nextFrame()
+
+      const unmountEndedAt = window.performance.now()
+
+      const unmountMemoryAfter = await readStableHeapBytes()
+
+      samplesByCount.push({
+        count,
+        mountDurationMs: mountReady ? mountEndedAt - mountStartedAt : null,
+        unmountDurationMs: unmountReady ? unmountEndedAt - unmountStartedAt : null,
+        mountMemoryDeltaBytes:
+          mountReady && mountMemoryBefore !== null && mountMemoryAfter !== null
+            ? mountMemoryAfter - mountMemoryBefore
+            : null,
+        unmountMemoryDeltaBytes:
+          unmountReady && unmountMemoryBefore !== null && unmountMemoryAfter !== null
+            ? unmountMemoryAfter - unmountMemoryBefore
+            : null,
+        timedOut: !mountReady || !unmountReady,
+      })
+    }
+  }
+
+  return {
+    version,
+    renderMode,
+    samplesByCount,
+  }
+}
+
+window.__reactTooltipBenchmark = {
+  runScalingBenchmark,
+}
+
+renderFixture({
+  version: 'v6',
+  count: 0,
+  renderMode: 'shared',
+})

package/benchmarks/fixture/index.html

@@ -0,0 +1,54 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>React Tooltip Benchmark</title>
+    <style>
+      html,
+      body {
+        margin: 0;
+        padding: 0;
+      }
+
+      body {
+        font-family: sans-serif;
+      }
+
+      #root {
+        min-height: 100vh;
+      }
+
+      .benchmark-surface {
+        left: 24px;
+        opacity: 0.02;
+        pointer-events: none;
+        position: fixed;
+        top: 24px;
+        width: 1200px;
+        z-index: -1;
+      }
+
+      .anchor-grid {
+        display: grid;
+        gap: 8px;
+        grid-template-columns: repeat(10, minmax(0, 1fr));
+      }
+
+      .anchor {
+        align-items: center;
+        background: #111827;
+        border: 0;
+        border-radius: 6px;
+        color: #fff;
+        display: inline-flex;
+        height: 28px;
+        justify-content: center;
+      }
+    </style>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/app.js"></script>
+  </body>
+</html>