<!-- source-hash: 5ef079ca48dfe4a6d1f2fa08a9c755fe -->
Rich contenteditable chat input component with support for `@`-mention chips, slash-command suggestions, send/stop controls, and a ghost preview overlay.

## Key Components

### Exported

- **`ChatInput`** (`forwardRef<ChatInputRef, ChatInputProps>`) — Primary component. Renders a `contenteditable` div editor rather than a `<textarea>`, enabling inline mention chips as atomic DOM nodes.

### Internal Helpers

| Function | Purpose |
|---|---|
| `parseSegments` | Splits a draft string into `text` and `mention` segments using `MENTION_GLOBAL` regex |
| `serialize` | Walks the editor's `childNodes` to reconstruct the draft string from text nodes and chip elements |
| `buildChipEl` | Creates a non-React DOM node for a committed `@`-mention using `renderToStaticMarkup` on the `Tag` component |
| `rebuildDom` | Replaces editor content wholesale from a value string + metadata map |
| `placeCaretAtEnd` / `placeCaretAtOffset` | Caret placement utilities using the Selection API |
| `insertTextAtCaret` | Inserts plain text at caret without injecting `<br>` or `<div>` elements |

### `ChatInputRef` (Imperative Handle)

| Method | Description |
|---|---|
| `focus()` / `blur()` | Programmatic focus control |
| `clear()` | Resets draft and metadata |
| `setValue(next)` | Replaces editor content |
| `setValueAndCursor(next, offset)` | Replaces content and positions caret |
| `submit(next)` | Fires the send handler directly |
| `getValue()` | Synchronous draft read |
| `removeMentionTrigger()` | Strips trailing `@query` from draft |
| `commitMention(token, meta?)` | Replaces in-progress `@query` with a chip token |

## Usage Example

```typescript
import { useRef } from "react"
import { ChatInput } from "./chat-input"
import type { ChatInputRef } from "./types"

function MyComposer() {
  const inputRef = useRef<ChatInputRef>(null)

  return (
    <ChatInput
      ref={inputRef}
      placeholder="Type a message..."
      onSend={(message) => {
        console.log("Sending:", message)
        return fetch("/api/chat", { method: "POST", body: message })
          .then(() => true)
      }}
      onMentionQueryChange={(query) => {
        // fetch mention suggestions for `query`
      }}
      slashCommands={[
        { name: "summarize", description: "Summarize the conversation" },
      ]}
      autoFocus
    />
  )
}

// Imperative control
inputRef.current?.setValue("/summarize ")
inputRef.current?.commitMention("ticket:abc123", {
  label: "Ticket #123",
  icon: <TicketIcon />,
})
```

## Key Regex Constants

```typescript
// Committed mention token in draft string
const MENTION_GLOBAL = /@[A-Za-z0-9_.+/=-]+:[A-Za-z0-9_.+/=-]+/g

// In-progress @query at end of draft (excludes email addresses)
const MENTION_TRIGGER_AT_END = /(^|\s)@([\w.-]*)$/

// Slash command activation trigger
const SLASH_INPUT_TRIGGER = /^\/([a-z][a-z0-9-]*)?$/
```

> **Note:** `SLASH_INPUT_TRIGGER` is shared with `lib/config/slash-commands-config.ts` and the chat-route slash dispatch parser — keep all three in sync.

## Source

[`chat-input.tsx` on GitHub](https://github.com/flamingo-stack/openframe-oss-lib/blob/main/chat-input.tsx)