@werxt/livekit-components-react 2.9.20

package/src/hooks/useAudioPlayback.ts

@@ -0,0 +1,34 @@
+import type { Room } from 'livekit-client';
+import * as React from 'react';
+import { useObservableState } from './internal';
+import { roomAudioPlaybackAllowedObservable } from '@livekit/components-core';
+import { useEnsureRoom } from '../context';
+
+/**
+ * In many browsers to start audio playback, the user must perform a user-initiated event such as clicking a button.
+ * The `useAudioPlayback` hook returns an object with a boolean `canPlayAudio` flag that indicates whether audio
+ * playback is allowed in the current context, as well as a `startAudio` function that can be called in a button
+ * `onClick` callback to start audio playback in the current context.
+ *
+ * @see Autoplay policy on MDN web docs for more info: {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices#autoplay_policy}
+ * @alpha
+ */
+export function useAudioPlayback(room?: Room): {
+  canPlayAudio: boolean;
+  startAudio: () => Promise<void>;
+} {
+  const roomEnsured = useEnsureRoom(room);
+  const startAudio = React.useCallback(async () => {
+    await roomEnsured.startAudio();
+  }, [roomEnsured]);
+
+  const observable = React.useMemo(
+    () => roomAudioPlaybackAllowedObservable(roomEnsured),
+    [roomEnsured],
+  );
+  const { canPlayAudio } = useObservableState(observable, {
+    canPlayAudio: roomEnsured.canPlaybackAudio,
+  });
+
+  return { canPlayAudio, startAudio };
+}

package/src/hooks/useChat.ts

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import type { ChatOptions, ReceivedChatMessage } from '@livekit/components-core';
+import { setupChat } from '@livekit/components-core';
+import { ConnectionState, Room } from 'livekit-client';
+import { useEnsureRoom } from '../context';
+import { useObservableState } from './internal/useObservableState';
+import { useConnectionState } from './useConnectionStatus';
+
+/**
+ * The `useChat` hook provides chat functionality for a LiveKit room.
+ *
+ * @remarks
+ * Message history is not persisted and will be lost if the component is refreshed.
+ * You may want to persist message history in the browser, a cache or a database.
+ *
+ * @returns An object containing:
+ * - `chatMessages` - Array of received chat messages
+ * - `send` - Function to send a new message
+ * - `isSending` - Boolean indicating if a message is currently being sent
+ *
+ * @example
+ * ```tsx
+ * function ChatComponent() {
+ *   const { chatMessages, send, isSending } = useChat();
+ *
+ *   return (
+ *     <div>
+ *       {chatMessages.map((msg) => (
+ *         <div key={msg.timestamp}>
+ *           {msg.from?.identity}: {msg.message}
+ *         </div>
+ *       ))}
+ *       <button disabled={isSending} onClick={() => send("Hello!")}>
+ *         Send Message
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ * @public
+ */
+export function useChat(options?: ChatOptions & { room?: Room }) {
+  const room = useEnsureRoom(options?.room);
+  const connectionState = useConnectionState(room);
+  const isDisconnected = React.useMemo(
+    () => connectionState === ConnectionState.Disconnected,
+    [connectionState],
+  ); // used to reset the messages on room disconnect
+  const setup = React.useMemo<ReturnType<typeof setupChat>>(
+    () => setupChat(room, options),
+    [room, options, isDisconnected],
+  );
+  const isSending = useObservableState(setup.isSendingObservable, false);
+  const chatMessages = useObservableState<ReceivedChatMessage[]>(setup.messageObservable, []);
+
+  return { send: setup.send, chatMessages, isSending };
+}

package/src/hooks/useChatToggle.ts

@@ -0,0 +1,38 @@
+import { setupChatToggle } from '@livekit/components-core';
+import { useLayoutContext } from '../context';
+import { mergeProps } from '../mergeProps';
+import * as React from 'react';
+
+/** @public */
+export interface UseChatToggleProps {
+  props: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+
+/**
+ * The `useChatToggle` hook provides state and functions for toggling the chat window.
+ * @remarks
+ * Depends on the `LayoutContext` to work properly.
+ * @see {@link ChatToggle}, {@link Chat}
+ * @public
+ */
+export function useChatToggle({ props }: UseChatToggleProps) {
+  const { dispatch, state } = useLayoutContext().widget;
+  const { className } = React.useMemo(() => setupChatToggle(), []);
+
+  const mergedProps = React.useMemo(() => {
+    return mergeProps(props, {
+      className,
+      onClick: () => {
+        if (dispatch) dispatch({ msg: 'toggle_chat' });
+      },
+      'aria-pressed': state?.showChat ? 'true' : 'false',
+      'data-lk-unread-msgs': state
+        ? state.unreadMessages < 10
+          ? state.unreadMessages.toFixed(0)
+          : '9+'
+        : '0',
+    });
+  }, [props, className, dispatch, state]);
+
+  return { mergedProps };
+}

package/src/hooks/useClearPinButton.ts

@@ -0,0 +1,29 @@
+import { setupClearPinButton } from '@livekit/components-core';
+import * as React from 'react';
+import { useLayoutContext } from '../context';
+import { mergeProps } from '../mergeProps';
+import type { ClearPinButtonProps } from '../components';
+
+/**
+ * The `useClearPinButton` hook provides props for the {@link ClearPinButton}
+ * or your custom implementation of it component. It adds the `onClick` handler
+ * to signal the `LayoutContext` that the tile in focus should be cleared.
+ * @public
+ */
+export function useClearPinButton(props: ClearPinButtonProps) {
+  const { state, dispatch } = useLayoutContext().pin;
+
+  const buttonProps = React.useMemo(() => {
+    const { className } = setupClearPinButton();
+    const mergedProps = mergeProps(props, {
+      className,
+      disabled: !state?.length,
+      onClick: () => {
+        if (dispatch) dispatch({ msg: 'clear_pin' });
+      },
+    });
+    return mergedProps;
+  }, [props, dispatch, state]);
+
+  return { buttonProps };
+}

package/src/hooks/useConnectionQualityIndicator.ts

@@ -0,0 +1,33 @@
+import { setupConnectionQualityIndicator } from '@livekit/components-core';
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureParticipant } from '../context';
+import { useObservableState } from './internal';
+
+/** @public */
+export interface ConnectionQualityIndicatorOptions {
+  participant?: Participant;
+}
+
+/**
+ * The `useConnectionQualityIndicator` hook provides props for the `ConnectionQualityIndicator` or your custom implementation of it component.
+ * @example
+ * ```tsx
+ * const { quality } = useConnectionQualityIndicator();
+ * // or
+ * const { quality } = useConnectionQualityIndicator({ participant });
+ * ```
+ * @public
+ */
+export function useConnectionQualityIndicator(options: ConnectionQualityIndicatorOptions = {}) {
+  const p = useEnsureParticipant(options.participant);
+
+  const { className, connectionQualityObserver } = React.useMemo(
+    () => setupConnectionQualityIndicator(p),
+    [p],
+  );
+
+  const quality = useObservableState(connectionQualityObserver, p.connectionQuality);
+
+  return { className, quality };
+}

package/src/hooks/useConnectionStatus.ts

@@ -0,0 +1,22 @@
+import { connectionStateObserver } from '@livekit/components-core';
+import type { Room } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * The `useConnectionState` hook allows you to simply implement your own `ConnectionState` component.
+ *
+ * @example
+ * ```tsx
+ * const connectionState = useConnectionState(room);
+ * ```
+ * @public
+ */
+export function useConnectionState(room?: Room) {
+  // passed room takes precedence, if not supplied get current room context
+  const r = useEnsureRoom(room);
+  const observable = React.useMemo(() => connectionStateObserver(r), [r]);
+  const connectionState = useObservableState(observable, r.state);
+  return connectionState;
+}

package/src/hooks/useDataChannel.ts

@@ -0,0 +1,73 @@
+import type { ReceivedDataMessage } from '@livekit/components-core';
+import { setupDataMessageHandler } from '@livekit/components-core';
+import * as React from 'react';
+import type { DataPublishOptions } from 'livekit-client';
+import { useRoomContext } from '../context';
+import { useObservableState } from './internal';
+
+type UseDataChannelReturnType<T extends string | undefined = undefined> = {
+  isSending: boolean;
+  send: (payload: Uint8Array, options: DataPublishOptions) => Promise<void>;
+  message: ReceivedDataMessage<T> | undefined;
+};
+
+/**
+ * The `useDataChannel` hook returns the ability to send and receive messages.
+ * Pass an optional `topic` to narrow down which messages are returned in the messages array.
+ *
+ * @remarks
+ * There is only one data channel. Passing a `topic` does not open a new data channel.
+ * It is only used to filter out messages with no or a different `topic`.
+ *
+ * @example
+ * ```tsx
+ * // Send messages to all participants via the 'chat' topic.
+ * const { message: latestMessage, send } = useDataChannel('chat', (msg) => console.log("message received", msg));
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Receive all messages (no topic filtering)
+ * const { message: latestMessage, send } = useDataChannel((msg) => console.log("message received", msg));
+ * ```
+ *
+ * @public
+ */
+export function useDataChannel<T extends string>(
+  topic: T,
+  onMessage?: (msg: ReceivedDataMessage<T>) => void,
+): UseDataChannelReturnType<T>;
+
+/**
+ * Overload for `useDataChannel` without a topic. See {@link (useDataChannel:1)} for information and usage examples.
+ *
+ * @public
+ */
+export function useDataChannel(
+  onMessage?: (msg: ReceivedDataMessage) => void,
+): UseDataChannelReturnType;
+/**
+ * @internal
+ */
+export function useDataChannel<T extends string>(
+  topicOrCallback?: T | ((msg: ReceivedDataMessage) => void),
+  callback?: (msg: ReceivedDataMessage<T>) => void,
+) {
+  const onMessage = typeof topicOrCallback === 'function' ? topicOrCallback : callback;
+
+  const topic = typeof topicOrCallback === 'string' ? topicOrCallback : undefined;
+  const room = useRoomContext();
+  const { send, messageObservable, isSendingObservable } = React.useMemo(
+    () => setupDataMessageHandler(room, topic, onMessage),
+    [room, topic, onMessage],
+  );
+
+  const message = useObservableState(messageObservable, undefined);
+  const isSending = useObservableState(isSendingObservable, false);
+
+  return {
+    message,
+    send,
+    isSending,
+  };
+}

package/src/hooks/useDisconnectButton.ts

@@ -0,0 +1,36 @@
+import { setupDisconnectButton } from '@livekit/components-core';
+import { ConnectionState } from 'livekit-client';
+import * as React from 'react';
+import type { DisconnectButtonProps } from '../components';
+import { useRoomContext } from '../context';
+import { mergeProps } from '../mergeProps';
+import { useConnectionState } from './useConnectionStatus';
+
+/**
+ * The `useDisconnectButton` hook is used to implement the `DisconnectButton` or your
+ * custom implementation of it. It adds onClick handler to the button to disconnect
+ * from the room.
+ *
+ * @example
+ * ```tsx
+ * const { buttonProps } = useDisconnectButton(buttonProps);
+ * return <button {...buttonProps}>Disconnect</button>;
+ * ```
+ * @public
+ */
+export function useDisconnectButton(props: DisconnectButtonProps) {
+  const room = useRoomContext();
+  const connectionState = useConnectionState(room);
+
+  const buttonProps = React.useMemo(() => {
+    const { className, disconnect } = setupDisconnectButton(room);
+    const mergedProps = mergeProps(props, {
+      className,
+      onClick: () => disconnect(props.stopTracks ?? true),
+      disabled: connectionState === ConnectionState.Disconnected,
+    });
+    return mergedProps;
+  }, [room, props, connectionState]);
+
+  return { buttonProps };
+}

package/src/hooks/useEvents.ts

@@ -0,0 +1,39 @@
+import * as React from 'react';
+import TypedEventEmitter, { EventMap } from 'typed-emitter';
+
+/** @public */
+export function useEvents<
+  Emitter extends TypedEventEmitter<EventMap>,
+  EmitterEventMap extends Emitter extends TypedEventEmitter<infer EM> ? EM : never,
+  Event extends Parameters<Emitter['on']>[0],
+  Callback extends EmitterEventMap[Event],
+>(
+  instance: Emitter | { internal: { emitter: Emitter } } | null | undefined,
+  event: Event,
+  handlerFn: Callback | undefined,
+  dependencies?: React.DependencyList,
+) {
+  const fallback = React.useMemo(() => () => {}, []);
+  const wrappedCallback = React.useCallback(handlerFn ?? fallback, dependencies ?? []);
+  const callback = dependencies ? wrappedCallback : handlerFn;
+
+  const emitter = React.useMemo(() => {
+    if (!instance) {
+      return null;
+    }
+    if ('internal' in instance) {
+      return instance.internal.emitter;
+    }
+    return instance;
+  }, [instance]);
+
+  React.useEffect(() => {
+    if (!emitter || !callback) {
+      return;
+    }
+    emitter.on(event, callback);
+    return () => {
+      emitter.off(event, callback);
+    };
+  }, [emitter, event, callback]);
+}

package/src/hooks/useFacingMode.ts

@@ -0,0 +1,22 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { LocalTrackPublication, facingModeFromLocalTrack } from 'livekit-client';
+
+/**
+ * Try to determine the `facingMode` of a local participant video track.
+ * @remarks
+ * Works only on local video tracks.
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/MediaTrackConstraints/facingMode | MDN docs on facingMode}
+ * @alpha
+ */
+export function useFacingMode(
+  trackReference: TrackReferenceOrPlaceholder,
+): 'user' | 'environment' | 'left' | 'right' | 'undefined' {
+  if (trackReference.publication instanceof LocalTrackPublication) {
+    const localTrack = trackReference.publication.track;
+    if (localTrack) {
+      const { facingMode } = facingModeFromLocalTrack(localTrack);
+      return facingMode;
+    }
+  }
+  return 'undefined';
+}

package/src/hooks/useFocusToggle.ts

@@ -0,0 +1,59 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { setupFocusToggle, isTrackReferencePinned } from '@livekit/components-core';
+import { useEnsureTrackRef, useMaybeLayoutContext } from '../context';
+import { mergeProps } from '../mergeProps';
+import * as React from 'react';
+
+/** @public */
+export interface UseFocusToggleProps {
+  trackRef?: TrackReferenceOrPlaceholder;
+  props: React.ButtonHTMLAttributes<HTMLButtonElement>;
+}
+
+/**
+ * The `useFocusToggle` hook is used to implement the `FocusToggle` or your custom implementation of it.
+ * The `TrackReferenceOrPlaceholder` is used to register a onClick handler and to identify the track to focus on.
+ *
+ * @example
+ * ```tsx
+ * const { mergedProps, inFocus } = useFocusToggle({ trackRef, props: yourButtonProps });
+ * return <button {...mergedProps}>{inFocus ? 'Unfocus' : 'Focus'}</button>;
+ * ```
+ * @public
+ */
+export function useFocusToggle({ trackRef, props }: UseFocusToggleProps) {
+  const trackReference = useEnsureTrackRef(trackRef);
+
+  const layoutContext = useMaybeLayoutContext();
+  const { className } = React.useMemo(() => setupFocusToggle(), []);
+
+  const inFocus: boolean = React.useMemo(() => {
+    return isTrackReferencePinned(trackReference, layoutContext?.pin.state);
+  }, [trackReference, layoutContext?.pin.state]);
+
+  const mergedProps = React.useMemo(
+    () =>
+      mergeProps(props, {
+        className,
+        onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => {
+          // Call user defined on click callbacks.
+          props.onClick?.(event);
+
+          // Set or clear focus based on current focus state.
+          if (inFocus) {
+            layoutContext?.pin.dispatch?.({
+              msg: 'clear_pin',
+            });
+          } else {
+            layoutContext?.pin.dispatch?.({
+              msg: 'set_pin',
+              trackReference,
+            });
+          }
+        },
+      }),
+    [props, className, trackReference, inFocus, layoutContext?.pin],
+  );
+
+  return { mergedProps, inFocus };
+}

package/src/hooks/useGridLayout.ts

@@ -0,0 +1,44 @@
+import { GRID_LAYOUTS, selectGridLayout } from '@livekit/components-core';
+import type { GridLayoutDefinition, GridLayoutInfo } from '@livekit/components-core';
+import * as React from 'react';
+import { useSize } from './internal';
+
+/**
+ * The `useGridLayout` hook tries to select the best layout to fit all tiles.
+ * If the available screen space is not enough, it will reduce the number of maximum visible
+ * tiles and select a layout that still works visually within the given limitations.
+ * As the order of tiles changes over time, the hook tries to keep visual updates to a minimum
+ * while trying to display important tiles such as speaking participants or screen shares.
+ *
+ * @example
+ * ```tsx
+ * const { layout } = useGridLayout(gridElement, trackCount);
+ * ```
+ * @public
+ */
+export function useGridLayout(
+  /** HTML element that contains the grid. */
+  gridElement: React.RefObject<HTMLDivElement>,
+  /** Count of tracks that should get layed out */
+  trackCount: number,
+  options: {
+    gridLayouts?: GridLayoutDefinition[];
+  } = {},
+): { layout: GridLayoutInfo; containerWidth: number; containerHeight: number } {
+  const gridLayouts = options.gridLayouts ?? GRID_LAYOUTS;
+  const { width, height } = useSize(gridElement);
+  const layout = selectGridLayout(gridLayouts, trackCount, width, height);
+
+  React.useEffect(() => {
+    if (gridElement.current && layout) {
+      gridElement.current.style.setProperty('--lk-col-count', layout?.columns.toString());
+      gridElement.current.style.setProperty('--lk-row-count', layout?.rows.toString());
+    }
+  }, [gridElement, layout]);
+
+  return {
+    layout,
+    containerWidth: width,
+    containerHeight: height,
+  };
+}

package/src/hooks/useIsEncrypted.ts

@@ -0,0 +1,29 @@
+import * as React from 'react';
+import { LocalParticipant } from 'livekit-client';
+import type { Participant, Room } from 'livekit-client';
+import { encryptionStatusObservable } from '@livekit/components-core';
+import { useEnsureParticipant, useEnsureRoom } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * @alpha
+ */
+export interface UseIsEncryptedOptions {
+  room?: Room;
+}
+
+/**
+ * @alpha
+ */
+export function useIsEncrypted(participant?: Participant, options: UseIsEncryptedOptions = {}) {
+  const p = useEnsureParticipant(participant);
+
+  const room = useEnsureRoom(options.room);
+
+  const observer = React.useMemo(() => encryptionStatusObservable(room, p), [room, p]);
+  const isEncrypted = useObservableState(
+    observer,
+    p.isLocal ? (p as LocalParticipant).isE2EEEnabled : !!p?.isEncrypted,
+  );
+  return isEncrypted;
+}

package/src/hooks/useIsMuted.ts

@@ -0,0 +1,51 @@
+import {
+  type TrackReferenceOrPlaceholder,
+  getTrackReferenceId,
+  mutedObserver,
+} from '@livekit/components-core';
+import type { Participant, Track } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureParticipant } from '../context';
+
+/** @public */
+export interface UseIsMutedOptions {
+  participant?: Participant;
+}
+
+/**
+ * The `useIsMuted` hook is used to implement the `TrackMutedIndicator` or your custom implementation of it.
+ * It returns a `boolean` that indicates if the track is muted or not.
+ *
+ * @example With a track reference
+ * ```tsx
+ * const isMuted = useIsMuted(track);
+ * ```
+ *
+ * @param trackRef - A `TrackReference` indicating the track to monitor.
+ * @returns boolean indicating if the track is muted
+ *
+ * @public
+ */
+export function useIsMuted(trackRef: TrackReferenceOrPlaceholder): boolean;
+export function useIsMuted(
+  sourceOrTrackRef: TrackReferenceOrPlaceholder | Track.Source,
+  options: UseIsMutedOptions = {},
+) {
+  const passedParticipant =
+    typeof sourceOrTrackRef === 'string' ? options.participant : sourceOrTrackRef.participant;
+  const p = useEnsureParticipant(passedParticipant);
+  const ref =
+    typeof sourceOrTrackRef === 'string'
+      ? { participant: p, source: sourceOrTrackRef }
+      : sourceOrTrackRef;
+  const [isMuted, setIsMuted] = React.useState(
+    !!(ref.publication?.isMuted || p.getTrackPublication(ref.source)?.isMuted),
+  );
+
+  React.useEffect(() => {
+    const listener = mutedObserver(ref).subscribe(setIsMuted);
+    return () => listener.unsubscribe();
+  }, [getTrackReferenceId(ref)]);
+
+  return isMuted;
+}

package/src/hooks/useIsRecording.ts

@@ -0,0 +1,23 @@
+import { recordingStatusObservable } from '@livekit/components-core';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+import { useObservableState } from './internal';
+import { useConnectionState } from './useConnectionStatus';
+import type { Room } from 'livekit-client';
+
+/**
+ * The `useIsRecording` hook returns a `boolean` that indicates if the room is currently being recorded.
+ * @example
+ * ```tsx
+ * const isRecording = useIsRecording();
+ * ```
+ * @public
+ */
+export function useIsRecording(room?: Room) {
+  const r = useEnsureRoom(room);
+  const connectionState = useConnectionState(r);
+  const observable = React.useMemo(() => recordingStatusObservable(r), [r, connectionState]);
+  const isRecording = useObservableState(observable, r.isRecording);
+
+  return isRecording;
+}

package/src/hooks/useIsSpeaking.ts

@@ -0,0 +1,21 @@
+import { createIsSpeakingObserver } from '@livekit/components-core';
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureParticipant } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * The `useIsSpeaking` hook returns a `boolean` that indicates if the participant is speaking or not.
+ * @example
+ * ```tsx
+ * const isSpeaking = useIsSpeaking(participant);
+ * ```
+ * @public
+ */
+export function useIsSpeaking(participant?: Participant) {
+  const p = useEnsureParticipant(participant);
+  const observable = React.useMemo(() => createIsSpeakingObserver(p), [p]);
+  const isSpeaking = useObservableState(observable, p.isSpeaking);
+
+  return isSpeaking;
+}