docs: theming-v2 documentation (#1722)

* docs: add scripts to run documentation server locally

* docs: add documentation guide for contributors

* test: fix channel data generation for ChannelHeader tests

* docs: add migration guides folder

* docs: add GHComponentLink component to generate Github links

* docs: add corrections and review notes to chat.mdx

* docs: add corrections and review notes to chat-context.mdx

* docs: add corrections and review notes to channel-list.mdx

* docs: add corrections and new content to channel-search.mdx

* docs: add image assets for channel-search.mdx

* docs: add ReviewNote docusaurus component

* docs: fix doc string of the VirtualizedMessageList's Message prop

* docs: fix doc string of the VirtualizedMessageList's Message prop

* docs: add asset message-actions-box-custom-actions.png

* docs: review core-components documentation

* docs: review contexts documentation

* docs: review basics documentation

* docs: review message-components documentation

* docs: update migration guide v10

* docs: add corrections and snippet to attachment.mdx

* docs: add missing migration for the shouldSubmit property

* deprecate: useCustomStyles hook

* docs: update channel preview example

* docs: add deprecation notice to css and theming

* docs: fix md table formatting for message-ui.mdx

* docs: add prop author to ReviewNote component

* docs: fix typo

* docs: add missing prop documentation and fix table formatting for reactions.mdx

* docs: add missing information to attachment.mdx doc

* docs: add missing information to message UI components documentation

* fix: remove unused prop displayLeft from MessageOptions

* docs: add docstrings to message UI components

* docs: document message input props in alpha order

* docs: add missing props documentation and fix props name for msg input UI components

* docs: add keywords and warning to v1 theming

* docs: fix the example in reactions.mdx

* docs: fix examples in customization message-ui.mdx

* docs: fix mistakes in customization input-ui.mdx

* docs: remove dated examples, links, update text in typescript.mdx

* docs(examples): update channel users list

* docs(examples): update livestream setup

* docs: instruct users to use css bundled with stream-chat-react

* docs: review code examples for channel-list-preview.mdx

Co-authored-by: Anton Arnautov <[email protected]>
Co-authored-by: Anton Arnautov <[email protected]>

CONTRIBUTING.md

@@ -54,7 +54,7 @@ Any contributions to the library should follow Stream's coding rules.
 All the code submitted should be covered by unit tests. Mocking utilities are provided in `src/mock-builders`. Optimally a suite of E2E tests should be included as well.
 
 #### 2. API Changes should be documented
-Changes to components interface exposed to the library integrators should be documented. We keep the documentation `docusaurus/docs/React` folder.
+Changes to components interface exposed to the library integrators should be documented. We keep the documentation `docusaurus/docs/React` folder. Please see the [dedicated documentation guide](./developers/DOCUMENTATION.md) for more information on how to maintain our documentation.
 
 #### 3. Code should be DRY & correctly formatted
 If you find yourself copying source code from one place to another, please extract it into a separate component or function.

developers/DOCUMENTATION.md

@@ -0,0 +1,20 @@
+# Documenting the SDK
+
+If you are introducing changes impacting the API or behavior of the SDK parts, you should document these. Our documentation is generated with [docusaurus](https://docusaurus.io/docs). We have our own cli tool [stream-chat-docusaurus-cli](https://github.com/GetStream/stream-chat-docusaurus-cli#installation-and-using-the-cli) to run the documentation server locally, so that you can inspect your adjustments.
+
+## Run the documentation server locally
+
+1. **Install [stream-chat-docusaurus-cli](https://github.com/GetStream/stream-chat-docusaurus-cli#installation-and-using-the-cli)**
+   (You will need it to serve the documentation locally)
+2. **Run the documentation server**
+
+
+```bash
+yarn docs-run
+```
+
+## Documentation patterns
+
+To keep the documentation consistent we would like you to adhere to the following recommendations:
+
+1. todo

docusaurus/docs/React/_docusaurus-components/ReviewNote.jsx

@@ -0,0 +1,76 @@
+import React from 'react';
+import BrowserOnly from '@docusaurus/BrowserOnly';
+
+const rootStyle = {
+  display:'flex',
+  position: 'relative',
+  cursor: 'pointer',
+  padding: '10px 10px',
+  margin: '10px 0',
+  borderRadius: "8px",
+  background: 'gold',
+  boxShadow: '0 1px 1px rgba(0,0,0,0.15)'
+}
+
+const popupStyle = {
+  position: 'absolute',
+  left: 0,
+  bottom: "60px",
+  width: '100%',
+  background: 'white',
+  boxShadow: '0 4px 4px 4px rgba(0,0,0,0.15)',
+  padding: '10px 10px',
+}
+
+const ReviewNote = ({author, children, id}) => {
+  const [display, setDisplay] = React.useState('none');
+  const [keepDisplayed, setKeepDisplayed] = React.useState(false);
+  const [root, setRoot] = React.useState(null);
+  const handleMouseLeave = React.useCallback(() => {
+    if (keepDisplayed) return;
+    setDisplay('none');
+  }, [keepDisplayed]);
+
+  React.useEffect(() => {
+    if (!root) return;
+
+    const handleClick = (event) => {
+      if (!root.contains(event.target)) {
+        setKeepDisplayed(false)
+      }
+    }
+    document.addEventListener('click', handleClick);
+
+    return () => {
+      document.removeEventListener('click', handleClick);
+    }
+  }, [root]);
+
+  return (
+    <BrowserOnly>
+      {() => window.location.hostname === 'localhost' ? (
+        <div style={rootStyle}
+             onClick={(event) => {
+               event.stopPropagation();
+               setKeepDisplayed(prev => !prev);
+             }}
+             onMouseEnter={() => setDisplay('block')}
+             onMouseLeave={handleMouseLeave}
+             ref={setRoot}
+        >
+          <div style={{display, ...popupStyle}}>
+
+            <div style={{ width: '100%'}}>{children}</div>
+          </div>
+          <div style={{display: 'flex', justifyContent: 'space-between', width: '100%'}}>
+            <div>Review note {author && <span style={{fontSize: '10px'}}>[author: {author}]</span>}</div>< div style={{fontSize: '10px'}}>[{id}]</div>
+
+          </div>
+
+        </div>
+      ): null}
+    </BrowserOnly>
+  );
+}
+
+export default ReviewNote;

docusaurus/docs/React/basics/getting-started.mdx

@@ -4,6 +4,8 @@ sidebar_position: 2
 title: Getting Started
 ---
 
+import ReviewNote from '../_docusaurus-components/ReviewNote';
+
 This section provides a high level overview of the library setup, core components, and how they fit together. It's a great
 starting point and you can follow along in your code editor. For a complete, step-by-step guide in terms setting up a React
 project or instructions on creating specific files, see our [React Chat tutorial](https://getstream.io/chat/react-chat/tutorial/).
@@ -82,6 +84,17 @@ The defaults include:
 - `gaming`
 - `commerce`
 
+<ReviewNote
+  id='ab86a784-22f9-11ed-936e-a4bb6d26ac2f'
+>
+  Failing to provide explanation why in the first place should user of the SDK interact with the channel object
+  directly.
+  Provide examples of scenarios when a channel object would be needed.
+  Missing the mention, that ChannelList - if used - loads channel data from the API and thus it integrator does not need
+  to create channels
+  Proposing to add recommendation to create channels from the backend
+</ReviewNote>
+
 :::note
 You can also create [custom channel types](https://getstream.io/chat/docs/react/channel_features/#creating-a-channel-type)
 and define your own permission sets.
@@ -107,13 +120,19 @@ const channel = client.channel('messaging', {
 Now that we have a client instance, a connected user, and a channel, it's time to look at the core components involved in building
 a fully functioning chat application.
 
+<ReviewNote
+  id='dcfe3c22-2304-11ed-83ef-a4bb6d26ac2f'
+>
+  Add visualisation - wireframe - to demonstrate the main components in the UI
+</ReviewNote>
+
 ### Chat
 
 The [`Chat`](../core-components/chat.mdx) component is a React Context provider that wraps the entire Stream Chat application. It provides the [`ChatContext`](../contexts/chat-context.mdx)
 to its children, which includes the `StreamChat` client instance. All other components within the library must be nested as children
 of `Chat` to maintain proper functionality.
 
-The client instance can be accesses with our custom context hook:
+The client instance can be accessed with our custom context hook:
 
 ```jsx
 const { client } = useChatContext();
@@ -176,6 +195,15 @@ The [`Thread`](../core-components/thread.mdx) component renders a list of replie
 
 In addition to the above referenced UI components, client instantiation, and user connection, you need little other code to get a fully functioning chat application up and running. See below for an example of the complete code.
 
+<ReviewNote
+  id='179e58f8-22fb-11ed-909b-a4bb6d26ac2f'
+>
+  The filters variable should actually include members key:
+  <CodeBlock>{'const filters = {type: "messaging", members: {$in: [userId]}};'}</CodeBlock>
+  That means that we should explain how the userId gets there in a real life application. For a real-life example too
+  soon here?
+</ReviewNote>
+
 ```tsx
 import React, { useEffect, useState } from 'react';
 import { StreamChat } from 'stream-chat';
@@ -196,10 +224,10 @@ const options = { state: true, presence: true, limit: 10 };
 const sort = { last_message_at: -1 };
 
 const App = () => {
-  const [client, setClient] = useState(null);
+const [client, setClient] = useState(null);
 
-  useEffect(() => {
-    const newClient = new StreamChat('your_api_key');
+useEffect(() => {
+const newClient = new StreamChat('your_api_key');
 
     const handleConnectionChange = ({ online = false }) => {
       if (!online) return console.log('connection lost');
@@ -220,23 +248,23 @@ const App = () => {
       newClient.off('connection.changed', handleConnectionChange);
       newClient.disconnectUser().then(() => console.log('connection closed'));
     };
-  }, []);
-
-  if (!client) return null;
-
-  return (
-    <Chat client={client}>
-      <ChannelList filters={filters} sort={sort} options={options} />
-      <Channel>
-        <Window>
-          <ChannelHeader />
-          <MessageList />
-          <MessageInput />
-        </Window>
-        <Thread />
-      </Channel>
-    </Chat>
-  );
+}, []);
+
+if (!client) return null;
+
+return (
+<Chat client={client}>
+<ChannelList filters={filters} sort={sort} options={options} />
+<Channel>
+<Window>
+<ChannelHeader />
+<MessageList />
+<MessageInput />
+</Window>
+<Thread />
+</Channel>
+</Chat>
+);
 };
 
 export default App;

docusaurus/docs/React/basics/installation.mdx

@@ -5,7 +5,7 @@ slug: /
 title: Overview
 ---
 
-Building on top of the the Stream Chat API, the Stream Chat React component library includes everything you need to build feature-rich and high-functioning chat user experiences out of the box. 
+Building on top of the Stream Chat API, the Stream Chat React component library includes everything you need to build feature-rich and high-functioning chat user experiences out of the box.
 The library includes an extensive set of performant and customizable React components which allow you to get started quickly with little to no plumbing required.
 Use cases include team and social messaging, virtual events, livestream gaming, and customer support. The library supports:
 
@@ -43,7 +43,7 @@ yarn add stream-chat stream-chat-react
 
 ### Install via CDN
 
-In case you are not using a package manager, or you wish to build a simple proof of concept in CodePen for example, you can load the library through a direct script link. 
+In case you are not using a package manager, or you wish to build a simple proof of concept in CodePen for example, you can load the library through a direct script link.
 If you choose to do this, make sure you explicitly specify the version of the library to prevent breaking releases from affecting your app.
 
 ```html

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

@@ -22,7 +22,7 @@ const { closeThread, loadMoreThread } = useChannelActionContext();
 Function to add a temporary notification to `MessageList`, and it will be removed after 5 seconds.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 |          |
 
@@ -31,7 +31,7 @@ Function to add a temporary notification to `MessageList`, and it will be remove
 The function to close the currently open `Thread`.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### dispatch
@@ -47,7 +47,7 @@ The dispatch function for the [`ChannelStateReducer`](https://github.com/GetStre
 A function that takes a message to be edited, returns a Promise.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### jumpToLatestMessage
@@ -60,7 +60,7 @@ Used in conjunction with `jumpToMessage`. Restores the position of the message l
 
 ### jumpToMessage
 
-When called, `jumpToMessage` causes the current message list to jump to the message with the id specified in the `messageId` parameter. 
+When called, `jumpToMessage` causes the current message list to jump to the message with the id specified in the `messageId` parameter.
 Here's an example of a button, which, when clicked, searches for a given message and  navigates to it:
 
 ```tsx
@@ -71,7 +71,7 @@ const JumpToMessage = () => {
     <button
       data-testid='jump-to-message'
       onClick={async () => {
-        // the filtering based on channelId is just for example purposes. 
+        // the filtering based on channelId is just for example purposes.
         const results = await chatClient.search(
           {
             id: { $eq: channelId },
@@ -108,77 +108,77 @@ const JumpToMessage = () => {
 The function to load next page/batch of `messages` (used for pagination).
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### loadMoreThread
 
 The function to load next page/batch of `messages` in a currently active/open `Thread` (used for pagination).
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### onMentionsClick
 
 Custom action handler function to execute when @mention is clicked, takes a DOM click event object and an array of mentioned users.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### onMentionsHover
 
 The function to execute when @mention is hovered in a `message`, takes a DOM click event object and an array of mentioned users.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### openThread
 
 The function to execute when replies count button is clicked, takes the parent message of the `Thread` to be opened and a DOM click event.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### removeMessage
 
 The function to remove a `message` from `MessageList`, handled by the `Channel` component. Takes a `message` object.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### retrySendMessage
 
 The function to resend a `message`, handled by the `Channel` component.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### sendMessage
 
 The function to send a `message` on `Channel`. Takes a `message` object with the basic message information as the first argument, and custom data as the second argument.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### setQuoteMessage
 
 The function to send a `QuotedMessage` on a `Channel`, take a `message` object.
 
 | Type     |
-| -------- |
+|----------|
 | function |
 
 ### updateMessage
 
 The function to update a `message` on `Channel`, takes a `message` object.
 
 | Type     |
-| -------- |
+|----------|
 | function |