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

package/src/debug-context/Constants.ts

@@ -0,0 +1,22 @@
+import type { ScopedConsoleContextType } from './Types'
+
+export function noopLog(...parameters: any[]) { }
+
+export function noopLogged<T>(message: string, value: T): T {
+	return value
+}
+
+export const noopScopedConsole: ScopedConsoleContextType = Object.freeze({
+	log: noopLog,
+	logged: noopLogged,
+	warn: noopLog,
+	warned: noopLogged,
+	error: noopLog,
+	errored: noopLogged,
+	trace: noopLog,
+	traced: noopLogged,
+})
+
+export function isNoopScopedConsole(value: unknown): boolean {
+	return value === noopScopedConsole
+}

package/src/debug-context/Context.tsx

@@ -0,0 +1,82 @@
+import { assert, isNonEmptyString } from '@contember/utilities'
+import { ReactNode, createContext, memo, useContext, useMemo, useRef } from 'react'
+import { isNoopScopedConsole, noopScopedConsole } from './Constants'
+import { ScopedConsoleContextType } from './Types'
+
+function createPrefixedConsole(message: string, prefixedConsole?: ScopedConsoleContextType): ScopedConsoleContextType {
+	return {
+		error: function error(...parameters: any[]) {
+			(prefixedConsole ?? console).error(message, ...parameters)
+		},
+		errored: function errored<T>(message: string, value: T): T {
+			(prefixedConsole ?? console).error(message, value)
+			return value
+		},
+		log: function log(...parameters: any[]) {
+			(prefixedConsole ?? console).log(message, ...parameters)
+		},
+		logged: function logged<T>(message: string, value: T): T {
+			(prefixedConsole ?? console).log(message, value)
+			return value
+		},
+		trace: function trace(...parameters: any[]) {
+			(prefixedConsole ?? console).trace(message, ...parameters)
+		},
+		traced: function traced<T>(message: string, value: T): T {
+			(prefixedConsole ?? console).trace(message, value)
+			return value
+		},
+		warn: function warn(...parameters: any[]) {
+			(prefixedConsole ?? console).warn(message, ...parameters)
+		},
+		warned: function warned<T>(message: string, value: T): T {
+			(prefixedConsole ?? console).warn(message, value)
+			return value
+		},
+	}
+}
+
+export const ScopedConsoleContext = createContext<ScopedConsoleContextType>(null!)
+ScopedConsoleContext.displayName = 'ScopedConsoleContext'
+
+function parentScopedConsoleOrNone(parentConsole: ScopedConsoleContextType): ScopedConsoleContextType | undefined {
+	return isNoopScopedConsole(parentConsole) ? undefined : parentConsole
+}
+
+export const useScopedConsoleRef = (prefix: string) => {
+	assert('prefix is non-empty string', prefix, isNonEmptyString)
+
+	const parentConsole = parentScopedConsoleOrNone(useContext(ScopedConsoleContext))
+
+	const scopedConsole = useMemo(() => {
+		if (parentConsole) {
+			return createPrefixedConsole(prefix, parentConsole)
+		} else {
+			return noopScopedConsole
+		}
+	}, [parentConsole, prefix])
+
+	const ref = useRef(scopedConsole)
+	ref.current = scopedConsole
+
+	return ref
+}
+
+export type DebugChildrenProps =
+	| { active: true; children: ReactNode; id: string; }
+	| { active?: false; children: ReactNode; id?: string; }
+
+export const DebugChildren = memo<DebugChildrenProps>(({ active = true, children, id }) => {
+	const parentScopedConsole = parentScopedConsoleOrNone(useContext(ScopedConsoleContext))
+
+	const console = active && id
+		? createPrefixedConsole(id, parentScopedConsole)
+		: noopScopedConsole
+
+	return (
+		<ScopedConsoleContext.Provider value={active ? console : noopScopedConsole}>
+			{children}
+		</ScopedConsoleContext.Provider>
+	)
+})
+DebugChildren.displayName = 'DebugChildren'

package/src/debug-context/Types.ts

@@ -0,0 +1,13 @@
+export type DebugMethod = (...parameters: any[]) => void
+export type ResultDebuggedMethod = <T>(message: string, value: T) => T
+
+export type ScopedConsoleContextType = {
+	log: DebugMethod;
+	logged: ResultDebuggedMethod,
+	warn: DebugMethod;
+	warned: ResultDebuggedMethod,
+	error: DebugMethod;
+	errored: ResultDebuggedMethod,
+	trace: DebugMethod;
+	traced: ResultDebuggedMethod,
+}

package/src/debug-context/index.ts

@@ -0,0 +1,3 @@
+export * from './Constants'
+export * from './Context'
+export * from './Types'

package/src/hooks/index.ts

@@ -1,11 +1,24 @@
+export * from './unwrapRefValue'
 export * from './useAbortController'
+export * from './useAddClassNameDuringResize'
 export * from './useArrayMapMemo'
+export * from './useComposeRef'
 export * from './useConstantLengthInvariant'
 export * from './useConstantValueInvariant'
+export * from './useCountLayoutSlotChildren'
 export * from './useDebounce'
 export * from './useDebounceCallback'
+export * from './useElementSize'
+export * from './useEventHandler'
+export * from './useExpectSameValueReference'
 export * from './useForceRender'
 export * from './useIsMounted'
 export * from './useObjectMemo'
+export * from './useOnElementMutation'
+export * from './useOnElementResize'
+export * from './useOnWindowResize'
 export * from './usePreviousValue'
+export * from './useScrollOffsets'
 export * from './useStoredState'
+export * from './useUpdatedRef'
+export * from './useWindowSize'

package/src/hooks/unwrapRefValue.ts

@@ -0,0 +1,16 @@
+import { RefObject } from 'react'
+
+export type RefObjectOrElement<T> = T | RefObject<T>
+
+/**
+ * Unwraps a ref object or returns the value if it is not a ref object.
+ * @param value - Value to unwrap
+ * @returns Unwrapped value
+ */
+export function unwrapRefValue<T>(value: RefObjectOrElement<T>): T | null {
+	if (value && typeof value === 'object' && 'current' in value) {
+		return value.current
+	} else {
+		return value
+	}
+}

package/src/hooks/useAddClassNameDuringResize.ts

@@ -0,0 +1,58 @@
+import { useLayoutEffect, useRef } from 'react'
+import { useReferentiallyStableCallback } from '../referentiallyStable'
+import { useOnWindowResize } from './useOnWindowResize'
+
+function intendedFlushOfCSSChangesToCauseImmediateReflow(element: HTMLElement) {
+	element.offsetHeight
+}
+
+function addClassName(
+	className: string,
+	element: HTMLElement,
+) {
+	if (element.classList.contains(className)) {
+		element.classList.remove(className)
+		intendedFlushOfCSSChangesToCauseImmediateReflow(element)
+	}
+}
+
+function removeClassName(
+	className: string,
+	element: HTMLElement,
+) {
+	if (!element.classList.contains(className)) {
+		element.classList.add(className)
+		intendedFlushOfCSSChangesToCauseImmediateReflow(element)
+	}
+}
+
+/**
+ * Adds CSS class during resize event to element
+ *
+ * - Falls back to document.body when no element is specified
+ * - Adds CSS class to element also on the initial load
+ * - Uses element.classList directly
+ *
+ * @param className - CSS class to apply during the resize event
+ * @param timeoutToRestore - Timeout in milliseconds to wait before finally removing the CSS class
+ * @param element - Optional HTML element to apply CSS class to
+ */
+export function useAddClassNameDuringResize(
+	className: string,
+	timeoutToRestore: number = 300,
+	element?: HTMLElement,
+) {
+	const timeoutID = useRef<number>()
+
+	const addTemporaryClassName = useReferentiallyStableCallback(() => {
+		clearTimeout(timeoutID.current)
+		removeClassName(className, element ?? document.body)
+
+		timeoutID.current = setTimeout(() => {
+			addClassName(className, element ?? document.body)
+		}, timeoutToRestore)
+	})
+
+	useLayoutEffect(addTemporaryClassName, [addTemporaryClassName])
+	useOnWindowResize(addTemporaryClassName)
+}

package/src/hooks/useComposeRef.ts

@@ -0,0 +1,46 @@
+import { MutableRefObject, RefCallback, useMemo, useRef } from 'react'
+
+export type MaybeRef<T> = ((instance: T | null) => void) | MutableRefObject<T | null> | null | undefined
+export type ComposedRefCallback<T> = RefCallback<T> & { current: T | null };
+
+function setRef<T>(ref: MaybeRef<T>, instance: T | null): void {
+	if (ref) {
+		if (typeof ref === 'function') {
+			ref(instance)
+		} else if (instance) {
+			ref.current = instance
+		}
+	}
+}
+
+/**
+ * Fills any number of refs with an instance
+ *
+ * Useful when you need to use outer ref and inner in the same time, e.g. passing element
+ * back to forwardedRef an also using the same value within the component locally.
+ *
+ * @param refs - Rest parameter of refs to fill with instance
+ * @returns Returns a function similar to a RefCallback
+ */
+export function useComposeRef<T>(...refs: MaybeRef<T>[]): ComposedRefCallback<T> {
+	const initialRefs = useRef(refs)
+
+	const composeRef: ComposedRefCallback<T> = useMemo(() => {
+		function composedRefCallback(instance: T | null) {
+			initialRefs.current.forEach(ref => setRef(ref, instance))
+			setCurrent(instance)
+		}
+
+		function setCurrent(instance: T | null) {
+			if (instance) {
+				composedRefCallback.current = instance
+			}
+		}
+
+		composedRefCallback.current = null as T | null
+
+		return composedRefCallback
+	}, [])
+
+	return composeRef
+}

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/useDebounceCallback.ts

@@ -6,7 +6,7 @@ export const useDebounceCallback = (cb: () => any, debounceMs: number) => {
 	cbRef.current = cb
 
 	useEffect(() => {
-		return () => timerRef.current && clearTimeout(timerRef.current)
+		return () => clearTimeout(timerRef.current)
 	}, [])
 
 	return useCallback(() => {

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])
+}