@werxt/livekit-components-react 2.9.20

package/src/hooks/useParticipantAttributes.ts

@@ -0,0 +1,69 @@
+import { participantAttributesObserver } from '@livekit/components-core';
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureParticipant, useMaybeParticipantContext } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * The `useParticipantAttributes` hook returns the attributes of a given participant and allows to set them.
+ * It requires a `Participant` object passed as property or via the `ParticipantContext`.
+ *
+ * @example
+ * ```tsx
+ * const { attributes } = useParticipantAttributes({ participant });
+ * ```
+ * @public
+ */
+export interface UseParticipantAttributesOptions {
+  participant?: Participant;
+}
+
+/** @public */
+export function useParticipantAttributes(props: UseParticipantAttributesOptions = {}) {
+  const participantContext = useMaybeParticipantContext();
+  const p = props.participant ?? participantContext;
+  const attributeObserver = React.useMemo(
+    // weird typescript constraint
+    () => (p ? participantAttributesObserver(p) : participantAttributesObserver(p)),
+    [p],
+  );
+  const attributeState = useObservableState(attributeObserver, {
+    attributes: p?.attributes,
+  });
+
+  return attributeState;
+}
+
+/**
+ * The `useParticipantAttribute` hook returns the latest value of a given attribute key of a participant.
+ * It requires a `Participant` object passed as property in the `UseParticipantAttributesOptions` or via the `ParticipantContext`.
+ *
+ * @example
+ * ```tsx
+ * const myAttributeValue = useParticipantAttribute('targetAttributeName');
+ * ```
+ * @public
+ */
+export function useParticipantAttribute(
+  attributeKey: string,
+  options: UseParticipantAttributesOptions = {},
+) {
+  const p = useEnsureParticipant(options.participant);
+  const [attribute, setAttribute] = React.useState(p.attributes[attributeKey]);
+
+  React.useEffect(() => {
+    if (!p) {
+      return;
+    }
+    const subscription = participantAttributesObserver(p).subscribe((val) => {
+      if (val.changed[attributeKey] !== undefined) {
+        setAttribute(val.attributes[attributeKey]);
+      }
+    });
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, [p, attributeKey]);
+
+  return attribute;
+}

package/src/hooks/useParticipantInfo.ts

@@ -0,0 +1,35 @@
+import { participantInfoObserver } from '@livekit/components-core';
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useMaybeParticipantContext } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * The `useParticipantInfo` hook returns the identity, name, and metadata of a given participant.
+ * It requires a `Participant` object passed as property or via the `ParticipantContext`.
+ *
+ * @example
+ * ```tsx
+ * const { identity, name, metadata } = useParticipantInfo({ participant });
+ * ```
+ * @public
+ */
+export interface UseParticipantInfoOptions {
+  participant?: Participant;
+}
+
+/** @public */
+export function useParticipantInfo(props: UseParticipantInfoOptions = {}) {
+  let p = useMaybeParticipantContext();
+  if (props.participant) {
+    p = props.participant;
+  }
+  const infoObserver = React.useMemo(() => participantInfoObserver(p), [p]);
+  const { identity, name, metadata } = useObservableState(infoObserver, {
+    name: p?.name,
+    identity: p?.identity,
+    metadata: p?.metadata,
+  });
+
+  return { identity, name, metadata };
+}

package/src/hooks/useParticipantPermissions.ts

@@ -0,0 +1,29 @@
+import { participantPermissionObserver } from '@livekit/components-core';
+import type { ParticipantPermission } from '@livekit/protocol';
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureParticipant } from '../context';
+import { useObservableState } from './internal/useObservableState';
+
+/**
+ * The `useParticipantPermissions` hook returns the permissions of a given participant.
+ *
+ * @example
+ * ```tsx
+ * const permissions = useParticipantPermissions({ participant });
+ * ```
+ * @public
+ */
+export interface UseParticipantPermissionsOptions {
+  participant?: Participant;
+}
+
+/** @public */
+export function useParticipantPermissions(
+  options: UseParticipantPermissionsOptions = {},
+): ParticipantPermission | undefined {
+  const p = useEnsureParticipant(options.participant);
+  const permissionObserver = React.useMemo(() => participantPermissionObserver(p), [p]);
+  const permissions = useObservableState(permissionObserver, p.permissions);
+  return permissions;
+}

package/src/hooks/useParticipantTile.ts

@@ -0,0 +1,81 @@
+import type { ParticipantClickEvent, TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { setupParticipantTile } from '@livekit/components-core';
+import * as React from 'react';
+import { useEnsureTrackRef } from '../context';
+import { mergeProps } from '../mergeProps';
+import { useFacingMode } from './useFacingMode';
+import { useIsMuted } from './useIsMuted';
+import { useIsSpeaking } from './useIsSpeaking';
+import { Track } from 'livekit-client';
+
+/** @public */
+export interface UseParticipantTileProps<T extends HTMLElement> extends React.HTMLAttributes<T> {
+  /** The track reference to display. */
+  trackRef?: TrackReferenceOrPlaceholder;
+  disableSpeakingIndicator?: boolean;
+  onParticipantClick?: (event: ParticipantClickEvent) => void;
+  htmlProps: React.HTMLAttributes<T>;
+}
+
+/**
+ * The `useParticipantTile` hook is used to implement the `ParticipantTile` and returns the props needed to render the tile.
+ * @remarks
+ * The returned props include many data attributes that are useful for CSS styling purposes because they
+ * indicate the state of the participant and the track.
+ * For example: `data-lk-audio-muted`, `data-lk-video-muted`, `data-lk-speaking`, `data-lk-local-participant`, `data-lk-source`, `data-lk-facing-mode`.
+ * @public
+ */
+export function useParticipantTile<T extends HTMLElement>({
+  trackRef,
+  onParticipantClick,
+  disableSpeakingIndicator,
+  htmlProps,
+}: UseParticipantTileProps<T>) {
+  const trackReference = useEnsureTrackRef(trackRef);
+
+  const mergedProps = React.useMemo(() => {
+    const { className } = setupParticipantTile();
+    return mergeProps(htmlProps, {
+      className,
+      onClick: (event: React.MouseEvent<T, MouseEvent>) => {
+        htmlProps.onClick?.(event);
+        if (typeof onParticipantClick === 'function') {
+          const track =
+            trackReference.publication ??
+            trackReference.participant.getTrackPublication(trackReference.source);
+          onParticipantClick({ participant: trackReference.participant, track });
+        }
+      },
+    });
+  }, [
+    htmlProps,
+    onParticipantClick,
+    trackReference.publication,
+    trackReference.source,
+    trackReference.participant,
+  ]);
+
+  const micTrack = trackReference.participant.getTrackPublication(Track.Source.Microphone);
+  const micRef = React.useMemo(() => {
+    return {
+      participant: trackReference.participant,
+      source: Track.Source.Microphone,
+      publication: micTrack,
+    };
+  }, [micTrack, trackReference.participant]);
+  const isVideoMuted = useIsMuted(trackReference);
+  const isAudioMuted = useIsMuted(micRef);
+  const isSpeaking = useIsSpeaking(trackReference.participant);
+  const facingMode = useFacingMode(trackReference);
+  return {
+    elementProps: {
+      'data-lk-audio-muted': isAudioMuted,
+      'data-lk-video-muted': isVideoMuted,
+      'data-lk-speaking': disableSpeakingIndicator === true ? false : isSpeaking,
+      'data-lk-local-participant': trackReference.participant.isLocal,
+      'data-lk-source': trackReference.source,
+      'data-lk-facing-mode': facingMode,
+      ...mergedProps,
+    } as React.HTMLAttributes<T>,
+  };
+}

package/src/hooks/useParticipantTracks.ts

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import type { TrackReference } from '@livekit/components-core';
+import { participantTracksObservable } from '@livekit/components-core';
+import { useObservableState } from './internal';
+import type { Room, Track } from 'livekit-client';
+import { useMaybeParticipantContext } from '../context';
+import { useParticipants } from './useParticipants';
+
+type UseParticipantTracksOptions = {
+  participantIdentity?: string;
+  room?: Room;
+};
+
+/**
+ * `useParticipantTracks` is a custom React that allows you to get tracks of a specific participant only, by specifiying the participant's identity.
+ * If the participant identity is not passed the hook will try to get the participant from a participant context.
+ * @public
+ */
+export function useParticipantTracks<TrackSource extends Track.Source>(
+  sources: Array<TrackSource>,
+  optionsOrParticipantIdentity:
+    | UseParticipantTracksOptions
+    | UseParticipantTracksOptions['participantIdentity'] = {},
+): Array<TrackReference> {
+  let participantIdentity: UseParticipantTracksOptions['participantIdentity'];
+  let room: UseParticipantTracksOptions['room'];
+  if (typeof optionsOrParticipantIdentity === 'string') {
+    participantIdentity = optionsOrParticipantIdentity;
+  } else {
+    participantIdentity = optionsOrParticipantIdentity?.participantIdentity;
+    room = optionsOrParticipantIdentity?.room;
+  }
+
+  const participantContext = useMaybeParticipantContext();
+  const participants = useParticipants({ room, updateOnlyOn: [] });
+
+  const p = React.useMemo(() => {
+    if (participantIdentity) {
+      return participants.find((p) => p.identity === participantIdentity);
+    }
+    return participantContext;
+  }, [participantIdentity, participants, participantContext]);
+
+  const observable = React.useMemo(() => {
+    if (!p) {
+      return undefined;
+    }
+    return participantTracksObservable(p, { sources });
+  }, [p, JSON.stringify(sources)]);
+
+  const trackRefs = useObservableState(observable, [] as Array<TrackReference>);
+
+  return trackRefs;
+}

package/src/hooks/useParticipants.ts

@@ -0,0 +1,42 @@
+import type { Room, RoomEvent } from 'livekit-client';
+import { useLocalParticipant } from './useLocalParticipant';
+import { useRemoteParticipants } from './useRemoteParticipants';
+import * as React from 'react';
+
+/** @public */
+export interface UseParticipantsOptions {
+  /**
+   * To optimize performance, you can use the `updateOnlyOn` property to decide on what RoomEvents the hook updates.
+   * By default it updates on all relevant RoomEvents to keep the returned participants array up to date.
+   * The minimal set of non-overwriteable `RoomEvents` is: `[RoomEvent.ParticipantConnected, RoomEvent.ParticipantDisconnected, RoomEvent.ConnectionStateChanged]`
+   */
+  updateOnlyOn?: RoomEvent[];
+  /**
+   * The room to use. If not provided, the hook will use the room from the context.
+   */
+  room?: Room;
+}
+
+/**
+ * The `useParticipants` hook returns all participants (local and remote) of the current room.
+ * @remarks
+ * To optimize performance, you can use the `updateOnlyOn` property to decide on what `RoomEvents` the hook updates.
+ *
+ * @example
+ * ```tsx
+ * const participants = useParticipants();
+ * <ParticipantLoop participants={participants}>
+ *  <ParticipantName />
+ * </ParticipantLoop>
+ * ```
+ * @public
+ */
+export function useParticipants(options: UseParticipantsOptions = {}) {
+  const remoteParticipants = useRemoteParticipants(options);
+  const { localParticipant } = useLocalParticipant(options);
+
+  return React.useMemo(
+    () => [localParticipant, ...remoteParticipants],
+    [localParticipant, remoteParticipants],
+  );
+}

package/src/hooks/usePersistentUserChoices.ts

@@ -0,0 +1,64 @@
+import type { LocalUserChoices } from '@livekit/components-core';
+import { loadUserChoices, saveUserChoices } from '@livekit/components-core';
+import * as React from 'react';
+
+/**
+ * Options for the `usePersistentDeviceSettings` hook.
+ * @alpha
+ */
+export interface UsePersistentUserChoicesOptions {
+  /**
+   * The default value to use if reading from local storage returns no results or fails.
+   */
+  defaults?: Partial<LocalUserChoices>;
+  /**
+   * Whether to prevent saving to persistent storage.
+   * @defaultValue false
+   */
+  preventSave?: boolean;
+  /**
+   * Whether to prevent loading user choices from persistent storage and use `defaults` instead.
+   * @defaultValue false
+   */
+  preventLoad?: boolean;
+}
+
+/**
+ * A hook that provides access to user choices stored in local storage, such as
+ * selected media devices and their current state (on or off), as well as the user name.
+ * @alpha
+ */
+export function usePersistentUserChoices(options: UsePersistentUserChoicesOptions = {}) {
+  const [userChoices, setSettings] = React.useState<LocalUserChoices>(
+    loadUserChoices(options.defaults, options.preventLoad ?? false),
+  );
+
+  const saveAudioInputEnabled = React.useCallback((isEnabled: boolean) => {
+    setSettings((prev) => ({ ...prev, audioEnabled: isEnabled }));
+  }, []);
+  const saveVideoInputEnabled = React.useCallback((isEnabled: boolean) => {
+    setSettings((prev) => ({ ...prev, videoEnabled: isEnabled }));
+  }, []);
+  const saveAudioInputDeviceId = React.useCallback((deviceId: string) => {
+    setSettings((prev) => ({ ...prev, audioDeviceId: deviceId }));
+  }, []);
+  const saveVideoInputDeviceId = React.useCallback((deviceId: string) => {
+    setSettings((prev) => ({ ...prev, videoDeviceId: deviceId }));
+  }, []);
+  const saveUsername = React.useCallback((username: string) => {
+    setSettings((prev) => ({ ...prev, username: username }));
+  }, []);
+
+  React.useEffect(() => {
+    saveUserChoices(userChoices, options.preventSave ?? false);
+  }, [userChoices, options.preventSave]);
+
+  return {
+    userChoices,
+    saveAudioInputEnabled,
+    saveVideoInputEnabled,
+    saveAudioInputDeviceId,
+    saveVideoInputDeviceId,
+    saveUsername,
+  };
+}

package/src/hooks/usePinnedTracks.ts

@@ -0,0 +1,24 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import * as React from 'react';
+import type { LayoutContextType } from '../context';
+import { useEnsureLayoutContext } from '../context';
+
+/**
+ * The `usePinnedTracks` hook returns a array of the pinned tracks of the current room.
+ * @remarks
+ * To function properly, this hook must be called within a `LayoutContext`.
+ * @example
+ * ```tsx
+ * const pinnedTracks = usePinnedTracks();
+ * ```
+ * @public
+ */
+export function usePinnedTracks(layoutContext?: LayoutContextType): TrackReferenceOrPlaceholder[] {
+  layoutContext = useEnsureLayoutContext(layoutContext);
+  return React.useMemo(() => {
+    if (layoutContext?.pin.state !== undefined && layoutContext.pin.state.length >= 1) {
+      return layoutContext.pin.state;
+    }
+    return [];
+  }, [layoutContext.pin.state]);
+}

package/src/hooks/useRemoteParticipant.ts

@@ -0,0 +1,79 @@
+import {
+  type ParticipantIdentifier,
+  connectedParticipantObserver,
+  participantByIdentifierObserver,
+} from '@livekit/components-core';
+import type { ParticipantEvent, RemoteParticipant } from 'livekit-client';
+import * as React from 'react';
+import { useRoomContext } from '../context';
+
+/** @public */
+export interface UseRemoteParticipantOptions {
+  /**
+   * To optimize performance, you can use the `updateOnlyOn` property to decide on what `ParticipantEvents` the hook updates.
+   * By default it updates on all relevant ParticipantEvents to keep the returned participant up to date.
+   */
+  updateOnlyOn?: ParticipantEvent[];
+}
+
+/**
+ * The `useRemoteParticipant` hook returns the first RemoteParticipant by either identity and/or based on the participant kind.
+ * @remarks
+ * To optimize performance, you can use the `updateOnlyOn` property to decide on what `ParticipantEvents` the hook updates.
+ *
+ * @example
+ * ```tsx
+ * const participant = useRemoteParticipant({kind: ParticipantKind.Agent, identity: 'myAgent'});
+ * ```
+ * @public
+ */
+export function useRemoteParticipant(
+  identifier: ParticipantIdentifier,
+  options?: UseRemoteParticipantOptions,
+): RemoteParticipant | undefined;
+/**
+ * The `useRemoteParticipant` hook returns the first RemoteParticipant by either identity or based on the participant kind.
+ * @remarks
+ * To optimize performance, you can use the `updateOnlyOn` property to decide on what `ParticipantEvents` the hook updates.
+ *
+ * @example
+ * ```tsx
+ * const participant = useRemoteParticipant('Russ');
+ * ```
+ * @public
+ */
+export function useRemoteParticipant(
+  identity: string,
+  options?: UseRemoteParticipantOptions,
+): RemoteParticipant | undefined;
+export function useRemoteParticipant(
+  identityOrIdentifier: string | ParticipantIdentifier,
+  options: UseRemoteParticipantOptions = {},
+): RemoteParticipant | undefined {
+  const room = useRoomContext();
+  const [updateOnlyOn] = React.useState(options.updateOnlyOn);
+
+  const observable = React.useMemo(() => {
+    if (typeof identityOrIdentifier === 'string') {
+      return connectedParticipantObserver(room, identityOrIdentifier, {
+        additionalEvents: updateOnlyOn,
+      });
+    } else {
+      return participantByIdentifierObserver(room, identityOrIdentifier, {
+        additionalEvents: updateOnlyOn,
+      });
+    }
+  }, [room, JSON.stringify(identityOrIdentifier), updateOnlyOn]);
+
+  // Using `wrapperParticipant` to ensure a new object reference,
+  // triggering a re-render when the participant events fire.
+  const [participantWrapper, setParticipantWrapper] = React.useState({
+    p: undefined as RemoteParticipant | undefined,
+  });
+  React.useEffect(() => {
+    const listener = observable.subscribe((p) => setParticipantWrapper({ p }));
+    return () => listener.unsubscribe();
+  }, [observable]);
+
+  return participantWrapper.p;
+}

package/src/hooks/useRemoteParticipants.ts

@@ -0,0 +1,45 @@
+import { connectedParticipantsObserver } from '@livekit/components-core';
+import type { RoomEvent, RemoteParticipant, Room } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+
+/** @public */
+export interface UseRemoteParticipantsOptions {
+  /**
+   * To optimize performance, you can use the `updateOnlyOn` property to decide on what RoomEvents the hook updates.
+   * By default it updates on all relevant RoomEvents to keep the returned participants array up to date.
+   * The minimal set of non-overwriteable `RoomEvents` is: `[RoomEvent.ParticipantConnected, RoomEvent.ParticipantDisconnected, RoomEvent.ConnectionStateChanged]`
+   */
+  updateOnlyOn?: RoomEvent[];
+  /**
+   * The room to use. If not provided, the hook will use the room from the context.
+   */
+  room?: Room;
+}
+
+/**
+ * The `useRemoteParticipants` hook returns all remote participants (without the local) of the current room.
+ * @remarks
+ * To optimize performance, you can use the `updateOnlyOn` property to decide on what `RoomEvents` the hook updates.
+ *
+ * @example
+ * ```tsx
+ * const participants = useRemoteParticipants();
+ * <ParticipantLoop participants={participants}>
+ *  <ParticipantName />
+ * </ParticipantLoop>
+ * ```
+ * @public
+ */
+export function useRemoteParticipants(options: UseRemoteParticipantsOptions = {}) {
+  const room = useEnsureRoom(options.room);
+  const [participants, setParticipants] = React.useState<RemoteParticipant[]>([]);
+
+  React.useEffect(() => {
+    const listener = connectedParticipantsObserver(room, {
+      additionalRoomEvents: options.updateOnlyOn,
+    }).subscribe(setParticipants);
+    return () => listener.unsubscribe();
+  }, [room, JSON.stringify(options.updateOnlyOn)]);
+  return participants;
+}

package/src/hooks/useRoomInfo.ts

@@ -0,0 +1,32 @@
+import { roomInfoObserver } from '@livekit/components-core';
+import type { Room } from 'livekit-client';
+import * as React from 'react';
+import { useEnsureRoom } from '../context';
+import { useObservableState } from './internal';
+
+/**
+ * The `useRoomInfo` hook returns the name and metadata of the given `Room`.
+ * @remarks
+ * Needs to be called inside a `RoomContext` or by passing a `Room` instance.
+ *
+ * @example
+ * ```tsx
+ * const { name, metadata } = useRoomInfo();
+ * ```
+ * @public
+ */
+export interface UseRoomInfoOptions {
+  room?: Room;
+}
+
+/** @public */
+export function useRoomInfo(options: UseRoomInfoOptions = {}) {
+  const room = useEnsureRoom(options.room);
+  const infoObserver = React.useMemo(() => roomInfoObserver(room), [room]);
+  const { name, metadata } = useObservableState(infoObserver, {
+    name: room.name,
+    metadata: room.metadata,
+  });
+
+  return { name, metadata };
+}