docs(relase-guides): tmp - new reactions

docusaurus/docs/React/release-guides/new-reactions.mdx

@@ -0,0 +1,135 @@
+# Introducing new reactions (with breaking changes)
+
+As a "move-away-from-EmojiMart" initiative we decided to start with reaction components (selector and list) and revamp the DX to make customization of these components much easier and more intuitive without having to rebuild default selector and list components from scratch.
+
+### Main reasons for a revamp
+
+- inability to reuse default (Stream supplied reactions) with your custom ones
+- strong reliance on EmojiMart and inability to use completely custom reactions out of the box
+- certain `additionalEmojiProps` did not work with Stream-supplied reactions
+
+```tsx
+// not exported directly (hidden, poor DX)
+import { defaultMinimalEmojis } from 'stream-chat-react/dist/components/Channel/emojiData';
+
+// this wouldn't work
+export const customReactions = [
+  {
+    // relies on EmojiMart-supplied sprite sheet, "native" option does not work for Stream-supplied reactions
+    // you'd need to look for supported id's in stream-emoji.json under "emojis" key
+    id: 'bulb',
+  },
+  // unsupported
+  {
+    id: 'rick_roll',
+  },
+  ...defaultMinimalEmojis,
+];
+```
+
+## Default setup and how it works
+
+SDK by default comes with six reaction types (`angry`, `haha`, `like`, `love`, `sad` and `wow`) which are rendered by [`StreamEmoji`]() component which utilises sprite sheet system and renders images for each reaction to make sure it works flawlessly on every system. Default reaction options are defined in [`defaultReactionOptions`]() and these options are reused for both [`ReactionSelector`]() and [`ReactionList`]() (as well as [`SimpleReactionList`]()). These options come by default from the ComponentContext but local component property will be prioritised if defined:
+
+```ts
+contextReactionOptions = defaultReactionOptions;
+// ...
+const reactionOptions = propsReactionOptions ?? contextReactionOptions;
+```
+
+## Custom reaction types and components
+
+It's possible to supply your own reaction types and components to represent such reactions - let's implement reaction of type `rick_roll` to render a Rick Roll GIF:
+
+```tsx
+// mention custom types and components here
+
+const CustomReactionSelector = forwardRef((props, ref) => (
+  <ReactionSelector {...props} ref={ref} reactionOptions={selectorReactions} />
+));
+
+const CustomReactionsList = (props) => <ReactionsList {...props} reactionOptions={listReactions} />;
+```
+
+## EmojiMart integration
+
+If you're used to work with EmojiMart then integrating with new reaction system shouldn't be a big trouble as you can define how your components look and reach for context if you need to - after all, it's just components.
+
+```tsx
+const CustomLikeComponent = () => {
+  // arbitrary EmojiMartContext (does not come with the SDK)
+  const { selectedSkinTones, selectedSet } = useMyEmojiMartContext();
+
+  return <em-emoji id='+1' set={selectedSet} skin={selectedSkinTones['+1']} />;
+};
+
+const reactionOptions = [
+  {
+    type: 'like',
+    component: CustomLikeComponent,
+    name: 'EmojiMart like',
+  },
+];
+
+// pass reaction options to either ReactionSelector or ReactionList or component context (Channel)
+```
+
+## Use of different components for the same reaction types for ReactionSelector and ReactionList components
+
+Either for small changes like this:
+
+```tsx
+const selectorReactionOptions = [
+  {
+    type: 'like',
+    component: ReactionComponent.Like,
+    name: 'Like',
+  },
+];
+
+const listReactionOptions = [
+  {
+    type: 'like',
+    // in this example it's just different size of the emoji, but can be anything you want it to be
+    component: ReactionComponent.LikeMedium,
+    name: 'Like medium',
+  },
+];
+```
+
+Or completely adjusted sets:
+
+```tsx
+// subset of clickable options available to the user
+const selectedReactionOptions = [{ type: 'haha' /* ... */ }, { type: 'cat' /* ... */ }];
+
+// set of all available options to be rendered
+const completeReactionOptions = [
+  { type: 'haha' /* ... */ },
+  { type: 'cat' /* ... */ },
+  { type: '+1' /* ... */ },
+  { type: 'smile' /* ... */ },
+];
+```
+
+## Order ranking (coming from custom context)
+
+## Use of SpriteImage component
+
+## Transition from previous version of custom reactions
+
+The transition is super easy:
+
+```tsx
+// old options
+const reactionOptions = [{ id: 'bulb' /* ...extra properties... */ }, { id: '+1' }, { id: 'joy' }];
+
+// would newly become
+const newReactionOptions = [
+  { type: 'bulb', Component: () => <>💡</>, name: 'Bulb reaction' },
+  { type: '+1', Component: () => <>👍</> },
+  { type: 'joy', Component: () => <>🤣</>, name: 'ROFL' },
+];
+```
+
+All of the extra options previously applied to EmojiMart emojis can now be directly applied to your custom components either manually or through your custom context. For more information see [EmojiMart integration](#emojimart-integration).