@iyulab/chat-components 0.5.0 → 0.5.1

package/skills/iyulab-chat-components/SKILL.md

@@ -0,0 +1,107 @@
+---
+name: iyulab-chat-components
+description: LLM chat UI component library. Covers all u-* custom elements for building chat interfaces — message rendering, chat input, markdown/code blocks, file attachments, reference citations, and the Intent/View system. Use when working with @iyulab/chat-components package.
+license: MIT
+metadata:
+  author: iyulab
+  version: "0.5.0"
+---
+
+# @iyulab/chat-components
+
+Web component library for building LLM chat interfaces, built on [Lit](https://lit.dev/). All components are custom elements (`u-*` tags) that work in any framework or vanilla HTML.
+
+## Quick Start
+
+```bash
+npm install @iyulab/chat-components
+```
+
+Import all components at once:
+
+```ts
+import '@iyulab/chat-components';
+```
+
+Import individual components (tree-shakable):
+
+```ts
+import '@iyulab/chat-components/dist/components/message/UMessage.js';
+import '@iyulab/chat-components/dist/components/prompt/UPrompt.js';
+```
+
+> For detailed setup and usage patterns, see [./references/usage.md](./references/usage.md).
+
+---
+
+## Components
+
+### Message & Input
+
+- [`u-message`](./references/components/message.md) — Chat message wrapper. Slot-based block layout, loading animation, bubble/default style variants
+- [`u-prompt`](./references/components/prompt.md) — Chat input component. File attachment preview, auto-resize textarea, integrated send/stop button
+
+### Content Blocks
+
+- [`u-marked-block`](./references/components/marked-block.md) — Renders markdown to HTML. KaTeX math, code highlighting, citation insertion, view-json/intent-json handling
+- [`u-code-block`](./references/components/code-block.md) — Highlight.js code block with language label and clipboard copy
+- [`u-text-block`](./references/components/text-block.md) — Plain text display or editable textarea
+- [`u-think-block`](./references/components/think-block.md) — LLM reasoning (thinking) block. Collapse/expand, auto-scroll
+- [`u-tool-block`](./references/components/tool-block.md) — Tool call input/output display. Collapse/expand
+- [`u-file-block`](./references/components/file-block.md) — File attachment card. Type icon, upload status, download, remove
+- [`u-ref-block`](./references/components/ref-block.md) — Reference source group block. Collapse/expand, grid of ref cards
+- [`u-json-block`](./references/components/json-block.md) — Visualizes JSON data as a collapsible tree
+- [`u-table-block`](./references/components/table-block.md) — Markdown table renderer. Column sort, search filter, CSV/XLS download
+
+### Action Buttons
+
+- [`u-copy-button`](./references/components/copy-button.md) — Clipboard copy button; icon changes after copy
+- [`u-vote-button`](./references/components/vote-button.md) — Thumbs-up / thumbs-down vote button pair
+- [`u-attach-button`](./references/components/attach-button.md) — File picker button; fires `attach` event with selected files
+
+### Reference Components
+
+- [`u-ref-tag`](./references/components/ref-tag.md) — Inline citation tag. Tooltip and external-link icon
+- [`u-ref-card`](./references/components/ref-card.md) — Reference source card. web/document type, favicon, tags
+- [`u-ref-card-group`](./references/components/ref-card-group.md) — Paginated group of reference cards
+
+### Intent Components
+
+- [`u-question-intent`](./references/components/question-intent.md) — LLM-generated question with clickable choice buttons
+
+### View Components
+
+- [`u-images-view`](./references/components/images-view.md) — Image gallery (carousel + lightbox)
+- [`u-video-view`](./references/components/video-view.md) — YouTube / Vimeo / direct video file player
+- [`u-chart-view`](./references/components/chart-view.md) — Chart.js charts (bar, line, pie, etc.)
+- [`u-map-view`](./references/components/map-view.md) — OpenStreetMap embed
+- [`u-view`](./references/components/view.md) — Dynamic custom element renderer (runtime for view-json blocks)
+
+---
+
+## Utilities
+
+- [`IntentPromptBuilder`](./references/utilities/intent-prompt-builder.md) — Build LLM system prompt instructions for intents and parse intent-json responses
+- [`ViewPromptBuilder`](./references/utilities/view-prompt-builder.md) — Build LLM system prompt instructions for views
+
+---
+
+## Types
+
+- [`BlockItem`](./references/types.md) — Union type for message content blocks (text, markdown, file, tool, reference, thinking)
+- `ReferenceSource` / `ReferenceCitation` — Citation source and inline citation position types
+- `IntentDefinition` / `PresetIntent` — Intent definition and preset bit flags
+- `ViewDefinition` / `PresetView` — View definition and preset bit flags
+
+---
+
+## Events
+
+| Event | Source | Detail Type | Description |
+|-------|--------|-------------|-------------|
+| `send` | `u-prompt` | `unknown` | Send button clicked or Enter pressed |
+| `stop` | `u-prompt` | `unknown` | Stop button clicked while loading |
+| `attach` | `u-attach-button` | `{ files: File[] }` | File selection completed |
+| `choice` | `u-question-intent` | `{ value: string }` | Choice button clicked |
+| `change` | `u-vote-button` | `Event` | Vote state changed |
+| `remove` | `u-file-block` | `RemoveEventDetail` | Remove button clicked |

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

@@ -0,0 +1,69 @@
+# u-attach-button
+
+```ts
+import '@iyulab/chat-components/dist/components/buttons/UAttachButton.js';
+```
+
+**Tag:** `u-attach-button`
+
+Opens a file picker dialog. Fires an `attach` event with the selected files. Place in `u-prompt`'s `left-actions` slot.
+
+```html
+<!-- Basic usage -->
+<u-attach-button></u-attach-button>
+
+<!-- Images only -->
+<u-attach-button accept="image/*">Add image</u-attach-button>
+
+<!-- Multiple files allowed -->
+<u-attach-button multiple accept="image/*,application/pdf">Attach files</u-attach-button>
+
+<!-- Inside u-prompt -->
+<u-prompt>
+  <u-attach-button
+    slot="left-actions"
+    multiple
+    accept="image/*,application/pdf,text/*"
+    @attach=${handleAttach}
+  >
+    Files
+  </u-attach-button>
+</u-prompt>
+```
+
+```ts
+const attachBtn = document.querySelector('u-attach-button');
+
+attachBtn.addEventListener('attach', (e) => {
+  const { files } = e.detail; // File[]
+  console.log('Selected files:', files.map(f => f.name));
+});
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Tooltip label text |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `accept` | `string` | `undefined` | Accepted MIME types (comma-separated). E.g. `"image/*"`, `"image/*,application/pdf"` |
+| `multiple` | `boolean` | `false` | Allow selecting multiple files |
+
+## Events
+
+| Event | Detail | Description |
+|-------|--------|-------------|
+| `attach` | `{ files: File[] }` | Fired after file selection. The file input is reset automatically |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `base` | The button element (`u-button`) |
+| `icon` | Paperclip icon |

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

@@ -0,0 +1,65 @@
+# u-chart-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UChartView.js';
+```
+
+**Tag:** `u-chart-view`
+
+Renders charts using Chart.js (lazy-loaded). Supports PNG and JSON download. Automatically re-renders when the page theme changes.
+
+```html
+<!-- Bar chart -->
+<u-chart-view
+  type="bar"
+  .data=${{
+    labels: ['Jan', 'Feb', 'Mar'],
+    datasets: [{ label: 'Revenue', data: [100, 200, 150] }]
+  }}
+></u-chart-view>
+
+<!-- Line chart with options -->
+<u-chart-view
+  type="line"
+  .data=${{
+    labels: ['A', 'B', 'C', 'D'],
+    datasets: [{ label: 'Trend', data: [10, 40, 30, 60], fill: true }]
+  }}
+  .options=${{ plugins: { legend: { position: 'bottom' } } }}
+></u-chart-view>
+```
+
+LLM output example (`view-json` code block):
+
+````
+```view-json
+{
+  "tag": "u-chart-view",
+  "properties": {
+    "type": "bar",
+    "data": {
+      "labels": ["Jan", "Feb", "Mar"],
+      "datasets": [{ "label": "Revenue", "data": [100, 200, 150] }]
+    }
+  }
+}
+```
+````
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `type` | `ChartType` | `undefined` | Chart type: `'bar'`, `'line'`, `'pie'`, `'doughnut'`, `'radar'`, `'polarArea'`, `'bubble'`, `'scatter'` |
+| `data` | `ChartData` | `undefined` | Chart.js data object with `labels` and `datasets` |
+| `options` | `ChartOptions` | `undefined` | Chart.js options object |
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Lazy load | Chart.js is dynamically imported on first render |
+| Download | Export chart as PNG or raw JSON data |
+| Theme sync | Watches `document.documentElement[theme]` and re-renders on change |

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

@@ -0,0 +1,42 @@
+# u-code-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UCodeBlock.js';
+```
+
+**Tag:** `u-code-block`
+
+Syntax-highlighted code block powered by Highlight.js. Shows a language label, clipboard copy button, and loading spinner. Automatically rendered inside `u-marked-block` for fenced code blocks.
+
+```html
+<!-- Direct usage -->
+<u-code-block lang="typescript" .value=${"const x: number = 42;"}></u-code-block>
+
+<!-- Without header -->
+<u-code-block lang="json" headless .value=${JSON.stringify({key: 'value'}, null, 2)}></u-code-block>
+
+<!-- Loading state (streaming) -->
+<u-code-block lang="python" loading .value=${"def hello():"}></u-code-block>
+
+<!-- Inject code via slot -->
+<u-code-block lang="javascript">
+  console.log("Hello from slot");
+</u-code-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `lang` | `string` | `'plaintext'` | ✓ | Code language. Falls back to `plaintext` if not supported by Highlight.js |
+| `value` | `string` | `undefined` | — | Code content. Can also be set via slot `textContent` |
+| `loading` | `boolean` | `false` | ✓ | Loading state. Replaces the code icon with a spinner in the header |
+| `headless` | `boolean` | `false` | ✓ | Hides the header (language label + copy button) |
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default, hidden)* | Code text injected directly as content; updates `value` on `slotchange` |

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 |