@werxt/livekit-components-react 2.9.20

package/src/components/controls/DisconnectButton.tsx

@@ -0,0 +1,32 @@
+import * as React from 'react';
+import { useDisconnectButton } from '../../hooks';
+
+/** @public */
+export interface DisconnectButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  stopTracks?: boolean;
+}
+
+/**
+ * The `DisconnectButton` is a basic html button with the added ability to disconnect from a LiveKit room.
+ * Normally this is the big red button that allows end users to leave the video or audio call.
+ *
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <DisconnectButton>Leave room</DisconnectButton>
+ * </LiveKitRoom>
+ * ```
+ * @public
+ */
+export const DisconnectButton: (
+  props: DisconnectButtonProps & React.RefAttributes<HTMLButtonElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLButtonElement, DisconnectButtonProps>(
+  function DisconnectButton(props: DisconnectButtonProps, ref) {
+    const { buttonProps } = useDisconnectButton(props);
+    return (
+      <button ref={ref} {...buttonProps}>
+        {props.children}
+      </button>
+    );
+  },
+);

package/src/components/controls/FocusToggle.tsx

@@ -0,0 +1,54 @@
+import * as React from 'react';
+import { LayoutContext, useMaybeTrackRefContext } from '../../context';
+import { FocusToggleIcon, UnfocusToggleIcon } from '../../assets/icons';
+import { useFocusToggle } from '../../hooks';
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+
+/** @public */
+export interface FocusToggleProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  trackRef?: TrackReferenceOrPlaceholder;
+}
+
+/**
+ * The `FocusToggle` puts the `ParticipantTile` in focus or removes it from focus.
+ * @remarks
+ * This component needs to live inside `LayoutContext` to work properly.
+ *
+ * @example
+ * ```tsx
+ * <ParticipantTile>
+ *   <FocusToggle />
+ * </ParticipantTile>
+ * ```
+ * @public
+ */
+export const FocusToggle: (
+  props: FocusToggleProps & React.RefAttributes<HTMLButtonElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLButtonElement, FocusToggleProps>(
+  function FocusToggle({ trackRef, ...props }: FocusToggleProps, ref) {
+    const trackRefFromContext = useMaybeTrackRefContext();
+
+    const { mergedProps, inFocus } = useFocusToggle({
+      trackRef: trackRef ?? trackRefFromContext,
+      props,
+    });
+
+    return (
+      <LayoutContext.Consumer>
+        {(layoutContext) =>
+          layoutContext !== undefined && (
+            <button ref={ref} {...mergedProps}>
+              {props.children ? (
+                props.children
+              ) : inFocus ? (
+                <UnfocusToggleIcon />
+              ) : (
+                <FocusToggleIcon />
+              )}
+            </button>
+          )
+        }
+      </LayoutContext.Consumer>
+    );
+  },
+);

package/src/components/controls/MediaDeviceSelect.tsx

@@ -0,0 +1,144 @@
+import * as React from 'react';
+import { useMaybeRoomContext } from '../../context';
+import { mergeProps } from '../../utils';
+import { RoomEvent, type LocalAudioTrack, type LocalVideoTrack } from 'livekit-client';
+import { useMediaDeviceSelect } from '../../hooks';
+
+/** @public */
+export interface MediaDeviceSelectProps
+  extends Omit<React.HTMLAttributes<HTMLUListElement>, 'onError'> {
+  kind: MediaDeviceKind;
+  onActiveDeviceChange?: (deviceId: string) => void;
+  onDeviceListChange?: (devices: MediaDeviceInfo[]) => void;
+  onDeviceSelectError?: (e: Error) => void;
+  initialSelection?: string;
+  /** will force the browser to only return the specified device
+   * will call `onDeviceSelectError` with the error in case this fails
+   */
+  exactMatch?: boolean;
+  track?: LocalAudioTrack | LocalVideoTrack;
+  /**
+   * this will call getUserMedia if the permissions are not yet given to enumerate the devices with device labels.
+   * in some browsers multiple calls to getUserMedia result in multiple permission prompts.
+   * It's generally advised only flip this to true, once a (preview) track has been acquired successfully with the
+   * appropriate permissions.
+   *
+   * @see {@link MediaDeviceMenu}
+   * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/MediaDevices/enumerateDevices | MDN enumerateDevices}
+   */
+  requestPermissions?: boolean;
+  onError?: (e: Error) => void;
+}
+
+/**
+ * The `MediaDeviceSelect` list all media devices of one kind.
+ * Clicking on one of the listed devices make it the active media device.
+ *
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <MediaDeviceSelect kind='audioinput' />
+ * </LiveKitRoom>
+ * ```
+ * @public
+ */
+export const MediaDeviceSelect: (
+  props: MediaDeviceSelectProps & React.RefAttributes<HTMLUListElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLUListElement, MediaDeviceSelectProps>(
+  function MediaDeviceSelect(
+    {
+      kind,
+      initialSelection,
+      onActiveDeviceChange,
+      onDeviceListChange,
+      onDeviceSelectError,
+      exactMatch,
+      track,
+      requestPermissions,
+      onError,
+      ...props
+    }: MediaDeviceSelectProps,
+    ref,
+  ) {
+    const room = useMaybeRoomContext();
+    const previousActiveDeviceId = React.useRef<string>('default');
+    const handleError = React.useCallback(
+      (e: Error) => {
+        if (room) {
+          // awkwardly emit the event from outside of the room, as we don't have other means to raise a MediaDeviceError
+          room.emit(RoomEvent.MediaDevicesError, e);
+        }
+        onError?.(e);
+      },
+      [room, onError],
+    );
+    const { devices, activeDeviceId, setActiveMediaDevice, className } = useMediaDeviceSelect({
+      kind,
+      room,
+      track,
+      requestPermissions,
+      onError: handleError,
+    });
+    React.useEffect(() => {
+      if (initialSelection !== undefined) {
+        setActiveMediaDevice(initialSelection);
+      }
+    }, [setActiveMediaDevice]);
+
+    React.useEffect(() => {
+      if (typeof onDeviceListChange === 'function') {
+        onDeviceListChange(devices);
+      }
+    }, [onDeviceListChange, devices]);
+
+    React.useEffect(() => {
+      if (activeDeviceId !== previousActiveDeviceId.current) {
+        onActiveDeviceChange?.(activeDeviceId);
+      }
+      previousActiveDeviceId.current = activeDeviceId;
+    }, [activeDeviceId]);
+
+    const handleActiveDeviceChange = async (deviceId: string) => {
+      try {
+        await setActiveMediaDevice(deviceId, { exact: exactMatch ?? true });
+      } catch (e) {
+        if (e instanceof Error) {
+          onDeviceSelectError?.(e);
+        } else {
+          throw e;
+        }
+      }
+    };
+    // Merge Props
+    const mergedProps = React.useMemo(
+      () => mergeProps(props, { className }, { className: 'lk-list' }),
+      [className, props],
+    );
+
+    const hasDefault = !!devices.find((info) => info.label.toLowerCase().startsWith('default'));
+
+    function isActive(deviceId: string, activeDeviceId: string, index: number) {
+      return (
+        deviceId === activeDeviceId || (!hasDefault && index === 0 && activeDeviceId === 'default')
+      );
+    }
+
+    return (
+      <ul ref={ref} {...mergedProps}>
+        {devices.map((device, index) => (
+          <li
+            key={device.deviceId}
+            id={device.deviceId}
+            data-lk-active={isActive(device.deviceId, activeDeviceId, index)}
+            aria-selected={isActive(device.deviceId, activeDeviceId, index)}
+            role="option"
+          >
+            <button className="lk-button" onClick={() => handleActiveDeviceChange(device.deviceId)}>
+              {device.label}
+            </button>
+          </li>
+        ))}
+      </ul>
+    );
+  },
+);

package/src/components/controls/PaginationControl.tsx

@@ -0,0 +1,51 @@
+import * as React from 'react';
+import SvgChevron from '../../assets/icons/Chevron';
+import type { usePagination } from '../../hooks';
+import { createInteractingObservable } from '@livekit/components-core';
+
+export interface PaginationControlProps
+  extends Pick<
+    ReturnType<typeof usePagination>,
+    'totalPageCount' | 'nextPage' | 'prevPage' | 'currentPage'
+  > {
+  /** Reference to an HTML element that holds the pages, while interacting (`mouseover`)
+   *  with it, the pagination controls will appear for a while. */
+  pagesContainer?: React.RefObject<HTMLElement>;
+}
+
+export function PaginationControl({
+  totalPageCount,
+  nextPage,
+  prevPage,
+  currentPage,
+  pagesContainer: connectedElement,
+}: PaginationControlProps) {
+  const [interactive, setInteractive] = React.useState(false);
+  React.useEffect(() => {
+    let subscription:
+      | ReturnType<ReturnType<typeof createInteractingObservable>['subscribe']>
+      | undefined;
+    if (connectedElement) {
+      subscription = createInteractingObservable(connectedElement.current, 2000).subscribe(
+        setInteractive,
+      );
+    }
+    return () => {
+      if (subscription) {
+        subscription.unsubscribe();
+      }
+    };
+  }, [connectedElement]);
+
+  return (
+    <div className="lk-pagination-control" data-lk-user-interaction={interactive}>
+      <button className="lk-button" onClick={prevPage}>
+        <SvgChevron />
+      </button>
+      <span className="lk-pagination-count">{`${currentPage} of ${totalPageCount}`}</span>
+      <button className="lk-button" onClick={nextPage}>
+        <SvgChevron />
+      </button>
+    </div>
+  );
+}

package/src/components/controls/PaginationIndicator.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react';
+
+export interface PaginationIndicatorProps {
+  totalPageCount: number;
+  currentPage: number;
+}
+
+export const PaginationIndicator: (
+  props: PaginationIndicatorProps & React.RefAttributes<HTMLDivElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLDivElement, PaginationIndicatorProps>(
+  function PaginationIndicator({ totalPageCount, currentPage }: PaginationIndicatorProps, ref) {
+    const bubbles = new Array(totalPageCount).fill('').map((_, index) => {
+      if (index + 1 === currentPage) {
+        return <span data-lk-active key={index} />;
+      } else {
+        return <span key={index} />;
+      }
+    });
+
+    return (
+      <div ref={ref} className="lk-pagination-indicator">
+        {bubbles}
+      </div>
+    );
+  },
+);

package/src/components/controls/SettingsMenuToggle.tsx

@@ -0,0 +1,26 @@
+import * as React from 'react';
+import { useSettingsToggle } from '../../hooks/useSettingsToggle';
+
+/** @alpha */
+export interface SettingsMenuToggleProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {}
+
+/**
+ * The `SettingsMenuToggle` component is a button that toggles the visibility of the `SettingsMenu` component.
+ * @remarks
+ * For the component to have any effect it has to live inside a `LayoutContext` context.
+ *
+ * @alpha
+ */
+export const SettingsMenuToggle: (
+  props: SettingsMenuToggleProps & React.RefAttributes<HTMLButtonElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLButtonElement, SettingsMenuToggleProps>(
+  function SettingsMenuToggle(props: SettingsMenuToggleProps, ref) {
+    const { mergedProps } = useSettingsToggle({ props });
+
+    return (
+      <button ref={ref} {...mergedProps}>
+        {props.children}
+      </button>
+    );
+  },
+);

package/src/components/controls/StartAudio.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import { useEnsureRoom } from '../../context';
+import { useStartAudio } from '../../hooks';
+import { Room } from 'livekit-client';
+
+/** @public */
+export interface AllowAudioPlaybackProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  room?: Room;
+  label: string;
+}
+
+/**
+ * The `StartAudio` component is only visible when the browser blocks audio playback. This is due to some browser implemented autoplay policies.
+ * To start audio playback, the user must perform a user-initiated event such as clicking this button.
+ * As soon as audio playback starts, the button hides itself again.
+ *
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <StartAudio label="Click to allow audio playback" />
+ * </LiveKitRoom>
+ * ```
+ *
+ * @see Autoplay policy on MDN web docs: {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices#autoplay_policy}
+ * @public
+ */
+export const StartAudio: (
+  props: AllowAudioPlaybackProps & React.RefAttributes<HTMLButtonElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLButtonElement, AllowAudioPlaybackProps>(
+  function StartAudio({ label = 'Allow Audio', ...props }: AllowAudioPlaybackProps, ref) {
+    const room = useEnsureRoom(props.room);
+    const { mergedProps } = useStartAudio({ room, props });
+
+    return (
+      <button ref={ref} {...mergedProps}>
+        {label}
+      </button>
+    );
+  },
+);

package/src/components/controls/StartMediaButton.tsx

@@ -0,0 +1,41 @@
+import * as React from 'react';
+import { useRoomContext } from '../../context';
+import { useStartAudio, useStartVideo } from '../../hooks';
+
+/** @public */
+export interface AllowMediaPlaybackProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  label?: string;
+}
+
+/**
+ * The `StartMediaButton` component is only visible when the browser blocks media playback. This is due to some browser implemented autoplay policies.
+ * To start media playback, the user must perform a user-initiated event such as clicking this button.
+ * As soon as media playback starts, the button hides itself again.
+ *
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <StartMediaButton label="Click to allow media playback" />
+ * </LiveKitRoom>
+ * ```
+ *
+ * @see Autoplay policy on MDN web docs: {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Audio_API/Best_practices#autoplay_policy}
+ * @public
+ */
+export const StartMediaButton: (
+  props: AllowMediaPlaybackProps & React.RefAttributes<HTMLButtonElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLButtonElement, AllowMediaPlaybackProps>(
+  function StartMediaButton({ label, ...props }: AllowMediaPlaybackProps, ref) {
+    const room = useRoomContext();
+    const { mergedProps: audioProps, canPlayAudio } = useStartAudio({ room, props });
+    const { mergedProps, canPlayVideo } = useStartVideo({ room, props: audioProps });
+    const { style, ...restProps } = mergedProps;
+    style.display = canPlayAudio && canPlayVideo ? 'none' : 'block';
+
+    return (
+      <button ref={ref} style={style} {...restProps}>
+        {label ?? `Start ${!canPlayAudio ? 'Audio' : 'Video'}`}
+      </button>
+    );
+  },
+);

package/src/components/controls/TrackToggle.tsx

@@ -0,0 +1,54 @@
+import type { CaptureOptionsBySource, ToggleSource } from '@livekit/components-core';
+import * as React from 'react';
+import { getSourceIcon } from '../../assets/icons/util';
+import { useTrackToggle } from '../../hooks';
+import { TrackPublishOptions } from 'livekit-client';
+
+/** @public */
+export interface TrackToggleProps<T extends ToggleSource>
+  extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
+  source: T;
+  showIcon?: boolean;
+  initialState?: boolean;
+  /**
+   * Function that is called when the enabled state of the toggle changes.
+   * The second function argument `isUserInitiated` is `true` if the change was initiated by a user interaction, such as a click.
+   */
+  onChange?: (enabled: boolean, isUserInitiated: boolean) => void;
+  captureOptions?: CaptureOptionsBySource<T>;
+  publishOptions?: TrackPublishOptions;
+  onDeviceError?: (error: Error) => void;
+}
+
+/**
+ * With the `TrackToggle` component it is possible to mute and unmute your camera and microphone.
+ * The component uses an html button element under the hood so you can treat it like a button.
+ *
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <TrackToggle source={Track.Source.Microphone} />
+ *   <TrackToggle source={Track.Source.Camera} />
+ * </LiveKitRoom>
+ * ```
+ * @public
+ */
+export const TrackToggle: <T extends ToggleSource>(
+  props: TrackToggleProps<T> & React.RefAttributes<HTMLButtonElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef(function TrackToggle<
+  T extends ToggleSource,
+>({ showIcon, ...props }: TrackToggleProps<T>, ref: React.ForwardedRef<HTMLButtonElement>) {
+  const { buttonProps, enabled } = useTrackToggle(props);
+  const [isClient, setIsClient] = React.useState(false);
+  React.useEffect(() => {
+    setIsClient(true);
+  }, []);
+  return (
+    isClient && (
+      <button ref={ref} {...buttonProps}>
+        {(showIcon ?? true) && getSourceIcon(props.source, enabled)}
+        {props.children}
+      </button>
+    )
+  );
+});

package/src/components/index.ts

@@ -0,0 +1,34 @@
+export * from './controls/ClearPinButton';
+export * from './ConnectionState';
+export * from './controls/ChatToggle';
+export * from './controls/DisconnectButton';
+export * from './controls/FocusToggle';
+export * from './controls/MediaDeviceSelect';
+export * from './controls/StartAudio';
+export * from './controls/StartMediaButton';
+export * from './controls/TrackToggle';
+export * from './layout';
+export * from './layout/LayoutContextProvider';
+export * from './LiveKitRoom';
+export * from './participant/AudioVisualizer';
+export * from './participant/ConnectionQualityIndicator';
+export * from './participant/AudioTrack';
+export * from './participant/VideoTrack';
+export * from './participant/ParticipantName';
+export * from './participant/TrackMutedIndicator';
+export * from './ParticipantLoop';
+export { RoomAudioRenderer, type RoomAudioRendererProps } from './RoomAudioRenderer';
+export * from './RoomName';
+export { Toast } from './Toast';
+export * from './TrackLoop';
+export * from './participant/ParticipantTile';
+export * from './participant/ParticipantAudioTile';
+export * from './participant/BarVisualizer';
+export { ConnectionStateToast, type ConnectionStateToastProps } from './ConnectionStateToast';
+export {
+  type MessageFormatter,
+  type ChatEntryProps,
+  ChatEntry,
+  formatChatMessageLinks,
+} from './ChatEntry';
+export * from './SessionProvider';

package/src/components/layout/CarouselLayout.tsx

@@ -0,0 +1,80 @@
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { getScrollBarWidth } from '@livekit/components-core';
+import * as React from 'react';
+import { useSize } from '../../hooks/internal';
+import { useVisualStableUpdate } from '../../hooks';
+import { TrackLoop } from '../TrackLoop';
+
+const MIN_HEIGHT = 130;
+const MIN_WIDTH = 140;
+const MIN_VISIBLE_TILES = 1;
+const ASPECT_RATIO = 16 / 10;
+const ASPECT_RATIO_INVERT = (1 - ASPECT_RATIO) * -1;
+
+/** @public */
+export interface CarouselLayoutProps extends React.HTMLAttributes<HTMLMediaElement> {
+  tracks: TrackReferenceOrPlaceholder[];
+  children: React.ReactNode;
+  /** Place the tiles vertically or horizontally next to each other.
+   * If undefined orientation is guessed by the dimensions of the container. */
+  orientation?: 'vertical' | 'horizontal';
+}
+
+/**
+ * The `CarouselLayout` component displays a list of tracks in a scroll container.
+ * It will display as many tiles as possible and overflow the rest.
+ * @remarks
+ * To ensure visual stability when tiles are reordered due to track updates,
+ * the component uses the `useVisualStableUpdate` hook.
+ * @example
+ * ```tsx
+ * const tracks = useTracks([Track.Source.Camera]);
+ * <CarouselLayout tracks={tracks}>
+ *   <ParticipantTile />
+ * </CarouselLayout>
+ * ```
+ * @public
+ */
+export function CarouselLayout({ tracks, orientation, ...props }: CarouselLayoutProps) {
+  const asideEl = React.useRef<HTMLDivElement>(null);
+  const [prevTiles, setPrevTiles] = React.useState(0);
+  const { width, height } = useSize(asideEl);
+  const carouselOrientation = orientation
+    ? orientation
+    : height >= width
+      ? 'vertical'
+      : 'horizontal';
+
+  const tileSpan =
+    carouselOrientation === 'vertical'
+      ? Math.max(width * ASPECT_RATIO_INVERT, MIN_HEIGHT)
+      : Math.max(height * ASPECT_RATIO, MIN_WIDTH);
+  const scrollBarWidth = getScrollBarWidth();
+
+  const tilesThatFit =
+    carouselOrientation === 'vertical'
+      ? Math.max((height - scrollBarWidth) / tileSpan, MIN_VISIBLE_TILES)
+      : Math.max((width - scrollBarWidth) / tileSpan, MIN_VISIBLE_TILES);
+
+  let maxVisibleTiles = Math.round(tilesThatFit);
+  if (Math.abs(tilesThatFit - prevTiles) < 0.5) {
+    maxVisibleTiles = Math.round(prevTiles);
+  } else if (prevTiles !== tilesThatFit) {
+    setPrevTiles(tilesThatFit);
+  }
+
+  const sortedTiles = useVisualStableUpdate(tracks, maxVisibleTiles);
+
+  React.useLayoutEffect(() => {
+    if (asideEl.current) {
+      asideEl.current.dataset.lkOrientation = carouselOrientation;
+      asideEl.current.style.setProperty('--lk-max-visible-tiles', maxVisibleTiles.toString());
+    }
+  }, [maxVisibleTiles, carouselOrientation]);
+
+  return (
+    <aside key={carouselOrientation} className="lk-carousel" ref={asideEl} {...props}>
+      <TrackLoop tracks={sortedTiles}>{props.children}</TrackLoop>
+    </aside>
+  );
+}

package/src/components/layout/FocusLayout.tsx

@@ -0,0 +1,37 @@
+import * as React from 'react';
+import { mergeProps } from '../../utils';
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { ParticipantTile } from '../participant/ParticipantTile';
+import type { ParticipantClickEvent } from '@livekit/components-core';
+
+/** @public */
+export interface FocusLayoutContainerProps extends React.HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * The `FocusLayoutContainer` is a layout component that expects two children:
+ * A small side component: In a video conference, this is usually a carousel of participants
+ * who are not in focus. And a larger main component to display the focused participant.
+ * For example, with the `FocusLayout` component.
+ *  @public
+ */
+export function FocusLayoutContainer(props: FocusLayoutContainerProps) {
+  const elementProps = mergeProps(props, { className: 'lk-focus-layout' });
+
+  return <div {...elementProps}>{props.children}</div>;
+}
+
+/** @public */
+export interface FocusLayoutProps extends React.HTMLAttributes<HTMLElement> {
+  /** The track to display in the focus layout. */
+  trackRef?: TrackReferenceOrPlaceholder;
+
+  onParticipantClick?: (evt: ParticipantClickEvent) => void;
+}
+
+/**
+ * The `FocusLayout` component is just a light wrapper around the `ParticipantTile` to display a single participant.
+ * @public
+ */
+export function FocusLayout({ trackRef, ...htmlProps }: FocusLayoutProps) {
+  return <ParticipantTile trackRef={trackRef} {...htmlProps} />;
+}