@iyulab/chat-components 0.4.0 → 0.5.1

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

@@ -0,0 +1,46 @@
+# u-copy-button
+
+```ts
+import '@iyulab/chat-components/dist/components/buttons/UCopyButton.js';
+```
+
+**Tag:** `u-copy-button`
+
+Copies text to the clipboard on click. The icon switches to a checkmark temporarily to confirm the action. Used inside `u-code-block` for code copying.
+
+```html
+<!-- Basic usage -->
+<u-copy-button .value=${"Text to copy"}></u-copy-button>
+
+<!-- With tooltip text -->
+<u-copy-button .value=${"code content"}>Copy</u-copy-button>
+
+<!-- Custom reset delay (default: 1000ms) -->
+<u-copy-button .value=${"text"} .delay=${2000}></u-copy-button>
+```
+
+Typical placement in a message footer:
+
+```html
+<u-message>
+  <u-marked-block slot="default" .value=${content}></u-marked-block>
+  <div slot="footer">
+    <u-copy-button .value=${content}>Copy</u-copy-button>
+  </div>
+</u-message>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Tooltip label text |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `undefined` | Text to copy to clipboard |
+| `delay` | `number` | `1000` | Time in ms before the icon resets after copying. `0` resets immediately |

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

@@ -0,0 +1,64 @@
+# u-file-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UFileBlock.js';
+```
+
+**Tag:** `u-file-block`
+
+Displays a single file as a card. Shows a type-appropriate icon, upload status, download link, and an optional remove button.
+
+```html
+<!-- Image file -->
+<u-file-block name="photo.png" type="image/png" size=${102400}></u-file-block>
+
+<!-- Uploading state -->
+<u-file-block name="document.pdf" type="application/pdf" status="uploading"></u-file-block>
+
+<!-- With download link -->
+<u-file-block
+  name="report.xlsx"
+  type="application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
+  size=${512000}
+  url="https://example.com/report.xlsx"
+></u-file-block>
+
+<!-- Removable (e.g. prompt attachment) -->
+<u-file-block
+  removable
+  name="image.jpg"
+  type="image/jpeg"
+  @remove=${handleRemove}
+></u-file-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `removable` | `boolean` | `false` | ✓ | Shows the remove button |
+| `status` | `'idle'\|'uploading'\|'error'` | `undefined` | ✓ | File state. `uploading` shows spinner; `error` shows error icon |
+| `name` | `string` | `undefined` | — | File name |
+| `type` | `string` | `undefined` | — | MIME type (determines icon) |
+| `size` | `number` | `undefined` | — | File size in bytes; auto-formatted to KB/MB |
+| `url` | `string` | `undefined` | — | Download URL. Shows download button when set |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `remove` | `RemoveEventDetail` | Fired when the remove button is clicked. If not cancelled, the element removes itself from the DOM |
+
+## Icon Resolution by MIME Type
+
+| MIME | Icon |
+|------|------|
+| `image/*` | `file-earmark-image` |
+| `video/*` | `file-earmark-play` |
+| `audio/*` | `file-earmark-music` |
+| `application/pdf` | `file-earmark-pdf` |
+| `application/zip` | `file-earmark-zip` |
+| `text/*` | `file-earmark-text` |
+| other | `file-earmark` |

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

@@ -0,0 +1,63 @@
+# u-images-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UImagesView.js';
+```
+
+**Tag:** `u-images-view`
+
+Image gallery view. Uses `u-carousel` for a horizontal slide layout, with a click-to-open lightbox. Shows up to 3 slides at once. Keyboard arrow keys navigate the lightbox.
+
+Automatically rendered by `u-marked-block` from a `view-json` code block.
+
+```html
+<!-- Direct usage -->
+<u-images-view
+  .items=${[
+    { src: 'https://example.com/photo1.jpg', alt: 'First photo', caption: 'Seoul at night' },
+    { src: 'https://example.com/photo2.jpg', caption: 'Busan beach' },
+    { src: 'https://example.com/photo3.jpg' }
+  ]}
+></u-images-view>
+```
+
+LLM output example (`view-json` code block):
+
+````
+```view-json
+{
+  "tag": "u-images-view",
+  "properties": {
+    "items": [
+      { "src": "https://example.com/photo.jpg", "alt": "Description", "caption": "Caption" }
+    ]
+  }
+}
+```
+````
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `items` | `ImageSlide[]` | `[]` | Array of image slide objects |
+
+## ImageSlide Type
+
+```ts
+interface ImageSlide {
+  src: string;       // Image URL (required)
+  alt?: string;      // Accessibility alt text
+  caption?: string;  // Caption shown below the image
+}
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Carousel | Up to 3 slides visible; draggable |
+| Lightbox | Full-screen modal on image click |
+| Keyboard | `←` `→` to navigate, `Esc` to close |

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

@@ -0,0 +1,41 @@
+# u-json-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UJsonBlock.js';
+```
+
+**Tag:** `u-json-block`
+
+Renders JSON data as a collapsible, interactive tree. Used inside `u-tool-block` to display tool call input and output.
+
+```html
+<!-- Basic usage -->
+<u-json-block .value=${{ name: "Alice", age: 30, hobbies: ["reading", "coding"] }}></u-json-block>
+
+<!-- Collapsed by default -->
+<u-json-block .expanded=${false} .value=${complexData}></u-json-block>
+```
+
+Pass JSON via HTML attribute:
+
+```html
+<u-json-block value='{"key": "value", "count": 42}'></u-json-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `JsonNode` | `{}` | JSON data to render (object, array, or primitive) |
+| `expanded` | `boolean` | `true` | Initial expand state for all object/array nodes |
+
+## JsonNode Type
+
+```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/components/map-view.md

@@ -0,0 +1,54 @@
+# u-map-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UMapView.js';
+```
+
+**Tag:** `u-map-view`
+
+Embeds an OpenStreetMap iframe centered on a given coordinate. A marker is placed at the specified `lat`/`lng` position.
+
+```html
+<!-- Basic map -->
+<u-map-view lat="37.5665" lng="126.9780"></u-map-view>
+
+<!-- With label, description, and zoom -->
+<u-map-view
+  lat="37.5665"
+  lng="126.9780"
+  zoom="13"
+  label="Seoul City Hall"
+  description="110 Sejong-daero, Jung-gu, Seoul"
+></u-map-view>
+```
+
+LLM output example (`view-json` code block):
+
+````
+```view-json
+{
+  "tag": "u-map-view",
+  "properties": {
+    "lat": 37.5665,
+    "lng": 126.9780,
+    "zoom": 15,
+    "label": "Seoul City Hall",
+    "description": "Jung-gu, Seoul"
+  }
+}
+```
+````
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `lat` | `number` | `undefined` | Latitude (required) |
+| `lng` | `number` | `undefined` | Longitude (required) |
+| `zoom` | `number` | `15` | Zoom level (1–19) |
+| `label` | `string` | `undefined` | Bold label shown below the map |
+| `description` | `string` | `undefined` | Description shown below the label |
+
+Renders nothing if either `lat` or `lng` is missing.

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

@@ -0,0 +1,53 @@
+# u-marked-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UMarkedBlock.js';
+```
+
+**Tag:** `u-marked-block`
+
+Renders markdown text to HTML. Supports KaTeX math equations, code syntax highlighting, inline citation tag injection, and special handling for `view-json` and `intent-json` code blocks. Applying an 80ms debounce makes it suitable for LLM streaming.
+
+**Special code fences:**
+- `` ```view-json `` → automatically rendered as a `u-view` component
+- `` ```intent-json `` → stripped from output (must be parsed separately via `IntentPromptBuilder`)
+- All other HTML inside markdown is escaped to prevent XSS
+
+```html
+<!-- Basic markdown -->
+<u-marked-block value="# Hello\n\nThis is **bold** and `code`."></u-marked-block>
+
+<!-- Math equations -->
+<u-marked-block value="Euler's identity: $e^{i\pi} + 1 = 0$"></u-marked-block>
+
+<!-- With citation references -->
+<u-marked-block
+  .value=${"The Earth orbits the Sun."}
+  .refs=${[{
+    startIndex: 4,
+    endIndex: 9,
+    label: '[1]',
+    sources: [{ type: 'web', url: 'https://...', title: 'Source' }]
+  }]}
+></u-marked-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `string` | `undefined` | Markdown text to render |
+| `refs` | `ReferenceCitation[]` | `undefined` | Citation list. `u-ref-tag` elements are automatically inserted at `startIndex`/`endIndex` positions |
+
+## ReferenceCitation Type
+
+```ts
+interface ReferenceCitation {
+  startIndex: number;    // Start character index in the markdown text
+  endIndex: number;      // End character index
+  label?: string;        // Display label, e.g. "[1]" or "(Smith, 2023)"
+  sources: ReferenceSource[];
+}
+```

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

@@ -0,0 +1,60 @@
+# u-message
+
+```ts
+import '@iyulab/chat-components/dist/components/message/UMessage.js';
+```
+
+**Tag:** `u-message`
+
+Chat message wrapper component. Arranges content blocks via slots, shows a loading animation while the response streams in, and supports bubble or default visual styles.
+
+```html
+<!-- Default AI message -->
+<u-message>
+  <u-marked-block .value=${"## Hello\nMarkdown here."}></u-marked-block>
+</u-message>
+
+<!-- User message (right-aligned, bubble style) -->
+<u-message position="right" variant="bubble">
+  <u-text-block .value=${"Hello!"}></u-text-block>
+</u-message>
+
+<!-- Loading state (streaming) -->
+<u-message loading>
+  <u-marked-block .value=${"Streaming..."}></u-marked-block>
+</u-message>
+
+<!-- With header and footer slots -->
+<u-message>
+  <div slot="header">AI Assistant</div>
+  <u-marked-block .value=${content}></u-marked-block>
+  <div slot="footer">
+    <u-copy-button .value=${content}></u-copy-button>
+    <u-vote-button></u-vote-button>
+  </div>
+</u-message>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `header` | Area above the message body (avatar, name, etc.) |
+| *(default)* | Message content blocks |
+| `footer` | Area below the message body (buttons, etc.); hidden while `loading` |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `loading` | `boolean` | `false` | ✓ | Loading state. Shows three-dot animation; hides `footer` slot |
+| `variant` | `'default'\|'bubble'` | `'default'` | ✓ | Visual style |
+| `position` | `'left'\|'right'` | `'left'` | ✓ | Message alignment |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `body` | Message body wrapper |

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

@@ -0,0 +1,102 @@
+# u-prompt
+
+```ts
+import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
+```
+
+**Tag:** `u-prompt`
+
+Chat input component. Combines a text input area, file attachment previews, and an integrated send/stop button.
+
+```html
+<!-- Basic usage -->
+<u-prompt placeholder="Type a message..."></u-prompt>
+
+<!-- Loading (streaming) state -->
+<u-prompt loading></u-prompt>
+
+<!-- With file attach button -->
+<u-prompt>
+  <u-attach-button slot="left-actions" multiple accept="image/*,application/pdf">
+    Attach
+  </u-attach-button>
+</u-prompt>
+```
+
+```ts
+const prompt = document.querySelector('u-prompt');
+
+// Send event
+prompt.addEventListener('send', () => {
+  console.log('value:', prompt.value);
+  console.log('files:', prompt.files);
+});
+
+// Stop event (fired when send button is clicked while loading=true)
+prompt.addEventListener('stop', () => {
+  console.log('stopped');
+});
+
+// Wire up file attach button
+prompt.addEventListener('attach', (e) => {
+  const { files } = e.detail;
+  prompt.files = [
+    ...(prompt.files ?? []),
+    ...files.map(f => ({
+      type: 'file' as const,
+      name: f.name,
+      size: f.size,
+      mimeType: f.type,
+      status: 'idle' as const,
+    }))
+  ];
+});
+
+// Programmatic submit
+prompt.submit();
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `header` | Area above the input |
+| `left-actions` | Left side of the control bar (e.g. attach button) |
+| `right-actions` | Right side of the control bar |
+| `footer` | Area below the input |
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `loading` | `boolean` | `false` | ✓ | Loading state. Send button becomes a stop button |
+| `value` | `string` | `undefined` | — | Text input value |
+| `files` | `FileBlockItem[]` | `undefined` | — | Attached file list |
+| `placeholder` | `string` | `undefined` | — | Input placeholder text |
+| `minRows` | `number` | `1` | — | Minimum textarea rows |
+| `maxRows` | `number` | `10` | — | Maximum textarea rows (scrolls beyond) |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `submit()` | Programmatically submit. Fires `stop` if loading, otherwise fires `send` (only when value or files present) |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `send` | `unknown` | Fired on Enter or send button click |
+| `stop` | `unknown` | Fired on send button click while loading |
+| `remove` | `RemoveEventDetail` | Fired when an attached file's remove button is clicked |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `input` | Text input area (`u-text-block`) |
+| `files` | File attachment preview area |
+| `control` | Bottom control row (actions + send button) |
+| `send-btn` | Send / stop button |

package/skills/iyulab-chat-components/references/components/question-intent.md

@@ -0,0 +1,75 @@
+# u-question-intent
+
+```ts
+import '@iyulab/chat-components/dist/components/intents/UQuestionIntent.js';
+```
+
+**Tag:** `u-question-intent`
+
+Renders a question with clickable choice buttons generated by the LLM. Fires a `choice` event when the user selects an option.
+
+`u-marked-block` strips `intent-json` code blocks from the rendered output, so you must parse them manually using `IntentPromptBuilder` and create this component yourself.
+
+```html
+<!-- Basic usage -->
+<u-question-intent
+  question="What topic are you interested in?"
+  .choices=${["Artificial Intelligence", "Blockchain", "Cloud Computing"]}
+></u-question-intent>
+
+<!-- Choices only, no question text -->
+<u-question-intent
+  .choices=${["Yes, continue", "No, stop"]}
+></u-question-intent>
+```
+
+```ts
+const intent = document.querySelector('u-question-intent');
+
+intent.addEventListener('choice', (e) => {
+  const { value } = e.detail; // selected choice text
+  console.log('Selected:', value);
+
+  // Auto-fill and submit the prompt
+  prompt.value = value;
+  prompt.submit();
+});
+```
+
+Parsing from an LLM response with `IntentPromptBuilder`:
+
+```ts
+import { IntentPromptBuilder, PresetIntent } from '@iyulab/chat-components';
+
+// Setup
+IntentPromptBuilder.instance.use(PresetIntent.Questions);
+
+// Parse LLM response
+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 ?? [];
+    messageContainer.appendChild(el);
+  }
+}
+
+markedBlock.value = cleanText;
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `question` | `string` | `undefined` | Question text shown above choices. Hidden if not set |
+| `choices` | `string[]` | `[]` | Clickable choices (1–5 recommended). Renders nothing if empty |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `choice` | `{ value: string }` | Fired when a choice button is clicked |

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

@@ -0,0 +1,45 @@
+# u-ref-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/URefBlock.js';
+```
+
+**Tag:** `u-ref-block`
+
+Displays a group of reference sources as a collapsible block with a `u-ref-card` grid layout.
+
+```html
+<!-- Basic usage -->
+<u-ref-block
+  title="References"
+  .sources=${[
+    { type: 'web', url: 'https://example.com', title: 'Example Page', snippet: 'Summary...' },
+    { type: 'document', title: 'Internal Report', snippet: 'Excerpt...', tags: ['report'] }
+  ]}
+></u-ref-block>
+
+<!-- Expanded by default -->
+<u-ref-block .collapsed=${false} .sources=${sources}></u-ref-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `title` | `string` | `''` | — | Header title (falls back to 'References') |
+| `collapsed` | `boolean` | `true` | ✓ | Collapsed state. Toggle by clicking the header |
+| `sources` | `ReferenceSource[]` | `undefined` | — | List of reference sources |
+
+## ReferenceSource Type
+
+```ts
+interface ReferenceSource {
+  type: 'web' | 'document';
+  url?: string;       // Link URL
+  title?: string;     // Card title
+  snippet?: string;   // Excerpt text
+  tags?: string[];    // Tag list
+}
+```

package/skills/iyulab-chat-components/references/components/ref-card-group.md

@@ -0,0 +1,41 @@
+# u-ref-card-group
+
+```ts
+import '@iyulab/chat-components/dist/components/references/URefCardGroup.js';
+```
+
+**Tag:** `u-ref-card-group`
+
+Groups multiple `u-ref-card` elements into a paginated slider. Previous/next navigation and a page indicator appear automatically when there are 2 or more cards.
+
+Used automatically by `u-marked-block` when processing citation data.
+
+```html
+<u-ref-card-group>
+  <u-ref-card type="web" url="https://example.com/1" title="First Source"></u-ref-card>
+  <u-ref-card type="web" url="https://example.com/2" title="Second Source"></u-ref-card>
+  <u-ref-card type="document" title="Internal Doc"></u-ref-card>
+</u-ref-card-group>
+```
+
+```ts
+const group = document.querySelector('u-ref-card-group');
+
+// Navigate to a specific card
+group.switch(1); // go to second card
+group.switch(-1); // wraps to last card
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | `u-ref-card` elements |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `switch(index)` | Navigate to the card at `index`. Wraps around on out-of-bounds values |