Metri

pnpm add @joycostudio/metri

import { Metri } from '@joycostudio/metri'
 
const metri = new Metri({ throttleMs: 100 })
metri.initialize()
 
// Register an element — its bounds are cached and updated on resize.
const el = document.querySelector('#hero')!
metri.track(el)
 
metri.on('refresh', ({ target, rect }) => {
  if (target === el) console.log('hero moved', rect)
})
 
// Read cached bounds — no getBoundingClientRect call.
metri.get(el)         // document-space
metri.getBounds(el)   // viewport-space
metri.windowSize      // { width, height, ... }

import { MetriProvider, useBounds, useScreen } from '@joycostudio/metri/react'
import { useRef } from 'react'
 
function App() {
  return (
    <MetriProvider>
      <Hero />
    </MetriProvider>
  )
}
 
function Hero() {
  const ref = useRef<HTMLDivElement>(null)
  const { bounds } = useBounds(ref)
  const { screen } = useScreen()
 
  return (
    <div ref={ref}>
      {bounds?.width.toFixed(0)} × {bounds?.height.toFixed(0)}
      {' / viewport '}
      {screen.width} × {screen.height}
    </div>
  )
}

import { Metri } from '@joycostudio/metri'
 
const metri = new Metri(options?: MetriOptions)
metri.initialize()

type MetriOptions = {
  throttleMs?: number       // ResizeObserver + resize throttle (default: 100)
  scrollGetter?: ScrollGetter   // Read the current scroll state
  scrollListener?: ScrollListener // Subscribe to scroll updates
  debug?: boolean | { interval: number } // Opt-in instrumentation
}
 
type ScrollState = { scrollX: number; scrollY: number }
type ScrollGetter = () => ScrollState
type ScrollListener = (cb: (state: ScrollState) => void) => () => void

type Bounds = {
  x: number
  y: number
  top: number
  right: number
  bottom: number
  left: number
  width: number
  height: number
}

type IntersectionConfig = {
  root?: Element | Document | null
  rootMargin?: string
  threshold?: number | number[]
}

type MetriEventMap = {
  refresh: { target: Element | Window; rect: Bounds; metri: Metri }
  observe: { target: Element; visible: boolean; entry: IntersectionObserverEntry; metri: Metri }
  scroll:  { scrollX: number; scrollY: number }
}
 
metri.on('refresh', ({ target, rect }) => { /* ... */ })
metri.on('observe', ({ target, visible }) => { /* ... */ })
metri.on('scroll', ({ scrollY }) => { /* ... */ })
metri.off('refresh', listener)

const metri = new Metri({ debug: true })
// or log to console every 2s and reset counters per window:
const metri = new Metri({ debug: { interval: 2000 } })

type DebugSnapshot = {
  getBoundingClientRectCalls: number
  cacheHits: number
  cacheMisses: number
  trackedElementCount: number
  fullRefreshCount: number
  targetedRefreshCount: number
  resizeObserverFires: number
  intersectionObserverCount: number
  cacheSize: number
}

metri.disposeAll() // Disconnects observers, detaches listeners, clears the cache

import {
  MetriProvider,
  useMetri,
  useBounds,
  useQueryBounds,
  useScreen,
  useObserve,
  useTrack,
  useScrollCallback,
  DataVisibleSlot,
} from '@joycostudio/metri/react'

// Self-managed: provider creates and disposes on unmount
<MetriProvider throttleMs={100} debug={false}>
  {children}
</MetriProvider>
 
// Self-managed with custom scroll source (e.g. Lenis)
<MetriProvider scrollGetter={scrollGetter} scrollListener={scrollListener}>
  {children}
</MetriProvider>
 
// Bridge: reuse an instance (e.g. across portal roots)
const metri = new Metri({ throttleMs: 100 })
metri.initialize()
 
<MetriProvider metri={metri}>
  {children}
</MetriProvider>

const { metri } = useMetri()
metri.setPlaybackRate // ← nope, wrong lib; you get the Metri instance

const ref = useRef<HTMLDivElement>(null)
const { bounds, getBounds, refresh } = useBounds(ref, { space: 'document' })

const { bounds } = useQueryBounds<HTMLElement>('[data-hero]')

const { screen, getScreen } = useScreen()
// screen: { width, height }

const ref = useRef<HTMLDivElement>(null)
const { visible, observer } = useObserve(ref, { threshold: 0.5 })

const { bounds, observe, scrollProgress } = useTrack(ref, {
  threshold: 0,
  onProgress: (p) => setProgress(p), // 0 when entering from below, 1 when exited through top
})

useScrollCallback(({ scrollY }) => {
  // runs on every scroll event — not throttled
})

<DataVisibleSlot config={{ threshold: 0.25 }}>
  <section className="opacity-0 data-[visible=true]:opacity-100 transition">
    {/* CSS reacts to data-visible */}
  </section>
</DataVisibleSlot>

import Lenis from 'lenis'
import type { ScrollGetter, ScrollListener } from '@joycostudio/metri/react'
 
let lenis: Lenis | null = null
const getLenis = () => (lenis ??= new Lenis({ autoRaf: true }))
 
export const scrollGetter: ScrollGetter = () => ({ scrollY: getLenis().scroll, scrollX: 0 })
export const scrollListener: ScrollListener = (cb) =>
  getLenis().on('scroll', (l) => cb({ scrollX: 0, scrollY: l.scroll }))

<MetriProvider scrollGetter={scrollGetter} scrollListener={scrollListener}>
  {children}
</MetriProvider>

const { metri } = useMetri()
 
useEffect(() => {
  const lenis = new Lenis({ autoRaf: true })
  metri.setScrollHandlers(
    () => ({ scrollX: 0, scrollY: lenis.scroll }),
    (cb) => lenis.on('scroll', (l) => cb({ scrollX: 0, scrollY: l.scroll })),
  )
  return () => lenis.destroy()
}, [metri])

function Reveal({ children }: { children: React.ReactNode }) {
  const ref = useRef<HTMLDivElement>(null)
  const [p, setP] = useState(0)
 
  useTrack(ref, { onProgress: setP })
 
  return (
    <div ref={ref} style={{ opacity: p, transform: `translateY(${(1 - p) * 40}px)` }}>
      {children}
    </div>
  )
}

const metri = useMemo(() => new Metri(), [])
useLayoutEffect(() => {
  metri.initialize()
  return () => metri.disposeAll()
}, [metri])
 
return (
  <>
    <MetriProvider metri={metri}>{appTree}</MetriProvider>
    {createPortal(
      <MetriProvider metri={metri}>{overlayTree}</MetriProvider>,
      document.body,
    )}
  </>
)

const metri = new Metri({ debug: true })
metri.initialize()
 
// ...some interaction...
metri.debugReset()
await userTypes()
console.table(metri.debugSnapshot())

<DataVisibleSlot config={{ rootMargin: '-10%' }}>
  <h1 className="data-[visible=true]:animate-fade-in">Hello</h1>
</DataVisibleSlot>

documentBounds.top    = rect.top    + scrollY
viewportBounds.top    = documentBounds.top - scrollY