blixify-ui-web-mcp 0.1.1 → 0.1.3

package/lib/components/chat/chatBase/README.md

@@ -4,220 +4,187 @@
 
 <hr>
 
-Chat Base
+A chat window component with message bubbles, markdown rendering for received messages, message search, file upload (image/video), a loading reply indicator, and customisable header/footer/body slots.
 
 ##### Import
 
 ```js
-import { ChatBase } from "blixify-ui-web/components/chat/chatBase";
+import {
+  ChatBase,
+  Conversation,
+  Message,
+  User,
+} from "blixify-ui-web/components/chat/chatBase";
 ```
 
 ##### Usage
 
-```tsx
+Basic chat:
+
+```jsx
 const [message, setMessage] = useState("");
-const [search, setSearch] = useState("");
-const [filteredConversation, setFilteredConversation] =
-  useState<Conversation | null>();
-const [conversation, setConversation] = useState<Conversation>({
-  id: "1",
-  members: [currentUser, botUser],
-  messageList: [
-    {
-      sender: botUser,
-      messageBody: "Hi! How can I help you? 🤖",
-      createdAt: moment(
-        "Fri Nov 03 2023 12:21:14 GMT+0800 (Malaysia Time)"
-      ).toDate(),
-    },
-    {
-      sender: currentUser,
-      messageBody: "Yo, my computer's acting up.",
-      createdAt: moment(
-        "Fri Nov 03 2023 13:21:14 GMT+0800 (Malaysia Time)"
-      ).toDate(),
-    },
-  ],
-});
-
-const handleOnSendMessage = (conversation: Conversation) => {
-  setConversation(conversation);
-  setMessage("");
-};
-
-const handleOnSearch = (searchMessage: string) => {
-  if (searchMessage.length === 0) {
-    setSearch("");
-    setFilteredConversation(null);
-  } else {
-    const dupMessageList = conversation.messageList.filter((eachMessage) => {
-      return eachMessage.messageBody
-        .toLowerCase()
-        .includes(searchMessage.toLowerCase());
-    });
-    const dupConversation = {
-      id: conversation.id,
-      members: [...conversation.members],
-      messageList: [...dupMessageList],
-    };
-    setFilteredConversation(dupConversation);
-  }
-};
-
-const handleOnClearMessage = () => {
-  setFilteredConversation(null);
-  setConversation({
+const [conversation, setConversation] =
+  useState <
+  Conversation >
+  {
     id: "1",
     members: [currentUser, botUser],
-    messageList: [],
-  });
-};
-
-const headerElement = (
-  <div className="p-2 bg-primary-500 rounded-t-md">
-    <img src={Logo} alt="" className="h-12" />
-  </div>
-);
-
-const renderFooterElement = () => {
-  if (conversation.messageList.length >= messageLimit)
-    return (
-      <div className="p-2">
-        <div className="p-2 bg-primary-50 border border-primary-300 rounded-md shadow-md text-xs">
-          <p>
-            You have reached the message limit of: {messageLimit}
-            <br />
-            Clear previous messages to send a new one.
-          </p>
-          <TextButton
-            text="Clear now"
-            onClick={handleOnClearMessage}
-            className="mt-2"
-          />
-        </div>
-      </div>
-    );
-  else return <></>;
-};
-const footerElement = renderFooterElement();
-
-const additionalAction: ChatBaseAction[] = [
-  {
-    text: "Clear",
-    onClick: handleOnClearMessage,
-    icon: <TrashIcon className="w-3 h-3" aria-hidden="true" />,
-  },
-];
-
-return (
-  <ChatBase
-    open
-    value={message}
-    currentUser={currentUser}
-    conversation={filteredConversation ?? conversation}
-    headerElement={headerElement}
-    footerElement={footerElement}
-    additionalAction={additionalAction}
-    searchMessage={search}
-    onChangeSearch={(e) => setSearch(e.target.value)}
-    onSendMessage={handleOnSendMessage}
-    onChangeMessage={(e) => setMessage(e.target.value)}
-    onSearch={handleOnSearch}
-    className="border border-gray-200 shadow-lg w-96"
-    disableMobileResize
-    disableMessageInput={conversation.messageList.length >= messageLimit}
-    onHiddenChatText={true}
-  />
-);
+    messageList: [
+      {
+        sender: botUser,
+        messageBody: "Hi! How can I help?",
+        createdAt: new Date(),
+      },
+    ],
+  };
+
+<ChatBase
+  open
+  value={message}
+  currentUser={currentUser}
+  conversation={conversation}
+  onSendMessage={(updated) => {
+    setConversation(updated);
+    setMessage("");
+  }}
+  onChangeMessage={(e) => setMessage(e.target.value)}
+  sizeClassName="h-[500px] w-96"
+  disableMobileResize
+/>;
+```
+
+With search:
+
+```jsx
+<ChatBase
+  open
+  value={message}
+  currentUser={currentUser}
+  conversation={filteredConversation ?? conversation}
+  searchMessage={search}
+  onSearch={(q) => { /* filter conversation.messageList */ }}
+  onChangeSearch={(e) => setSearch(e.target.value)}
+  onSendMessage={...}
+  onChangeMessage={...}
+/>
+```
+
+With file upload:
+
+```jsx
+<ChatBase
+  open
+  value={message}
+  currentUser={currentUser}
+  conversation={conversation}
+  fileUpload={{
+    allowFileUpload: true,
+    file,
+    acceptFileType: ".jpg,.jpeg,.png,.mp4,.webm",
+    onChangeUpload: (e) => setFile(e.target.files[0]),
+    onSendUpload: (conversation) => { /* append file message */ },
+  }}
+  onSendMessage={...}
+  onChangeMessage={...}
+/>
+```
+
+With loading reply indicator:
+
+```jsx
+<ChatBase
+  open
+  value={message}
+  currentUser={currentUser}
+  conversation={conversation}
+  isLoadingReply={waitingForBot}
+  onSendMessage={...}
+  onChangeMessage={...}
+/>
 ```
 
 ##### Required props
 
-| Name         | Type           | Description                      |
-| ------------ | -------------- | -------------------------------- |
-| open         | `boolean`      | Visibility of ChatBase component |
-| value        | `string`       | Message input text               |
-| currentUser  | `User`         | User Object                      |
-| conversation | `Conversation` | Conversation Object              |
+| Name           | Type           | Description                                                          |
+| -------------- | -------------- | -------------------------------------------------------------------- |
+| `open`         | `boolean`      | When `false`, the component renders nothing                          |
+| `value`        | `string`       | Current message input value                                          |
+| `currentUser`  | `User`         | The logged-in user — used to determine which side messages appear on |
+| `conversation` | `Conversation` | The conversation to display — see Conversation below                 |
 
 ##### Optional props
 
-| Name                | Type                 | Default    | Description                                                                            |
-| ------------------- | -------------------- | ---------- | -------------------------------------------------------------------------------------- |
-| searchMessage       | `string`             | ""         | Search input text                                                                      |
-| headerElement       | `React Element`      | null       | Replaces default component Header                                                      |
-| bodyElement         | `React Element`      | null       | Replaces default component Body                                                        |
-| footerElement       | `React Element`      | null       | Footer element that floats above message input                                         |
-| additionalAction    | `ChatBaseAction[]`   | null       | Additional buttons to be place within action dropdown in top right corner              |
-| disableMessageInput | `boolean`            | null       | When true, message input is disabled                                                   |
-| isLoadingReply      | `boolean`            | null       | When true, loading indicator appears above message input and message input is disabled |
-| className           | `tailwind classname` | ""         | For component container                                                                |
-| sizeClassName       | `tailwind classname` | ""         | For component size                                                                     |
-| paddingTop          | `Padding top         | ""         | For mobile applications                                                                |
-| disableMobileResize | `boolean`            | null       | When true, mobile resize is disabled                                                   |
-| onSendMessage       | `function`           | `() => {}` | To send message                                                                        |
-| onChangeMessage     | `function`           | `() => {}` | To type in message input                                                               |
-| onSearch            | `function`           | `() => {}` | To search in messages                                                                  |
-| onChangeSearch      | `function`           | `() => {}` | To type in search input                                                                |
-| onClose             | `function`           | `() => {}` | To close ChatBase component - Only available on mobile                                 |
-| onHiddenChatText    | `boolean`            | `true`     | To hide the chat text and Paper Clip Icon                                              |
-
-##### Interface FileUpload
-
-| Name              | Type                                   | Description                                                            |
-| ----------------- | -------------------------------------- | ---------------------------------------------------------------------- |
-| `allowFileUpload` | `boolean`                              | When true, users are able to upload image and video                    |
-| `file`            | `string \| File \| any`                | Image / video file                                                     |
-| `maxFileSize?`    | `number`                               | Maximum file size                                                      |
-| `acceptFileType?` | `string`                               | Accepted file types (eg. ".jpg,.jpeg,.png,.svg,.tiff,.mp4,.webm,.ogg") |
-| `onChangeUpload`  | `(event: any) => void`                 | Function to change file in file upload input                           |
-| `onSendUpload`    | `(conversation: Conversation) => void` | Function to upload file                                                |
-
-##### Interface FileObj
-
-| Name       | Type     | Description                 |
-| ---------- | -------- | --------------------------- |
-| `fileName` | `string` | File name                   |
-| `token`    | `string` | File token                  |
-| `type`     | `string` | File type (eg. "image/png") |
-
-##### Interface Conversation
-
-| Name          | Type        | Description               |
-| ------------- | ----------- | ------------------------- |
-| `id`          | `string`    | Required id               |
-| `members`     | `User[]`    | Required list of Users    |
-| `messageList` | `Message[]` | Required list of Messages |
-
-##### Interface User
-
-| Name       | Type     | Description       |
-| ---------- | -------- | ----------------- |
-| `id`       | `string` | Required id       |
-| `name`     | `string` | Required name     |
-| `imageUrl` | `string` | Optional imageURL |
-
-##### Interface Conversation
-
-| Name          | Type        | Description               |
-| ------------- | ----------- | ------------------------- |
-| `id`          | `string`    | Required id               |
-| `members`     | `User[]`    | Required list of Users    |
-| `messageList` | `Message[]` | Required list of Messages |
-
-##### Interface Message
-
-| Name          | Type            | Description   |
-| ------------- | --------------- | ------------- |
-| `sender`      | `User`          | Required User |
-| `messageBody` | `string`        | messageBody   |
-| `reactElemet` | `React Element` | React Element |
-| `createdAt`   | `Date`          | Required date |
-
-##### Interface ChatBaseAction
-
-| Name      | Type          | Description               |
-| --------- | ------------- | ------------------------- |
-| `text`    | `string`      | Required text             |
-| `onClick` | `() => void`  | Required onClick function |
-| `icon`    | `JSX.Element` | Required icon             |
+| Name                   | Type                                   | Default                             | Description                                                                                   |
+| ---------------------- | -------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------------------------- |
+| `fileUpload`           | `FileUpload`                           | —                                   | Enables file upload — see FileUpload below                                                    |
+| `searchMessage`        | `string`                               | —                                   | Current search input value. Pass the filtered conversation to `conversation` to show results. |
+| `headerElement`        | `ReactElement`                         | —                                   | Replaces the default blue "Chat" header bar                                                   |
+| `bodyElement`          | `ReactElement`                         | —                                   | Replaces the default message list. Useful for loading states.                                 |
+| `footerElement`        | `ReactElement`                         | —                                   | Rendered above the message input. Useful for limit warnings or disclaimers.                   |
+| `additionalAction`     | `ChatBaseAction[]`                     | —                                   | Extra items added to the ⋮ actions dropdown — see ChatBaseAction below                        |
+| `hideAdditionalAction` | `boolean`                              | `false`                             | Hides the ⋮ actions dropdown entirely                                                         |
+| `disableMessageInput`  | `boolean`                              | `false`                             | Disables the message text input                                                               |
+| `isLoadingReply`       | `boolean`                              | `false`                             | Shows an animated typing indicator above the input and disables the input                     |
+| `onHiddenChatText`     | `boolean`                              | `false`                             | Hides the text input and paperclip icon. Useful when the input is managed externally.         |
+| `disableMobileResize`  | `boolean`                              | `false`                             | Prevents the component from expanding to full screen on mobile                                |
+| `sizeClassName`        | `string`                               | `h-full w-full sm:h-[75vh] sm:w-96` | Tailwind classes controlling the component dimensions                                         |
+| `className`            | `string`                               | —                                   | Additional Tailwind classes applied to the outer container                                    |
+| `paddingTop`           | `number`                               | `0`                                 | Top padding in pixels. Used to offset the actions menu in mobile app layouts.                 |
+| `onSendMessage`        | `(conversation: Conversation) => void` | —                                   | Called with the updated conversation (including the new message) when send is triggered       |
+| `onChangeMessage`      | `(event: any) => void`                 | —                                   | Called on every keystroke in the message input                                                |
+| `onSearch`             | `(searchMessage: string) => void`      | —                                   | Called when the search form is submitted                                                      |
+| `onChangeSearch`       | `(event: any) => void`                 | —                                   | Called on every keystroke in the search input                                                 |
+| `onClose`              | `() => void`                           | —                                   | Called when the mobile close (✕) button is tapped                                             |
+| `lib`                  | `{ axios?: any }`                      | —                                   | Pass axios for file upload operations                                                         |
+
+##### FileUpload
+
+| Name              | Type                                   | Description                                                                               |
+| ----------------- | -------------------------------------- | ----------------------------------------------------------------------------------------- |
+| `allowFileUpload` | `boolean`                              | Shows the paperclip button to trigger file selection                                      |
+| `file`            | `string \| File \| any`                | Currently selected file                                                                   |
+| `maxFileSize`     | `number`                               | Maximum file size in MB. Defaults to `15`.                                                |
+| `acceptFileType`  | `string`                               | Comma-separated accepted extensions, e.g. `".jpg,.png,.mp4"`                              |
+| `onChangeUpload`  | `(event: any) => void`                 | Called when a file is selected via the file input                                         |
+| `onSendUpload`    | `(conversation: Conversation) => void` | Called with the current conversation when the send button is clicked with a file selected |
+
+##### ChatBaseAction
+
+| Name      | Type          | Description                              |
+| --------- | ------------- | ---------------------------------------- |
+| `text`    | `string`      | Label shown in the dropdown item         |
+| `onClick` | `() => void`  | Called when the dropdown item is clicked |
+| `icon`    | `JSX.Element` | Icon rendered to the left of the label   |
+
+##### Conversation
+
+| Name          | Type        | Description                      |
+| ------------- | ----------- | -------------------------------- |
+| `id`          | `string`    | Unique conversation identifier   |
+| `members`     | `User[]`    | Participants in the conversation |
+| `messageList` | `Message[]` | Ordered list of messages         |
+
+##### Message
+
+| Name           | Type                | Description                                                                                    |
+| -------------- | ------------------- | ---------------------------------------------------------------------------------------------- |
+| `sender`       | `User`              | The user who sent the message                                                                  |
+| `messageBody`  | `string \| FileObj` | Text content (supports markdown for received messages) or a `FileObj` for image/video messages |
+| `reactElement` | `ReactElement`      | Optional — replaces `messageBody` rendering with a custom element                              |
+| `createdAt`    | `Date`              | Timestamp shown below the message bubble                                                       |
+
+##### User
+
+| Name       | Type     | Description                                        |
+| ---------- | -------- | -------------------------------------------------- |
+| `id`       | `string` | Unique user identifier                             |
+| `name`     | `string` | Display name shown above received message bubbles  |
+| `imageUrl` | `string` | Optional avatar URL. Falls back to a default icon. |
+
+##### FileObj
+
+| Name       | Type     | Description                                    |
+| ---------- | -------- | ---------------------------------------------- |
+| `fileName` | `string` | File URL or path                               |
+| `token`    | `string` | Unique file token                              |
+| `type`     | `string` | MIME type, e.g. `"image/png"` or `"video/mp4"` |