Merge pull request #159 from GetStream/mention-enhancement

Mention enhancement

Author: szuperaz

docusaurus/docs/Angular/assets/mention-screenshot.png

@@ -0,0 +1,4 @@
+{
+  "label": "Code examples",
+  "position": 6
+}

docusaurus/docs/Angular/code-examples/_category_.json

@@ -0,0 +1,138 @@
+---
+id: mention-actions
+sidebar_position: 1
+title: Mention actions
+---
+
+import Screenshot from "../assets/mention-screenshot.png";
+
+In this example, we will demonstrate how to create custom mention actions if a user clicks on or hovers over a mention in a message.
+
+## Custom mention template
+
+You can provide a custom message template to the `MessageList` component:
+
+```html
+<div id="root">
+  <stream-channel-list></stream-channel-list>
+  <stream-channel>
+    <stream-channel-header></stream-channel-header>
+    <stream-message-list
+      [mentionTemplate]="mentionTemplate"
+    ></stream-message-list>
+    <stream-notification-list></stream-notification-list>
+    <stream-message-input></stream-message-input>
+  </stream-channel>
+</div>
+
+<ng-template #mentionTemplate let-user="user">
+  <b>@{{ user.name || user.id }}</b>
+</ng-template>
+```
+
+The `MessageList` component will provide the mentioned user in a variable called `user`, the object has a [`UserResponse`](https://github.com/GetStream/stream-chat-js/blob/master/src/types.ts) type and you can use it to display information about the user.
+
+This template looks and works like the default mention template, however you can add interactions to this element.
+
+## Display user information on click
+
+In this step we will create a popover with additional user information that will be displayed if the user clicks on a mention. We are using the [`ngx-popperjs`](https://www.npmjs.com/package/ngx-popperjs) library for the popover, but you can use a different library as well.
+
+### Install `ngx-popperjs`
+
+Let's install the necessary dependencies:
+
+```bash
+npm install @popperjs/core ngx-popperjs --save
+```
+
+### Import the `NgxPopperjsModule` module
+
+```typescript
+import {NgxPopperjsModule} from 'ngx-popperjs';
+
+@NgModule({
+ // ...
+ imports: [
+   // ...
+   NgxPopperjsModule
+ ]
+})
+```
+
+### Import SCSS
+
+Add this to your `styles.scss`:
+
+```scss
+@import "~ngx-popperjs/scss/theme-white";
+```
+
+[CSS is also supported.](https://www.npmjs.com/package/ngx-popperjs)
+
+### Create the popover
+
+```html
+<ng-template #mentionTemplate let-user="user">
+  <span
+    style="cursor: pointer"
+    [popper]="popperContent"
+    [popperPositionFixed]="true"
+  >
+    <b>@{{ user.name || user.id }}</b>
+  </span>
+  <popper-content #popperContent style="display: inline">
+    <div style="display: flex; align-items: center">
+      <stream-avatar
+        [imageUrl]="user.image"
+        [name]="user.name || user.id"
+      ></stream-avatar>
+      <b>{{ user.name || user.id }}</b>
+      <span>&nbsp;{{ user.online ? "online" : "offline" }}</span>
+    </div>
+  </popper-content>
+</ng-template>
+```
+
+This is the popover that is displayed if we click on a mention in a message:
+
+<img src={Screenshot} width="500" />
+
+[`ngx-popperjs`](https://www.npmjs.com/package/ngx-popperjs) has a lot of other configuration options, feel free to explore those.
+
+## Display user information on hover
+
+Let's modify our solution and display the popover on hover instead of click:
+
+We need to add a variable to our component class:
+
+```typescript
+import { NgxPopperjsTriggers } from "ngx-popperjs";
+
+popoverTrigger = NgxPopperjsTriggers.hover;
+```
+
+And modify our template:
+
+```html
+<ng-template #mentionTemplate let-user="user">
+  <span
+    style="cursor: pointer"
+    [popper]="popperContent"
+    [popperPositionFixed]="true"
+    [popperTrigger]="popoverTrigger"
+  >
+    <b>@{{ user.name || user.id }}</b>
+  </span>
+  <popper-content #popperContent style="display: inline">
+    <div style="display: flex; align-items: center">
+      <stream-avatar
+        [imageUrl]="user.image"
+        [name]="user.name || user.id"
+      ></stream-avatar>
+      <b>{{ user.name || user.id }}</b>
+      <span>&nbsp;{{ user.online ? "online" : "offline" }}</span>
+    </div>
+  </popper-content>
+</ng-template>
+```

docusaurus/docs/Angular/code-examples/mention-actions.mdx

@@ -27,6 +27,8 @@ The channel list uses the `ChannelPreview` component to display channels, if you
 </ng-template>
 ```
 
+Your custom template can receive the same inputs (with the same name) as the default `ChannelPreview` component.
+
 :::note
 
 If you want to build your own `ChannelPreview` component, you might find the following building blocks useful:

docusaurus/docs/Angular/components/channel-preview.mdx

@@ -38,6 +38,8 @@ If you want to create your own message input, here is how to use it:
 
 The default chat UI uses the message input in two different places: at the bottom of the channel to send new message, and in the message list to edit a message.
 
+Your custom template can receive the same inputs (with the same name) as the default `MessageInput` component.
+
 :::note
 If you want to create your own message input, you can use the following building blocks:
 

docusaurus/docs/Angular/components/message-input.mdx

@@ -67,6 +67,14 @@ The input used for message edit. By default, the [default message input componen
 | ----------- |
 | TemplateRef |
 
+### mentionTemplate
+
+The template used to display a mention in a message. It receives the mentioned user in a variable called `user` with the type [`UserResponse`](https://github.com/GetStream/stream-chat-js/blob/master/src/types.ts). You can provide your own template if you want to [add actions to mentions](../code-examples/mention-actions.mdx).
+
+| Type        |
+| ----------- |
+| TemplateRef |
+
 ### areReactionsEnabled
 
 If true, the message reactions are displayed. Users can also react to messages if they have the necessary [channel capability](https://getstream.io/chat/docs/javascript/channel_capabilities/?language=javascript).

docusaurus/docs/Angular/components/message-list.mdx

@@ -53,6 +53,8 @@ The message list uses the `Message` component to display messages, if you want t
 </ng-template>
 ```
 
+Your custom template can receive the same inputs (with the same name) as the default `Message` component.
+
 :::note
 
 If you want to build your own `Message` component, you might find the following building blocks useful:
@@ -157,3 +159,11 @@ The input used for message edit. By default, the [default message input componen
 | Type        |
 | ----------- |
 | TemplateRef |
+
+### mentionTemplate
+
+The template used to display a mention in a message. It receives the mentioned user in a variable called `user` with the type [`UserResponse`](https://github.com/GetStream/stream-chat-js/blob/master/src/types.ts). You can provide your own template if you want to [add actions to mentions](../code-examples/mention-actions.mdx).
+
+| Type        |
+| ----------- |
+| TemplateRef |

docusaurus/docs/Angular/components/message.mdx

@@ -27,7 +27,8 @@
                   lastSentMessageId && message?.id === lastSentMessageId
                 ),
                 canReceiveReadEvents: canReceiveReadEvents,
-                messageInputTemplate: messageInputTemplate
+                messageInputTemplate: messageInputTemplate,
+                mentionTemplate: mentionTemplate
               }
             "
           ></ng-container>
@@ -43,6 +44,7 @@
             [enabledMessageActions]="enabledMessageActions"
             [canReceiveReadEvents]="canReceiveReadEvents"
             [messageInputTemplate]="messageInputTemplate"
+            [mentionTemplate]="mentionTemplate"
           ></stream-message>
         </ng-template>
       </li>