@iyulab/chat-components 0.5.0 → 0.5.2

package/skills/iyulab-chat-components/references/components/tool-block.md

@@ -0,0 +1,57 @@
+# u-tool-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UToolBlock.js';
+```
+
+**Tag:** `u-tool-block`
+
+Displays a tool call's input and output as collapsible JSON trees. Used to show LLM tool usage inline in a message.
+
+```html
+<!-- Tool call in progress -->
+<u-tool-block loading title="search_web"></u-tool-block>
+
+<!-- Completed tool call -->
+<u-tool-block
+  title="search_web"
+  .input=${{ query: "weather today" }}
+  .output=${{ results: ["Sunny, 25°C"] }}
+></u-tool-block>
+
+<!-- Expanded by default -->
+<u-tool-block
+  title="code_execution"
+  .collapsed=${false}
+  .input=${{ code: "print('hello')" }}
+  .output=${{ stdout: "hello\n" }}
+></u-tool-block>
+```
+
+Pass JSON via HTML attribute (uses `jsonAttrConverter`):
+
+```html
+<u-tool-block
+  title="calculator"
+  input='{"expression": "2 + 2"}'
+  output='{"result": 4}'
+></u-tool-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `title` | `string` | `''` | — | Tool name shown in the header (falls back to 'Tool Usage') |
+| `loading` | `boolean` | `false` | ✓ | Loading state. Shows spinner in header |
+| `collapsed` | `boolean` | `true` | ✓ | Collapsed state. Toggle by clicking the header |
+| `input` | `JsonNode` | `undefined` | — | Tool input JSON |
+| `output` | `JsonNode` | `undefined` | — | Tool output JSON |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `body` | Input / output display area |

package/skills/iyulab-chat-components/references/components/video-view.md

@@ -0,0 +1,55 @@
+# u-video-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UVideoView.js';
+```
+
+**Tag:** `u-video-view`
+
+Embeds a video from YouTube, Vimeo, or a direct file URL. Automatically detects the platform from the URL and selects the appropriate player.
+
+```html
+<!-- YouTube -->
+<u-video-view src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></u-video-view>
+
+<!-- Vimeo -->
+<u-video-view src="https://vimeo.com/123456789"></u-video-view>
+
+<!-- Direct video file -->
+<u-video-view
+  src="https://example.com/video.mp4"
+  poster="https://example.com/thumbnail.jpg"
+  ratio="4:3"
+></u-video-view>
+```
+
+LLM output example (`view-json` code block):
+
+````
+```view-json
+{
+  "tag": "u-video-view",
+  "properties": {
+    "src": "https://www.youtube.com/watch?v=VIDEO_ID"
+  }
+}
+```
+````
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | `string` | `undefined` | Video URL: YouTube, Vimeo, or direct file |
+| `poster` | `string` | `undefined` | Poster image URL for direct video files |
+| `ratio` | `'16:9'\|'4:3'\|'1:1'` | `'16:9'` | Aspect ratio |
+
+## Supported Platforms
+
+| Platform | URL Pattern | Embed Method |
+|----------|-------------|--------------|
+| YouTube | `youtube.com`, `youtu.be` | `youtube.com/embed/{id}` iframe |
+| Vimeo | `vimeo.com` | `player.vimeo.com/video/{id}` iframe |
+| Other | any URL | Native `<video>` element |

package/skills/iyulab-chat-components/references/components/view.md

@@ -0,0 +1,51 @@
+# u-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UView.js';
+```
+
+**Tag:** `u-view`
+
+Dynamic custom element renderer. Creates the element specified by `tag`, binds `properties` to it, and handles loading and error states. Used internally by `u-marked-block` to render `view-json` code blocks.
+
+```html
+<!-- Render u-chart-view dynamically -->
+<u-view
+  tag="u-chart-view"
+  .properties=${{
+    type: 'bar',
+    data: { labels: ['A', 'B'], datasets: [{ data: [10, 20] }] }
+  }}
+></u-view>
+
+<!-- Loading state (skeleton placeholder) -->
+<u-view tag="u-chart-view" loading></u-view>
+```
+
+How `u-marked-block` processes a `view-json` block:
+
+````
+```view-json
+{
+  "tag": "u-images-view",
+  "properties": { "items": [{ "src": "https://..." }] }
+}
+```
+````
+
+This is converted to `<u-view tag="u-images-view" ...>` via `UView.buildHTML()`.
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `tag` | `string` | `undefined` | — | Custom element tag to render. Must already be registered |
+| `properties` | `Record<string, unknown>` | `undefined` | — | Properties to bind to the rendered element |
+| `loading` | `boolean` | `false` | ✓ | Shows a skeleton placeholder instead of the element |
+| `blacklist` | `string[]` | `['innerHTML', 'outerHTML', ...]` | — | Property names blocked from binding for XSS prevention |
+
+## Security
+
+The following property names are blocked by default to prevent XSS: `innerHTML`, `outerHTML`, `textContent`, `innerText`, `outerText`, `srcdoc`. Extend `blacklist` to add more restrictions.

package/skills/iyulab-chat-components/references/components/vote-button.md

@@ -0,0 +1,60 @@
+# u-vote-button
+
+```ts
+import '@iyulab/chat-components/dist/components/buttons/UVoteButton.js';
+```
+
+**Tag:** `u-vote-button`
+
+Thumbs-up / thumbs-down vote button pair. Clicking a button toggles its active state; clicking the same button again resets back to `none`.
+
+```html
+<!-- Basic usage -->
+<u-vote-button></u-vote-button>
+
+<!-- Pre-set state -->
+<u-vote-button value="up"></u-vote-button>
+
+<!-- With tooltips -->
+<u-vote-button>
+  <span slot="up">Helpful</span>
+  <span slot="down">Not helpful</span>
+</u-vote-button>
+```
+
+```ts
+const voteBtn = document.querySelector('u-vote-button');
+
+voteBtn.addEventListener('change', () => {
+  console.log('vote:', voteBtn.value); // 'up' | 'down' | 'none'
+});
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `up` | Tooltip text for the thumbs-up button |
+| `down` | Tooltip text for the thumbs-down button |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `'none'\|'up'\|'down'` | `'none'` | Current vote state |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fired when vote state changes (`bubbles: true, composed: true`) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `up-btn` | Thumbs-up button |
+| `down-btn` | Thumbs-down button |
+| `icon` | Button icon |

package/skills/iyulab-chat-components/references/types.md

@@ -0,0 +1,115 @@
+# Types
+
+## BlockItem
+
+```ts
+import type { BlockItem } from '@iyulab/chat-components';
+```
+
+Union type for all message content blocks. Used to exchange structured message data with a server API.
+
+```ts
+type BlockItem =
+  | ThinkingBlockItem
+  | TextBlockItem
+  | MarkdownBlockItem
+  | FileBlockItem
+  | ToolBlockItem
+  | ReferenceBlockItem;
+```
+
+### ThinkingBlockItem → `u-think-block`
+
+```ts
+interface ThinkingBlockItem {
+  type: 'thinking';
+  loading?: boolean;  // Streaming in progress
+  value?: string;     // Reasoning text content
+}
+```
+
+### TextBlockItem → `u-text-block`
+
+```ts
+interface TextBlockItem {
+  type: 'text';
+  value?: string;
+}
+```
+
+### MarkdownBlockItem → `u-marked-block`
+
+```ts
+interface MarkdownBlockItem {
+  type: 'markdown';
+  value?: string;
+  refs?: ReferenceCitation[];
+}
+```
+
+### FileBlockItem → `u-file-block` / `u-prompt.files`
+
+```ts
+interface FileBlockItem {
+  type: 'file';
+  status?: 'idle' | 'uploading' | 'error';
+  name?: string;      // File name
+  size?: number;      // File size in bytes
+  mimeType?: string;  // MIME type, e.g. "image/png"
+  url?: string;       // Download URL
+  data?: any;
+}
+```
+
+### ToolBlockItem → `u-tool-block`
+
+```ts
+interface ToolBlockItem {
+  type: 'tool';
+  loading?: boolean;
+  title?: string;
+  input?: JsonNode;
+  output?: JsonNode;
+}
+```
+
+### ReferenceBlockItem → `u-ref-block`
+
+```ts
+interface ReferenceBlockItem {
+  type: 'reference';
+  sources: ReferenceSource[];
+}
+```
+
+---
+
+## ReferenceSource & ReferenceCitation
+
+```ts
+interface ReferenceSource {
+  type: 'web' | 'document';
+  url?: string;
+  title?: string;
+  snippet?: string;
+  tags?: string[];
+}
+
+interface ReferenceCitation {
+  startIndex: number;  // Start char index in markdown text
+  endIndex: number;    // End char index
+  label?: string;      // Display label, e.g. "[1]"
+  sources: ReferenceSource[];
+}
+```
+
+---
+
+## JsonNode
+
+```ts
+type JsonValue  = string | number | boolean | null;
+type JsonArray  = JsonNode[];
+type JsonObject = { [key: string]: JsonNode };
+type JsonNode   = JsonValue | JsonArray | JsonObject;
+```

package/skills/iyulab-chat-components/references/usage.md

@@ -0,0 +1,254 @@
+# Usage Guide
+
+## Installation
+
+```bash
+npm install @iyulab/chat-components
+```
+
+---
+
+## Importing Components
+
+### All at once
+
+```ts
+import '@iyulab/chat-components';
+```
+
+### Individual (tree-shakable)
+
+```ts
+import '@iyulab/chat-components/dist/components/message/UMessage.js';
+import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
+import '@iyulab/chat-components/dist/components/blocks/UMarkedBlock.js';
+```
+
+### Types only
+
+```ts
+import type { BlockItem, ReferenceSource } from '@iyulab/chat-components';
+import { PresetIntent, PresetView } from '@iyulab/chat-components';
+```
+
+---
+
+## Basic Chat UI
+
+Minimal setup connecting a message list and input prompt:
+
+```html
+<div id="chat-container">
+  <div id="messages"></div>
+  <u-prompt id="prompt" placeholder="Type a message..."></u-prompt>
+</div>
+```
+
+```ts
+import '@iyulab/chat-components';
+
+const prompt = document.getElementById('prompt');
+const messages = document.getElementById('messages');
+
+// Handle send event
+prompt.addEventListener('send', () => {
+  const value = prompt.value;
+  if (!value) return;
+
+  // Add user message
+  const userMsg = document.createElement('u-message');
+  userMsg.position = 'right';
+  userMsg.innerHTML = `<u-text-block .value="${value}"></u-text-block>`;
+  messages.appendChild(userMsg);
+  prompt.value = '';
+
+  // Add AI response (loading)
+  const aiMsg = document.createElement('u-message');
+  aiMsg.loading = true;
+  messages.appendChild(aiMsg);
+
+  // Handle LLM streaming...
+});
+
+// Handle file attachments
+prompt.addEventListener('attach', (e) => {
+  const { files } = e.detail;
+  prompt.files = files.map(f => ({
+    type: 'file',
+    name: f.name,
+    size: f.size,
+    mimeType: f.type,
+    status: 'idle',
+  }));
+});
+```
+
+---
+
+## Rendering Markdown Responses
+
+Stream LLM responses as markdown:
+
+```html
+<u-message>
+  <u-marked-block
+    .value=${"# Hello\n\nThis is **markdown** with `code`."}
+  ></u-marked-block>
+</u-message>
+```
+
+With citation references:
+
+```ts
+import type { ReferenceCitation } from '@iyulab/chat-components';
+
+const refs: ReferenceCitation[] = [
+  {
+    startIndex: 10,
+    endIndex: 20,
+    label: '[1]',
+    sources: [{ type: 'web', url: 'https://example.com', title: 'Example' }]
+  }
+];
+
+markedBlock.value = '...markdown text...';
+markedBlock.refs = refs;
+```
+
+---
+
+## Intent System
+
+Make the LLM output structured intent-json blocks by adding instructions to the system prompt:
+
+```ts
+import { IntentPromptBuilder, PresetIntent } from '@iyulab/chat-components';
+
+// Use preset intents
+IntentPromptBuilder.instance.use(PresetIntent.Questions);
+
+// Add custom intent
+IntentPromptBuilder.instance.add({
+  type: 'rating',
+  description: 'Ask user to rate something on a scale',
+  properties: {
+    label: { type: 'string', description: 'What to rate' },
+    max: { type: 'number', description: 'Max score (default: 5)' }
+  },
+  required: ['label']
+});
+
+// Inject into system prompt
+const systemPrompt = IntentPromptBuilder.instance.build();
+```
+
+Parse intent-json from the LLM response and render components:
+
+```ts
+const [cleanText, intents] = IntentPromptBuilder.instance.parse(llmResponse);
+
+for (const intent of intents) {
+  if (intent.type === 'question') {
+    const el = document.createElement('u-question-intent');
+    el.question = intent.properties?.question;
+    el.choices = intent.properties?.choices ?? [];
+    messageEl.appendChild(el);
+  }
+}
+
+markedBlock.value = cleanText;
+```
+
+---
+
+## View System
+
+Let the LLM render rich content (charts, maps, videos, etc.) via view-json code blocks:
+
+```ts
+import { ViewPromptBuilder, PresetView } from '@iyulab/chat-components';
+
+// Use all preset views
+ViewPromptBuilder.instance.use(PresetView.All);
+// Or selectively
+ViewPromptBuilder.instance.use(PresetView.Images | PresetView.Chart);
+
+// Inject into system prompt
+const systemPrompt = ViewPromptBuilder.instance.build();
+```
+
+When `u-marked-block` encounters a view-json code block from the LLM, it automatically renders it via `u-view`:
+
+````
+```view-json
+{
+  "tag": "u-chart-view",
+  "properties": {
+    "type": "bar",
+    "data": { "labels": ["A", "B"], "datasets": [{ "data": [10, 20] }] }
+  }
+}
+```
+````
+
+---
+
+## Rendering BlockItem Arrays
+
+Pattern for rendering structured message data received from a server:
+
+```ts
+import type { BlockItem } from '@iyulab/chat-components';
+
+function renderBlocks(blocks: BlockItem[], container: HTMLElement) {
+  for (const block of blocks) {
+    switch (block.type) {
+      case 'text': {
+        const el = document.createElement('u-text-block');
+        el.value = block.value;
+        container.appendChild(el);
+        break;
+      }
+      case 'markdown': {
+        const el = document.createElement('u-marked-block');
+        el.value = block.value;
+        el.refs = block.refs;
+        container.appendChild(el);
+        break;
+      }
+      case 'thinking': {
+        const el = document.createElement('u-think-block');
+        el.loading = block.loading ?? false;
+        el.value = block.value;
+        container.appendChild(el);
+        break;
+      }
+      case 'tool': {
+        const el = document.createElement('u-tool-block');
+        el.loading = block.loading ?? false;
+        el.title = block.title ?? '';
+        el.input = block.input;
+        el.output = block.output;
+        container.appendChild(el);
+        break;
+      }
+      case 'file': {
+        const el = document.createElement('u-file-block');
+        el.name = block.name;
+        el.size = block.size;
+        el.type = block.mimeType;
+        el.url = block.url;
+        el.status = block.status ?? 'idle';
+        container.appendChild(el);
+        break;
+      }
+      case 'reference': {
+        const el = document.createElement('u-ref-block');
+        el.sources = block.sources;
+        container.appendChild(el);
+        break;
+      }
+    }
+  }
+}
+```

package/skills/iyulab-chat-components/references/utilities/intent-prompt-builder.md

@@ -0,0 +1,123 @@
+# IntentPromptBuilder
+
+```ts
+import { IntentPromptBuilder, PresetIntent } from '@iyulab/chat-components';
+```
+
+Singleton utility that registers intents, generates LLM system prompt instructions, and parses `intent-json` blocks from LLM responses.
+
+---
+
+## Overview
+
+```ts
+import { IntentPromptBuilder, PresetIntent } from '@iyulab/chat-components';
+
+const builder = IntentPromptBuilder.instance;
+
+// 1. Register preset intents
+builder.use(PresetIntent.Questions);
+
+// 2. Register custom intents
+builder.add({
+  type: 'rating',
+  description: 'Prompt the user to rate something on a scale',
+  properties: {
+    label: { type: 'string', description: 'What to rate' },
+    max:   { type: 'number', description: 'Maximum score (default: 5)' }
+  },
+  required: ['label']
+});
+
+// 3. Inject into LLM system prompt
+const instruction = builder.build();
+
+// 4. Parse LLM response
+const [cleanText, intents] = builder.parse(llmResponse);
+// cleanText → markdown with intent-json blocks removed
+// intents   → parsed IntentSchema[]
+
+// 5. Render components
+for (const intent of intents) {
+  if (intent.type === 'question') {
+    const el = document.createElement('u-question-intent');
+    el.question = intent.properties?.question as string;
+    el.choices  = intent.properties?.choices as string[] ?? [];
+    container.appendChild(el);
+  }
+}
+
+markedBlock.value = cleanText;
+```
+
+---
+
+## API
+
+### `IntentPromptBuilder.instance`
+
+Returns the singleton. Created on first access.
+
+### `.use(flags: PresetIntent): this`
+
+Registers preset intents by bit flag.
+
+```ts
+builder.use(PresetIntent.Questions);
+builder.use(PresetIntent.All);
+```
+
+### `.add(definition: IntentDefinition): this`
+
+Registers a custom intent. Throws if the same `type` is already registered.
+
+```ts
+interface IntentDefinition {
+  type: string;
+  description: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+}
+```
+
+### `.build(): string`
+
+Returns LLM system prompt instructions for all registered intents. Returns an empty string if no intents are registered.
+
+### `.parse(value: string): [string, IntentSchema[]]`
+
+Extracts `intent-json` blocks from an LLM response string.
+
+- Index `[0]` — clean markdown text with intent-json blocks removed
+- Index `[1]` — array of parsed `IntentSchema` objects
+
+```ts
+interface IntentSchema {
+  type: string;
+  properties?: Record<string, unknown>;
+}
+```
+
+---
+
+## PresetIntent Flags
+
+```ts
+enum PresetIntent {
+  Questions = 1 << 0,
+  All       = Questions
+}
+```
+
+### Questions Intent Schema
+
+```json
+{
+  "type": "question",
+  "properties": {
+    "question": { "type": "string" },
+    "choices":  { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 5 }
+  },
+  "required": ["choices"]
+}
+```