blixify-ui-web-mcp 0.1.2 → 0.1.18

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

@@ -4,220 +4,268 @@
 
 <hr>
 
-Chat Base
+A chat window component with message bubbles, markdown rendering for received messages, message search, file upload (images, videos, PDFs, and other documents), a loading reply indicator, tool report logs, tool call chips, and customisable header/footer/body slots.
 
 ##### Import
 
 ```js
-import { ChatBase } from "blixify-ui-web/components/chat/chatBase";
+import {
+  ChatBase,
+  Conversation,
+  Message,
+  ToolReport,
+  ToolCall,
+  User,
+} from "blixify-ui-web/components/chat/chatBase";
 ```
 
 ##### Usage
 
-```tsx
-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);
-  }
-};
+Basic chat:
 
-const handleOnClearMessage = () => {
-  setFilteredConversation(null);
-  setConversation({
+```jsx
+const [message, setMessage] = useState("");
+const [conversation, setConversation] =
+  useState <
+  Conversation >
+  {
     id: "1",
     members: [currentUser, botUser],
-    messageList: [],
-  });
-};
+    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
+/>;
+```
 
-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();
+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={...}
+/>
+```
 
-const additionalAction: ChatBaseAction[] = [
-  {
-    text: "Clear",
-    onClick: handleOnClearMessage,
-    icon: <TrashIcon className="w-3 h-3" aria-hidden="true" />,
+With file upload:
+
+```jsx
+<ChatBase
+  open
+  value={message}
+  currentUser={currentUser}
+  conversation={conversation}
+  fileUpload={{
+    allowFileUpload: true,
+    file,
+    acceptFileType: ".jpg,.jpeg,.png,.mp4,.webm,.pdf,.docx",
+    onChangeUpload: (e) => setFile(e.target.files[0]),
+    onSendUpload: (conversation, file) => { /* handle upload */ },
+  }}
+  onSendMessage={...}
+  onChangeMessage={...}
+/>
+```
+
+With loading reply indicator:
+
+```jsx
+<ChatBase
+  open
+  value={message}
+  currentUser={currentUser}
+  conversation={conversation}
+  isLoadingReply={waitingForBot}
+  onSendMessage={...}
+  onChangeMessage={...}
+/>
+```
+
+With tool report (shows model + tool call status above an assistant message):
+
+```jsx
+const assistantMessage: Message = {
+  sender: botUser,
+  messageBody: "Your order is out for delivery.",
+  createdAt: new Date(),
+  toolReport: {
+    model: "gemini-2.0-flash",
+    tools: [
+      { content: "search_orders", request: {}, response: {}, status: "done" },
+      {
+        content: "fetch_delivery_status",
+        request: {},
+        response: {},
+        status: "done",
+      },
+    ],
   },
-];
-
-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}
-  />
-);
+};
+```
+
+Status dot colours: `"pending"` → yellow pulsing, `"done"` → green, `"error"` → red.
+
+With tool call chips (for AI pipelines that log tool invocations as separate messages):
+
+```jsx
+// Messages where author === "tool" should set isToolCall: true.
+// They render as a small centred chip instead of a chat bubble.
+const toolCallMessage: Message = {
+  sender: botUser,
+  messageBody: "fetch_policy_details",
+  createdAt: new Date(),
+  isToolCall: true,
+};
 ```
 
 ##### 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.                 |
+| `inputActions`         | `ReactElement[]`                       | —                                   | Extra icon buttons rendered in the input row between the paperclip and the send button        |
+| `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                                                                                     |
+| `hasFiles`        | `boolean`              | Tells the component files are selected — shows the send button and triggers `onSendMessage` on send                                      |
+| `multiple`        | `boolean`              | Allows picking multiple files at once                                                                                                    |
+| `acceptFileType`  | `string`               | Comma-separated accepted extensions, e.g. `".jpg,.png,.mp4,.pdf,.docx"`. Defaults to images only if omitted.                            |
+| `onChangeUpload`  | `(event: any) => void` | Called when files are selected via the file input. Consumer extracts files from `event.target.files` and manages their own `File[]` state |
+
+##### File rendering in message bubbles
+
+| File type         | Behaviour                                                                                            |
+| ----------------- | ---------------------------------------------------------------------------------------------------- |
+| `image/*`         | Renders as an inline image. Click to open a full-size preview modal. Hover to download.              |
+| `video/*`         | Renders as an inline video player. Hover to download.                                                |
+| `application/pdf` | Renders as a document icon + filename. Click to open a PDF preview modal. Download link shown below. |
+| Other             | Renders as a document icon + filename with a "Cannot preview" label. Download link shown below.      |
+
+##### 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, PDF, or document messages |
+| `reactElement` | `ReactElement`      | Optional — replaces `messageBody` rendering with a custom element                                                 |
+| `createdAt`    | `Date`              | Timestamp shown below the message bubble                                                                          |
+| `toolReport`   | `ToolReport`        | Optional — renders a compact tool log panel above the message body (see ToolReport below)                         |
+| `isToolCall`   | `boolean`           | Optional — renders the message as a centred chip instead of a chat bubble (see Tool Calls)                        |
+
+##### ToolReport
+
+Attach to an assistant `Message` to show which model and tools were used to produce the reply.
+
+| Name    | Type         | Description                          |
+| ------- | ------------ | ------------------------------------ |
+| `model` | `string`     | Optional model name shown at the top |
+| `tools` | `ToolCall[]` | List of tool calls and their status  |
+
+##### ToolCall
+
+| Name       | Type                             | Description                                                                      |
+| ---------- | -------------------------------- | -------------------------------------------------------------------------------- |
+| `content`  | `string`                         | Tool name displayed in the summary row                                           |
+| `request`  | `string \| any`                  | Request payload — shown in the expandable details panel                          |
+| `response` | `any`                            | Response payload — shown in the expandable details panel                         |
+| `status`   | `"pending" \| "done" \| "error"` | Dot colour: yellow pulsing (pending), green (done), red (error). Default pending |
+
+##### Tool Calls
+
+When an AI pipeline stores tool invocations as separate messages (e.g. `author: "tool"` in a database), set `isToolCall: true` on those messages. They render as small centred chips between conversation bubbles — visually distinct from user/assistant messages.
+
+```jsx
+const messages = chatList.map((chat) => ({
+  sender: chat.author === "assistant" ? botUser : userObj,
+  messageBody: chat.content,
+  createdAt: new Date(chat.createdAt),
+  isToolCall: chat.author === "tool",
+}));
+```
+
+##### 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 — also used as the display name in the bubble   |
+| `type`     | `string` | MIME type, e.g. `"image/png"`, `"video/mp4"`, `"application/pdf"` |