@livekit/components-js-docs 0.0.4 → 0.1.0

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

@@ -19,4 +19,6 @@ import { useEnsureLayoutContext } from '@livekit/components-react';
 
 ## Returns
 
-`LayoutContextType`
+```typescript
+LayoutContextType;
+```

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

@@ -19,4 +19,6 @@ import { useEnsureParticipant } from '@livekit/components-react';
 
 ## Returns
 
-`Participant`
+```typescript
+Participant;
+```

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

@@ -19,4 +19,6 @@ import { useEnsureRoom } from '@livekit/components-react';
 
 ## Returns
 
-`Room`
+```typescript
+Room;
+```

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

@@ -0,0 +1,24 @@
+<!-- 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} /%}
+
+## Parameters
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=true %}
+{% /parameter %}
+
+## Returns
+
+```typescript
+TrackReferenceOrPlaceholder;
+```

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

@@ -2,6 +2,10 @@
 
 # useEnsureTrackReference
 
+> Warning: This API is now obsolete.
+>
+> `useEnsureTrackReference` has been to `useEnsureTrackRef`<!-- -->, use this as a drop in replacement.
+
 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
@@ -19,4 +23,6 @@ import { useEnsureTrackReference } from '@livekit/components-react';
 
 ## Returns
 
-`TrackReferenceOrPlaceholder`
+```typescript
+TrackReferenceOrPlaceholder;
+```

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

@@ -2,19 +2,36 @@
 
 # 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';
 ```
 
-{% 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} /%}
 
 ## Parameters
 
-{% parameter name="{ trackSource, participant, props }" type="UseFocusToggleProps" optional=false %}
+{% parameter name="{ trackRef, trackSource, participant, props }" type="UseFocusToggleProps" optional=false %}
 {% /parameter %}
 
 ## Returns
 
-`{     mergedProps: React.ButtonHTMLAttributes<HTMLButtonElement> & {         className: string;         onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;     };     inFocus: boolean; }`
+```typescript
+{
+    mergedProps: React.ButtonHTMLAttributes<HTMLButtonElement> & {
+        className: string;
+        onClick: (event: React.MouseEvent<HTMLButtonElement, MouseEvent>) => void;
+    };
+    inFocus: boolean;
+}
+```

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
 
@@ -22,4 +28,8 @@ import { useGridLayout } from '@livekit/components-react';
 
 ## Returns
 
-`{     layout: GridLayoutDefinition; }`
+```typescript
+{
+  layout: GridLayoutDefinition;
+}
+```

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

@@ -2,22 +2,29 @@
 
 # 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} /%}
 
-{% parameter name="options" type="UseIsMutedOptions" optional=true %}
+## Parameters
+
+{% parameter name="trackRef" type="TrackReferenceOrPlaceholder" optional=false %}
 {% /parameter %}
 
 ## Returns
 
-`boolean`
+```typescript
+boolean;
+```

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
 
@@ -17,4 +25,6 @@ import { useIsSpeaking } from '@livekit/components-react';
 
 ## Returns
 
-`boolean`
+```typescript
+boolean;
+```

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

@@ -14,4 +14,6 @@ import { useLayoutContext } from '@livekit/components-react';
 
 ## Returns
 
-`LayoutContextType`
+```typescript
+LayoutContextType;
+```

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
 
@@ -17,4 +26,9 @@ import { useLiveKitRoom } from '@livekit/components-react';
 
 ## Returns
 
-`{     room: Room | undefined;     htmlProps: HTMLAttributes<T>; }`
+```typescript
+{
+  room: Room | undefined;
+  htmlProps: HTMLAttributes<T>;
+}
+```

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
 
@@ -19,4 +25,15 @@ import { useLocalParticipant } from '@livekit/components-react';
 
 ## Returns
 
-`{     isMicrophoneEnabled: boolean;     isScreenShareEnabled: boolean;     isCameraEnabled: boolean;     microphoneTrack: TrackPublication | undefined;     cameraTrack: TrackPublication | undefined;     lastMicrophoneError: Error | undefined;     lastCameraError: Error | undefined;     localParticipant: LocalParticipant; }`
+```typescript
+{
+  isMicrophoneEnabled: boolean;
+  isScreenShareEnabled: boolean;
+  isCameraEnabled: boolean;
+  microphoneTrack: TrackPublication | undefined;
+  cameraTrack: TrackPublication | undefined;
+  lastMicrophoneError: Error | undefined;
+  lastCameraError: Error | undefined;
+  localParticipant: LocalParticipant;
+}
+```

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

@@ -2,14 +2,24 @@
 
 # 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
 
-`import("livekit-client/dist/src/proto/livekit_models_pb").ParticipantPermission | undefined`
+```typescript
+import('livekit-client/dist/src/proto/livekit_models_pb').ParticipantPermission | undefined;
+```

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

@@ -14,4 +14,6 @@ import { useMaybeLayoutContext } from '@livekit/components-react';
 
 ## Returns
 
-`LayoutContextType | undefined`
+```typescript
+LayoutContextType | undefined;
+```

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

@@ -14,4 +14,6 @@ import { useMaybeParticipantContext } from '@livekit/components-react';
 
 ## Returns
 
-`Participant | undefined`
+```typescript
+Participant | undefined;
+```

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

@@ -14,4 +14,6 @@ import { useMaybeRoomContext } from '@livekit/components-react';
 
 ## Returns
 
-`Room | undefined`
+```typescript
+Room | undefined;
+```

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
@@ -14,4 +18,6 @@ import { useMaybeTrackContext } from '@livekit/components-react';
 
 ## Returns
 
-`TrackReferenceOrPlaceholder | undefined`
+```typescript
+TrackReferenceOrPlaceholder | undefined;
+```

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
 
@@ -19,4 +28,6 @@ import { useMediaDevices } from '@livekit/components-react';
 
 ## Returns
 
-`MediaDeviceInfo[]`
+```typescript
+MediaDeviceInfo[]
+```

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
 
@@ -17,4 +27,11 @@ import { useMediaDeviceSelect } from '@livekit/components-react';
 
 ## Returns
 
-`{     devices: MediaDeviceInfo[];     className: string;     activeDeviceId: string;     setActiveMediaDevice: (id: string, options?: import("@livekit/components-core").SetMediaDeviceOptions | undefined) => Promise<void>; }`
+```typescript
+{
+    devices: MediaDeviceInfo[];
+    className: string;
+    activeDeviceId: string;
+    setActiveMediaDevice: (id: string, options?: import("@livekit/components-core").SetMediaDeviceOptions | undefined) => Promise<void>;
+}
+```

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

@@ -2,6 +2,10 @@
 
 # useMediaTrack
 
+> Warning: This API is now obsolete.
+>
+> use `useTrack` instead
+
 ## Import
 
 ```typescript
@@ -23,4 +27,12 @@ import { useMediaTrack } from '@livekit/components-react';
 
 ## Returns
 
-`{     publication: import("livekit-client").TrackPublication | undefined;     isMuted: boolean | undefined;     isSubscribed: boolean | undefined;     track: import("livekit-client").Track | undefined;     elementProps: React.HTMLAttributes<HTMLElement>; }`
+```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/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
@@ -23,4 +27,12 @@ import { useMediaTrackByName } from '@livekit/components-react';
 
 ## Returns
 
-`{     publication: import("livekit-client").TrackPublication | undefined;     isMuted: boolean | undefined;     isSubscribed: boolean | undefined;     track: import("livekit-client").Track | undefined;     elementProps: import("react").HTMLAttributes<HTMLElement>; }`
+```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/useparticipantcontext.md

@@ -14,4 +14,6 @@ import { useParticipantContext } from '@livekit/components-react';
 
 ## Returns
 
-`Participant`
+```typescript
+Participant;
+```

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

@@ -17,4 +17,10 @@ import { useParticipantInfo } from '@livekit/components-react';
 
 ## Returns
 
-`{     identity: string;     name: string | undefined;     metadata: string | undefined; }`
+```typescript
+{
+  identity: string;
+  name: string | undefined;
+  metadata: string | undefined;
+}
+```

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

@@ -17,4 +17,6 @@ import { useParticipantPermissions } from '@livekit/components-react';
 
 ## Returns
 
-`import("livekit-client/dist/src/proto/livekit_models_pb").ParticipantPermission | undefined`
+```typescript
+import('livekit-client/dist/src/proto/livekit_models_pb').ParticipantPermission | undefined;
+```

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
 
@@ -19,4 +32,6 @@ import { useParticipants } from '@livekit/components-react';
 
 ## Returns
 
-`(import("livekit-client").RemoteParticipant | import("livekit-client").LocalParticipant)[]`
+```typescript
+(import("livekit-client").RemoteParticipant | import("livekit-client").LocalParticipant)[]
+```

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

@@ -2,19 +2,29 @@
 
 # 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
 
-`{     elementProps: React.HTMLAttributes<T>; }`
+```typescript
+{
+  elementProps: React.HTMLAttributes<T>;
+}
+```