@werxt/livekit-components-react 2.9.20

package/src/components/participant/ParticipantTile.tsx

@@ -0,0 +1,192 @@
+import * as React from 'react';
+import type { Participant } from 'livekit-client';
+import { Track } from 'livekit-client';
+import type { ParticipantClickEvent, TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { isTrackReference, isTrackReferencePinned } from '@livekit/components-core';
+import { ConnectionQualityIndicator } from './ConnectionQualityIndicator';
+import { ParticipantName } from './ParticipantName';
+import { TrackMutedIndicator } from './TrackMutedIndicator';
+import {
+  ParticipantContext,
+  TrackRefContext,
+  useEnsureTrackRef,
+  useFeatureContext,
+  useMaybeLayoutContext,
+  useMaybeParticipantContext,
+  useMaybeTrackRefContext,
+} from '../../context';
+import { FocusToggle } from '../controls/FocusToggle';
+import { ParticipantPlaceholder } from '../../assets/images';
+import { LockLockedIcon, ScreenShareIcon } from '../../assets/icons';
+import { VideoTrack } from './VideoTrack';
+import { AudioTrack } from './AudioTrack';
+import { useParticipantTile } from '../../hooks';
+import { useIsEncrypted } from '../../hooks/useIsEncrypted';
+
+/**
+ * The `ParticipantContextIfNeeded` component only creates a `ParticipantContext`
+ * if there is no `ParticipantContext` already.
+ * @example
+ * ```tsx
+ * <ParticipantContextIfNeeded participant={trackReference.participant}>
+ *  ...
+ * </ParticipantContextIfNeeded>
+ * ```
+ * @public
+ */
+export function ParticipantContextIfNeeded(
+  props: React.PropsWithChildren<{
+    participant?: Participant;
+  }>,
+) {
+  const hasContext = !!useMaybeParticipantContext();
+  return props.participant && !hasContext ? (
+    <ParticipantContext.Provider value={props.participant}>
+      {props.children}
+    </ParticipantContext.Provider>
+  ) : (
+    <>{props.children}</>
+  );
+}
+
+/**
+ * Only create a `TrackRefContext` if there is no `TrackRefContext` already.
+ * @internal
+ */
+export function TrackRefContextIfNeeded(
+  props: React.PropsWithChildren<{
+    trackRef?: TrackReferenceOrPlaceholder;
+  }>,
+) {
+  const hasContext = !!useMaybeTrackRefContext();
+  return props.trackRef && !hasContext ? (
+    <TrackRefContext.Provider value={props.trackRef}>{props.children}</TrackRefContext.Provider>
+  ) : (
+    <>{props.children}</>
+  );
+}
+
+/** @public */
+export interface ParticipantTileProps extends React.HTMLAttributes<HTMLDivElement> {
+  /** The track reference to display. */
+  trackRef?: TrackReferenceOrPlaceholder;
+  disableSpeakingIndicator?: boolean;
+
+  onParticipantClick?: (event: ParticipantClickEvent) => void;
+}
+
+/**
+ * The `ParticipantTile` component is the base utility wrapper for displaying a visual representation of a participant.
+ * This component can be used as a child of the `TrackLoop` component or by passing a track reference as property.
+ *
+ * @example Using the `ParticipantTile` component with a track reference:
+ * ```tsx
+ * <ParticipantTile trackRef={trackRef} />
+ * ```
+ * @example Using the `ParticipantTile` component as a child of the `TrackLoop` component:
+ * ```tsx
+ * <TrackLoop>
+ *  <ParticipantTile />
+ * </TrackLoop>
+ * ```
+ * @public
+ */
+export const ParticipantTile: (
+  props: ParticipantTileProps & React.RefAttributes<HTMLDivElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLDivElement, ParticipantTileProps>(
+  function ParticipantTile(
+    {
+      trackRef,
+      children,
+      onParticipantClick,
+      disableSpeakingIndicator,
+      ...htmlProps
+    }: ParticipantTileProps,
+    ref,
+  ) {
+    const trackReference = useEnsureTrackRef(trackRef);
+
+    const { elementProps } = useParticipantTile<HTMLDivElement>({
+      htmlProps,
+      disableSpeakingIndicator,
+      onParticipantClick,
+      trackRef: trackReference,
+    });
+    const isEncrypted = useIsEncrypted(trackReference.participant);
+    const layoutContext = useMaybeLayoutContext();
+
+    const autoManageSubscription = useFeatureContext()?.autoSubscription;
+
+    const handleSubscribe = React.useCallback(
+      (subscribed: boolean) => {
+        if (
+          trackReference.source &&
+          !subscribed &&
+          layoutContext &&
+          layoutContext.pin.dispatch &&
+          isTrackReferencePinned(trackReference, layoutContext.pin.state)
+        ) {
+          layoutContext.pin.dispatch({ msg: 'clear_pin' });
+        }
+      },
+      [trackReference, layoutContext],
+    );
+
+    return (
+      <div ref={ref} style={{ position: 'relative' }} {...elementProps}>
+        <TrackRefContextIfNeeded trackRef={trackReference}>
+          <ParticipantContextIfNeeded participant={trackReference.participant}>
+            {children ?? (
+              <>
+                {isTrackReference(trackReference) &&
+                (trackReference.publication?.kind === 'video' ||
+                  trackReference.source === Track.Source.Camera ||
+                  trackReference.source === Track.Source.ScreenShare) ? (
+                  <VideoTrack
+                    trackRef={trackReference}
+                    onSubscriptionStatusChanged={handleSubscribe}
+                    manageSubscription={autoManageSubscription}
+                  />
+                ) : (
+                  isTrackReference(trackReference) && (
+                    <AudioTrack
+                      trackRef={trackReference}
+                      onSubscriptionStatusChanged={handleSubscribe}
+                    />
+                  )
+                )}
+                <div className="lk-participant-placeholder">
+                  <ParticipantPlaceholder />
+                </div>
+                <div className="lk-participant-metadata">
+                  <div className="lk-participant-metadata-item">
+                    {trackReference.source === Track.Source.Camera ? (
+                      <>
+                        {isEncrypted && <LockLockedIcon style={{ marginRight: '0.25rem' }} />}
+                        <TrackMutedIndicator
+                          trackRef={{
+                            participant: trackReference.participant,
+                            source: Track.Source.Microphone,
+                          }}
+                          show={'muted'}
+                        ></TrackMutedIndicator>
+                        <ParticipantName />
+                      </>
+                    ) : (
+                      <>
+                        <ScreenShareIcon style={{ marginRight: '0.25rem' }} />
+                        <ParticipantName>&apos;s screen</ParticipantName>
+                      </>
+                    )}
+                  </div>
+                  <ConnectionQualityIndicator className="lk-participant-metadata-item" />
+                </div>
+              </>
+            )}
+            <FocusToggle trackRef={trackReference} />
+          </ParticipantContextIfNeeded>
+        </TrackRefContextIfNeeded>
+      </div>
+    );
+  },
+);

package/src/components/participant/TrackMutedIndicator.tsx

@@ -0,0 +1,53 @@
+import * as React from 'react';
+import { mergeProps } from '../../utils';
+import { getSourceIcon } from '../../assets/icons/util';
+import { useTrackMutedIndicator } from '../../hooks';
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+
+/** @public */
+export interface TrackMutedIndicatorProps extends React.HTMLAttributes<HTMLDivElement> {
+  trackRef: TrackReferenceOrPlaceholder;
+  show?: 'always' | 'muted' | 'unmuted';
+}
+
+/**
+ * The `TrackMutedIndicator` shows whether the participant's camera or microphone is muted or not.
+ * By default, a muted/unmuted icon is displayed for a camera, microphone, and screen sharing track.
+ *
+ * @example
+ * ```tsx
+ * <TrackMutedIndicator trackRef={trackRef} />
+ * ```
+ * @public
+ */
+export const TrackMutedIndicator: (
+  props: TrackMutedIndicatorProps & React.RefAttributes<HTMLDivElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLDivElement, TrackMutedIndicatorProps>(
+  function TrackMutedIndicator(
+    { trackRef, show = 'always', ...props }: TrackMutedIndicatorProps,
+    ref,
+  ) {
+    const { className, isMuted } = useTrackMutedIndicator(trackRef);
+
+    const showIndicator =
+      show === 'always' || (show === 'muted' && isMuted) || (show === 'unmuted' && !isMuted);
+
+    const htmlProps = React.useMemo(
+      () =>
+        mergeProps(props, {
+          className,
+        }),
+      [className, props],
+    );
+
+    if (!showIndicator) {
+      return null;
+    }
+
+    return (
+      <div ref={ref} {...htmlProps} data-lk-muted={isMuted}>
+        {props.children ?? getSourceIcon(trackRef.source, !isMuted)}
+      </div>
+    );
+  },
+);

package/src/components/participant/VideoTrack.tsx

@@ -0,0 +1,92 @@
+import { RemoteTrackPublication } from 'livekit-client';
+import * as React from 'react';
+import { useMediaTrackBySourceOrName } from '../../hooks/useMediaTrackBySourceOrName';
+import type { ParticipantClickEvent, TrackReference } from '@livekit/components-core';
+import { useEnsureTrackRef } from '../../context';
+import * as useHooks from 'usehooks-ts';
+
+/** @public */
+export interface VideoTrackProps extends React.VideoHTMLAttributes<HTMLVideoElement> {
+  /** The track reference of the track to render. */
+  trackRef?: TrackReference;
+  onTrackClick?: (evt: ParticipantClickEvent) => void;
+  onSubscriptionStatusChanged?: (subscribed: boolean) => void;
+  manageSubscription?: boolean;
+}
+
+/**
+ * The `VideoTrack` component is responsible for rendering participant video tracks like `camera` and `screen_share`.
+ * This component must have access to the participant's context, or alternatively pass it a `Participant` as a property.
+ *
+ * @example
+ * ```tsx
+ * <VideoTrack trackRef={trackRef} />
+ * ```
+ * @see {@link @livekit/components-react#ParticipantTile | ParticipantTile}
+ * @public
+ */
+export const VideoTrack: (
+  props: VideoTrackProps & React.RefAttributes<HTMLVideoElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLVideoElement, VideoTrackProps>(
+  function VideoTrack(
+    {
+      onTrackClick,
+      onClick,
+      onSubscriptionStatusChanged,
+      trackRef,
+      manageSubscription,
+      ...props
+    }: VideoTrackProps,
+    ref,
+  ) {
+    const trackReference = useEnsureTrackRef(trackRef);
+
+    const mediaEl = React.useRef<HTMLVideoElement>(null);
+    React.useImperativeHandle(ref, () => mediaEl.current as HTMLVideoElement);
+
+    const intersectionEntry = useHooks.useIntersectionObserver({ root: mediaEl.current });
+
+    const [debouncedIntersectionEntry] = useHooks.useDebounceValue(intersectionEntry, 3000);
+
+    React.useEffect(() => {
+      if (
+        manageSubscription &&
+        trackReference.publication instanceof RemoteTrackPublication &&
+        debouncedIntersectionEntry?.isIntersecting === false &&
+        intersectionEntry?.isIntersecting === false
+      ) {
+        trackReference.publication.setSubscribed(false);
+      }
+    }, [debouncedIntersectionEntry, trackReference, manageSubscription]);
+
+    React.useEffect(() => {
+      if (
+        manageSubscription &&
+        trackReference.publication instanceof RemoteTrackPublication &&
+        intersectionEntry?.isIntersecting === true
+      ) {
+        trackReference.publication.setSubscribed(true);
+      }
+    }, [intersectionEntry, trackReference, manageSubscription]);
+
+    const {
+      elementProps,
+      publication: pub,
+      isSubscribed,
+    } = useMediaTrackBySourceOrName(trackReference, {
+      element: mediaEl,
+      props,
+    });
+
+    React.useEffect(() => {
+      onSubscriptionStatusChanged?.(!!isSubscribed);
+    }, [isSubscribed, onSubscriptionStatusChanged]);
+
+    const clickHandler = (evt: React.MouseEvent<HTMLVideoElement, MouseEvent>) => {
+      onClick?.(evt);
+      onTrackClick?.({ participant: trackReference?.participant, track: pub });
+    };
+
+    return <video ref={mediaEl} {...elementProps} muted={true} onClick={clickHandler}></video>;
+  },
+);

package/src/components/participant/animationSequences/connectingSequence.ts

@@ -0,0 +1,9 @@
+export const generateConnectingSequenceBar = (columns: number): number[][] => {
+  const seq = [];
+
+  for (let x = 0; x < columns; x++) {
+    seq.push([x, columns - 1 - x]);
+  }
+
+  return seq;
+};

package/src/components/participant/animationSequences/listeningSequence.ts

@@ -0,0 +1,6 @@
+export const generateListeningSequenceBar = (columns: number): number[][] => {
+  const center = Math.floor(columns / 2);
+  const noIndex = -1;
+
+  return [[center], [noIndex]];
+};

package/src/components/participant/animationSequences/thinkingSequence.ts

@@ -0,0 +1,12 @@
+export const generateThinkingSequenceBar = (columns: number): number[][] => {
+  const seq = [];
+  for (let x = 0; x < columns; x++) {
+    seq.push([x]);
+  }
+
+  for (let x = columns - 1; x >= 0; x--) {
+    seq.push([x]);
+  }
+
+  return seq;
+};

package/src/components/participant/animators/useBarAnimator.ts

@@ -0,0 +1,55 @@
+import { useEffect, useRef, useState } from 'react';
+import { generateConnectingSequenceBar } from '../animationSequences/connectingSequence';
+import { generateListeningSequenceBar } from '../animationSequences/listeningSequence';
+import type { AgentState } from '../../../hooks';
+
+export const useBarAnimator = (
+  state: AgentState | undefined,
+  columns: number,
+  interval: number,
+): number[] => {
+  const [index, setIndex] = useState(0);
+  const [sequence, setSequence] = useState<number[][]>([[]]);
+
+  useEffect(() => {
+    if (state === 'thinking') {
+      setSequence(generateListeningSequenceBar(columns));
+    } else if (state === 'connecting' || state === 'initializing') {
+      const sequence = [...generateConnectingSequenceBar(columns)];
+      setSequence(sequence);
+    } else if (state === 'listening') {
+      setSequence(generateListeningSequenceBar(columns));
+    } else if (state === undefined || state === 'speaking') {
+      setSequence([new Array(columns).fill(0).map((_, idx) => idx)]);
+    } else {
+      setSequence([[]]);
+    }
+    setIndex(0);
+  }, [state, columns]);
+
+  const animationFrameId = useRef<number | null>(null);
+  useEffect(() => {
+    let startTime = performance.now();
+
+    const animate = (time: DOMHighResTimeStamp) => {
+      const timeElapsed = time - startTime;
+
+      if (timeElapsed >= interval) {
+        setIndex((prev) => prev + 1);
+        startTime = time;
+      }
+
+      animationFrameId.current = requestAnimationFrame(animate);
+    };
+
+    animationFrameId.current = requestAnimationFrame(animate);
+
+    return () => {
+      if (animationFrameId.current !== null) {
+        cancelAnimationFrame(animationFrameId.current);
+      }
+    };
+  }, [interval, columns, state, sequence.length]);
+
+  return sequence[index % sequence.length];
+};

package/src/context/chat-context.ts

@@ -0,0 +1,37 @@
+import type { WidgetState } from '@livekit/components-core';
+import type * as React from 'react';
+
+/** @internal */
+export type ChatContextAction =
+  | { msg: 'show_chat' }
+  | { msg: 'hide_chat' }
+  | { msg: 'toggle_chat' }
+  | { msg: 'unread_msg'; count: number }
+  | { msg: 'toggle_settings' };
+
+/** @internal */
+export type WidgetContextType = {
+  dispatch?: React.Dispatch<ChatContextAction>;
+  state?: WidgetState;
+};
+
+/** @internal */
+export function chatReducer(state: WidgetState, action: ChatContextAction): WidgetState {
+  if (action.msg === 'show_chat') {
+    return { ...state, showChat: true, unreadMessages: 0 };
+  } else if (action.msg === 'hide_chat') {
+    return { ...state, showChat: false };
+  } else if (action.msg === 'toggle_chat') {
+    const newState = { ...state, showChat: !state.showChat };
+    if (newState.showChat === true) {
+      newState.unreadMessages = 0;
+    }
+    return newState;
+  } else if (action.msg === 'unread_msg') {
+    return { ...state, unreadMessages: action.count };
+  } else if (action.msg === 'toggle_settings') {
+    return { ...state, showSettings: !state.showSettings };
+  } else {
+    return { ...state };
+  }
+}

package/src/context/feature-context.ts

@@ -0,0 +1,28 @@
+import * as React from 'react';
+
+/** @internal */
+export interface FeatureFlags {
+  autoSubscription?: boolean;
+}
+
+type FeatureContext<T extends boolean = false> = T extends true
+  ? FeatureFlags
+  : FeatureFlags | undefined;
+
+/** @internal */
+export const LKFeatureContext = React.createContext<FeatureFlags | undefined>(undefined);
+
+/**
+ * @internal
+ */
+export function useFeatureContext<T extends boolean>(require?: T): FeatureContext<T> {
+  const ctx = React.useContext(LKFeatureContext) as FeatureContext<T>;
+  if (require === true) {
+    if (ctx) {
+      return ctx;
+    } else {
+      throw Error('tried to access feature context, but none is present');
+    }
+  }
+  return ctx;
+}

package/src/context/index.ts

@@ -0,0 +1,27 @@
+export {} from './chat-context';
+export type { LayoutContextType } from './layout-context';
+export {
+  LayoutContext,
+  useCreateLayoutContext,
+  useEnsureCreateLayoutContext,
+  useEnsureLayoutContext,
+  useLayoutContext,
+  useMaybeLayoutContext,
+} from './layout-context';
+export {
+  ParticipantContext,
+  useEnsureParticipant,
+  useMaybeParticipantContext,
+  useParticipantContext,
+} from './participant-context';
+export {} from './pin-context';
+export { RoomContext, useEnsureRoom, useMaybeRoomContext, useRoomContext } from './room-context';
+export { useEnsureSession, useMaybeSessionContext, useSessionContext } from './session-context';
+export {
+  TrackRefContext,
+  useEnsureTrackRef,
+  useMaybeTrackRefContext,
+  useTrackRefContext,
+} from './track-reference-context';
+
+export { type FeatureFlags, useFeatureContext, LKFeatureContext } from './feature-context';

package/src/context/layout-context.ts

@@ -0,0 +1,72 @@
+import { PIN_DEFAULT_STATE, WIDGET_DEFAULT_STATE } from '@livekit/components-core';
+import * as React from 'react';
+import type { PinContextType } from './pin-context';
+import type { WidgetContextType } from './chat-context';
+import { chatReducer } from './chat-context';
+import { pinReducer } from './pin-context';
+
+/** @public */
+export type LayoutContextType = {
+  pin: PinContextType;
+  widget: WidgetContextType;
+};
+
+/** @public */
+export const LayoutContext = React.createContext<LayoutContextType | undefined>(undefined);
+
+/**
+ * Ensures that a layout context is provided via context.
+ * If no layout context is provided, an error is thrown.
+ * @public
+ */
+export function useLayoutContext(): LayoutContextType {
+  const layoutContext = React.useContext(LayoutContext);
+  if (!layoutContext) {
+    throw Error('Tried to access LayoutContext context outside a LayoutContextProvider provider.');
+  }
+  return layoutContext;
+}
+
+/**
+ * Ensures that a layout context is provided, either via context or explicitly as a parameter.
+ * If not inside a `LayoutContext` and no layout context is provided, an error is thrown.
+ * @public
+ */
+export function useEnsureLayoutContext(layoutContext?: LayoutContextType) {
+  const layout = useMaybeLayoutContext();
+  layoutContext ??= layout;
+  if (!layoutContext) {
+    throw Error('Tried to access LayoutContext context outside a LayoutContextProvider provider.');
+  }
+  return layoutContext;
+}
+
+/** @public */
+export function useCreateLayoutContext(): LayoutContextType {
+  const [pinState, pinDispatch] = React.useReducer(pinReducer, PIN_DEFAULT_STATE);
+  const [widgetState, widgetDispatch] = React.useReducer(chatReducer, WIDGET_DEFAULT_STATE);
+  return {
+    pin: { dispatch: pinDispatch, state: pinState },
+    widget: { dispatch: widgetDispatch, state: widgetState },
+  };
+}
+
+/** @public */
+export function useEnsureCreateLayoutContext(layoutContext?: LayoutContextType): LayoutContextType {
+  const [pinState, pinDispatch] = React.useReducer(pinReducer, PIN_DEFAULT_STATE);
+  const [widgetState, widgetDispatch] = React.useReducer(chatReducer, WIDGET_DEFAULT_STATE);
+  return (
+    layoutContext ?? {
+      pin: { dispatch: pinDispatch, state: pinState },
+      widget: { dispatch: widgetDispatch, state: widgetState },
+    }
+  );
+}
+
+/**
+ * Returns a layout context from the `LayoutContext` if it exists, otherwise `undefined`.
+ * @public
+ */
+export function useMaybeLayoutContext(): LayoutContextType | undefined {
+  return React.useContext(LayoutContext);
+}

package/src/context/participant-context.ts

@@ -0,0 +1,44 @@
+import type { Participant } from 'livekit-client';
+import * as React from 'react';
+import { useMaybeTrackRefContext } from './track-reference-context';
+
+/** @public */
+export const ParticipantContext = React.createContext<Participant | undefined>(undefined);
+
+/**
+ * Ensures that a participant is provided via context.
+ * If not inside a `ParticipantContext`, an error is thrown.
+ * @public
+ */
+export function useParticipantContext() {
+  const participant = React.useContext(ParticipantContext);
+  if (!participant) {
+    throw Error('tried to access participant context outside of participant context provider');
+  }
+  return participant;
+}
+
+/**
+ * Returns a participant from the `ParticipantContext` if it exists, otherwise `undefined`.
+ * @public
+ */
+export function useMaybeParticipantContext() {
+  return React.useContext(ParticipantContext);
+}
+
+/**
+ * Ensures that a participant is provided, either via context or explicitly as a parameter.
+ * If not inside a `ParticipantContext` and no participant is provided, an error is thrown.
+ * @public
+ */
+export function useEnsureParticipant(participant?: Participant) {
+  const context = useMaybeParticipantContext();
+  const trackContext = useMaybeTrackRefContext();
+  const p = participant ?? context ?? trackContext?.participant;
+  if (!p) {
+    throw new Error(
+      'No participant provided, make sure you are inside a participant context or pass the participant explicitly',
+    );
+  }
+  return p;
+}

package/src/context/pin-context.ts

@@ -0,0 +1,27 @@
+import type { PinState, TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import type * as React from 'react';
+
+/** @internal */
+export type PinAction =
+  | {
+      msg: 'set_pin';
+      trackReference: TrackReferenceOrPlaceholder;
+    }
+  | { msg: 'clear_pin' };
+
+/** @internal */
+export type PinContextType = {
+  dispatch?: React.Dispatch<PinAction>;
+  state?: PinState;
+};
+
+/** @internal */
+export function pinReducer(state: PinState, action: PinAction): PinState {
+  if (action.msg === 'set_pin') {
+    return [action.trackReference];
+  } else if (action.msg === 'clear_pin') {
+    return [];
+  } else {
+    return { ...state };
+  }
+}