@iyulab/chat-components 0.4.0 → 0.5.1

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.

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

@@ -0,0 +1,60 @@
+# u-vote-button
+
+```ts
+import '@iyulab/chat-components/dist/components/buttons/UVoteButton.js';
+```
+
+**Tag:** `u-vote-button`
+
+Thumbs-up / thumbs-down vote button pair. Clicking a button toggles its active state; clicking the same button again resets back to `none`.
+
+```html
+<!-- Basic usage -->
+<u-vote-button></u-vote-button>
+
+<!-- Pre-set state -->
+<u-vote-button value="up"></u-vote-button>
+
+<!-- With tooltips -->
+<u-vote-button>
+  <span slot="up">Helpful</span>
+  <span slot="down">Not helpful</span>
+</u-vote-button>
+```
+
+```ts
+const voteBtn = document.querySelector('u-vote-button');
+
+voteBtn.addEventListener('change', () => {
+  console.log('vote:', voteBtn.value); // 'up' | 'down' | 'none'
+});
+```
+
+---
+
+## Slots
+
+| Name | Description |
+|------|-------------|
+| `up` | Tooltip text for the thumbs-up button |
+| `down` | Tooltip text for the thumbs-down button |
+
+## Properties
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `value` | `'none'\|'up'\|'down'` | `'none'` | Current vote state |
+
+## Events
+
+| Event | Description |
+|-------|-------------|
+| `change` | Fired when vote state changes (`bubbles: true, composed: true`) |
+
+## CSS Parts
+
+| Part | Description |
+|------|-------------|
+| `up-btn` | Thumbs-up button |
+| `down-btn` | Thumbs-down button |
+| `icon` | Button icon |

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

@@ -0,0 +1,115 @@
+# Types
+
+## BlockItem
+
+```ts
+import type { BlockItem } from '@iyulab/chat-components';
+```
+
+Union type for all message content blocks. Used to exchange structured message data with a server API.
+
+```ts
+type BlockItem =
+  | ThinkingBlockItem
+  | TextBlockItem
+  | MarkdownBlockItem
+  | FileBlockItem
+  | ToolBlockItem
+  | ReferenceBlockItem;
+```
+
+### ThinkingBlockItem → `u-think-block`
+
+```ts
+interface ThinkingBlockItem {
+  type: 'thinking';
+  loading?: boolean;  // Streaming in progress
+  value?: string;     // Reasoning text content
+}
+```
+
+### TextBlockItem → `u-text-block`
+
+```ts
+interface TextBlockItem {
+  type: 'text';
+  value?: string;
+}
+```
+
+### MarkdownBlockItem → `u-marked-block`
+
+```ts
+interface MarkdownBlockItem {
+  type: 'markdown';
+  value?: string;
+  refs?: ReferenceCitation[];
+}
+```
+
+### FileBlockItem → `u-file-block` / `u-prompt.files`
+
+```ts
+interface FileBlockItem {
+  type: 'file';
+  status?: 'idle' | 'uploading' | 'error';
+  name?: string;      // File name
+  size?: number;      // File size in bytes
+  mimeType?: string;  // MIME type, e.g. "image/png"
+  url?: string;       // Download URL
+  data?: any;
+}
+```
+
+### ToolBlockItem → `u-tool-block`
+
+```ts
+interface ToolBlockItem {
+  type: 'tool';
+  loading?: boolean;
+  title?: string;
+  input?: JsonNode;
+  output?: JsonNode;
+}
+```
+
+### ReferenceBlockItem → `u-ref-block`
+
+```ts
+interface ReferenceBlockItem {
+  type: 'reference';
+  sources: ReferenceSource[];
+}
+```
+
+---
+
+## ReferenceSource & ReferenceCitation
+
+```ts
+interface ReferenceSource {
+  type: 'web' | 'document';
+  url?: string;
+  title?: string;
+  snippet?: string;
+  tags?: string[];
+}
+
+interface ReferenceCitation {
+  startIndex: number;  // Start char index in markdown text
+  endIndex: number;    // End char index
+  label?: string;      // Display label, e.g. "[1]"
+  sources: ReferenceSource[];
+}
+```
+
+---
+
+## JsonNode
+
+```ts
+type JsonValue  = string | number | boolean | null;
+type JsonArray  = JsonNode[];
+type JsonObject = { [key: string]: JsonNode };
+type JsonNode   = JsonValue | JsonArray | JsonObject;
+```