@metricinsights/concierge/README.md

Metric Insights Concierge Component

# @metricinsights/concierge

Metric Insights Concierge Component

A versatile chat interface component that can be integrated into any React application. It provides a customizable chat experience with support for rich content, themes, and custom actions.

## Key Features

- Real-time chat interface with streaming support
- Customizable themes (light/dark)
- Rich content blocks with HTML support
- Custom positioning and styling
- Action system for custom interactions
- Message history management
- Custom rendering capabilities

## Installation

```bash
npm install @metricinsights/concierge
# or
yarn add @metricinsights/concierge
```

## Basic Usage

```tsx
import { ConciergeProvider, Concierge } from '@metricinsights/concierge';
import '@metricinsights/concierge/dist/styles.css';
import 'katex/dist/katex.min.css'; // KaTeX styles support

function App() {
  return (
    <ConciergeProvider defaultOpen={false} defaultTheme="light" defaultPosition="bottom-right">
      <Concierge title="Basic Concierge" />
    </ConciergeProvider>
  );
}
```

## Theme Customization

The component supports both light and dark themes:

```tsx
// Light Theme
<ConciergeProvider defaultTheme="light">
  <Concierge title="Light Theme" />
</ConciergeProvider>

// Dark Theme
<ConciergeProvider defaultTheme="dark">
  <Concierge title="Dark Theme" />
</ConciergeProvider>
```

## Position Variants

The component can be positioned in four different corners:

```tsx
// Top Left
<ConciergeProvider defaultPosition="top-left">
  <Concierge title="Top Left" />
</ConciergeProvider>

// Top Right
<ConciergeProvider defaultPosition="top-right">
  <Concierge title="Top Right" />
</ConciergeProvider>

// Bottom Left
<ConciergeProvider defaultPosition="bottom-left">
  <Concierge title="Bottom Left" />
</ConciergeProvider>

// Bottom Right
<ConciergeProvider defaultPosition="bottom-right">
  <Concierge title="Bottom Right" />
</ConciergeProvider>
```

## Custom Components

You can customize the rendering of different message types:

```tsx
<ConciergeProvider>
  <Concierge
    title="Custom Components"
    components={{
      Text: ({ block, message }) => (
        <div style={{
          padding: '10px',
          backgroundColor: message.type === 'user' ? '#e3f2fd' : '#f5f5f5',
          borderRadius: '8px',
        }}>
          {block.content}
        </div>
      ),
      Element: ({ block, message }) => (
        <div style={{
          padding: '10px',
          backgroundColor: '#fff',
          border: '1px solid #eee',
          borderRadius: '8px',
        }}>
          <Element markdown={block.raw} />
        </div>
      ),
      Error: ({ block, message }) => (
        <div style={{
          padding: '10px',
          backgroundColor: '#fee2e2',
          color: '#dc2626',
          borderRadius: '8px',
          display: 'flex',
          alignItems: 'center',
          gap: '8px',
        }}>
          <span>⚠️</span>
          {block.content}
        </div>
      ),
    }}
  />
</ConciergeProvider>
```

## Custom Actions

You can register custom actions using the `useActionContext` hook:

```tsx
const CustomActionsConcierge = () => {
  const { registerAction } = useActionContext();

  useEffect(() => {
    registerAction('click', 'customAction', () => {
      console.log('Custom action triggered!');
    });
  }, [registerAction]);

  return (
    <Concierge
      title="Custom Actions Concierge"
      components={{
        Element: ({ block }) => (
          <div onClick={() => block.raw === 'custom' && console.log('Custom element clicked!')}>
            <Element markdown={block.raw} />
          </div>
        ),
      }}
    />
  );
};
```

## Message History

Initialize the component with message history:

```tsx
const exampleMessagesWithBlocks: Message[] = [
  {
    id: '1',
    content: '',
    timestamp: new Date(),
    type: 'assistant',
    blocks: [
      {
        type: 'html',
        content: '<div class="action-badge">Analyzing request...</div>',
        startIndex: 0,
        endIndex: 0,
        raw: '',
      },
      {
        type: 'html',
        content: '<div class="links">Here are some helpful links...</div>',
        startIndex: 0,
        endIndex: 0,
        raw: '',
      }
    ],
  }
];

<ConciergeProvider defaultMessages={exampleMessagesWithBlocks}>
  <Concierge title="Message History" />
</ConciergeProvider>
```

## Custom Render

You can completely customize the UI using the render prop:

```tsx
<ConciergeProvider>
  <Concierge
    title="Custom Render"
    render={({
      isOpen,
      toggleOpen,
      messages,
      addMessage,
      updateMessage,
      clearMessages,
      isLoading,
      error,
      theme,
      position,
      input,
      setInput,
      sendMessage,
      cancelRequest,
      components,
    }) => (
      <div style={{
        position: 'relative',
        width: '100%',
        backgroundColor: theme === 'dark' ? '#1f2937' : '#ffffff',
        color: theme === 'dark' ? '#f3f4f6' : '#1f2937',
        borderRadius: '12px',
        boxShadow: '0 4px 6px -1px rgb(0 0 0 / 0.1)',
        overflow: 'hidden',
        display: 'flex',
        flexDirection: 'column',
        height: '400px',
        maxWidth: '400px',
        margin: '0 auto',
      }}>
        {/* Custom UI implementation */}
      </div>
    )}
  />
</ConciergeProvider>
```

## Component Structure

### 1. ConciergeProvider

Context provider for Concierge functionality.

#### Props:
- `defaultOpen`: boolean - Initial open state
- `defaultTheme`: 'light' | 'dark' - Initial theme
- `defaultPosition`: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' - Initial position
- `defaultMessages`: Message[] - Initial message history
- `apiOptions`:
  - `useStreaming`: boolean
  - `headers`: Record<string, string>

### 2. Concierge

Main chat interface component.

#### Props:
- `title`: string - Chat window title
- `components`:
  - `Element`: (props: { block: Block }) => React.ReactNode - Custom component renderers
- `render`: (props: ConciergeRenderProps) => React.ReactNode - Custom render function

## Data Structures

### Message Structure
```typescript
interface Message {
  id: string;
  content: string;
  timestamp: Date;
  type: 'user' | 'assistant';
  blocks?: Block[];
}
```

### Block Structure
```typescript
interface Block {
  type: string;
  content: string;
  startIndex: number;
  endIndex: number;
  raw: string;
}
```

## Styling

The component uses SCSS for styling with the following structure:
- `styles.scss` - Main styles file
- `_variables.scss` - Theme variables and configuration
- `_mixins.scss` - Reusable style mixins
- `action-badge.scss` - Action badge styles

### Theme Customization
The component supports light and dark themes with the following classes:
- `.light` - Light theme (default)
- `.dark` - Dark theme

### Position Customization
The component can be positioned using the following classes:
- `.bottom-right` - Bottom right corner (default)
- `.bottom-left` - Bottom left corner
- `.top-right` - Top right corner
- `.top-left` - Top left corner

### Available Variables
```scss
// Colors
$primary-color: #2563eb;
$secondary-color: #1e40af;
$background-light: #ffffff;
$background-dark: #1f2937;
$text-light: #1f2937;
$text-dark: #f3f4f6;

// Layout
$border-radius: 8px;
$shadow: 0 4px 6px -1px rgb(0 0 0 / 0.1), 0 2px 4px -2px rgb(0 0 0 / 0.1);
$transition: all 0.3s ease;

// Component dimensions
$concierge-width: 380px;
$concierge-height: 500px;
$concierge-max-width: 90vw;
$concierge-max-height: 80vh;
$concierge-z-index: 1000;

// Spacing
$spacing-xs: 0.5rem;
$spacing-sm: 0.75rem;
$spacing-md: 1rem;
$spacing-lg: 1.25rem;
$spacing-xl: 1.5rem;

// Typography
$font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
$font-size-sm: 0.875rem;
$font-size-base: 1rem;
$font-size-lg: 1.25rem;
```

## Available Components

### Core Components

#### Element Component
```tsx
import { Element } from 'concierge-component/src/components/concierge/components';

// Usage
<Element markdown={markdownContent} />
```
Renders markdown content with support for HTML elements.

#### Input Component
```tsx
import { ConciergeInput } from 'concierge-component/src/components/concierge/components';

// Usage
<ConciergeInput
  value={input}
  onChange={setInput}
  onSend={sendMessage}
  placeholder="Type your message..."
/>
```
Custom input component with send button and keyboard shortcuts.

#### Button Components
```tsx
import { ToggleButton } from 'concierge-component/src/components/concierge/components';

// Usage
<ToggleButton
  isOpen={isOpen}
  onClick={toggleOpen}
  theme={theme}
/>
```
Toggle button for opening/closing the chat interface.

## Context Usage

### Available Contexts

#### UI Context
```tsx
import { useUIContext } from 'concierge-component/src/components/concierge/contexts';

// Usage
const {
  isOpen,
  toggleOpen,
  close,
  open,
  theme,
  setTheme,
  position,
  setPosition
} = useUIContext();
```

#### Message Context
```tsx
import { useMessageContext } from 'concierge-component/src/components/concierge/contexts';

// Usage
const {
  messages,
  addMessage,
  updateMessage,
  clearMessages
} = useMessageContext();
```

#### Action Context
```tsx
import { useActionContext } from 'concierge-component/src/components/concierge/contexts';

// Usage
const {
  registerAction,
  unregisterAction,
  handleEvent
} = useActionContext();
```

#### API Context
```tsx
import { useAPIContext } from 'concierge-component/src/components/concierge/contexts';

// Usage
const {
  isLoading,
  error,
  sendMessage,
  cancelRequest
} = useAPIContext();
```

## License

ISC