@contember/react-utils 1.2.0-alpha.0 → 1.2.0-alpha.1

package/src/hooks/useCountLayoutSlotChildren.ts

@@ -0,0 +1,46 @@
+import { useLayoutEffect, useRef, useState } from 'react'
+import { RefObjectOrElement, unwrapRefValue } from './unwrapRefValue'
+import { useOnElementMutation } from './useOnElementMutation'
+
+// TODO: Remove when Firefox supports :has selector, e.g.
+// when selectors like `:has(:not(.layout-slot:empty))` work
+// or below issue can be solved more easily:
+//
+// ISSUE:
+// Targeting containers that are visibly empty and hide them
+// or remove paddings without support for :has() is tedious.
+/** @deprecated Check support for :has() for Firefox before using.  */
+export function useCountLayoutSlotChildren(
+	refOrElement: RefObjectOrElement<HTMLElement | undefined>,
+	selector: string = '.layout-slot',
+) {
+	const [count, setCount] = useState(Infinity)
+
+	const countChildren = useRef((element: HTMLElement | null | undefined) => {
+		if (element) {
+			setCount(element.querySelectorAll(`${selector} > *`).length)
+		}
+	})
+
+	useOnElementMutation(refOrElement, () => {
+		countChildren.current(unwrapRefValue(refOrElement))
+	}, { attributes: true, childList: true, subtree: true })
+
+	useLayoutEffect(() => {
+		countChildren.current(unwrapRefValue(refOrElement))
+	})
+
+	return count
+}
+
+export function useHasEmptySlotsClassName(
+	refOrElement: RefObjectOrElement<HTMLElement | undefined>,
+) {
+	const slotChildrenCount = useCountLayoutSlotChildren(refOrElement)
+
+	if (slotChildrenCount === 0) {
+		return 'has-empty-slots'
+	} else {
+		return 'has-non-empty-slots'
+	}
+}

package/src/hooks/useElementSize.ts

@@ -0,0 +1,73 @@
+import { getSizeFromResizeObserverEntryFactory } from '@contember/utilities'
+import { useLayoutEffect, useMemo, useRef, useState } from 'react'
+import { useScopedConsoleRef } from '../debug-context'
+import { RefObjectOrElement, unwrapRefValue } from './unwrapRefValue'
+import { useOnElementResize } from './useOnElementResize'
+
+function getElementWidth(element: HTMLElement) {
+	return element.offsetWidth
+}
+
+function getElementHeight(element: HTMLElement) {
+	return element.offsetHeight
+}
+
+/**
+ * Measure HTMLElement
+ *
+ * @param refOrElement - HTMLElement passed directly or indirectly as RefObject
+ * @returns Size vector consisting of width and height properties
+ */
+export function useElementSize(
+	refOrElement: RefObjectOrElement<HTMLElement>,
+	options: ResizeObserverOptions = {},
+	timeout: number = 300,
+): { height: number | undefined, width: number | undefined } {
+	const { logged } = useScopedConsoleRef('useElementSize').current
+
+	const { box = 'border-box' } = options
+	const getSizeFromResizeObserverEntry = useMemo(() => getSizeFromResizeObserverEntryFactory(box), [box])
+
+	const refValue = unwrapRefValue(refOrElement)
+	const [width, setWidth] = useState<number | undefined>(refValue?.offsetWidth)
+	const [height, setHeight] = useState<number | undefined>(refValue?.offsetHeight)
+
+	logged('dimensions', { width, height })
+
+	useOnElementResize(refOrElement, entry => {
+		const dimensions = logged('useOnElementResize => entry:dimensions', getSizeFromResizeObserverEntry(entry))
+
+		if (width !== dimensions.width) {
+			setWidth(dimensions.width)
+		}
+		if (height !== dimensions.height) {
+			setHeight(dimensions.height)
+		}
+	}, { box }, timeout)
+
+	// INTENTIONAL AVOID OF ESLint ERROR: We need measure on every Layout side-effect
+	// otherwise the browser will paint and cause layout shifts.
+	//
+	// React Hook useLayoutEffect contains a call to 'setWidth'. Without a list of dependencies,
+	// this can lead to an infinite chain of updates. To fix this, pass [element] as a second argument
+	// to the useLayoutEffect Hook.
+	//
+	// Seems like only pure function lets us measure before the browser has a chance to paint
+	const measure = useRef((element: HTMLElement | null) => {
+		logged('measure(element)', element)
+
+		if (element instanceof HTMLElement) {
+			setWidth(logged('getElementWidth(element):', getElementWidth(element)))
+			setHeight(logged('getElementHeight(element):', getElementHeight(element)))
+		} else if (element) {
+			throw new Error('Exhaustive error: Expecting element to be instance of HTMLElement or Window')
+		}
+	})
+
+	useLayoutEffect(() => {
+		const element = unwrapRefValue(refOrElement)
+		logged('useLayoutEffect => measure', measure.current(element))
+	})
+
+	return { height, width }
+}

package/src/hooks/useEventHandler.ts

@@ -0,0 +1,24 @@
+import { EventHandler, SyntheticEvent, useEffect, useRef } from 'react'
+
+/**
+ * Similar to useEvent with inferred type for the event parameter according to event type
+ *
+ * @param type - String, keyof DocumentEventMap, e.g. 'click', 'keydown',...
+ * @param callback - EventHandler
+ * @returns Stable reference callback
+ */
+export function useEventHandler<E extends SyntheticEvent<any>>(type: E['type'], callback: EventHandler<E>): EventHandler<E> {
+	const callbackRef = useRef(callback); callbackRef.current = callback
+
+	const stableHandler = useRef(function (event: any) {
+		return callbackRef.current(event)
+	}).current
+
+	useEffect(() => {
+		return () => {
+			callbackRef.current = () => { }
+		}
+	}, [])
+
+	return stableHandler
+}

package/src/hooks/useExpectSameValueReference.ts

@@ -0,0 +1,26 @@
+import deepEqual from 'deep-equal'
+import { useRef } from 'react'
+
+// TODO: Unify error behavior with useConstantValueInvariant() and maybe merge into one hook.
+export function useExpectSameValueReference<T>(next: T, shouldThrow: boolean = false) {
+	const previous = useRef(next)
+
+	if (next !== previous.current
+		&& typeof next === 'object'
+		&& typeof previous.current === 'object'
+		&& deepEqual(next, previous.current)
+	) {
+		if (import.meta.env.DEV) {
+			console.error('Previous and next next do not match in reference although match in value', {
+				previous: previous.current,
+				next,
+			})
+		}
+
+		if (shouldThrow) {
+			throw new Error('Expecting same reference for same values')
+		}
+	}
+
+	previous.current = next
+}

package/src/hooks/useOnElementMutation.ts

@@ -0,0 +1,42 @@
+import deepEqual from 'deep-equal'
+import { useEffect, useLayoutEffect, useRef, useState } from 'react'
+import { useScopedConsoleRef } from '../debug-context'
+import { RefObjectOrElement, unwrapRefValue } from './unwrapRefValue'
+
+export function useOnElementMutation(
+	refOrElement: RefObjectOrElement<HTMLElement | undefined>,
+	callback: MutationCallback,
+	options: MutationObserverInit = { attributes: true, childList: true, subtree: true },
+) {
+	const scopedConsoleRef = useScopedConsoleRef('useOnElementMutation')
+
+	const callbackRef = useRef(callback); callbackRef.current = callback
+	const optionsRef = useRef<MutationObserverInit>(options); optionsRef.current = options
+
+	const [optionsState, setOptionsState] = useState<MutationObserverInit>(options)
+
+	useEffect(() => {
+		if (!deepEqual(optionsRef.current, options)) {
+			setOptionsState(options)
+		}
+	}, [options])
+
+	useLayoutEffect(() => {
+		const element = unwrapRefValue(refOrElement)
+
+		if (element) {
+			function handler(mutations: MutationRecord[], observer: MutationObserver) {
+				scopedConsoleRef.current.logged('element.mutations', mutations)
+				callbackRef.current(mutations, observer)
+			}
+
+			const observer = new MutationObserver(handler)
+
+			observer.observe(element, optionsState)
+
+			return () => {
+				observer.disconnect()
+			}
+		}
+	}, [optionsState, refOrElement, scopedConsoleRef])
+}

package/src/hooks/useOnElementResize.ts

@@ -0,0 +1,52 @@
+import { useLayoutEffect, useRef } from 'react'
+import { useScopedConsoleRef } from '../debug-context'
+import { RefObjectOrElement, unwrapRefValue } from './unwrapRefValue'
+
+export function useOnElementResize(
+	refOrElement: RefObjectOrElement<HTMLElement | null> | null,
+	callback: (entries: ResizeObserverEntry) => void,
+	options: ResizeObserverOptions = {},
+	timeout: number = 300,
+): void {
+	const scopedConsoleRef = useScopedConsoleRef('useOnElementResize')
+
+	const { box = 'border-box' } = options
+	const element = unwrapRefValue(refOrElement)
+	const callbackRef = useRef(callback); callbackRef.current = callback
+	const lastTimeStamp = useRef<number>(0)
+
+	useLayoutEffect(() => {
+		let timeoutID: number | undefined = undefined
+
+		function debouncedOnChange([entry]: ResizeObserverEntry[]) {
+			const timeStamp = Date.now()
+			const delta = timeStamp - lastTimeStamp.current
+
+			if (delta > timeout) {
+				scopedConsoleRef.current.warned('element.resize:immediate', null)
+				callbackRef.current(entry)
+				lastTimeStamp.current = timeStamp
+			} else {
+				clearTimeout(timeoutID)
+				timeoutID = setTimeout(() => {
+					scopedConsoleRef.current.warned('element.resize:debounced', null)
+					callbackRef.current(entry)
+					lastTimeStamp.current = timeStamp
+				}, timeout)
+			}
+		}
+
+		if (element instanceof HTMLElement) {
+			const resizeObserver = new ResizeObserver(debouncedOnChange)
+
+			resizeObserver.observe(element, { box })
+
+			return () => {
+				clearTimeout(timeoutID)
+				resizeObserver.unobserve(element)
+			}
+		} else if (element) {
+			throw new Error('Exhaustive error: Expecting element to be instance of HTMLElement')
+		}
+	}, [box, element, scopedConsoleRef, timeout])
+}

package/src/hooks/useOnScrollWithin.ts

@@ -0,0 +1,67 @@
+import { useLayoutEffect, useRef } from 'react'
+import { useScopedConsoleRef } from '../debug-context'
+import { RefObjectOrElement, unwrapRefValue } from './unwrapRefValue'
+
+/**
+ * Invokes callback on scroll event within the scroll container
+ *
+ * @param refOrElement - Scroll container
+ * @param callback - Callback that is invoked on scroll event
+ * @param interval - Specifies how often should scroll event invoke callback
+ */
+export function useOnScrollWithin(
+	refOrElement: RefObjectOrElement<HTMLElement | null> | null,
+	callback: (event: Event) => void,
+	interval: number = 1000 / 60,
+) {
+	const scopedConsoleRef = useScopedConsoleRef('useOnScrollWithin')
+
+	const callbackRef = useRef(callback); callbackRef.current = callback
+	const lastTimeStamp = useRef<number>(0)
+
+	const element = unwrapRefValue(refOrElement)
+
+	useLayoutEffect(() => {
+		let timeoutID: number | undefined = undefined
+
+		function debouncedHandler(event: Event) {
+			clearTimeout(timeoutID)
+
+			const delta = event.timeStamp - lastTimeStamp.current
+			scopedConsoleRef.current.logged('event:element.scroll:delta', delta)
+
+			if (delta > interval) {
+				scopedConsoleRef.current.warned('event:element.scroll:immediately', event)
+				callbackRef.current(event)
+				lastTimeStamp.current = event.timeStamp
+			} else {
+				timeoutID = setTimeout(() => {
+					scopedConsoleRef.current.warned('event:element.scroll:debounced', event)
+					lastTimeStamp.current = event.timeStamp
+					callbackRef.current(event)
+				}, interval)
+			}
+		}
+
+		if (element && element instanceof HTMLElement) {
+			if (element instanceof HTMLBodyElement || element instanceof HTMLHtmlElement) {
+				window.addEventListener('scroll', debouncedHandler, { capture: true, passive: true })
+				window.addEventListener('resize', debouncedHandler)
+
+				return () => {
+					window.removeEventListener('scroll', debouncedHandler)
+					window.removeEventListener('resize', debouncedHandler)
+				}
+			} else {
+				element.addEventListener('scroll', debouncedHandler, { passive: true, capture: true })
+
+				return () => {
+					element.removeEventListener('scroll', debouncedHandler)
+				}
+			}
+		} else if (element) {
+			throw new Error('Exhaustive error: Expecting element to be instance of HTMLElement')
+		}
+
+	}, [element, interval, scopedConsoleRef])
+}

package/src/hooks/useOnWindowResize.ts

@@ -0,0 +1,42 @@
+import { useLayoutEffect, useRef } from 'react'
+import { useScopedConsoleRef } from '../debug-context'
+
+export function useOnWindowResize(
+	callback: (event: Event) => void,
+	interval: number = 300,
+) {
+	const scopedConsoleRef = useScopedConsoleRef('useOnWindowResize')
+
+	const callbackRef = useRef(callback); callbackRef.current = callback
+	const lastTimeStamp = useRef<number>(0)
+
+	useLayoutEffect(() => {
+		let timeoutID: number | undefined = undefined
+
+		function debouncedHandler(event: Event) {
+			clearTimeout(timeoutID)
+
+			const delta = event.timeStamp - lastTimeStamp.current
+			scopedConsoleRef.current.logged('window.resize:delta', delta)
+
+			if (delta > interval) {
+				scopedConsoleRef.current.warned('event:window.resize:immediately', null)
+				callbackRef.current(event)
+				lastTimeStamp.current = event.timeStamp
+			} else {
+				timeoutID = setTimeout(() => {
+					scopedConsoleRef.current.warned('event:window.resize:debounced', null)
+					lastTimeStamp.current = event.timeStamp
+					callbackRef.current(event)
+				}, interval)
+			}
+		}
+
+		window.addEventListener('resize', debouncedHandler)
+
+		return () => {
+			clearTimeout(timeoutID)
+			window.removeEventListener('resize', debouncedHandler)
+		}
+	}, [callbackRef, interval, scopedConsoleRef])
+}

package/src/hooks/useScrollOffsets.ts

@@ -0,0 +1,88 @@
+import { assert } from '@contember/utilities'
+import { useLayoutEffect, useMemo, useState } from 'react'
+import { useScopedConsoleRef } from '../debug-context'
+import { useReferentiallyStableCallback } from '../referentiallyStable'
+import { RefObjectOrElement, unwrapRefValue } from './unwrapRefValue'
+import { useOnScrollWithin } from './useOnScrollWithin'
+import { useOnWindowResize } from './useOnWindowResize'
+
+export type Offsets = {
+	bottom: number;
+	left: number;
+	right: number;
+	top: number;
+}
+
+export function useScrollOffsets(refOrElement: RefObjectOrElement<HTMLElement | null> | null, interval: number = 1000 / 60) {
+	const { logged } = useScopedConsoleRef('useScrollOffsets').current
+
+	const [top, setTop] = useState(0)
+	const [bottom, setBottom] = useState(0)
+	const [left, setLeft] = useState(0)
+	const [right, setRight] = useState(0)
+
+	const updateScrollOffsetsState = useReferentiallyStableCallback((offsets: Offsets) => {
+		logged('Update the offsets:', {
+			previous: { bottom, left, right, top },
+			next: offsets,
+		})
+
+		if (offsets.bottom !== bottom) setBottom(offsets.bottom)
+		if (offsets.left !== left) setLeft(offsets.left)
+		if (offsets.right !== right) setRight(offsets.right)
+		if (offsets.top !== top) setTop(offsets.top)
+	})
+
+	const handler = useReferentiallyStableCallback(() => {
+		const maybeScrollContent = unwrapRefValue(refOrElement) ?? document
+
+		if (maybeScrollContent) {
+			updateScrollOffsetsState(
+				getElementScrollOffsets(maybeScrollContent),
+			)
+		}
+	})
+
+	useOnScrollWithin(refOrElement, handler, interval)
+	useOnWindowResize(handler)
+	useLayoutEffect(handler, [handler])
+
+	return useMemo(() => ({ bottom, left, right, top }), [bottom, left, right, top])
+}
+
+function isIntrinsicScrollElement(element: unknown): element is Document {
+	return element instanceof HTMLBodyElement
+		|| element instanceof HTMLHtmlElement
+		|| element instanceof DocumentType
+		|| element instanceof Document
+		|| element instanceof HTMLDocument
+}
+
+function getIntrinsicScrollContainer(element: HTMLElement | Document): HTMLElement {
+	const html = document.body.parentElement
+	assert('HTML element exists', html, (value): value is HTMLElement => value instanceof HTMLElement)
+
+	if (isIntrinsicScrollElement(element)) {
+		return html
+	} else {
+		return element
+	}
+}
+
+function getElementScrollOffsets(element: HTMLElement | Document): Offsets {
+	const isIntrinsicScrolling = isIntrinsicScrollElement(element)
+	const scrollContainer = getIntrinsicScrollContainer(element)
+
+	const { scrollLeft, scrollTop, scrollHeight, scrollWidth } = scrollContainer
+
+	const height = isIntrinsicScrolling ? window.innerHeight : scrollContainer.offsetHeight
+	const width = isIntrinsicScrolling ? window.innerWidth : scrollContainer.offsetWidth
+
+	const left = Math.round(scrollLeft)
+	const top = Math.round(scrollTop)
+
+	const right = Math.round(scrollWidth - width - left)
+	const bottom = Math.round(scrollHeight - height - top)
+
+	return { bottom, left, right, top }
+}

package/src/hooks/useStoredState.ts

@@ -1,8 +1,8 @@
 import { useCallback, useState } from 'react'
 import { Serializable } from '../types'
 
-type SetState<V extends Serializable> = (value: V | ((current: V) => V)) => void;
-type ValueInitializer<V extends Serializable> = (storedValue: V | undefined) => V;
+export type SetState<V extends Serializable> = (value: V | ((current: V) => V)) => void;
+export type ValueInitializer<V extends Serializable> = (storedValue: V | undefined) => V;
 
 const createStoredStateHook = (getStorage: () => Storage) => {
 	return <V extends Serializable>(key: string, initializeValue: ValueInitializer<V>): [V, SetState<V>] => {

package/src/hooks/useUpdatedRef.ts

@@ -0,0 +1,14 @@
+import { useRef } from 'react'
+
+/**
+ * Returns a stable mutable object with value that is updated upon each call
+ *
+ * @param value - Value that could update after initial call
+ * @returns Mutable ref object with updated value
+ */
+export function useUpdatedRef<T>(value: T) {
+	const ref = useRef(value)
+	ref.current = value
+
+	return ref
+}

package/src/hooks/useWindowSize.ts

@@ -0,0 +1,20 @@
+import { useMemo, useState } from 'react'
+import { useOnWindowResize } from './useOnWindowResize'
+
+export function useWindowSize() {
+  const [width, setWidth] = useState(window.innerWidth)
+  const [height, setHeight] = useState(window.innerHeight)
+
+  useOnWindowResize(() => {
+    const { innerHeight, innerWidth } = window
+    if (innerHeight !== height) {
+      setHeight(innerHeight)
+    }
+
+    if (innerWidth !== width) {
+      setWidth(innerWidth)
+    }
+  })
+
+  return useMemo(() => ({ height, width }), [height, width])
+}

package/src/index.ts

@@ -1,3 +1,5 @@
+export * from './context'
+export * from './debug-context'
 export * from './hooks'
 export * from './referentiallyStable'
 export * from './types'

package/src/tsconfig.json

@@ -2,5 +2,8 @@
 	"extends": "../../../tsconfig.settings.json",
 	"compilerOptions": {
 		"outDir": "../dist/types"
-	}
+	},
+	"references": [
+		{ "path": "../../utilities/src" },
+	]
 }

package/src/types/PropsWithRequiredChildren.ts

@@ -0,0 +1,3 @@
+import { ReactNode } from 'react'
+
+export type PropsWithRequiredChildren<P = unknown> = P & { children: ReactNode | undefined };

package/src/types/index.ts

@@ -0,0 +1,2 @@
+export * from './PropsWithRequiredChildren'
+export * from './Serializable'

package/dist/types/types.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GACrB,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,YAAY,EAAE,GACvB;IAAE,QAAQ,EAAE,CAAC,IAAI,MAAM,CAAC,CAAC,EAAE,YAAY;CAAE,CAAA"}