@kitn.ai/chat/llms.txt

Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS.

<!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
# @kitn.ai/chat

> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 44 `kitn-*` custom elements: streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.

## Install

```bash
npm install @kitn.ai/chat
# SolidJS consumers also need the peer dep:
npm install solid-js
```

## #1 rule: array/object data goes on JS PROPERTIES, not HTML attributes

This is the single most common mistake. Arrays and objects (`messages`, `models`, `context`, `suggestions`, `slashCommands`, …) MUST be assigned as JavaScript properties on the element. They CANNOT be passed as HTML attributes — an HTML attribute is always a string and will be ignored or mis-parsed.

```js
const chat = document.querySelector('kc-chat');
chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
```
```html
<kc-chat messages="[...]"></kc-chat>  <!-- ❌ never works -->
```

Only scalar values (string/number/boolean) work as attributes (e.g. `placeholder`, `loading`, `theme`).

## Two layers

**Layer 1 — batteries-included web components** (`import '@kitn.ai/chat/elements'`):
Drop an element into any framework (React, Vue, plain HTML). Data in via JS properties; interactions out via non-bubbling CustomEvents.

- `<kc-chat>` — full chat UI (message list + prompt input). The primary starting point.
- `<kc-conversations>` — sidebar conversation browser with group support.
- `<kc-prompt-input>` — standalone composer with send button.

**Layer 2 — composable primitives** (`import { … } from '@kitn.ai/chat'`):
All 44 elements are also exported individually. Use them for custom layouts or features `<kc-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.

## Key rules for the web components

1. **Array/object data = JS properties** (see above). Scalars may be attributes.
2. **Events are non-bubbling `CustomEvent`s** — listen directly on the element:
   `chat.addEventListener('kc-submit', (e) => console.log(e.detail.value))`
3. **`theme` attribute** (`'light' | 'dark' | 'auto'`) works on every element. Default `auto` follows `prefers-color-scheme`.
4. **Theming via CSS custom properties** — override `--kc-color-*` tokens on `:root`; they pierce Shadow DOM.

## ChatMessage schema (required for `<kc-chat>`)

```ts
interface ChatMessage {
  id: string;
  role: 'user' | 'assistant';
  content: string;
  reasoning?: { text: string; label?: string };
  tools?: ToolPart[];
  attachments?: AttachmentData[];
  actions?: ('copy' | 'like' | 'dislike' | 'regenerate' | 'edit')[];
}
```

## Framework wiring

**Plain HTML / CDN**
```html
<script type="module" src="https://unpkg.com/@kitn.ai/chat/elements"></script>
<kc-chat style="display:block;height:100vh"></kc-chat>
<script type="module">
  const chat = document.querySelector('kc-chat');
  chat.messages = [];
</script>
```

**React** — typed wrappers auto-set properties and expose `on<Event>` props:
```tsx
import { Chat } from '@kitn.ai/chat/react';
<Chat messages={messages} onSubmit={(e) => send(e.detail.value)} />
```

**Vue** — use the element directly; pass arrays via `.prop`:
```vue
<kc-chat :messages.prop="messages" @kc-submit="send" />
```

## Theming

```css
:root {
  --kc-color-background: #0f0f0f;
  --kc-color-primary: #7c3aed;
  --kc-color-muted: #1e1e1e;
}
```

For plain HTML/CDN: `<link rel="stylesheet" href="…/@kitn.ai/chat/theme.tokens.css">`.
For Tailwind builds: `@import "@kitn.ai/chat/theme.css"` in your CSS.

## Docs

- Full element reference (all 44 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
- Machine-readable Custom Elements Manifest: https://unpkg.com/@kitn.ai/chat/dist/custom-elements.json
- Working examples: https://github.com/kitn-ai/chat/tree/main/examples
- Storybook: https://storybook.kitn.dev
- Repository: https://github.com/kitn-ai/chat