Merge pull request #169 from Wolox/update-docs

Update docs
Wolox · Apr 15, 2020 · 8076feb · 8076feb
2 parents 4705a23 + 5dd5677
commit 8076feb
Show file tree

Hide file tree

Showing 6 changed files with 138 additions and 76 deletions.
diff --git a/LICENSE b/LICENSE
@@ -1,4 +1,4 @@
-  Copyright (c) 2017 Martín Callegari <martin.callegari@wolox.com.ar>
+  Copyright (c) 2020 Martín Callegari <martin.callegari@wolox.com.ar>
 
   Permission is hereby granted, free of charge, to any person obtaining a copy
   of this software and associated documentation files (the "Software"), to deal

diff --git a/README.md b/README.md
@@ -52,19 +52,17 @@ yarn add react-chat-widget
 1- Add the Widget component to your root component
 
 ```js
-import React, { Component } from 'react';
+import React from 'react';
 import { Widget } from 'react-chat-widget';
 
 import 'react-chat-widget/lib/styles.css';
 
-class App extends Component {
-  render() {
-    return (
-      <div className="App">
-        <Widget />
-      </div>
-    );
-  }
+function App() {
+  return (
+    <div className="App">
+      <Widget />
+    </div>
+  );
 }
 
 export default App;
@@ -73,26 +71,24 @@ export default App;
 2- The only required prop you need to use is the `handleNewUserMessage`, which will receive the input from the user.
 
 ```js
-import React, { Component } from 'react';
+import React from 'react';
 import { Widget } from 'react-chat-widget';
 
 import 'react-chat-widget/lib/styles.css';
 
-class App extends Component {
-  handleNewUserMessage = (newMessage) => {
+function App() {
+  const handleNewUserMessage = (newMessage) => {
     console.log(`New message incoming! ${newMessage}`);
     // Now send the message throught the backend API
-  }
+  };
 
-  render() {
-    return (
-      <div className="App">
-        <Widget
-          handleNewUserMessage={this.handleNewUserMessage}
-        />
-      </div>
-    );
-  }
+  return (
+    <div className="App">
+      <Widget
+        handleNewUserMessage={handleNewUserMessage}
+      />
+    </div>
+  );
 }
 
 export default App;
@@ -101,31 +97,29 @@ export default App;
 3- Import the methods for you to add messages in the Widget. (See [messages](#messages))
 
 ```js
-import React, { Component } from 'react';
+import React from 'react';
 import { Widget, addResponseMessage } from 'react-chat-widget';
 
 import 'react-chat-widget/lib/styles.css';
 
-class App extends Component {
-  componentDidMount() {
-    addResponseMessage("Welcome to this awesome chat!");
-  }
+function App() {
+  useEffect(() => {
+    addResponseMessage('Welcome to this awesome chat!');
+  }, []);
 
-  handleNewUserMessage = (newMessage) => {
+  const handleNewUserMessage = (newMessage) => {
     console.log(`New message incoming! ${newMessage}`);
     // Now send the message throught the backend API
     addResponseMessage(response);
-  }
+  };
 
-  render() {
-    return (
-      <div className="App">
-        <Widget
-          handleNewUserMessage={this.handleNewUserMessage}
-        />
-      </div>
-    );
-  } 
+  return (
+    <div className="App">
+      <Widget
+        handleNewUserMessage={handleNewUserMessage}
+      />
+    </div>
+  );
 }
 
 export default App;
@@ -134,28 +128,28 @@ export default App;
 4- Customize the widget to match your app design! You can add both props to manage the title of the widget and the avatar it will use. Of course, feel free to change the styles the widget will have in the CSS
 
 ```js
-import React, { Component } from 'react';
+import React from 'react';
 import { Widget, addResponseMessage, addLinkSnippet, addUserMessage } from 'react-chat-widget';
 
 import 'react-chat-widget/lib/styles.css';
 
 import logo from './logo.svg';
 
-class App extends Component {
-  componentDidMount() {
-    addResponseMessage("Welcome to this awesome chat!");
-  }
+function App() {
+  useEffect(() => {
+    addResponseMessage('Welcome to this awesome chat!');
+  }, []);
 
-  handleNewUserMessage = (newMessage) => {
+  const handleNewUserMessage = (newMessage) => {
     console.log(`New message incoming! ${newMessage}`);
     // Now send the message throught the backend API
-  }
+  };
 
   render() {
     return (
       <div className="App">
         <Widget
-          handleNewUserMessage={this.handleNewUserMessage}
+          handleNewUserMessage={handleNewUserMessage}
           profileAvatar={logo}
           title="My new awesome title"
           subtitle="And my cool subtitle"
@@ -172,20 +166,25 @@ export default App;
 
 #### Props
 
-|   |type|required|default value|description|
+|prop|type|required|default value|description|
 |---|--- |---     |---          |---        |
-|**handleNewUserMessage**|PropTypes.func|YES| |Function to handle the user input, will receive the full text message when submitted|
-|**title**|PropTypes.string|NO|'Welcome'|Title of the widget|
-|**subtitle**|PropTypes.string|NO|'This is your chat subtitle'|Subtitle of the widget|
-|**senderPlaceHolder**|PropTypes.string|NO|'Type a message...'|The placeholder of the message input|
-|**profileAvatar**|PropTypes.string|NO| |The profile image that will be set on the responses|
-|**titleAvatar**|PropTypes.string|NO| |The picture image that will be shown next to the chat title|
-|**showCloseButton**|PropTypes.bool|NO|false|Show or hide the close button in full screen mode|
-|**fullScreenMode**|PropTypes.bool|NO|false|Allow the use of full screen in full desktop mode|
-|**badge**|PropTypes.number|NO|0|Display a notification badge on the launcher if the value is greater than 0|
-|**autofocus**|PropTypes.bool|NO|true|Autofocus or not the user input|
-|**launcher**|PropTypes.func|NO||Custom Launcher component to use instead of the default|
-|**handleQuickButtonClicked**|PropTypes.func|NO||Function to handle the user clicking a quick button, will receive the 'value' when clicked.|
+|**handleNewUserMessage**|(...args: any[]) => any|YES| |Function to handle the user input, will receive the full text message when submitted|
+|**title**|string|NO|'Welcome'|Title of the widget|
+|**subtitle**|string|NO|'This is your chat subtitle'|Subtitle of the widget|
+|**senderPlaceHolder**|string|NO|'Type a message...'|The placeholder of the message input|
+|**profileAvatar**|string|NO| |The profile image that will be set on the responses|
+|**titleAvatar**|string|NO| |The picture image that will be shown next to the chat title|
+|**showCloseButton**|boolean|NO|false|Show or hide the close button in full screen mode|
+|**fullScreenMode**|boolean|NO|false|Allow the use of full screen in full desktop mode|
+|**autofocus**|boolean|NO|true|Autofocus or not the user input|
+|**launcher**|(handleToggle) => ElementType|NO||Custom Launcher component to use instead of the default|
+|**handleQuickButtonClicked**|(...args: any[]) => any|NO||Function to handle the user clicking a quick button, will receive the 'value' when clicked.|
+|**showTimeStamp**|boolean|NO|true|Show time stamp on messages|
+|**chatId**|string|NO|'rcw-chat-container'|Chat container id for a11y|
+|**launcherOpenLabel**|string|NO|'Open chat'|Alt value for the laucher when closed|
+|**launcherCloseLabel**|string|NO|'Close chat'|Alt value for the laucher when open|
+|**sendButtonAlt**|string|NO|'Send'|Send button alt for a11y purposes|
+|**handleTextInputChange**|(event) => any|NO| |Prop that triggers on input change|
 
 #### Styles
 
@@ -207,22 +206,24 @@ That way, you can leave the JS clean and keep the styles within the CSS.
 
 #### Messages
 
-If you want to add new messages, you can use the following methods:
+As of v3.0, messages now have an optional ID that can be added on creation.If you want to add new messages, you can use the following methods:
 
 - **addResponseMessage**
   - params:
-    - text
+    - text: string
+    - id: string (optional)
   - Method to add a new message written as a response to a user input.
 
 - **addUserMessage**
   - params: 
-    - text
+    - text: string
+    - id: string (optional)
   - This method will add a new message written as a user. Keep in mind it will not trigger the prop handleNewUserMessage()
 
 - **addLinkSnippet**
   - params:
     - link
-  - Method to add a link snippet. For now, you need to provide this method with a link object, which must be in the shape of:
+  - Method to add a link snippet. You need to provide this method with a link object, which must be in the shape of:
     ```js
     {
       title: 'My awesome link',
@@ -238,11 +239,12 @@ If you want to add new messages, you can use the following methods:
     - props: props the component needs,
     - showAvatar: boolean, default value: false; the component will be rendered with the avatar like the messages
   - Method to render a custom component inse the messages container. With this method, you can add whatever component you need the widget to have.
+
 - **setQuickButtons**
   - params:
     - buttons: An array of objects with the keys `label` and `value`
 
-**Markdown is supported for the responses and user messages.**
+**Markdown is supported for both the responses and user messages.**
 
 #### Widget behavior
 
@@ -256,26 +258,50 @@ You can also control certain actions of the widget:
   - params: No params expected
   - Method to toggle the availability of the message input for the user to write on
 
+- **toggleMsgLoader**
+  - Toggles the message loader that shows as a "typing..." style.
+
+- **deleteMessages***
+  - params:
+    - count: messages to delete counting from last to first
+    - id: message id to delete
+  - Delete messages that either have an id you previously set with the `addResponseMessage` or delete based on position or both of them. For example `deleteMessages(2, 'myId')` will delete the message that has the id `myId` and the previous message.
+
+- **markAllAsRead**
+  - Marks all response messages as read. The user messages doesn't have the read/unread property.
+
+- **setBadgeCount**
+  - params:
+    - count: number
+  - As of v3.0, the `badge` prop is being changed to be managed from within the Widget. This method is manually set the badge number.
+
 #### Widget components
 
 ##### Custom Launcher
 
-You can use a custom component for the Launcher if you need one that's not the default, simply use the **launcher** prop like:
+You can use a custom component for the Launcher if you need one that's not the default, simply use the **launcher** prop:
 
 ```js
-  launcher={handleToggle => this.getCustomLauncher(handleToggle)}
-```
+import React from 'react';
+import { Wdiget } from 'react-chat-widget';
 
-`getCustomLauncher()` is a method that will return the `Launcher` component. By default, the function passed by that prop, will receive the `handleToggle` parameter which is the method that will toggle the widget.
+...
 
-For example, if you want to use a simple button to toggle the widget:
+function MyApp() {
+  const getCustomLaucher = (handleToggle) =>
+    <button onClick={handleToggle}>This is my launcher component!</button>
 
-```js
-  launcher={handleToggle => (
-    <button onClick={handleToggle}>Toggle</button>
-  )}
+  return (
+    <Widget
+      ...
+      launcher={handleToggle => getCustomLauncher(handleToggle)}
+    />
+  )
+}
 ```
 
+`getCustomLauncher()` is a method that will return the `Launcher` component as seen in the example. By default, the function passed by that prop, will receive the `handleToggle` parameter which is the method that will toggle the widget.
+
 ## About
 
 This project is maintained by [Martín Callegari](https://github.com/mcallegari10) and it was written by [Wolox](http://www.wolox.com.ar).

diff --git a/index.d.ts b/index.d.ts
@@ -0,0 +1,35 @@
+// Type definitions for react-chat-widget v3.0.0
+// Project: <https://github.com/Wolox/react-chat-widget>
+// Definitions by: Martín Callegari <https://github.com/mcallegari10>
+
+import { ElementType } from 'react';
+
+declare const Widget: ElementType;
+
+export function addUserMessage(text: string): void;
+export function addUserMessage(text: string, id: string): void;
+
+export function addResponseMessage(text: string): void;
+export function addResponseMessage(text: string, id: string): void;
+
+export function addLinkSnippet(link: { link: string, title: string, target?: string }): void;
+export function addLinkSnippet(link: { link: string, title: string, target?: string }, id: string): void;
+
+export function renderCustomComponent(component: ElementType, props: any): void;
+export function renderCustomComponent(component: ElementType, props: any, showAvatar: boolean): void;
+export function renderCustomComponent(component: ElementType, props: any, showAvatar: boolean, id: string): void;
+
+export function toggleMsgLoader(): void;
+export function toggleWidget(): void;
+export function toggleInputDisabled(): void;
+export function dropMessages(): void;
+export function isWidgetOpened(): boolean;
+export function setQuickButtons(buttons: Array<{ label: string, value: string | number }>): void;
+
+export function deleteMessages(count: number): void;
+export function deleteMessages(count: number, id: string): void;
+
+export function markAllAsRead(): void;
+export function setBadgeCount(count: number): void;
+
+export as namespace ReactChatWidget;
diff --git a/package.json b/package.json
@@ -6,6 +6,7 @@
   "repository": "git@github.com:Wolox/react-chat-widget.git",
   "author": "Martín Callegari <martin.callegari@wolox.com.ar>",
   "license": "MIT",
+  "types": "./lib/index.d.ts",
   "scripts": {
     "start": "webpack-dev-server --config webpack.config.dev.js",
     "build": "webpack --config ./webpack.config.prod.js",

diff --git a/src/components/Widget/index.tsx b/src/components/Widget/index.tsx
@@ -17,7 +17,7 @@ type Props = {
   autofocus: boolean;
   customLauncher?: AnyFunction;
   handleNewUserMessage: AnyFunction;
-  handleQuickButtonClicked: AnyFunction;
+  handleQuickButtonClicked?: AnyFunction;
   handleTextInputChange?: (event: any) => void;
   chatId: string;
   launcherOpenLabel: string;

diff --git a/src/index.tsx b/src/index.tsx
@@ -9,7 +9,7 @@ import { AnyFunction } from './utils/types';
 
 type Props = {
   handleNewUserMessage: AnyFunction;
-  handleQuickButtonClicked: AnyFunction;
+  handleQuickButtonClicked?: AnyFunction;
   title?: string;
   titleAvatar?: string;
   subtitle?: string;