npm package: @ofi-summer-ai/mark-chatbot
Description: Mark Chatbot component library — granular React chatbot UI components with SSE streaming support
Latest version: 0.1.1

# @ofi-summer-ai/mark-chatbot

A granular React chatbot UI component library. Every part of a chatbot — the bubble, the avatar, the input, the header — is its own independently importable component. Build only what you need, style it your way.

## Features

- 24 individual components — use any single one or compose them all
- SSE streaming hook ready for mark-backend
- Markdown rendering in assistant messages
- Copy / thumbs-up / thumbs-down message actions
- Auto-scroll to bottom as messages arrive
- Floating "scroll to bottom" button
- Typing indicator with animated dots
- Online status indicator
- localStorage chat history persistence hook
- Full TypeScript types
- Tailwind CSS 4 styling with dark-mode support
- Zero framework lock-in — works with any React 18+ project

---

## Installation

```bash
npm install @ofi-summer-ai/mark-chatbot
# or
pnpm add @ofi-summer-ai/mark-chatbot
```

Import the stylesheet once in your app entry point:

```ts
import '@ofi-summer-ai/mark-chatbot/style.css';
```

---

## Quick Start

### Option 1 — Drop-in chatbot (zero config)

```tsx
import { ChatBot } from '@ofi-summer-ai/mark-chatbot';
import '@ofi-summer-ai/mark-chatbot/style.css';

export default function App() {
  return (
    <ChatBot
      config={{
        apiBaseUrl: 'https://api.example.com',
        authToken: 'Bearer your-token',
        campaignId: 'your-campaign-uuid',
        botName: 'Mark AI',
        botAvatar: '/bot-avatar.png',
        placeholder: 'Ask me about your campaign...',
      }}
      initialMessage="Hi! I'm Mark. How can I help with your marketing today?"
      height="600px"
    />
  );
}
```

### Option 2 — Compose with ChatWindow

```tsx
import { ChatWindow } from '@ofi-summer-ai/mark-chatbot/components';
import { useChatStream } from '@ofi-summer-ai/mark-chatbot/hooks';

const { messages, isLoading, sendMessage } = useChatStream({
  config: { apiBaseUrl: '...', campaignId: '...' },
});

<ChatWindow
  messages={messages}
  isLoading={isLoading}
  onSendMessage={sendMessage}
  headerProps={{ title: 'Mark AI', status: 'online' }}
  botAvatar="/bot.png"
  height="500px"
/>
```

### Option 3 — Build your own from atoms

```tsx
import {
  ChatBubble,
  ChatAvatar,
  ChatTimestamp,
  ChatMessageContent,
} from '@ofi-summer-ai/mark-chatbot/components';

<div className="flex gap-2">
  <ChatAvatar role="assistant" src="/bot.png" />
  <div>
    <ChatBubble variant="assistant">
      <ChatMessageContent content="**Hello!** How can I help?" />
    </ChatBubble>
    <ChatTimestamp timestamp={new Date().toISOString()} />
  </div>
</div>
```

---

## Import Paths

| Import | What you get |
|--------|-------------|
| `@ofi-summer-ai/mark-chatbot` | Everything: types + hooks + components |
| `@ofi-summer-ai/mark-chatbot/components` | All UI components only |
| `@ofi-summer-ai/mark-chatbot/hooks` | All hooks only |
| `@ofi-summer-ai/mark-chatbot/style.css` | Tailwind CSS stylesheet |

---

## Component Overview

### Layout

| Component | Description |
|-----------|-------------|
| [`ChatWindow`](docs/components/layout/ChatWindow.md) | Full window: header + body + footer |
| [`ChatHeader`](docs/components/layout/ChatHeader.md) | Top bar with avatar, title, status, close button |
| [`ChatBody`](docs/components/layout/ChatBody.md) | Scrollable messages area with auto-scroll |
| [`ChatFooter`](docs/components/layout/ChatFooter.md) | Input area wrapper |

### Message

| Component | Description |
|-----------|-------------|
| [`ChatMessage`](docs/components/message/ChatMessage.md) | Complete message row (avatar + bubble + timestamp + actions) |
| [`ChatBubble`](docs/components/message/ChatBubble.md) | The bubble shape — user / assistant / error variants |
| [`ChatAvatar`](docs/components/message/ChatAvatar.md) | Circular avatar with image or icon fallback |
| [`ChatTimestamp`](docs/components/message/ChatTimestamp.md) | Formatted time display |
| [`ChatMessageContent`](docs/components/message/ChatMessageContent.md) | Markdown-rendered message text |
| [`ChatMessageActions`](docs/components/message/ChatMessageActions.md) | Copy / thumbs-up / thumbs-down row |
| [`ChatMessageError`](docs/components/message/ChatMessageError.md) | Error bubble with red styling |
| [`ChatMessageSystem`](docs/components/message/ChatMessageSystem.md) | Centered system / status pill |

### Input

| Component | Description |
|-----------|-------------|
| [`ChatInput`](docs/components/input/ChatInput.md) | Full input row: textarea + send button + hint |
| [`ChatTextarea`](docs/components/input/ChatTextarea.md) | Auto-growing textarea |
| [`ChatSendButton`](docs/components/input/ChatSendButton.md) | Send icon button with loading spinner |
| [`ChatInputHint`](docs/components/input/ChatInputHint.md) | Keyboard shortcut hint line |

### Status / Feedback

| Component | Description |
|-----------|-------------|
| [`ChatTypingIndicator`](docs/components/status/ChatTypingIndicator.md) | Animated three-dot "Thinking..." indicator |
| [`ChatOnlineIndicator`](docs/components/status/ChatOnlineIndicator.md) | Online / offline / away status dot |
| [`ChatScrollButton`](docs/components/status/ChatScrollButton.md) | Floating scroll-to-bottom button |
| [`ChatEmptyState`](docs/components/status/ChatEmptyState.md) | Empty conversation placeholder |
| [`ChatTokenCount`](docs/components/status/ChatTokenCount.md) | Token usage display |

### All-in-One

| Component | Description |
|-----------|-------------|
| [`ChatBot`](docs/components/ChatBot.md) | Drop-in complete chatbot with SSE streaming |

---

## Hook Overview

| Hook | Description |
|------|-------------|
| [`useChat`](docs/hooks/useChat.md) | Message array state management |
| [`useChatStream`](docs/hooks/useChatStream.md) | SSE streaming for mark-backend |
| [`useAutoScroll`](docs/hooks/useAutoScroll.md) | Auto-scroll ref to bottom of a list |
| [`useChatHistory`](docs/hooks/useChatHistory.md) | localStorage chat history persistence |

---

## Peer Dependencies

```json
{
  "react": ">=18.0.0",
  "react-dom": ">=18.0.0"
}
```

---

## License

MIT © [OFI Summer AI](https://github.com/OFI-Summer-AI/mark-chatbot-template)