@livekit/components-js-docs 0.0.4 → 0.1.0

package/generated-docs/core/trackreferenceid.md

@@ -0,0 +1,9 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+## TrackReferenceId type
+
+**Signature:**
+
+```typescript
+export type TrackReferenceId = ReturnType<typeof getTrackReferenceId>;
+```

package/generated-docs/react/audiotrackprops.md

@@ -14,11 +14,12 @@ export interface AudioTrackProps<T extends HTMLMediaElement = HTMLMediaElement>
 
 ## Properties
 
-| Property                                                                               | Type                             | Description                                              |
-| -------------------------------------------------------------------------------------- | -------------------------------- | -------------------------------------------------------- |
-| [name?](./react/audiotrackprops.name.md)                                               | string                           | _(Optional)_                                             |
-| [onSubscriptionStatusChanged?](./react/audiotrackprops.onsubscriptionstatuschanged.md) | (subscribed: boolean) =&gt; void | _(Optional)_                                             |
-| [participant?](./react/audiotrackprops.participant.md)                                 | Participant                      | _(Optional)_                                             |
-| [publication?](./react/audiotrackprops.publication.md)                                 | TrackPublication                 | _(Optional)_                                             |
-| [source](./react/audiotrackprops.source.md)                                            | Track.Source                     |                                                          |
-| [volume?](./react/audiotrackprops.volume.md)                                           | number                           | _(Optional)_ by the default the range is between 0 and 1 |
+| Property                                                                               | Type                                       | Description                                                                           |
+| -------------------------------------------------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------- |
+| [name?](./react/audiotrackprops.name.md)                                               | string                                     | _(Optional)_                                                                          |
+| [onSubscriptionStatusChanged?](./react/audiotrackprops.onsubscriptionstatuschanged.md) | (subscribed: boolean) =&gt; void           | _(Optional)_                                                                          |
+| [participant?](./react/audiotrackprops.participant.md)                                 | Participant                                | _(Optional)_                                                                          |
+| [publication?](./react/audiotrackprops.publication.md)                                 | TrackPublication                           | _(Optional)_                                                                          |
+| [source?](./react/audiotrackprops.source.md)                                           | Track.Source                               | _(Optional)_                                                                          |
+| [trackRef?](./react/audiotrackprops.trackref.md)                                       | [TrackReference](./core/trackreference.md) | _(Optional)_ The track reference of the track from which the audio is to be rendered. |
+| [volume?](./react/audiotrackprops.volume.md)                                           | number                                     | _(Optional)_ by the default the range is between 0 and 1                              |

package/generated-docs/react/audiotrackprops.name.md

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

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

@@ -2,8 +2,14 @@
 
 ## AudioTrackProps.participant property
 
+> Warning: This API is now obsolete.
+>
+> This property 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/audiotrackprops.publication.md

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

package/generated-docs/react/audiotrackprops.source.md

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

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

@@ -0,0 +1,13 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+## AudioTrackProps.trackRef property
+
+The track reference of the track from which the audio is to be rendered.
+
+**Signature:**
+
+```typescript
+trackRef?: TrackReference;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/audiovisualizerprops.md

@@ -14,6 +14,7 @@ export interface AudioVisualizerProps extends React.HTMLAttributes<SVGElement>
 
 ## Properties
 
-| Property                                                    | Type        | Description  |
-| ----------------------------------------------------------- | ----------- | ------------ |
-| [participant?](./react/audiovisualizerprops.participant.md) | Participant | _(Optional)_ |
+| Property                                                    | Type                                                                 | Description  |
+| ----------------------------------------------------------- | -------------------------------------------------------------------- | ------------ |
+| [participant?](./react/audiovisualizerprops.participant.md) | Participant                                                          | _(Optional)_ |
+| [trackRef?](./react/audiovisualizerprops.trackref.md)       | [TrackReferenceOrPlaceholder](./core/trackreferenceorplaceholder.md) | _(Optional)_ |

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

@@ -2,8 +2,14 @@
 
 ## AudioVisualizerProps.participant property
 
+> Warning: This API is now obsolete.
+>
+> this property 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/audiovisualizerprops.trackref.md

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

package/generated-docs/react/{carouselviewprops.children.md → carousellayoutprops.children.md}

@@ -1,6 +1,6 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-## CarouselViewProps.children property
+## CarouselLayoutProps.children property
 
 **Signature:**
 

package/generated-docs/react/carousellayoutprops.md

@@ -0,0 +1,21 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+## CarouselLayoutProps interface
+
+**Signature:**
+
+```typescript
+export interface CarouselLayoutProps extends React.HTMLAttributes<HTMLMediaElement>
+```
+
+**Extends:** React.HTMLAttributes&lt;HTMLMediaElement&gt;
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Properties
+
+| Property                                                   | Type                                                                             | Description                                                                                                                                         |
+| ---------------------------------------------------------- | -------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| [children](./react/carousellayoutprops.children.md)        | React.ReactNode                                                                  |                                                                                                                                                     |
+| [orientation?](./react/carousellayoutprops.orientation.md) | 'vertical' \| 'horizontal'                                                       | _(Optional)_ Place the tiles vertically or horizontally next to each other. If undefined orientation is guessed by the dimensions of the container. |
+| [tracks](./react/carousellayoutprops.tracks.md)            | [TrackReferenceOrPlaceholder](./core/trackreferenceorplaceholder.md)<!-- -->\[\] |                                                                                                                                                     |

package/generated-docs/react/{carouselviewprops.orientation.md → carousellayoutprops.orientation.md}

@@ -1,6 +1,6 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-## CarouselViewProps.orientation property
+## CarouselLayoutProps.orientation property
 
 Place the tiles vertically or horizontally next to each other. If undefined orientation is guessed by the dimensions of the container.
 

package/generated-docs/react/{carouselviewprops.tracks.md → carousellayoutprops.tracks.md}

@@ -1,6 +1,6 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-## CarouselViewProps.tracks property
+## CarouselLayoutProps.tracks property
 
 **Signature:**
 

package/generated-docs/react/carouselview.md

@@ -0,0 +1,15 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+## CarouselView variable
+
+> Warning: This API is now obsolete.
+>
+> Renamed to \[\[CarouselLayout\]\]
+
+**Signature:**
+
+```typescript
+CarouselView: typeof CarouselLayout;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}

package/generated-docs/react/chatprops.md

@@ -16,6 +16,6 @@ export interface ChatProps extends React.HTMLAttributes<HTMLDivElement>
 
 | Property                                                   | Type                                            | Description  |
 | ---------------------------------------------------------- | ----------------------------------------------- | ------------ |
-| [messageDecoder?](./react/chatprops.messagedecoder.md)     | [MessageDecoder](./react/messagedecoder.md)     | _(Optional)_ |
-| [messageEncoder?](./react/chatprops.messageencoder.md)     | [MessageEncoder](./react/messageencoder.md)     | _(Optional)_ |
+| [messageDecoder?](./react/chatprops.messagedecoder.md)     | [MessageDecoder](./core/messagedecoder.md)      | _(Optional)_ |
+| [messageEncoder?](./react/chatprops.messageencoder.md)     | [MessageEncoder](./core/messageencoder.md)      | _(Optional)_ |
 | [messageFormatter?](./react/chatprops.messageformatter.md) | [MessageFormatter](./react/messageformatter.md) | _(Optional)_ |

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

@@ -14,7 +14,7 @@ import { AudioTrack } from '@livekit/components-react';
 
 ```tsx
 <ParticipantTile>
-  <AudioTrack source={Track.Source.Microphone} />
+  <AudioTrack trackRef={trackRef} />
 </ParticipantTile>
 ```
 
@@ -22,9 +22,6 @@ import { AudioTrack } from '@livekit/components-react';
 
 ## Properties
 
-{% parameter name="source" type="Track.Source" optional=false %}
-{% /parameter %}
-
 {% parameter name="name" type="string" optional=true %}
 _(Optional)_
 
@@ -45,6 +42,16 @@ _(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 from which the audio is to be rendered.
+
+{% /parameter %}
+
 {% parameter name="volume" type="number" optional=true %}
 _(Optional)_ by the default the range is between 0 and 1
 

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

@@ -2,13 +2,25 @@
 
 # AudioVisualizer
 
+The AudioVisualizer component is used to visualize the audio volume of a given audio track.
+
 ## Import
 
 ```typescript
 import { AudioVisualizer } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Remarks
+
+Requires a `TrackReferenceOrPlaceholder` to be provided either as a property or via the `TrackRefContext`<!-- -->.
+
+## Usage
+
+```tsx
+<AudioVisualizer />
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Properties
 
@@ -16,3 +28,8 @@ import { AudioVisualizer } from '@livekit/components-react';
 _(Optional)_
 
 {% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_
+
+{% /parameter %}

package/generated-docs/react/component/{carouselview.md → carousellayout.md}

@@ -1,19 +1,23 @@
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
-# CarouselView
+# CarouselLayout
 
-The `CarouselLayout` displays a list of tracks horizontally or vertically. Depending on the size of the container, the carousel will display as many tiles as possible and overflows the rest. The CarouselLayout uses the `useVisualStableUpdate` hook to ensure that tile reordering due to track updates is visually stable but still moves the important tiles (speaking participants) to the front.
+The `CarouselLayout` component displays a list of tracks in a scroll container. It will display as many tiles as possible and overflow the rest.
 
 ## Import
 
 ```typescript
-import { CarouselView } from '@livekit/components-react';
+import { CarouselLayout } from '@livekit/components-react';
 ```
 
+## Remarks
+
+To ensure visual stability when tiles are reordered due to track updates, the component uses the `useVisualStableUpdate` hook.
+
 ## Usage
 
 ```tsx
-const tracks = useTracks();
+const tracks = useTracks([Track.Source.Camera]);
 <CarouselLayout tracks={tracks}>
   <ParticipantTile />
 </CarouselLayout>;

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

@@ -2,7 +2,7 @@
 
 # ChatToggle
 
-The ChatToggle component toggles the visibility of the chat component.
+The `ChatToggle` component is a button that toggles the visibility of the `Chat` component.
 
 ## Import
 
@@ -10,6 +10,10 @@ The ChatToggle component toggles the visibility of the chat component.
 import { ChatToggle } from '@livekit/components-react';
 ```
 
+## Remarks
+
+For the component to have any effect it has to live inside a `LayoutContext` context.
+
 ## Usage
 
 ```tsx

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

@@ -2,7 +2,7 @@
 
 # ClearPinButton
 
-The ClearPinButton is a basic html button with the added ability to signal the LiveKitRoom that it should display the grid view again.
+The `ClearPinButton` is a basic html button with the added ability to signal the `LayoutContext` that it should display the grid view again.
 
 ## Import
 
@@ -12,13 +12,13 @@ import { ClearPinButton } from '@livekit/components-react';
 
 ## Remarks
 
-This component works only inside a PinContext.
+This component works only inside a `LayoutContext`<!-- -->.
 
 ## Usage
 
 ```tsx
 <LiveKitRoom>
-  <ClearPinButton>Leave room</ClearPinButton>
+  <ClearPinButton>Back to grid view</ClearPinButton>
 </LiveKitRoom>
 ```
 

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

@@ -2,7 +2,7 @@
 
 # ConnectionQualityIndicator
 
-The ConnectionQualityIndicator shows the individual connection quality of a participant.
+The `ConnectionQualityIndicator` shows the individual connection quality of a participant.
 
 ## Import
 

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

@@ -2,7 +2,7 @@
 
 # ConnectionState
 
-The ConnectionState component displays the connection status of the room in written form.
+The `ConnectionState` component displays the connection status of the room as strings (`"connected" | "connecting" | "disconnected" | "reconnecting"`<!-- -->).
 
 ## Import
 

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

@@ -2,6 +2,8 @@
 
 # ConnectionStateToast
 
+The `ConnectionStateToast` component displays a toast notification indicating the current connection state of the room.
+
 ## Import
 
 ```typescript

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

@@ -2,7 +2,7 @@
 
 # ControlBar
 
-The ControlBar prefab component gives the user the basic user interface to control their media devices and leave the room.
+The `ControlBar` prefab gives the user the basic user interface to control their media devices (camera, microphone and screen share), open the `Chat` and leave the room.
 
 ## Import
 

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

@@ -2,7 +2,7 @@
 
 # DisconnectButton
 
-The DisconnectButton is a basic html button with the added ability to disconnect from a LiveKit room. Normally, it is used by end-users to leave a video or audio call.
+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.
 
 ## Import
 

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

@@ -2,6 +2,8 @@
 
 # FocusLayout
 
+The `FocusLayout` component is just a light wrapper around the `ParticipantTile` to display a single participant.
+
 ## Import
 
 ```typescript
@@ -21,3 +23,8 @@ _(Optional)_
 _(Optional)_
 
 {% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_ The track to display in the focus layout.
+
+{% /parameter %}

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

@@ -2,6 +2,8 @@
 
 # FocusLayoutContainer
 
+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.
+
 ## Import
 
 ```typescript

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

@@ -2,7 +2,7 @@
 
 # FocusToggle
 
-The FocusToggle puts the ParticipantTile in focus or removes it from focus.
+The `FocusToggle` puts the `ParticipantTile` in focus or removes it from focus.
 
 ## Import
 
@@ -10,6 +10,10 @@ The FocusToggle puts the ParticipantTile in focus or removes it from focus.
 import { FocusToggle } from '@livekit/components-react';
 ```
 
+## Remarks
+
+This component needs to live inside `LayoutContext` to work properly.
+
 ## Usage
 
 ```tsx
@@ -22,10 +26,17 @@ import { FocusToggle } from '@livekit/components-react';
 
 ## Properties
 
-{% parameter name="trackSource" type="Track.Source" optional=false %}
+{% parameter name="participant" type="Participant" optional=true %}
+_(Optional)_
+
 {% /parameter %}
 
-{% parameter name="participant" type="Participant" optional=true %}
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_
+
+{% /parameter %}
+
+{% parameter name="trackSource" type="Track.Source" optional=true %}
 _(Optional)_
 
 {% /parameter %}

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

@@ -2,7 +2,7 @@
 
 # GridLayout
 
-The GridLayout component displays the nested participants in a grid where every participants has the same size.
+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.
 
 ## Import
 
@@ -10,6 +10,10 @@ The GridLayout component displays the nested participants in a grid where every
 import { GridLayout } from '@livekit/components-react';
 ```
 
+## Remarks
+
+To ensure visual stability when tiles are reordered due to track updates, the component uses the `useVisualStableUpdate` hook.
+
 ## Usage
 
 ```tsx

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

@@ -2,7 +2,7 @@
 
 # LiveKitRoom
 
-The LiveKitRoom component provides the room context to all its child components. It is generally the starting point of your LiveKit app and the root of the LiveKit component tree. It provides the room state as a React context to all child components, so you don't have to pass it yourself.
+The `LiveKitRoom` component provides the room context to all its child components. It is generally the starting point of your LiveKit app and the root of the LiveKit component tree. It provides the room state as a React context to all child components, so you don't have to pass it yourself.
 
 ## Import
 

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

@@ -2,7 +2,7 @@
 
 # MediaDeviceMenu
 
-The MediaDeviceMenu prefab component is a button that opens a menu that lists all media devices and allows the user to select them.
+The `MediaDeviceMenu` component is a button that opens a menu that lists all media devices and allows the user to select them.
 
 ## Import
 

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

@@ -2,7 +2,7 @@
 
 # MediaDeviceSelect
 
-The MediaDeviceSelect list all media devices of one kind. Clicking on one of the listed devices make it the active media device.
+The `MediaDeviceSelect` list all media devices of one kind. Clicking on one of the listed devices make it the active media device.
 
 ## Import
 

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

@@ -2,7 +2,7 @@
 
 # ParticipantAudioTile
 
-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.
+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.
 
 ## Import
 
@@ -44,3 +44,8 @@ _(Optional)_
 _(Optional)_
 
 {% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_ The track reference to display.
+
+{% /parameter %}

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

@@ -2,10 +2,20 @@
 
 # ParticipantContextIfNeeded
 
+The `ParticipantContextIfNeeded` component only creates a `ParticipantContext` if there is no `ParticipantContext` already.
+
 ## Import
 
 ```typescript
 import { ParticipantContextIfNeeded } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+<ParticipantContextIfNeeded participant={trackReference.participant}>
+  ...
+</ParticipantContextIfNeeded>
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}

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

@@ -2,7 +2,7 @@
 
 # ParticipantLoop
 
-The ParticipantLoop component loops over an array of participants to create a context for every participant. This component takes exactly one child component as a template. By providing your own template as a child you have full control over the look and feel of your participant representations.
+The `ParticipantLoop` component loops over an array of participants to create a context for every participant. This component takes exactly one child component as a template. By providing your own template as a child you have full control over the look and feel of your participant representations.
 
 ## Import
 

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

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