@iyulab/chat-components 0.5.0 → 0.5.2

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 |

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

@@ -0,0 +1,48 @@
+# u-ref-card
+
+```ts
+import '@iyulab/chat-components/dist/components/references/URefCard.js';
+```
+
+**Tag:** `u-ref-card`
+
+Displays a single reference source as a card. Supports `web` and `document` types. For web sources, automatically fetches a favicon via the Google Favicon API.
+
+Extends `UDataElement`, so data can also be injected via a `<script type="application/json">` slot.
+
+```html
+<!-- Web source -->
+<u-ref-card
+  type="web"
+  url="https://example.com/article"
+  title="Article Title"
+  snippet="Short content summary..."
+  .tags=${["tech", "AI"]}
+></u-ref-card>
+
+<!-- Document source -->
+<u-ref-card
+  type="document"
+  title="Internal Document"
+  snippet="Document excerpt..."
+></u-ref-card>
+
+<!-- JSON slot injection -->
+<u-ref-card>
+  <script type="application/json">
+    { "type": "web", "url": "https://example.com", "title": "Example", "snippet": "Description" }
+  </script>
+</u-ref-card>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `type` | `'web'\|'document'` | `'web'` | ✓ | Card type. Determines badge icon |
+| `url` | `string` | `undefined` | — | External link URL. Click is suppressed if not set |
+| `title` | `string` | `''` | — | Card title (falls back to domain name for web type) |
+| `snippet` | `string` | `undefined` | — | Excerpt text |
+| `tags` | `string[]` | `undefined` | — | Tag list. Pass as JSON array string via HTML attribute |

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

@@ -0,0 +1,40 @@
+# u-ref-tag
+
+```ts
+import '@iyulab/chat-components/dist/components/references/URefTag.js';
+```
+
+**Tag:** `u-ref-tag`
+
+Inline citation tag inserted within markdown body text. Opens an external link on click and shows source details in a tooltip.
+
+Typically inserted automatically by `u-marked-block` when `refs` data is provided.
+
+```html
+<!-- Inline citation -->
+<u-ref-tag href="https://example.com">
+  [1]
+  <div slot="tooltip">Example Domain — source description...</div>
+</u-ref-tag>
+
+<!-- No href (local document) -->
+<u-ref-tag>
+  [2]
+  <div slot="tooltip">Internal document title</div>
+</u-ref-tag>
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| *(default)* | Citation label text (e.g. `[1]`, `(Smith, 2023)`) |
+| `tooltip` | Tooltip content (source details) |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `href` | `string` | `undefined` | External link URL. Click is suppressed if not set |

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

@@ -0,0 +1,63 @@
+# u-table-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UTableBlock.js';
+```
+
+**Tag:** `u-table-block`
+
+Renders tabular data with column sorting, search filtering, and CSV/XLS download. Automatically rendered inside `u-marked-block` for markdown tables.
+
+Extends `UDataElement`, so data can also be injected via a `<script type="application/json">` slot.
+
+```html
+<!-- Direct data binding -->
+<u-table-block
+  .headers=${[
+    { text: 'Name', align: 'left' },
+    { text: 'Age', align: 'center' },
+    { text: 'Score', align: 'right' }
+  ]}
+  .rows=${[
+    [{ text: 'Alice', align: 'left' }, { text: '30', align: 'center' }, { text: '95', align: 'right' }],
+    [{ text: 'Bob',   align: 'left' }, { text: '25', align: 'center' }, { text: '88', align: 'right' }]
+  ]}
+></u-table-block>
+
+<!-- JSON slot injection -->
+<u-table-block>
+  <script type="application/json">
+    {
+      "headers": [{ "text": "Name", "align": "left" }],
+      "rows": [[{ "text": "Alice", "align": "left" }]]
+    }
+  </script>
+</u-table-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `headers` | `TableCell[]` | `[]` | Header cells, each with `text` and `align` |
+| `rows` | `TableCell[][]` | `[]` | Row data; each row is an array of `TableCell` |
+
+## TableCell Type
+
+```ts
+interface TableCell {
+  text: string;
+  align: 'left' | 'center' | 'right' | null;
+}
+```
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| Column sort | Click a header to sort asc/desc |
+| Search filter | Search bar filters rows (debounced) |
+| CSV download | Downloads current filtered/sorted data as CSV |
+| XLS download | Downloads as Excel file |

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

@@ -0,0 +1,59 @@
+# u-text-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UTextBlock.js';
+```
+
+**Tag:** `u-text-block`
+
+Displays plain text or acts as an editable textarea. Used inside `u-prompt` as the input area.
+
+```html
+<!-- Read-only text display -->
+<u-text-block .value=${"Hello!"}></u-text-block>
+
+<!-- Editable textarea -->
+<u-text-block
+  editable
+  placeholder="Type a message..."
+  .minRows=${3}
+  .maxRows=${10}
+  .value=${inputValue}
+  @input=${handleInput}
+></u-text-block>
+```
+
+```ts
+const block = document.querySelector('u-text-block');
+
+block.addEventListener('input', () => {
+  console.log(block.value);
+});
+
+block.focus();
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | `undefined` | — | Text content |
+| `editable` | `boolean` | `false` | ✓ | Enables the textarea and focuses it on activation |
+| `placeholder` | `string` | `undefined` | — | Placeholder shown in edit mode |
+| `minRows` | `number` | `1` | — | Minimum visible rows |
+| `maxRows` | `number` | `undefined` | — | Maximum rows before scrolling |
+| `spellcheck` | `boolean` | `false` | — | Enables browser spell-check |
+
+## Methods
+
+| Method | Description |
+|--------|-------------|
+| `focus(options?)` | Focuses the inner textarea |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `input` | Fired on text change (re-dispatches the original `InputEvent`) |

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

@@ -0,0 +1,48 @@
+# u-think-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UThinkBlock.js';
+```
+
+**Tag:** `u-think-block`
+
+Displays LLM reasoning (thinking) content. Shows "Thinking..." while loading and switches to "Thought" on completion. Content can be collapsed or expanded via a header click.
+
+```html
+<!-- Reasoning in progress -->
+<u-think-block loading .value=${"Analyzing..."}></u-think-block>
+
+<!-- Completed (default: collapsed) -->
+<u-think-block .value=${"Full reasoning content here."}></u-think-block>
+
+<!-- Expanded with auto-scroll during streaming -->
+<u-think-block
+  auto-scroll
+  .collapsed=${false}
+  .value=${streamingThought}
+></u-think-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `value` | `string` | `undefined` | — | Reasoning text (rendered as markdown) |
+| `loading` | `boolean` | `false` | ✓ | Loading state. Shows spinner, displays "Thinking..." label |
+| `collapsed` | `boolean` | `true` | ✓ | Collapsed state. Toggle by clicking the header |
+| `autoScroll` | `boolean` | `false` | — | (`auto-scroll`) Scrolls to bottom on each `value` update. Disables on user scroll interaction |
+
+## Methods
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `scrollToBottom()` | `boolean` | Smoothly scrolls the body to the bottom. Returns `true` if body element exists |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `header` | Header row (icon + title + collapse toggle) |
+| `body` | Scrollable content area |