@livekit/components-js-docs 0.0.5 → 0.1.1

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "AudioConference",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/prefabs/AudioConference.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # AudioConference
@@ -7,7 +14,7 @@ This component is the default setup of a classic LiveKit audio conferencing app.
 ## Import
 
 ```typescript
-import { AudioConference } from '@livekit/components-react';
+import { AudioConference } from "@livekit/components-react";
 ```
 
 ## Remarks

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "AudioTrack",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/participant/AudioTrack.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # AudioTrack
@@ -7,14 +14,14 @@ The AudioTrack component is responsible for rendering participant audio tracks.
 ## Import
 
 ```typescript
-import { AudioTrack } from '@livekit/components-react';
+import { AudioTrack } from "@livekit/components-react";
 ```
 
 ## Usage
 
 ```tsx
 <ParticipantTile>
-  <AudioTrack source={Track.Source.Microphone} />
+  <AudioTrack trackRef={trackRef} />
 </ParticipantTile>
 ```
 
@@ -22,30 +29,53 @@ import { AudioTrack } from '@livekit/components-react';
 
 ## Properties
 
-{% parameter name="source" type="Track.Source" optional=false %}
+{% parameter name="onSubscriptionStatusChanged" type="(subscribed: boolean) => void" optional=true %}
+_(Optional)_
+
 {% /parameter %}
 
-{% parameter name="name" type="string" optional=true %}
-_(Optional)_
+{% 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="onSubscriptionStatusChanged" type="(subscribed: boolean) => void" optional=true %}
+{% parameter name="volume" type="number" optional=true %}
+_(Optional)_ by the default the range is between 0 and 1
+
+{% /parameter %}
+
+{% parameter name="name" type="string" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This property will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
 {% /parameter %}
 
-{% parameter name="participant" type="Participant" optional=true %}
+{% parameter name="participant" type="Participant" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This property will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
 {% /parameter %}
 
-{% parameter name="publication" type="TrackPublication" optional=true %}
+{% parameter name="publication" type="TrackPublication" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This property will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
 {% /parameter %}
 
-{% parameter name="volume" type="number" optional=true %}
-_(Optional)_ by the default the range is between 0 and 1
+{% parameter name="source" type="Track.Source" optional=true deprecated=true %}
+_(Optional)_
+
+{% callout type="caution" variation="compact" %}
+This property will be removed in a future version use `trackRef` instead.
 
+{% /callout %}
 {% /parameter %}

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

@@ -1,18 +1,46 @@
+---
+{
+  "title": "AudioVisualizer",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/participant/AudioVisualizer.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # AudioVisualizer
 
+The AudioVisualizer component is used to visualize the audio volume of a given audio track.
+
 ## Import
 
 ```typescript
-import { AudioVisualizer } from '@livekit/components-react';
+import { AudioVisualizer } from "@livekit/components-react";
+```
+
+## 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: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Properties
 
-{% parameter name="participant" type="Participant" optional=true %}
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_
+
+{% /parameter %}
+
+{% parameter name="participant" type="Participant" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+this property will be removed in a future version, use `trackRef` instead
+
+{% /callout %}
 {% /parameter %}

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

@@ -1,19 +1,30 @@
+---
+{
+  "title": "CarouselLayout",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/layout/CarouselLayout.tsx"
+}
+---
+
 <!-- 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/chat.md

@@ -1,3 +1,10 @@
+---
+{
+  "title": "Chat",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/prefabs/Chat.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # Chat
@@ -7,7 +14,7 @@ The Chat component adds a basis chat functionality to the LiveKit room. The mess
 ## Import
 
 ```typescript
-import { Chat } from '@livekit/components-react';
+import { Chat } from "@livekit/components-react";
 ```
 
 ## Usage

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "ChatEntry",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/ChatEntry.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # ChatEntry
@@ -7,7 +14,7 @@ The `ChatEntry` component holds and displays one chat message.
 ## Import
 
 ```typescript
-import { ChatEntry } from '@livekit/components-react';
+import { ChatEntry } from "@livekit/components-react";
 ```
 
 ## Usage

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

@@ -1,15 +1,26 @@
+---
+{
+  "title": "ChatToggle",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/controls/ChatToggle.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { ChatToggle } from '@livekit/components-react';
+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

@@ -1,24 +1,31 @@
+---
+{
+  "title": "ClearPinButton",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/controls/ClearPinButton.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { ClearPinButton } from '@livekit/components-react';
+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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "ConnectionQualityIndicator",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/participant/ConnectionQualityIndicator.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # ConnectionQualityIndicator
 
-The ConnectionQualityIndicator shows the individual connection quality of a participant.
+The `ConnectionQualityIndicator` shows the individual connection quality of a participant.
 
 ## Import
 
 ```typescript
-import { ConnectionQualityIndicator } from '@livekit/components-react';
+import { ConnectionQualityIndicator } from "@livekit/components-react";
 ```
 
 ## Usage

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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "ConnectionState",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/ConnectionState.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { ConnectionState } from '@livekit/components-react';
+import { ConnectionState } from "@livekit/components-react";
 ```
 
 ## Usage

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

@@ -1,11 +1,20 @@
+---
+{
+  "title": "ConnectionStateToast",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/ConnectionStateToast.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # ConnectionStateToast
 
+The `ConnectionStateToast` component displays a toast notification indicating the current connection state of the room.
+
 ## Import
 
 ```typescript
-import { ConnectionStateToast } from '@livekit/components-react';
+import { ConnectionStateToast } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "ControlBar",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/prefabs/ControlBar.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { ControlBar } from '@livekit/components-react';
+import { ControlBar } from "@livekit/components-react";
 ```
 
 ## Remarks

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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "DisconnectButton",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/controls/DisconnectButton.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { DisconnectButton } from '@livekit/components-react';
+import { DisconnectButton } from "@livekit/components-react";
 ```
 
 ## Usage

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

@@ -1,11 +1,20 @@
+---
+{
+  "title": "FocusLayout",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/layout/FocusLayout.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # FocusLayout
 
+The `FocusLayout` component is just a light wrapper around the `ParticipantTile` to display a single participant.
+
 ## Import
 
 ```typescript
-import { FocusLayout } from '@livekit/components-react';
+import { FocusLayout } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
@@ -17,7 +26,16 @@ _(Optional)_
 
 {% /parameter %}
 
-{% parameter name="track" type="TrackReferenceOrPlaceholder" optional=true %}
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_ The track to display in the focus layout.
+
+{% /parameter %}
+
+{% parameter name="track" type="TrackReferenceOrPlaceholder" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This property will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
 {% /parameter %}

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

@@ -1,23 +1,40 @@
+---
+{
+  "title": "FocusLayoutContainer",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/layout/FocusLayout.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
-import { FocusLayoutContainer } from '@livekit/components-react';
+import { FocusLayoutContainer } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
 ## Properties
 
-{% parameter name="focusTrack" type="TrackReference" optional=true %}
+{% parameter name="focusTrack" type="TrackReference" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This property has no effect and will be removed in a future version.
+
+{% /callout %}
 {% /parameter %}
 
-{% parameter name="participants" type="Array<Participant>" optional=true %}
+{% parameter name="participants" type="Array<Participant>" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This property has no effect and will be removed in a future version.
+
+{% /callout %}
 {% /parameter %}

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

@@ -1,15 +1,26 @@
+---
+{
+  "title": "FocusToggle",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/controls/FocusToggle.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { FocusToggle } from '@livekit/components-react';
+import { FocusToggle } from "@livekit/components-react";
 ```
 
+## Remarks
+
+This component needs to live inside `LayoutContext` to work properly.
+
 ## Usage
 
 ```tsx
@@ -22,10 +33,25 @@ import { FocusToggle } from '@livekit/components-react';
 
 ## Properties
 
-{% parameter name="trackSource" type="Track.Source" optional=false %}
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+_(Optional)_
+
 {% /parameter %}
 
-{% parameter name="participant" type="Participant" optional=true %}
+{% parameter name="participant" type="Participant" optional=true deprecated=true %}
 _(Optional)_
 
+{% callout type="caution" variation="compact" %}
+This parameter will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
+{% /parameter %}
+
+{% parameter name="trackSource" type="Track.Source" optional=true deprecated=true %}
+_(Optional)_
+
+{% callout type="caution" variation="compact" %}
+This parameter will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
 {% /parameter %}

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

@@ -1,15 +1,26 @@
+---
+{
+  "title": "GridLayout",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/layout/GridLayout.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { GridLayout } from '@livekit/components-react';
+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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "LiveKitRoom",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/LiveKitRoom.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { LiveKitRoom } from '@livekit/components-react';
+import { LiveKitRoom } from "@livekit/components-react";
 ```
 
 ## Usage

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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "MediaDeviceMenu",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/prefabs/MediaDeviceMenu.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { MediaDeviceMenu } from '@livekit/components-react';
+import { MediaDeviceMenu } from "@livekit/components-react";
 ```
 
 ## Remarks

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

@@ -1,13 +1,20 @@
+---
+{
+  "title": "MediaDeviceSelect",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/components/controls/MediaDeviceSelect.tsx"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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
 
 ```typescript
-import { MediaDeviceSelect } from '@livekit/components-react';
+import { MediaDeviceSelect } from "@livekit/components-react";
 ```
 
 ## Usage