@liveblocks/react 0.18.0-beta0 → 0.18.0-beta1

package/.built-by-link-script

@@ -1 +1 @@
-11a0666afa7ed3e5356b3c304466109fb37d8b87
+82a138d642402a9a15f754de8f42105c6724d0b0

package/index.d.ts

@@ -1,7 +1,31 @@
+import * as React from 'react';
+import { ReactElement, ReactNode } from 'react';
 import { JsonObject, LsonObject, LiveObject, BaseUserMeta, Json, Client, Room, BroadcastOptions, History, Others, User } from '@liveblocks/client';
-export { Json, JsonObject } from '@liveblocks/client';
+export { Json, JsonObject, shallow } from '@liveblocks/client';
 import { ToImmutable, Resolve, RoomInitializers } from '@liveblocks/client/internal';
-import * as React from 'react';
+
+declare type Props = {
+    fallback: NonNullable<ReactNode> | null;
+    children: () => ReactNode | undefined;
+};
+/**
+ * Almost like a normal <Suspense> component, except that for server-side
+ * renders, the fallback will be used.
+ *
+ * The child props will have to be provided in a function, i.e. change:
+ *
+ *   <Suspense fallback={<Loading />}>
+ *     <MyRealComponent a={1} />
+ *   </Suspense>
+ *
+ * To:
+ *
+ *   <ClientSideSuspense fallback={<Loading />}>
+ *     {() => <MyRealComponent a={1} />}
+ *   </ClientSideSuspense>
+ *
+ */
+declare function ClientSideSuspense(props: Props): ReactElement;
 
 /**
  * For any function type, returns a similar function type, but without the
@@ -210,6 +234,70 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
      *
      */
     useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
+    /**
+     * Related to useOthers(), but optimized for selecting only "subsets" of
+     * others. This is useful for performance reasons in particular, because
+     * selecting only a subset of users also means limiting the number of
+     * re-renders that will be triggered.
+     *
+     * Note that there are two ways to use this hook, and depending on how you
+     * call it, the return value will be slightly different.
+     *
+     * @example
+     * const ids = useOtherIds();
+     * //    ^^^ number[]
+     */
+    useOtherIds(): readonly number[];
+    /**
+     * Related to useOthers(), but optimized for selecting only "subsets" of
+     * others. This is useful for performance reasons in particular, because
+     * selecting only a subset of users also means limiting the number of
+     * re-renders that will be triggered.
+     *
+     * Note that there are two ways to use this hook, and depending on how you
+     * call it, the return value will be slightly different.
+     *
+     * @example
+     * const avatars = useOtherIds(user => user.info.avatar);
+     * //    ^^^^^^^
+     * //    { connectionId: number; data: string }[]
+     *
+     * The selector function you pass to useOtherIds() is called an "item
+     * selector", and operates on a single user at a time. If you provide an
+     * (optional) comparison function, it will also work on the _item_ level.
+     *
+     * For example, to select multiple properties:
+     *
+     * @example
+     * const avatarsAndCursors = useOtherIds(
+     *   user => [u.info.avatar, u.presence.cursor],
+     *   shallow,  // ❗️
+     * );
+     */
+    useOtherIds<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): readonly {
+        readonly connectionId: number;
+        readonly data: T;
+    }[];
+    /**
+     * Given a connection ID (as obtained by using `useOtherIds()`), you can call
+     * this selector deep down in your component stack to only have the component
+     * re-render if properties for this particular connection change.
+     *
+     * @example
+     * // Returns full user and re-renders whenever anything on the user changes
+     * const secondUser = useOther(2);
+     */
+    useOther(connectionId: number): User<TPresence, TUserMeta>;
+    /**
+     * Given a connection ID (as obtained by using `useOtherIds()`), you can call
+     * this selector deep down in your component stack to only have the component
+     * re-render if properties for this particular connection change.
+     *
+     * @example
+     * // Returns only the selected values re-renders whenever that selection changes)
+     * const { x, y } = useOther(2, user => user.presence.cursor);
+     */
+    useOther<T>(connectionId: number, selector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
     /**
      * Returns the Room of the nearest RoomProvider above in the React component
      * tree.
@@ -277,8 +365,18 @@ declare type RoomContextBundle<TPresence extends JsonObject, TStorage extends Ls
         useSelf<T>(selector: (me: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
         useOthers(): Others<TPresence, TUserMeta>;
         useOthers<T>(selector: (others: Others<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
+        useOtherIds(): readonly number[];
+        useOtherIds<T>(itemSelector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): readonly {
+            readonly connectionId: number;
+            readonly data: T;
+        }[];
+        useOther(connectionId: number): User<TPresence, TUserMeta>;
+        useOther<T>(connectionId: number, selector: (other: User<TPresence, TUserMeta>) => T, isEqual?: (a: T, b: T) => boolean): T;
+        useList<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey];
+        useMap<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey];
+        useObject<TKey extends Extract<keyof TStorage, string>>(key: TKey): TStorage[TKey];
     };
 };
 declare function createRoomContext<TPresence extends JsonObject, TStorage extends LsonObject = LsonObject, TUserMeta extends BaseUserMeta = BaseUserMeta, TRoomEvent extends Json = never>(client: Client): RoomContextBundle<TPresence, TStorage, TUserMeta, TRoomEvent>;
 
-export { MutationContext, createRoomContext };
+export { ClientSideSuspense, MutationContext, createRoomContext };

package/index.js

@@ -1,6 +1,19 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } }// src/factory.tsx
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _interopRequireWildcard(obj) { if (obj && obj.__esModule) { return obj; } else { var newObj = {}; if (obj != null) { for (var key in obj) { if (Object.prototype.hasOwnProperty.call(obj, key)) { newObj[key] = obj[key]; } } } newObj.default = obj; return newObj; } }// src/ClientSideSuspense.tsx
+var _react = require('react'); var React = _interopRequireWildcard(_react); var React2 = _interopRequireWildcard(_react);
+function ClientSideSuspense(props) {
+  const [mounted, setMounted] = React.useState(false);
+  React.useEffect(() => {
+    setMounted(true);
+  }, []);
+  return /* @__PURE__ */ React.createElement(React.Suspense, {
+    fallback: props.fallback
+  }, mounted ? props.children() : props.fallback);
+}
+
+// src/factory.tsx
+var _client = require('@liveblocks/client');
 var _internal = require('@liveblocks/client/internal');
-var _react = require('react'); var React = _interopRequireWildcard(_react);
+
 var _withselector = require('use-sync-external-store/shim/with-selector');
 
 // src/hooks.ts
@@ -20,21 +33,12 @@ function useInitial(value) {
 var noop = () => {
 };
 var identity = (x) => x;
-var EMPTY_OTHERS = [];
-Object.defineProperty(EMPTY_OTHERS, "count", {
-  value: 0,
-  enumerable: false
-});
-Object.defineProperty(EMPTY_OTHERS, "toArray", {
-  value: () => EMPTY_OTHERS,
-  enumerable: false
-});
-_internal.freeze.call(void 0, EMPTY_OTHERS);
+var EMPTY_OTHERS = _internal.asArrayWithLegacyMethods.call(void 0, []);
 function getEmptyOthers() {
   return EMPTY_OTHERS;
 }
 function createRoomContext(client) {
-  const RoomContext = React.createContext(null);
+  const RoomContext = React2.createContext(null);
   function RoomProvider(props) {
     const { id: roomId, initialPresence, initialStorage } = props;
     if (process.env.NODE_ENV !== "production") {
@@ -51,14 +55,14 @@ function createRoomContext(client) {
       initialPresence,
       initialStorage
     });
-    const [room, setRoom] = React.useState(
+    const [room, setRoom] = React2.useState(
       () => client.enter(roomId, {
         initialPresence,
         initialStorage,
         DO_NOT_USE_withoutConnecting: typeof window === "undefined"
       })
     );
-    React.useEffect(() => {
+    React2.useEffect(() => {
       setRoom(
         client.enter(roomId, {
           initialPresence: frozen.initialPresence,
@@ -70,12 +74,15 @@ function createRoomContext(client) {
         client.leave(roomId);
       };
     }, [roomId, frozen]);
-    return /* @__PURE__ */ React.createElement(RoomContext.Provider, {
+    return /* @__PURE__ */ React2.createElement(RoomContext.Provider, {
       value: room
     }, props.children);
   }
+  function connectionIdSelector(others) {
+    return others.map((user) => user.connectionId);
+  }
   function useRoom() {
-    const room = React.useContext(RoomContext);
+    const room = React2.useContext(RoomContext);
     if (room == null) {
       throw new Error("RoomProvider is missing from the react tree");
     }
@@ -85,11 +92,8 @@ function createRoomContext(client) {
     const room = useRoom();
     const presence = room.getPresence();
     const rerender = useRerender();
-    React.useEffect(() => room.events.me.subscribe(rerender), [room, rerender]);
-    const setPresence = React.useCallback(
-      (patch, options) => room.updatePresence(patch, options),
-      [room]
-    );
+    const setPresence = room.updatePresence;
+    React2.useEffect(() => room.events.me.subscribe(rerender), [room, rerender]);
     return [presence, setPresence];
   }
   function useUpdateMyPresence() {
@@ -98,10 +102,7 @@ function createRoomContext(client) {
   function useOthers(selector, isEqual) {
     const room = useRoom();
     const subscribe = room.events.others.subscribe;
-    const getSnapshot = React.useCallback(
-      () => room.getOthers(),
-      [room]
-    );
+    const getSnapshot = room.getOthers;
     const getServerSnapshot = getEmptyOthers;
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
@@ -111,9 +112,80 @@ function createRoomContext(client) {
       isEqual
     );
   }
+  function useOtherIds(itemSelector, isEqual) {
+    const _useCallback = React2.useCallback;
+    const _useOthers = useOthers;
+    if (itemSelector === void 0) {
+      return _useOthers(connectionIdSelector, _client.shallow);
+    } else {
+      const wrappedSelector = _useCallback(
+        (others) => others.map((other) => ({
+          connectionId: other.connectionId,
+          data: itemSelector(other)
+        })),
+        [itemSelector]
+      );
+      const wrappedIsEqual = _useCallback(
+        (a, b) => {
+          const eq = isEqual != null ? isEqual : Object.is;
+          return a.length === b.length && a.every((atuple, index) => {
+            const btuple = b[index];
+            return atuple.connectionId === btuple.connectionId && eq(atuple.data, btuple.data);
+          });
+        },
+        [isEqual]
+      );
+      return _useOthers(wrappedSelector, wrappedIsEqual);
+    }
+  }
+  const sentinel = Symbol();
+  function useOther(connectionId, selector, isEqual) {
+    const _useCallback = React2.useCallback;
+    const _useOthers = useOthers;
+    if (selector === void 0) {
+      const selector2 = _useCallback(
+        (others) => others.find((other2) => other2.connectionId === connectionId),
+        [connectionId]
+      );
+      const other = _useOthers(selector2, _client.shallow);
+      if (other === void 0) {
+        throw new Error(
+          `No such other user with connection id ${connectionId} exists`
+        );
+      }
+      return other;
+    } else {
+      const wrappedSelector = _useCallback(
+        (others) => {
+          const other2 = others.find(
+            (other3) => other3.connectionId === connectionId
+          );
+          return other2 !== void 0 ? selector(other2) : sentinel;
+        },
+        [connectionId, selector]
+      );
+      const wrappedIsEqual = _useCallback(
+        (a, b) => {
+          if (a === sentinel || b === sentinel) {
+            return a === b;
+          }
+          const eq = isEqual != null ? isEqual : Object.is;
+          return eq(a, b);
+        },
+        [isEqual]
+      );
+      const other = _useOthers(wrappedSelector, wrappedIsEqual);
+      if (other === sentinel) {
+        throw new Error(
+          `No such other user with connection id ${connectionId} exists`
+        );
+      }
+      return other;
+    }
+  }
   function useBroadcastEvent() {
     const room = useRoom();
-    return React.useCallback(
+    return React2.useCallback(
       (event, options = { shouldQueueEventIfNotReady: false }) => {
         room.broadcastEvent(event, options);
       },
@@ -122,22 +194,22 @@ function createRoomContext(client) {
   }
   function useErrorListener(callback) {
     const room = useRoom();
-    const savedCallback = React.useRef(callback);
-    React.useEffect(() => {
+    const savedCallback = React2.useRef(callback);
+    React2.useEffect(() => {
       savedCallback.current = callback;
     });
-    React.useEffect(
+    React2.useEffect(
       () => room.events.error.subscribe((e) => savedCallback.current(e)),
       [room]
     );
   }
   function useEventListener(callback) {
     const room = useRoom();
-    const savedCallback = React.useRef(callback);
-    React.useEffect(() => {
+    const savedCallback = React2.useRef(callback);
+    React2.useEffect(() => {
       savedCallback.current = callback;
     });
-    React.useEffect(() => {
+    React2.useEffect(() => {
       const listener = (eventData) => {
         savedCallback.current(eventData);
       };
@@ -146,7 +218,7 @@ function createRoomContext(client) {
   }
   function useSelf(maybeSelector, isEqual) {
     const room = useRoom();
-    const subscribe = React.useCallback(
+    const subscribe = React2.useCallback(
       (onChange) => {
         const unsub1 = room.events.me.subscribe(onChange);
         const unsub2 = room.events.connection.subscribe(onChange);
@@ -159,11 +231,11 @@ function createRoomContext(client) {
     );
     const getSnapshot = room.getSelf;
     const selector = maybeSelector != null ? maybeSelector : identity;
-    const wrappedSelector = React.useCallback(
+    const wrappedSelector = React2.useCallback(
       (me) => me !== null ? selector(me) : null,
       [selector]
     );
-    const getServerSnapshot = React.useCallback(() => null, []);
+    const getServerSnapshot = React2.useCallback(() => null, []);
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
       getSnapshot,
@@ -176,7 +248,7 @@ function createRoomContext(client) {
     const room = useRoom();
     const subscribe = room.events.storageDidLoad.subscribeOnce;
     const getSnapshot = room.getStorageSnapshot;
-    const getServerSnapshot = React.useCallback(() => null, []);
+    const getServerSnapshot = React2.useCallback(() => null, []);
     const selector = identity;
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
@@ -199,8 +271,8 @@ function createRoomContext(client) {
   }
   function useCanUndo() {
     const room = useRoom();
-    const [canUndo, setCanUndo] = React.useState(room.history.canUndo);
-    React.useEffect(
+    const [canUndo, setCanUndo] = React2.useState(room.history.canUndo);
+    React2.useEffect(
       () => room.events.history.subscribe(({ canUndo: canUndo2 }) => setCanUndo(canUndo2)),
       [room]
     );
@@ -208,8 +280,8 @@ function createRoomContext(client) {
   }
   function useCanRedo() {
     const room = useRoom();
-    const [canRedo, setCanRedo] = React.useState(room.history.canRedo);
-    React.useEffect(
+    const [canRedo, setCanRedo] = React2.useState(room.history.canRedo);
+    React2.useEffect(
       () => room.events.history.subscribe(({ canRedo: canRedo2 }) => setCanRedo(canRedo2)),
       [room]
     );
@@ -222,7 +294,7 @@ function createRoomContext(client) {
     const room = useRoom();
     const root = useMutableStorageRoot();
     const rerender = useRerender();
-    React.useEffect(() => {
+    React2.useEffect(() => {
       if (root == null) {
         return;
       }
@@ -263,15 +335,15 @@ function createRoomContext(client) {
     const room = useRoom();
     const rootOrNull = useMutableStorageRoot();
     const selector = maybeSelector != null ? maybeSelector : identity;
-    const wrappedSelector = React.useCallback(
+    const wrappedSelector = React2.useCallback(
       (rootOrNull2) => rootOrNull2 !== null ? selector(rootOrNull2) : null,
       [selector]
     );
-    const subscribe = React.useCallback(
+    const subscribe = React2.useCallback(
       (onStoreChange) => rootOrNull !== null ? room.subscribe(rootOrNull, onStoreChange, { isDeep: true }) : noop,
       [room, rootOrNull]
     );
-    const getSnapshot = React.useCallback(() => {
+    const getSnapshot = React2.useCallback(() => {
       if (rootOrNull === null) {
         return null;
       } else {
@@ -280,7 +352,7 @@ function createRoomContext(client) {
         return imm;
       }
     }, [rootOrNull]);
-    const getServerSnapshot = React.useCallback(() => null, []);
+    const getServerSnapshot = React2.useCallback(() => null, []);
     return _withselector.useSyncExternalStoreWithSelector.call(void 0, 
       subscribe,
       getSnapshot,
@@ -320,7 +392,7 @@ function createRoomContext(client) {
     const room = useRoom();
     const root = useMutableStorageRoot();
     const setMyPresence = room.updatePresence;
-    return React.useMemo(
+    return React2.useMemo(
       () => {
         if (root !== null) {
           const mutationCtx = {
@@ -366,6 +438,25 @@ function createRoomContext(client) {
       isEqual
     );
   }
+  function useOtherIdsSuspense(itemSelector, isEqual) {
+    useSuspendUntilPresenceLoaded();
+    return useOtherIds(
+      itemSelector,
+      isEqual
+    );
+  }
+  function useOtherSuspense(connectionId, selector, isEqual) {
+    useSuspendUntilPresenceLoaded();
+    return useOther(
+      connectionId,
+      selector,
+      isEqual
+    );
+  }
+  function useLegacyKeySuspense(key) {
+    useSuspendUntilStorageLoaded();
+    return useLegacyKey(key);
+  }
   return {
     RoomProvider,
     useBatch,
@@ -377,6 +468,8 @@ function createRoomContext(client) {
     useHistory,
     useMyPresence,
     useOthers,
+    useOtherIds,
+    useOther,
     useRedo,
     useRoom,
     useSelf,
@@ -392,10 +485,20 @@ function createRoomContext(client) {
     suspense: {
       useStorage: useStorageSuspense,
       useSelf: useSelfSuspense,
-      useOthers: useOthersSuspense
+      useOthers: useOthersSuspense,
+      useOtherIds: useOtherIdsSuspense,
+      useOther: useOtherSuspense,
+      useList: useLegacyKeySuspense,
+      useMap: useLegacyKeySuspense,
+      useObject: useLegacyKeySuspense
     }
   };
 }
 
+// src/index.ts
+
+
+
+
 
-exports.createRoomContext = createRoomContext;
+exports.ClientSideSuspense = ClientSideSuspense; exports.createRoomContext = createRoomContext; exports.shallow = _client.shallow;

package/index.mjs

@@ -1,4 +1,6 @@
 import mod from "./index.js";
 
 export default mod;
+export const ClientSideSuspense = mod.ClientSideSuspense;
 export const createRoomContext = mod.createRoomContext;
+export const shallow = mod.shallow;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/react",
-  "version": "0.18.0-beta0",
+  "version": "0.18.0-beta1",
   "description": "A set of React hooks and providers to use Liveblocks declaratively.",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -27,7 +27,7 @@
     "use-sync-external-store": "^1.2.0"
   },
   "peerDependencies": {
-    "@liveblocks/client": "0.18.0-beta0",
+    "@liveblocks/client": "0.18.0-beta1",
     "react": "^16.14.0 || ^17 || ^18"
   },
   "repository": {