@mediamonks/react-kit 1.0.0-0

package/dist/hocs/ensuredForwardRef/ensuredForwardRef.js

@@ -0,0 +1,31 @@
+import { createRef, forwardRef, useMemo, } from 'react';
+export function ensuredForwardRef(
+// eslint-disable-next-line @typescript-eslint/naming-convention
+Component) {
+    // eslint-disable-next-line react/display-name
+    return forwardRef((props, ref) => {
+        const refObject = useMemo(() => {
+            // At runtime, ref _could_ be undefined when this component is rendered
+            // from a framework level that doesn't leverage typescript.
+            // Example is Next.js with dynamic imports.
+            // This can't be covered with tests.
+            // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+            if (ref !== null && ref !== undefined && 'current' in ref) {
+                return ref;
+            }
+            return new Proxy(createRef(), {
+                set(target, prop, newValue) {
+                    if (prop !== 'current') {
+                        return false;
+                    }
+                    // Update proxy ref value
+                    target.current = newValue;
+                    // Call ref function when it exists
+                    ref?.(newValue);
+                    return true;
+                },
+            });
+        }, [ref]);
+        return Component(props, refObject);
+    });
+}

package/dist/hooks/useClientSideValue/useClientSideValue.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Hook that returns the value returned by a callback function that is only called on client-side.
+ *
+ * @example
+ * function MyComponent() {
+ *   const value = useClientSideValue(Date.now, null);
+ *
+ *   return <div>{value ?? 'n/a'}</div>;
+ * }
+ */
+export declare function useClientSideValue<T>(callback: () => T, initialValue?: T): typeof initialValue;

package/dist/hooks/useClientSideValue/useClientSideValue.js

@@ -0,0 +1,19 @@
+import { useState } from 'react';
+import { useMount } from '../../lifecycle/hooks/useMount/useMount.js';
+/**
+ * Hook that returns the value returned by a callback function that is only called on client-side.
+ *
+ * @example
+ * function MyComponent() {
+ *   const value = useClientSideValue(Date.now, null);
+ *
+ *   return <div>{value ?? 'n/a'}</div>;
+ * }
+ */
+export function useClientSideValue(callback, initialValue) {
+    const [value, setValue] = useState(initialValue);
+    useMount(() => {
+        setValue(callback);
+    });
+    return value;
+}

package/dist/hooks/useEventListener/useEventListener.d.ts

@@ -0,0 +1,2 @@
+import { type RefObject } from 'react';
+export declare function useEventListener<T extends EventTarget>(targetOption: RefObject<T> | T | null | undefined, type: string, listener: EventListener, options?: boolean | AddEventListenerOptions): void;

package/dist/hooks/useEventListener/useEventListener.js

@@ -0,0 +1,17 @@
+/* eslint-disable  @typescript-eslint/unified-signatures, @typescript-eslint/no-explicit-any */
+import { useEffect } from 'react';
+import { unref } from '../../utils/unref/unref.js';
+import { useRefValue } from '../useRefValue/useRefValue.js';
+export function useEventListener(targetOption, type, listener, options) {
+    const listenerRef = useRefValue(listener);
+    useEffect(() => {
+        const target = unref(targetOption);
+        function callback(event) {
+            listenerRef.current?.(event);
+        }
+        target?.addEventListener(type, callback, options);
+        return () => {
+            target?.removeEventListener(type, callback, options);
+        };
+    }, [listenerRef, options, targetOption, type]);
+}

package/dist/hooks/useForceRerender/useForceRerender.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Forces a rerender of the component when the returned function is called.
+ *
+ * This should only be used when there is no other state that can be used to trigger a rerender.
+ *
+ * Examples could be to force a rerender after a timeout or interval, to compare the current time
+ * (that changes) with the time when the component was last updated.
+ *
+ * @returns A function that can be called to force a rerender.
+ */
+export declare function useForceRerender(): () => void;

package/dist/hooks/useForceRerender/useForceRerender.js

@@ -0,0 +1,18 @@
+import { useReducer } from 'react';
+// use an arbitrary large number instead of a toggle boolean to avoid potential optimization issues
+// when called multiple times in a single render, but have a cap to avoid overflow
+const updateReducer = (value) => (value + 1) % Number.MAX_SAFE_INTEGER;
+/**
+ * Forces a rerender of the component when the returned function is called.
+ *
+ * This should only be used when there is no other state that can be used to trigger a rerender.
+ *
+ * Examples could be to force a rerender after a timeout or interval, to compare the current time
+ * (that changes) with the time when the component was last updated.
+ *
+ * @returns A function that can be called to force a rerender.
+ */
+export function useForceRerender() {
+    const [, update] = useReducer(updateReducer, 0);
+    return update;
+}

package/dist/hooks/useHasFocus/useHasFocus.d.ts

@@ -0,0 +1,9 @@
+import { type RefObject } from 'react';
+export type FocusPseudoSelector = ':focus' | ':focus-visible' | ':focus-within';
+/**
+ * This hook allows you to determine if an element matches the :focus, :focus-visible, or :focus-within pseudo selectors.
+ *
+ * @param ref - The ref to the element to check
+ * @param selector - The pseudo selector to check for
+ */
+export declare function useHasFocus(ref: RefObject<HTMLElement>, selector?: FocusPseudoSelector): boolean;

package/dist/hooks/useHasFocus/useHasFocus.js

@@ -0,0 +1,18 @@
+import { useCallback, useState } from 'react';
+import { useEventListener } from '../useEventListener/useEventListener.js';
+/**
+ * This hook allows you to determine if an element matches the :focus, :focus-visible, or :focus-within pseudo selectors.
+ *
+ * @param ref - The ref to the element to check
+ * @param selector - The pseudo selector to check for
+ */
+export function useHasFocus(ref, selector = ':focus') {
+    const matches = useCallback(() => ref.current?.matches(selector) ?? false, [ref, selector]);
+    const [state, setState] = useState(matches);
+    const onUpdate = useCallback(() => {
+        setState(matches());
+    }, [matches, setState]);
+    useEventListener(globalThis.document, 'focusin', onUpdate);
+    useEventListener(globalThis.document, 'focusout', onUpdate);
+    return state;
+}

package/dist/hooks/useIntersectionObserver/useIntersectionObserver.d.ts

@@ -0,0 +1,13 @@
+import { type RefObject } from 'react';
+/**
+ * This hook creates an IntersectionObserver and uses it to observe
+ * the target element.
+ *
+ * For a full explanation of the IntersectionObserver API, check the docs:
+ * https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver
+ *
+ * @param targetOrTargets - The target or targets to observe
+ * @param callback - The callback to fire when the element resizes
+ * @param options - Optional options object
+ */
+export declare function useIntersectionObserver(targetOrTargets: RefObject<Element | ReadonlyArray<Element | null> | null>, callback: IntersectionObserverCallback, options?: IntersectionObserverInit): void;

package/dist/hooks/useIntersectionObserver/useIntersectionObserver.js

@@ -0,0 +1,38 @@
+import { useEffect } from 'react';
+import { unref } from '../../utils/unref/unref.js';
+import { useClientSideValue } from '../useClientSideValue/useClientSideValue.js';
+import { useRefValue } from '../useRefValue/useRefValue.js';
+/**
+ * This hook creates an IntersectionObserver and uses it to observe
+ * the target element.
+ *
+ * For a full explanation of the IntersectionObserver API, check the docs:
+ * https://developer.mozilla.org/en-US/docs/Web/API/IntersectionObserver/IntersectionObserver
+ *
+ * @param targetOrTargets - The target or targets to observe
+ * @param callback - The callback to fire when the element resizes
+ * @param options - Optional options object
+ */
+export function useIntersectionObserver(targetOrTargets, callback, options) {
+    const callbackRef = useRefValue(callback);
+    const intersectionObserverInstance = useClientSideValue(() => new IntersectionObserver((entries, observer) => callbackRef.current?.(entries, observer), options));
+    useEffect(() => {
+        const targets = Array.isArray(targetOrTargets.current)
+            ? targetOrTargets.current
+            : [targetOrTargets.current];
+        for (const target of targets) {
+            const element = unref(target);
+            if (element) {
+                intersectionObserverInstance?.observe(element);
+            }
+        }
+        return () => {
+            for (const target of targets) {
+                const element = unref(target);
+                if (element) {
+                    intersectionObserverInstance?.unobserve(element);
+                }
+            }
+        };
+    }, [intersectionObserverInstance, targetOrTargets]);
+}

package/dist/hooks/useInterval/useInterval.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A hook that sets up an interval to repeatedly call a callback function.
+ *
+ * @param callback - The function to be called repeatedly.
+ * @param ms - The number of milliseconds between each call to the callback function. Defaults to 0.
+ * @param enabled - Whether the interval should be enabled. Defaults to true.
+ */
+export declare function useInterval(callback: () => void, ms?: number, enabled?: boolean): void;

package/dist/hooks/useInterval/useInterval.js

@@ -0,0 +1,25 @@
+import { useEffect, useRef } from 'react';
+import { useRefValue } from '../useRefValue/useRefValue.js';
+/**
+ * A hook that sets up an interval to repeatedly call a callback function.
+ *
+ * @param callback - The function to be called repeatedly.
+ * @param ms - The number of milliseconds between each call to the callback function. Defaults to 0.
+ * @param enabled - Whether the interval should be enabled. Defaults to true.
+ */
+export function useInterval(callback, ms, enabled = true) {
+    const callbackRef = useRefValue(callback);
+    const intervalRef = useRef();
+    useEffect(() => {
+        if (!enabled) {
+            clearInterval(intervalRef.current);
+            return;
+        }
+        intervalRef.current = setInterval(() => {
+            callbackRef.current?.();
+        }, ms);
+        return () => {
+            clearInterval(intervalRef.current);
+        };
+    }, [callbackRef, enabled, ms]);
+}

package/dist/hooks/useMediaDuration/useMediaDuration.d.ts

@@ -0,0 +1,5 @@
+import { type MutableRefObject } from 'react';
+/**
+ * Retrieves the duration of the audio / video file in seconds.
+ */
+export declare function useMediaDuration(mediaElementRef: MutableRefObject<HTMLMediaElement | null>): number;

package/dist/hooks/useMediaDuration/useMediaDuration.js

@@ -0,0 +1,20 @@
+import { useCallback, useEffect, useState } from 'react';
+/**
+ * Retrieves the duration of the audio / video file in seconds.
+ */
+export function useMediaDuration(mediaElementRef) {
+    const [mediaDuration, setMediaDuration] = useState(Number.NaN);
+    const updateDuration = useCallback(() => {
+        setMediaDuration(mediaElementRef.current?.duration ?? Number.NaN);
+    }, [mediaElementRef]);
+    useEffect(() => {
+        const mediaElement = mediaElementRef.current;
+        mediaElement?.addEventListener('durationchange', updateDuration);
+        // metadata could have been loaded before listener is attached
+        updateDuration();
+        return () => {
+            mediaElement?.removeEventListener('durationchange', updateDuration);
+        };
+    }, [mediaElementRef, updateDuration]);
+    return mediaDuration;
+}

package/dist/hooks/useMediaQuery/useMediaQuery.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The MediaQueryVariables type is used for the `mediaQueryOrVariableName` parameter of
+ * `useMediaQuery`.
+ *
+ * Augment the MediaQueryVariables interface to add the names for the CSS variables that
+ * describe media queries in your project.
+ *
+ * @example
+ * import '@mediamonks/react-kit';
+ *
+ * declare module '@mediamonks/react-kit' {
+ *   interface MediaQueryVariables {
+ *     '--media-query-name': never;
+ *   }
+ * }
+ */
+export interface MediaQueryVariables {
+}
+/**
+ * Enables auto-completion for the variable names that are defined in `MediaQueryVariables` and also allows custom string values.
+ */
+type MediaQueryValues = keyof MediaQueryVariables | (string & {
+    __custom_query__do_not_use_this_field__?: boolean;
+});
+export declare function getMediaQueryList(mediaQueryOrVariableName: MediaQueryValues): MediaQueryList | undefined;
+/**
+ * Hook that returns a boolean indicating whether the media query matches.
+ *
+ * @param mediaQueryOrVariableName - The name of the CSS variable that describes the media query.
+ * @param defaultValue - The default value to return if the matchMedia API is not available.
+ */
+export declare function useMediaQuery(mediaQueryOrVariableName: MediaQueryValues, defaultValue?: boolean): boolean;
+export {};

package/dist/hooks/useMediaQuery/useMediaQuery.js

@@ -0,0 +1,32 @@
+import { useEffect, useState } from 'react';
+import { useEventListener } from '../useEventListener/useEventListener.js';
+export function getMediaQueryList(mediaQueryOrVariableName) {
+    if (typeof matchMedia === 'undefined') {
+        return undefined;
+    }
+    const mediaQuery = mediaQueryOrVariableName.startsWith('--')
+        ? getComputedStyle(document.body).getPropertyValue(mediaQueryOrVariableName)
+        : mediaQueryOrVariableName;
+    return matchMedia(mediaQuery);
+}
+/**
+ * Hook that returns a boolean indicating whether the media query matches.
+ *
+ * @param mediaQueryOrVariableName - The name of the CSS variable that describes the media query.
+ * @param defaultValue - The default value to return if the matchMedia API is not available.
+ */
+export function useMediaQuery(mediaQueryOrVariableName, defaultValue = false) {
+    const [mediaQueryList, setMediaQueryList] = useState(() => getMediaQueryList(mediaQueryOrVariableName));
+    const [matches, setMatches] = useState(defaultValue);
+    useEffect(() => {
+        const newMediaQueryList = getMediaQueryList(mediaQueryOrVariableName);
+        setMediaQueryList(newMediaQueryList);
+        setMatches(newMediaQueryList?.matches);
+    }, [defaultValue, mediaQueryList?.matches, mediaQueryOrVariableName]);
+    useEventListener(mediaQueryList, 'change', (event) => {
+        if (event instanceof MediaQueryListEvent) {
+            setMatches(event.matches);
+        }
+    });
+    return matches ?? defaultValue;
+}

package/dist/hooks/useMutationObserver/useMutationObserver.d.ts

@@ -0,0 +1,16 @@
+import { type Unreffable } from '../../index.js';
+/**
+ * Hook that sets up a MutationObserver to watch for changes to a DOM element.
+ *
+ * @example
+ * function MyComponent(): ReactElement {
+ *   const targetRef = useRef<HTMLElement>(null);
+ *
+ *   useMutationObserver(targetRef, (mutations, observer) => {
+ *     console.log('Mutations observed:', mutations);
+ *   }, { childList: true });
+ *
+ *   return <div ref={targetRef}>Hello, world!</div>;
+ * }
+ */
+export declare function useMutationObserver(target: Unreffable<Element | null>, callback: MutationCallback, options: MutationObserverInit): void;

package/dist/hooks/useMutationObserver/useMutationObserver.js

@@ -0,0 +1,36 @@
+import { useEffect, useMemo } from 'react';
+import { unref, useRefValue } from '../../index.js';
+/**
+ * Hook that sets up a MutationObserver to watch for changes to a DOM element.
+ *
+ * @example
+ * function MyComponent(): ReactElement {
+ *   const targetRef = useRef<HTMLElement>(null);
+ *
+ *   useMutationObserver(targetRef, (mutations, observer) => {
+ *     console.log('Mutations observed:', mutations);
+ *   }, { childList: true });
+ *
+ *   return <div ref={targetRef}>Hello, world!</div>;
+ * }
+ */
+export function useMutationObserver(target, callback, options) {
+    const memoizedOptions = useMemo(() => options, 
+    // Options are serializable so we can safely use JSON.stringify for the comparison
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [JSON.stringify(options)]);
+    const callbackRef = useRefValue(callback);
+    useEffect(() => {
+        const element = unref(target);
+        if (element === null) {
+            return;
+        }
+        const mutationObserverInstance = new MutationObserver((mutations, observer) => {
+            callbackRef.current?.(mutations, observer);
+        });
+        mutationObserverInstance.observe(element, memoizedOptions);
+        return () => {
+            mutationObserverInstance.disconnect();
+        };
+    }, [callbackRef, memoizedOptions, target]);
+}

package/dist/hooks/useRafCallback/useRafCallback.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Hook that returns a function that will be called on the next animation frame.
+ * This is useful for performing non-blocking updates to the DOM or other state.
+ */
+export declare function useRafCallback(callback: FrameRequestCallback): () => number;

package/dist/hooks/useRafCallback/useRafCallback.js

@@ -0,0 +1,21 @@
+import { useCallback, useRef } from 'react';
+import { useUnmount } from '../../lifecycle/hooks/useUnmount/useUnmount.js';
+import { useRefValue } from '../useRefValue/useRefValue.js';
+/**
+ * Hook that returns a function that will be called on the next animation frame.
+ * This is useful for performing non-blocking updates to the DOM or other state.
+ */
+export function useRafCallback(callback) {
+    const callbackRef = useRefValue(callback);
+    const animationFrameRef = useRef(0);
+    useUnmount(() => {
+        cancelAnimationFrame(animationFrameRef.current);
+    });
+    return useCallback(() => {
+        cancelAnimationFrame(animationFrameRef.current);
+        animationFrameRef.current = requestAnimationFrame((time) => {
+            callbackRef.current?.(time);
+        });
+        return animationFrameRef.current;
+    }, [callbackRef]);
+}

package/dist/hooks/useRefValue/useRefValue.d.ts

@@ -0,0 +1,11 @@
+import { type RefObject } from 'react';
+/**
+ * Keeps a ref up to date with a changing value.
+ *
+ * Normal values are captured in scopes, while refs are not. Therefore a changing value in a callback
+ * requires the use of a ref.
+ *
+ * @param value The value to keep in the ref.
+ * @returns A ref object that is updated with the value.
+ */
+export declare function useRefValue<T>(value: T): RefObject<T>;

package/dist/hooks/useRefValue/useRefValue.js

@@ -0,0 +1,15 @@
+import { useRef } from 'react';
+/**
+ * Keeps a ref up to date with a changing value.
+ *
+ * Normal values are captured in scopes, while refs are not. Therefore a changing value in a callback
+ * requires the use of a ref.
+ *
+ * @param value The value to keep in the ref.
+ * @returns A ref object that is updated with the value.
+ */
+export function useRefValue(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}

package/dist/hooks/useRefs/useRefs.d.ts

@@ -0,0 +1,5 @@
+import { type RefObject } from 'react';
+/**
+ * Utility to automatically create refs
+ */
+export declare function useRefs<T extends Record<string | symbol, RefObject<unknown>>>(initialTarget?: Partial<T>): T;

package/dist/hooks/useRefs/useRefs.js

@@ -0,0 +1,17 @@
+import { createRef, useMemo, useRef } from 'react';
+/**
+ * Utility to automatically create refs
+ */
+export function useRefs(initialTarget) {
+    const proxyTarget = useRef(initialTarget ?? {});
+    return useMemo(() => new Proxy(proxyTarget.current, {
+        get(target, prop) {
+            if (target[prop] !== undefined) {
+                return target[prop];
+            }
+            // @ts-expect-error - the type cannot be correctly inferred from the prop name because it is a symbol or string
+            target[prop] = createRef();
+            return target[prop];
+        },
+    }), []);
+}

package/dist/hooks/useRefs/useRefs.types.d.ts

@@ -0,0 +1,15 @@
+import type { MutableRefObject, RefObject } from 'react';
+type UnknownRecord = Record<string | number | symbol, unknown>;
+/**
+ * Type utility to create an object type where all values are RefObjects
+ */
+export type Refs<T extends UnknownRecord = UnknownRecord> = {
+    [P in keyof T]: RefObject<T[P] | null>;
+};
+/**
+ * Type utility to create an object type where all values are MutableRefObjects
+ */
+export type MutableRefs<T extends UnknownRecord = UnknownRecord> = {
+    [P in keyof T]: MutableRefObject<T[P] | null>;
+};
+export {};

package/dist/hooks/useRefs/useRefs.types.js

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useRefs/utils/assertAndUnwrapRefs/assertAndUnwrapRefs.d.ts

@@ -0,0 +1,14 @@
+import { type NonNullableRecord } from '../../../../_utils/isNonNullableRecord/isNonNullableRecord.js';
+import type { Refs } from '../../useRefs.types.js';
+import type { UnwrapRefs } from '../unwrapRefs/unwrapRefs.types.js';
+/**
+ * Unwraps refs and assert every field is not null
+ *
+ * NOTE: this function asserts fields known during runtime on the refs parameter.
+ * The useRefs Proxy only creates a field in the getter, this means that a field's
+ * value will still be undefined when you never reference that field. The return
+ * type of this function doesn't reflect that behavior.
+ *
+ * @deprecated use `validateAndUnwrapRefs` instead to avoid errors during hot reloading
+ */
+export declare function assertAndUnwrapRefs<T extends Refs>(refs: T): NonNullableRecord<UnwrapRefs<T>>;

package/dist/hooks/useRefs/utils/assertAndUnwrapRefs/assertAndUnwrapRefs.js

@@ -0,0 +1,19 @@
+import { isNonNullableRecord, } from '../../../../_utils/isNonNullableRecord/isNonNullableRecord.js';
+import { unwrapRefs } from '../unwrapRefs/unwrapRefs.js';
+/**
+ * Unwraps refs and assert every field is not null
+ *
+ * NOTE: this function asserts fields known during runtime on the refs parameter.
+ * The useRefs Proxy only creates a field in the getter, this means that a field's
+ * value will still be undefined when you never reference that field. The return
+ * type of this function doesn't reflect that behavior.
+ *
+ * @deprecated use `validateAndUnwrapRefs` instead to avoid errors during hot reloading
+ */
+export function assertAndUnwrapRefs(refs) {
+    const unwrappedRefs = unwrapRefs(refs);
+    if (!isNonNullableRecord(unwrappedRefs)) {
+        throw new Error('"refs" contains null values', refs);
+    }
+    return unwrappedRefs;
+}

package/dist/hooks/useRefs/utils/unwrapRefs/unwrapRefs.d.ts

@@ -0,0 +1,6 @@
+import type { Refs } from '../../useRefs.types.js';
+import type { UnwrapRefs } from './unwrapRefs.types.js';
+/**
+ * Unwraps RefObjects in object
+ */
+export declare function unwrapRefs<T extends Refs>(refs: T): UnwrapRefs<T>;

package/dist/hooks/useRefs/utils/unwrapRefs/unwrapRefs.js

@@ -0,0 +1,12 @@
+/**
+ * Unwraps RefObjects in object
+ */
+export function unwrapRefs(refs) {
+    const unwrappedRefs = {};
+    for (const key in refs) {
+        if (Object.hasOwn(refs, key)) {
+            unwrappedRefs[key] = refs[key].current;
+        }
+    }
+    return unwrappedRefs;
+}

package/dist/hooks/useRefs/utils/unwrapRefs/unwrapRefs.types.d.ts

@@ -0,0 +1,7 @@
+import type { RefObject } from 'react';
+/**
+ * Unwrap RefObject values in Record
+ */
+export type UnwrapRefs<T extends Record<string | number | symbol, RefObject<unknown>>> = {
+    [K in keyof T]: T[K]['current'];
+};

package/dist/hooks/useRefs/utils/unwrapRefs/unwrapRefs.types.js

@@ -0,0 +1 @@
+export {};

package/dist/hooks/useRefs/utils/validateAndUnwrapRefs/validateAndUnwrapRefs.d.ts

@@ -0,0 +1,12 @@
+import { type NonNullableRecord } from '../../../../_utils/isNonNullableRecord/isNonNullableRecord.js';
+import type { Refs } from '../../useRefs.types.js';
+import type { UnwrapRefs } from '../unwrapRefs/unwrapRefs.types.js';
+/**
+ * Unwraps refs and assert every field is not null
+ *
+ * NOTE: this function asserts fields known during runtime on the refs parameter.
+ * The useRefs Proxy only creates a field in the getter, this means that a field's
+ * value will still be undefined when you never reference that field. The return
+ * type of this function doesn't reflect that behavior.
+ */
+export declare function validateAndUnwrapRefs<T extends Refs>(refs: T): [false, undefined] | [true, NonNullableRecord<UnwrapRefs<T>>];

package/dist/hooks/useRefs/utils/validateAndUnwrapRefs/validateAndUnwrapRefs.js

@@ -0,0 +1,17 @@
+import { isNonNullableRecord, } from '../../../../_utils/isNonNullableRecord/isNonNullableRecord.js';
+import { unwrapRefs } from '../unwrapRefs/unwrapRefs.js';
+/**
+ * Unwraps refs and assert every field is not null
+ *
+ * NOTE: this function asserts fields known during runtime on the refs parameter.
+ * The useRefs Proxy only creates a field in the getter, this means that a field's
+ * value will still be undefined when you never reference that field. The return
+ * type of this function doesn't reflect that behavior.
+ */
+export function validateAndUnwrapRefs(refs) {
+    const unwrappedRefs = unwrapRefs(refs);
+    if (!isNonNullableRecord(unwrappedRefs)) {
+        return [false, undefined];
+    }
+    return [true, unwrappedRefs];
+}

package/dist/hooks/useResizeObserver/useResizeObserver.d.ts

@@ -0,0 +1,9 @@
+import { type Unreffable } from '../../utils/unref/unref.js';
+/**
+ * This hook allows you to add a ResizeObserver for an element and remove it
+ * when the component unmounts.
+ *
+ * @param target - The target to observe
+ * @param callback - The callback to fire when the element resizes
+ */
+export declare function useResizeObserver(target: Unreffable<Element | null>, callback: ResizeObserverCallback): void;

package/dist/hooks/useResizeObserver/useResizeObserver.js

@@ -0,0 +1,22 @@
+import { useEffect } from 'react';
+import { unref } from '../../utils/unref/unref.js';
+/**
+ * This hook allows you to add a ResizeObserver for an element and remove it
+ * when the component unmounts.
+ *
+ * @param target - The target to observe
+ * @param callback - The callback to fire when the element resizes
+ */
+export function useResizeObserver(target, callback) {
+    useEffect(() => {
+        const element = unref(target);
+        if (element === null) {
+            return;
+        }
+        const resizeObserverInstance = new ResizeObserver(callback);
+        resizeObserverInstance.observe(element);
+        return () => {
+            resizeObserverInstance.disconnect();
+        };
+    }, [target, callback]);
+}

package/dist/hooks/useStaticValue/useStaticValue.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Keep track of a value that is initialized once and then never changes.
+ *
+ * This behavior is similar to `useState`, but the value is never updated.
+ */
+export declare function useStaticValue<T>(initializeFunction: (() => T) | T): T;