@iyulab/chat-components 0.4.0 → 0.5.1

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?` |

package/dist/assets/action-prompt.md.js

@@ -1,3 +0,0 @@
-const template = "## Interactive Actions\n\nYou can guide the user with interactive actions by appending `action-json` fenced code blocks at the end of your response.\nThe user will see these as interactive UI elements and can click them to continue the conversation.\n\n**Output format (the fence language must be `action-json`):**\n```action-json\n{\n  \"type\": \"action-type-here\",\n  \"properties\" : {\n    \"key\": \"value\"\n  }\n}\n```\n\n**Rules — follow these STRICTLY. Violation means the feature will not work:**\n1. ALWAYS wrap the block in triple backticks with the language identifier `action-json` exactly — never use `json`, plain text, or any other identifier.\n2. `type` must be one of the exact strings listed below. Do not invent new types.\n3. Place ALL action blocks at the very end of your response, after all prose content.\n4. Output valid JSON only — no comments, no trailing commas, no markdown inside the block.\n5. Only include actions when they genuinely help the user continue the conversation.\n6. Do NOT describe or explain the action block in surrounding text (e.g. do not write \"Here are some suggested questions:\"). Just output the block.\n\n**Available actions:**\n{{ACTION_LIST}}\n\n---\n\n{{ACTION_DOCS}}\n";
-
-export { template as default };

package/dist/assets/widget-prompt.md.js

@@ -1,3 +0,0 @@
-const template = "## Renderable Widgets\n\nYou can render interactive visual widgets inside your response.\nWhen a widget would make your answer clearer or more useful, output a `widget-json` fenced code block.\n\n**Output format (the fence language must be `widget-json`):**\n```widget-json\n{\n  \"tag\": \"exact-widget-tag-here\",\n  \"properties\": {\n    \"key\": \"value\"\n  }\n}\n```\n\n**Rules — follow these strictly:**\n1. The fenced block language identifier must be `widget-json`, not `json` or anything else.\n2. `tag` must be one of the exact strings listed below. Never invent a tag.\n3. Include every property listed under `required`. Omit optional properties only if not needed.\n4. For schema-less `object` fields (e.g., Chart.js `data` / `options`), output a complete, realistic configuration using your knowledge.\n5. Output valid JSON — no comments, no trailing commas.\n\n**Available widgets:**\n{{WIDGET_LIST}}\n\n---\n\n{{WIDGET_DOCS}}\n";
-
-export { template as default };

package/dist/components/actions/UQuestionAction.component.js

@@ -1,58 +0,0 @@
-import { nothing, html } from 'lit';
-import { property } from 'lit/decorators.js';
-import { repeat } from 'lit/directives/repeat.js';
-import { UElement } from '@iyulab/components/dist/components/UElement.js';
-import { UButton } from '@iyulab/components/dist/components/button/UButton.component.js';
-import { styles } from './UQuestionAction.styles.js';
-
-var __defProp = Object.defineProperty;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = void 0 ;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (decorator(target, key, result) ) || result;
-  if (result) __defProp(target, key, result);
-  return result;
-};
-class UQuestionAction extends UElement {
-  constructor() {
-    super(...arguments);
-    this.choices = [];
-  }
-  static {
-    this.styles = [super.styles, styles];
-  }
-  static {
-    this.dependencies = {
-      "u-button": UButton
-    };
-  }
-  render() {
-    if (!this.choices || this.choices.length === 0) {
-      return nothing;
-    }
-    return html`
-      <p class="question" ?hidden=${!this.question}>${this.question}</p>
-      <div class="choices">
-        ${repeat(this.choices, (value, index) => html`
-          <u-button @click=${() => this.handleChoiceClick(index)}>
-            ${value}
-          </u-button>
-        `)}
-      </div>
-    `;
-  }
-  handleChoiceClick(index) {
-    const value = this.choices[index];
-    if (!value) return;
-    this.emit("u-submit", { value });
-  }
-}
-__decorateClass([
-  property({ type: String })
-], UQuestionAction.prototype, "question");
-__decorateClass([
-  property({ type: Array })
-], UQuestionAction.prototype, "choices");
-
-export { UQuestionAction };

package/dist/components/actions/UQuestionAction.d.ts

@@ -1,7 +0,0 @@
-import { UQuestionAction } from './UQuestionAction.component.js';
-declare global {
-    interface HTMLElementTagNameMap {
-        "u-question-action": UQuestionAction;
-    }
-}
-export { UQuestionAction };

package/dist/components/actions/UQuestionAction.js

@@ -1,5 +0,0 @@
-import { UQuestionAction } from './UQuestionAction.component.js';
-
-UQuestionAction.define("u-question-action");
-
-export { UQuestionAction };

package/dist/components/blocks/UCodeBlock.component.d.ts

@@ -1,25 +0,0 @@
-import { UElement } from '@iyulab/components/dist/components/UElement.js';
-/**
- * 코드 블록을 렌더링하는 컴포넌트입니다.
- * 언어와 코드를 받아 syntax highlighting을 적용합니다.
- */
-export declare class UCodeBlock extends UElement {
-    static styles: import('lit').CSSResultGroup[];
-    static dependencies: Record<string, typeof UElement>;
-    /** 클립보드 복사 상태를 나타내는 플래그입니다. */
-    isCopied: boolean;
-    /** 코드 블록이 로딩 중인지 여부를 나타냅니다. */
-    loading: boolean;
-    /** 코드 블록의 헤더를 숨길지 여부를 지정합니다. */
-    headless: boolean;
-    /** 코드 언어를 지정합니다. */
-    lang: string;
-    /** 표시할 코드 내용입니다. */
-    value?: string;
-    render(): import('lit-html').TemplateResult<1>;
-    /**
-     * slot에 할당된 코드를 value로 설정합니다.
-     * 이 기능을 통해 HTML 내에 직접 코드를 작성할 수 있습니다.
-     */
-    private handleSlotChange;
-}

package/dist/components/blocks/UCodeBlock.component.js

@@ -1,88 +0,0 @@
-import { html } from 'lit';
-import { state, property } from 'lit/decorators.js';
-import { unsafeHTML } from 'lit/directives/unsafe-html.js';
-import hljs from 'highlight.js';
-import { UElement } from '@iyulab/components/dist/components/UElement.js';
-import { UIcon } from '@iyulab/components/dist/components/icon/UIcon.component.js';
-import { USpinner } from '@iyulab/components/dist/components/spinner/USpinner.component.js';
-import { UCopyButton } from '../buttons/UCopyButton.component.js';
-import { styles } from './UCodeBlock.styles.js';
-
-var __defProp = Object.defineProperty;
-var __decorateClass = (decorators, target, key, kind) => {
-  var result = void 0 ;
-  for (var i = decorators.length - 1, decorator; i >= 0; i--)
-    if (decorator = decorators[i])
-      result = (decorator(target, key, result) ) || result;
-  if (result) __defProp(target, key, result);
-  return result;
-};
-class UCodeBlock extends UElement {
-  constructor() {
-    super(...arguments);
-    this.isCopied = false;
-    this.loading = false;
-    this.headless = false;
-    this.lang = "plaintext";
-    /**
-     * slot에 할당된 코드를 value로 설정합니다.
-     * 이 기능을 통해 HTML 내에 직접 코드를 작성할 수 있습니다.
-     */
-    this.handleSlotChange = (e) => {
-      const slot = e.target;
-      const nodes = slot.assignedNodes({ flatten: true });
-      this.value = nodes.map((node) => node.textContent).join("\n\n");
-    };
-  }
-  static {
-    this.styles = [super.styles, styles];
-  }
-  static {
-    this.dependencies = {
-      "u-icon": UIcon,
-      "u-spinner": USpinner,
-      "u-copy-button": UCopyButton
-    };
-  }
-  render() {
-    const lang = hljs.getLanguage(this.lang) ? this.lang : "plaintext";
-    const value = this.value || "";
-    return html`
-      <div class="header" ?hidden=${this.headless}>
-        <span class="status">
-          ${this.loading ? html`<u-spinner></u-spinner>` : html`<u-icon lib="internal" name="code-slash"></u-icon>`}
-        </span>
-        <span class="lang">
-          ${lang}
-        </span>
-        <div style="flex: 1"></div>
-        <u-copy-button
-          .value=${value}
-        ></u-copy-button>
-      </div>
-
-      <pre class="hljs">${unsafeHTML(hljs.highlight(value, {
-      language: lang
-    }).value)}</pre>
-
-      <slot hidden @slotchange=${this.handleSlotChange}></slot>
-    `;
-  }
-}
-__decorateClass([
-  state()
-], UCodeBlock.prototype, "isCopied");
-__decorateClass([
-  property({ type: Boolean, reflect: true })
-], UCodeBlock.prototype, "loading");
-__decorateClass([
-  property({ type: Boolean, reflect: true })
-], UCodeBlock.prototype, "headless");
-__decorateClass([
-  property({ type: String, reflect: true })
-], UCodeBlock.prototype, "lang");
-__decorateClass([
-  property({ type: String })
-], UCodeBlock.prototype, "value");
-
-export { UCodeBlock };