@iyulab/chat-components 0.5.0 → 0.5.1

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"]
+}
+```

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

@@ -0,0 +1,112 @@
+# ViewPromptBuilder
+
+```ts
+import { ViewPromptBuilder, PresetView } from '@iyulab/chat-components';
+```
+
+Singleton utility that registers views and generates LLM system prompt instructions. No manual parsing is needed — `u-marked-block` automatically renders `view-json` code blocks via `u-view`.
+
+---
+
+## Overview
+
+```ts
+import { ViewPromptBuilder, PresetView } from '@iyulab/chat-components';
+
+const builder = ViewPromptBuilder.instance;
+
+// 1. Register preset views
+builder.use(PresetView.All);
+// Or selectively
+builder.use(PresetView.Images | PresetView.Chart);
+
+// 2. Register a custom view
+builder.add({
+  element: MyCustomView,    // CustomElementConstructor
+  tag: 'my-custom-view',
+  description: 'Display a custom visualization',
+  properties: {
+    data: { type: 'array', description: 'Data array' }
+  },
+  required: ['data']
+});
+
+// 3. Inject into LLM system prompt
+const instruction = builder.build();
+```
+
+When the LLM outputs a `view-json` block, `u-marked-block` renders it automatically:
+
+````
+```view-json
+{
+  "tag": "u-chart-view",
+  "properties": {
+    "type": "pie",
+    "data": {
+      "labels": ["A", "B", "C"],
+      "datasets": [{ "data": [30, 50, 20] }]
+    }
+  }
+}
+```
+````
+
+---
+
+## API
+
+### `ViewPromptBuilder.instance`
+
+Returns the singleton. Created on first access.
+
+### `.use(flags: PresetView): this`
+
+Registers preset views by bit flag.
+
+```ts
+builder.use(PresetView.Images);
+builder.use(PresetView.All);
+builder.use(PresetView.Images | PresetView.Chart);
+```
+
+### `.add(definition: ViewDefinition): this`
+
+Registers a custom view and its custom element. Throws if the same `tag` is already registered or if the tag is already defined with a different class.
+
+```ts
+interface ViewDefinition {
+  element: CustomElementConstructor;
+  tag: string;
+  description: string;
+  properties?: Record<string, JsonSchema>;
+  required?: string[];
+}
+```
+
+### `.build(): string`
+
+Returns LLM system prompt instructions for all registered views. Returns an empty string if no views are registered.
+
+---
+
+## PresetView Flags
+
+```ts
+enum PresetView {
+  Images = 1 << 0,   // u-images-view
+  Video  = 1 << 1,   // u-video-view
+  Map    = 1 << 3,   // u-map-view
+  Chart  = 1 << 4,   // u-chart-view
+  All    = Images | Video | Map | Chart
+}
+```
+
+### Preset View Schema Summary
+
+| Tag | Key Properties |
+|-----|----------------|
+| `u-images-view` | `items: [{ src, alt?, caption? }]` |
+| `u-video-view`  | `src`, `poster?`, `ratio?` |
+| `u-map-view`    | `lat`, `lng`, `zoom?`, `label?`, `description?` |
+| `u-chart-view`  | `type`, `data`, `options?` |