@livekit/components-js-docs 0.0.5 → 0.1.1

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

@@ -1,18 +1,31 @@
+---
+{
+  "title": "useLocalParticipant",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useLocalParticipant.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLocalParticipant
 
-The useLocalParticipant hook the state of the local participant.
+The `useLocalParticipant` hook returns the local participant and the associated state around the participant.
 
 ## Import
 
 ```typescript
-import { useLocalParticipant } from '@livekit/components-react';
+import { useLocalParticipant } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const { localParticipant } = useLocalParticipant();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="options" type="UseLocalParticipantOptions" optional=true %}
 {% /parameter %}

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

@@ -1,17 +1,32 @@
+---
+{
+  "title": "useLocalParticipantPermissions",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useLocalParticipantPermissions.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useLocalParticipantPermissions
 
+The `useLocalParticipantPermissions` hook returns the local participant's permissions.
+
 ## Import
 
 ```typescript
-import { useLocalParticipantPermissions } from '@livekit/components-react';
+import { useLocalParticipantPermissions } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const { canPublish, canPublishData } = useLocalParticipantPermissions();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Returns
 
 ```typescript
-import('livekit-client/dist/src/proto/livekit_models_pb').ParticipantPermission | undefined;
+import("livekit-client/dist/src/proto/livekit_models_pb").ParticipantPermission | undefined;
 ```

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeLayoutContext",
+  "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. -->
 
 # useMaybeLayoutContext
@@ -7,7 +14,7 @@ Returns a layout context from the `LayoutContext` if it exists, otherwise `undef
 ## Import
 
 ```typescript
-import { useMaybeLayoutContext } from '@livekit/components-react';
+import { useMaybeLayoutContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeParticipantContext",
+  "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. -->
 
 # useMaybeParticipantContext
@@ -7,7 +14,7 @@ Returns a participant from the `ParticipantContext` if it exists, otherwise `und
 ## Import
 
 ```typescript
-import { useMaybeParticipantContext } from '@livekit/components-react';
+import { useMaybeParticipantContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useMaybeRoomContext",
+  "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. -->
 
 # useMaybeRoomContext
@@ -7,7 +14,7 @@ Returns the room context if it exists, otherwise undefined.
 ## Import
 
 ```typescript
-import { useMaybeRoomContext } from '@livekit/components-react';
+import { useMaybeRoomContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,13 +1,28 @@
+---
+{
+  "title": "useMaybeTrackContext",
+  "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. -->
 
 # useMaybeTrackContext
 
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+`useMaybeTrackContext` has been renamed to `useMaybeTrackRefContext`<!-- -->, use this as a drop in replacement.
+
+{% /callout %}
+
 Returns a track reference from the `TrackContext` if it exists, otherwise `undefined`<!-- -->.
 
 ## Import
 
 ```typescript
-import { useMaybeTrackContext } from '@livekit/components-react';
+import { useMaybeTrackContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -0,0 +1,26 @@
+---
+{
+  "title": "useMaybeTrackRefContext",
+  "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. -->
+
+# useMaybeTrackRefContext
+
+Returns a track reference from the `TrackRefContext` if it exists, otherwise `undefined`<!-- -->.
+
+## Import
+
+```typescript
+import { useMaybeTrackRefContext } from "@livekit/components-react";
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Returns
+
+```typescript
+TrackReferenceOrPlaceholder | undefined;
+```

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

@@ -1,20 +1,36 @@
+---
+{
+  "title": "useMediaDevices",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaDevices.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaDevices
 
+The `useMediaDevices` hook returns the list of media devices of a given kind.
+
 ## Import
 
 ```typescript
-import { useMediaDevices } from '@livekit/components-react';
+import { useMediaDevices } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const videoDevices = useMediaDevices({ kind: "videoinput" });
+const audioDevices = useMediaDevices({ kind: "audioinput" });
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="{ kind }" type="{
-    kind: MediaDeviceKind;
-}" optional=false %}
+      kind: MediaDeviceKind;
+  }" optional=false %}
 {% /parameter %}
 
 ## Returns

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

@@ -1,18 +1,46 @@
+---
+{
+  "title": "useMediaDeviceSelect",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaDeviceSelect.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaDeviceSelect
 
+The `useMediaDeviceSelect` hook is used to implement the `MediaDeviceSelect` component and returns o.a. the list of devices of a given kind (audioinput or videoinput), the currently active device and a function to set the the active device.
+
 ## Import
 
 ```typescript
-import { useMediaDeviceSelect } from '@livekit/components-react';
+import { useMediaDeviceSelect } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const { devices, activeDeviceId, setActiveMediaDevice } = useMediaDeviceSelect({
+  kind: "audioinput"
+});
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
+
+{% parameter name="kind" type="MediaDeviceKind" optional=false %}
+{% /parameter %}
+
+{% parameter name="requestPermissions" type="boolean" optional=true %}
+this will call getUserMedia if the permissions are not yet given to enumerate the devices with device labels. in some browsers multiple calls to getUserMedia result in multiple permission prompts. It's generally advised only flip this to true, once a (preview) track has been acquired successfully with the appropriate permissions.
+
+{% /parameter %}
+
+{% parameter name="room" type="Room" optional=true %}
+{% /parameter %}
 
-{% parameter name="{ kind, room, track, requestPermissions, }" type="UseMediaDeviceSelectProps" optional=false %}
+{% parameter name="track" type="LocalAudioTrack | LocalVideoTrack" optional=true %}
 {% /parameter %}
 
 ## Returns

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

@@ -1,16 +1,31 @@
+---
+{
+  "title": "useMediaTrack",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaTrack.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaTrack
 
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+use `useTrack` instead
+
+{% /callout %}
+
 ## Import
 
 ```typescript
-import { useMediaTrack } from '@livekit/components-react';
+import { useMediaTrack } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="source" type="VideoSource | AudioSource" optional=false %}
 {% /parameter %}
@@ -25,10 +40,10 @@ import { useMediaTrack } from '@livekit/components-react';
 
 ```typescript
 {
-  publication: import('livekit-client').TrackPublication | undefined;
+  publication: import("livekit-client").TrackPublication | undefined;
   isMuted: boolean | undefined;
   isSubscribed: boolean | undefined;
-  track: import('livekit-client').Track | undefined;
+  track: import("livekit-client").Track | undefined;
   elementProps: React.HTMLAttributes<HTMLElement>;
 }
 ```

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

@@ -1,16 +1,31 @@
+---
+{
+  "title": "useMediaTrackByName",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useMediaTrackByName.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useMediaTrackByName
 
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+This function will be removed in a future version, use `useTrackByName` instead.
+
+{% /callout %}
+
 ## Import
 
 ```typescript
-import { useMediaTrackByName } from '@livekit/components-react';
+import { useMediaTrackByName } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="name" type="string" optional=false %}
 {% /parameter %}
@@ -25,10 +40,10 @@ import { useMediaTrackByName } from '@livekit/components-react';
 
 ```typescript
 {
-  publication: import('livekit-client').TrackPublication | undefined;
+  publication: import("livekit-client").TrackPublication | undefined;
   isMuted: boolean | undefined;
   isSubscribed: boolean | undefined;
-  track: import('livekit-client').Track | undefined;
-  elementProps: import('react').HTMLAttributes<HTMLElement>;
+  track: import("livekit-client").Track | undefined;
+  elementProps: import("react").HTMLAttributes<HTMLElement>;
 }
 ```

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useParticipantContext",
+  "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. -->
 
 # useParticipantContext
@@ -7,7 +14,7 @@ Ensures that a participant is provided via context. If not inside a `Participant
 ## Import
 
 ```typescript
-import { useParticipantContext } from '@livekit/components-react';
+import { useParticipantContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

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

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useParticipantPermissions",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useParticipantPermissions.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useParticipantPermissions
@@ -5,12 +12,12 @@
 ## Import
 
 ```typescript
-import { useParticipantPermissions } from '@livekit/components-react';
+import { useParticipantPermissions } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="options" type="UseParticipantPermissionsOptions" optional=true %}
 {% /parameter %}
@@ -18,5 +25,5 @@ import { useParticipantPermissions } from '@livekit/components-react';
 ## Returns
 
 ```typescript
-import('livekit-client/dist/src/proto/livekit_models_pb').ParticipantPermission | undefined;
+import("livekit-client/dist/src/proto/livekit_models_pb").ParticipantPermission | undefined;
 ```

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

@@ -1,18 +1,38 @@
+---
+{
+  "title": "useParticipants",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useParticipants.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useParticipants
 
-The useParticipants hook returns all participants (local and remote) of the current room.
+The `useParticipants` hook returns all participants (local and remote) of the current room.
 
 ## Import
 
 ```typescript
-import { useParticipants } from '@livekit/components-react';
+import { useParticipants } from "@livekit/components-react";
+```
+
+## Remarks
+
+To optimize performance, you can use the `updateOnlyOn` property to decide on what `RoomEvents` the hook updates.
+
+## Usage
+
+```tsx
+const participants = useParticipants();
+<ParticipantLoop participants={participants}>
+  <ParticipantName />
+</ParticipantLoop>;
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="options" type="UseParticipantsOptions" optional=true %}
 {% /parameter %}

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

@@ -1,18 +1,63 @@
+---
+{
+  "title": "useParticipantTile",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useParticipantTile.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useParticipantTile
 
+The `useParticipantTile` hook is used to implement the `ParticipantTile` and returns the props needed to render the tile.
+
 ## Import
 
 ```typescript
-import { useParticipantTile } from '@livekit/components-react';
+import { useParticipantTile } from "@livekit/components-react";
 ```
 
+## Remarks
+
+The returned props include many data attributes that are useful for CSS styling purposes because they indicate the state of the participant and the track. For example: `data-lk-audio-muted`<!-- -->, `data-lk-video-muted`<!-- -->, `data-lk-speaking`<!-- -->, `data-lk-local-participant`<!-- -->, `data-lk-source`<!-- -->, `data-lk-facing-mode`<!-- -->.
+
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
+
+{% parameter name="htmlProps" type="React.HTMLAttributes<T>" optional=false %}
+{% /parameter %}
+
+{% parameter name="disableSpeakingIndicator" type="boolean" optional=true %}
+{% /parameter %}
+
+{% parameter name="onParticipantClick" type="(event: ParticipantClickEvent) => void" optional=true %}
+{% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+The track reference to display.
+
+{% /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 %}
+
+{% parameter name="publication" type="TrackPublication" optional=true deprecated=true %}
+{% callout type="caution" variation="compact" %}
+This parameter will be removed in a future version use `trackRef` instead.
+
+{% /callout %}
+{% /parameter %}
+
+{% parameter name="source" 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="{ participant, source, publication, onParticipantClick, disableSpeakingIndicator, htmlProps, }" type="UseParticipantTileProps<T>" optional=false %}
+{% /callout %}
 {% /parameter %}
 
 ## Returns

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

@@ -1,16 +1,35 @@
+---
+{
+  "title": "usePinnedTracks",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/usePinnedTracks.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # usePinnedTracks
 
+The `usePinnedTracks` hook returns a array of the pinned tracks of the current room.
+
 ## Import
 
 ```typescript
-import { usePinnedTracks } from '@livekit/components-react';
+import { usePinnedTracks } from "@livekit/components-react";
+```
+
+## Remarks
+
+To function properly, this hook must be called within a `LayoutContext`<!-- -->.
+
+## Usage
+
+```tsx
+const pinnedTracks = usePinnedTracks();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="layoutContext" type="LayoutContextType" optional=true %}
 {% /parameter %}

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

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

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

@@ -1,16 +1,35 @@
+---
+{
+  "title": "useRemoteParticipant",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useRemoteParticipant.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useRemoteParticipant
 
+The `useRemoteParticipant` hook returns the RemoteParticipant with the given `identity`<!-- -->.
+
 ## Import
 
 ```typescript
-import { useRemoteParticipant } from '@livekit/components-react';
+import { useRemoteParticipant } from "@livekit/components-react";
+```
+
+## Remarks
+
+To optimize performance, you can use the `updateOnlyOn` property to decide on what `ParticipantEvents` the hook updates.
+
+## Usage
+
+```tsx
+const participant = useRemoteParticipant("Russ");
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="identity" type="string" optional=false %}
 {% /parameter %}