Merge pull request #1456 from GetStream/develop

Author: petyosi

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Describe a new feature
+title: ''
+labels: feature
+assignees: ''
+
+---
+
+**Motivation**
+A clear and concise description of what the problem/opportunity is. Ex. I'm always frustrated when [...]
+
+**Proposed solution**
+A clear and concise description of what you want to happen.
+
+**Acceptance Criteria**
+A set of predefined requirements that must be met to mark a user story complete.

docusaurus/docs/React/assets/margin-inspector.png

@@ -65,6 +65,14 @@ Error object (if any) in loading the `channel`, otherwise null.
 | ------ |
 | object |
 
+### giphyVersion
+
+The giphy version to use when displaying giphies. 
+
+| Type                                                                                                                                                |
+| --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `'original' | 'fixed_height' | 'fixed_height_still' | 'fixed_height_downsampled' | 'fixed_width' | 'fixed_width_still' | 'fixed_width_downsampled'` |
+
 ### hasMore
 
 If the channel has more messages to paginate through.

docusaurus/docs/React/assets/message-height.png

@@ -262,6 +262,14 @@ Custom UI component to render a Giphy preview in the `VirtualizedMessageList`.
 | --------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | component | [GiphyPreviewMessage](https://github.com/GetStream/stream-chat-react/blob/master/src/components/MessageList/GiphyPreviewMessage.tsx) |
 
+### giphyVersion
+
+The Giphy version to render - check the keys of the [Image Object](https://developers.giphy.com/docs/api/schema#image-object) for possible values. 
+
+| Type      | Default        |
+| --------- | -------------- |
+| string    | 'fixed_height' |
+
 ### HeaderComponent
 
 Custom UI component to render at the top of the `MessageList`.

docusaurus/docs/React/contexts/channel-state-context.mdx

@@ -9,7 +9,7 @@ import CustomChannelSearch from '../assets/CustomChannelSearch.png';
 ## How-to Guide for Customizing ChannelSearch
 
 In this example, we will customize the [`ChannelSearch`](../core-components/channel-list.mdx#channelsearch) component. Though this component can be used standalone, we will do our customization when it's established in the `ChannelList`. Here is a guide that outlines how to
-override the default `DropdownContainer` and `SearchResultItem` components, as well as use several other useful props.
+override the default `DropdownContainer`, `SearchResultItem`, and `SearchResultsHeader` components, as well as use several other useful props.
 
 :::note
 A complete override of this component is possible by utilizing the [`ChannelSearch`](../core-components/channel-list.mdx#channelsearch) prop on `ChannelList`.
@@ -308,3 +308,34 @@ const additionalProps = {
 ### Result:
 
 <img src={CustomChannelSearch} alt='Custom Channel Search UI Component for Chat' width='700' />
+
+### The searchFunction Prop:
+
+By default the `ChannelSearch` component searches just for users. Use the `searchForChannels` prop to also search for channels.
+
+To override the search method, completely use the `searchFunction` prop. This prop is useful, say, when you want to search just for channels
+and for only channels that the current logged in user is a member of. See the example below for this.
+
+```jsx
+const customSearchFunction = async (props: ChannelSearchFunctionParams, event: { target: { value: SetStateAction<string>; }; }) => {
+  const { setResults, setResultsOpen, setSearching, setQuery } = props;
+  const { client } = useChatContext();
+
+  const filters = {
+      name: { $autocomplete: event.target.value },
+      members: { $in: client.userID }
+  }
+
+  setSearching(true);
+  setQuery(event.target.value);
+  const channels = await chatClient.queryChannels(filters);
+  setResults(channels);
+  setResultsOpen(true);
+  setSearching(false);
+};
+
+<ChannelList
+  showChannelSearch
+  additionalChannelSearchProps={{searchFunction: customSearchFunction}}
+/>
+```

docusaurus/docs/React/core-components/channel.mdx

@@ -0,0 +1,80 @@
+---
+id: livestream-setup
+sidebar_position: 22
+title: Livestream Best Practices
+---
+import MarginInspector from '../assets/margin-inspector.png'
+import MessageHeight from '../assets/message-height.png'
+
+Livestream chat UI poses several hard technological challenges since users can spend a few hours watching a certain event. For that period, the chat UI should be able to handle a constant stream of messages, reactions, and media attachments. 
+
+The React SDK offers a special component for that purpose - the `VirtualizedMessageList`. The component renders only the messages visible in the viewport and dynamically updates its contents as the user scrolls. 
+This decreases browser memory usage and does not degrade the performance of the page even if the user receives thousands of messages in a single session. 
+
+In this article, we will go through the best practices and tweaks for configuring the `VirtualizedMessageList` to ensure a smooth user experience during a high message traffic.
+
+## Get Started
+
+The `VirtualizedMessageList` is mostly compatible with the non-virtualized `MessageList`, although not all properties are the same. The simplest configuration and placement are the same:
+
+```tsx
+<Chat client={client}>
+  <ChannelList />
+  <Channel>
+    <VirtualizedMessageList />
+    <MessageInput />
+  </Channel>
+</Chat>
+```
+
+With this configuration, the virtualized list will look identical to the non-virtualized version. With the next few steps, we can configure the component for maximum performance.
+
+## Disable the automatic scroll to bottom transition
+
+By default, the `VirtualizedMessageList` will scroll down to display new messages using the `"smooth"` scroll behavior ([MDN link](https://developer.mozilla.org/en-US/docs/Web/API/Element/scrollTo#examples)). This works well for moderately busy chat rooms but can be unwieldy in chats with more than 2-3 incoming messages per second. A safer, snappier option is `"auto"`. With that setting, the list scrolls to the latest received message instantly. 
+
+```tsx
+<VirtualizedMessageList stickToBottomScrollBehavior="auto" />
+```
+
+## Specify the default item height
+
+The `VirtualizedMessageList` supports items with varying heights and automatically keeps track of the rendered item sizes, while estimating the not-yet-rendered sizes based on latest message during load. To optimize this further and minimize potential recalculations, set the `defaultItemHeight` to the height of your usual one-line message (If in doubt, use the developer tools inspector to determine the sizing). 
+
+<img src={MessageHeight} alt='Message Height' width='700' />
+
+The element above is `58px` tall, so let's put that at the `defaultItemHeight` prop value:
+
+```tsx
+<VirtualizedMessageList defaultItemHeight={58} />
+```
+
+## Avoid vertical CSS margins
+If the custom Message component has vertical margins that affect its height, the message list might behave erratically (blinking, rendering white areas, etc).
+
+This could be a potential pitfall if you're using a custom message component. The `VirtualizedMessageList` uses `getBoundingClientRect` ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect)) on the outermost message element. 
+This method does not measure CSS margins, which are tricky to measure in the first place [due to collapsing](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Box_Model/Mastering_margin_collapsing).
+If the custom Message component has vertical margins that affect its height, the message list might behave erratically (blinking, rendering white areas, etc). 
+
+Use your DOM inspector and look for any orange gaps between the message elements. See the screenshot below for example of headings with margins:
+
+<img src={MarginInspector} alt='Margin Inspector' width='700' />
+
+## Choose the right Giphy size
+
+This practice is not unique to the virtualized message list but might help you build a more compact chat timeline and reduce the overall traffic for your users. By default, the Giphy attachments [use the original Giphy version image](https://developers.giphy.com/docs/api/schema#image-object). You can override that by setting the `giphyVersion` property of the `Channel` Component to a smaller one - use the keys [from the Giphy documentation](https://developers.giphy.com/docs/api/schema#image-object).
+
+```tsx
+<Chat client={client}>
+  <ChannelList />
+  <Channel giphyVersion="fixed_height_small">
+    <VirtualizedMessageList />
+    <MessageInput />
+  </Channel>
+</Chat>
+```
+
+## Design reactions so that they don't change the message size
+
+One final best practice: make sure that adding reactions to the message does not increase the message height if you're using a custom `Message` component. Good examples for such design would be the chat boxes of Twitch and Telegram.
+Avoiding that will make the message list appear more stable and less jumpy during high traffic.

docusaurus/docs/React/custom-code-examples/channel-search.mdx

@@ -118,6 +118,156 @@ export const CustomMessage = () => {
 };
 ```
 
+CustomMessage.scss:
+
+```css
+.str-chat__li {
+  margin: 0px;
+  padding: 15px;
+  position: relative;
+
+  &:hover {
+    background: rgba(0, 0, 0, 0.03);
+    .str-chat__message-text-inner {
+      background: rgba(0, 0, 0, 0);
+    }
+  }
+}
+
+.message-wrapper {
+  display: flex;
+
+  &-content {
+    display: flex;
+    flex-direction: column;
+    align-items: flex-start;
+    width: 100%;
+  }
+}
+
+.message-header {
+  display: flex;
+
+  &-name {
+    font-family: Helvetica Neue, sans-serif;
+    font-weight: 500;
+    font-size: 11px;
+    line-height: 120%;
+    color: #858688;
+  }
+
+  &-timestamp {
+    font-family: Helvetica Neue, sans-serif;
+    font-size: 11px;
+    line-height: 120%;
+    color: #858688;
+    margin-left: 6px;
+  }
+}
+
+.str-chat__li:hover .str-chat__message-simple__actions {
+  position: absolute;
+  top: -14px;
+  right: 20px;
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  height: 24px;
+  border-radius: 100px;
+  background: white;
+  border: 1px solid #e0e0e0;
+  box-shadow: 0 2px 1px 0 rgba(0, 0, 0, 0.07);
+  z-index: 1;
+  padding: 0 4px 0;
+
+  &__action--reactions {
+    display: flex;
+  }
+
+  &__action--options {
+    display: flex;
+  }
+
+  &__action--thread {
+    display: flex;
+  }
+}
+
+.str-chat__message-simple__actions {
+  margin-top: 0;
+}
+
+.str-chat__message-actions-box {
+  top: initial;
+  left: -100px;
+  border-radius: 16px 16px 0 16px;
+}
+
+.str-chat__message-text {
+  display: flex;
+  width: 100%;
+}
+
+.str-chat__message-text-inner {
+  position: relative;
+  flex: 1;
+  display: block;
+  min-height: 32px;
+  font-size: 15px;
+  color: black;
+  border-radius: 0;
+  border: 0px;
+  margin-left: 0;
+
+  p {
+    font-family: Helvetica Neue, sans-serif;
+    font-size: 15px;
+    line-height: 18px;
+    color: #000000;
+    margin-bottom: 0;
+  }
+}
+
+.str-chat__message-replies-count-button {
+  font-family: Helvetica Neue, sans-serif;
+  font-weight: bold;
+  font-size: 13px;
+  text-align: right;
+  color: #4e1d9d;
+}
+
+.str-chat__simple-reactions-list {
+  border-radius: 10px;
+}
+
+.str-chat__reaction-selector {
+  max-height: 40px;
+  top: -58px;
+  right: 20px;
+  border-radius: 20px;
+  background: white;
+  box-shadow: 0px 3px 8px rgba(0, 0, 0, 0.15);
+  border: 1px solid #bed5e4;
+}
+
+.str-chat__message-reactions-list-item__count {
+  color: #000000;
+}
+
+.str-chat__message-simple-status {
+  right: 22px;
+}
+
+.quoted-message-inner {
+  margin-top: 10px;
+  box-shadow: 0 2px 6px rgba(0, 0, 0, 0.15);
+}
+
+.str-chat__li .quoted-message.mine .quoted-message-inner {
+  background: #ebebeb;
+}
+```
+
 #### The Result:
 
 <img src={CustomMessage} alt='Custom Message UI Component for Chat' width='700' />