# @loquix/core

Web Components for AI/LLM chat interfaces. Framework-agnostic, built with [Lit](https://lit.dev/).

## Install

```bash
npm install @loquix/core
```

Peer dependency: `lit@^3.0.0`

## Quick Start

```html
<script type="module">
  import '@loquix/core';
</script>

<loquix-chat-container layout="full">
  <loquix-chat-header slot="header" agent-name="AI Assistant"></loquix-chat-header>
  <loquix-message-list slot="messages" auto-scroll></loquix-message-list>
  <loquix-chat-composer slot="composer" placeholder="Ask anything..."></loquix-chat-composer>
</loquix-chat-container>
```

## Import Strategies

```js
// Auto-register all 33 components (side-effect)
import '@loquix/core';

// Register a single component
import '@loquix/core/define/define-chat-container';

// Class-only (manual registration)
import { LoquixChatContainer } from '@loquix/core/classes/loquix-chat-container';

// Controllers
import { AgentController, UploadController } from '@loquix/core';

// Types only
import type { AgentProvider, Attachment, Suggestion } from '@loquix/core';

// CSS tokens
import '@loquix/core/tokens/variables.css';
import '@loquix/core/tokens/themes/dark.css';
```

## CDN

```html
<link rel="stylesheet" href="https://unpkg.com/@loquix/core/src/tokens/variables.css" />
<script type="module" src="https://unpkg.com/@loquix/core/cdn"></script>
```

## Components (33)

### Core Chat

- `<loquix-chat-container>` - Root layout container
- `<loquix-chat-header>` - Header bar with agent name
- `<loquix-chat-composer>` - Input area with send button
- `<loquix-prompt-input>` - Auto-resizing textarea
- `<loquix-message-list>` - Scrollable message container
- `<loquix-message-item>` - Single message bubble
- `<loquix-message-content>` - Text/code content renderer
- `<loquix-message-avatar>` - User/AI avatar
- `<loquix-typing-indicator>` - Animated typing dots
- `<loquix-generation-controls>` - Stop/pause/resume buttons
- `<loquix-composer-toolbar>` - Toolbar with left/right slots

### Actions

- `<loquix-action-button>` - Generic action button
- `<loquix-action-copy>` - Copy to clipboard
- `<loquix-action-edit>` - Edit message (inline or modal)
- `<loquix-action-feedback>` - Thumbs up/down
- `<loquix-message-actions>` - Action button toolbar

### Onboarding

- `<loquix-suggestion-chips>` - Suggestion chip strip
- `<loquix-follow-up-suggestions>` - Follow-up suggestions after messages
- `<loquix-welcome-screen>` - Empty-state with suggestions
- `<loquix-template-card>` - Template preview card
- `<loquix-template-picker>` - Searchable template picker dialog
- `<loquix-example-gallery>` - Categorized example prompt grid
- `<loquix-nudge-banner>` - Contextual tip/info banner

### Configuration

- `<loquix-mode-selector>` - AI mode tabs/dropdown/pills
- `<loquix-model-selector>` - LLM model dropdown with tiers
- `<loquix-dropdown-select>` - Rich dropdown with search
- `<loquix-attachment-chip>` - File attachment chip
- `<loquix-attachment-panel>` - File attachment panel with file picker and attachment chips
- `<loquix-drop-zone>` - Drag-and-drop overlay zone
- `<loquix-parameter-panel>` - AI parameter sliders/toggles
- `<loquix-filter-bar>` - Filter chip bar

### Disclosure

- `<loquix-disclosure-badge>` - "Generated by AI" badge
- `<loquix-caveat-notice>` - AI limitations notice

## Controllers

| Controller             | Purpose                                           |
| ---------------------- | ------------------------------------------------- |
| `AgentController`      | Orchestrates AI conversations via `AgentProvider` |
| `UploadController`     | File upload queue with retry and concurrency      |
| `StreamingController`  | ReadableStream lifecycle (pause/resume/abort)     |
| `KeyboardController`   | Keyboard shortcut bindings                        |
| `AutoScrollController` | Smart auto-scroll for message lists               |
| `ResizeController`     | Textarea auto-resize                              |

## Provider Interfaces

Implement these to connect to any AI or upload backend:

```typescript
import type { AgentProvider, UploadProvider } from '@loquix/core';
```

- **`AgentProvider`** - `send(messages, options) => Promise<{ stream: ReadableStream<string> }>`
- **`UploadProvider`** - `upload(file, options) => Promise<{ url: string }>`

## Theming

Override CSS custom properties with the `--loquix-` prefix:

```css
:root {
  --loquix-ai-color: #7c3aed;
  --loquix-user-color: #2563eb;
  --loquix-surface-bg: #ffffff;
  --loquix-border-radius: 12px;
}
```

Dark theme: add `data-theme="dark"` to any ancestor, or import the theme CSS.

## Events

All events use the `loquix-` prefix with `bubbles: true` and `composed: true`:

```js
container.addEventListener('loquix-submit', e => {
  console.log(e.detail.content); // typed!
});
```

30 typed events with full `HTMLElementEventMap` augmentation for TypeScript.

## Browser Support

Chromium, WebKit (Safari), Firefox. Requires ES2021+.

## License

MIT