@liveblocks/react 1.10.4 → 1.11.0

package/dist/index.d.mts

@@ -28,9 +28,25 @@ declare type Props = {
 declare function ClientSideSuspense(props: Props): ReactElement;
 
 declare type UseThreadsOptions<TThreadMetadata extends BaseMetadata> = {
+    /**
+     * The query (including metadata) to filter the threads by. If provided, only threads
+     * that match the query will be returned. If not provided, all threads will be returned.
+     */
     query?: {
+        /**
+         * The metadata to filter the threads by. If provided, only threads with metadata that matches
+         * the provided metadata will be returned. If not provided, all threads will be returned.
+         */
         metadata?: Partial<TThreadMetadata>;
     };
+    /**
+     * Whether to scroll to a comment on load based on the URL hash. Defaults to `true`.
+     *
+     * @example
+     * Given the URL `https://example.com/my-room#cm_xxx`, the `cm_xxx` comment will be
+     * scrolled to on load if it exists in the page.
+     */
+    scrollOnLoad?: boolean;
 };
 
 declare type UserStateLoading = {
@@ -1045,7 +1061,7 @@ declare type LiveblocksContextBundle<TUserMeta extends BaseUserMeta> = Resolve<L
  * This is an internal API, use "createLiveblocksContext" instead.
  */
 declare function useLiveblocksContextBundle(): LiveblocksContextBundle<BaseUserMeta>;
-declare function createLiveblocksContext<TUserMeta extends BaseUserMeta = BaseUserMeta, TThreadMetadata extends BaseMetadata$1 = never>(client: Client<TUserMeta>): LiveblocksContextBundle<TUserMeta>;
+declare function createLiveblocksContext<TUserMeta extends BaseUserMeta = BaseUserMeta, TThreadMetadata extends BaseMetadata$1 = never>(client: Client): LiveblocksContextBundle<TUserMeta>;
 
 /**
  * @private

package/dist/index.d.ts

@@ -28,9 +28,25 @@ declare type Props = {
 declare function ClientSideSuspense(props: Props): ReactElement;
 
 declare type UseThreadsOptions<TThreadMetadata extends BaseMetadata> = {
+    /**
+     * The query (including metadata) to filter the threads by. If provided, only threads
+     * that match the query will be returned. If not provided, all threads will be returned.
+     */
     query?: {
+        /**
+         * The metadata to filter the threads by. If provided, only threads with metadata that matches
+         * the provided metadata will be returned. If not provided, all threads will be returned.
+         */
         metadata?: Partial<TThreadMetadata>;
     };
+    /**
+     * Whether to scroll to a comment on load based on the URL hash. Defaults to `true`.
+     *
+     * @example
+     * Given the URL `https://example.com/my-room#cm_xxx`, the `cm_xxx` comment will be
+     * scrolled to on load if it exists in the page.
+     */
+    scrollOnLoad?: boolean;
 };
 
 declare type UserStateLoading = {
@@ -1045,7 +1061,7 @@ declare type LiveblocksContextBundle<TUserMeta extends BaseUserMeta> = Resolve<L
  * This is an internal API, use "createLiveblocksContext" instead.
  */
 declare function useLiveblocksContextBundle(): LiveblocksContextBundle<BaseUserMeta>;
-declare function createLiveblocksContext<TUserMeta extends BaseUserMeta = BaseUserMeta, TThreadMetadata extends BaseMetadata$1 = never>(client: Client<TUserMeta>): LiveblocksContextBundle<TUserMeta>;
+declare function createLiveblocksContext<TUserMeta extends BaseUserMeta = BaseUserMeta, TThreadMetadata extends BaseMetadata$1 = never>(client: Client): LiveblocksContextBundle<TUserMeta>;
 
 /**
  * @private

package/dist/index.js

@@ -5,7 +5,7 @@ var _core = require('@liveblocks/core');
 
 // src/version.ts
 var PKG_NAME = "@liveblocks/react";
-var PKG_VERSION = "1.10.4";
+var PKG_VERSION = "1.11.0";
 var PKG_FORMAT = "cjs";
 
 // src/ClientSideSuspense.tsx
@@ -895,7 +895,33 @@ function createRoomContext(client, options) {
       return;
     }
   }
-  function useThreads(options2 = { query: { metadata: {} } }) {
+  function handleScrollToCommentOnLoad(isQueryLoading, shouldScrollOnLoad, state) {
+    if (shouldScrollOnLoad === false)
+      return;
+    if (isQueryLoading === true)
+      return;
+    const isWindowDefined = typeof window !== "undefined";
+    if (!isWindowDefined)
+      return;
+    const hash = window.location.hash;
+    const commentId = hash.slice(1);
+    if (!commentId.startsWith("cm_"))
+      return;
+    const comment = document.getElementById(commentId);
+    if (comment === null)
+      return;
+    const comments = state.threads.flatMap((thread) => thread.comments);
+    const isCommentInThreads = comments.some(
+      (comment2) => comment2.id === commentId
+    );
+    if (!isCommentInThreads)
+      return;
+    comment.scrollIntoView();
+  }
+  function useThreads(options2 = {
+    query: { metadata: {} }
+  }) {
+    const { scrollOnLoad = true } = options2;
     const room = useRoom();
     const queryKey = React2.useMemo(
       () => generateQueryKey(room.id, options2.query),
@@ -907,15 +933,15 @@ function createRoomContext(client, options) {
       return () => decrementQuerySubscribers(queryKey);
     }, [room, queryKey]);
     const selector = React2.useCallback(
-      (state) => {
-        const query = state.queries[queryKey];
+      (state2) => {
+        const query = state2.queries[queryKey];
         if (query === void 0 || query.isLoading) {
           return {
             isLoading: true
           };
         }
         return {
-          threads: selectedThreads(room.id, state, options2),
+          threads: selectedThreads(room.id, state2, options2),
           isLoading: false,
           error: query.error
         };
@@ -923,17 +949,30 @@ function createRoomContext(client, options) {
       [room, queryKey]
       // eslint-disable-line react-hooks/exhaustive-deps
     );
-    return _withselectorjs.useSyncExternalStoreWithSelector.call(void 0, 
+    const state = _withselectorjs.useSyncExternalStoreWithSelector.call(void 0, 
       store.subscribe,
       store.get,
       store.get,
       selector
     );
+    React2.useEffect(
+      () => {
+        if (state.isLoading === true)
+          return;
+        handleScrollToCommentOnLoad(state.isLoading, scrollOnLoad, state);
+      },
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- We only want to run this effect once
+      [state.isLoading]
+    );
+    return state;
   }
-  function useThreadsSuspense(options2 = { query: { metadata: {} } }) {
+  function useThreadsSuspense(options2 = {
+    query: { metadata: {} }
+  }) {
+    const { scrollOnLoad = true } = options2;
     const room = useRoom();
     const queryKey = React2.useMemo(
-      () => generateQueryKey(room.id, _optionalChain([options2, 'optionalAccess', _5 => _5.query])),
+      () => generateQueryKey(room.id, options2.query),
       [room, options2]
     );
     const query = store.get().queries[queryKey];
@@ -944,9 +983,9 @@ function createRoomContext(client, options) {
       throw query.error;
     }
     const selector = React2.useCallback(
-      (state) => {
+      (state2) => {
         return {
-          threads: selectedThreads(room.id, state, options2),
+          threads: selectedThreads(room.id, state2, options2),
           isLoading: false
         };
       },
@@ -959,12 +998,20 @@ function createRoomContext(client, options) {
         decrementQuerySubscribers(queryKey);
       };
     }, [queryKey]);
-    return _withselectorjs.useSyncExternalStoreWithSelector.call(void 0, 
+    const state = _withselectorjs.useSyncExternalStoreWithSelector.call(void 0, 
       store.subscribe,
       store.get,
       store.get,
       selector
     );
+    React2.useEffect(
+      () => {
+        handleScrollToCommentOnLoad(state.isLoading, scrollOnLoad, state);
+      },
+      // eslint-disable-next-line react-hooks/exhaustive-deps -- We only want to run this effect once
+      [state.isLoading]
+    );
+    return state;
   }
   function useCreateThread() {
     const room = useRoom();
@@ -1448,7 +1495,7 @@ function createRoomContext(client, options) {
             );
           }
         } catch (error) {
-          _core.console.error(_optionalChain([error, 'optionalAccess', _6 => _6.message]));
+          _core.console.error(_optionalChain([error, 'optionalAccess', _5 => _5.message]));
         }
       };
       if (mentionSuggestionsCache.has(mentionSuggestionsCacheKey)) {
@@ -1780,7 +1827,7 @@ function getCurrentUserId(room) {
 }
 function handleApiError(err) {
   const message = `Request failed with status ${err.status}: ${err.message}`;
-  if (_optionalChain([err, 'access', _7 => _7.details, 'optionalAccess', _8 => _8.error]) === "FORBIDDEN") {
+  if (_optionalChain([err, 'access', _6 => _6.details, 'optionalAccess', _7 => _7.error]) === "FORBIDDEN") {
     const detailedMessage = [message, err.details.suggestion, err.details.docs].filter(Boolean).join("\n");
     _core.console.error(detailedMessage);
   }
@@ -1804,6 +1851,12 @@ function useSharedContextBundle() {
     );
   }
 }
+var missingUserError = new Error(
+  "resolveUsers didn't return anything for this user ID."
+);
+var missingRoomInfoError = new Error(
+  "resolveRoomsInfo didn't return anything for this room ID."
+);
 function createSharedContext(client) {
   const usersStore = client[_core.kInternal].usersStore;
   const roomsInfoStore = client[_core.kInternal].roomsInfoStore;
@@ -1821,8 +1874,10 @@ function createSharedContext(client) {
       getUserState
     );
     return state ? {
-      ...state,
-      user: state.data
+      isLoading: state.isLoading,
+      user: state.data,
+      // Return an error if `undefined` was returned by `resolveUsers` for this user ID
+      error: !state.isLoading && !state.data && !state.error ? missingUserError : state.error
     } : { isLoading: true };
   }
   function useUserSuspense(userId) {
@@ -1837,14 +1892,18 @@ function createSharedContext(client) {
     if (userState.error) {
       throw userState.error;
     }
+    if (!userState.data) {
+      throw missingUserError;
+    }
     const state = _indexjs.useSyncExternalStore.call(void 0, 
       usersStore.subscribe,
       getUserState,
       getUserState
     );
     return {
-      ...state,
-      user: _optionalChain([state, 'optionalAccess', _9 => _9.data])
+      isLoading: false,
+      user: _optionalChain([state, 'optionalAccess', _8 => _8.data]),
+      error: _optionalChain([state, 'optionalAccess', _9 => _9.error])
     };
   }
   function useRoomInfo(roomId) {
@@ -1861,8 +1920,10 @@ function createSharedContext(client) {
       getRoomInfoState
     );
     return state ? {
-      ...state,
-      info: state.data
+      isLoading: state.isLoading,
+      info: state.data,
+      // Return an error if `undefined` was returned by `resolveRoomsInfo` for this room ID
+      error: !state.isLoading && !state.data && !state.error ? missingRoomInfoError : state.error
     } : { isLoading: true };
   }
   function useRoomInfoSuspense(roomId) {
@@ -1877,14 +1938,18 @@ function createSharedContext(client) {
     if (roomInfoState.error) {
       throw roomInfoState.error;
     }
+    if (!roomInfoState.data) {
+      throw missingRoomInfoError;
+    }
     const state = _indexjs.useSyncExternalStore.call(void 0, 
       roomsInfoStore.subscribe,
       getRoomInfoState,
       getRoomInfoState
     );
     return {
-      ...state,
-      info: _optionalChain([state, 'optionalAccess', _10 => _10.data])
+      isLoading: false,
+      info: _optionalChain([state, 'optionalAccess', _10 => _10.data]),
+      error: _optionalChain([state, 'optionalAccess', _11 => _11.error])
     };
   }
   const bundle = {