docs: Update docs

Author: tjtanjin

docs/api/events.md

@@ -31,6 +31,7 @@ Below is a list of available events with a brief description for each one. You c
 | RcbShowToastEvent           | Emitted when a toast message is displayed.                        |
 | RcbStartStreamMessageEvent  | Emitted when the chatbot starts streaming a message.              |
 | RcbStopStreamMessageEvent   | Emitted when the chatbot stops streaming a message.               |
+| RcbStartSpeakAudioEvent     | Emitted when a message is read out (audio starts to play)         |
 | RcbToggleAudioEvent         | Emitted when the audio is toggled on or off.                      |
 | RcbToggleChatWindowEvent    | Emitted when the chat window is toggled open or closed.           |
 | RcbToggleNotificationsEvent | Emitted when notifications are toggled on or off.                 |
@@ -253,9 +254,12 @@ Emitted before a message is injected into the chat.
 - Event is **preventable** with `event.preventDefault()`.
 
 #### Data
-| Name      | Type      | Description                                                     |
-|-----------|-----------|-----------------------------------------------------------------|
-| message   | `Message` | The message being sent into the chat.                           |
+| Name             | Type                 | Description                                                     |
+|------------------|----------------------|-----------------------------------------------------------------|
+| message          | `Message`            | The message being sent into the chat.                           |
+| simStreamChunker | `function` \| `null` | A custom function to parse messages for simulated streaming     |
+
+Note: The `simStreamChunker` function takes in a string and returns an array of strings. By default, this field is null and strings are split per-character. A custom function can be passed in to control how simulated streaming is carried out. For example, in the implementation of the [**HTML Renderer Plugin**](https://www.npmjs.com/package/@rcb-plugins/html-renderer), a custom function is passed in to skip over html tags when simulating message stream.
 
 #### Code Example
 ```jsx
@@ -428,6 +432,43 @@ const MyComponent = () => {
 };
 ```
 
+### RcbStartSpeakAudioEvent
+
+#### Description
+Emitted when a message is read out (audio starts to play).
+
+#### Note
+- Requires `settings.event.rcbStartSpeakAudio` to be set to true.
+- Event is **preventable** with `event.preventDefault()`.
+
+#### Data
+| Name       | Type      | Description                                                           |
+|------------|-----------|-----------------------------------------------------------------------|
+| textToRead | `string`  | The message string that is to be read out.                            |
+
+#### Code Example
+```jsx
+import { useEffect } from "react";
+import { RcbStartSpeakAudioEvent } from "react-chatbotify";
+
+const MyComponent = () => {
+  useEffect(() => {
+    const handleStartSpeakAudio = (event: RcbStartSpeakAudioEvent) => {
+      // handle the start speak audio event
+    };
+
+    window.addEventListener("rcb-start-speak-audio", handleStartSpeakAudio);
+    return () => {
+      window.removeEventListener("rcb-start-speak-audio", handleStartSpeakAudio);
+    };
+  }, []);
+
+  return (
+    <ExampleComponent/>
+  );
+};
+```
+
 ### RcbToggleAudioEvent
 
 #### Description

docs/api/hooks.md

@@ -156,11 +156,12 @@ const MyNestedComponent = () => {
 The `useChatHistory` hook allows you to show, retrieve and set chat history messages.
 
 #### Return Values
-| Name                | Type       | Description                                                   |
-| ------------------- | ---------- | ------------------------------------------------------------- |
-| showChatHistory     | `function` | Shows the chat history messages on the chatbot.               |
-| getHistoryMessages  | `function` | Retrieves the chat history messages.                          |
-| setHistoryMessages  | `function` | Sets the chat history messages (note that this is permanent). |
+| Name                 | Type       | Description                                                   |
+| -------------------- | ---------- | ------------------------------------------------------------- |
+| showChatHistory      | `function` | Shows the chat history messages on the chatbot.               |
+| getHistoryMessages   | `function` | Retrieves the chat history messages.                          |
+| setHistoryMessages   | `function` | Sets the chat history messages (note that this is permanent). |
+| hasChatHistoryLoaded | `boolean`  | Boolean indicating if chat history has been loaded.           |
 
 #### Code Example
 ```jsx

docs/api/settings.md

@@ -110,15 +110,13 @@ const DefaultSettings: Settings = {
 		avatar: userAvatar,
 		simStream: false,
 		streamSpeed: 30,
-		dangerouslySetInnerHtml: false,
 	},
 	botBubble: {
 		animate: true,
 		showAvatar: false,
 		avatar: botAvatar,
 		simStream: false,
 		streamSpeed: 30,
-		dangerouslySetInnerHtml: false,
 	},
 	voice: {
 		disabled: true,
@@ -298,7 +296,6 @@ Properties here handle the chat bubble for messages sent by the bot.
 | avatar                | `string`                          | -                                            | Image import or URL for the avatar to be displayed for bot chat bubbles.                                                             |                                                                              |
 | simStream                 | `boolean`                         | false                                       | Specifies whether to simulate text messages from the bot as a stream.                                                         |
 | streamSpeed                | `number`                          | 30                                            | Specifies the interval in milliseconds between streaming each character (ignored if `simStream` is false).                                                             |                                                                              |
-| dangerouslySetInnerHtml    | `boolean`                         | false                                       | Specifies whether to allow setting of raw HTML content within a bot message bubble (if `true`, do sanitize input strings and use with caution).                                                         |
 
 ### chatButton
 
@@ -506,7 +503,6 @@ Properties here handle the chat bubble for messages sent by the user.
 | avatar                | `string`                          | -                                            | Image import or URL for the avatar to be displayed for user chat bubbles.                                                            |
 | simStream                 | `boolean`                         | false                                       | Specifies whether to simulate text messages from the user as a stream.                                                         |
 | streamSpeed                | `number`                          | 30                                            | Specifies the interval in milliseconds between streaming each character (ignored if `simStream` is false).                                                             |      
-| dangerouslySetInnerHtml    | `boolean`                         | false                                       | Specifies whether to allow setting of raw HTML content within a user message bubble (if `true`, do sanitize input strings and use with caution).                                                         |
 
 ### voice
 

docs/concepts/conversations.md

@@ -158,12 +158,13 @@ For details and usage on each of these parameters, you may consult the [**API do
 
 Not to be confused with `message` from the section on [**Attributes**](/docs/concepts/conversations#attributes), the `Message` component here represents the interactions between the user and the bot. Every element in the chatbot body (including custom components) are considered a Message (as **outlined in red** on the image above). Within a message you will find **5 properties**: 
 
-- id (required) - an auto-generated uuidv4 `string`, uniquely identifying a message
-- content (required) - a `string` or `JSX.Element`, representing the content of the message
-- contentWrapper (optional) - a react component that wraps the message content (received via children) to enable custom styling or layout (niche use-case)
-- sender (required) - a `string` representing message sender (can be `user`, `bot` or `system`)
-- type (required) - a `string` that specifies "string" (for plain text) or "object" (for JSX elements)
-- timestamp (required) - a `string` representing the time the message was sent in UTC
+- id **(required)** - an auto-generated uuidv4 `string`, uniquely identifying a message
+- content **(required)** - a `string` or `JSX.Element`, representing the content of the message
+- sender **(required)** - a `string` representing message sender (can be `user`, `bot` or `system`)
+- type **(required)** - a `string` that specifies "string" (for plain text) or "object" (for JSX elements)
+- timestamp **(required)** - a `string` representing the time the message was sent in UTC
+- contentWrapper **(optional)** - a react component that wraps the message content (received via children) to enable custom styling or layout (niche use-case)
+- tags **(optional)** - an array of strings, typically used by plugins to tag and identify messages that are processed
 
 :::info Info
 

docs/examples/html_render.md

@@ -0,0 +1,54 @@
+---
+sidebar_position: 17
+title: HTML Render
+description: html render chatbot example
+keywords: [react, chat, chatbot, chatbotify]
+---
+
+# HTML Render
+
+The following is an example showing how you may allow markup syntax (e.g. `<br/>`, `<b>`, `<hr/>`) in user chat bubbles and bot chat bubbles. It leverages on the [**HTML Renderer Plugin**](https://www.npmjs.com/package/@rcb-plugins/html-renderer), which is maintained separately on the [**React ChatBotify Plugins**](https://github.com/orgs/React-ChatBotify-Plugins) organization. If you require support with the plugin, please reach out to support on the [**plugins discord**](https://discord.gg/J6pA4v3AMW) instead.
+
+:::tip
+
+If you're looking to render markdown messages, you may refer to the [**markdown render example**](/docs/examples/markdown_render.md) instead.
+
+:::
+
+```jsx live noInline title=MyChatBot.js
+const MyChatBot = () => {
+	// loads html renderer plugin to be passed into chatbot
+	const plugins = [HtmlRenderer()];
+
+	const flow: Flow = {
+		start: {
+			message: "<b>Hey there, I am a bolded sentence!</b> Try typing a bolded message to me!",
+			path: "reply",
+			renderHtml: ["BOT", "USER"],
+		} as HtmlRendererBlock,
+		reply: {
+			message: "Interesting, let's try again?",
+			options: ["Try again"],
+			chatDisabled: true,
+			path: "start",
+			renderHtml: ["BOT", "USER"],
+		} as HtmlRendererBlock,
+	}
+
+	const settings = {
+		general: {
+			embedded: true
+		},
+		chatHistory: {
+			storageKey: "example_html_render"
+		}
+	}
+
+	return (
+		<ChatBot plugins={plugins} settings={settings} flow={flow}
+		/>
+	);
+};
+
+render(<MyChatBot/>)
+```

docs/examples/markdown_render.md

@@ -9,6 +9,12 @@ keywords: [react, chat, chatbot, chatbotify]
 
 The following is an example for rendering markdown messages. It leverages on the [**Markdown Renderer Plugin**](https://www.npmjs.com/package/@rcb-plugins/markdown-renderer), which is maintained separately on the [**React ChatBotify Plugins**](https://github.com/orgs/React-ChatBotify-Plugins) organization. If you require support with the plugin, please reach out to support on the [**plugins discord**](https://discord.gg/J6pA4v3AMW) instead.
 
+:::tip
+
+If you're looking to render html markup messages, you may refer to the [**html render example**](/docs/examples/html_render.md) instead.
+
+:::
+
 ```jsx live noInline title=MyChatBot.js
 const MyChatBot = () => {
 	// loads markdown renderer plugin to be passed into chatbot

docs/examples/markup_message.md

@@ -22,13 +22,14 @@
     "@docusaurus/theme-live-codeblock": "^3.2.0",
     "@google/generative-ai": "^0.2.1",
     "@mdx-js/react": "^3.0.1",
+    "@rcb-plugins/html-renderer": "^0.1.0",
     "@rcb-plugins/input-validator": "^0.1.1",
-    "@rcb-plugins/markdown-renderer": "^0.1.0",
+    "@rcb-plugins/markdown-renderer": "^0.1.1",
     "clsx": "^1.2.1",
     "openai": "^4.47.1",
     "prism-react-renderer": "^2.3.1",
     "react": "^18.2.0",
-    "react-chatbotify": "^2.0.0-beta.29",
+    "react-chatbotify": "^2.0.0-beta.31",
     "react-dom": "^18.2.0",
     "react-github-btn": "^1.4.0"
   },

package-lock.json

@@ -6,6 +6,7 @@ import ExecutionEnvironment from "@docusaurus/ExecutionEnvironment";
 let ChatBot = null;
 let InputValidator = null;
 let MarkdownRenderer = null;
+let HtmlRenderer = null;
 let reactChatbotify = {};
 
 if (ExecutionEnvironment.canUseDOM) {
@@ -20,6 +21,9 @@ if (ExecutionEnvironment.canUseDOM) {
 
 	// imports rcb plugin - markdown renderer
 	MarkdownRenderer = require("@rcb-plugins/markdown-renderer");
+
+	// imports rcb plugin - html renderer
+	HtmlRenderer = require("@rcb-plugins/html-renderer");
 }
 
 const ReactLiveScope = {
@@ -28,6 +32,7 @@ const ReactLiveScope = {
 	...reactChatbotify,
 	InputValidator,
 	MarkdownRenderer,
+	HtmlRenderer,
 	GoogleGenerativeAI,
 	OpenAI,
 };