@dxos/react-hooks 0.8.3 → 0.8.4-main.1068cf700f

package/package.json

@@ -1,15 +1,20 @@
 {
   "name": "@dxos/react-hooks",
-  "version": "0.8.3",
+  "version": "0.8.4-main.1068cf700f",
   "description": "React hooks supporting DXOS React primitives.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dxos/dxos"
+  },
   "license": "MIT",
   "author": "DXOS.org",
-  "sideEffects": true,
+  "sideEffects": false,
   "type": "module",
   "exports": {
     ".": {
+      "source": "./src/index.ts",
       "types": "./dist/types/src/index.d.ts",
       "browser": "./dist/lib/browser/index.mjs",
       "node": "./dist/lib/node-esm/index.mjs"
@@ -24,20 +29,23 @@
     "src"
   ],
   "dependencies": {
-    "@preact-signals/safe-react": "^0.9.0",
+    "@radix-ui/react-id": "1.1.0",
     "alea": "^1.0.1",
-    "@dxos/async": "0.8.3",
-    "@dxos/log": "0.8.3"
+    "lodash.defaultsdeep": "^4.6.1",
+    "mini-virtual-list": "^0.3.2",
+    "@dxos/async": "0.8.4-main.1068cf700f",
+    "@dxos/log": "0.8.4-main.1068cf700f"
   },
   "devDependencies": {
-    "@types/react": "~18.2.0",
-    "@types/react-dom": "~18.2.0",
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0"
+    "@types/lodash.defaultsdeep": "^4.6.6",
+    "@types/react": "~19.2.7",
+    "@types/react-dom": "~19.2.3",
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3"
   },
   "peerDependencies": {
-    "react": "~18.2.0",
-    "react-dom": "~18.2.0"
+    "react": "~19.2.3",
+    "react-dom": "~19.2.3"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -5,8 +5,9 @@
 export * from './useAsyncEffect';
 export * from './useAsyncState';
 export * from './useControlledState';
-export * from './useDebugReactDeps';
+export * from './useDebugDeps';
 export * from './useDefaultValue';
+export * from './useDefaults';
 export * from './useDynamicRef';
 export * from './useFileDownload';
 export * from './useForwardedRef';
@@ -15,6 +16,8 @@ export * from './useIsFocused';
 export * from './useMediaQuery';
 export * from './useMulticastObservable';
 export * from './useRefCallback';
-export * from './useResize';
-export * from './useTrackProps';
+export * from './useViewportResize';
+export * from './useTimeout';
 export * from './useTransitions';
+
+export { useSize, useScroller } from 'mini-virtual-list';

package/src/useAsyncEffect.ts

@@ -2,61 +2,31 @@
 // Copyright 2022 DXOS.org
 //
 
-import { useEffect } from 'react';
-
-import { log } from '@dxos/log';
+import { type DependencyList, type EffectCallback, useEffect } from 'react';
 
 /**
- * Process async event with optional non-async destructor.
- * Inspired by: https://github.com/rauldeheer/use-async-effect/blob/master/index.js
- *
- * ```tsx
- * useAsyncEffect(async () => {
- *   await test();
- * }, []);
- * ```
- *
- * The callback may check of the component is still mounted before doing state updates.
- *
- * ```tsx
- * const [value, setValue] = useState<string>();
- * useAsyncEffect<string>(async (isMounted) => {
- *   const value = await test();
- *   if (!isMounted()) {
- *     setValue(value);
- *   }
- * }, () => console.log('Unmounted'), []);
- * ```
- *
- * @param callback Receives a getter function that determines if the component is still mounted.
- * @param destructor Receives the value returned from the callback.
- * @param deps
- *
- * NOTE: This effect does not cancel the async operation if the component is unmounted.
- *
- * @deprecated
+ * Async version of useEffect.
+ * The `AbortController` can be used to detect if the component has been unmounted and
+ * can be used to propagate abort signals to downstream async operations (e.g., `fetch`).
  */
-export const useAsyncEffect = <T>(
-  callback: (isMounted: () => boolean) => Promise<T> | undefined,
-  destructor?: ((value?: T) => void) | any[],
-  deps?: any[],
+export const useAsyncEffect = (
+  cb: (controller: AbortController) => Promise<EffectCallback | void>,
+  deps?: DependencyList,
 ) => {
-  const [effectDestructor, effectDeps] =
-    typeof destructor === 'function' ? [destructor, deps] : [undefined, destructor];
-
   useEffect(() => {
-    let mounted = true;
-    let value: T | undefined;
-    const asyncResult = callback(() => mounted);
-    void Promise.resolve(asyncResult)
-      .then((result) => {
-        value = result;
-      })
-      .catch(log.catch);
+    const controller = new AbortController();
+    let cleanup: EffectCallback | void;
+    // NOTE: Timeout enables us to immediately cancel. if the component is unmounted.
+    const t = setTimeout(async () => {
+      if (!controller.signal.aborted) {
+        cleanup = await cb(controller);
+      }
+    });
 
     return () => {
-      mounted = false;
-      effectDestructor?.(value);
+      clearTimeout(t);
+      controller.abort();
+      cleanup?.();
     };
-  }, effectDeps);
+  }, deps ?? []);
 };

package/src/useAsyncState.ts

@@ -14,7 +14,7 @@ export const useAsyncState = <T>(
   const [value, setValue] = useState<T | undefined>();
   useEffect(() => {
     let disposed = false;
-    queueMicrotask(async () => {
+    const t = setTimeout(async () => {
       const data = await cb();
       if (!disposed) {
         setValue(data);
@@ -23,6 +23,7 @@ export const useAsyncState = <T>(
 
     return () => {
       disposed = true;
+      clearTimeout(t);
     };
   }, deps);
 

package/src/useControlledState.ts

@@ -2,18 +2,37 @@
 // Copyright 2023 DXOS.org
 //
 
-import { type Dispatch, type SetStateAction, useEffect, useState } from 'react';
+import { type Dispatch, type SetStateAction, useCallback, useEffect, useRef, useState } from 'react';
+
+import { useDynamicRef } from './useDynamicRef';
 
 /**
  * A stateful hook with a controlled value.
+ * NOTE: Consider using Radix's `useControllableState`.
  */
-export const useControlledState = <T>(controlledValue: T, ...deps: any[]): [T, Dispatch<SetStateAction<T>>] => {
-  const [value, setValue] = useState<T>(controlledValue);
+export const useControlledState = <T>(
+  valueProp: T,
+  onChange?: (value: T) => void,
+): [T, Dispatch<SetStateAction<T>>] => {
+  const [value, setControlledValue] = useState(valueProp);
   useEffect(() => {
-    if (controlledValue !== undefined) {
-      setValue(controlledValue);
-    }
-  }, [controlledValue, ...deps]);
+    setControlledValue(valueProp);
+  }, [valueProp]);
+
+  const onChangeRef = useRef(onChange);
+  const valueRef = useDynamicRef(valueProp);
+  const setValue = useCallback<Dispatch<SetStateAction<T>>>(
+    (nextValue) => {
+      const value = isFunction(nextValue) ? nextValue(valueRef.current) : nextValue;
+      setControlledValue(value);
+      onChangeRef.current?.(value);
+    },
+    [valueRef, onChangeRef],
+  );
 
   return [value, setValue];
 };
+
+function isFunction(value: unknown): value is (...args: any[]) => any {
+  return typeof value === 'function';
+}

package/src/useDebugDeps.ts

@@ -0,0 +1,35 @@
+//
+// Copyright 2024 DXOS.org
+//
+
+import { type DependencyList, useEffect, useRef } from 'react';
+
+import { log } from '@dxos/log';
+
+/**
+ * Util to log deps that have changed.
+ */
+export const useDebugDeps = (deps: DependencyList = [], label = 'useDebugDeps', active = true) => {
+  const lastDeps = useRef<DependencyList>([]);
+  useEffect(() => {
+    if (!active) {
+      return;
+    }
+
+    const diff: Record<number, { previous: any; current: any }> = {};
+    for (let i = 0; i < Math.max(lastDeps.current.length ?? 0, deps.length ?? 0); i++) {
+      if (lastDeps.current[i] !== deps[i] || i > lastDeps.current.length) {
+        diff[i] = {
+          previous: lastDeps.current[i],
+          current: deps[i],
+        };
+      }
+    }
+
+    if (Object.keys(diff).length > 0) {
+      log.warn(`Updated: ${label} [${lastDeps.current.length}/${deps.length}]`, diff);
+    }
+
+    lastDeps.current = deps;
+  }, [...deps, active]);
+};

package/src/useDefaultValue.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { useEffect, useState, useMemo } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
 /**
  * A custom React hook that provides a stable default value for a potentially undefined reactive value.
@@ -21,7 +21,6 @@ export const useDefaultValue = <T>(reactiveValue: T | undefined | null, getDefau
   // regardless of whether the defaultValue changes.
   const stableDefaultValue = useMemo(getDefaultValue, []);
   const [value, setValue] = useState(reactiveValue ?? stableDefaultValue);
-
   useEffect(() => {
     setValue(reactiveValue ?? stableDefaultValue);
   }, [reactiveValue, stableDefaultValue]);

package/src/useDefaults.ts

@@ -0,0 +1,14 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import defaultsDeep from 'lodash.defaultsdeep';
+import { useMemo } from 'react';
+
+/**
+ * Returns a memo-ized deep-merged object of the default and value.
+ * If value is undefined or null, then returns the default.
+ */
+export const useDefaults = <T>(value: T | undefined | null, defaults: T): T => {
+  return useMemo(() => defaultsDeep({}, defaults, value), [value, defaults]);
+};

package/src/useDynamicRef.ts

@@ -2,16 +2,37 @@
 // Copyright 2024 DXOS.org
 //
 
-import { useEffect, useRef } from 'react';
+import { type Dispatch, type RefObject, type SetStateAction, useCallback, useEffect, useRef, useState } from 'react';
+
+/**
+ * Like `useState` but with an additional dynamic value.
+ */
+export const useStateWithRef = <T>(valueProp: T): [T, Dispatch<SetStateAction<T>>, RefObject<T>] => {
+  const [value, setValue] = useState<T>(valueProp);
+  const valueRef = useRef<T>(valueProp);
+  const setter = useCallback<Dispatch<SetStateAction<T>>>((value) => {
+    if (typeof value === 'function') {
+      setValue((current) => {
+        valueRef.current = (value as Function)(current);
+        return valueRef.current;
+      });
+    } else {
+      valueRef.current = value;
+      setValue(value);
+    }
+  }, []);
+
+  return [value, setter, valueRef];
+};
 
 /**
  * Ref that is updated by a dependency.
  */
-export const useDynamicRef = <T>(value: T) => {
-  const ref = useRef<T>(value);
+export const useDynamicRef = <T>(value: T): RefObject<T> => {
+  const valueRef = useRef<T>(value);
   useEffect(() => {
-    ref.current = value;
+    valueRef.current = value;
   }, [value]);
 
-  return ref;
+  return valueRef;
 };

package/src/useForwardedRef.ts

@@ -2,25 +2,60 @@
 // Copyright 2022 DXOS.org
 //
 
-import { type ForwardedRef, useRef, useEffect } from 'react';
+import { type ForwardedRef, type Ref, type RefCallback, useEffect, useMemo, useRef } from 'react';
 
 /**
  * Combines a possibly undefined forwarded ref with a locally defined ref.
- * See also: react-merge-refs
+ * Returns a stable ref object that synchronizes with the forwarded ref.
+ *
+ * Best practice: This hook creates a stable local ref and synchronizes it with the forwarded ref.
+ * The returned ref object is stable across renders, preventing infinite loops caused by ref identity changes.
+ *
+ * NOTE: This pattern doesn't update refs once they are set. If this is required, use `useMergeRefs`.
  */
-export const useForwardedRef = <T>(ref: ForwardedRef<T>) => {
-  const innerRef = useRef<T>(null);
+export const useForwardedRef = <T>(forwardedRef: ForwardedRef<T>) => {
+  const localRef = useRef<T>(null as T);
   useEffect(() => {
-    if (!ref) {
-      return;
-    }
+    setRef(forwardedRef, localRef.current);
+  }, [forwardedRef]);
+
+  return localRef;
+};
+
+/**
+ * Sets a value on a React ref, handling both callback refs and ref objects.
+ * Returns a cleanup function if the ref is a callback ref.
+ */
+export function setRef<T>(ref: Ref<T> | undefined | null, value: T | null): ReturnType<RefCallback<T>> {
+  if (typeof ref === 'function') {
+    return ref(value);
+  } else if (ref) {
+    ref.current = value;
+  }
+}
 
-    if (typeof ref === 'function') {
-      ref(innerRef.current);
-    } else {
-      ref.current = innerRef.current;
+/**
+ * Merges multiple refs into a single ref callback.
+ * Returns a ref callback that synchronizes all provided refs and handles cleanup.
+ */
+export const mergeRefs = <T>(refs: (Ref<T> | undefined)[]): Ref<T> => {
+  return (value: T | null) => {
+    const cleanups: (() => void)[] = [];
+    for (const ref of refs) {
+      const cleanup = setRef(ref, value);
+      cleanups.push(typeof cleanup === 'function' ? cleanup : () => setRef(ref, null));
     }
-  });
 
-  return innerRef;
+    return () => {
+      for (const cleanup of cleanups) cleanup();
+    };
+  };
+};
+
+/**
+ * Hook that merges multiple refs into a single stable ref callback.
+ * The returned ref is memoized and only changes when the refs array changes.
+ */
+export const useMergeRefs = <T>(refs: (Ref<T> | undefined)[]): Ref<T> => {
+  return useMemo(() => mergeRefs(refs), [...refs]);
 };

package/src/useId.ts

@@ -19,8 +19,9 @@ export const randomString = (n = 4) =>
     .toString(16)
     .slice(2, n + 2);
 
-export const useId = (namespace: string, propsId?: string, opts?: Partial<{ n: number }>) =>
-  useMemo(() => makeId(namespace, propsId, opts), [propsId]);
+export const useId = (namespace: string, propsId?: string, opts?: Partial<{ n: number }>) => {
+  return useMemo(() => makeId(namespace, propsId, opts), [propsId]);
+};
 
 export const makeId = (namespace: string, propsId?: string, opts?: Partial<{ n: number }>) =>
   propsId ?? `${namespace}-${randomString(opts?.n ?? 4)}`;

package/src/useIsFocused.ts

@@ -5,9 +5,9 @@
 // Based upon the useIsFocused hook which is part of the `rci` project:
 /// https://github.com/leonardodino/rci/blob/main/packages/use-is-focused
 
-import { useEffect, useRef, useState, type RefObject } from 'react';
+import { type RefObject, useEffect, useRef, useState } from 'react';
 
-export const useIsFocused = (inputRef: RefObject<HTMLInputElement>) => {
+export const useIsFocused = (inputRef: RefObject<HTMLInputElement | null>) => {
   const [isFocused, setIsFocused] = useState<boolean | undefined>(undefined);
   const isFocusedRef = useRef<boolean | undefined>(isFocused);
 

package/src/useMediaQuery.ts

@@ -6,12 +6,7 @@
 
 import { useEffect, useState } from 'react';
 
-export type UseMediaQueryOptions = {
-  fallback?: boolean | boolean[];
-  ssr?: boolean;
-};
-
-// TODO(thure): This should be derived from the same source of truth as the Tailwind theme config
+// TODO(thure): This should be derived from the same source of truth as the Tailwind theme config.
 const breakpointMediaQueries: Record<string, string> = {
   sm: '(min-width: 640px)',
   md: '(min-width: 768px)',
@@ -20,8 +15,13 @@ const breakpointMediaQueries: Record<string, string> = {
   '2xl': '(min-width: 1536px)',
 };
 
+export type UseMediaQueryOptions = {
+  fallback?: boolean | boolean[];
+  ssr?: boolean;
+};
+
 /**
- * React hook that tracks state of a CSS media query
+ * React hook that tracks state of a CSS media query.
  *
  * @param query the media query to match, or a recognized breakpoint token
  * @param options the media query options { fallback, ssr }
@@ -29,8 +29,7 @@ const breakpointMediaQueries: Record<string, string> = {
  * @see Docs https://chakra-ui.com/docs/hooks/use-media-query
  */
 export const useMediaQuery = (query: string | string[], options: UseMediaQueryOptions = {}): boolean[] => {
-  // TODO(wittjosiah): Why is the default here true?
-  const { ssr = true, fallback } = options;
+  const { ssr = false, fallback } = options;
 
   const queries = (Array.isArray(query) ? query : [query]).map((query) =>
     query in breakpointMediaQueries ? breakpointMediaQueries[query] : query,

package/src/{useMulticastObservable.test.tsx → useMulticastObservable.test.ts}

@@ -15,9 +15,7 @@ describe('useMulticastObservable', () => {
     const observable = MulticastObservable.from(event, 0);
     const { result } = renderHook(() => useMulticastObservable(observable));
     expect(result.current).toEqual(0);
-
-    await act(() => event.emit(1));
-
+    await act(async () => event.emit(1));
     await expect.poll(() => result.current).toEqual(1);
   });
 });

package/src/useTimeout.ts

@@ -0,0 +1,46 @@
+//
+// Copyright 2025 DXOS.org
+//
+
+import { useEffect, useRef } from 'react';
+
+export const useTimeout = (callback?: () => Promise<void>, delay = 0, deps: any[] = []) => {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    if (delay == null) {
+      return;
+    }
+
+    const t = setTimeout(() => callbackRef.current?.(), delay);
+    return () => clearTimeout(t);
+  }, [delay, ...deps]);
+};
+
+export const useInterval = (
+  callback?: (() => Promise<void | boolean>) | (() => void | boolean),
+  delay = 0,
+  deps: any[] = [],
+) => {
+  const callbackRef = useRef(callback);
+  useEffect(() => {
+    callbackRef.current = callback;
+  }, [callback]);
+
+  useEffect(() => {
+    if (delay == null) {
+      return;
+    }
+
+    const i = setInterval(async () => {
+      const result = await callbackRef.current?.();
+      if (result === false) {
+        clearInterval(i);
+      }
+    }, delay);
+    return () => clearInterval(i);
+  }, [delay, ...deps]);
+};

package/src/useTransitions.ts

@@ -2,7 +2,7 @@
 // Copyright 2024 DXOS.org
 //
 
-import { useRef, useEffect, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 const isFunction = <T>(functionToCheck: any): functionToCheck is (value: T) => boolean => {
   return functionToCheck instanceof Function;
@@ -48,7 +48,9 @@ export const useDidTransition = <T>(
  * Executes a callback function when a specified transition occurs in a value.
  *
  * This function utilizes the `useDidTransition` hook to monitor changes in `currentValue`.
- * When `currentValue` transitions from `fromValue` to `toValue`, the provided `callback` function is executed. */
+ * When `currentValue` transitions from `fromValue` to `toValue`, the provided `callback` function is executed.
+ */
+// TODO(wittjosiah): Seems overwrought.
 export const useOnTransition = <T>(
   currentValue: T,
   fromValue: T | ((value: T) => boolean),

package/src/{useResize.ts → useViewportResize.ts}

@@ -4,8 +4,8 @@
 
 import { useLayoutEffect, useMemo } from 'react';
 
-export const useResize = (
-  handler: (event?: Event) => void,
+export const useViewportResize = (
+  cb: (event?: Event) => void,
   deps: Parameters<typeof useLayoutEffect>[1] = [],
   delay: number = 800,
 ) => {
@@ -14,10 +14,10 @@ export const useResize = (
     return (event?: Event) => {
       clearTimeout(timeout);
       timeout = setTimeout(() => {
-        handler(event);
+        cb(event);
       }, delay);
     };
-  }, [handler, delay]);
+  }, [cb, delay]);
 
   return useLayoutEffect(() => {
     window.visualViewport?.addEventListener('resize', debouncedHandler);