@werxt/livekit-components-react 2.9.20

package/src/components/layout/GridLayout.tsx

@@ -0,0 +1,63 @@
+import * as React from 'react';
+import type { UseParticipantsOptions } from '../../hooks';
+import { useGridLayout, usePagination, useSwipe } from '../../hooks';
+import { mergeProps } from '../../utils';
+import type { TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { TrackLoop } from '../TrackLoop';
+import { PaginationControl } from '../controls/PaginationControl';
+import { PaginationIndicator } from '../controls/PaginationIndicator';
+
+/** @public */
+export interface GridLayoutProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    Pick<UseParticipantsOptions, 'updateOnlyOn'> {
+  children: React.ReactNode;
+  tracks: TrackReferenceOrPlaceholder[];
+}
+
+/**
+ * The `GridLayout` component displays the nested participants in a grid where every participants has the same size.
+ * It also supports pagination if there are more participants than the grid can display.
+ * @remarks
+ * To ensure visual stability when tiles are reordered due to track updates,
+ * the component uses the `useVisualStableUpdate` hook.
+ * @example
+ * ```tsx
+ * <LiveKitRoom>
+ *   <GridLayout tracks={tracks}>
+ *     <ParticipantTile />
+ *   </GridLayout>
+ * <LiveKitRoom>
+ * ```
+ * @public
+ */
+export function GridLayout({ tracks, ...props }: GridLayoutProps) {
+  const gridEl = React.createRef<HTMLDivElement>();
+
+  const elementProps = React.useMemo(
+    () => mergeProps(props, { className: 'lk-grid-layout' }),
+    [props],
+  );
+  const { layout } = useGridLayout(gridEl, tracks.length);
+  const pagination = usePagination(layout.maxTiles, tracks);
+
+  useSwipe(gridEl, {
+    onLeftSwipe: pagination.nextPage,
+    onRightSwipe: pagination.prevPage,
+  });
+
+  return (
+    <div ref={gridEl} data-lk-pagination={pagination.totalPageCount > 1} {...elementProps}>
+      <TrackLoop tracks={pagination.tracks}>{props.children}</TrackLoop>
+      {tracks.length > layout.maxTiles && (
+        <>
+          <PaginationIndicator
+            totalPageCount={pagination.totalPageCount}
+            currentPage={pagination.currentPage}
+          />
+          <PaginationControl pagesContainer={gridEl} {...pagination} />
+        </>
+      )}
+    </div>
+  );
+}

package/src/components/layout/LayoutContextProvider.tsx

@@ -0,0 +1,36 @@
+import type { PinState, WidgetState } from '@livekit/components-core';
+import { log } from '@livekit/components-core';
+import * as React from 'react';
+import type { LayoutContextType } from '../../context';
+import { LayoutContext, useEnsureCreateLayoutContext } from '../../context';
+
+/** @alpha */
+export interface LayoutContextProviderProps {
+  value?: LayoutContextType;
+  onPinChange?: (state: PinState) => void;
+  onWidgetChange?: (state: WidgetState) => void;
+}
+
+/** @alpha */
+export function LayoutContextProvider({
+  value,
+  onPinChange,
+  onWidgetChange,
+  children,
+}: React.PropsWithChildren<LayoutContextProviderProps>) {
+  const layoutContextValue = useEnsureCreateLayoutContext(value);
+
+  React.useEffect(() => {
+    log.debug('PinState Updated', { state: layoutContextValue.pin.state });
+    if (onPinChange && layoutContextValue.pin.state) onPinChange(layoutContextValue.pin.state);
+  }, [layoutContextValue.pin.state, onPinChange]);
+
+  React.useEffect(() => {
+    log.debug('Widget Updated', { widgetState: layoutContextValue.widget.state });
+    if (onWidgetChange && layoutContextValue.widget.state) {
+      onWidgetChange(layoutContextValue.widget.state);
+    }
+  }, [onWidgetChange, layoutContextValue.widget.state]);
+
+  return <LayoutContext.Provider value={layoutContextValue}>{children}</LayoutContext.Provider>;
+}

package/src/components/layout/index.ts

@@ -0,0 +1,3 @@
+export * from './FocusLayout';
+export * from './GridLayout';
+export { CarouselLayout, type CarouselLayoutProps } from './CarouselLayout';

package/src/components/participant/AudioTrack.tsx

@@ -0,0 +1,89 @@
+import * as React from 'react';
+import { useMediaTrackBySourceOrName } from '../../hooks/useMediaTrackBySourceOrName';
+import type { TrackReference } from '@livekit/components-core';
+import { log } from '@livekit/components-core';
+import { RemoteAudioTrack, RemoteTrackPublication } from 'livekit-client';
+import { useEnsureTrackRef } from '../../context';
+
+/** @public */
+export interface AudioTrackProps extends React.AudioHTMLAttributes<HTMLAudioElement> {
+  /** The track reference of the track from which the audio is to be rendered. */
+  trackRef?: TrackReference;
+
+  onSubscriptionStatusChanged?: (subscribed: boolean) => void;
+  /** Sets the volume of the audio track. By default, the range is between `0.0` and `1.0`. */
+  volume?: number;
+  /**
+   * Mutes the audio track if set to `true`.
+   * @remarks
+   * If set to `true`, the server will stop sending audio track data to the client.
+   * @alpha
+   */
+  muted?: boolean;
+}
+
+/**
+ * The AudioTrack component is responsible for rendering participant audio tracks.
+ * This component must have access to the participant's context, or alternatively pass it a `Participant` as a property.
+ *
+ * @example
+ * ```tsx
+ *   <ParticipantTile>
+ *     <AudioTrack trackRef={trackRef} />
+ *   </ParticipantTile>
+ * ```
+ *
+ * @see `ParticipantTile` component
+ * @public
+ */
+export const AudioTrack: (
+  props: AudioTrackProps & React.RefAttributes<HTMLAudioElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLAudioElement, AudioTrackProps>(
+  function AudioTrack(
+    { trackRef, onSubscriptionStatusChanged, volume, ...props }: AudioTrackProps,
+    ref,
+  ) {
+    const trackReference = useEnsureTrackRef(trackRef);
+
+    const mediaEl = React.useRef<HTMLAudioElement>(null);
+    React.useImperativeHandle(ref, () => mediaEl.current as HTMLAudioElement);
+
+    const {
+      elementProps,
+      isSubscribed,
+      track,
+      publication: pub,
+    } = useMediaTrackBySourceOrName(trackReference, {
+      element: mediaEl,
+      props,
+    });
+
+    React.useEffect(() => {
+      onSubscriptionStatusChanged?.(!!isSubscribed);
+    }, [isSubscribed, onSubscriptionStatusChanged]);
+
+    React.useEffect(() => {
+      if (track === undefined || volume === undefined) {
+        return;
+      }
+      if (track instanceof RemoteAudioTrack) {
+        track.setVolume(volume);
+      } else {
+        log.warn('Volume can only be set on remote audio tracks.');
+      }
+    }, [volume, track]);
+
+    React.useEffect(() => {
+      if (pub === undefined || props.muted === undefined) {
+        return;
+      }
+      if (pub instanceof RemoteTrackPublication) {
+        pub.setEnabled(!props.muted);
+      } else {
+        log.warn('Can only call setEnabled on remote track publications.');
+      }
+    }, [props.muted, pub, track]);
+
+    return <audio ref={mediaEl} {...elementProps} />;
+  },
+);

package/src/components/participant/AudioVisualizer.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+import { type TrackReference } from '@livekit/components-core';
+import { useEnsureTrackRef } from '../../context';
+import { useMultibandTrackVolume } from '../../hooks';
+
+/**
+ * @public
+ * @deprecated Use BarVisualizer instead
+ */
+export interface AudioVisualizerProps extends React.HTMLAttributes<SVGElement> {
+  trackRef?: TrackReference;
+}
+
+/**
+ * The AudioVisualizer component is used to visualize the audio volume of a given audio track.
+ * @remarks
+ * Requires a `TrackReferenceOrPlaceholder` to be provided either as a property or via the `TrackRefContext`.
+ * @example
+ * ```tsx
+ * <AudioVisualizer />
+ * ```
+ * @public
+ * @deprecated Use BarVisualizer instead
+ */
+export const AudioVisualizer: (
+  props: AudioVisualizerProps & React.RefAttributes<SVGSVGElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<SVGSVGElement, AudioVisualizerProps>(
+  function AudioVisualizer({ trackRef, ...props }: AudioVisualizerProps, ref) {
+    const svgWidth = 200;
+    const svgHeight = 90;
+    const barWidth = 6;
+    const barSpacing = 4;
+    const volMultiplier = 50;
+    const barCount = 7;
+    const trackReference = useEnsureTrackRef(trackRef);
+
+    const volumes = useMultibandTrackVolume(trackReference, { bands: 7, loPass: 300 });
+
+    return (
+      <svg
+        ref={ref}
+        width="100%"
+        height="100%"
+        viewBox={`0 0 ${svgWidth} ${svgHeight}`}
+        {...props}
+        className="lk-audio-visualizer"
+      >
+        <rect x="0" y="0" width="100%" height="100%" />
+        <g
+          style={{
+            transform: `translate(${(svgWidth - barCount * (barWidth + barSpacing)) / 2}px, 0)`,
+          }}
+        >
+          {volumes.map((vol, idx) => (
+            <rect
+              key={idx}
+              x={idx * (barWidth + barSpacing)}
+              y={svgHeight / 2 - (vol * volMultiplier) / 2}
+              width={barWidth}
+              height={vol * volMultiplier}
+            ></rect>
+          ))}
+        </g>
+      </svg>
+    );
+  },
+);

package/src/components/participant/BarVisualizer.tsx

@@ -0,0 +1,164 @@
+import * as React from 'react';
+import { useBarAnimator } from './animators/useBarAnimator';
+import { useMultibandTrackVolume, type AgentState } from '../../hooks';
+import { type TrackReferenceOrPlaceholder } from '@livekit/components-core';
+import { useMaybeTrackRefContext } from '../../context';
+import { cloneSingleChild, mergeProps } from '../../utils';
+import { LocalAudioTrack, RemoteAudioTrack } from 'livekit-client';
+
+/**
+ * @beta
+ */
+export type BarVisualizerOptions = {
+  /** in percentage */
+  maxHeight?: number;
+  /** in percentage */
+  minHeight?: number;
+};
+
+/**
+ * @beta
+ */
+export interface BarVisualizerProps extends React.HTMLProps<HTMLDivElement> {
+  /** If set, the visualizer will transition between different voice assistant states */
+  state?: AgentState;
+  /** Number of bars that show up in the visualizer */
+  barCount?: number;
+  /** @deprecated use `track` field instead */
+  trackRef?: TrackReferenceOrPlaceholder;
+  track?: TrackReferenceOrPlaceholder | LocalAudioTrack | RemoteAudioTrack;
+  options?: BarVisualizerOptions;
+  /** The template component to be used in the visualizer. */
+  children?: React.ReactNode;
+}
+
+const sequencerIntervals = new Map<AgentState, number>([
+  ['connecting', 2000],
+  ['initializing', 2000],
+  ['listening', 500],
+  ['thinking', 150],
+]);
+
+const getSequencerInterval = (
+  state: AgentState | undefined,
+  barCount: number,
+): number | undefined => {
+  if (state === undefined) {
+    return 1000;
+  }
+  let interval = sequencerIntervals.get(state);
+  if (interval) {
+    switch (state) {
+      case 'connecting':
+        // case 'thinking':
+        interval /= barCount;
+        break;
+
+      default:
+        break;
+    }
+  }
+  return interval;
+};
+/**
+ * Visualizes audio signals from a TrackReference as bars.
+ * If the `state` prop is set, it automatically transitions between VoiceAssistant states.
+ * @beta
+ *
+ * @remarks For VoiceAssistant state transitions this component requires a voice assistant agent running with livekit-agents \>= 0.9.0
+ *
+ * @example
+ * ```tsx
+ * function SimpleVoiceAssistant() {
+ *   const { state, audioTrack } = useVoiceAssistant();
+ *   return (
+ *    <BarVisualizer
+ *      state={state}
+ *      trackRef={audioTrack}
+ *    />
+ *   );
+ * }
+ * ```
+ *
+ * @example
+ *  Styling the BarVisualizer using CSS classes
+ * ```css
+ * .lk-audio-bar {
+ *  // Styles for "idle" bars
+ *  }
+ * .lk-audio-bar.lk-highlighted {
+ *  // Styles for "active" bars
+ * }
+ * ```
+ *
+ * @example
+ * Styling the BarVisualizer using CSS custom properties
+ * ```css
+ * --lk-fg // for the "active" colour, note that this defines the main foreground colour for the whole "theme"
+ * --lk-va-bg // for "idle" colour
+ * ```
+ *
+ * @example
+ * Using a custom bar template for the BarVisualizer
+ * ```tsx
+ * <BarVisualizer>
+ *   <div className="all the classes" />
+ * </BarVisualizer>
+ * ```
+ * the highlighted children will get a data prop of data-lk-highlighted for them to switch between active and idle bars in their own template bar
+ */
+export const BarVisualizer = /* @__PURE__ */ React.forwardRef<HTMLDivElement, BarVisualizerProps>(
+  function BarVisualizer(
+    { state, options, barCount = 15, trackRef, track, children, ...props }: BarVisualizerProps,
+    ref,
+  ) {
+    const elementProps = mergeProps(props, { className: 'lk-audio-bar-visualizer' });
+    let targetTrack: TrackReferenceOrPlaceholder | LocalAudioTrack | RemoteAudioTrack | undefined =
+      useMaybeTrackRefContext();
+
+    if (trackRef || track) {
+      targetTrack = trackRef || track;
+    }
+
+    const volumeBands = useMultibandTrackVolume(targetTrack, {
+      bands: barCount,
+      loPass: 100,
+      hiPass: 200,
+    });
+    const minHeight = options?.minHeight ?? 20;
+    const maxHeight = options?.maxHeight ?? 100;
+
+    const highlightedIndices = useBarAnimator(
+      state,
+      barCount,
+      getSequencerInterval(state, barCount) ?? 100,
+    );
+
+    return (
+      <div ref={ref} {...elementProps} data-lk-va-state={state}>
+        {volumeBands.map((volume, idx) =>
+          children ? (
+            cloneSingleChild(children, {
+              'data-lk-highlighted': highlightedIndices.includes(idx),
+              'data-lk-bar-index': idx,
+              className: 'lk-audio-bar',
+              style: { height: `${Math.min(maxHeight, Math.max(minHeight, volume * 100 + 5))}%` },
+            })
+          ) : (
+            <span
+              key={idx}
+              data-lk-highlighted={highlightedIndices.includes(idx)}
+              data-lk-bar-index={idx}
+              className={`lk-audio-bar ${highlightedIndices.includes(idx) && 'lk-highlighted'}`}
+              style={{
+                // TODO transform animations would be more performant, however the border-radius gets distorted when using scale transforms. a 9-slice approach (or 3 in this case) could work
+                // transform: `scale(1, ${Math.min(maxHeight, Math.max(minHeight, volume))}`,
+                height: `${Math.min(maxHeight, Math.max(minHeight, volume * 100 + 5))}%`,
+              }}
+            ></span>
+          ),
+        )}
+      </div>
+    );
+  },
+);

package/src/components/participant/ConnectionQualityIndicator.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { mergeProps } from '../../utils';
+import { getConnectionQualityIcon } from '../../assets/icons/util';
+import type { ConnectionQualityIndicatorOptions } from '../../hooks';
+import { useConnectionQualityIndicator } from '../../hooks';
+
+/** @public */
+export interface ConnectionQualityIndicatorProps
+  extends React.HTMLAttributes<HTMLDivElement>,
+    ConnectionQualityIndicatorOptions {}
+
+/**
+ * The `ConnectionQualityIndicator` shows the individual connection quality of a participant.
+ *
+ * @example
+ * ```tsx
+ * <ConnectionQualityIndicator />
+ * ```
+ * @public
+ */
+export const ConnectionQualityIndicator: (
+  props: ConnectionQualityIndicatorProps & React.RefAttributes<HTMLDivElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<
+  HTMLDivElement,
+  ConnectionQualityIndicatorProps
+>(function ConnectionQualityIndicator(props: ConnectionQualityIndicatorProps, ref) {
+  const { className, quality } = useConnectionQualityIndicator(props);
+  const elementProps = React.useMemo(() => {
+    return { ...mergeProps(props, { className: className as string }), 'data-lk-quality': quality };
+  }, [quality, props, className]);
+  return (
+    <div ref={ref} {...elementProps}>
+      {props.children ?? getConnectionQualityIcon(quality)}
+    </div>
+  );
+});

package/src/components/participant/ParticipantAudioTile.tsx

@@ -0,0 +1,67 @@
+import * as React from 'react';
+
+import { ConnectionQualityIndicator } from './ConnectionQualityIndicator';
+import { ParticipantName } from './ParticipantName';
+import { TrackMutedIndicator } from './TrackMutedIndicator';
+import { TrackRefContext, useEnsureTrackRef } from '../../context';
+
+import type { ParticipantTileProps } from './ParticipantTile';
+import { AudioTrack } from './AudioTrack';
+import { useParticipantTile } from '../../hooks';
+import { isTrackReference } from '@livekit/components-core';
+import { BarVisualizer } from './BarVisualizer';
+
+/**
+ * The `ParticipantAudioTile` component is the base utility wrapper for displaying a visual representation of a participant.
+ * This component can be used as a child of the `TileLoop` or independently if a participant is passed as a property.
+ *
+ * @example
+ * ```tsx
+ * <ParticipantAudioTile />
+ * ```
+ * @public
+ */
+export const ParticipantAudioTile: (
+  props: ParticipantTileProps & React.RefAttributes<HTMLDivElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLDivElement, ParticipantTileProps>(
+  function ParticipantAudioTile(
+    {
+      children,
+      disableSpeakingIndicator,
+      onParticipantClick,
+      trackRef,
+      ...htmlProps
+    }: ParticipantTileProps,
+    ref,
+  ) {
+    const trackReference = useEnsureTrackRef(trackRef);
+    const { elementProps } = useParticipantTile({
+      trackRef: trackReference,
+      htmlProps,
+      disableSpeakingIndicator,
+      onParticipantClick,
+    });
+
+    return (
+      <div ref={ref} style={{ position: 'relative', minHeight: '160px' }} {...elementProps}>
+        <TrackRefContext.Provider value={trackReference}>
+          {children ?? (
+            <>
+              {isTrackReference(trackReference) && (
+                <AudioTrack trackRef={trackReference}></AudioTrack>
+              )}
+              <BarVisualizer barCount={7} options={{ minHeight: 8 }} />
+              <div className="lk-participant-metadata">
+                <div className="lk-participant-metadata-item">
+                  <TrackMutedIndicator trackRef={trackReference}></TrackMutedIndicator>
+                  <ParticipantName />
+                </div>
+                <ConnectionQualityIndicator className="lk-participant-metadata-item" />
+              </div>
+            </>
+          )}
+        </TrackRefContext.Provider>
+      </div>
+    );
+  },
+);

package/src/components/participant/ParticipantName.tsx

@@ -0,0 +1,50 @@
+import { setupParticipantName } from '@livekit/components-core';
+import * as React from 'react';
+import { useEnsureParticipant } from '../../context';
+import { useObservableState } from '../../hooks/internal/useObservableState';
+import { mergeProps } from '../../utils';
+import type { UseParticipantInfoOptions } from '../../hooks';
+
+/** @public */
+export interface ParticipantNameProps
+  extends React.HTMLAttributes<HTMLSpanElement>,
+    UseParticipantInfoOptions {}
+
+/**
+ * The `ParticipantName` component displays the name of the participant as a string within an HTML span element.
+ * If no participant name is undefined the participant identity string is displayed.
+ *
+ * @example
+ * ```tsx
+ * <ParticipantName />
+ * ```
+ * @public
+ */
+export const ParticipantName: (
+  props: ParticipantNameProps & React.RefAttributes<HTMLSpanElement>,
+) => React.ReactNode = /* @__PURE__ */ React.forwardRef<HTMLSpanElement, ParticipantNameProps>(
+  function ParticipantName({ participant, ...props }: ParticipantNameProps, ref) {
+    const p = useEnsureParticipant(participant);
+
+    const { className, infoObserver } = React.useMemo(() => {
+      return setupParticipantName(p);
+    }, [p]);
+
+    const { identity, name } = useObservableState(infoObserver, {
+      name: p.name,
+      identity: p.identity,
+      metadata: p.metadata,
+    });
+
+    const mergedProps = React.useMemo(() => {
+      return mergeProps(props, { className, 'data-lk-participant-name': name });
+    }, [props, className, name]);
+
+    return (
+      <span ref={ref} {...mergedProps}>
+        {name !== '' ? name : identity}
+        {props.children}
+      </span>
+    );
+  },
+);