// ❌ Broken — over-memoized component with a stale closure bug
'use client'
import { useMemo, useCallback, memo, useState } from 'react'

interface Item {
  id: string
  name: string
  price: number
}

const ItemRow = memo(({ item, onSelect }: { item: Item; onSelect: (id: string) => void }) => {
  return <li onClick={() => onSelect(item.id)}>{item.name}</li>
})

function ItemList({ items, discount }: { items: Item[]; discount: number }) {
  const [selected, setSelected] = useState<string | null>(null)

  // ❌ useMemo with wrong deps — discount is not in the dependency array
  // filteredItems will not update when discount changes
  const filteredItems = useMemo(() => {
    return items.filter(item => item.price * (1 - discount) < 100)
  }, [items]) // ← discount is missing

  // ❌ useCallback closes over stale `selected` due to empty deps
  const handleSelect = useCallback((id: string) => {
    console.log('Previously selected:', selected) // Always logs null
    setSelected(id)
  }, []) // ← selected is missing, but adding it recreates the callback on every render

  return <ul>{filteredItems.map(item => <ItemRow key={item.id} item={item} onSelect={handleSelect} />)}</ul>
}

# Step 1: Install the ESLint plugin (includes compiler purity rules as of v1.0)
npm install --save-dev eslint-plugin-react-hooks@latest

# Step 2: Install the compiler babel plugin
npm install --save-dev babel-plugin-react-compiler

// eslint.config.js — react-hooks plugin now includes compiler purity rules
import reactHooks from 'eslint-plugin-react-hooks'

export default [
  {
    plugins: { 'react-hooks': reactHooks },
    rules: {
      ...reactHooks.configs.recommended.rules,
      // Compiler purity rules are included in react-hooks@latest:
      'react-hooks/react-compiler': 'error', // Fail on purity violations
    },
  },
]

// next.config.ts — enable the React Compiler in Next.js 15
import type { NextConfig } from 'next'

const config: NextConfig = {
  experimental: {
    reactCompiler: true,
    // OR for incremental adoption — opt in per directory/file:
    reactCompiler: {
      compilationMode: 'annotation', // Only compile files with 'use memo' directive
    },
  },
}
export default config

// babel.config.js — for Vite or CRA projects
module.exports = {
  plugins: [
    ['babel-plugin-react-compiler', {
      target: '18', // React version: '17', '18', or '19'
      // compilationMode: 'annotation' — for incremental adoption
    }],
  ],
}

// Source — what you write:
function ProductCard({ product }: { product: Product }) {
  const discountedPrice = product.price * 0.9
  const label = `${product.name} — ${formatPrice(discountedPrice)}`

  return (
    <div>
      <h3>{label}</h3>
      <span>{formatPrice(discountedPrice)}</span>
    </div>
  )
}

// Compiled output (simplified) — what the compiler produces:
function ProductCard(t0) {
  const $ = useMemoCache(6) // c(6) — a cache array with 6 slots
  const { product } = t0

  let t1 // discountedPrice
  if ($[0] !== product.price) {
    t1 = product.price * 0.9  // Only recomputed when product.price changes
    $[0] = product.price
    $[1] = t1
  } else {
    t1 = $[1] // Cached value — no recomputation
  }

  let t2 // label
  if ($[2] !== product.name || $[3] !== t1) {
    t2 = `${product.name} — ${formatPrice(t1)}`
    $[2] = product.name
    $[3] = t1
    $[4] = t2
  } else {
    t2 = $[4]
  }

  let t3 // JSX output
  if ($[5] !== t2) {
    t3 = <div><h3>{t2}</h3><span>{formatPrice(t1)}</span></div>
    $[5] = t3
  }
  return t3 // If product hasn't changed, same JSX reference returned — no re-render
}

// ❌ Mutating props — impure, compiler skips
function BadComponent({ items }: { items: Item[] }) {
  items.push({ id: 'extra', name: 'Added' }) // ← Mutation during render
  return <ul>{items.map(i => <li key={i.id}>{i.name}</li>)}</ul>
}

// ❌ Reading from a mutable external ref during render — impure
let globalCounter = 0
function Counter() {
  globalCounter++ // ← Side effect during render
  return <span>{globalCounter}</span>
}

// ❌ Calling non-pure functions during render — impure if the function has side effects
function DataRow({ id }: { id: string }) {
  const data = fetchDataSynchronously(id) // ← Side effect (I/O during render)
  return <div>{data.name}</div>
}

// ✅ Pure — same inputs always produce the same output
function ProductCard({ product }: { product: Product }) {
  const price = product.price * 0.9           // ← Pure derivation
  return <div>{product.name}: {price}</div>   // ← Deterministic output
}

// Example: why is this component re-rendering on every parent render?

// Compiled output reveals:
if ($[0] !== props.onClose) {  // ← onClose is in slot 0
  // ...compute expensive JSX
  $[0] = props.onClose
}

// If onClose is created inline in the parent: onClick={() => setOpen(false)}
// → New function reference on every parent render
// → $[0] !== props.onClose is always true
// → Cache always misses
// → No benefit from compiler memoization for this component

// Fix: move onClose to a stable Server Action or use useCallback in the parent
// (or, after the compiler, the parent's own compiled output will stabilize onClose)

// ❌ The compiler cannot see through this — useCallback still required
function MapComponent({ onLocationChange }: { onLocationChange: (loc: LatLng) => void }) {
  const map = useRef<google.maps.Map>(null)

  // This callback is passed to the Google Maps SDK — not to React
  // The compiler cannot analyze what Google Maps does with it
  // If onLocationChange is recreated every render, Maps SDK re-subscribes every render
  const handleMapClick = useCallback((e: google.maps.MapMouseEvent) => {
    onLocationChange(e.latLng!)
  }, [onLocationChange]) // ← Still needed — external SDK subscription

  useEffect(() => {
    if (!map.current) return
    const listener = map.current.addListener('click', handleMapClick)
    return () => google.maps.event.removeListener(listener)
  }, [handleMapClick]) // ← handleMapClick in deps — useCallback is the correct tool here
}

// ❌ Values used in useEffect dependency arrays with external stores — useMemo still needed
function StoreConnectedComponent({ filter }: { filter: Filter }) {
  // computedQuery escapes React — it's passed to an external store subscription
  const computedQuery = useMemo(() => buildQuery(filter), [filter])

  useEffect(() => {
    const subscription = externalStore.subscribe(computedQuery, handleUpdate)
    return () => subscription.unsubscribe()
  }, [computedQuery]) // ← computedQuery must be stable across renders
}

// The compiler memoizes PriceTag's JSX output inside ProductCard
// so ProductCard's render does not recreate PriceTag's JSX on every render.

// React.memo on PriceTag prevents re-renders when ProductCard re-renders
// for reasons unrelated to the props PriceTag cares about.

// Both are useful: the compiler optimizes the output creation,
// React.memo optimizes the component invocation from the parent.

const PriceTag = React.memo(({ price, currency }: { price: number; currency: string }) => {
  return <span>{formatPrice(price, currency)}</span>
})
// This is not redundant with the compiler — they optimize at different levels

function DebugComponent({ data }: { data: unknown }) {
  'use no memo' // ← Opts this component out of compiler optimization entirely
  // Use temporarily when debugging to isolate whether the compiler is causing unexpected behavior
  // Remove once debugging is complete — do not leave in production code
  console.log('render:', data)
  return <pre>{JSON.stringify(data, null, 2)}</pre>
}

// React 18 and earlier — forwardRef wrapper required
const Input = forwardRef<HTMLInputElement, InputProps>((props, ref) => {
  return <input ref={ref} {...props} />
})

// React 19 — ref is a regular prop, no wrapper needed
function Input({ ref, ...props }: InputProps & { ref?: React.Ref<HTMLInputElement> }) {
  return <input ref={ref} {...props} />
}
// The compiler handles both patterns during migration — no "use no memo" needed