@livekit/components-js-docs 0.0.5 → 0.1.1

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useConnectionState",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useConnectionStatus.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useConnectionState
@@ -7,7 +14,7 @@ The `useConnectionState` hook allows you to simply implement your own `Connectio
 ## Import
 
 ```typescript
-import { useConnectionState } from '@livekit/components-react';
+import { useConnectionState } from "@livekit/components-react";
 ```
 
 ## Usage
@@ -18,7 +25,7 @@ const connectionState = useConnectionState(room);
 
 {% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="room" type="Room" optional=true %}
 {% /parameter %}
@@ -26,5 +33,5 @@ const connectionState = useConnectionState(room);
 ## Returns
 
 ```typescript
-import('livekit-client').ConnectionState;
+import("livekit-client").ConnectionState;
 ```

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useCreateLayoutContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/layout-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useCreateLayoutContext
@@ -5,7 +12,7 @@
 ## Import
 
 ```typescript
-import { useCreateLayoutContext } from '@livekit/components-react';
+import { useCreateLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,16 +1,36 @@
+---
+{
+  "title": "useDataChannel",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useDataChannel.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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';
+import { useDataChannel } from "@livekit/components-react";
+```
+
+## 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: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="topic" type="T" optional=false %}
 {% /parameter %}

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

@@ -1,16 +1,36 @@
+---
+{
+  "title": "useDataChannel",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useDataChannel.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useDataChannel
 
+The `useDataChannel` hook returns the ability to send and receive messages.
+
 ## Import
 
 ```typescript
-import { useDataChannel } from '@livekit/components-react';
+import { useDataChannel } from "@livekit/components-react";
+```
+
+## 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: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="onMessage" type="(msg: ReceivedDataMessage) => void" optional=true %}
 {% /parameter %}

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

@@ -1,18 +1,34 @@
+---
+{
+  "title": "useDisconnectButton",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useDisconnectButton.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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';
+import { useDisconnectButton } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const { buttonProps } = useDisconnectButton();
+return <button {...buttonProps}>Disconnect</button>;
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
-{% parameter name="props" type="DisconnectButtonProps" optional=false %}
+{% parameter name="stopTracks" type="boolean" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useEnsureCreateLayoutContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/layout-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useEnsureCreateLayoutContext
@@ -5,12 +12,12 @@
 ## Import
 
 ```typescript
-import { useEnsureCreateLayoutContext } from '@livekit/components-react';
+import { useEnsureCreateLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="layoutContext" type="LayoutContextType" optional=true %}
 {% /parameter %}

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useEnsureLayoutContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/layout-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useEnsureLayoutContext
@@ -7,12 +14,12 @@ Ensures that a layout context is provided, either via context or explicitly as a
 ## Import
 
 ```typescript
-import { useEnsureLayoutContext } from '@livekit/components-react';
+import { useEnsureLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="layoutContext" type="LayoutContextType" optional=true %}
 {% /parameter %}

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useEnsureParticipant",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/participant-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useEnsureParticipant
@@ -7,12 +14,12 @@ Ensures that a participant is provided, either via context or explicitly as a pa
 ## Import
 
 ```typescript
-import { useEnsureParticipant } from '@livekit/components-react';
+import { useEnsureParticipant } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="participant" type="Participant" optional=true %}
 {% /parameter %}

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useEnsureRoom",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/room-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useEnsureRoom
@@ -7,12 +14,12 @@ Ensures that a room is provided, either via context or explicitly as a parameter
 ## Import
 
 ```typescript
-import { useEnsureRoom } from '@livekit/components-react';
+import { useEnsureRoom } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="room" type="Room" optional=true %}
 {% /parameter %}

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

@@ -0,0 +1,31 @@
+---
+{
+  "title": "useEnsureTrackRef",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/track-reference-context.ts"
+}
+---
+
+<!-- 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} /%}
+
+## Properties
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+TrackReferenceOrPlaceholder;
+```

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

@@ -1,18 +1,33 @@
+---
+{
+  "title": "useEnsureTrackReference",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/track-reference-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useEnsureTrackReference
 
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+`useEnsureTrackReference` has been renamed to `useEnsureTrackRef`<!-- -->, use this as a drop in replacement.
+
+{% /callout %}
+
 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
 
 ```typescript
-import { useEnsureTrackReference } from '@livekit/components-react';
+import { useEnsureTrackReference } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="track" type="TrackReferenceOrPlaceholder" optional=true %}
 {% /parameter %}

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

@@ -1,18 +1,51 @@
+---
+{
+  "title": "useFocusToggle",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useFocusToggle.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # 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';
+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} /%}
+
+## Properties
+
+{% parameter name="props" type="React.ButtonHTMLAttributes<HTMLButtonElement>" optional=false %}
+{% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+{% /parameter %}
+
+{% parameter name="participant" type="Participant" optional=true deprecated=true %}
+{% callout type="caution" variation="compact" %}
+This parameter will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
+{% /parameter %}
 
-## Parameters
+{% parameter name="trackSource" type="Track.Source" optional=true deprecated=true %}
+{% callout type="caution" variation="compact" %}
+This parameter will be removed in a future version use `trackRef` instead.
 
-{% parameter name="{ trackSource, participant, props }" type="UseFocusToggleProps" optional=false %}
+{% /callout %}
 {% /parameter %}
 
 ## Returns

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

@@ -1,18 +1,31 @@
+---
+{
+  "title": "useGridLayout",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useGridLayout.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useGridLayout
 
-The useGridLayout hook tries to select the best layout to fit all tiles. If the available screen space is not enough, it will reduce the number of maximum visible tiles and select a layout that still works visually within the given limitations. As the order of tiles changes over time, the hook tries to keep visual updates to a minimum while trying to display important tiles such as speaking participants or screen shares.
+The `useGridLayout` hook tries to select the best layout to fit all tiles. If the available screen space is not enough, it will reduce the number of maximum visible tiles and select a layout that still works visually within the given limitations. As the order of tiles changes over time, the hook tries to keep visual updates to a minimum while trying to display important tiles such as speaking participants or screen shares.
 
 ## Import
 
 ```typescript
-import { useGridLayout } from '@livekit/components-react';
+import { useGridLayout } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const { layout } = useGridLayout(gridElement, trackCount);
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="gridElement" type="React.RefObject<HTMLDivElement>" optional=false %}
 {% /parameter %}

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

@@ -1,21 +1,33 @@
+---
+{
+  "title": "useIsMuted",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useIsMuted.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useIsMuted
 
+The `useIsMuted` hook is used to implement the `TrackMutedIndicator` or your custom implementation of it. It returns a `boolean` that indicates if the track is muted or not.
+
 ## Import
 
 ```typescript
-import { useIsMuted } from '@livekit/components-react';
+import { useIsMuted } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
 
-## Parameters
+```tsx
+const isMuted = useIsMuted(track);
+```
 
-{% parameter name="source" type="Track.Source" optional=false %}
-{% /parameter %}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
+
+## Properties
 
-{% parameter name="options" type="UseIsMutedOptions" optional=true %}
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=false %}
 {% /parameter %}
 
 ## Returns

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

@@ -0,0 +1,40 @@
+---
+{
+  "title": "useIsMuted",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useIsMuted.ts"
+}
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useIsMuted
+
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+This overload will be removed in a future version, pass in trackRef instead.
+
+{% /callout %}
+
+## Import
+
+```typescript
+import { useIsMuted } from "@livekit/components-react";
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Properties
+
+{% parameter name="source" type="Track.Source" optional=false %}
+{% /parameter %}
+
+{% parameter name="options" type="UseIsMutedOptions" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+boolean;
+```

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

@@ -1,16 +1,31 @@
+---
+{
+  "title": "useIsSpeaking",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useIsSpeaking.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useIsSpeaking
 
+The `useIsSpeaking` hook returns a `boolean` that indicates if the participant is speaking or not.
+
 ## Import
 
 ```typescript
-import { useIsSpeaking } from '@livekit/components-react';
+import { useIsSpeaking } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const isSpeaking = useIsSpeaking(participant);
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="participant" type="Participant" optional=true %}
 {% /parameter %}

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useLayoutContext",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/context/layout-context.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLayoutContext
@@ -7,7 +14,7 @@ Ensures that a layout context is provided via context. If no layout context is p
 ## Import
 
 ```typescript
-import { useLayoutContext } from '@livekit/components-react';
+import { useLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,18 +1,91 @@
+---
+{
+  "title": "useLiveKitRoom",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useLiveKitRoom.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLiveKitRoom
 
+The `useLiveKitRoom` hook is used to implement the `LiveKitRoom` or your custom implementation of it. It returns a `Room` instance and HTML props that should be applied to the root element of the component.
+
 ## Import
 
 ```typescript
-import { useLiveKitRoom } from '@livekit/components-react';
+import { useLiveKitRoom } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { room, htmlProps } = useLiveKitRoom();
+return <div {...htmlProps}>...</div>;
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
+
+## Properties
+
+{% parameter name="serverUrl" type="string | undefined" optional=false %}
+URL to the LiveKit server. For example: `wss://<domain>.livekit.cloud` To simplify the implementation, `undefined` is also accepted as an intermediate value, but only with a valid string url can the connection be established.
+
+{% /parameter %}
+
+{% parameter name="token" type="string | undefined" optional=false %}
+A user specific access token for a client to authenticate to the room. This token is necessary to establish a connection to the room. To simplify the implementation, `undefined` is also accepted as an intermediate value, but only with a valid string token can the connection be established.
+
+{% /parameter %}
+
+{% parameter name="audio" type="AudioCaptureOptions | boolean" optional=true %}
+Publish audio immediately after connecting to your LiveKit room.
+
+{% /parameter %}
+
+{% parameter name="connect" type="boolean" optional=true %}
+If set to true a connection to LiveKit room is initiated.
+
+{% /parameter %}
+
+{% parameter name="connectOptions" type="RoomConnectOptions" optional=true %}
+Define options how to connect to the LiveKit server.
+
+{% /parameter %}
+
+{% parameter name="onConnected" type="() => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="onDisconnected" type="() => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="onError" type="(error: Error) => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="onMediaDeviceFailure" type="(failure?: MediaDeviceFailure) => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="options" type="RoomOptions" optional=true %}
+Options for when creating a new room. When you pass your own room instance to this component, these options have no effect. Instead, set the options directly in the room instance.
+
+{% /parameter %}
+
+{% parameter name="room" type="Room" optional=true %}
+Optional room instance. By passing your own room instance you overwrite the `options` parameter, make sure to set the options directly on the room instance itself.
+
+{% /parameter %}
+
+{% parameter name="screen" type="ScreenShareCaptureOptions | boolean" optional=true %}
+Publish screen share immediately after connecting to your LiveKit room.
+
+{% /parameter %}
+
+{% parameter name="simulateParticipants" type="number | undefined" optional=true %}
+{% /parameter %}
 
-## Parameters
+{% parameter name="video" type="VideoCaptureOptions | boolean" optional=true %}
+Publish video immediately after connecting to your LiveKit room.
 
-{% parameter name="props" type="LiveKitRoomProps" optional=false %}
 {% /parameter %}
 
 ## Returns