@liveblocks/react 0.17.1 → 0.17.4

package/index.d.ts

@@ -52,32 +52,122 @@ declare type RoomProviderProps<
     children: React.ReactNode;
   } & RoomInitializers<TPresence, TStorage>
 >;
-declare function createRoomContext<
+declare type RoomContext<
   TPresence extends JsonObject,
-  TStorage extends LsonObject = LsonObject,
-  TUserMeta extends BaseUserMeta = BaseUserMeta,
-  TRoomEvent extends Json = never
->(
-  client: Client
-): {
-  RoomProvider: (props: RoomProviderProps<TPresence, TStorage>) => JSX.Element;
-  useBatch: () => (callback: () => void) => void;
-  useBroadcastEvent: () => (
-    event: TRoomEvent,
-    options?: BroadcastOptions
-  ) => void;
-  useErrorListener: (callback: (err: Error) => void) => void;
-  useEventListener: (
+  TStorage extends LsonObject,
+  TUserMeta extends BaseUserMeta,
+  TRoomEvent extends Json
+> = {
+  /**
+   * Makes a Room available in the component hierarchy below.
+   * When this component is unmounted, the current user leave the room.
+   * That means that you can't have 2 RoomProvider with the same room id in your react tree.
+   */
+  RoomProvider(props: RoomProviderProps<TPresence, TStorage>): JSX.Element;
+  /**
+   * Returns a function that batches modifications made during the given function.
+   * All the modifications are sent to other clients in a single message.
+   * All the modifications are merged in a single history item (undo/redo).
+   * All the subscribers are called only after the batch is over.
+   */
+  useBatch(): (callback: () => void) => void;
+  /**
+   * Returns a callback that lets you broadcast custom events to other users in the room
+   *
+   * @example
+   * const broadcast = useBroadcastEvent();
+   *
+   * broadcast({ type: "CUSTOM_EVENT", data: { x: 0, y: 0 } });
+   */
+  useBroadcastEvent(): (event: TRoomEvent, options?: BroadcastOptions) => void;
+  /**
+   * useErrorListener is a react hook that lets you react to potential room connection errors.
+   *
+   * @example
+   * useErrorListener(er => {
+   *   console.error(er);
+   * })
+   */
+  useErrorListener(callback: (err: Error) => void): void;
+  /**
+   * useEventListener is a react hook that lets you react to event broadcasted by other users in the room.
+   *
+   * @example
+   * useEventListener(({ connectionId, event }) => {
+   *   if (event.type === "CUSTOM_EVENT") {
+   *     // Do something
+   *   }
+   * });
+   */
+  useEventListener(
     callback: (eventData: { connectionId: number; event: TRoomEvent }) => void
-  ) => void;
-  useHistory: () => History;
-  useList: <TKey extends Extract<keyof TStorage, string>>(
+  ): void;
+  /**
+   * Returns the room.history
+   */
+  useHistory(): History;
+  /**
+   * Returns a function that undoes the last operation executed by the current client.
+   * It does not impact operations made by other clients.
+   */
+  useUndo(): () => void;
+  /**
+   * Returns a function that redoes the last operation executed by the current client.
+   * It does not impact operations made by other clients.
+   */
+  useRedo(): () => void;
+  /**
+   * Returns the LiveList associated with the provided key.
+   * The hook triggers a re-render if the LiveList is updated, however it does not triggers a re-render if a nested CRDT is updated.
+   *
+   * @param key The storage key associated with the LiveList
+   * @returns null while the storage is loading, otherwise, returns the LiveList associated to the storage
+   *
+   * @example
+   * const animals = useList("animals");  // e.g. [] or ["🦁", "🐍", "🦍"]
+   */
+  useList<TKey extends Extract<keyof TStorage, string>>(
+    key: TKey
+  ): TStorage[TKey] | null;
+  /**
+   * Returns the LiveMap associated with the provided key. If the LiveMap does not exist, a new empty LiveMap will be created.
+   * The hook triggers a re-render if the LiveMap is updated, however it does not triggers a re-render if a nested CRDT is updated.
+   *
+   * @param key The storage key associated with the LiveMap
+   * @returns null while the storage is loading, otherwise, returns the LiveMap associated to the storage
+   *
+   * @example
+   * const shapesById = useMap("shapes");
+   */
+  useMap<TKey extends Extract<keyof TStorage, string>>(
     key: TKey
-  ) => TStorage[TKey] | null;
-  useMap: <TKey_1 extends Extract<keyof TStorage, string>>(
-    key: TKey_1
-  ) => TStorage[TKey_1] | null;
-  useMyPresence: () => [
+  ): TStorage[TKey] | null;
+  /**
+   * Returns the LiveObject associated with the provided key.
+   * The hook triggers a re-render if the LiveObject is updated, however it does not triggers a re-render if a nested CRDT is updated.
+   *
+   * @param key The storage key associated with the LiveObject
+   * @returns null while the storage is loading, otherwise, returns the LveObject associated to the storage
+   *
+   * @example
+   * const object = useObject("obj");
+   */
+  useObject<TKey extends Extract<keyof TStorage, string>>(
+    key: TKey
+  ): TStorage[TKey] | null;
+  /**
+   * Returns the presence of the current user of the current room, and a function to update it.
+   * It is different from the setState function returned by the useState hook from React.
+   * You don't need to pass the full presence object to update it.
+   *
+   * @example
+   * const [myPresence, updateMyPresence] = useMyPresence();
+   * updateMyPresence({ x: 0 });
+   * updateMyPresence({ y: 0 });
+   *
+   * // At the next render, "myPresence" will be equal to "{ x: 0, y: 0 }"
+   */
+  useMyPresence(): [
     TPresence,
     (
       overrides: Partial<TPresence>,
@@ -86,46 +176,128 @@ declare function createRoomContext<
       }
     ) => void
   ];
-  useObject: <TKey_2 extends Extract<keyof TStorage, string>>(
-    key: TKey_2
-  ) => TStorage[TKey_2] | null;
-  useOthers: () => Others<TPresence, TUserMeta>;
-  useRedo: () => () => void;
-  useRoom: () => Room<TPresence, TStorage, TUserMeta, TRoomEvent>;
-  useSelf: () => User<TPresence, TUserMeta> | null;
-  useStorage: () => [root: LiveObject<TStorage> | null];
-  useUndo: () => () => void;
-  useUpdateMyPresence: () => (
+  /**
+   * Returns an object that lets you get information about all the the users currently connected in the room.
+   *
+   * @example
+   * const others = useOthers();
+   *
+   * // Example to map all cursors in JSX
+   * {
+   *   others.map((user) => {
+   *     if (user.presence?.cursor == null) {
+   *       return null;
+   *     }
+   *     return <Cursor key={user.connectionId} cursor={user.presence.cursor} />
+   *   })
+   * }
+   */
+  useOthers(): Others<TPresence, TUserMeta>;
+  /**
+   * Returns the Room of the nearest RoomProvider above in the React component
+   * tree.
+   */
+  useRoom(): Room<TPresence, TStorage, TUserMeta, TRoomEvent>;
+  /**
+   * Gets the current user once it is connected to the room.
+   *
+   * @example
+   * const user = useSelf();
+   */
+  useSelf(): User<TPresence, TUserMeta> | null;
+  /**
+   * Returns the LiveObject instance that is the root of your entire Liveblocks
+   * Storage.
+   *
+   * @example
+   * const [root] = useStorage();
+   */
+  useStorage(): [root: LiveObject<TStorage> | null];
+  /**
+   * useUpdateMyPresence is similar to useMyPresence but it only returns the function to update the current user presence.
+   * If you don't use the current user presence in your component, but you need to update it (e.g. live cursor), it's better to use useUpdateMyPresence to avoid unnecessary renders.
+   *
+   * @example
+   * const updateMyPresence = useUpdateMyPresence();
+   * updateMyPresence({ x: 0 });
+   * updateMyPresence({ y: 0 });
+   *
+   * // At the next render, the presence of the current user will be equal to "{ x: 0, y: 0 }"
+   */
+  useUpdateMyPresence(): (
     overrides: Partial<TPresence>,
     options?: {
       addToHistory: boolean;
     }
   ) => void;
-  deprecated_useList: {
-    <TValue extends Lson>(key: string): LiveList<TValue> | null;
-    <TValue_1 extends Lson>(
-      key: string,
-      items: TValue_1[]
-    ): LiveList<TValue_1> | null;
-  };
-  deprecated_useMap: {
-    <TKey_3 extends string, TValue_2 extends Lson>(key: string): LiveMap<
-      TKey_3,
-      TValue_2
-    > | null;
-    <TKey_4 extends string, TValue_3 extends Lson>(
-      key: string,
-      entries: readonly (readonly [TKey_4, TValue_3])[] | null
-    ): LiveMap<TKey_4, TValue_3> | null;
-  };
-  deprecated_useObject: {
-    <TData extends LsonObject>(key: string): LiveObject<TData> | null;
-    <TData_1 extends LsonObject>(
-      key: string,
-      initialData: TData_1
-    ): LiveObject<TData_1> | null;
-  };
+  /**
+   * Returns the LiveList associated with the provided key.
+   * The hook triggers a re-render if the LiveList is updated, however it does not triggers a re-render if a nested CRDT is updated.
+   *
+   * @param key The storage key associated with the LiveList
+   * @returns null while the storage is loading, otherwise, returns the LiveList associated to the storage
+   *
+   * @example
+   * const animals = useList("animals");  // e.g. [] or ["🦁", "🐍", "🦍"]
+   */
+  deprecated_useList<TValue extends Lson>(key: string): LiveList<TValue> | null;
+  /**
+   * @deprecated We no longer recommend initializing the
+   * items from the useList() hook. For details, see https://bit.ly/3Niy5aP.
+   */
+  deprecated_useList<TValue extends Lson>(
+    key: string,
+    items: TValue[]
+  ): LiveList<TValue> | null;
+  /**
+   * Returns the LiveMap associated with the provided key. If the LiveMap does not exist, a new empty LiveMap will be created.
+   * The hook triggers a re-render if the LiveMap is updated, however it does not triggers a re-render if a nested CRDT is updated.
+   *
+   * @param key The storage key associated with the LiveMap
+   * @returns null while the storage is loading, otherwise, returns the LiveMap associated to the storage
+   *
+   * @example
+   * const shapesById = useMap("shapes");
+   */
+  deprecated_useMap<TKey extends string, TValue extends Lson>(
+    key: string
+  ): LiveMap<TKey, TValue> | null;
+  /**
+   * @deprecated We no longer recommend initializing the
+   * entries from the useMap() hook. For details, see https://bit.ly/3Niy5aP.
+   */
+  deprecated_useMap<TKey extends string, TValue extends Lson>(
+    key: string,
+    entries: readonly (readonly [TKey, TValue])[] | null
+  ): LiveMap<TKey, TValue> | null;
+  /**
+   * Returns the LiveObject associated with the provided key.
+   * The hook triggers a re-render if the LiveObject is updated, however it does not triggers a re-render if a nested CRDT is updated.
+   *
+   * @param key The storage key associated with the LiveObject
+   * @returns null while the storage is loading, otherwise, returns the LveObject associated to the storage
+   *
+   * @example
+   * const object = useObject("obj");
+   */
+  deprecated_useObject<TData extends LsonObject>(
+    key: string
+  ): LiveObject<TData> | null;
+  /**
+   * @deprecated We no longer recommend initializing the fields from the
+   * useObject() hook. For details, see https://bit.ly/3Niy5aP.
+   */
+  deprecated_useObject<TData extends LsonObject>(
+    key: string,
+    initialData: TData
+  ): LiveObject<TData> | null;
 };
+declare function createRoomContext<
+  TPresence extends JsonObject,
+  TStorage extends LsonObject = LsonObject,
+  TUserMeta extends BaseUserMeta = BaseUserMeta,
+  TRoomEvent extends Json = never
+>(client: Client): RoomContext<TPresence, TStorage, TUserMeta, TRoomEvent>;
 
 /**
  * NOTE:

package/index.js

@@ -75,9 +75,9 @@ function createRoomContext(client$1) {
           return client$1;
         }
       : useClient;
-  var RoomContext = React__namespace.createContext(null);
+  var RoomCtx = React__namespace.createContext(null);
   function useRoom() {
-    var room = React__namespace.useContext(RoomContext);
+    var room = React__namespace.useContext(RoomCtx);
     if (null == room)
       throw new Error("RoomProvider is missing from the react tree");
     return room;
@@ -285,7 +285,7 @@ function createRoomContext(client$1) {
           [_client, roomId]
         ),
         React__namespace.createElement(
-          RoomContext.Provider,
+          RoomCtx.Provider,
           { value: room },
           props.children
         )

package/index.mjs

@@ -58,9 +58,9 @@ function useRerender() {
 function createRoomContext(client) {
   let useClient$1;
   useClient$1 = "__legacy" !== client ? () => client : useClient;
-  const RoomContext = React.createContext(null);
+  const RoomCtx = React.createContext(null);
   function useRoom() {
-    const room = React.useContext(RoomContext);
+    const room = React.useContext(RoomCtx);
     if (null == room)
       throw new Error("RoomProvider is missing from the react tree");
     return room;
@@ -241,11 +241,7 @@ function createRoomContext(client) {
           ),
           [_client, roomId]
         ),
-        React.createElement(
-          RoomContext.Provider,
-          { value: room },
-          props.children
-        )
+        React.createElement(RoomCtx.Provider, { value: room }, props.children)
       );
     },
     useBatch: function () {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@liveblocks/react",
-  "version": "0.17.1",
+  "version": "0.17.4",
   "description": "A set of React hooks and providers to use Liveblocks declaratively.",
   "main": "./index.js",
   "module": "./index.mjs",
@@ -29,7 +29,7 @@
   },
   "license": "Apache-2.0",
   "peerDependencies": {
-    "@liveblocks/client": "0.17.1",
+    "@liveblocks/client": "0.17.4",
     "react": "^16.14.0 || ^17 || ^18"
   },
   "devDependencies": {