@ibti-tech/chatbot 0.1.3 → 0.5.6

package/README.md

@@ -1,36 +1,304 @@
-# IBTI Chatbot
+# @ibti-tech/chatbot
 
-IBTI Chatbot is an assistent designed to provide intelligent responses and assist users effectively according to ibti available data from website and blog.
+A modern and customizable React chatbot component developed by IBTI Soluções em TI. This package provides an intelligent conversational interface that can be easily integrated into any React application.
 
-## How to use on your project
+## 📋 Features
 
-1. Install using yarn or npm
+- 🎨 **Customizable themes**: Support for light and dark themes
+- 🌍 **Internationalization**: Support for Brazilian Portuguese (pt-BR) and English (en)
+- 💬 **Modern interface**: Responsive and intuitive design
+- ⚡ **Optimized performance**: Built with ESBuild for maximum performance
+- 🔌 **Easy integration**: Simple React component to use
+- 📱 **Responsive**: Works perfectly on desktop and mobile
 
-```sh
-  yarn add @ibti-tech/chatbot | npm install @ibti-tech/chatbot
+## 📦 Installation
+
+Install the package using yarn or npm:
+
+```bash
+# Using yarn
+yarn add @ibti-tech/chatbot
+
+# Using npm
+npm install @ibti-tech/chatbot
 ```
 
-2. Import Chatbot component into your react application and use it as a component
+## 🚀 Basic Usage
+
+### Import
 
 ```jsx
-import { Chatbot } from '@ibti-tech/chatbot'
+import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
 ```
 
-3. Use the component
+### Minimal Example
 
 ```jsx
-// {...}
-const MyFunctionalComponent = () => {
+import React from 'react'
+import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
+
+function App() {
   return (
-    <div>
+    <ChatbotProvider
+      locale="pt-BR"
+      apiURL="https://api.example.com"
+      theme="dark"
+    >
+      <ChatbotBar />
+    </ChatbotProvider>
+  )
+}
+
+export default App
+```
+
+## 📚 Available Components
+
+### `ChatbotProvider`
+
+Context component that provides chatbot configuration and state to child components.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `locale` | `'pt-BR' \| 'en'` | ✅ | Chatbot interface language |
+| `apiURL` | `string` | ✅ | Chatbot backend API URL |
+| `theme` | `'light' \| 'dark'` | ✅ | Chatbot visual theme |
+| `isOpen` | `boolean` | ❌ | Controls if the chatbot is initially open. Default: `false` |
+| `texts` | `ChatbotTypes.Texts` | ❌ | Custom texts to override default translations. See [Custom Texts](#custom-texts) section |
+| `children` | `ReactNode` | ❌ | Child components to be rendered |
+
+### `ChatbotBar`
+
+Main component that displays the chatbot bar with toggle button and conversation interface.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `verticalPosition` | `'top' \| 'bottom'` | ❌ | Vertical position of the chatbot. Default: `'bottom'` |
+| `horizontalPosition` | `'left' \| 'right'` | ❌ | Horizontal position of the chatbot. Default: `'right'` |
+
+### `ChatbotDevice`
+
+Alternative component that can be used to display the chatbot on different devices or layouts.
+
+#### Props
+
+| Prop | Type | Required | Description |
+|------|------|----------|-------------|
+| `verticalPosition` | `'top' \| 'bottom'` | ❌ | Vertical position of the chatbot. Default: `'bottom'` |
+
+## 🎨 Themes
+
+The chatbot supports two themes:
+
+- **`light`**: Light theme with bright colors
+- **`dark`**: Dark theme with dark colors
+
+```jsx
+<ChatbotProvider theme="dark" ...>
+  <ChatbotBar />
+</ChatbotProvider>
+```
+
+## 🌍 Localization
+
+The chatbot supports the following languages:
+
+- **`pt-BR`**: Brazilian Portuguese
+- **`en`**: English
+
+```jsx
+<ChatbotProvider locale="pt-BR" ...>
+  <ChatbotBar />
+</ChatbotProvider>
+```
+
+### Custom Texts
+
+You can customize all texts in the chatbot interface by passing a `texts` prop to `ChatbotProvider`. This allows you to override default translations for any locale.
+
+```jsx
+<ChatbotProvider
+  locale="pt-BR"
+  apiURL="https://api.example.com"
+  theme="dark"
+  texts={{
+    'pt-BR': {
+      CHATBOT_NAME: 'Meu Assistente',
+      INPUT_PLACEHOLDER: 'Digite sua mensagem...',
+      CHATBOT_BAR: {
+        OPEN: 'Abrir chat',
+        CLOSE: 'Fechar chat',
+      },
+      CHAT_FEEDBACK: {
+        TITLE: 'Avalie esta resposta',
+        DESCRIPTION: 'Sua opinião nos ajuda a melhorar',
+        MESSAGE_FIELD: 'Mensagem (opcional)',
+        SUBMIT_BUTTON: 'Enviar',
+        CLOSE_BUTTON: 'Fechar',
+        RATE: 'Avaliar',
+      },
+      SUGGESTED_QUESTIONS: {
+        TITLE: 'Perguntas sugeridas',
+        LOADING: 'Carregando...',
+      },
+      STATUS: {
+        ONLINE: 'Online',
+        LOADING: 'Carregando',
+        WRITING: 'Digitando...',
+        UNAVAILABLE: 'Indisponível',
+        INACTIVE: 'Inativo',
+      },
+      ERRORS: {
+        UNKNOWN: 'Erro desconhecido',
+      },
+      MESSAGE_ACTIONS: {
+        COPY: 'Copiar',
+        SHARE: 'Compartilhar',
+        RESEND: 'Reenviar',
+      },
+      USER_LABEL: 'Você',
+      WRITING_MESSAGE: 'Digitando...',
+    },
+    'en': {
+      CHATBOT_NAME: 'My Assistant',
+      // ... other custom texts
+    },
+  }}
+>
+  <ChatbotBar />
+</ChatbotProvider>
+```
+
+**Available text keys:**
+- `CHATBOT_NAME`: Name displayed in the chatbot header
+- `INPUT_PLACEHOLDER`: Placeholder text for the input field
+- `CHATBOT_BAR.OPEN`: Text for opening the chatbot
+- `CHATBOT_BAR.CLOSE`: Text for closing the chatbot
+- `CHAT_FEEDBACK.*`: All feedback form texts
+- `SUGGESTED_QUESTIONS.*`: Suggested questions section texts
+- `STATUS.*`: Status indicator texts
+- `ERRORS.*`: Error message texts
+- `MESSAGE_ACTIONS.*`: Message action button texts
+- `USER_LABEL`: Label for user messages
+- `WRITING_MESSAGE`: Text shown when the bot is typing
+
+## 📝 Complete Example
+
+```jsx
+import React from 'react'
+import { ChatbotProvider, ChatbotBar } from '@ibti-tech/chatbot'
+
+function MyApp() {
+  return (
+    <div className="app">
+      <h1>My Application</h1>
+      
+      {/* Other components of your application */}
+      
       <ChatbotProvider
         locale="pt-BR"
-        apiURL="http://localhost:6061"
+        apiURL={process.env.REACT_APP_CHATBOT_API_URL || "http://localhost:6061"}
         theme="dark"
+        isOpen={false}
       >
-        <ChatbotBar />
+        <ChatbotBar 
+          verticalPosition="bottom"
+          horizontalPosition="right"
+        />
       </ChatbotProvider>
     </div>
   )
 }
+
+export default MyApp
+```
+
+## 🎛️ Advanced Configuration
+
+### Positioning the Chatbot
+
+You can control the position of the chatbot using the `ChatbotBar` component props:
+
+```jsx
+// Bottom right (default)
+<ChatbotBar />
+
+// Top right
+<ChatbotBar verticalPosition="top" />
+
+// Bottom left
+<ChatbotBar horizontalPosition="left" />
+
+// Top left
+<ChatbotBar 
+  verticalPosition="top" 
+  horizontalPosition="left" 
+/>
+```
+
+### Controlling Initial State
+
+Use the `isOpen` prop to control whether the chatbot starts open or closed:
+
+```jsx
+<ChatbotProvider
+  locale="pt-BR"
+  apiURL="https://api.example.com"
+  theme="dark"
+  isOpen={true}  // Chatbot starts open
+>
+  <ChatbotBar />
+</ChatbotProvider>
 ```
+
+## 🔧 Requirements
+
+### Peer Dependencies
+
+This package requires the following dependencies that must be installed in your project:
+
+- `react`: `^18.2.0`
+- `react-dom`: `^18.2.0`
+- `lodash`: `^4.17.21`
+- `nookies`: `^2.5.2`
+
+Make sure these dependencies are installed:
+
+```bash
+yarn add react react-dom lodash nookies
+# or
+npm install react react-dom lodash nookies
+```
+
+## 📡 Backend API
+
+The chatbot expects the backend API to be configured and accessible at the provided URL. The API must implement the necessary endpoints for:
+
+- Sending messages
+- Receiving responses
+- Managing conversation history
+- Suggested questions
+
+## 🐛 Issues and Support
+
+If you encounter any issues or have questions:
+
+1. Check the [complete documentation](https://github.com/ibti-solutions/ibti-chatbot)
+2. Open an [issue on GitHub](https://github.com/ibti-solutions/ibti-chatbot/issues)
+3. Contact the IBTI team
+
+## 📄 License
+
+ISC
+
+## 👥 Author
+
+IBTI Soluções em TI
+
+---
+
+For more information about development and contribution, see the [DEV_NOTES.md](./DEV_NOTES.md) file.