@iyulab/chat-components 0.5.0 → 0.5.1

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 |

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

@@ -0,0 +1,57 @@
+# u-tool-block
+
+```ts
+import '@iyulab/chat-components/dist/components/blocks/UToolBlock.js';
+```
+
+**Tag:** `u-tool-block`
+
+Displays a tool call's input and output as collapsible JSON trees. Used to show LLM tool usage inline in a message.
+
+```html
+<!-- Tool call in progress -->
+<u-tool-block loading title="search_web"></u-tool-block>
+
+<!-- Completed tool call -->
+<u-tool-block
+  title="search_web"
+  .input=${{ query: "weather today" }}
+  .output=${{ results: ["Sunny, 25°C"] }}
+></u-tool-block>
+
+<!-- Expanded by default -->
+<u-tool-block
+  title="code_execution"
+  .collapsed=${false}
+  .input=${{ code: "print('hello')" }}
+  .output=${{ stdout: "hello\n" }}
+></u-tool-block>
+```
+
+Pass JSON via HTML attribute (uses `jsonAttrConverter`):
+
+```html
+<u-tool-block
+  title="calculator"
+  input='{"expression": "2 + 2"}'
+  output='{"result": 4}'
+></u-tool-block>
+```
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `title` | `string` | `''` | — | Tool name shown in the header (falls back to 'Tool Usage') |
+| `loading` | `boolean` | `false` | ✓ | Loading state. Shows spinner in header |
+| `collapsed` | `boolean` | `true` | ✓ | Collapsed state. Toggle by clicking the header |
+| `input` | `JsonNode` | `undefined` | — | Tool input JSON |
+| `output` | `JsonNode` | `undefined` | — | Tool output JSON |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `body` | Input / output display area |

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

@@ -0,0 +1,55 @@
+# u-video-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UVideoView.js';
+```
+
+**Tag:** `u-video-view`
+
+Embeds a video from YouTube, Vimeo, or a direct file URL. Automatically detects the platform from the URL and selects the appropriate player.
+
+```html
+<!-- YouTube -->
+<u-video-view src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"></u-video-view>
+
+<!-- Vimeo -->
+<u-video-view src="https://vimeo.com/123456789"></u-video-view>
+
+<!-- Direct video file -->
+<u-video-view
+  src="https://example.com/video.mp4"
+  poster="https://example.com/thumbnail.jpg"
+  ratio="4:3"
+></u-video-view>
+```
+
+LLM output example (`view-json` code block):
+
+````
+```view-json
+{
+  "tag": "u-video-view",
+  "properties": {
+    "src": "https://www.youtube.com/watch?v=VIDEO_ID"
+  }
+}
+```
+````
+
+---
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `src` | `string` | `undefined` | Video URL: YouTube, Vimeo, or direct file |
+| `poster` | `string` | `undefined` | Poster image URL for direct video files |
+| `ratio` | `'16:9'\|'4:3'\|'1:1'` | `'16:9'` | Aspect ratio |
+
+## Supported Platforms
+
+| Platform | URL Pattern | Embed Method |
+|----------|-------------|--------------|
+| YouTube | `youtube.com`, `youtu.be` | `youtube.com/embed/{id}` iframe |
+| Vimeo | `vimeo.com` | `player.vimeo.com/video/{id}` iframe |
+| Other | any URL | Native `<video>` element |

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

@@ -0,0 +1,51 @@
+# u-view
+
+```ts
+import '@iyulab/chat-components/dist/components/views/UView.js';
+```
+
+**Tag:** `u-view`
+
+Dynamic custom element renderer. Creates the element specified by `tag`, binds `properties` to it, and handles loading and error states. Used internally by `u-marked-block` to render `view-json` code blocks.
+
+```html
+<!-- Render u-chart-view dynamically -->
+<u-view
+  tag="u-chart-view"
+  .properties=${{
+    type: 'bar',
+    data: { labels: ['A', 'B'], datasets: [{ data: [10, 20] }] }
+  }}
+></u-view>
+
+<!-- Loading state (skeleton placeholder) -->
+<u-view tag="u-chart-view" loading></u-view>
+```
+
+How `u-marked-block` processes a `view-json` block:
+
+````
+```view-json
+{
+  "tag": "u-images-view",
+  "properties": { "items": [{ "src": "https://..." }] }
+}
+```
+````
+
+This is converted to `<u-view tag="u-images-view" ...>` via `UView.buildHTML()`.
+
+---
+
+## Properties
+
+| Property | Type | Default | Reflect | Description |
+|----------|------|---------|---------|-------------|
+| `tag` | `string` | `undefined` | — | Custom element tag to render. Must already be registered |
+| `properties` | `Record<string, unknown>` | `undefined` | — | Properties to bind to the rendered element |
+| `loading` | `boolean` | `false` | ✓ | Shows a skeleton placeholder instead of the element |
+| `blacklist` | `string[]` | `['innerHTML', 'outerHTML', ...]` | — | Property names blocked from binding for XSS prevention |
+
+## Security
+
+The following property names are blocked by default to prevent XSS: `innerHTML`, `outerHTML`, `textContent`, `innerText`, `outerText`, `srcdoc`. Extend `blacklist` to add more restrictions.