# React SDK for Zocks.io

`@zocks-communications/client-sdk-react` is the official React SDK for [Zocks.io](https://zocks.io). With this SDK, you
can quickly integrate functionality provided by Zocks.io into your React application. The SDK is built on top of the
[Javascript Zocks.io SDK](https://www.npmjs.com/package/@zocks-communications/client-sdk-js)

The SDK is a collection of hooks and standard components. The components are highly customizable and extendable via both
CSS and render props. Hooks are provided for using the SDK in headless mode.

## Docs

Docs are available at https://docs.zocks.io

[React SDK Reference](https://docs.zocks.io/category/react)

## Installation

### Yarn

```shell
yarn add @zocks-communications/client-sdk-react
```

### npm

```shell
npm install @zocks-communications/client-sdk-react --save
```

# Usage

## Example

A simple meeting application can be created as follows:

`Meeting.tsx` (_accountId_ and _apiBaseUrl_ should be filled)

```typescript jsx
import {
    useZocksActions,
    useZocksSession,
    useLeaveOnUnload,
    JoinPage,
    Participants,
    RoomControls
} from '@zocks-communications/client-sdk-react'

export const Meeting = () => {
    const {sessionActions, localMediaActions} = useZocksActions({accountId: '{accountId}'})
    useLeaveOnUnload(sessionActions.leave)

    const {localParticipantIsConnected} = useZocksSession()

    return (
        <div className='meeting'>
            {!localParticipantIsConnected ? (
                <JoinPage createRoomAction={sessionActions.createRoom}
                          joinAction={sessionActions.join}
                />
            ) : (
                <>
                    <RoomControls mediaActions={localMediaActions} leaveAction={sessionActions.leave}/>
                    <Participants/>
                </>
            )}
        </div>
    )
}
```

Import the global library CSS and wrap your component into `ZocksProvider`

`App.tsx`

```typescript jsx
/* ... */
import '@zocks-communications/client-sdk-react/dist/zocks-client-sdk-react.css'

const App: React.FC = () => {
    return (
        <ZocksProvider>
            <Meeting/>
        </ZocksProvider>
    )
}
```

Then, simply run the application, and the meeting app should start.

## Styling

Styling can be done either via CSS modules or by overwriting styles in a global CSS. This documentation contains related
CSS classes for the different components.

* When styling via CSS modules, simply the related CSS classes have to be overwritten. Most components implement
  the `StyledComponent` interface, which has a single `styles` property. CSS modules and overwritten module styles are
  passed down to the components in this prop.
    * The passed styles are merged with the module styles by the `getMergedClassNames` utility function.
    * The CSS class names are retrieved from the merged styles by the `getClassName` utility function.
* When styling via global CSS, the related CSS classes have to be prefixed with `zocks__`. For example, when overwriting
  the `participant__name` class this way, `zocks__participant__name` has to be overwritten.

## Component customization

Most components can be customized via component render props. This means that specific parts of the component can be
switched, hidden, or components can be extended with new functionality. Customizable components have a `components`
property, which contains the render props. Interchangeable parts of components are described in the [component
documentation](#components), where applicable.

## Hooks

#### useZocksActions

This hook is used for accessing session, local media and chat related actions. The actions automatically handle joining
to a session,
processing events, publishing audio, video or screen share tracks, and more.

The hook also exposes the low-level Zocks Session after connecting for more fine-grained control over the session if
necessary, for example for custom event handling.

Parameters:

|   Parameter   |            Type             | Description              |
|:-------------:|:---------------------------:|--------------------------|
| `zocksConfig` | [ZocksConfig](#zocksconfig) | The Zocks configuration. |

Returns a [ZocksActions](#ZocksActions) object. For more detail on the specific actions, see the corresponding model
objects.

|        Property        |                          Type                           | Description                    |
|:----------------------:|:-------------------------------------------------------:|--------------------------------|
|    `sessionActions`    |       [ZocksSessionActions](#zockssessionactions)       | Session related actions.       |
|  `localMediaActions`   |         [ZocksMediaActions](#zocksmediaactions)         | Local media related actions.   |
|     `chatActions`      |          [ZocksChatActions](#zockschatactions)          | Chat related actions.          |
| `transcriptionActions` | [ZocksTranscriptionActions](#zockstranscriptionactions) | Transcription related actions. |
|       `session`        |                Session &#124; undefined                 | The current Zocks session.     |

---

#### useZocksSession

Provides state data about the current session.

Returns:

|           Property            |                  Type                   | Description                                                                       |
|:-----------------------------:|:---------------------------------------:|-----------------------------------------------------------------------------------|
|           `roomId`            |           string &#124; null            | Current session room identifier.                                                  |
|          `roomName`           |           string &#124; null            | Current session room name.                                                        |
|        `sessionState`         |              SessionState               | Session state.                                                                    |
|      `localParticipant`       |  [ParticipantModel](#participantmodel)  | Local participant.                                                                |
|     `remoteParticipants`      | [ParticipantModel](#participantmodel)[] | Remote participants.                                                              |
|        `isConnecting`         |                 boolean                 | Flag indicating if connection is in progress or not.                              |
| `localParticipantIsConnected` |                 boolean                 | Flag indicating if the local participant is connected and able to publish tracks. |

---

#### useLocalMedia

Provides local media stream capabilities. Primarily used for creating join page experiences. The local audio/video
streams are completely separate from the tracks published in an active session.

Parameters:

|        Parameter        |  Type   | Description                                                     |
|:-----------------------:|:-------:|-----------------------------------------------------------------|
| `videoEnabledByDefault` | boolean | Optional. If true, starts the local video stream automatically. |
| `audioEnabledByDefault` | boolean | Optional. If true, starts the local audio stream automatically. |

Returns:

|         Property         |                  Type                  | Description                                                    |
|:------------------------:|:--------------------------------------:|----------------------------------------------------------------|
|  `currentAudioDeviceId`  |           string &#124; null           | The currently selected audio device, if any.                   |
|  `currentVideoDeviceId`  |           string &#124; null           | The currently selected video device, if any.                   |
|    `localAudioStream`    |   LocalMediaStream &#124; undefined    | The currently active local audio stream, if there is one.      |
|    `localVideoStream`    |   LocalMediaStream &#124; undefined    | The currently active local video stream, if there is one.      |
|  `videoStreamIsLoading`  |                boolean                 | True while the local video stream is loading, false otherwise. |
| `toggleLocalAudioStream` |               () => void               | Turns on or off the currently selected local audio stream.     |
| `toggleLocalVideoStream` |               () => void               | Turns on or off the currently selected local video stream.     |
|   `selectAudioDevice`    | (audioDevice: MediaDeviceInfo) => void | Selects a new audio device for the local audio stream.         |
|   `selectVideoDevice`    | (videoDevice: MediaDeviceInfo) => void | Selects a new video device for the local video stream.         |

---

#### useParticipant

Provides various information primarily for displaying a participant. Can be either the local or a remote participant.

Parameters:

|   Parameter   |                 Type                  | Description                                |
|:-------------:|:-------------------------------------:|--------------------------------------------|
| `participant` | [ParticipantModel](#participantmodel) | The participant model to derive data from. |

Returns:

|       Property        |                      Type                       | Description                                                                                                                      |
|:---------------------:|:-----------------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------|
|         `id`          |               string &#124; null                | Participant identifier.                                                                                                          |
|        `name`         |               string &#124; null                | Participant name.                                                                                                                |
|       `tracks`        | [ParticipantTracksView](#participanttracksview) | Tracks of the participant: all audio and video tracks; the primary audio and video tracks; the screen share track (if available) |
|       `isLocal`       |                     boolean                     | Flag indicating if the participant is the local participant or not.                                                              |
|     `isSpeaking`      |                     boolean                     | Flag indicating if the participant is currently speaking or not.                                                                 |
|   `isScreenSharing`   |                     boolean                     | Flag indicating if the participant is currently sharing their screen or not.                                                     |
|  `connectionQuality`  |                ConnectionQuality                | Connection quality of the participant.                                                                                           |

---

#### useLeaveOnUnload

Convenience hook for leaving the session when the browser window is closed.

Parameters:

| Parameter |    Type    | Description                                                                                                         |
|:---------:|:----------:|---------------------------------------------------------------------------------------------------------------------|
|  `leave`  | () => void | The leave action from [ZocksSessionActions](#zockssessionactions), provided by [useZocksActions](#usezocksactions). |

### Selectors

Hooks usually provide higher level data and functions which can be used without additional configuration. The SDK
also provides a more direct way to access state via selectors. Most of the SDK components use these selectors in
conjunction with the hooks.

Selectors can be used via the `useZocksStore` hook.

Session related selectors:

|                  Selector                   |                    Return type                    | Description                                                                                                                                                                           |
|:-------------------------------------------:|:-------------------------------------------------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|               `selectRoomId`                |                string &#124; null                 | The current room identifier, when connected.                                                                                                                                          |
|            `selectActiveSession`            |             ActiveSession &#124; null             | The current active session identifier, when connected.                                                                                                                                |
|              `selectRoomState`              |                     RoomState                     | The current room state.                                                                                                                                                               |
|            `selectIsConnecting`             |                      boolean                      | Flag indicating if a connection is in progress or not.                                                                                                                                |
|          `selectLocalParticipant`           |       [ParticipantModel](#participantmodel)       | The local participant.                                                                                                                                                                |
|         `selectRemoteParticipants`          |      [ParticipantModel](#participantmodel)[]      | The remote participants.                                                                                                                                                              |
|     `selectLocalParticipantIsConnected`     |                      boolean                      | Flag indicating if the local participant is connected or not.                                                                                                                         |
|        `selectTracksForParticipant`         |  [ParticipantTracksView](#participanttracksview)  | The media tracks of a participant. Requires a [ParticipantModel](#participantmodel) parameter. Usage: `useZocksStore((state) => selectTracksForParticipant(state, participantModel))` |
|           `selectIsScreenSharing`           |                      boolean                      | True if someone is sharing their screen, false otherwise.                                                                                                                             |
|      `selectScreenSharingParticipant`       | [ParticipantModel](#participantmodel) &#124; null | The participant who is currently sharing their screen.                                                                                                                                |
|           `selectActiveSpeakers`            |                     string[]                      | Identifiers of the participants who are currently speaking.                                                                                                                           |
|            `selectLastSpeakers`             |                     string[]                      | Identifiers of the participants who were speaking in the past, ordered by the last time they were active.                                                                             |
| `selectUnmutedRemoteParticipantAudioTracks` |             [TrackView](#trackview)[]             | All subscribed and unmuted audio tracks.                                                                                                                                              |

Media device related selectors:

|           Selector           |    Return type     | Description                                                                                    |
|:----------------------------:|:------------------:|------------------------------------------------------------------------------------------------|
| `selectCurrentAudioDeviceId` | string &#124; null | The currently selected audio device id.                                                        |
| `selectCurrentVideoDeviceId` | string &#124; null | The currently selected video device id.                                                        |
| `selectCurrentMediaDeviceId` | string &#124; null | Has a `MediaDeviceKind` parameter. Returns the currently selected device id based on the kind. |

Virtual background related selectors:

|             Selector             |            Return type            | Description                     |
|:--------------------------------:|:---------------------------------:|---------------------------------|
| `selectCurrentVirtualBackground` | VirtualBackgroundType &#124; null | The current virtual background. |

Transcription related selectors:

|            Selector            |                                     Return type                                     | Description                                                                                                                                                                             |
|:------------------------------:|:-----------------------------------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|  `selectTranscriptionStatus`   |                     [TranscriptionStatus](#transcriptionstatus)                     | The transcription service status.                                                                                                                                                       |
|      `selectTranscripts`       | {[participantId: string]: [ParticipantTranscriptModel](#participanttranscriptmodel) | Transcriptions of all participants.                                                                                                                                                     |
| `selectParticipantTranscripts` |              [ParticipantTranscriptModel](#participanttranscriptmodel)              | Has a `participantId` and a `since` parameter. Selects transcriptions of the given participant. If `since` is given, only transcripts created in the last `since` seconds are selected. |

Intelligence related selectors:

|         Selector         |              Return type              | Description                                                             |
|:------------------------:|:-------------------------------------:|-------------------------------------------------------------------------|
| `selectAIFeaturesStatus` | [AIFeaturesStatus](#aifeaturesstatus) | The AI features status.                                                 |
|    `selectAIFeatures`    |  [AIFeatureModel](#aifeaturemodel)[]  | The AI features of the current session and their corresponding results. |

### Models

#### ZocksConfig

|      Property      |        Type         | Description                                                     |
|:------------------:|:-------------------:|-----------------------------------------------------------------|
|    `accountId`     |       string        | Zocks account identifier.                                       |
|    `apiBaseUrl`    |       string?       | Optional. Zocks API URL. Default is `https://api.zocks.io/v1`   |
|   `aiApiBaseUrl`   |       string?       | Optional. Zocks AI API URL. Default is `https://ai.zocks.io/v1` |
| `apiTokenProvider` | ApiTokenProvider[]? | Optional. API token providers. See the Zocks Javascript SDK.    |
| `apiTokenKeyName`  |       string?       | Optional. API token key name. See the Zocks Javascript SDK.     |
|     `logLevel`     |       string?       | Optional. Zocks log level. See the Zocks Javascript SDK.        |

#### ZocksActions

|        Property        |                          Type                           | Description                                    |
|:----------------------:|:-------------------------------------------------------:|------------------------------------------------|
|    `sessionActions`    |       [ZocksSessionActions](#zockssessionactions)       | Session related actions.                       |
|  `localMediaActions`   |         [ZocksMediaActions](#zocksmediaactions)         | Local media related actions.                   |
|     `chatActions`      |          [ZocksChatActions](#zockschatactions)          | Chat related actions.                          |
| `transcriptionActions` | [ZocksTranscriptionActions](#zockstranscriptionactions) | Transcription related actions.                 |
|      `aiActions`       |            [ZocksAIActions](#zocksaiactions)            | Intelligence related actions.                  |
|       `session`        |                Session &#124; undefined                 | The current session (from the Javascript SDK). |

#### ZocksSessionActions

|   Property   |                        Type                        | Description                                                                      |
|:------------:|:--------------------------------------------------:|----------------------------------------------------------------------------------|
|    `join`    | (joinOptions: [JoinOptions](#joinoptions)) => void | Joins a session by providing a room identifier an optionally additional options. |
|   `leave`    |                     () => void                     | Leaves the session.                                                              |
| `createRoom` |              () => Promise\<RoomInfo>              | Creates a room for future use. Returns information about the created room.       |

#### JoinOptions

|         Property          |                            Type                             | Description                                                                                                  |
|:-------------------------:|:-----------------------------------------------------------:|--------------------------------------------------------------------------------------------------------------|
|         `roomId`          |                           string?                           | Optional. The room identifier to join to.                                                                    |
|        `roomName`         |                           string?                           | Optional. The room name to join to.                                                                          |
|       `autoCreate`        |                          boolean?                           | Optional. If the room should be automatically created or not. Default `false`                                |
|      `autoSubscribe`      |                          boolean?                           | Optional. If `true`, the client will automatically subscribe to published tracks. Default `true`             |
|   `audioDeviceSettings`   |                     MediaTrackSettings?                     | Optional. If provided, the audio device identified by the settings is automatically published after joining. |
|   `videoDeviceSettings`   |                     MediaTrackSettings?                     | Optional. If provided, the video device identified by the settings is automatically published after joining. |
|    `virtualBackground`    |                   VirtualBackgroundType?                    | Optional. If provided, the virtual background will be automatically enabled after joining.                   |
| `virtualBackgroundConfig` |                  VirtualBackgroundConfig?                   | Optional. If provided, the virtual background will be enabled with this configuration after joining.         |
|    `afterJoinCallback`    |                         () => void?                         | Optional. Utility callback function which will be called immediately after successfully joining.             |
|    `joinErrorCallback`    | (e: [ErrorResponse](#errorresponse) &#124; string) => void? | Optional. Utility callback function which will be called with the error as a parameter if joining fails.     |

#### ErrorResponse

| Property |                 Type                  | Description      |
|:--------:|:-------------------------------------:|------------------|
| `errors` | [ValidationError](#validationerror)[] | Errors returned. |

#### ValidationError

|  Property   |  Type   | Description               |
|:-----------:|:-------:|---------------------------|
|  `message`  | string  | Description of the error. |
| `location`  | string? | Location of the error.    |

#### ZocksMediaActions

|         Property         |                                                            Type                                                             | Description                                                                                                         |
|:------------------------:|:---------------------------------------------------------------------------------------------------------------------------:|---------------------------------------------------------------------------------------------------------------------|
|      `publishVideo`      |                                      (mediaTrackSettings?: MediaTrackSettings) => void                                      | Publishes a local video track. Optional `mediaTrackSettings` parameter can be used for specifying the video device. |
|      `publishAudio`      |                                      (mediaTrackSettings?: MediaTrackSettings) => void                                      | Publishes a local audio track. Optional `mediaTrackSettings` parameter can be used for specifying the audio device. |
|   `publishScreenShare`   |                                                         () => void                                                          | Initiates publishing a local screen share track.                                                                    |
|     `unpublishVideo`     |                                      (mediaTrackSettings?: MediaTrackSettings) => void                                      | Unpublishes a local video track.                                                                                    |
|     `unpublishAudio`     |                                      (mediaTrackSettings?: MediaTrackSettings) => void                                      | Unpublishes a local audio track.                                                                                    |
|  `unpublishScreenShare`  |                                                         () => void                                                          | Unpublishes the local screen share track.                                                                           |
|   `switchActiveDevice`   |                                      (kind: MediaDeviceKind, deviceId: string) => void                                      | Switches an audio/video device based on the `kind` and `deviceId` parameters.                                       |
|  `setVirtualBackground`  | (type: VirtualBackgroundType, config?: VirtualBackgroundConfig, mediaTrackSettings?: MediaTrackSettings) => Promise\<void>  | Sets a virtual background.                                                                                          |
| `clearVirtualBackground` |                                                    () => Promise\<void>                                                     | Clears the current virtual background.                                                                              |

#### ZocksTranscriptionActions

|        Property        |                             Type                             | Description                                                                                    |
|:----------------------:|:------------------------------------------------------------:|------------------------------------------------------------------------------------------------|
| `enableTranscription`  |       (config?: TranscriptionConfig) => Promise\<void>       | Enables the transcription service with the specified config.                                   |
| `disableTranscription` |                     () => Promise\<void>                     | Disables the transcription service.                                                            |
|  `startTranscription`  | (audioConstraints?: MediaTrackConstraints) => Promise\<void> | Starts the transcription. If given, uses the audio device specified by the `audioConstraints`. |
|  `stopTranscription`   |                     () => Promise\<void>                     | Stops the transcription.                                                                       |

#### ZocksAIActions

|     Property     |            Type             | Description                                     |
|:----------------:|:---------------------------:|-------------------------------------------------|
| `listAIFeatures` | () => Promise\<AIFeature[]> | Returns the AI features for the current room.   |
| `listAIResults`  | () => Promise\<AIResult[]>  | Returns the AI results for the current session. |

#### TrackModel

|    Property    |  Type   | Description                                         |
|:--------------:|:-------:|-----------------------------------------------------|
|      `id`      | string  | Track identifier.                                   |
|   `isMuted`    | boolean | Flag indicating the muted status of the track.      |
| `isSubscribed` | boolean | Flag indicating the subscribed status of the track. |

#### ParticipantTracksModel

|      Property      |                 Type                  | Description                                                         |
|:------------------:|:-------------------------------------:|---------------------------------------------------------------------|
|   `videoTracks`    |      [TrackModel](#trackmodel)[]      | Video tracks of the participant.                                    |
|   `audioTracks`    |      [TrackModel](#trackmodel)[]      | Audio tracks of the participant.                                    |
| `screenShareTrack` | [TrackModel](#trackmodel) &#124; null | Screen share track of the participant if available, null otherwise. |

#### ParticipantModel

|      Property       |                       Type                        | Description                      |
|:-------------------:|:-------------------------------------------------:|----------------------------------|
|        `id`         |                string &#124; null                 | Participant identifier.          |
|       `name`        |                string &#124; null                 | Participant name.                |
|      `tracks`       | [ParticipantTracksModel](#participanttracksmodel) | Track models of the participant. |
| `connectionQuality` |                 ConnectionQuality                 | Participant connection quality.  |

#### SessionModel

|       Property       |                     Type                     | Description                                                                       |
|:--------------------:|:--------------------------------------------:|-----------------------------------------------------------------------------------|
|       `roomId`       |              string &#124; null              | Session room identifier.                                                          |
|      `roomName`      |              string &#124; null              | Session room name.                                                                |
|    `sessionState`    |                 SessionState                 | Session state.                                                                    |
|    `isConnecting`    |                   boolean                    | Flag indicating if a room connection is in progress or not.                       |
|  `localParticipant`  |    [ParticipantModel](#participantmodel)     | Local participant.                                                                |
| `remoteParticipants` |   [ParticipantModel](#participantmodel)[]    | Remote participants.                                                              |
|      `speakers`      | {activeSpeakers: string[], lastSpeakers: []} | Current and last active speakers for speaker indication and participant ordering. |

Views are primarily used for display purposes and contain derived data from the state. The most important
is [ParticipantView](#participantview), which contains information necessary for displaying a single participant,
including their media
tracks, since tracks themselves are not stored in the state.

#### TrackView

|    Property    |  Type   | Description                                        |
|:--------------:|:-------:|----------------------------------------------------|
|    `track`     |  Track  | The media track which can be attached to elements. |
|   `isMuted`    | boolean | Flag indicating the muted status of the track.     |
| `isSubscribed` | boolean | Flag indicating the muted subscribed of the track. |

#### ParticipantTracksView

|      Property       |                Type                 | Description                                                                                                                                                                                         |
|:-------------------:|:-----------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|    `videoTracks`    |      [TrackView](#trackview)[]      | All available video tracks of the participant.                                                                                                                                                      |
|    `audioTracks`    |      [TrackView](#trackview)[]      | All available audio tracks of the participant.                                                                                                                                                      |
| `primaryVideoTrack` | [TrackView](#trackview) &#124; null | The first subscribed and unmuted video track of the participant. If there is no such video track, then the first video track of the participant. If the participant has no video tracks, then null. |
| `primaryAudioTrack` | [TrackView](#trackview) &#124; null | The first subscribed and unmuted audio track of the participant. If there is no such audio track, then the first audio track of the participant. If the participant has no audio tracks, then null. |
| `screenShareTrack`  | [TrackView](#trackview) &#124; null | The screen share track of the participant if available, null otherwise.                                                                                                                             |

#### ParticipantView

|      Property       |                      Type                       | Description                                                                  |
|:-------------------:|:-----------------------------------------------:|------------------------------------------------------------------------------|
|        `id`         |               string &#124; null                | Participant identifier.                                                      |
|       `name`        |               string &#124; null                | Participant name.                                                            |
|      `tracks`       | [ParticipantTracksView](#participanttracksview) | Tracks of the participant.                                                   |
|      `isLocal`      |                     boolean                     | Flag indicating if the participant is the local participant or not.          |
|    `isSpeaking`     |                     boolean                     | Flag indicating if the participant is currently speaking or not.             |
|  `isScreenSharing`  |                     boolean                     | Flag indicating if the participant is currently sharing their screen or not. |
| `connectionQuality` |                ConnectionQuality                | Connection quality of the participant.                                       |

#### TranscriptionStatus

|         Property          |  Type   | Description                                                                    |
|:-------------------------:|:-------:|--------------------------------------------------------------------------------|
|     `serviceEnabled`      | boolean | Indicates whether the service is enabled or not.                               |
|     `serviceLoading`      | boolean | Indicates whether the service is loading or not.                               |
|       `autoEnabled`       | boolean | When the service is enabled, indicates if it was automatically enabled or not. |
|  `displayTranscriptions`  | boolean | Indicates whether transcriptions should be displayed or not.                   |
| `transcriptionInProgress` | boolean | Indicates whether a local transcription is in progress or not.                 |

#### ParticipantTranscriptModel

|      Property       |              Type               | Description                                                          |
|:-------------------:|:-------------------------------:|----------------------------------------------------------------------|
| `finalTranscripts`  |      TranscriptionResult[]      | All final transcriptions results of the participant.                 |
| `partialTranscript` | TranscriptionResult &#124; null | The current partial transcription result of the participant, if any. |

#### AIFeaturesStatus

Enum. Possible values are:

- `INITIAL`
- `IDLE`
- `LOADING`
- `SUCCESS`
- `ERROR`

#### AIFeatureModel

|            Property            |    Type    | Description                              |
|:------------------------------:|:----------:|------------------------------------------|
| \<all properties of AIFeature> |            |                                          |
|           `results`            | AIResult[] | The AI results belonging to the feature. |

## Chat-related hooks

#### useChat

Convenience hook for all chat related actions and data.

Parameters:

|   Parameter   |                 Type                  | Description                                                                                           |
|:-------------:|:-------------------------------------:|-------------------------------------------------------------------------------------------------------|
| `chatActions` | [ZocksChatActions](#zockschatactions) | The chat actions from [ZocksActions](#ZocksActions), provided by [useZocksActions](#usezocksactions). |

Returns:

|        Property         |                                                                     Type                                                                     | Description                                                                                                             |
|:-----------------------:|:--------------------------------------------------------------------------------------------------------------------------------------------:|-------------------------------------------------------------------------------------------------------------------------|
|   `sendPublicMessage`   |                             (message: string, attachment?: [ChatAttachmentModel](#chatattachmentmodel)) => void                              | Sends a public chat message, optionally with an attachment.                                                             |
|  `sendPrivateMessage`   | (message: string, remoteParticipant: [ParticipantModel](#participantmodel), attachment?: [ChatAttachmentModel](#chatattachmentmodel) => void | Sends a private chat message to the specified remote participant, optionally with an attachment.                        |
|   `uploadAttachment`    |                 (file: File, remoteParticipant?: [ParticipantModel](#participantmodel)) => Promise\<string &#124; undefined>                 | Uploads a file attachment, optionally addressed to a remote participant.                                                |
| `getAttachmentLocation` |                                       (attachmentFileId: string) => Promise\<string &#124; undefined>                                        | Provides a download link for a previously uploaded attachment file.                                                     |
|  `publicChatMessages`   |                                                   [ChatMessageModel](#chatmessagemodel)[]                                                    | All public chat messages.                                                                                               |
|  `privateChatMessages`  |                                      {[participantId: string]: [ChatMessageModel](#chatmessagemodel)[]}                                      | Remote participant → chat messages mapping for private chat messages.                                                   |
|   `messageRecipient`    |                                                                    string                                                                    | Currently selected message recipient. Public message recipients are identified by the `PUBLIC_CHAT_RECIPIENT` constant. |

---

#### useNewMessagesFrom

Hook for accessing part of the state which stores remote participants with unread messages for display purposes.

|      Property      |             Type              | Description                                                                                    |
|:------------------:|:-----------------------------:|------------------------------------------------------------------------------------------------|
| `newMessagesFrom`  |           string[]            | Remote participant identifiers with unread messages. Can also contain `PUBLIC_CHAT_RECIPIENT`. |
| `clearMessageFrom` | (messageFrom: string) => void | Remove the given sender from the unread messages list, clearing it from `newMessagesFrom`.     |

### Selectors

Similarly to session related selectors, chat selectors can be used via the `useZocksStore` hook.

|          Selector           |                             Return type                              | Description                                                                                    |
|:---------------------------:|:--------------------------------------------------------------------:|------------------------------------------------------------------------------------------------|
| `selectPublicChatMessages`  |               [ChatMessageModel](#chatmessagemodel)[]                | Public chat messages.                                                                          |
| `selectPrivateChatMessages` | { [participantId: string]: [ChatMessageModel](#chatmessagemodel)[] } | Private chat messages.                                                                         |
|  `selectMessageRecipient`   |                                string                                | Current message recipient.                                                                     |
|   `selectNewMessagesFrom`   |                               string[]                               | Remote participant identifiers with unread messages. Can also contain `PUBLIC_CHAT_RECIPIENT`. |

### Models

#### ZocksChatActions

|        Property         |                                                                               Type                                                                               | Description                                                                                                             |
|:-----------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------------------------:|-------------------------------------------------------------------------------------------------------------------------|
|   `sendPublicMessage`   |                                       (message: string, attachment?: [ChatAttachmentModel](#chatattachmentmodel)) => void                                        | Sends a public chat message, optionally with an attachment.                                                             |
|  `sendPrivateMessage`   | (message: string, remoteParticipant: [ParticipantModel](#participantmodel), attachment?: ([ChatAttachmentModel](#chatattachmentmodel) &#124; undefined)) => void | Sends a private chat message to the specified remote participant, optionally with an attachment.                        |
|   `uploadAttachment`    |                           (file: File, remoteParticipant?: [ParticipantModel](#participantmodel)) => Promise\<string &#124; undefined>                           | Uploads a file attachment, optionally addressed to a remote participant.                                                |
| `getAttachmentLocation` |                                                 (attachmentFileId: string) => Promise\<string &#124; undefined>                                                  | Provides a download link for a previously uploaded attachment file.                                                     |

#### ChatMessageModel

|   Property   |                     Type                     | Description                                                             |
|:------------:|:--------------------------------------------:|-------------------------------------------------------------------------|
|    `type`    |               ChatMessageType                | Type of the chat message. `PUBLIC` or `PRIVATE`.                        |
|  `message`   |                    string                    | The chat message.                                                       |
| `timestamp`  |                    number                    | Epoch timestamp in seconds, indicates send time.                        |
|    `from`    |          {id: string, name: string}          | Sender identifier and name.                                             |
|     `to`     |         {id: string, name: string}?          | Optional. Recipient identifier and name. Not given for public messages. |
| `attachment` | [ChatAttachmentModel](#chatattachmentmodel)? | Optional. The attachment of the chat message.                           |

#### ChatAttachmentModel

|   Property    |  Type  | Description                                                          |
|:-------------:|:------:|----------------------------------------------------------------------|
|   `fileId`    | string | Identifier of the attached file. Used for generating a download URL. |
|  `fileName`   | string | Name of the attached file.                                           |
|  `fileSize`   | number | File size in bytes.                                                  |
| `contentType` | string | Content type of the attached file.                                   |

There are several other hooks for specialized uses cases in components. Those are described with their corresponding
components.

## Components

### Video

Renders a `video` element from a video stream.

_Props_:

|   Property    |              Type               | Description                 |
|:-------------:|:-------------------------------:|-----------------------------|
| `videoStream` | DOMAttachableStream &#124; null | The video stream to render. |

_Notes_:

* Both tracks provided by [TrackViews](#trackview) and local media streams are compatible with the component.
* Uses the custom `useVideo` hook, which handles automatic attachment and detachment of tracks, and provides a `ref`
  for the video element.

---

### Audio

Renders an `audio` element from an audio stream.

_Props_:

|   Property    |              Type               | Description                 |
|:-------------:|:-------------------------------:|-----------------------------|
| `audioStream` | DOMAttachableStream &#124; null | The audio stream to render. |

_Notes_:

* Both tracks provided by [TrackViews](#trackview) and local media streams are compatible with the component.
* Uses the custom `useAudio` hook, which handles automatic attachment and deattachment of tracks, and provides a `ref`
  for the audio element.

---

### Participant

Renders a single participant. Renders the participant video if available, and optionally the participant audio if
available. Also renders status icons for audio, video, and connection quality.

The component can be optionally extended by a custom component, enriching its functionality.

_Props_ (`ParticipantProps`):

|   Property    |                 Type                  | Description                                                                                |
|:-------------:|:-------------------------------------:|--------------------------------------------------------------------------------------------|
| `participant` | [ParticipantModel](#participantmodel) | The participant model                                                                      |
|  `withAudio`  |               boolean?                | Optional. If true, renders also participant audio.                                         |
| `components`  |        ParticipantComponents?         | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`ParticipantComponents`):

|  Property   |                    Type                    | Description                            |
|:-----------:|:------------------------------------------:|----------------------------------------|
| `Extension` | ComponentType\<ParticipantExtensionProps>? | Participant extension. Default: `null` |

_Extension props_ (`ParticipantExtensionProps`):

|      Property       |        Type        | Description                                                       |
|:-------------------:|:------------------:|-------------------------------------------------------------------|
|   `participantId`   | string &#124; null | Participant identifier                                            |
|  `participantName`  | string &#124; null | Participant name                                                  |
|      `isLocal`      |      boolean       | True if the participant is the local participant, false otherwise |
| `connectionQuality` | ConnectionQuality  | Connection quality                                                |
|    `isSpeaking`     |      boolean       | True if the participant is currently speaking, false otherwise    |
|   `videoIsMuted`    |      boolean       | True if the participant does not have video                       |
|   `audioIsMuted`    |      boolean       | True if the participant does not have audio                       |
|  `isScreenSharing`  |      boolean       | True if the participant is sharing their screen                   |

_Related CSS classes_:

- `participant`
- `participant__name`
- `participant__video-container`
- `participant__video-container--speaking`
- `participant__video-container--local`
- `participant__avatar`
- `participant__status-icons`
- `participant__no-video-icon`
- `participant__no-audio-icon`
- `participant__unknown-quality-icon`
- `participant__poor-quality-icon`
- `participant__good-quality-icon`
- `participant__excellent-quality-icon`

---

### ScreenShare

Simple component rendering a screen share video.

_Props_ (`ScreenShareProps`):

|   Property    |                 Type                  | Description           |
|:-------------:|:-------------------------------------:|-----------------------|
| `participant` | [ParticipantModel](#participantmodel) | The participant model |

_Related CSS classes_:

- `screen-share`

---

### ParticipantsGridView

Renders all participants in a grid, with paging. The grid size changes based on the number of displayed participants.
Currently, the maximum grid is 5x5.

By default, participants are rendered with the `Participant` component, but the participant renderer can be changed.

_Props_ (`MultipleParticipantViewProps`):

|   Property   |                Type                | Description                                                                                |
|:------------:|:----------------------------------:|--------------------------------------------------------------------------------------------|
|  `pageSize`  |              number?               | Optional. The maximum number of participants on a single page. Default `25`.               |
| `components` | MultipleParticipantViewComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`MultipleParticipantViewComponents`):

|   Property    |               Type                | Description                                                   |
|:-------------:|:---------------------------------:|---------------------------------------------------------------|
| `Participant` | ComponentType\<ParticipantProps>? | Optional. Single participant renderer. Default: `Participant` |

_Related CSS classes_:

- `participants-grid-view`
- `participants-grid-view__grid`
- `participants-grid-view__button`
- `participants-grid-view__previous-button`
- `participants-grid-view__previous-button-icon`
- `participants-grid-view__next-button`
- `participants-grid-view__next-button-icon`

---

### ParticipantsSpeakerView

Renders the main speaker participant (the participant who is currently speaking, or was the last one speaking), and all
other participants on the side, with paging.

By default, participants are rendered with the `Participant` component, but the participant renderer can be changed.

_Props_ (`MultipleParticipantViewProps`):

|   Property   |                Type                | Description                                                                                |
|:------------:|:----------------------------------:|--------------------------------------------------------------------------------------------|
|  `pageSize`  |              number?               | Optional. The maximum number of participants on a single page. Default `25`.               |
| `components` | MultipleParticipantViewComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`MultipleParticipantViewComponents`):

|   Property    |               Type                | Description                                                   |
|:-------------:|:---------------------------------:|---------------------------------------------------------------|
| `Participant` | ComponentType\<ParticipantProps>? | Optional. Single participant renderer. Default: `Participant` |

_Related CSS classes_:

- `participants-speaker-view`
- `participants-speaker-view__active-speaker`
- `participants-speaker-view__only-speaker`
- `participants-speaker-view__others-container`
- `participants-speaker-view__others`
- `participants-speaker-view__button`
- `participants-speaker-view__previous-button`
- `participants-speaker-view__previous-button-icon`
- `participants-speaker-view__next-button`
- `participants-speaker-view__next-button-icon`

---

### ParticipantsScreenShareView

Renders a shared screen, and all participants on the side, with paging.

By default, participants are rendered with the `Participant` component, and the screen share with the `ScreenShare`
component,
but the these renderers can be changed.

_Props_ (`ScreenShareViewProps`):

|   Property   |            Type            | Description                                                                                |
|:------------:|:--------------------------:|--------------------------------------------------------------------------------------------|
|  `pageSize`  |          number?           | Optional. The maximum number of participants on a single page. Default `25`.               |
| `components` | ScreenShareViewComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`ScreenShareViewComponents`):

|   Property    |               Type                | Description                                                   |
|:-------------:|:---------------------------------:|---------------------------------------------------------------|
| `Participant` | ComponentType\<ParticipantProps>? | Optional. Single participant renderer. Default: `Participant` |
| `ScreenShare` | ComponentType\<ParticipantProps>? | Optional. Screen share renderer. Default: `ScreenShare`       |

_Related CSS classes_:

- `participants-screen-share-view`
- `participants-screen-share-view__current-share`
- `participants-screen-share-view__participants-container`
- `participants-screen-share-view__participants`
- `participants-screen-share-view__button`
- `participants-screen-share-view__previous-button`
- `participants-screen-share-view__previous-button-icon`
- `participants-screen-share-view__next-button`
- `participants-screen-share-view__next-button-icon`

---

### ViewSwitcher

Simple component for switching between grid and speaker views. The current view is stored in state, so it can be changed
globally.

_Props_: none

_Notes_:

Has a custom hook, `useViewSwitcher`, which returns the current view (`currentView` property), and a function to change
views (`changeView` property). Possible views are `ParticipantsViewType.Grid` and `ParticipantsViewType.Speaker`

---

### ParticipantAudio

Renders `audio` elements for all unmuted remote participants. Useful for views displaying all participants, so no audio
track has to be individually rendered.

_Props_: none

_Notes_:

Uses the `selectUnmutedRemoteParticipantAudioTracks` selector for retrieving all audio tracks.

---

### Participants

Composite component displaying all participants in the currently selected view, and a view switcher. If a screen share
is going on, then displays the screen share.

_Props_ (`ParticipantsProps`):

|       Property        |          Type           | Description                                                                                      |
|:---------------------:|:-----------------------:|--------------------------------------------------------------------------------------------------|
|    `gridPageSize`     |         number?         | Optional. The maximum number of participants on a single page in grid view. Default `25`.        |
|   `speakerPageSize`   |         number?         | Optional. The maximum number of participants on a single page in speaker view. Default `4`.      |
| `screenSharePageSize` |         number?         | Optional. The maximum number of participants on a single page in screen share view. Default `4`. |
|     `components`      | ParticipantsComponents? | Optional. If given, renders the components given in this prop instead of the default ones.       |

_Components_ (`ParticipantsComponents`):

|   Property    |               Type                | Description                      |
|:-------------:|:---------------------------------:|----------------------------------|
| `Participant` | ComponentType\<ParticipantProps>? | Optional. Participant renderer.  |
| `ScreenShare` | ComponentType\<ParticipantProps>? | Optional. Screen share renderer. |

---

### ParticipantsList

Renders all participants in a dismissible list. Usually used for displaying the complete list of participants in a room,
optionally
with their media status.

_Props_ (`ParticipantsListProps`):

|    Property    |                  Type                   | Description                                                                                |
|:--------------:|:---------------------------------------:|--------------------------------------------------------------------------------------------|
| `participants` | [ParticipantModel](#participantmodel)[] | The participants to display.                                                               |
|   `dismiss`    |               () => void?               | Optional. The function to call when dismissing the list.                                   |
|  `components`  |       ParticipantsListComponents?       | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`ParticipantsListComponents`):

|         Property         |                     Type                      | Description                                                                           |
|:------------------------:|:---------------------------------------------:|---------------------------------------------------------------------------------------|
| `ParticipantListElement` | ComponentType\<ParticipantsListElementProps>? | Optional. Participant list element renderer. Default: `SimpleParticipantsListElement` |

_List element props_ (`ParticipantsListElementProps`):

|   Property    |                 Type                  | Description                 |
|:-------------:|:-------------------------------------:|-----------------------------|
| `participant` | [ParticipantModel](#participantmodel) | The participant to display. |

_Related CSS classes_:

- `participants-list`
- `participants-list__participants-container`
- `participants-list__dismiss-button`
- `participants-list__participant-container`
- `participants-list__participant-avatar`
- `participants-list__participant-name`

_Notes_:

Used by `OnlineParticipantsList`.

---

### OnlineParticipantsList

Extended version of `ParticipantsList` via using a custom participant list element renderer. Renders all online
participants
with their status (whether they have audio and video, and whether they are speaking or not).

_Props_ (`OnlineParticipantsListProps`):

|       Property       |                  Type                   | Description                                                                                |
|:--------------------:|:---------------------------------------:|--------------------------------------------------------------------------------------------|
|      `dismiss`       |               () => void?               | Optional. The function to call when dismissing the list.                                   |
|     `components`     |       ParticipantsListComponents?       | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`ParticipantsListComponents`):

|         Property         |                     Type                      | Description                                                                           |
|:------------------------:|:---------------------------------------------:|---------------------------------------------------------------------------------------|
| `ParticipantListElement` | ComponentType\<ParticipantsListElementProps>? | Optional. Participant list element renderer. Default: `SimpleParticipantsListElement` |

---

### ControlButtons

#### AudioControlButton

Mute and unmute for audio streams, and customizable select menu for audio device selection.

_Props_ (`AudioControlButtonProps`):

|        Property         |                    Type                    | Description                                                                                |
|:-----------------------:|:------------------------------------------:|--------------------------------------------------------------------------------------------|
|       `audioIsOn`       |                  boolean                   | Indicates whether audio is currently on or off.                                            |
|      `toggleAudio`      |                 () => void                 | Toggle audio function.                                                                     |
| `onAudioDeviceSelected` | (mediaDeviceInfo: MediaDeviceInfo) => void | Called when a new audio device is selected.                                                |
|      `components`       |        AudioControlMenuComponents?         | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`AudioControlMenuComponents`):

|      Property      |               Type               | Description                                                                     |
|:------------------:|:--------------------------------:|---------------------------------------------------------------------------------|
| `AudioControlMenu` | ComponentType\<SelectMenuProps>? | Optional. Audio device select menu renderer. Default: `DefaultAudioControlMenu` |

_Related CSS classes_:

- `control-button`
- `audio-button-container`
- `audio-button--unmuted`
- `audio-button--muted`

##### DefaultAudioControlMenu

Renders a simple audio device select menu.

_Related CSS classes_:

- `select-button__popover-container`
- `select-button__popover-list`
- `select-button__popover-item`
- `audio-control-menu-item`

##### TranscriptionAudioControlMenu

Creates an audio device select menu renderer for audio device selection and transcription control. When transcription
was not automatically enabled, the transcription control button toggles it.
When transcription is automatically enabled, the control can be used to show or hide displaying transcriptions.

_Parameters_:

|       Property        |                    Type                     | Description                                      |
|:---------------------:|:-------------------------------------------:|--------------------------------------------------|
| `transcriptionStatus` | [TranscriptionStatus](#transcriptionstatus) | The current status of the transcription service. |
| `toggleTranscription` |            () => Promise\<void>             | Toggle transcription function.                   |

_Related CSS classes_:

- `select-button__popover-container`
- `select-button__popover-list`
- `select-button__popover-item`
- `audio-control-menu-item`
- `transcription-menu-item`

#### VideoControlButton

Mute and unmute for video streams, and customizable select menu for video device selection.

_Props_ (`VideoControlButtonProps`):

|        Property         |                    Type                    | Description                                                                                |
|:-----------------------:|:------------------------------------------:|--------------------------------------------------------------------------------------------|
|       `videoIsOn`       |                  boolean                   | Indicates whether audio is currently on or off.                                            |
|    `videoIsLoading`     |                  boolean?                  | Optional. Indicates whether the video is loading or not.                                   |
|      `toggleVideo`      |                 () => void                 | Toggle audio function.                                                                     |
| `onVideoDeviceSelected` | (mediaDeviceInfo: MediaDeviceInfo) => void | Called when a new audio device is selected.                                                |
|      `components`       |        VideoControlMenuComponents?         | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`VideoControlMenuComponents`):

|      Property      |               Type               | Description                                                                     |
|:------------------:|:--------------------------------:|---------------------------------------------------------------------------------|
| `VideoControlMenu` | ComponentType\<SelectMenuProps>? | Optional. Video device select menu renderer. Default: `DefaultVideoControlMenu` |

_Related CSS classes_:

- `video-button-container`
- `control-button`
- `video-button--unmuted`
- `video-button--muted`

##### DefaultVideoControlMenu

Renders a simple video device select menu.

_Related CSS classes_:

- `select-button__popover-container`
- `select-button__popover-list`
- `select-button__popover-item`
- `video-control-menu-item`

##### VirtualBackgroundVideoControlMenu

Creates a video device select menu renderer for video device selection and virtual background control.

_Parameters_:

|          Property          |               Type                | Description                             |
|:--------------------------:|:---------------------------------:|-----------------------------------------|
| `currentVirtualBackground` | VirtualBackgroundType &#124; null | The current virtual background, if any. |
|        `toggleBlur`        |       () => Promise\<void>        | Toggle blur function.                   |

_Related CSS classes_:

- `select-button__popover-container`
- `select-button__popover-list`
- `select-button__popover-item`
- `audio-control-menu-item`
- `blur-menu-item`

#### ScreenShareControlButton

Starts and stops screen share.

_Props_ (`ScreenShareControlButtonProps`):

|       Property       |    Type    | Description                                                             |
|:--------------------:|:----------:|-------------------------------------------------------------------------|
|  `isScreenSharing`   |  boolean   | Indicates whether there is a screen share going on or not.              |
| `isLocalScreenShare` |  boolean   | Indicates whether the local participant is sharing their screen or not. |
| `toggleScreenShare`  | () => void | Toggle screen share function.                                           |

_Related CSS classes_:

- `control-button`
- `screen-share-button`
- `screen-share-button--share-on`
- `screen-share-button--share-off`

#### LeaveButton

Leave button for leaving a meeting.

_Props_ (`LeaveButtonProps`):

|   Property    |    Type    | Description   |
|:-------------:|:----------:|---------------|
| `leaveAction` | () => void | Leave action. |

_Related CSS classes_:

- `control-button`
- `leave-button`

---

### JoinPage

Provides a complete join page experience with switchable audio and video streams, ability to join an existing meeting,
create a new meeting now or create a new meeting for later. Different areas of the join page can be customized via
the `components` prop.

_Props_ (`JoinPageProps`)`:

|        Property         |                        Type                        | Description                                                                                              |
|:-----------------------:|:--------------------------------------------------:|----------------------------------------------------------------------------------------------------------|
|      `joinAction`       | (joinOptions: [JoinOptions](#joinoptions)) => void | Action to call when clicking the Join or New Meeting buttons.                                            |
|   `createRoomAction`    |              () => Promise\<RoomInfo>              | Action to call when clicking the Create New Meeting button.                                              |
|     `initialRoomId`     |                      string?                       | Optional. The initial value of the room input.                                                           |
|  `newMeetingDisabled`   |                      boolean?                      | Optional. Disabled state of the New Meeting button.                                                      |
| `videoEnabledByDefault` |                      boolean?                      | Optional. When true, the local video stream is turned on by default.                                     |
| `audioEnabledByDefault` |                      boolean?                      | Optional. When true, the local audio stream is turned on by default.                                     |
|   `onNewRoomCreated`    |           (roomInfo: RoomInfo) => void?            | Optional. Callback when a new room for later is successfully created. Can be used to display room info.. |
|      `joinOptions`      |       Partial\<[JoinOptions](#joinoptions)>?       | Optional. Join options, see the corresponding model.                                                     |
|      `components`       |                JoinPageComponents?                 | Optional. If given, renders the components given in this prop instead of the default ones.               |

_Components_ (`JoinPageComponents`)`:

|        Property        |                   Type                    | Description                                                                            |
|:----------------------:|:-----------------------------------------:|----------------------------------------------------------------------------------------|
| `JoinPageLocalStreams` | ComponentType\<JoinPageLocalStreamsProps> | Optional. Local streams renderer. Default: `JoinPageLocalStreams`                      |
|    `JoinPageHeader`    |      ComponentType\<JoinPageHeader>       | Optional. Join page header renderer. Default: `JoinPageHeader`                         |
|  `JoinPageRoomInput`   |     ComponentType\<JoinPageRoomInput>     | Optional. Room input renderer for specifying a room. Default: `JoinPageRoomInput`      |
| `JoinPageRoomButtons`  | ComponentType\<JoinPageLocalStreamsProps> | Optional. Room buttons renderer for creating new rooms. Default: `JoinPageRoomButtons` |

Uses the `useJoinpage` custom hook which provides the following properties and functions:

|                Property                |      Type       | Description                                                                                                              |
|:--------------------------------------:|:---------------:|--------------------------------------------------------------------------------------------------------------------------|
|              `localMedia`              | LocalMediaProps | Local media related state and functions.                                                                                 |
|           `afterJoinCleanUp`           |   () => void    | Cleanup function to call after joining a room. Stops local streams and the virtual background on the local video stream. |

_LocalMedia_ (`LocalMediaProps`):

|                Property                 |                    Type                     | Description                                                                                                              |
|:---------------------------------------:|:-------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------|
|      `localMedia.localAudioStream`      |      LocalMediaStream &#124; undefined      | The currently active local audio stream, if there is one.                                                                |
|      `localMedia.localVideoStream`      |      LocalMediaStream &#124; undefined      | The currently active local video stream, if there is one.                                                                |
|  `localMedia.currentVirtualBackground`  |      VirtualBackgroundType &#124; null      | The current virtual background of the local participant, if any.                                                         |
|  `localMedia.virtualBackgroundStream`   |              LocalMediaStream?              | Media stream of the current virtual background, if any.                                                                  |
|    `localMedia.videoStreamIsLoading`    |                   boolean                   | True while the local video stream is loading, false otherwise.                                                           |
|    `localMedia.currentVideoDeviceId`    |             string &#124; null              | The currently selected video device, if any.                                                                             |
|   `localMedia.toggleLocalAudioStream`   |                 () => void                  | Turns on or off the currently selected local audio stream.                                                               |
|   `localMedia.toggleLocalVideoStream`   |                 () => void                  | Turns on or off the currently selected local video stream.                                                               |
|  `localMedia.changeVirtualBackground`   | (VirtualBackgroundType &#124; null) => void | Sets or clears the current virtual background.                                                                           |
| `localMedia.stopLocalVirtualBackground` |                 () => void                  | Stops processing the current virtual background. Can be used for stopping the processing after joining the room.         |
|     `localMedia.selectAudioDevice`      |   (audioDevice: MediaDeviceInfo) => void    | Selects a new audio device for the local audio stream.                                                                   |
|     `localMedia.selectVideoDevice`      |   (videoDevice: MediaDeviceInfo) => void    | Selects a new video device for the local video stream.                                                                   |

Note: this is basically the combination of the `useLocalMedia` and `useLocalVirtualBackgrounds` hooks.

_Related CSS classes_:

- `join-page`
- `join-page__controls`

#### JoinPageLocalStreams

Displays the local streams and their corresponding controls. By default, contains an audio selector and a video selector
with background blur.

_Props_(`JoinPageLocalStreamsProps`):

|     Property      |              Type               | Description                                                                                |
|:-----------------:|:-------------------------------:|--------------------------------------------------------------------------------------------|
|   `localMedia`    |         LocalMediaProps         | Local media related props, provided by the `JoinPage`.                                     |
| `baseJoinOptions` |      Partial\<JoinOptions>      | Join options, used when join functionality is required on this part of the join page.      |
|   `components`    | JoinPageLocalStreamsComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`JoinPageLocalStreamsComponents`)`:

|         Property         |                  Type                   | Description                                                                            |
|:------------------------:|:---------------------------------------:|----------------------------------------------------------------------------------------|
|   `AudioControlButton`   | ComponentType\<AudioControlButtonProps> | Optional. Audio control button renderer. Default: `AudioControlButton`                 |
|   `VideoControlButton`   | ComponentType\<VideoControlButtonProps> | Optional. Video control button renderer. Default: `VideoControlButton`                 |
| `DisabledVideoComponent` |     ComponentType\<StyledComponent>     | Optional. Room input renderer for specifying a room. Default: `DisabledVideoComponent` |
|     `ExtraComponent`     |     ComponentType\<StyledComponent>     | Optional. Room buttons renderer for creating new rooms. Default: `null`                |

_Related CSS classes_:

- `join-page__local-streams`
- `join-page__video-container`
- `join-page__video-preview`
- `join-page__local-stream-buttons`
- `join-page__no-video-icon`

#### JoinPageHeader

Header part of the right side of the join page.

_Related CSS classes_:

- `join-page__header`
- `join-page__header-greetings`
- `join-page__header-meeting-id-info`

#### JoinPageRoomInput

_Props_(`JoinPageRoomInputProps`):

|       Property        |                Type                | Description                                                          |
|:---------------------:|:----------------------------------:|----------------------------------------------------------------------|
|    `initialRoomId`    |               string               | Initial value of the room id.                                        |
|     `joinAction`      | (joinOptions: JoinOptions) => void | Join action.                                                         |
|   `baseJoinOptions`   |       Partial\<JoinOptions>        | Join options.                                                        |
|  `roomIdInputLabel`   |              string?               | Optional. Label for the room id input. Default: `Enter a Meeting ID` |
| `roomIdInputDisabled` |              boolean?              | Optional. Disabled state for the room id input.                      |
|  `roomIdPlaceholder`  |              string?               | Optional. Placeholder for room id input. Default: `Meeting ID`       |
|   `joinButtonLabel`   |              string?               | Optional. Join button label. Default: `Join the Meeting`             |

_Related CSS classes_:

- `join-page__join-room-container`
- `join-page__room-input`
- `join-page__room-input--error`
- `join-page__join-button`
- `join_page__room-input-popover`
- `join-page__room-input-popover-text`
- `join-page__room-input-wrapper`
- `join-page__room-input-select`

#### JoinPageRoomButtons

Contains buttons for joining a new room now, or creating a new room for later.

_Props_(`JoinPageRoomButtonsProps`):

|              Property              |                Type                | Description                                                                               |
|:----------------------------------:|:----------------------------------:|-------------------------------------------------------------------------------------------|
|            `joinAction`            | (joinOptions: JoinOptions) => void | Join action.                                                                              |
|         `createRoomAction`         |     () => Promise\<RoomInfo>?      | Optional. Create room for later action.                                                   |
|         `onNewRoomCreated`         |   (roomInfo: RoomInfo) => void?    | Optional. Called with the room info when successfully creating a new room for later.      |
|         `baseJoinOptions`          |       Partial\<JoinOptions>        | Join options.                                                                             |
|      `joinNewRoomButtonLabel`      |              string?               | Optional. Join new room button label. Default: `Start New Meeting`                        |
| `createNewRoomForLaterButtonLabel` |              string?               | Optional. Create new room for later button label. Default: `Create New Meeting for Later` |
|             `disabled`             |              boolean?              | Optional. Disabled state of the buttons.                                                  |

---

### DeviceSelectButton

Button for listing and selecting media devices.

_Props_(`DeviceSelectButtonProps`):

|      Property      |                    Type                    | Description                                                                                |
|:------------------:|:------------------------------------------:|--------------------------------------------------------------------------------------------|
|    `deviceKind`    |              MediaDeviceKind               | The media device kind.                                                                     |
| `onDeviceSelected` | (mediaDeviceInfo: MediaDeviceInfo) => void | Called when a device is selected.                                                          |
|     `disabled`     |                  boolean?                  | Optional. Disabled state of the button.                                                    |
|    `className`     |                  string?                   | Optional. Additional class for the button.                                                 |
|      `label`       |                  string?                   | Optional. Button label.                                                                    |
|    `components`    |                  string?                   | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_(`DeviceSelectButtonComponents`):

|   Property   |               Type               | Description                                                       |
|:------------:|:--------------------------------:|-------------------------------------------------------------------|
| `SelectMenu` | ComponentType\<SelectMenuProps>? | Optional. The select menu to render. Default: `DefaultSelectMenu` |

_Related CSS classes_:

- `select-button__button-container`
- `select-button__button`
- `select-button__button-icon`
- `select-button__popover-container`
- `select-button__popover-list`
- `select-button__popover-item`

---

### RoomControls

Provides media controls and a leave button for the local participant.

_Props_(`RoomControlsProps`):

|        Property        |                  Type                   | Description                                                                                                                         |
|:----------------------:|:---------------------------------------:|-------------------------------------------------------------------------------------------------------------------------------------|
|     `mediaActions`     | [ZocksMediaActions](#zocksmediaactions) | Actions for controlling the local media. Usually the `mediaActions` from the [useZocksActions](#usezocksactions) hook               |
|     `leaveAction`      |               () => void                | Action to call when clicking the Leave button. Usually the `sessionActions.leave` from the [useZocksActions](#usezocksactions) hook |
| `transcriptionActions` |        ZocksTranscriptionActions        | Actions for controlling transcription. Usually the `transcriptionActions` from the [useZocksActions](#usezocksactions) hook         |
|      `components`      |         RoomControlsComponents?         | Optional. If given, renders the components given in this prop instead of the default ones.                                          |

_Components_(`RoomControlsComponents`):

|          Property          |                      Type                      | Description                                                               |
|:--------------------------:|:----------------------------------------------:|---------------------------------------------------------------------------|
|    `AudioControlButton`    |    ComponentType\<AudioControlButtonProps>?    | Audio control button renderer. Default: `AudioControlButton`              |
|    `VideoControlButton`    |    ComponentType\<VideoControlButtonProps>?    | Video control button renderer. Default: `VideoControlButton`              |
| `ScreenShareControlButton` | ComponentType\<ScreenShareControlButtonProps>? | Screen share control button renderer. Default: `ScreenShareControlButton` |
|       `LeaveButton`        |       ComponentType\<LeaveButtonProps>?        | Leave button renderer. Default: `LeaveButton`                             |
|      `ExtraComponent`      |        ComponentType\<StyledComponent>?        | Extra components renderer. Default: `null`                                |

_Related CSS classes_:

- `room-controls`
- `control-button`
- `audio-select-button`
- `video-select-button`

_Notes_:

Uses the custom hook called `useRoomControls` which provides the following properties and functions. Can be used for
easily creating custom room controls.

|       Property       |                  Type                  | Description                                                           |
|:--------------------:|:--------------------------------------:|-----------------------------------------------------------------------|
|     `audioIsOn`      |                boolean                 | Flag indicating that the local audio stream is published and unmuted. |
|     `videoIsOn`      |                boolean                 | Flag indicating that the local video stream is published and unmuted. |
|  `isScreenSharing`   |                boolean                 | Flag indicating that there is a screen share going on in the room.    |
| `isLocalScreenShare` |                boolean                 | Flag indicating that the local screen share stream is published.      |
|    `toggleAudio`     |               () => void               | Toggles the local audio stream.                                       |
|    `toggleVideo`     |               () => void               | Toggles the local video stream.                                       |
| `toggleScreenShare`  |               () => void               | Toggles the local screen share.                                       |
| `selectAudioDevice`  | (audioDevice: MediaDeviceInfo) => void | Changes the local audio device.                                       |
| `selectVideoDevice`  | (videoDevice: MediaDeviceInfo) => void | Changes the local video device.                                       |

For controlling virtual background, uses the `useVirtualBackgrounds` hook, which provides the following properties and
functions:

|           Property           |                    Type                     | Description                                                      |
|:----------------------------:|:-------------------------------------------:|------------------------------------------------------------------|
|    `availableBackgrounds`    |           VirtualBackgroundType[]           | The available virtual backgrounds.                               |
|  `currentVirtualBackground`  |      VirtualBackgroundType &#124; null      | The current virtual background of the local participant, if any. |
| `virtualBackgroundIsLoading` |                   boolean                   | Flag indicating that the virtual background is loading.          |
|  `changeVirtualBackground`   | (VirtualBackgroundType &#124; null) => void | Sets or clears the current virtual background.                   |

For controlling transcriptions, uses the `useTranscription` hook, which provides the following properties and functions:

|       Property        |                    Type                     | Description                                                                                                                    |
|:---------------------:|:-------------------------------------------:|--------------------------------------------------------------------------------------------------------------------------------|
| `transcriptionStatus` | [TranscriptionStatus](#transcriptionstatus) | Status of the transcription service.                                                                                           |
| `toggleTranscription` |            () => Promise\<void>             | When transcription was not automatically enabled, toggles transcription, otherwise toggles displaying the transcriptions only. |

### VirtualBackgroundSelector

Simple selector for virtual backgrounds. Provides all available virtual backgrounds, and a `None` option for clearing
the background.

_Props_ (`VirtualBackgroundSelectorProps`):

|          Property          |                    Type                     | Description                                    |
|:--------------------------:|:-------------------------------------------:|------------------------------------------------|
|   `availableBackgrounds`   |           VirtualBackgroundType[]           | The available virtual backgrounds.             |
| `currentVirtualBackground` |      VirtualBackgroundType &#124; null      | The current virtual background, if any.        |
| `selectVirtualBackground`  | (VirtualBackgroundType &#124; null) => void | Sets or clears the current virtual background. |
|         `disabled`         |                  boolean?                   | Optional. Disabled property of the selector.   |

_Related CSS classes_:

- `virtual-background-select-container`
- `virtual-background-select-text`
- `virtual-background-select-button`

### TranscriptionDisplay

Displays the transcription of a single participant, with configurable word count and hide delay.
Can be used in a [Participant](#participant) extension.

_Props_:

|    Property     |  Type   | Description                                                                          |
|:---------------:|:-------:|--------------------------------------------------------------------------------------|
| `participantId` | string  | The participant id.                                                                  |
|  `wordsInLine`  | number? | Optional. The number of maximum words per line. Default: `10`                        |
|   `hideDelay`   | number? | Optional. Hides the transcription after the specified delay (in ms). Default: `3000` |

For getting participant transcription data, uses the `useParticipantTranscript` hook, which provides the following
properties:

|            Property             |                    Type                     | Description                                                                                                                        |
|:-------------------------------:|:-------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------|
|      `transcriptionStatus`      | [TranscriptionStatus](#transcriptionstatus) | Status of the transcription service.                                                                                               |
|       `partialTranscript`       |       TranscriptionResult &#124; null       | The current partial transcript of the participant, if any. Can be used for displaying partial results differently than final ones. |
|       `finalTranscripts`        |            TranscriptionResult[]            | The final (stable) transcript results of the participant.                                                                          |

_Related CSS classes_:

- `transcription-display__container`
- `transcription-display__line`

### Intelligence features

Currently, accessing intelligence features can be only done in headless mode, there is no component for presentation in
this SDK.
For accessing AI related data, the `useAIFeatures` hook can be used, which provides the following properties and
functions:

|          Property           |                 Type                  | Description                                                  |
|:---------------------------:|:-------------------------------------:|--------------------------------------------------------------|
|     `aiFeaturesStatus`      | [AIFeaturesStatus](#aifeaturesstatus) | The AI feature status.                                       |
|        `aiFeatures`         |  [AIFeatureModel](#aifeaturemodel)[]  | The AI features and their corresponding results.             |
| `loadAIFeaturesWithResults` |              () => void               | Loads the AI features and results for the current session.   |
|      `resetAIFeatures`      |              () => void               | Clears the AI features and results from the current session. |

## Chat-related components

### Chat input

#### ChatMessageInput

Simple multiline message text area with instant message sending.

_Props_ (`ChatMessageInputProps`):

|        Property        |           Type            | Description                                              |
|:----------------------:|:-------------------------:|----------------------------------------------------------|
|  `currentChatMessage`  |          string           | The current chat message.                                |
| `onChatMessageChanged` | (message: string) => void | Callback fired when the message is changed.              |
|   `placeholderText`    |          string?          | Optional. Placeholder for the text area.                 |
|     `sendMessage`      |        () => void?        | Optional. For message sending from within the component. |

_Related CSS classes_:

- `chat-input__message-textarea`

_Notes_:

The text area `ref` is forwarded for manual focusing capability.

---

#### SendButton

Simple button for sending a chat message.

_Props_ (`SendButtonProps`):

|   Property   |    Type     | Description                               |
|:------------:|:-----------:|-------------------------------------------|
|  `disabled`  |  boolean?   | Optional. Disabled state of the button.   |
|  `onClick`   | () => void? | Optional. Fired when clicking the button. |
| `buttonText` |   string?   | Optional. Text of the button.             |

_Related CSS classes_:

- `chat-input__send-button`

---

#### RecipientSelector

Component for selecting a chat recipient, including public messages.

_Props_ (`RecipientSelectorProps`):

|        Property        |                   Type                   | Description                                                          |
|:----------------------:|:----------------------------------------:|----------------------------------------------------------------------|
| `onRecipientSelected`  |      (recipientId: string) => void       | Called when a new recipient is selected.                             |
|  `remoteParticipants`  | [ParticipantModel](#participantmodel)[]? | Optional. The remote participants.                                   |
|    `selectInfoText`    |                 string?                  | Optional. Additional text for the selector.                          |
| `allParticipantsLabel` |                 string?                  | Optional. Label of the public message recipient. Default: `Everyone` |

_Related CSS classes_:

- `chat-input__recipient-select-container`
- `chat-input__recipient-select`

---

#### EmojiSelector

Emoji selector component with customizable emojis. The emojis are selected from a popover, which is opened and closed
with a button.

_Props_ (`EmojiSelectorProps`):

|      Property       |                      Type                       | Description                                                                    |
|:-------------------:|:-----------------------------------------------:|--------------------------------------------------------------------------------|
|   `onSelectEmoji`   |             (emoji: string) => void             | Called when an emoji is selected.                                              |
|      `emojis`       |                    string[]?                    | Optional. The list of emojis. Default:  `['😂', '👍', '🎉', '😃', '👏']`       |
|  `currentMessage`   |                     string?                     | Optional. The current message. Can be used for additional logic.               |

_Components_:

|   Property   |                     Type                      | Description           |
|:------------:|:---------------------------------------------:|-----------------------|
| `OpenButton` | ComponentType\<EmojiSelectorOpenButtonProps>? | Open button renderer. |

_Props for the open button element_ (`EmojiSelectorOpenButtonElementProps`):

| Property  |    Type    | Description                        |
|:---------:|:----------:|------------------------------------|
| `onClick` | () => void | Called when the button is clicked. |

_Related CSS classes_:

- `emoji-selector__emoji-container`
- `emoji-selector__emoji-button`
- `emoji-selector__open-button`

---

#### AttachmentUploader

Attachment uploader with loading state and customizable file upload button.

_Props_ (`AttachmentUploaderProps`):

|            Property             |                                                     Type                                                     | Description                                                                                                     |
|:-------------------------------:|:------------------------------------------------------------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------|
|       `uploadAttachment`        | (file: File, remoteParticipant?: [ParticipantModel](#participantmodel)) => Promise\<string &#124; undefined> | The upload attachment actions. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions) |
|      `attachmentRecipient`      |                                    [ParticipantModel](#participantmodel)?                                    | Optional. The recipient of the attachment, if any.                                                              |
|   `onAttachmentUploadStarted`   |                                            (file: File) => void?                                             | Optional. Called when file upload is started.                                                                   |
|  `onAttachmentUploadFinished`   |                                    (file: File, fileId: string) => void?                                     | Optional. Called when file upload has finished successfully.                                                    |
|   `onAttachmentUploadFailed`    |                                            (file: File) => void?                                             | Optional. Called when file upload finished with an error.                                                       |

_Components_:

|      Property      |                        Type                         | Description             |
|:------------------:|:---------------------------------------------------:|-------------------------|
| `UploadAttachment` | ComponentType\<UploadAttachmentButtonElementProps>? | Upload button renderer. |

_Props for the open button element_ (`UploadAttachmentButtonElementProps`):

|  Property  |    Type    | Description                             |
|:----------:|:----------:|-----------------------------------------|
| `onClick`  | () => void | Called when the button is clicked.      |
| `disabled` |  boolean?  | Optional. Disabled state of the button. |
| `hasError` |  boolean?  | Optional. Error state of the button.    |

_Related CSS classes_:

- `attachment-uploader__container`
- `attachment-uploader__file-input`

---

#### AttachmentDisplay

Displays an uploaded attachment file before actually sending the chat message with the attachment. Also, able to delete
the attachment.

_Props_ (`AttachmentDisplayProps`):

|            Property            |                     Type                      | Description                                                                            |
|:------------------------------:|:---------------------------------------------:|----------------------------------------------------------------------------------------|
|          `attachment`          | [ChatAttachmentModel](#chatattachmentmodel)?  | Optional. The chat attachment, if any. If there is no attachment, nothing is rendered. |
|      `hasAttachmentError`      |                   boolean?                    | Optional. Flag indicating if there was an error when uploading the attachment.         |
|      `onClearAttachment`       |                  () => void?                  | Optional. Called when clearing the attachment.                                         |

_Components_:

|        Property         |                        Type                        | Description                       |
|:-----------------------:|:--------------------------------------------------:|-----------------------------------|
| `ClearAttachmentButton` | ComponentType\<ClearAttachmentButtonElementProps>? | Clear attachment button renderer. |

_Props for the clear button element_ (`ClearAttachmentButtonElementProps`):

|  Property  |    Type    | Description                             |
|:----------:|:----------:|-----------------------------------------|
| `onClick`  | () => void | Called when the button is clicked.      |

_Related CSS classes_:

- `attachment-display__container`
- `attachment-display__name`
- `attachment-display__error`

---

#### CustomizableChatInput

Composite component utilizing the different input elements for a complete chat input experience.

_Props_ (`ChatInputProps & CustomizableChatInputProps`):

|          Property           |                                                                      Type                                                                      | Description                                                                                       |
|:---------------------------:|:----------------------------------------------------------------------------------------------------------------------------------------------:|---------------------------------------------------------------------------------------------------|
|     `messageRecipient`      |                                                                     string                                                                     | The current recipient.                                                                            |
|    `remoteParticipants`     |                                                    [ParticipantModel](#participantmodel)[]?                                                    | Optional. The remote participants.                                                                |
|    `onRecipientSelected`    |                                                         (recipientId: string) => void?                                                         | Optional. Called when a new recipient is selected.                                                |
|     `sendPublicMessage`     |                              (message: string, attachment?: [ChatAttachmentModel](#chatattachmentmodel)) => void?                              | Optional. Sends a new public message, optionally with an attachment.                              |
|    `sendPrivateMessage`     | (message: string, remoteParticipant: [ParticipantModel](#participantmodel), attachment?: [ChatAttachmentModel](#chatattachmentmodel)) => void? | Optional. Sends a new private private message, optionally with an attachment.                     |
|     `uploadAttachment`      |                  (file: File, remoteParticipant?: [ParticipantModel](#participantmodel)) => Promise<string &#124; undefined>?                  | Optional. Uploads an attachment, optionally with a recipient.                                     |

_Components_:

|      Property      |                   Type                   | Description                                                                             |
|:------------------:|:----------------------------------------:|-----------------------------------------------------------------------------------------|
|  ChatMessageInput  |  ComponentType\<ChatMessageInputProps>?  | Element renderer for customizing the chat input. Default: `ChatMessageInput`            |
|     SendButton     |     ComponentType\<SendButtonProps>?     | Element renderer for customizing the send button. Default: `SendButton`                 |
| RecipientSelector  | ComponentType\<RecipientSelectorProps>?  | Element renderer for customizing the recipient selector. Default: `RecipientSelector`   |
|   EmojiSelector    |   ComponentType\<EmojiSelectorProps>?    | Element renderer for customizing the emoji selector. Default: `EmojiSelector`           |
| AttachmentUploader | ComponentType\<AttachmentUploaderProps>? | Element renderer for customizing the attachment uploader. Default: `AttachmentUploader` |
| AttachmentDisplay  | ComponentType\<AttachmentDisplayProps>?  | Element renderer for customizing the attachment display. Default: `AttachmentDisplay`   |

_Related CSS classes_:

- `chat-input__input-group`
- `chat-input__message-input-container`
- `chat-input__top-bar`
- `chat-input__loader-container`
- `chat-input__loader`

### Chat message

#### ChatMessageWithAvatar

Renders a chat message, optionally with a participant avatar.

_Props_ (`ChatMessageProps & AvatarProps`):

|            Property            |                          Type                          | Description                                                                                                                                        |
|:------------------------------:|:------------------------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------|
|         `chatMessage`          |         [ChatMessageModel](#chatmessagemodel)          | The chat message to display.                                                                                                                       |
|          `showAvatar`          |                        boolean                         | Whether the avatar should be displayed or not.                                                                                                     |
|    `getAttachmentLocation`     | (fileId: string) => Promise\<string &#124; undefined>? | Optional. Function for getting a download URL for an attachment. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions). |

_Components_:

|       Property        |                    Type                     | Description                                                                                    |
|:---------------------:|:-------------------------------------------:|------------------------------------------------------------------------------------------------|
| ChatMessageAttachment | ComponentType\<ChatMessageAttachmentProps>? | Element renderer for customizing how the attachment is displayed. See `ChatMessageAttachment`. |

_Related CSS classes_:

- `chat-message-a__container`
- `chat-message-a__container--sent`
- `chat-message-a__container--received`
- `chat-message-a__message-container`
- `chat-message-a__avatar`
- `chat-message-a__message`

_Notes_:

Used in `SplitChat` for a chat experience with separate threads.

---

#### ChatMessageWithParticipantInfo

Renders a chat message, optionally with additional information about the participants, such as their name..

_Props_ (`ChatMessageProps & InfoProps`):

|            Property            |                          Type                          | Description                                                                                                                                        |
|:------------------------------:|:------------------------------------------------------:|----------------------------------------------------------------------------------------------------------------------------------------------------|
|         `chatMessage`          |         [ChatMessageModel](#chatmessagemodel)          | The chat message to display.                                                                                                                       |
|     `showParticipantInfo`      |                        boolean                         | Whether additional participant information should be displayed or not.                                                                             |
|    `localParticipantLabel`     |                        string?                         | Optional. Name of the local participant. Default: `Me`                                                                                             |
|    `getAttachmentLocation`     | (fileId: string) => Promise\<string &#124; undefined>? | Optional. Function for getting a download URL for an attachment. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions). |

_Components_:

|       Property        |                    Type                     | Description                                                                                    |
|:---------------------:|:-------------------------------------------:|------------------------------------------------------------------------------------------------|
| ChatMessageAttachment | ComponentType\<ChatMessageAttachmentProps>? | Element renderer for customizing how the attachment is displayed. See `ChatMessageAttachment`. |

_Related CSS classes_:

- `chat-message-i__container`
- `chat-message-i__container--sent`
- `chat-message-i__container--received`
- `chat-message-i__message-container`
- `chat-message-i__avatar`
- `chat-message-i__header`
- `chat-message-i__header--public`
- `chat-message-i__header--private`
- `chat-message-i__message`

_Notes_:

Used in `CombinedChat` for a chat experience with a single thread, where differentiating between participants is more
difficult.

---

#### ChatMessageAttachment

Renders a chat attachment in a received chat message with a Download button, so the attachment can be downloaded.

_Props_ (`ChatMessageAttachmentProps`):

|        Property         |                          Type                          | Description                                                                                                                             |
|:-----------------------:|:------------------------------------------------------:|-----------------------------------------------------------------------------------------------------------------------------------------|
|      `attachment`       |      [ChatAttachmentModel](#chatattachmentmodel)       | The attachment to display.                                                                                                              |
| `getAttachmentLocation` | (fileId: string) => Promise\<string &#124; undefined>? | Function for getting a download URL for an attachment. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions) |

_Related CSS classes_:

- `chat-message-attachment__container`
- `chat-message-attachment__name`
- `chat-message-attachment__download-button`
- `chat-message-attachment__hidden-link`

_Notes_:

Uses the custom hook `useChatAttachment`. This hook provides download capabilities with loading indicator and error
handling for simple downloading of attachments via an
anchor tag.

Parameters:

|        Parameter        |                          Type                          | Description                                                                                                                              |
|:-----------------------:|:------------------------------------------------------:|------------------------------------------------------------------------------------------------------------------------------------------|
|      `attachment`       |      [ChatAttachmentModel](#chatattachmentmodel)       | The attachment to display.                                                                                                               |
| `getAttachmentLocation` | (fileId: string) => Promise\<string &#124; undefined>? | Function for getting a download URL for an attachment. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions). |

Returns:

|       Property        |                Type                 | Description                                                                    |
|:---------------------:|:-----------------------------------:|--------------------------------------------------------------------------------|
|      `anchorRef`      | React.RefObject\<HTMLAnchorElement> | `ref` to an invisible anchor tag which is used for downloading the attachment. |
| `downloadAttachment`  |             () => void              | Generates a new download URL and downloads the attachment via that URL         |
| `isAttachmentLoading` |               boolean               | Flag indicating attachment download URL generation is in progress              |
| `hasAttachmentError`  |               boolean               | Flag indicating if there was an error during download URL generation           |
|    `attachmentUrl`    |               string                | The generated download URL for the attachment for display purposes             |

### Full chat experience

#### CombinedChat

Provides a chat experience where there is a single thread and all messages, whether they are public or private, are
displayed in a single list.

_Props_ (`ChatProps`):

|       Property       |                 Type                  | Description                                                                                                     |
|:--------------------:|:-------------------------------------:|-----------------------------------------------------------------------------------------------------------------|
|    `chatActions`     | [ZocksChatActions](#zockschatactions) | Chat actions. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions).                 |
|      `dismiss`       |              () => void               | Optional. Called when dismissing the chat.                                                                      |

_Components_:

|        Property         |               Type                | Description                                                                                                          |
|:-----------------------:|:---------------------------------:|----------------------------------------------------------------------------------------------------------------------|
|       ChatMessage       | ComponentType\<ChatMessageProps>? | Element renderer for chat messages. Default: `ChatMessageWithParticipantInfo`                                        |
|        ChatInput        | ComponentType\<ChatMessageProps>? | Element renderer for chat input. Default: `CustomizableChatInput`                                                    |
| ParticipantNotConnected | ComponentType\<StyledComponent>?  | Element renderer for displaying a message when the participant is not connected.. Default: `ParticipantNotConnected` |

_Related CSS classes_:

- `chat`
- `chat__header`
- `chat__main-container`
- `chat__messages-container`
- `chat__footer`

---

#### SplitChat

Provides a full chat experience with separate threads and a custom recipient selector.

_Props_ (`SplitChatProps`):

|          Property          |                   Type                   | Description                                                                                                     |
|:--------------------------:|:----------------------------------------:|-----------------------------------------------------------------------------------------------------------------|
|       `chatActions`        |  [ZocksChatActions](#zockschatactions)   | Chat actions. Usually comes from `chatActions` provided by [useZocksActions](#usezocksactions).                 |
|         `dismiss`          |                () => void                | Optional. Called when dismissing the chat.                                                                      |

_Components_:

|        Property         |                  Type                   | Description                                                                                                          |
|:-----------------------:|:---------------------------------------:|----------------------------------------------------------------------------------------------------------------------|
|       ChatMessage       |    ComponentType\<ChatMessageProps>?    | Element renderer for chat messages. Default: `ChatMessageWithAvatar`                                                 |
|        ChatInput        |    ComponentType\<ChatMessageProps>?    | Element renderer for chat input. Default: `ChatInputWithoutRecipientSelector`                                        |
|    RecipientSelector    | ComponentType\<RecipientSelectorProps>? | Element renderer for the recipient selector. Default: `RecipientSelector`                                            |
| ParticipantNotConnected |    ComponentType\<StyledComponent>?     | Element renderer for displaying a message when the participant is not connected.. Default: `ParticipantNotConnected` |

_Related CSS classes_:

- `chat`
- `chat__header`
- `chat__main-container`
- `chat__messages-container`
- `chat__footer`

## One-on-One Meeting

`OneOnOneMeeting` provides a complete one-on-one experience built on top of the existing components of the
SDK, with many customized components. The join page is much more lightweight with a Join button on the local stream
area. In the meeting, there is a floating participant component, which displays the local participant by
default, and a main participant component which displays the remote participant by default.
During screen share, the floating view displays the remote participant while the main view is occupied by the screen
share. There is also a full screen functionality available provided by extending the room controls component.

An example usage can be found in `OneOnOneMeetingWrapper`.

_Props_ (`OneOnOneMeetingProps`):

|    Property    |            Type            | Description                                                                                |
|:--------------:|:--------------------------:|--------------------------------------------------------------------------------------------|
| `zocksActions` |        ZocksActions        | The Zocks actions provided by the [useZocksActions](#usezocksactions) hook.                |
|    `roomId`    |          string?           | Optional. The room id to join to.                                                          |
|   `roomName`   |          string?           | Optional. The room name to join to.                                                        |
|  `components`  | OneOnOneMeetingComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`OneOnOneMeetingComponents`):

|    Property    |                Type                | Description                                                     |
|:--------------:|:----------------------------------:|-----------------------------------------------------------------|
| `roomControls` |      RoomControlsComponents?       | Optional. The room controls components.                         |
| `participant`  | OneOnOneParticipantViewComponents? | Optional. The component for the floating and main participants. |
|   `joinPage`   |    OneOnOneJoinPageComponents?     | Optional. Components for the join page.                         |
|    `Loader`    |  ComponentType\<StyledComponent>?  | Optional. Loader component                                      |

_Related CSS classes_:

- `oneonone-meeting__container`
- `oneonone-meeting--full-screen`
    - increase `z-index` here when there are issues with full-screen functionality of this component

### OneOnOneJoinPage

Join page for the one-on-one meeting with built-in join button on the local streams.

_Props_ (`OneOnOneJoinPageProps`):

|   Property    |                Type                | Description                                                                                |
|:-------------:|:----------------------------------:|--------------------------------------------------------------------------------------------|
|   `roomId`    |              string?               | The room id to join to.                                                                    |
|  `roomName`   |              string?               | The room name to join to.                                                                  |
| `joinAction`  | (joinOptions: JoinOptions) => void | The join action.                                                                           |
| `joinOptions` |       Partial\<JoinOptions>        | Optional. Join options.                                                                    |
| `components`  |    OneOnOneJoinPageComponents?     | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`OneOnOneJoinPageComponents`):

|          Property          |               Type               | Description                                          |
|:--------------------------:|:--------------------------------:|------------------------------------------------------|
| `DisabledVideoPlaceholder` | ComponentType\<StyledComponent>? | Optional. Placeholder when the video is disabled.    |
|        `JoinButton`        | ComponentType\<StyledComponent>? | Optional. The join button in the local streams area. |

_Related CSS classes_:

- `oneonone-join-page__no-video`
- `oneonone-join-page__join-button`

---

### OneOnOneParticipantView

Renders a picture in picture participant view for one on one meetings.
By default, participants are rendered with the `Participant` component, and the screen share with the `ScreenShare`
component, but the these renderers can be changed.

This component can be embedded into any page and renders a full screen button which puts the whole component above
everything.

_Props_ (`OneOnOneParticipantViewProps`):

|   Property   |                Type                | Description                                                                                |
|:------------:|:----------------------------------:|--------------------------------------------------------------------------------------------|
| `components` | OneOnOneParticipantViewComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Components_ (`OneOnOneParticipantViewComponents`):

|       Property        |               Type                | Description                                  |
|:---------------------:|:---------------------------------:|----------------------------------------------|
| `FloatingParticipant` | ComponentType\<ParticipantProps>? | Optional. The floating participant renderer. |
|   `MainParticipant`   | ComponentType\<ParticipantProps>? | Optional. The main participant renderer.     |

_Related CSS classes_:

- `oneonone-participant-view__container`
- `oneonone-participant-view__main_participant`
- `oneonone-participant-view__floating-participant`

---

### OneOnOneRoomControls

Join page for the one-on-one meeting with built-in join button on the local streams.

_Props_ (`OneOnOneRoomControlsProps`):

|      Property      |          Type           | Description                                                                                |
|:------------------:|:-----------------------:|--------------------------------------------------------------------------------------------|
|   `zocksActions`   |      ZocksActions       | The Zocks actions provided by the [useZocksActions](#usezocksactions) hook.                |
|  `isInFullscreen`  |         boolean         | Indicates whether the one-on-one meeting is in fullscreen or not.                          |
| `toggleFullscreen` |       () => void        | Toggle full screen action.                                                                 |
|    `components`    | RoomControlsComponents? | Optional. If given, renders the components given in this prop instead of the default ones. |

_Related CSS classes_:

- `oneone-room-controls__container`
- `oneonone-room-controls__full-screen-button`
- `oneonone-room-controls__full-screen-button--on`
- `oneonone-room-controls__full-screen-button--off`

