@livekit/components-js-docs 0.0.5 → 0.1.0

package/generated-docs/react/component/prejoin.md

@@ -2,7 +2,7 @@
 
 # PreJoin
 
-The PreJoin prefab component is normally presented to the user before he enters a room. This component allows the user to check and select the preferred media device (camera und microphone). On submit the user decisions are returned, which can then be passed on to the LiveKitRoom so that the user enters the room with the correct media devices.
+The `PreJoin` prefab component is normally presented to the user before he enters a room. This component allows the user to check and select the preferred media device (camera und microphone). On submit the user decisions are returned, which can then be passed on to the `LiveKitRoom` so that the user enters the room with the correct media devices.
 
 ## Import
 
@@ -12,7 +12,7 @@ import { PreJoin } from '@livekit/components-react';
 
 ## Remarks
 
-This component is independent from the LiveKitRoom component and don't has to be nested inside it. Because it only access the local media tracks this component is self contained and works without connection to the LiveKit server.
+This component is independent from the `LiveKitRoom` component and don't has to be nested inside it. Because it only access the local media tracks this component is self contained and works without connection to the LiveKit server.
 
 ## Usage
 
@@ -64,6 +64,11 @@ _(Optional)_ Provide your custom validation function. Only if validation is succ
 
 {% /parameter %}
 
+{% parameter name="showE2EEOptions" type="boolean" optional=true %}
+_(Optional)_
+
+{% /parameter %}
+
 {% parameter name="userLabel" type="string" optional=true %}
 _(Optional)_
 

package/generated-docs/react/component/roomaudiorenderer.md

@@ -2,7 +2,7 @@
 
 # RoomAudioRenderer
 
-The RoomAudioRenderer component is a drop-in solution for adding audio to your LiveKit app. It takes care of handling remote participants’ audio tracks and makes sure that microphones and screen share are audible.
+The `RoomAudioRenderer` component is a drop-in solution for adding audio to your LiveKit app. It takes care of handling remote participants’ audio tracks and makes sure that microphones and screen share are audible.
 
 ## Import
 

package/generated-docs/react/component/roomname.md

@@ -2,7 +2,7 @@
 
 # RoomName
 
-The RoomName component renders the name of the connected LiveKit room inside a span tag.
+The `RoomName` component renders the name of the connected LiveKit room inside a span tag.
 
 ## Import
 

package/generated-docs/react/component/startaudio.md

@@ -2,7 +2,7 @@
 
 # StartAudio
 
-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.
+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.
 
 ## Import
 

package/generated-docs/react/component/toast.md

@@ -2,10 +2,18 @@
 
 # Toast
 
+The `Toast` component is a rudimentary way to display a message to the user. This message should be short lived and not require user interaction. For example, displaying the current connection state like `ConnectionStateToast` does.
+
 ## Import
 
 ```typescript
 import { Toast } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+<Toast>Connecting...</Toast>
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}

package/generated-docs/react/component/trackloop.md

@@ -2,7 +2,7 @@
 
 # TrackLoop
 
-The TrackLoop component loops over tracks. It is for example a easy way to loop over all participant camera and screen share tracks. TrackLoop creates a TrackContext for each track that you can use to e.g. render the track.
+The `TrackLoop` component loops over tracks. It is for example a easy way to loop over all participant camera and screen share tracks. `TrackLoop` creates a `TrackRefContext` for each track that you can use to e.g. render the track.
 
 ## Import
 
@@ -13,11 +13,11 @@ import { TrackLoop } from '@livekit/components-react';
 ## Usage
 
 ```tsx
-const tracks = useTracks([Track.Source.Camera]);
-<TrackLoop tracks={tracks} >
- <TrackContext.Consumer>
-   {(track) => track && <VideoTrack {...track}/>}
- </TrackContext.Consumer>
+const trackRefs = useTracks([Track.Source.Camera]);
+<TrackLoop tracks={trackRefs} >
+ <TrackRefContext.Consumer>
+   {(trackRef) => trackRef && <VideoTrack trackRef={trackRef}/>}
+ </TrackRefContext.Consumer>
 <TrackLoop />
 ```
 

package/generated-docs/react/component/trackmutedindicator.md

@@ -2,7 +2,7 @@
 
 # TrackMutedIndicator
 
-The TrackMutedIndicator shows whether the participant's camera or microphone is muted or not.
+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.
 
 ## Import
 
@@ -21,9 +21,6 @@ import { TrackMutedIndicator } from '@livekit/components-react';
 
 ## Properties
 
-{% parameter name="source" type="Track.Source" optional=false %}
-{% /parameter %}
-
 {% parameter name="participant" type="Participant" optional=true %}
 _(Optional)_
 
@@ -33,3 +30,13 @@ _(Optional)_
 _(Optional)_
 
 {% /parameter %}
+
+{% parameter name="source" type="Track.Source" optional=true %}
+_(Optional)_
+
+{% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_
+
+{% /parameter %}

package/generated-docs/react/component/tracktoggle.md

@@ -2,7 +2,7 @@
 
 # TrackToggle
 
-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.
+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.
 
 ## Import
 

package/generated-docs/react/component/videoconference.md

@@ -2,7 +2,7 @@
 
 # VideoConference
 
-This component is the default setup of a classic LiveKit video conferencing app. It provides functionality like switching between participant grid view and focus view.
+The `VideoConference` ready-made component is your drop-in solution for a classic video conferencing application. It provides functionality such as focusing on one participant, grid view with pagination to handle large numbers of participants, basic non-persistent chat, screen sharing, and more.
 
 ## Import
 
@@ -12,7 +12,7 @@ import { VideoConference } from '@livekit/components-react';
 
 ## Remarks
 
-The component is implemented with other LiveKit components like `FocusContextProvider`<!-- -->, `GridLayout`<!-- -->, `ControlBar`<!-- -->, `FocusLayoutContainer` and `FocusLayout`<!-- -->.
+The component is implemented with other LiveKit components like `FocusContextProvider`<!-- -->, `GridLayout`<!-- -->, `ControlBar`<!-- -->, `FocusLayoutContainer` and `FocusLayout`<!-- -->. You can use this components as a starting point for your own custom video conferencing application.
 
 ## Usage
 

package/generated-docs/react/component/videotrack.md

@@ -2,7 +2,7 @@
 
 # VideoTrack
 
-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.
+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.
 
 ## Import
 
@@ -13,16 +13,13 @@ import { VideoTrack } from '@livekit/components-react';
 ## Usage
 
 ```tsx
-<VideoTrack source={Track.Source.Camera} />
+<VideoTrack trackRef={trackRef} />
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Properties
 
-{% parameter name="source" type="Track.Source" optional=false %}
-{% /parameter %}
-
 {% parameter name="manageSubscription" type="boolean" optional=true %}
 _(Optional)_
 
@@ -52,3 +49,13 @@ _(Optional)_
 _(Optional)_
 
 {% /parameter %}
+
+{% parameter name="source" type="Track.Source" optional=true %}
+_(Optional)_
+
+{% /parameter %}
+
+{% parameter name="trackRef" type="TrackReference" optional=true %}
+_(Optional)_ The track reference of the track to render.
+
+{% /parameter %}

package/generated-docs/react/focuslayoutcontainerprops.focustrack.md

@@ -2,8 +2,14 @@
 
 ## FocusLayoutContainerProps.focusTrack property
 
+> Warning: This API is now obsolete.
+>
+> This property has no effect and will be removed in a future version.
+
 **Signature:**
 
 ```typescript
 focusTrack?: TrackReference;
 ```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/focuslayoutcontainerprops.participants.md

@@ -2,8 +2,14 @@
 
 ## FocusLayoutContainerProps.participants property
 
+> Warning: This API is now obsolete.
+>
+> This property has no effect and will be removed in a future version.
+
 **Signature:**
 
 ```typescript
 participants?: Array<Participant>;
 ```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/focuslayoutprops.md

@@ -14,7 +14,8 @@ export interface FocusLayoutProps extends React.HTMLAttributes<HTMLElement>
 
 ## Properties
 
-| Property                                                              | Type                                                                               | Description  |
-| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------ |
-| [onParticipantClick?](./react/focuslayoutprops.onparticipantclick.md) | (evt: [ParticipantClickEvent](./core/participantclickevent.md)<!-- -->) =&gt; void | _(Optional)_ |
-| [track?](./react/focuslayoutprops.track.md)                           | [TrackReferenceOrPlaceholder](./core/trackreferenceorplaceholder.md)               | _(Optional)_ |
+| Property                                                              | Type                                                                               | Description                                            |
+| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| [onParticipantClick?](./react/focuslayoutprops.onparticipantclick.md) | (evt: [ParticipantClickEvent](./core/participantclickevent.md)<!-- -->) =&gt; void | _(Optional)_                                           |
+| [track?](./react/focuslayoutprops.track.md)                           | [TrackReferenceOrPlaceholder](./core/trackreferenceorplaceholder.md)               | _(Optional)_                                           |
+| [trackRef?](./react/focuslayoutprops.trackref.md)                     | [TrackReferenceOrPlaceholder](./core/trackreferenceorplaceholder.md)               | _(Optional)_ The track to display in the focus layout. |

package/generated-docs/react/focuslayoutprops.track.md

@@ -2,8 +2,14 @@
 
 ## FocusLayoutProps.track property
 
+> Warning: This API is now obsolete.
+>
+> This property will be removed in a future version use `trackRef` instead.
+
 **Signature:**
 
 ```typescript
 track?: TrackReferenceOrPlaceholder;
 ```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/focuslayoutprops.trackref.md

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+## FocusLayoutProps.trackRef property
+
+The track to display in the focus layout.
+
+**Signature:**
+
+```typescript
+trackRef?: TrackReferenceOrPlaceholder;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/focustoggleprops.md

@@ -14,7 +14,8 @@ export interface FocusToggleProps extends React.ButtonHTMLAttributes<HTMLButtonE
 
 ## Properties
 
-| Property                                                | Type         | Description  |
-| ------------------------------------------------------- | ------------ | ------------ |
-| [participant?](./react/focustoggleprops.participant.md) | Participant  | _(Optional)_ |
-| [trackSource](./react/focustoggleprops.tracksource.md)  | Track.Source |              |
+| Property                                                | Type                                                                 | Description  |
+| ------------------------------------------------------- | -------------------------------------------------------------------- | ------------ |
+| [participant?](./react/focustoggleprops.participant.md) | Participant                                                          | _(Optional)_ |
+| [trackRef?](./react/focustoggleprops.trackref.md)       | [TrackReferenceOrPlaceholder](./core/trackreferenceorplaceholder.md) | _(Optional)_ |
+| [trackSource?](./react/focustoggleprops.tracksource.md) | Track.Source                                                         | _(Optional)_ |

package/generated-docs/react/focustoggleprops.participant.md

@@ -2,8 +2,14 @@
 
 ## FocusToggleProps.participant property
 
+> Warning: This API is now obsolete.
+>
+> This parameter will be removed in a future version use `trackRef` instead.
+
 **Signature:**
 
 ```typescript
 participant?: Participant;
 ```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/focustoggleprops.trackref.md

@@ -0,0 +1,9 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+## FocusToggleProps.trackRef property
+
+**Signature:**
+
+```typescript
+trackRef?: TrackReferenceOrPlaceholder;
+```

package/generated-docs/react/focustoggleprops.tracksource.md

@@ -2,8 +2,14 @@
 
 ## FocusToggleProps.trackSource property
 
+> Warning: This API is now obsolete.
+>
+> This parameter will be removed in a future version use `trackRef` instead.
+
 **Signature:**
 
 ```typescript
-trackSource: Track.Source;
+trackSource?: Track.Source;
 ```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/hook/usechat.md

@@ -2,12 +2,18 @@
 
 # useChat
 
+The `useChat` hook provides chat functionality for a LiveKit room. It returns a simple `send` function to send chat messages and an array of `chatMessages` to hold received messages.
+
 ## Import
 
 ```typescript
 import { useChat } from '@livekit/components-react';
 ```
 
+## Remarks
+
+It is possible to pass configurations for custom message encoding and decoding.
+
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
 ## Parameters
@@ -23,7 +29,7 @@ import { useChat } from '@livekit/components-react';
 ```typescript
 {
     send: ((message: string) => Promise<void>) | undefined;
-    chatMessages: ReceivedChatMessage[];
+    chatMessages: import("@livekit/components-core").ReceivedChatMessage[];
     isSending: boolean;
 }
 ```

package/generated-docs/react/hook/usechattoggle.md

@@ -2,12 +2,18 @@
 
 # useChatToggle
 
+The `useChatToggle` hook provides state and functions for toggling the chat window.
+
 ## Import
 
 ```typescript
 import { useChatToggle } from '@livekit/components-react';
 ```
 
+## Remarks
+
+Depends on the `LayoutContext` to work properly.
+
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
 ## Parameters

package/generated-docs/react/hook/useclearpinbutton.md

@@ -2,6 +2,8 @@
 
 # useClearPinButton
 
+The `useClearPinButton` hook provides props for the [ClearPinButton()](./react/component/clearpinbutton.md) or your custom implementation of it component. It adds the `onClick` handler to signal the `LayoutContext` that the tile in focus should be cleared.
+
 ## Import
 
 ```typescript

package/generated-docs/react/hook/useconnectionqualityindicator.md

@@ -2,13 +2,23 @@
 
 # useConnectionQualityIndicator
 
+The `useConnectionQualityIndicator` hook provides props for the `ConnectionQualityIndicator` or your custom implementation of it component.
+
 ## Import
 
 ```typescript
 import { useConnectionQualityIndicator } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { quality } = useConnectionQualityIndicator();
+// or
+const { quality } = useConnectionQualityIndicator({ participant });
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 
@@ -19,64 +29,7 @@ import { useConnectionQualityIndicator } from '@livekit/components-react';
 
 ```typescript
 {
-  className: 'lk-rotate' |
-    'lk-audio-conference' |
-    'lk-audio-conference-stage' |
-    'lk-audio-container' |
-    'lk-button' |
-    'lk-button-group' |
-    'lk-button-group-container' |
-    'lk-camera-off-note' |
-    'lk-chat' |
-    'lk-chat-entry' |
-    'lk-chat-form' |
-    'lk-chat-form-input' |
-    'lk-chat-messages' |
-    'lk-control-bar' |
-    'lk-focus-layout-wrapper' |
-    'lk-form-control' |
-    'lk-grid-layout-wrapper' |
-    'lk-join-button' |
-    'lk-list' |
-    'lk-message-body' |
-    'lk-meta-data' |
-    'lk-participant-name' |
-    'lk-prejoin' |
-    'lk-timestamp' |
-    'lk-username-container' |
-    'lk-video-conference' |
-    'lk-video-conference-inner' |
-    'lk-video-container' |
-    'lk-audio-visualizer' |
-    'lk-button-group-menu' |
-    'lk-button-menu' |
-    'lk-carousel' |
-    'lk-chat-toggle' |
-    'lk-connection-quality' |
-    'lk-device-menu' |
-    'lk-device-menu-heading' |
-    'lk-disconnect-button' |
-    'lk-focus-layout' |
-    'lk-focus-toggle-button' |
-    'lk-focused-participant' |
-    'lk-grid-layout' |
-    'lk-media-device-select' |
-    'lk-pagination-control' |
-    'lk-pagination-count' |
-    'lk-pagination-indicator' |
-    'lk-participant-media-audio' |
-    'lk-participant-media-video' |
-    'lk-participant-metadata' |
-    'lk-participant-metadata-item' |
-    'lk-participant-placeholder' |
-    'lk-participant-tile' |
-    'lk-pip-track' |
-    'lk-room-container' |
-    'lk-spinner' |
-    'lk-start-audio-button' |
-    'lk-toast' |
-    'lk-track-muted-indicator-camera' |
-    'lk-track-muted-indicator-microphone';
+  className: 'lk-connection-quality';
   quality: ConnectionQuality;
 }
 ```

package/generated-docs/react/hook/usedatachannel.md

@@ -2,13 +2,26 @@
 
 # useDataChannel
 
+The `useDataChannel` hook returns the ability to send and receive messages. By optionally passing a `topic`<!-- -->, you can narrow down which messages are returned in the messages array.
+
 ## Import
 
 ```typescript
 import { useDataChannel } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## 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`<!-- -->.
+
+## Usage
+
+```tsx
+// Send messages to all participants via the 'chat' topic.
+const { message, send } = useDataChannel('chat');
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

package/generated-docs/react/hook/usedatachannel_1.md

@@ -2,13 +2,26 @@
 
 # useDataChannel
 
+The `useDataChannel` hook returns the ability to send and receive messages.
+
 ## Import
 
 ```typescript
 import { useDataChannel } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## 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`<!-- -->.
+
+## Usage
+
+```tsx
+// Send messages to all participants
+const { message, send } = useDataChannel(callback);
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

package/generated-docs/react/hook/usedisconnectbutton.md

@@ -2,13 +2,22 @@
 
 # useDisconnectButton
 
+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.
+
 ## Import
 
 ```typescript
 import { useDisconnectButton } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { buttonProps } = useDisconnectButton();
+return <button {...buttonProps}>Disconnect</button>;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

package/generated-docs/react/hook/useensuretrackref.md

@@ -0,0 +1,24 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useEnsureTrackRef
+
+Ensures that a track reference is provided, either via context or explicitly as a parameter. If not inside a `TrackRefContext` and no track reference is provided, an error is thrown.
+
+## Import
+
+```typescript
+import { useEnsureTrackRef } from '@livekit/components-react';
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Parameters
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+TrackReferenceOrPlaceholder;
+```

package/generated-docs/react/hook/useensuretrackreference.md

@@ -2,6 +2,10 @@
 
 # useEnsureTrackReference
 
+> Warning: This API is now obsolete.
+>
+> `useEnsureTrackReference` has been to `useEnsureTrackRef`<!-- -->, use this as a drop in replacement.
+
 Ensures that a track reference is provided, either via context or explicitly as a parameter. If not inside a `TrackContext` and no track reference is provided, an error is thrown.
 
 ## Import

package/generated-docs/react/hook/usefocustoggle.md

@@ -2,17 +2,26 @@
 
 # useFocusToggle
 
+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.
+
 ## Import
 
 ```typescript
 import { useFocusToggle } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { mergedProps, inFocus } = useFocusToggle({ trackRef, props: yourButtonProps });
+return <button {...mergedProps}>{inFocus ? 'Unfocus' : 'Focus'}</button>;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 
-{% parameter name="{ trackSource, participant, props }" type="UseFocusToggleProps" optional=false %}
+{% parameter name="{ trackRef, trackSource, participant, props }" type="UseFocusToggleProps" optional=false %}
 {% /parameter %}
 
 ## Returns