@dxos/react-hooks 0.8.4-main.5ad4a44 → 0.8.4-main.66e292d

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dxos/react-hooks",
-  "version": "0.8.4-main.5ad4a44",
+  "version": "0.8.4-main.66e292d",
   "description": "React hooks supporting DXOS React primitives.",
   "homepage": "https://dxos.org",
   "bugs": "https://github.com/dxos/dxos/issues",
@@ -26,15 +26,17 @@
   ],
   "dependencies": {
     "@preact-signals/safe-react": "^0.9.0",
+    "@radix-ui/react-use-controllable-state": "^1.2.2",
     "alea": "^1.0.1",
     "lodash.defaultsdeep": "^4.6.1",
-    "@dxos/async": "0.8.4-main.5ad4a44",
-    "@dxos/log": "0.8.4-main.5ad4a44"
+    "mini-virtual-list": "^0.3.2",
+    "@dxos/async": "0.8.4-main.66e292d",
+    "@dxos/log": "0.8.4-main.66e292d"
   },
   "devDependencies": {
     "@types/lodash.defaultsdeep": "^4.6.6",
     "@types/react": "~19.2.2",
-    "@types/react-dom": "~19.2.1",
+    "@types/react-dom": "~19.2.2",
     "react": "~19.2.0",
     "react-dom": "~19.2.0"
   },

package/src/index.ts

@@ -16,7 +16,9 @@ export * from './useIsFocused';
 export * from './useMediaQuery';
 export * from './useMulticastObservable';
 export * from './useRefCallback';
-export * from './useResize';
+export * from './useViewportResize';
 export * from './useSignals';
 export * from './useTimeout';
 export * from './useTransitions';
+
+export { useSize, useScroller } from 'mini-virtual-list';

package/src/useControlledState.ts

@@ -2,27 +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: Be careful not to provide an inlinde default array.
+ * @deprecated Use Radix `useControllableState` (NOTE: `useControlledState` is not compatible with `useControllableState`)
  */
 export const useControlledState = <T>(
-  controlledValue: T,
+  valueParam: T,
   onChange?: (value: T) => void,
-  ...deps: any[]
 ): [T, Dispatch<SetStateAction<T>>] => {
-  const [value, setValue] = useState<T>(controlledValue);
+  const [value, setControlledValue] = useState(valueParam);
   useEffect(() => {
-    if (controlledValue !== undefined) {
-      setValue(controlledValue);
-    }
-  }, [controlledValue, ...deps]);
+    setControlledValue(valueParam);
+  }, [valueParam]);
 
-  useEffect(() => {
-    onChange?.(value);
-  }, [value, onChange]);
+  const onChangeRef = useRef(onChange);
+  const valueRef = useDynamicRef(valueParam);
+  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/useDynamicRef.ts

@@ -2,13 +2,12 @@
 // Copyright 2024 DXOS.org
 //
 
-import { useCallback } from '@preact-signals/safe-react/react';
-import { type Dispatch, type MutableRefObject, type SetStateAction, useEffect, useRef, useState } 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>(valueParam: T): [T, Dispatch<SetStateAction<T>>, MutableRefObject<T>] => {
+export const useStateWithRef = <T>(valueParam: T): [T, Dispatch<SetStateAction<T>>, RefObject<T>] => {
   const [value, setValue] = useState<T>(valueParam);
   const valueRef = useRef<T>(valueParam);
   const setter = useCallback<Dispatch<SetStateAction<T>>>((value) => {
@@ -29,7 +28,7 @@ export const useStateWithRef = <T>(valueParam: T): [T, Dispatch<SetStateAction<T
 /**
  * Ref that is updated by a dependency.
  */
-export const useDynamicRef = <T>(value: T): MutableRefObject<T> => {
+export const useDynamicRef = <T>(value: T): RefObject<T> => {
   const valueRef = useRef<T>(value);
   useEffect(() => {
     valueRef.current = value;

package/src/useForwardedRef.ts

@@ -2,25 +2,60 @@
 // Copyright 2022 DXOS.org
 //
 
-import { type ForwardedRef, useEffect, useRef } 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.
- * @deprecated Use `useComposedRefs` from @radix-ui/react-compose-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/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 }

package/src/useMulticastObservable.test.ts

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

package/src/useSignals.ts

@@ -3,8 +3,7 @@
 //
 
 import { computed, effect } from '@preact-signals/safe-react';
-import { useRef } from '@preact-signals/safe-react/react';
-import { type DependencyList, useEffect, useMemo } from 'react';
+import { type DependencyList, useEffect, useMemo, useRef } from 'react';
 
 /**
  * Like `useEffect` but also tracks signals inside of the callback.

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

@@ -4,7 +4,7 @@
 
 import { useLayoutEffect, useMemo } from 'react';
 
-export const useResize = (
+export const useViewportResize = (
   handler: (event?: Event) => void,
   deps: Parameters<typeof useLayoutEffect>[1] = [],
   delay: number = 800,

package/dist/types/src/useResize.d.ts

@@ -1,3 +0,0 @@
-import { useLayoutEffect } from 'react';
-export declare const useResize: (handler: (event?: Event) => void, deps?: Parameters<typeof useLayoutEffect>[1], delay?: number) => void;
-//# sourceMappingURL=useResize.d.ts.map

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

@@ -1 +0,0 @@
-{"version":3,"file":"useResize.d.ts","sourceRoot":"","sources":["../../../src/useResize.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,eAAe,EAAW,MAAM,OAAO,CAAC;AAEjD,eAAO,MAAM,SAAS,GACpB,SAAS,CAAC,KAAK,CAAC,EAAE,KAAK,KAAK,IAAI,EAChC,OAAM,UAAU,CAAC,OAAO,eAAe,CAAC,CAAC,CAAC,CAAM,EAChD,QAAO,MAAY,SAiBpB,CAAC"}