@livekit/components-js-docs 0.0.5 → 0.1.0

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

@@ -2,7 +2,7 @@
 
 # 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
 
@@ -10,7 +10,13 @@ The useGridLayout hook tries to select the best layout to fit all tiles. If the
 import { useGridLayout } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { layout } = useGridLayout(gridElement, trackCount);
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -2,20 +2,25 @@
 
 # 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';
 ```
 
-{% 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} /%}
+
+## Parameters
 
-{% 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,29 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useIsMuted
+
+> Warning: This API is now obsolete.
+>
+> This overload will be removed in a future version, pass in trackRef instead.
+
+## Import
+
+```typescript
+import { useIsMuted } from '@livekit/components-react';
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Parameters
+
+{% 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

@@ -2,13 +2,21 @@
 
 # useIsSpeaking
 
+The `useIsSpeaking` hook returns a `boolean` that indicates if the participant is speaking or not.
+
 ## Import
 
 ```typescript
 import { useIsSpeaking } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const isSpeaking = useIsSpeaking(participant);
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -2,13 +2,22 @@
 
 # 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';
 ```
 
-{% 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} /%}
 
 ## Parameters
 

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

@@ -2,7 +2,7 @@
 
 # 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
 
@@ -10,7 +10,13 @@ The useLocalParticipant hook the state of the local participant.
 import { useLocalParticipant } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { localParticipant } = useLocalParticipant();
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -2,13 +2,21 @@
 
 # useLocalParticipantPermissions
 
+The `useLocalParticipantPermissions` hook returns the local participant's permissions.
+
 ## Import
 
 ```typescript
 import { useLocalParticipantPermissions } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { canPublish, canPublishData } = useLocalParticipantPermissions();
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Returns
 

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

@@ -2,6 +2,10 @@
 
 # useMaybeTrackContext
 
+> Warning: This API is now obsolete.
+>
+> `useMaybeTrackContext` has been to `useMaybeTrackRefContext`<!-- -->, use this as a drop in replacement.
+
 Returns a track reference from the `TrackContext` if it exists, otherwise `undefined`<!-- -->.
 
 ## Import

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

@@ -0,0 +1,19 @@
+<!-- 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

@@ -2,13 +2,22 @@
 
 # useMediaDevices
 
+The `useMediaDevices` hook returns the list of media devices of a given kind.
+
 ## Import
 
 ```typescript
 import { useMediaDevices } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const videoDevices = useMediaDevices({ kind: 'videoinput' });
+const audioDevices = useMediaDevices({ kind: 'audioinput' });
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -2,13 +2,23 @@
 
 # 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';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const { devices, activeDeviceId, setActiveMediaDevice } = useMediaDeviceSelect({
+  kind: 'audioinput',
+});
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -2,6 +2,10 @@
 
 # useMediaTrack
 
+> Warning: This API is now obsolete.
+>
+> use `useTrack` instead
+
 ## Import
 
 ```typescript

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

@@ -2,6 +2,10 @@
 
 # useMediaTrackByName
 
+> Warning: This API is now obsolete.
+>
+> This function will be removed in a future version, use `useTrackByName` instead.
+
 ## Import
 
 ```typescript

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

@@ -2,7 +2,7 @@
 
 # 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
 
@@ -10,7 +10,20 @@ The useParticipants hook returns all participants (local and remote) of the curr
 import { useParticipants } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## 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: 1} /%}
 
 ## Parameters
 

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

@@ -2,17 +2,23 @@
 
 # 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';
 ```
 
+## 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
 
-{% parameter name="{ participant, source, publication, onParticipantClick, disableSpeakingIndicator, htmlProps, }" type="UseParticipantTileProps<T>" optional=false %}
+{% parameter name="{ trackRef, participant, source, publication, onParticipantClick, disableSpeakingIndicator, htmlProps, }" type="UseParticipantTileProps<T>" optional=false %}
 {% /parameter %}
 
 ## Returns

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

@@ -2,13 +2,25 @@
 
 # usePinnedTracks
 
+The `usePinnedTracks` hook returns a array of the pinned tracks of the current room.
+
 ## Import
 
 ```typescript
 import { usePinnedTracks } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Remarks
+
+To function properly, this hook must be called within a `LayoutContext`<!-- -->.
+
+## Usage
+
+```tsx
+const pinnedTracks = usePinnedTracks();
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -2,13 +2,25 @@
 
 # useRemoteParticipant
 
+The `useRemoteParticipant` hook returns the RemoteParticipant with the given `identity`<!-- -->.
+
 ## Import
 
 ```typescript
 import { useRemoteParticipant } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## 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: 1} /%}
 
 ## Parameters
 

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

@@ -2,7 +2,7 @@
 
 # useRemoteParticipants
 
-The useRemoteParticipants
+The `useRemoteParticipants` hook returns all remote participants (without the local) of the current room.
 
 ## Import
 
@@ -10,7 +10,20 @@ The useRemoteParticipants
 import { useRemoteParticipants } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## 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: 1} /%}
 
 ## Parameters
 

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

@@ -2,7 +2,7 @@
 
 # useSortedParticipants
 
-The useSortedParticipants hook returns the only the active speakers of all participants.
+The `useSortedParticipants` hook returns the participants sorted by importance.
 
 ## Import
 

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

@@ -2,7 +2,7 @@
 
 # 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
 
@@ -10,7 +10,13 @@ The useSpeakingParticipants hook returns the only the active speakers of all par
 import { useSpeakingParticipants } from '@livekit/components-react';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const activeSpeakers = useSpeakingParticipants();
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Returns
 

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

@@ -2,13 +2,21 @@
 
 # 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';
 ```
 
-{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+## Usage
+
+```tsx
+const token = useToken(<token-endpoint>, roomName, { userInfo: { identity, name }});
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 1} /%}
 
 ## Parameters
 

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

@@ -0,0 +1,31 @@
+<!-- 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} /%}
+
+## Parameters
+
+{% 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,31 @@
+<!-- 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} /%}
+
+## Parameters
+
+{% 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

@@ -2,7 +2,11 @@
 
 # useTrackContext
 
-Ensures that a track reference is provided via context. If not inside a `TrackContext`<!-- -->, an error is thrown.
+> Warning: This API is now obsolete.
+>
+> `useTrackContext` has been to `useTrackRefContext`<!-- -->, use this as a drop in replacement.
+
+Ensures that a track reference is provided via context. If not inside a `TrackRefContext`<!-- -->, an error is thrown.
 
 ## Import
 

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

@@ -2,27 +2,29 @@
 
 # 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';
 ```
 
-{% 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} /%}
+
+## Parameters
 
-{% 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,29 @@
+<!-- Do not edit this file. It is automatically generated by API Documenter. -->
+
+# useTrackMutedIndicator
+
+> Warning: This API is now obsolete.
+>
+> This overload will be removed in a future version, pass in trackRef instead.
+
+## Import
+
+```typescript
+import { useTrackMutedIndicator } from '@livekit/components-react';
+```
+
+{% partial file="p_usage.md" variables={exampleCount: 0} /%}
+
+## Parameters
+
+{% 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,19 @@
+<!-- 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;
+```