@tamagui/use-element-layout 1.129.6-1751237024118

package/src/index.ts

@@ -0,0 +1,304 @@
+import { isClient, useIsomorphicLayoutEffect } from '@tamagui/constants'
+import { isEqualShallow } from '@tamagui/is-equal-shallow'
+import type { RefObject } from 'react'
+
+const LayoutHandlers = new WeakMap<HTMLElement, Function>()
+const Nodes = new Set<HTMLElement>()
+
+type TamaguiComponentStatePartial = {
+  host?: any
+}
+
+type LayoutMeasurementStrategy = 'off' | 'sync' | 'async'
+
+let strategy: LayoutMeasurementStrategy = 'async'
+
+export function setOnLayoutStrategy(state: LayoutMeasurementStrategy): void {
+  strategy = state
+}
+
+export type LayoutValue = {
+  x: number
+  y: number
+  width: number
+  height: number
+  left: number
+  top: number
+}
+
+export type LayoutEvent = {
+  nativeEvent: {
+    layout: LayoutValue
+    target: any
+  }
+  timeStamp: number
+}
+
+const NodeRectCache = new WeakMap<HTMLElement, DOMRect>()
+const ParentRectCache = new WeakMap<HTMLElement, DOMRect>()
+const DebounceTimers = new WeakMap<HTMLElement, NodeJS.Timeout>()
+const LastChangeTime = new WeakMap<HTMLElement, number>()
+
+const rAF = typeof window !== 'undefined' ? window.requestAnimationFrame : undefined
+const DEBOUNCE_DELAY = 32 // 32ms debounce (2 frames at 60fps)
+
+// prevent thrashing during first hydration (somewhat, streaming gets trickier)
+let avoidUpdates = true
+const queuedUpdates = new Map<HTMLElement, Function>()
+
+export function enable(): void {
+  if (avoidUpdates) {
+    avoidUpdates = false
+    if (queuedUpdates) {
+      queuedUpdates.forEach((cb) => cb())
+      queuedUpdates.clear()
+    }
+  }
+}
+
+if (isClient) {
+  if (rAF) {
+    // track frame timing to detect sync work and avoid updates during heavy periods
+    let lastFrameAt = Date.now()
+    const numDroppedFramesUntilPause = 2 // adjust sensitivity
+
+    async function updateLayoutIfChanged(node: HTMLElement) {
+      const nodeRect = node.getBoundingClientRect()
+      const parentNode = node.parentElement
+      const parentRect = parentNode?.getBoundingClientRect()
+
+      const onLayout = LayoutHandlers.get(node)
+      if (typeof onLayout !== 'function') return
+
+      const cachedRect = NodeRectCache.get(node)
+      const cachedParentRect = parentNode ? NodeRectCache.get(parentNode) : null
+
+      if (
+        !cachedRect ||
+        // has changed one rect
+        (!isEqualShallow(cachedRect, nodeRect) &&
+          (!cachedParentRect || !isEqualShallow(cachedParentRect, parentRect)))
+      ) {
+        NodeRectCache.set(node, nodeRect)
+        if (parentRect && parentNode) {
+          ParentRectCache.set(parentNode, parentRect)
+        }
+
+        if (avoidUpdates) {
+          // Use sync version for queued updates to avoid promise complications
+          const event = getElementLayoutEvent(node)
+          queuedUpdates.set(node, () => onLayout(event))
+        } else if (strategy === 'async') {
+          // For async strategy, debounce the layout update
+          const now = Date.now()
+          LastChangeTime.set(node, now)
+
+          // Clear existing debounce timer
+          const existingTimer = DebounceTimers.get(node)
+          if (existingTimer) {
+            clearTimeout(existingTimer)
+          }
+
+          // Set new debounce timer
+          const timer = setTimeout(async () => {
+            const lastChange = LastChangeTime.get(node) || 0
+            const timeSinceChange = Date.now() - lastChange
+
+            // Only fire if at least DEBOUNCE_DELAY has passed since last change
+            if (timeSinceChange >= DEBOUNCE_DELAY) {
+              const event = await getElementLayoutEventAsync(node)
+              onLayout(event)
+              DebounceTimers.delete(node)
+            } else {
+              // Reschedule if not enough time has passed
+              const remainingDelay = DEBOUNCE_DELAY - timeSinceChange
+              const newTimer = setTimeout(async () => {
+                const event = await getElementLayoutEventAsync(node)
+                onLayout(event)
+                DebounceTimers.delete(node)
+              }, remainingDelay)
+              DebounceTimers.set(node, newTimer)
+            }
+          }, DEBOUNCE_DELAY)
+
+          DebounceTimers.set(node, timer)
+        } else {
+          // Sync strategy - use sync version
+          const event = getElementLayoutEvent(node)
+          onLayout(event)
+        }
+      }
+    }
+
+    // note that getBoundingClientRect() does not thrash layout if its after an animation frame
+    rAF!(layoutOnAnimationFrame)
+
+    function layoutOnAnimationFrame() {
+      const now = Date.now()
+      const timeSinceLastFrame = now - lastFrameAt
+      lastFrameAt = now
+
+      if (strategy !== 'off') {
+        // avoid updates if we've been dropping frames (indicates sync work happening)
+        const expectedFrameTime = 16.67 // ~60fps
+        const hasRecentSyncWork =
+          timeSinceLastFrame > expectedFrameTime * numDroppedFramesUntilPause
+
+        if (!hasRecentSyncWork) {
+          Nodes.forEach(updateLayoutIfChanged)
+        }
+      }
+      rAF!(layoutOnAnimationFrame)
+    }
+  } else {
+    if (process.env.NODE_ENV === 'development') {
+      console.warn(
+        `No requestAnimationFrame - please polyfill for onLayout to work correctly`
+      )
+    }
+  }
+}
+
+// Sync versions
+export const getElementLayoutEvent = (target: HTMLElement): LayoutEvent => {
+  let res: LayoutEvent | null = null
+  measureLayout(target, null, (x, y, width, height, left, top) => {
+    res = {
+      nativeEvent: {
+        layout: { x, y, width, height, left, top },
+        target,
+      },
+      timeStamp: Date.now(),
+    }
+  })
+  if (!res) {
+    throw new Error(`‼️`) // impossible
+  }
+  return res
+}
+
+export const measureLayout = (
+  node: HTMLElement,
+  relativeTo: HTMLElement | null,
+  callback: (
+    x: number,
+    y: number,
+    width: number,
+    height: number,
+    left: number,
+    top: number
+  ) => void
+): void => {
+  const relativeNode = relativeTo || node?.parentElement
+  if (relativeNode instanceof HTMLElement) {
+    const nodeDim = node.getBoundingClientRect()
+    const relativeNodeDim = relativeNode.getBoundingClientRect()
+
+    if (relativeNodeDim && nodeDim) {
+      const { x, y, width, height, left, top } = getRelativeDimensions(
+        nodeDim,
+        relativeNodeDim
+      )
+      callback(x, y, width, height, left, top)
+    }
+  }
+}
+
+export const getElementLayoutEventAsync = async (
+  target: HTMLElement
+): Promise<LayoutEvent> => {
+  const layout = await measureLayoutAsync(target)
+  if (!layout) {
+    throw new Error(`‼️`) // impossible
+  }
+  return {
+    nativeEvent: {
+      layout,
+      target,
+    },
+    timeStamp: Date.now(),
+  }
+}
+
+export const measureLayoutAsync = async (
+  node: HTMLElement,
+  relativeTo?: HTMLElement | null
+): Promise<null | LayoutValue> => {
+  const relativeNode = relativeTo || node?.parentElement
+  if (relativeNode instanceof HTMLElement) {
+    const [nodeDim, relativeNodeDim] = await Promise.all([
+      node.getBoundingClientRect(),
+      relativeNode.getBoundingClientRect(),
+    ])
+
+    if (relativeNodeDim && nodeDim) {
+      const { x, y, width, height, left, top } = getRelativeDimensions(
+        nodeDim,
+        relativeNodeDim
+      )
+      return { x, y, width, height, left, top }
+    }
+  }
+  return null
+}
+
+const getRelativeDimensions = (a: DOMRectReadOnly, b: DOMRectReadOnly) => {
+  const { height, left, top, width } = a
+  const x = left - b.left
+  const y = top - b.top
+  return { x, y, width, height, left, top }
+}
+
+export function useElementLayout(
+  ref: RefObject<TamaguiComponentStatePartial>,
+  onLayout?: ((e: LayoutEvent) => void) | null
+): void {
+  // ensure always up to date so we can avoid re-running effect
+  const node = ensureWebElement(ref.current?.host)
+  if (node && onLayout) {
+    LayoutHandlers.set(node, onLayout)
+  }
+
+  useIsomorphicLayoutEffect(() => {
+    if (!onLayout) return
+    const node = ref.current?.host
+    if (!node) return
+
+    LayoutHandlers.set(node, onLayout)
+    Nodes.add(node)
+    onLayout(getElementLayoutEvent(node))
+
+    return () => {
+      Nodes.delete(node)
+      LayoutHandlers.delete(node)
+      NodeRectCache.delete(node)
+
+      // Clean up debounce timer and tracking
+      const timer = DebounceTimers.get(node)
+      if (timer) {
+        clearTimeout(timer)
+        DebounceTimers.delete(node)
+      }
+      LastChangeTime.delete(node)
+    }
+  }, [ref, !!onLayout])
+}
+
+function ensureWebElement<X>(x: X): HTMLElement | undefined {
+  if (typeof HTMLElement === 'undefined') {
+    return undefined
+  }
+  return x instanceof HTMLElement ? x : undefined
+}
+
+const getBoundingClientRect = (node: HTMLElement | null): undefined | DOMRect => {
+  if (!node || node.nodeType !== 1) return
+  return node.getBoundingClientRect?.()
+}
+
+export const getRect = (node: HTMLElement): LayoutValue | undefined => {
+  const rect = getBoundingClientRect(node)
+  if (!rect) return
+  const { x, y, top, left } = rect
+  return { x, y, width: node.offsetWidth, height: node.offsetHeight, top, left }
+}

package/types/index.d.ts

@@ -0,0 +1,32 @@
+import type { RefObject } from "react";
+type TamaguiComponentStatePartial = {
+	host?: any;
+};
+type LayoutMeasurementStrategy = "off" | "sync" | "async";
+export declare function setOnLayoutStrategy(state: LayoutMeasurementStrategy): void;
+export type LayoutValue = {
+	x: number;
+	y: number;
+	width: number;
+	height: number;
+	left: number;
+	top: number;
+};
+export type LayoutEvent = {
+	nativeEvent: {
+		layout: LayoutValue;
+		target: any;
+	};
+	timeStamp: number;
+};
+export declare function enable(): void;
+// Sync versions
+export declare const getElementLayoutEvent: (target: HTMLElement) => LayoutEvent;
+export declare const measureLayout: (node: HTMLElement, relativeTo: HTMLElement | null, callback: (x: number, y: number, width: number, height: number, left: number, top: number) => void) => void;
+export declare const getElementLayoutEventAsync: (target: HTMLElement) => Promise<LayoutEvent>;
+export declare const measureLayoutAsync: (node: HTMLElement, relativeTo?: HTMLElement | null) => Promise<null | LayoutValue>;
+export declare function useElementLayout(ref: RefObject<TamaguiComponentStatePartial>, onLayout?: ((e: LayoutEvent) => void) | null): void;
+export declare const getRect: (node: HTMLElement) => LayoutValue | undefined;
+export {};
+
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1,27 @@
+{
+  "mappings": "AAEA,cAAc,iBAAiB,OAAO;KAKjC,+BAA+B;CAClC;AACD;KAEI,4BAA4B,QAAQ,SAAS;AAIlD,OAAO,iBAAS,oBAAoBA,OAAO;AAI3C,YAAY,cAAc;CACxB;CACA;CACA;CACA;CACA;CACA;AACD;AAED,YAAY,cAAc;CACxB,aAAa;EACX,QAAQ;EACR;CACD;CACD;AACD;AAcD,OAAO,iBAAS;;AAkHhB,OAAO,cAAM,wBAAyBC,QAAQ,gBAAc;AAiB5D,OAAO,cAAM,gBACXC,MAAM,aACNC,YAAY,oBACZC,WACEC,WACAC,WACAC,eACAC,gBACAC,cACAC;AAkBJ,OAAO,cAAM,6BACXT,QAAQ,gBACP,QAAQ;AAcX,OAAO,cAAM,qBACXC,MAAM,aACNS,aAAa,uBACZ,eAAe;AA0BlB,OAAO,iBAAS,iBACdC,KAAK,UAAU,+BACfC,aAAaC,GAAG;AA6ClB,OAAO,cAAM,UAAWZ,MAAM,gBAAc",
+  "names": [
+    "state: LayoutMeasurementStrategy",
+    "target: HTMLElement",
+    "node: HTMLElement",
+    "relativeTo: HTMLElement | null",
+    "callback: (\n    x: number,\n    y: number,\n    width: number,\n    height: number,\n    left: number,\n    top: number\n  ) => void",
+    "x: number",
+    "y: number",
+    "width: number",
+    "height: number",
+    "left: number",
+    "top: number",
+    "relativeTo?: HTMLElement | null",
+    "ref: RefObject<TamaguiComponentStatePartial>",
+    "onLayout?: ((e: LayoutEvent) => void) | null",
+    "e: LayoutEvent"
+  ],
+  "sources": [
+    "src/index.ts"
+  ],
+  "sourcesContent": [
+    "import { isClient, useIsomorphicLayoutEffect } from '@tamagui/constants'\nimport { isEqualShallow } from '@tamagui/is-equal-shallow'\nimport type { RefObject } from 'react'\n\nconst LayoutHandlers = new WeakMap<HTMLElement, Function>()\nconst Nodes = new Set<HTMLElement>()\n\ntype TamaguiComponentStatePartial = {\n  host?: any\n}\n\ntype LayoutMeasurementStrategy = 'off' | 'sync' | 'async'\n\nlet strategy: LayoutMeasurementStrategy = 'async'\n\nexport function setOnLayoutStrategy(state: LayoutMeasurementStrategy): void {\n  strategy = state\n}\n\nexport type LayoutValue = {\n  x: number\n  y: number\n  width: number\n  height: number\n  left: number\n  top: number\n}\n\nexport type LayoutEvent = {\n  nativeEvent: {\n    layout: LayoutValue\n    target: any\n  }\n  timeStamp: number\n}\n\nconst NodeRectCache = new WeakMap<HTMLElement, DOMRect>()\nconst ParentRectCache = new WeakMap<HTMLElement, DOMRect>()\nconst DebounceTimers = new WeakMap<HTMLElement, NodeJS.Timeout>()\nconst LastChangeTime = new WeakMap<HTMLElement, number>()\n\nconst rAF = typeof window !== 'undefined' ? window.requestAnimationFrame : undefined\nconst DEBOUNCE_DELAY = 32 // 32ms debounce (2 frames at 60fps)\n\n// prevent thrashing during first hydration (somewhat, streaming gets trickier)\nlet avoidUpdates = true\nconst queuedUpdates = new Map<HTMLElement, Function>()\n\nexport function enable(): void {\n  if (avoidUpdates) {\n    avoidUpdates = false\n    if (queuedUpdates) {\n      queuedUpdates.forEach((cb) => cb())\n      queuedUpdates.clear()\n    }\n  }\n}\n\nif (isClient) {\n  if (rAF) {\n    // track frame timing to detect sync work and avoid updates during heavy periods\n    let lastFrameAt = Date.now()\n    const numDroppedFramesUntilPause = 2 // adjust sensitivity\n\n    async function updateLayoutIfChanged(node: HTMLElement) {\n      const nodeRect = node.getBoundingClientRect()\n      const parentNode = node.parentElement\n      const parentRect = parentNode?.getBoundingClientRect()\n\n      const onLayout = LayoutHandlers.get(node)\n      if (typeof onLayout !== 'function') return\n\n      const cachedRect = NodeRectCache.get(node)\n      const cachedParentRect = parentNode ? NodeRectCache.get(parentNode) : null\n\n      if (\n        !cachedRect ||\n        // has changed one rect\n        (!isEqualShallow(cachedRect, nodeRect) &&\n          (!cachedParentRect || !isEqualShallow(cachedParentRect, parentRect)))\n      ) {\n        NodeRectCache.set(node, nodeRect)\n        if (parentRect && parentNode) {\n          ParentRectCache.set(parentNode, parentRect)\n        }\n\n        if (avoidUpdates) {\n          // Use sync version for queued updates to avoid promise complications\n          const event = getElementLayoutEvent(node)\n          queuedUpdates.set(node, () => onLayout(event))\n        } else if (strategy === 'async') {\n          // For async strategy, debounce the layout update\n          const now = Date.now()\n          LastChangeTime.set(node, now)\n\n          // Clear existing debounce timer\n          const existingTimer = DebounceTimers.get(node)\n          if (existingTimer) {\n            clearTimeout(existingTimer)\n          }\n\n          // Set new debounce timer\n          const timer = setTimeout(async () => {\n            const lastChange = LastChangeTime.get(node) || 0\n            const timeSinceChange = Date.now() - lastChange\n\n            // Only fire if at least DEBOUNCE_DELAY has passed since last change\n            if (timeSinceChange >= DEBOUNCE_DELAY) {\n              const event = await getElementLayoutEventAsync(node)\n              onLayout(event)\n              DebounceTimers.delete(node)\n            } else {\n              // Reschedule if not enough time has passed\n              const remainingDelay = DEBOUNCE_DELAY - timeSinceChange\n              const newTimer = setTimeout(async () => {\n                const event = await getElementLayoutEventAsync(node)\n                onLayout(event)\n                DebounceTimers.delete(node)\n              }, remainingDelay)\n              DebounceTimers.set(node, newTimer)\n            }\n          }, DEBOUNCE_DELAY)\n\n          DebounceTimers.set(node, timer)\n        } else {\n          // Sync strategy - use sync version\n          const event = getElementLayoutEvent(node)\n          onLayout(event)\n        }\n      }\n    }\n\n    // note that getBoundingClientRect() does not thrash layout if its after an animation frame\n    rAF!(layoutOnAnimationFrame)\n\n    function layoutOnAnimationFrame() {\n      const now = Date.now()\n      const timeSinceLastFrame = now - lastFrameAt\n      lastFrameAt = now\n\n      if (strategy !== 'off') {\n        // avoid updates if we've been dropping frames (indicates sync work happening)\n        const expectedFrameTime = 16.67 // ~60fps\n        const hasRecentSyncWork =\n          timeSinceLastFrame > expectedFrameTime * numDroppedFramesUntilPause\n\n        if (!hasRecentSyncWork) {\n          Nodes.forEach(updateLayoutIfChanged)\n        }\n      }\n      rAF!(layoutOnAnimationFrame)\n    }\n  } else {\n    if (process.env.NODE_ENV === 'development') {\n      console.warn(\n        `No requestAnimationFrame - please polyfill for onLayout to work correctly`\n      )\n    }\n  }\n}\n\n// Sync versions\nexport const getElementLayoutEvent = (target: HTMLElement): LayoutEvent => {\n  let res: LayoutEvent | null = null\n  measureLayout(target, null, (x, y, width, height, left, top) => {\n    res = {\n      nativeEvent: {\n        layout: { x, y, width, height, left, top },\n        target,\n      },\n      timeStamp: Date.now(),\n    }\n  })\n  if (!res) {\n    throw new Error(`‼️`) // impossible\n  }\n  return res\n}\n\nexport const measureLayout = (\n  node: HTMLElement,\n  relativeTo: HTMLElement | null,\n  callback: (\n    x: number,\n    y: number,\n    width: number,\n    height: number,\n    left: number,\n    top: number\n  ) => void\n): void => {\n  const relativeNode = relativeTo || node?.parentElement\n  if (relativeNode instanceof HTMLElement) {\n    const nodeDim = node.getBoundingClientRect()\n    const relativeNodeDim = relativeNode.getBoundingClientRect()\n\n    if (relativeNodeDim && nodeDim) {\n      const { x, y, width, height, left, top } = getRelativeDimensions(\n        nodeDim,\n        relativeNodeDim\n      )\n      callback(x, y, width, height, left, top)\n    }\n  }\n}\n\nexport const getElementLayoutEventAsync = async (\n  target: HTMLElement\n): Promise<LayoutEvent> => {\n  const layout = await measureLayoutAsync(target)\n  if (!layout) {\n    throw new Error(`‼️`) // impossible\n  }\n  return {\n    nativeEvent: {\n      layout,\n      target,\n    },\n    timeStamp: Date.now(),\n  }\n}\n\nexport const measureLayoutAsync = async (\n  node: HTMLElement,\n  relativeTo?: HTMLElement | null\n): Promise<null | LayoutValue> => {\n  const relativeNode = relativeTo || node?.parentElement\n  if (relativeNode instanceof HTMLElement) {\n    const [nodeDim, relativeNodeDim] = await Promise.all([\n      node.getBoundingClientRect(),\n      relativeNode.getBoundingClientRect(),\n    ])\n\n    if (relativeNodeDim && nodeDim) {\n      const { x, y, width, height, left, top } = getRelativeDimensions(\n        nodeDim,\n        relativeNodeDim\n      )\n      return { x, y, width, height, left, top }\n    }\n  }\n  return null\n}\n\nconst getRelativeDimensions = (a: DOMRectReadOnly, b: DOMRectReadOnly) => {\n  const { height, left, top, width } = a\n  const x = left - b.left\n  const y = top - b.top\n  return { x, y, width, height, left, top }\n}\n\nexport function useElementLayout(\n  ref: RefObject<TamaguiComponentStatePartial>,\n  onLayout?: ((e: LayoutEvent) => void) | null\n): void {\n  // ensure always up to date so we can avoid re-running effect\n  const node = ensureWebElement(ref.current?.host)\n  if (node && onLayout) {\n    LayoutHandlers.set(node, onLayout)\n  }\n\n  useIsomorphicLayoutEffect(() => {\n    if (!onLayout) return\n    const node = ref.current?.host\n    if (!node) return\n\n    LayoutHandlers.set(node, onLayout)\n    Nodes.add(node)\n    onLayout(getElementLayoutEvent(node))\n\n    return () => {\n      Nodes.delete(node)\n      LayoutHandlers.delete(node)\n      NodeRectCache.delete(node)\n\n      // Clean up debounce timer and tracking\n      const timer = DebounceTimers.get(node)\n      if (timer) {\n        clearTimeout(timer)\n        DebounceTimers.delete(node)\n      }\n      LastChangeTime.delete(node)\n    }\n  }, [ref, !!onLayout])\n}\n\nfunction ensureWebElement<X>(x: X): HTMLElement | undefined {\n  if (typeof HTMLElement === 'undefined') {\n    return undefined\n  }\n  return x instanceof HTMLElement ? x : undefined\n}\n\nconst getBoundingClientRect = (node: HTMLElement | null): undefined | DOMRect => {\n  if (!node || node.nodeType !== 1) return\n  return node.getBoundingClientRect?.()\n}\n\nexport const getRect = (node: HTMLElement): LayoutValue | undefined => {\n  const rect = getBoundingClientRect(node)\n  if (!rect) return\n  const { x, y, top, left } = rect\n  return { x, y, width: node.offsetWidth, height: node.offsetHeight, top, left }\n}\n"
+  ],
+  "version": 3
+}