@kitnai/chat 0.3.1 → 0.5.0

package/dist/llms/llms.txt

@@ -0,0 +1,104 @@
+<!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
+# @kitnai/chat
+
+> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 28 `kitn-*` custom elements: streaming responses, markdown + code rendering, reasoning/tool panels, attachments, conversation sidebar, voice input. Zero framework dependency for consumers; the SolidJS runtime it is authored in is bundled in, so the host needs nothing.
+
+## Install
+
+```bash
+npm install @kitnai/chat
+# SolidJS consumers also need the peer dep:
+npm install solid-js
+```
+
+## #1 rule: array/object data goes on JS PROPERTIES, not HTML attributes
+
+This is the single most common mistake. Arrays and objects (`messages`, `models`, `context`, `suggestions`, `slashCommands`, …) MUST be assigned as JavaScript properties on the element. They CANNOT be passed as HTML attributes — an HTML attribute is always a string and will be ignored or mis-parsed.
+
+```js
+const chat = document.querySelector('kitn-chat');
+chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
+```
+```html
+<kitn-chat messages="[...]"></kitn-chat>  <!-- ❌ never works -->
+```
+
+Only scalar values (string/number/boolean) work as attributes (e.g. `placeholder`, `loading`, `theme`).
+
+## Two layers
+
+**Layer 1 — batteries-included web components** (`import '@kitnai/chat/elements'`):
+Drop an element into any framework (React, Vue, plain HTML). Data in via JS properties; interactions out via non-bubbling CustomEvents.
+
+- `<kitn-chat>` — full chat UI (message list + prompt input). The primary starting point.
+- `<kitn-conversation-list>` — sidebar conversation browser with group support.
+- `<kitn-prompt-input>` — standalone composer with send button.
+
+**Layer 2 — composable primitives** (`import { … } from '@kitnai/chat'`):
+All 28 elements are also exported individually. Use them for custom layouts or features `<kitn-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
+
+## Key rules for the web components
+
+1. **Array/object data = JS properties** (see above). Scalars may be attributes.
+2. **Events are non-bubbling `CustomEvent`s** — listen directly on the element:
+   `chat.addEventListener('submit', (e) => console.log(e.detail.value))`
+3. **`theme` attribute** (`'light' | 'dark' | 'auto'`) works on every element. Default `auto` follows `prefers-color-scheme`.
+4. **Theming via CSS custom properties** — override `--kitn-color-*` tokens on `:root`; they pierce Shadow DOM.
+
+## ChatMessage schema (required for `<kitn-chat>`)
+
+```ts
+interface ChatMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  reasoning?: { text: string; label?: string };
+  tools?: ToolPart[];
+  attachments?: AttachmentData[];
+  actions?: ('copy' | 'like' | 'dislike' | 'regenerate' | 'edit')[];
+}
+```
+
+## Framework wiring
+
+**Plain HTML / CDN**
+```html
+<script type="module" src="https://unpkg.com/@kitnai/chat/elements"></script>
+<kitn-chat style="display:block;height:100vh"></kitn-chat>
+<script type="module">
+  const chat = document.querySelector('kitn-chat');
+  chat.messages = [];
+</script>
+```
+
+**React** — typed wrappers auto-set properties and expose `on<Event>` props:
+```tsx
+import { KitnChat } from '@kitnai/chat/react';
+<KitnChat messages={messages} onSubmit={(e) => send(e.detail.value)} />
+```
+
+**Vue** — use the element directly; pass arrays via `.prop`:
+```vue
+<kitn-chat :messages.prop="messages" @submit="send" />
+```
+
+## Theming
+
+```css
+:root {
+  --kitn-color-background: #0f0f0f;
+  --kitn-color-primary: #7c3aed;
+  --kitn-color-muted: #1e1e1e;
+}
+```
+
+For plain HTML/CDN: `<link rel="stylesheet" href="…/@kitnai/chat/theme.tokens.css">`.
+For Tailwind builds: `@import "@kitnai/chat/theme.css"` in your CSS.
+
+## Docs
+
+- Full element reference (all 28 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Machine-readable Custom Elements Manifest: https://unpkg.com/@kitnai/chat/dist/custom-elements.json
+- Working examples: https://github.com/kitn-ai/chat/tree/main/examples
+- Storybook: https://storybook.kitn.dev
+- Repository: https://github.com/kitn-ai/chat

package/dist/theme.tokens.css

@@ -0,0 +1,137 @@
+/* AUTO-GENERATED from theme.css by scripts/build-theme-tokens.mjs — do not edit.
+   Browser-ready token stylesheet for <link>/CDN consumers (the kit's ELEMENTS
+   are self-themed and don't need this; it themes host-page chrome / rebrands). */
+
+:root {
+  --color-background: var(--kitn-color-background, hsl(0 0% 100%));
+  --color-foreground: var(--kitn-color-foreground, hsl(240 10% 3.9%));
+  --color-card: var(--kitn-color-card, hsl(0 0% 100%));
+  --color-card-foreground: var(--kitn-color-card-foreground, hsl(240 10% 3.9%));
+  --color-popover: var(--kitn-color-popover, hsl(0 0% 100%));
+  --color-popover-foreground: var(--kitn-color-popover-foreground, hsl(240 10% 3.9%));
+  --color-primary: var(--kitn-color-primary, hsl(240 5.9% 10%));
+  --color-primary-foreground: var(--kitn-color-primary-foreground, hsl(0 0% 98%));
+  --color-secondary: var(--kitn-color-secondary, hsl(240 4.8% 95.9%));
+  --color-secondary-foreground: var(--kitn-color-secondary-foreground, hsl(240 5.9% 10%));
+  --color-muted: var(--kitn-color-muted, hsl(240 4.8% 95.9%));
+  --color-muted-foreground: var(--kitn-color-muted-foreground, hsl(240 3.8% 43%));
+  --color-accent: var(--kitn-color-accent, hsl(240 4.8% 95.9%));
+  --color-accent-foreground: var(--kitn-color-accent-foreground, hsl(240 5.9% 10%));
+  --color-destructive: var(--kitn-color-destructive, hsl(0 84.2% 60.2%));
+  --color-destructive-foreground: var(--kitn-color-destructive-foreground, hsl(0 0% 98%));
+  --color-border: var(--kitn-color-border, hsl(240 5.9% 90%));
+  --color-input: var(--kitn-color-input, hsl(240 5.9% 90%));
+  /* Focus ring — a deliberate blue (not a neutral) so keyboard focus is always
+     obvious and on-brand in both modes. Light uses a strong blue; dark uses a
+     brighter one for contrast on dark surfaces. Both clear WCAG 2.1 non-text
+     contrast (≥3:1) against the kit's backgrounds. Override via --kitn-color-ring. */
+  --color-ring: var(--kitn-color-ring, hsl(217 91% 53%));
+  --color-sidebar: var(--kitn-color-sidebar, hsl(0 0% 100%));
+  /* Inline `code` accent. Blue text on a translucent blue chip. */
+  --color-code-foreground: var(--kitn-color-code-foreground, hsl(224.3 76.3% 48%));
+  /* Tool/status chip hues. Each chip is hue text over a 15% translucent fill of
+     the SAME hue (set in tool.tsx). The bare hue is too light to reach WCAG AA
+     (4.5:1) on the faint fill in LIGHT mode, so the light values are darkened;
+     dark mode keeps brighter hues for AA on the dark fill. Override via
+     --kitn-color-tool-* to retheme. */
+  --color-tool-blue: var(--kitn-color-tool-blue, hsl(217 91% 38%));
+  --color-tool-amber: var(--kitn-color-tool-amber, hsl(38 92% 28%));
+  --color-tool-green: var(--kitn-color-tool-green, hsl(142 71% 26%));
+  --color-tool-red: var(--kitn-color-tool-red, hsl(0 72% 42%));
+  --radius: var(--kitn-radius, 0.6rem);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  /* Typography scale — semantic sizes shared by all components. Each generates a
+     Tailwind utility (text-caption / text-meta / text-body / text-title). To
+     restyle the kit's typography, override the namespaced --kitn-text-* token on
+     :root (e.g. `--kitn-text-body: 0.9375rem`) — it pierces the Shadow DOM via the
+     var() fallback, exactly like the --kitn-color-* tokens. The bare --text-*
+     names stay internal so a host's own --text-* can't collide. (Message/markdown/
+     input reading size also scales with the `proseSize` prop; these tokens cover
+     the fixed chrome & controls.) */
+  --text-caption: var(--kitn-text-caption, 0.6875rem);  --text-caption--line-height: 1rem;      /* 11px — micro labels, badges, sub-counts */
+  --text-meta: var(--kitn-text-meta, 0.75rem);     --text-meta--line-height: 1.1rem;       /* 12px — controls, toggles, switchers, captions */
+  --text-body: var(--kitn-text-body, 0.875rem);    --text-body--line-height: 1.45rem;      /* 14px — primary reading text */
+  --text-title: var(--kitn-text-title, 1rem);        --text-title--line-height: 1.5rem;      /* 16px — emphasis / headers */
+}
+
+@keyframes typing { 0%,100% { transform: translateY(0); opacity: .5 } 50% { transform: translateY(-2px); opacity: 1 } }
+@keyframes loading-dots { 0%,100% { opacity: 0 } 50% { opacity: 1 } }
+@keyframes wave { 0%,100% { transform: scaleY(1) } 50% { transform: scaleY(.6) } }
+@keyframes blink { 0%,100% { opacity: 1 } 50% { opacity: 0 } }
+@keyframes text-blink { 0%,100% { color: var(--color-primary) } 50% { color: var(--color-muted-foreground) } }
+@keyframes bounce-dots { 0%,100% { transform: scale(.8); opacity: .5 } 50% { transform: scale(1.2); opacity: 1 } }
+@keyframes thin-pulse { 0%,100% { transform: scale(.95); opacity: .8 } 50% { transform: scale(1.05); opacity: .4 } }
+@keyframes pulse-dot { 0%,100% { transform: scale(1); opacity: .8 } 50% { transform: scale(1.5); opacity: 1 } }
+@keyframes shimmer-text { 0% { background-position: 150% center } 100% { background-position: -150% center } }
+@keyframes wave-bars { 0%,100% { transform: scaleY(1); opacity: .5 } 50% { transform: scaleY(.6); opacity: 1 } }
+@keyframes shimmer { 0% { background-position: 200% 50% } 100% { background-position: -200% 50% } }
+@keyframes spinner-fade { 0% { opacity: 0 } 100% { opacity: 1 } }
+@keyframes collapsible-down { from { height: 0; opacity: 0 } to { height: var(--kb-collapsible-content-height); opacity: 1 } }
+@keyframes collapsible-up { from { height: var(--kb-collapsible-content-height); opacity: 1 } to { height: 0; opacity: 0 } }
+.dark {
+  --color-background: var(--kitn-color-background, hsl(50 2% 9%));
+  --color-foreground: var(--kitn-color-foreground, hsl(0 0% 98%));
+  --color-card: var(--kitn-color-card, hsl(45 4% 12%));
+  --color-card-foreground: var(--kitn-color-card-foreground, hsl(0 0% 98%));
+  --color-popover: var(--kitn-color-popover, hsl(45 4% 12%));
+  --color-popover-foreground: var(--kitn-color-popover-foreground, hsl(0 0% 98%));
+  --color-primary: var(--kitn-color-primary, hsl(0 0% 98%));
+  --color-primary-foreground: var(--kitn-color-primary-foreground, hsl(45 4% 11%));
+  --color-secondary: var(--kitn-color-secondary, hsl(45 4% 17%));
+  --color-secondary-foreground: var(--kitn-color-secondary-foreground, hsl(0 0% 98%));
+  --color-muted: var(--kitn-color-muted, hsl(45 4% 17%));
+  --color-muted-foreground: var(--kitn-color-muted-foreground, hsl(45 4% 64%));
+  --color-accent: var(--kitn-color-accent, hsl(45 4% 17%));
+  --color-accent-foreground: var(--kitn-color-accent-foreground, hsl(0 0% 98%));
+  --color-destructive: var(--kitn-color-destructive, hsl(0 62.8% 30.6%));
+  --color-destructive-foreground: var(--kitn-color-destructive-foreground, hsl(0 0% 98%));
+  --color-border: var(--kitn-color-border, hsl(45 4% 17%));
+  --color-input: var(--kitn-color-input, hsl(45 4% 17%));
+  --color-ring: var(--kitn-color-ring, hsl(217 91% 68%));
+  --color-sidebar: var(--kitn-color-sidebar, hsl(50 2% 7%));
+  --color-code-foreground: var(--kitn-color-code-foreground, hsl(213 94% 78%));
+
+  /* Tool/status chip hues — dark mode. Brighter hues reach AA on the dark fill. */
+  --color-tool-blue: var(--kitn-color-tool-blue, hsl(217 91% 70%));
+  --color-tool-amber: var(--kitn-color-tool-amber, hsl(38 92% 50%));
+  --color-tool-green: var(--kitn-color-tool-green, hsl(142 71% 45%));
+  --color-tool-red: var(--kitn-color-tool-red, hsl(0 84% 70%));
+}
+
+/* Self-contained markdown styling — replaces the typography plugin's `prose`.
+   Keyed on --color-* tokens so it themes with the rest of the kit. */
+.chat-markdown { color: var(--color-foreground); line-height: 1.6; }
+.chat-markdown > div:first-child > :first-child { margin-top: 0; }
+.chat-markdown > div:last-child > :last-child { margin-bottom: 0; }
+.chat-markdown p { margin: 0 0 0.75em; }
+.chat-markdown p:last-child { margin-bottom: 0; }
+.chat-markdown h1, .chat-markdown h2, .chat-markdown h3, .chat-markdown h4 {
+  margin: 1.2em 0 0.5em; font-weight: 600; line-height: 1.3; color: var(--color-foreground);
+}
+.chat-markdown h1 { font-size: 1.4em; } .chat-markdown h2 { font-size: 1.25em; }
+.chat-markdown h3 { font-size: 1.1em; } .chat-markdown h4 { font-size: 1em; }
+.chat-markdown ul, .chat-markdown ol { margin: 0 0 0.75em; padding-left: 1.4em; }
+.chat-markdown li { margin: 0.2em 0; }
+.chat-markdown ul { list-style: disc; } .chat-markdown ol { list-style: decimal; }
+.chat-markdown a { color: var(--color-primary); text-decoration: underline; text-underline-offset: 2px; }
+.chat-markdown strong { font-weight: 600; color: var(--color-foreground); }
+.chat-markdown em { font-style: italic; }
+.chat-markdown blockquote {
+  margin: 0 0 0.75em; padding-left: 0.9em; border-left: 2px solid var(--color-border);
+  color: var(--color-muted-foreground);
+}
+.chat-markdown hr { margin: 1em 0; border: 0; border-top: 1px solid var(--color-border); }
+.chat-markdown code:not(pre code) {
+  background: color-mix(in oklab, var(--color-code-foreground) 15%, transparent);
+  color: var(--color-code-foreground);
+  border-radius: 4px; padding: 0.1em 0.35em; font-size: 0.875em;
+  font-family: ui-monospace, "SF Mono", Menlo, monospace;
+}
+.chat-markdown table { width: 100%; border-collapse: collapse; margin: 0 0 0.75em; font-size: 0.9em; }
+.chat-markdown th, .chat-markdown td { border: 1px solid var(--color-border); padding: 0.4em 0.6em; text-align: left; }
+.chat-markdown th { font-weight: 600; background: color-mix(in oklab, var(--color-muted-foreground) 8%, transparent); }
+
+.scrollbar-thin { scrollbar-width: thin; scrollbar-color: var(--color-muted) transparent; }