Skip to content

Commit

Permalink
Adjust documentation, add review suggestions
Browse files Browse the repository at this point in the history
  • Loading branch information
@arnautov-anton
arnautov-anton committed Nov 7, 2023
1 parent 4c1f690 commit 90a7ba0
Show file tree
Hide file tree
Showing 6 changed files with 98 additions and 81 deletions.
6 changes: 5 additions & 1 deletion docusaurus/docs/React/basics/getting-started.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -124,10 +124,14 @@ const { client } = useChatContext();
The [`Channel`](../components/core-components/channel.mdx) component is a React Context provider that wraps all of the logic, functionality, and UI for an individual chat channel.
It provides five separate contexts to its children:

:::caution
`EmojiContext` has been removed in version `11.0.0`, see related release guides (["Reactions 11.0.0"](../release-guides/reactions-v11.mdx), ["EmojiPicker 11.0.0"](../release-guides/emoji-picker-v11.mdx) and ["emojiSearchIndex 11.0.0"](../release-guides/emoji-search-index-v11.mdx)) to adjust your integration to this new change.
:::

- [`ChannelStateContext`](../components/contexts/channel-state-context.mdx) - stateful data (ex: `messages` or `members`)
- [`ChannelActionContext`](../components/contexts/channel-action-context.mdx) - action handlers (ex: `sendMessage` or `openThread`)
- [`ComponentContext`](../components/contexts/component-context.mdx) - custom component UI overrides (ex: `Avatar` or `Message`)
- [`EmojiContext`](../components/contexts/emoji-context.mdx) - emoji UI components and data (ex: `EmojiPicker` or `emojiConfig`)
- [`EmojiContext`](../components/contexts/emoji-context.mdx) - emoji UI components and data (ex: `EmojiPicker` or `emojiConfig`) - removed in `11.0.0`
- [`TypingContext`](../components/contexts/typing-context.mdx) - object of currently typing users (i.e., `typing`)

### ChannelList
Expand Down
4 changes: 4 additions & 0 deletions docusaurus/docs/React/components/contexts/emoji-context.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,10 @@ sidebar_position: 5
title: EmojiContext
---

:::caution
`EmojiContext` has been removed in version `11.0.0`, see related release guides (["Reactions 11.0.0"](../release-guides/reactions-v11.mdx), ["EmojiPicker 11.0.0"](../release-guides/emoji-picker-v11.mdx) and ["emojiSearchIndex 11.0.0"](../release-guides/emoji-search-index-v11.mdx)) to adjust your integration to this new change.
:::

The `EmojiContext` is established by the `Channel` component and exposes the `useEmojiContext` hook. This context holds
the UI components and stateful data necessary to render emoji selector functionality.

Expand Down
103 changes: 57 additions & 46 deletions docusaurus/docs/React/components/core-components/channel.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -263,45 +263,54 @@ Custom UI component to override default edit message input.
| --------- | ---------------------------------------------------------------------------------- |
| component | <GHComponentLink text='EditMessageForm' path='/MessageInput/EditMessageForm.tsx'/> |

### Emoji
### Emoji (removed in `11.0.0`)

Custom UI component to override default `NimbleEmoji` from `emoji-mart`.

| Type |
| --------- |
| component |

### emojiData
### emojiData (removed in `11.0.0`)

Custom prop to override default `facebook.json` emoji data set from `emoji-mart`.

| Type |
| ------ |
| object |

### EmojiIcon
### EmojiIcon (removed in `11.0.0`)

Custom UI component for emoji button in input.

| Type | Default |
| --------- | ----------------------------------------------------------------------- |
| component | <GHComponentLink text='EmojiIconSmall' path='/MessageInput/icons.tsx'/> |

### EmojiIndex
### EmojiIndex (removed in `11.0.0`)

Custom UI component to override default `NimbleEmojiIndex` from `emoji-mart`.
Custom search mechanism class to override default `NimbleEmojiIndex` class from `emoji-mart`.

| Type |
| --------- |
| component |
| Type | Default |
| ----- | ----------------------------------------------------------------------------------------------------------------- |
| class | [NimbleEmojiIndex](https://github.com/missive/emoji-mart/blob/v3.0.1/src/utils/emoji-index/nimble-emoji-index.js) |

### EmojiPicker
### emojiSearchIndex (available since `11.0.0`)

Custom UI component to override default `NimblePicker` from `emoji-mart`.
Custom search mechanism instance or object to enable emoji autocomplete. See ["emojiSearchIndex 11.0.0"](../../release-guides/emoji-search-index-v11.mdx) release guide for more information.

| Type |
| --------- |
| component |
| Type | Default |
| ------ | --------- |
| object | undefined |

### EmojiPicker (changed in `11.0.0`)

Custom UI component to override default `NimblePicker` from `emoji-mart`. Markup structure changed in `11.0.0`, see ["EmojiPicker 11.0.0"](../../release-guides/emoji-picker-v11.mdx) release guide for more information.

| Version | Type | Default |
| ------- | --------- | -------------------------------------------------------------------------------------------------------- |
| >=4.0.0 | component | [NimblePicker](https://github.com/missive/emoji-mart/blob/v3.0.1/src/components/picker/nimble-picker.js) |
| ^11.0.0 | component | undefined |

### EmptyPlaceholder

Expand Down Expand Up @@ -381,48 +390,50 @@ A custom function to provide size configuration for image attachments
Allows to prevent triggering the `channel.watch()` (triggers channel query HTTP request) call when mounting the `Channel` component (the default behavior) with uninitialized (`channel.initialized`) `Channel` instance. That means that no channel data from the back-end will be received neither channel WS events will be delivered to the client. Preventing to initialize the channel on mount allows us to postpone the channel creation in the Stream's DB to a later point in time, for example, when a first message is sent:

```typescript jsx
import {useCallback} from "react";
import { useCallback } from 'react';
import {
getChannel,
MessageInput as StreamMessageInput,
MessageInputProps, MessageToSend,
MessageInputProps,
MessageToSend,
useChannelActionContext,
useChatContext
} from "stream-chat-react";
import {Message, SendMessageOptions} from "stream-chat";
useChatContext,
} from 'stream-chat-react';
import { Message, SendMessageOptions } from 'stream-chat';

import {useChannelInitContext} from "../../context/ChannelInitProvider";
import type { MyStreamChatGenerics } from "../../types";
import { useChannelInitContext } from '../../context/ChannelInitProvider';
import type { MyStreamChatGenerics } from '../../types';

export const MessageInput = (props: MessageInputProps) => {
const {client} = useChatContext();
const {sendMessage} = useChannelActionContext();
const { setInitializedChannelOnMount} = useChannelInitContext();

const submitHandler: MessageInputProps['overrideSubmitHandler'] = useCallback(async (
message: MessageToSend<MyStreamChatGenerics>,
channelCid: string,
customMessageData?: Partial<Message<MyStreamChatGenerics>>,
options?: SendMessageOptions,
) => {
const [channelType, channelId] = channelCid.split(":");
const channel = client.channel(channelType, channelId);
if (!channel.initialized) {
await getChannel({channel, client});
setInitializedChannelOnMount(true);
}

await sendMessage(message, customMessageData, options);
}, [client, sendMessage, setInitializedChannelOnMount]);

return (
<StreamMessageInput {...props} overrideSubmitHandler={submitHandler} />
const { client } = useChatContext();
const { sendMessage } = useChannelActionContext();
const { setInitializedChannelOnMount } = useChannelInitContext();

const submitHandler: MessageInputProps['overrideSubmitHandler'] = useCallback(
async (
message: MessageToSend<MyStreamChatGenerics>,
channelCid: string,
customMessageData?: Partial<Message<MyStreamChatGenerics>>,
options?: SendMessageOptions,
) => {
const [channelType, channelId] = channelCid.split(':');
const channel = client.channel(channelType, channelId);
if (!channel.initialized) {
await getChannel({ channel, client });
setInitializedChannelOnMount(true);
}

await sendMessage(message, customMessageData, options);
},
[client, sendMessage, setInitializedChannelOnMount],
);

return <StreamMessageInput {...props} overrideSubmitHandler={submitHandler} />;
};
```

| Type | Default |
|---------|---------|
| ------- | ------- |
| boolean | true |

### Input
Expand Down Expand Up @@ -629,9 +640,9 @@ Custom UI component for send button.

You can turn on/off thumbnail generation for video attachments

| Type |
| --------- |
| `boolean` |
| Type |
| ------- |
| boolean |

### skipMessageDataMemoization

Expand Down
19 changes: 8 additions & 11 deletions docusaurus/docs/React/guides/customization/emoji-picker.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,16 +6,15 @@ title: Emoji Picker

import CustomEmojiPicker from '../../assets/CustomEmojiPicker.png';

In this example, we will demonstrate how to create a custom Emoji Picker component that can be used in the `MessageInput`.
This component will replace the default [`EmojiPicker`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/MessageInput/EmojiPicker.tsx)
with only breakfast food emojis.
:::caution
Note that this guide is for versions lower than `11.0.0`, the new API has slightly changed. See the ["EmojiPicker 11.0.0"](../../release-guides/emoji-picker-v11.mdx) release guide to help you transition smoothly to the new API.
:::

In this example, we will demonstrate how to create a custom Emoji Picker component that can be used in the `MessageInput`. This component will replace the default [`EmojiPicker`](https://github.com/GetStream/stream-chat-react/blob/master/src/components/MessageInput/EmojiPicker.tsx) with only breakfast food emojis.

## Choose Your Emojis

The default `EmojiPicker` renders individual emoji objects using the [`NimbleEmoji`](https://github.com/missive/emoji-mart/blob/master/src/components/emoji/nimble-emoji.js)
component from [emoji-mart](https://www.npmjs.com/package/emoji-mart). Our custom set of emojis will need to follow the same `NimbleEmoji` props.
`NimbleEmoji` accepts an `emoji` prop, which pertains to either an object mapping of the emoji data or simply the ID (for IDs already existing
in `emoji-mart`). The object mapping of the `emoji` prop has the following type:
The default `EmojiPicker` renders individual emoji objects using the [`NimbleEmoji`](https://github.com/missive/emoji-mart/blob/v3.0.1/src/components/emoji/nimble-emoji.js) component from [emoji-mart](https://www.npmjs.com/package/emoji-mart). Our custom set of emojis will need to follow the same `NimbleEmoji` props. `NimbleEmoji` accepts an `emoji` prop, which pertains to either an object mapping of the emoji data or simply the ID (for IDs already existing in `emoji-mart`). The object mapping of the `emoji` prop has the following type:

```tsx
export interface BaseEmoji {
Expand All @@ -29,8 +28,7 @@ export interface BaseEmoji {
}
```

In this example we will use only the ID and select existing emojis. For a more detailed example of how to construct these emoji objects, please see the
[Reactions Selector and List](../theming/reactions.mdx) section. Below is the array of breakfast emojis we will use:
In this example we will use only the ID and select existing emojis. For a more detailed example of how to construct these emoji objects, please see the [Reactions Selector and List](../theming/reactions.mdx) section. Below is the array of breakfast emojis we will use:

```tsx
const customEmojis = ['fried_egg', 'croissant', 'bacon', 'waffle', 'pancakes', 'doughnut'];
Expand All @@ -43,8 +41,7 @@ loaded into the component library.

## Create the Custom Component

To construct our component, we will utilize the `EmojiContext` to get our `emojiConfig` data. This config object contains the `emojiData` we need for the
`data` prop on the `Emoji` component. Using the `onSelectEmoji` method from the `MessageInputContext`, we can add the onClick functionality to our custom picker.
To construct our component, we will utilize the `EmojiContext` to get our `emojiConfig` data. This config object contains the `emojiData` we need for the `data` prop on the `Emoji` component. Using the `onSelectEmoji` method from the `MessageInputContext`, we can add the onClick functionality to our custom picker.

:::note
The `Emoji` component needs to be wrapped in React's `Suspense` component because it is lazy loaded.
Expand Down
12 changes: 4 additions & 8 deletions docusaurus/docs/React/release-guides/emoji-picker-v11.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
---
id: new-emoji-picker-integration-v11
id: emoji-picker-v11
sidebar_position: 3
title: EmojiPicker Integration (11.0.0)
title: EmojiPicker 11.0.0
keywords: [migration guide, upgrade, emoji picker, breaking changes, v11]
---

Expand All @@ -15,8 +15,6 @@ By default - our SDK would ship with `emoji-mart` dependency on top of which our

SDK's `EmojiPicker` component now comes as two-part "bundle" - a button and an actual picker element. The component now holds its own `open` state which is handled by clicking the button (or anywhere else to close it).

{/_ TODO: extend once the component is fully ready _/}

## Switching to opt-in mechanism (BREAKING CHANGE)

We made `emoji-mart` package in our SDK completely optional which means that `EmojiPicker` component is now disabled by default.
Expand All @@ -29,7 +27,7 @@ To reinstate the previous behavior you'll have to add `emoji-mart` to your packa
yarn add emoji-mart@^5.5.2 @emoji-mart/data@^1.1.2 @emoji-mart/react@^1.1.1
```

\\Import `EmojiPicker` component from the `stream-chat-react` package:
Import `EmojiPicker` component from the `stream-chat-react` package:

```tsx
import { Channel } from 'stream-chat-react';
Expand Down Expand Up @@ -74,6 +72,4 @@ export const CustomEmojiPicker = () => {
// and pass it down to the `Channel` component
```

You can make the component slightly better using [`FloatingUI`](https://floating-ui.com/) by wrapping the actual picker element to make it float perfectly positioned above the button. See the [source of the component (`EmojiPicker`)]() which comes with the SDK for inspiration.

{/_ TODO: mention EmojiContext removal _/}
You can make the component slightly better using [`FloatingUI`](https://floating-ui.com/) by wrapping the actual picker element to make it float perfectly positioned above the button. See the source of the component <GHComponentLink text="EmojiPicker" branch="feat/emoji-picker-delete" as="code" path="/Emojis/EmojiPicker.tsx" /> which comes with the SDK for inspiration.
35 changes: 20 additions & 15 deletions docusaurus/docs/React/release-guides/emoji-search-index-v11.mdx
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
---
id: emoji-search-index-integration-v11
id: emoji-search-index-v11
sidebar_position: 4
title: Emoji Search Index Integration (11.0.0)
title: emojiSearchIndex 11.0.0
keywords: [migration guide, upgrade, emoji search index, breaking changes, v11]
---

## Dropping support for built-in `EmojiIndex`

By default, our SDK comes bundled with the `emoji-mart`'s (`emojiIndex`)[https://github.com/missive/emoji-mart/tree/v3.0.1#headless-search]. This index serves as a tool for efficiently searching through the emoji list and returning a subset that matches the search criteria (query). Within our SDK, this functionality is utilized by our autocomplete component, triggered by entering `:<query>` to the meessage input. This functionality will continue to be integrated within our SDK. However, due to our decision to discontinue the use of `emoji-mart` within the SDK, this feature will now be available on an opt-in basis. With the updated types and interface this will also allow integrators to supply their own `emojiSearchIndex` instead of relying exclusively on the one supplied by `emoji-mart`.
By default, our SDK comes bundled with the `emoji-mart`'s [`emojiIndex`](https://github.com/missive/emoji-mart/tree/v3.0.1#headless-search), more specifically - `NimbleEmojiIndex` class which is then instantiated with custom `emojiData` by our SDK. This index serves as a tool for efficiently searching through the emoji list and returning a subset that matches the search criteria (query). Within our SDK, this functionality is utilized by our autocomplete component, triggered by entering `:<query>` to the meessage input. This functionality will continue to be integrated within our SDK. However, due to our decision to discontinue the use of `emoji-mart` within the SDK, this feature will now be available on an opt-in basis. With the updated types and interface this will also allow integrators to supply their own `emojiSearchIndex` instead of relying exclusively on the one supplied by `emoji-mart`.

### Reinstate emoji autocomplete behavior (search for emojis with `:`)

Expand All @@ -17,7 +17,7 @@ Add `emoji-mart` to your packages and make sure the package versions fit our pee
yarn add emoji-mart@^5.5.2 @emoji-mart/data@^1.1.2
```

\Import `SearchIndex` and `data` from `emoji-mart`, initiate these data and then and pass `SearchIndex` to our `MessageInput` component:
Import `SearchIndex` and `data` from `emoji-mart`, initiate these data and then and pass `SearchIndex` to our `MessageInput` component:

```tsx
import { MessageInput } from 'stream-chat-react';
Expand All @@ -31,9 +31,9 @@ export const WrappedMessageInput = () => {
};
```

### Build your custom `emojiSearchIndex`
## Build your custom `emojiSearchIndex`

## Prerequisities
### Prerequisities

Your data returned from the `search` method should have _at least_ these three properies which our SDK relies on:

Expand All @@ -46,9 +46,10 @@ Optional properties:
- emoticons - an array of strings to match substitutions with, ie: `[":D", ":-D", ":d"]`
- native - native emoji string (old `emoji-mart` API), ie: `"😄"` - will be prioritized if specified

## Example
### Example

```tsx
import { type EmojiSearchIndex } from 'stream-chat-react';
import search from '@jukben/emoji-search';

const emoticonMap: Record<string, string[]> = {
Expand Down Expand Up @@ -76,7 +77,7 @@ export const WrappedChannel = ({ children }) => (
);
```

### Migrate from `v10` to `v11` (`EmojiIndex` becomes `emojiSearchIndex`)
## Migrate from `v10` to `v11` (`EmojiIndex` becomes `emojiSearchIndex`)

`EmojiIndex` has previously lived in the `EmojiContext` passed to through `Channel` component. But since `EmojiContext` no longer exists in our SDK, the property has been moved to our `ComponentContext` (still passed through `Channel`) and changed its name to `emojiSearchIndex` to properly repesent its funtionality. If your custom `EmojiIndex` worked with our default components in `v10` then it should still work in `v11` without any changes to its `search` method output:

Expand All @@ -85,11 +86,11 @@ Your old code:
```tsx
import { Channel, MessageInput } from 'stream-chat-react';
// arbitrary import
import { CustomEmojiIndex } from './CustomEmojiIndex';
import { CustomEmojiIndex, customData } from './CustomEmojiIndex';

const App = () => {
return (
<Channel EmojiIndex={CustomEmojiIndex}>
<Channel emojiData={customData} EmojiIndex={CustomEmojiIndex}>
{/* other components */}
<MessageInput />
</Channel>
Expand All @@ -102,11 +103,13 @@ Should newly look like this:
```tsx
import { Channel, MessageInput } from 'stream-chat-react';
// arbitrary import
import { CustomEmojiIndex } from './CustomEmojiIndex';
import { CustomEmojiIndex, customData } from './CustomEmojiIndex';
// instantiate the search index
const customEmojiSearchIndex = new CustomEmojiIndex(customData);

const App = () => {
return (
<Channel emojiSearchIndex={CustomEmojiIndex}>
<Channel emojiSearchIndex={customEmojiSearchIndex}>
{/* other components */}
<MessageInput />
</Channel>
Expand All @@ -119,14 +122,16 @@ Or enable it in either of the `MessageInput` components individually:
```tsx
import { Channel, MessageInput } from 'stream-chat-react';
// arbitrary import
import { CustomEmojiIndex } from './CustomEmojiIndex';
import { CustomEmojiIndex, customData } from './CustomEmojiIndex';
// instantiate the search index
const customEmojiSearchIndex = new CustomEmojiIndex(customData);

const App = () => {
return (
<Channel>
{/* other components */}
<MessageInput emojiSearchIndex={CustomEmojiIndex} />
<Thread additionalMessageInputProps={{ emojiSearchIndex: CustomEmojiIndex }} />
<MessageInput emojiSearchIndex={customEmojiSearchIndex} />
<Thread additionalMessageInputProps={{ emojiSearchIndex: customEmojiSearchIndex }} />
</Channel>
);
};
Expand Down

0 comments on commit 90a7ba0

Please sign in to comment.