Merge pull request #705 from GetStream/usePinHandler-docs

adds docs for usePinHandler

Author: DanC5

CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [4.0.1](https://github.com/GetStream/stream-chat-react/releases/tag/v4.0.1) 2021-02-11
+
+**NOTE: breaking changes in v4.0.0, this follow-up version patches the docs**
+
+### Feature
+
+- Add `usePinHandler` example to docs [#705](https://github.com/GetStream/stream-chat-react/pull/705)
+
+### Bug
+
+- Remove legacy APIs in mock data used for generating the docs [#704](https://github.com/GetStream/stream-chat-react/pull/704)
+
 ## [4.0.0](https://github.com/GetStream/stream-chat-react/releases/tag/v4.0.0) 2021-02-10
 
 ### ⚠️ BREAKING CHANGES ⚠️

src/docs/useFlagHandler.md

@@ -21,5 +21,4 @@ const MyCustomMessageComponent = (props) => {
     </div>
   );
 };
-`
 ```

src/docs/useMuteHandler.md

@@ -20,5 +20,4 @@ const MyCustomMessageComponent = (props) => {
     </div>
   );
 };
-`
 ```

src/docs/useOpenThreadHandler.md

@@ -22,5 +22,4 @@ const MyCustomMessageComponent = (props) => {
     </div>
   );
 };
-`
 ```

src/docs/usePinHandler.md

@@ -0,0 +1,35 @@
+A custom hook to handle message pinning. It provides the permission status of the connected user and a function to toggle pinned status on the message.
+
+| Parameter                            | Type                                                     | Description                                                     |
+| ------------------------------------ | -------------------------------------------------------- | --------------------------------------------------------------- |
+| `message`                            | [object](https://getstream.io/chat/docs/#message_format) | The message to be handled.                                      |
+| `permissions`                        | object                                                   | The user roles allowed to pin messages in various channel types |
+| `notifications`                      | object                                                   | An object containing the following properties:                  |
+| `notifications.notify`               | func                                                     | A function that adds notification text to message               |
+| `notifications.getErrorNotification` | func                                                     | A function that returns an error message                        |
+
+It returns the following object:
+
+| Parameter   | Type    | Description                                        |
+| ----------- | ------- | -------------------------------------------------- |
+| `canPin`    | boolean | Whether or not the connected user can pin messages |
+| `handlePin` | func    | Function to toggle the pinned status of a message  |
+
+```json
+import { usePinHandler } from 'stream-chat-react';
+const MyCustomMessageComponent = (props) => {
+  const { addNotification, getPinMessageErrorNotification, message, pinPermissions } = props;
+  const { canPin, handlePin } = usePinHandler(message, pinPermissions, {
+    notify: addNotification,
+    getErrorNotification: getPinMessageErrorNotification,
+  });
+  const handleClick = () => {
+    if (canPin) handlePin(message);
+  }
+  return (
+    <div className={message.pinned ? 'pinned' : ''} onClick={handleClick}>
+      <p>{message.text}</p>
+    </div>
+  );
+};
+```

src/docs/useReactionHandler.md

@@ -22,5 +22,4 @@ const MyCustomMessageComponent = (props) => {
     </div>
   );
 };
-`
 ```

src/docs/useRetryHandler.md

@@ -29,5 +29,4 @@ const MyCustomMessageComponent = (props) => {
     </div>
   );
 };
-`
 ```

styleguide.config.js

@@ -81,6 +81,10 @@ module.exports = {
               name: 'useOpenThreadHandler',
               content: 'src/docs/useOpenThreadHandler.md',
             },
+            {
+              name: 'usePinHandler',
+              content: 'src/docs/usePinHandler.md',
+            },
             {
               name: 'useReactionHandler',
               content: 'src/docs/useReactionHandler.md',