@kitnai/chat 0.4.0 → 0.6.0

package/README.md

@@ -1,15 +1,15 @@
 # @kitnai/chat
 
-A SolidJS component kit for building AI chat interfaces — message threads, prompt inputs, streaming responses, markdown + code rendering, reasoning/tool panels, attachments, and a conversation sidebar.
+Framework-agnostic web components for building AI chat interfaces — message threads, prompt inputs, streaming responses, markdown + code rendering, reasoning/tool panels, attachments, and a conversation sidebar. Drop them into any app: React, Vue, Angular, Svelte, or plain HTML.
 
 It can be consumed two ways:
 
-1. **As SolidJS components** — import the components directly into a SolidJS app for full compositional control.
-2. **As framework-agnostic web components** — drop `<kitn-chat>`, `<kitn-conversation-list>`, and `<kitn-prompt-input>` into any project (React, Vue, plain HTML). Each is fully style-isolated via Shadow DOM; SolidJS is bundled in, so the host needs nothing.
+1. **As framework-agnostic web components** *(primary)* — drop `<kitn-chat>`, `<kitn-conversation-list>`, and `<kitn-prompt-input>` into any project (React, Vue, Angular, Svelte, plain HTML). Each is fully style-isolated via Shadow DOM, and the rendering runtime is bundled in, so the host needs nothing.
+2. **As native SolidJS components** — the kit is authored in SolidJS, so SolidJS apps can import the components directly for full compositional control. (This is a convenience for SolidJS users, not a requirement — the web components work everywhere.)
 
 ## Highlights
 
-- **~50 composable components** across three layers: headless primitives → UI primitives (built on [Kobalte](https://kobalte.dev)) → AI feature components.
+- **~50 composable components** across three layers: headless primitives → accessible UI primitives (built in-house, WCAG 2.1 AA — no third-party UI dependency) → AI feature components.
 - **Shadow-DOM web components** — zero CSS conflicts in any host. The host's styles can't leak in; the kit's Tailwind can't leak out.
 - **Lightweight by design** — a markdown-only `<kitn-chat>` is **~61 KB gzip** (one file). Syntax highlighting (Shiki) is loaded **on demand, per-language, with no WASM** — and never loads at all if you don't render code.
 - **Tailwind v4** design tokens — rebrand by overriding `--color-*` custom properties.
@@ -60,6 +60,25 @@ npm run build   # emits dist/kitn-chat.es.js
 
 The element bundle is **ES-module only** and loads via `<script type="module">` in every modern browser. See **[docs/web-components.md](docs/web-components.md)** for the full element API (every property, event, and the `ChatMessage` schema).
 
+#### Or load from a CDN (no build, no npm)
+
+The element bundle is a self-contained ES module — load it directly from [jsDelivr](https://www.jsdelivr.com/package/npm/@kitnai/chat) or [unpkg](https://unpkg.com/browse/@kitnai/chat/), no install or bundler required:
+
+```html
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/@kitnai/chat/dist/kitn-chat.es.js';
+  // …or unpkg: import 'https://unpkg.com/@kitnai/chat/dist/kitn-chat.es.js';
+</script>
+
+<kitn-chat></kitn-chat>
+```
+
+The URLs above track the **latest** release — handy for trying things out. **For production, pin an exact version** (e.g. `@kitnai/chat@0.4.0/dist/kitn-chat.es.js`): pinned URLs are immutable and cached far more aggressively, and — since this package is pre-1.0 — pinning shields you from breaking changes in a future minor release. SolidJS and the kit's CSS are bundled in, and the lazy code-highlighting chunks load from the same CDN on demand. To override design tokens, also include `theme.css`:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kitnai/chat/theme.css">
+```
+
 ### Option B — SolidJS components
 
 ```tsx
@@ -303,7 +322,7 @@ Storybook is the primary way to explore and develop components in isolation.
 ```
 src/
   primitives/    Headless logic hooks + ChatConfig + on-demand highlighter
-  ui/            UI primitives (Button, Dialog, Tooltip, … built on Kobalte)
+  ui/            Accessible UI primitives (Button, Dropdown, Tooltip, HoverCard, … built in-house, no third-party UI deps)
   components/    AI feature components (Message, PromptInput, Markdown, Tool, …)
   elements/      Web-component facades + defineKitnElement wrapper + Vite lib entry
   stories/       Composed example stories (full chat app, layouts)
@@ -314,6 +333,56 @@ docs/
 
 The web-component layer wraps a few coarse facades over the SolidJS components; the SolidJS API stays the source of truth and is unchanged by it.
 
+## Examples
+
+A set of runnable examples and a hosted component playground are included in the repo. See [`examples/README.md`](examples/README.md) for full details.
+
+### Composable showcase
+
+The composable showcase demonstrates every individual element in one page. Build the package first, then serve from the repo root:
+
+```bash
+npm run build     # produces dist/kitn-chat.es.js
+npm run examples  # static server at http://localhost:8000
+```
+
+Then open: **http://localhost:8000/examples/composable/index.html**
+
+### Storybook
+
+Storybook is the primary component playground for development:
+
+```bash
+npm run dev    # dev server at http://localhost:6006
+```
+
+The published docs are deployed to GitHub Pages:
+**https://kitn-ai.github.io/chat/**
+
+### Framework example apps
+
+The `examples/react`, `examples/solid`, `examples/angular`, and `examples/vue` directories are full Vite apps — install their dependencies and run the local dev server:
+
+```bash
+cd examples/react && npm install && npm run dev
+# or
+cd examples/solid && npm install && npm run dev
+# or
+cd examples/angular && npm install && npm run dev
+# or
+cd examples/vue && npm install && npm run dev
+```
+
+- `examples/react` — uses the generated React wrappers from `@kitnai/chat/react`
+- `examples/solid` — uses the raw SolidJS component API
+- `examples/angular` — uses the web components natively via Angular's `[prop]` / `(event)` bindings with `CUSTOM_ELEMENTS_SCHEMA` (no wrappers needed)
+- `examples/vue` — uses the web components natively via Vue's `:prop.prop` modifier and `@event` bindings; `isCustomElement` in `vite.config.ts` prevents Vue treating `kitn-*` tags as Vue components
+
+### Docs and reference
+
+- **[docs/web-components.md](docs/web-components.md)** — full element API: every property, event, and the `ChatMessage` schema.
+- **[llms.txt](llms.txt)** / **[llms-full.txt](llms-full.txt)** — dense machine-readable references for AI coding agents.
+
 ## Bundle size
 
 | Scenario | Loaded |

package/dist/custom-elements.json

@@ -568,6 +568,481 @@
             }
           ]
         },
+        {
+          "kind": "class",
+          "customElement": true,
+          "tagName": "kitn-chat-workspace",
+          "name": "KitnChatWorkspaceElement",
+          "description": "",
+          "members": [
+            {
+              "kind": "field",
+              "name": "groups",
+              "type": {
+                "text": "{ id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[]"
+              },
+              "description": "Pre-bucketed conversation groups for the sidebar. Set as a JS property.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "conversations",
+              "type": {
+                "text": "{ id: string; title: string; groupId?: undefined | string; scope: { type: \"document\" | \"collection\"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | \"transcript\" | \"markdown\"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string }[]"
+              },
+              "description": "Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "activeId",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Id of the open conversation, highlighted in the sidebar.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "messages",
+              "type": {
+                "text": "{ id: string; role: \"user\" | \"assistant\"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: \"input-streaming\" | \"input-available\" | \"output-available\" | \"output-error\"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: \"file\" | \"source-document\"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | (\"copy\" | \"like\" | \"dislike\" | \"regenerate\" | \"edit\")[] }[]"
+              },
+              "description": "The active conversation's message thread, newest last. Set as a JS property.",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "value",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "placeholder",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "loading",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "suggestions",
+              "type": {
+                "text": "undefined | string[]"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "suggestionMode",
+              "type": {
+                "text": "undefined | \"submit\" | \"fill\""
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "proseSize",
+              "type": {
+                "text": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "codeTheme",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "codeHighlight",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "chatTitle",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "models",
+              "type": {
+                "text": "undefined | { id: string; name: string; provider?: undefined | string }[]"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "currentModel",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "context",
+              "type": {
+                "text": "undefined | { usedTokens: number; maxTokens: number; inputTokens?: undefined | number; outputTokens?: undefined | number; estimatedCost?: undefined | number }"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "scrollButton",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "search",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "voice",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "slashCommands",
+              "type": {
+                "text": "undefined | { id: string; label: string; description?: undefined | string; category?: undefined | string }[]"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "slashActiveIds",
+              "type": {
+                "text": "undefined | string[]"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "slashCompact",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "sidebarWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Sidebar default width as a percent of the workspace (default 22).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "sidebarMinWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Sidebar min width in px (default 200).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "sidebarMaxWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Sidebar max width in px (default 420).",
+              "privacy": "public"
+            },
+            {
+              "kind": "field",
+              "name": "sidebarCollapsed",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Initial collapsed state of the sidebar (default false).",
+              "privacy": "public"
+            }
+          ],
+          "attributes": [
+            {
+              "name": "theme",
+              "type": {
+                "text": "'light' | 'dark' | 'auto'"
+              },
+              "description": "Color mode (auto follows prefers-color-scheme)."
+            },
+            {
+              "name": "active-id",
+              "fieldName": "activeId",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": "Id of the open conversation, highlighted in the sidebar."
+            },
+            {
+              "name": "value",
+              "fieldName": "value",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": ""
+            },
+            {
+              "name": "placeholder",
+              "fieldName": "placeholder",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": ""
+            },
+            {
+              "name": "loading",
+              "fieldName": "loading",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": ""
+            },
+            {
+              "name": "suggestion-mode",
+              "fieldName": "suggestionMode",
+              "type": {
+                "text": "undefined | \"submit\" | \"fill\""
+              },
+              "description": ""
+            },
+            {
+              "name": "prose-size",
+              "fieldName": "proseSize",
+              "type": {
+                "text": "undefined | \"xs\" | \"sm\" | \"base\" | \"lg\""
+              },
+              "description": ""
+            },
+            {
+              "name": "code-theme",
+              "fieldName": "codeTheme",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": ""
+            },
+            {
+              "name": "code-highlight",
+              "fieldName": "codeHighlight",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": ""
+            },
+            {
+              "name": "chat-title",
+              "fieldName": "chatTitle",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": ""
+            },
+            {
+              "name": "current-model",
+              "fieldName": "currentModel",
+              "type": {
+                "text": "undefined | string"
+              },
+              "description": ""
+            },
+            {
+              "name": "scroll-button",
+              "fieldName": "scrollButton",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": ""
+            },
+            {
+              "name": "search",
+              "fieldName": "search",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": ""
+            },
+            {
+              "name": "voice",
+              "fieldName": "voice",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": ""
+            },
+            {
+              "name": "slash-compact",
+              "fieldName": "slashCompact",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": ""
+            },
+            {
+              "name": "sidebar-width",
+              "fieldName": "sidebarWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Sidebar default width as a percent of the workspace (default 22)."
+            },
+            {
+              "name": "sidebar-min-width",
+              "fieldName": "sidebarMinWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Sidebar min width in px (default 200)."
+            },
+            {
+              "name": "sidebar-max-width",
+              "fieldName": "sidebarMaxWidth",
+              "type": {
+                "text": "undefined | number"
+              },
+              "description": "Sidebar max width in px (default 420)."
+            },
+            {
+              "name": "sidebar-collapsed",
+              "fieldName": "sidebarCollapsed",
+              "type": {
+                "text": "undefined | false | true"
+              },
+              "description": "Initial collapsed state of the sidebar (default false)."
+            }
+          ],
+          "events": [
+            {
+              "name": "conversationselect",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "messageaction",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "modelchange",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "newchat",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "search",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "sidebartoggle",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "slashselect",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "submit",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "suggestionclick",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "valuechange",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            },
+            {
+              "name": "voice",
+              "type": {
+                "text": "CustomEvent<unknown>"
+              },
+              "description": ""
+            }
+          ]
+        },
         {
           "kind": "class",
           "customElement": true,