@livekit/components-js-docs 0.0.5 → 0.1.1

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

@@ -1,18 +1,38 @@
+---
+{
+  "title": "useRemoteParticipants",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useRemoteParticipants.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useRemoteParticipants
 
-The useRemoteParticipants
+The `useRemoteParticipants` hook returns all remote participants (without the local) of the current room.
 
 ## Import
 
 ```typescript
-import { useRemoteParticipants } from '@livekit/components-react';
+import { useRemoteParticipants } 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 = useRemoteParticipants();
+<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="UseRemoteParticipantsOptions" optional=true %}
 {% /parameter %}

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

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

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

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

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

@@ -1,18 +1,25 @@
+---
+{
+  "title": "useSortedParticipants",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useSortedParticipants.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useSortedParticipants
 
-The useSortedParticipants hook returns the only the active speakers of all participants.
+The `useSortedParticipants` hook returns the participants sorted by importance.
 
 ## Import
 
 ```typescript
-import { useSortedParticipants } from '@livekit/components-react';
+import { useSortedParticipants } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="participants" type="Array<Participant>" optional=false %}
 {% /parameter %}

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

@@ -1,16 +1,29 @@
+---
+{
+  "title": "useSpeakingParticipants",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useSpeakingParticipants.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useSpeakingParticipants
 
-The useSpeakingParticipants hook returns the only the active speakers of all participants.
+The `useSpeakingParticipants` hook returns the only the active speakers of all participants.
 
 ## Import
 
 ```typescript
-import { useSpeakingParticipants } from '@livekit/components-react';
+import { useSpeakingParticipants } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const activeSpeakers = useSpeakingParticipants();
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Returns
 

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

@@ -1,16 +1,31 @@
+---
+{
+  "title": "useToken",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useToken.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useToken
 
+The `useToken` hook fetches a token from the given token endpoint with the given user info.
+
 ## Import
 
 ```typescript
-import { useToken } from '@livekit/components-react';
+import { useToken } from "@livekit/components-react";
+```
+
+## Usage
+
+```tsx
+const token = useToken(<token-endpoint>, roomName, { userInfo: { identity, name }});
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="roomName" type="string" optional=false %}
 {% /parameter %}

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

@@ -0,0 +1,38 @@
+---
+{
+  "title": "useTrack",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useTrack.ts"
+}
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useTrack
+
+## Import
+
+```typescript
+import { useTrack } from "@livekit/components-react";
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Properties
+
+{% parameter name="trackRef" type="TrackIdentifier" optional=false %}
+{% /parameter %}
+
+{% parameter name="options" type="UseTrackOptions" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+{
+  publication: import("livekit-client").TrackPublication | undefined;
+  isMuted: boolean | undefined;
+  isSubscribed: boolean | undefined;
+  track: import("livekit-client").Track | undefined;
+  elementProps: React.HTMLAttributes<HTMLElement>;
+}
+```

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

@@ -0,0 +1,38 @@
+---
+{
+  "title": "useTrackByName",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useTrackByName.ts"
+}
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useTrackByName
+
+## Import
+
+```typescript
+import { useTrackByName } from "@livekit/components-react";
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Properties
+
+{% parameter name="options" type="UseMediaTrackOptions" optional=true %}
+{% /parameter %}
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+{
+  publication: import("livekit-client").TrackPublication | undefined;
+  isMuted: boolean | undefined;
+  isSubscribed: boolean | undefined;
+  track: import("livekit-client").Track | undefined;
+  elementProps: import("react").HTMLAttributes<HTMLElement>;
+}
+```

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

@@ -1,13 +1,28 @@
+---
+{
+  "title": "useTrackContext",
+  "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. -->
 
 # useTrackContext
 
-Ensures that a track reference is provided via context. If not inside a `TrackContext`<!-- -->, an error is thrown.
+{% callout type="caution" variation="normal" %}
+
+This API is deprecated:
+
+`useTrackContext` has been renamed to `useTrackRefContext`<!-- -->, use this as a drop in replacement.
+
+{% /callout %}
+
+Ensures that a track reference is provided via context. If not inside a `TrackRefContext`<!-- -->, an error is thrown.
 
 ## Import
 
 ```typescript
-import { useTrackContext } from '@livekit/components-react';
+import { useTrackContext } from "@livekit/components-react";
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 0} /%}

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

@@ -1,28 +1,37 @@
+---
+{
+  "title": "useTrackMutedIndicator",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useTrackMutedIndicator.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useTrackMutedIndicator
 
+The `useTrackMutedIndicator` hook is used to implement the `TrackMutedIndicator` component and returns the muted state of the given track.
+
 ## Import
 
 ```typescript
-import { useTrackMutedIndicator } from '@livekit/components-react';
+import { useTrackMutedIndicator } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
 
-## Parameters
+```tsx
+const { isMuted } = useTrackMutedIndicator(trackRef);
+```
 
-{% parameter name="source" type="Track.Source" optional=false %}
-{% /parameter %}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
+
+## Properties
 
-{% parameter name="options" type="UseTrackMutedIndicatorOptions" optional=true %}
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
 {% /parameter %}
 
 ## Returns
 
 ```typescript
-{
-  isMuted: boolean;
-  className: string;
-}
+TrackMutedIndicatorReturnType;
 ```

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

@@ -0,0 +1,40 @@
+---
+{
+  "title": "useTrackMutedIndicator",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useTrackMutedIndicator.ts"
+}
+---
+
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useTrackMutedIndicator
+
+{% 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 { useTrackMutedIndicator } 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="UseTrackMutedIndicatorOptions" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+TrackMutedIndicatorReturnType;
+```

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

@@ -0,0 +1,26 @@
+---
+{
+  "title": "useTrackRefContext",
+  "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. -->
+
+# useTrackRefContext
+
+Ensures that a track reference is provided via context. If not inside a `TrackRefContext`<!-- -->, an error is thrown.
+
+## Import
+
+```typescript
+import { useTrackRefContext } from "@livekit/components-react";
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Returns
+
+```typescript
+TrackReferenceOrPlaceholder;
+```

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

@@ -1,3 +1,10 @@
+---
+{
+  "title": "useTracks",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useTracks.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useTracks
@@ -7,7 +14,7 @@ The `useTracks` hook returns an array of `TrackReference` or `TrackReferenceOrPl
 ## Import
 
 ```typescript
-import { useTracks } from '@livekit/components-react';
+import { useTracks } from "@livekit/components-react";
 ```
 
 ## Usage Example 1
@@ -23,13 +30,13 @@ const trackReferences: TrackReference[] = useTracks([Track.Source.Camera]);
 // Return all subscribed camera tracks as well as placeholders for
 // participants without a camera subscription.
 const trackReferencesWithPlaceholders: TrackReferenceOrPlaceholder[] = useTracks([
-  { source: Track.Source.Camera, withPlaceholder: true },
+  { source: Track.Source.Camera, withPlaceholder: true }
 ]);
 ```
 
 {% partial file="p_usage.md" variables={exampleCount: 2} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="options" type="UseTracksOptions" optional=true %}
 {% /parameter %}

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

@@ -1,19 +1,30 @@
+---
+{
+  "title": "useTrackToggle",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useTrackToggle.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useTrackToggle
 
+The `useTrackToggle` hook is used to implement the `TrackToggle` component and returns state and functionality of the given track.
+
 ## Import
 
 ```typescript
-import { useTrackToggle } from '@livekit/components-react';
+import { useTrackToggle } from "@livekit/components-react";
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
 
-## Parameters
+```tsx
+const { buttonProps, enabled } = useTrackToggle(trackRef);
+return <button {...buttonProps}>{enabled ? "disable" : "enable"}</button>;
+```
 
-{% parameter name="{ source, onChange, initialState, captureOptions, ...rest }" type="UseTrackToggleProps<T>" optional=false %}
-{% /parameter %}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Returns
 

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

@@ -1,22 +1,36 @@
+---
+{
+  "title": "useVisualStableUpdate",
+  "linkToSource": "https://github.com/livekit/components-js/blob/main/packages/react/src/hooks/useVisualStableUpdate.ts"
+}
+---
+
 <!-- Do not edit this file. It is automatically generated by API Documenter. -->
 
 # useVisualStableUpdate
 
-> This API is provided as a preview for developers and may change based on feedback that we receive. Do not use this API in a production environment.
-
-The useVisualStableUpdate hook tries to keep visual updates of the TackBundles array to a minimum, while still trying to display important tiles such as speaking participants or screen shares.
-
-Updating works with pagination. For example, if a participant starts speaking on the second page, they will be moved to the first page by replacing the least active/interesting participant on the first page.
+The `useVisualStableUpdate` hook is used to prevent visually jarring jumps and shifts of elements in an array. The algorithm only starts to update when there are more items than visually fit on a page. If this is the case, it will make sure that speaking participants move to the first page and are always visible.
 
 ## Import
 
 ```typescript
-import { useVisualStableUpdate } from '@livekit/components-react';
+import { useVisualStableUpdate } from "@livekit/components-react";
+```
+
+## Remarks
+
+Updating the array can occur because attendees leave or join a room, or because they mute/unmute or start speaking. The hook is used for the `GridLayout` and `CarouselLayout` components.
+
+## Usage
+
+```tsx
+const trackRefs = useTracks();
+const updatedTrackRefs = useVisualStableUpdate(trackRefs, itemPerPage);
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
-## Parameters
+## Properties
 
 {% parameter name="maxItemsOnPage" type="number" optional=false %}
 {% /parameter %}