@kitnai/chat 0.3.1 → 0.5.0

package/src/elements/thinking-bar.tsx

@@ -0,0 +1,34 @@
+import { defineKitnElement } from './define';
+import { ThinkingBar } from '../components/thinking-bar';
+
+interface Props extends Record<string, unknown> {
+  /** The shimmering label, e.g. "Thinking…". */
+  text?: string;
+  /** When true, show a "stop" affordance that fires a `stop` event. */
+  stoppable?: boolean;
+  /** Label for the stop affordance. */
+  stopLabel?: string;
+}
+
+/** Events fired by `<kitn-thinking-bar>`. */
+interface Events {
+  /** The "stop / answer now" affordance was clicked. */
+  stop: void;
+}
+
+/**
+ * `<kitn-thinking-bar>` — a pure leaf element: an animated "thinking" indicator
+ * (one of the primitives the batteries-included `<kitn-chat>` does NOT surface).
+ * Config via attributes, the only interaction (`stop`) comes back as an event.
+ */
+defineKitnElement<Props, Events>('kitn-thinking-bar', {
+  text: 'Thinking',
+  stoppable: false,
+  stopLabel: 'Answer now',
+}, (props, { dispatch, flag }) => (
+  <ThinkingBar
+    text={props.text}
+    stopLabel={props.stopLabel}
+    onStop={flag('stoppable') ? () => dispatch('stop') : undefined}
+  />
+));

package/src/elements/tool.tsx

@@ -0,0 +1,23 @@
+import { Show } from 'solid-js';
+import { defineKitnElement } from './define';
+import { Tool, type ToolPart } from '../components/tool';
+
+interface Props extends Record<string, unknown> {
+  /** The tool-call to display. Set as a JS property. */
+  tool?: ToolPart;
+  /** Start expanded. */
+  open?: boolean;
+}
+
+/**
+ * `<kitn-tool>` — a collapsible tool-call panel (input/output inspection with a
+ * state badge). Data via the `tool` property; `open` flag starts it expanded.
+ */
+defineKitnElement<Props>('kitn-tool', {
+  tool: undefined,
+  open: false,
+}, (props, { flag }) => (
+  <Show when={props.tool}>
+    <Tool toolPart={props.tool!} defaultOpen={flag('open')} />
+  </Show>
+));

package/src/elements/voice-input.tsx

@@ -0,0 +1,41 @@
+import { defineKitnElement } from './define';
+import { VoiceInput } from '../components/voice-input';
+
+interface Props extends Record<string, unknown> {
+  /**
+   * Transcriber the host supplies — records audio, returns the text. This is a
+   * **function-valued property** (`el.transcribe = async blob => '...'`) because
+   * a value-returning callback can't be modelled as a fire-and-forget event.
+   */
+  transcribe?: (audio: Blob) => Promise<string>;
+  /** Disable the mic button (non-interactive). */
+  disabled?: boolean;
+}
+
+/** Events fired by `<kitn-voice-input>`. */
+interface Events {
+  /** Raw audio captured (before transcription) — for hosts that prefer to
+   *  handle transcription themselves instead of via the `transcribe` property. */
+  audiocaptured: { blob: Blob };
+  /** Transcription completed (the `transcribe` property resolved). */
+  transcription: { text: string };
+}
+
+/**
+ * `<kitn-voice-input>` — a mic button that records and transcribes. The
+ * canonical **function-property** element: set `el.transcribe` to your async
+ * transcriber. Also emits `audiocaptured` (raw blob) and `transcription` (text).
+ */
+defineKitnElement<Props, Events>('kitn-voice-input', {
+  transcribe: undefined,
+  disabled: false,
+}, (props, { dispatch, flag }) => (
+  <VoiceInput
+    disabled={flag('disabled')}
+    onTranscribe={async (blob) => {
+      dispatch('audiocaptured', { blob });
+      return props.transcribe ? props.transcribe(blob) : '';
+    }}
+    onTranscription={(text) => dispatch('transcription', { text })}
+  />
+));

package/src/index.ts

@@ -34,7 +34,6 @@ export { Separator } from './ui/separator';
 export { ResizablePanelGroup, ResizablePanel, ResizableHandle } from './ui/resizable';
 export type { ResizablePanelGroupProps, ResizablePanelProps, ResizableHandleProps } from './ui/resizable';
 export { Skeleton } from './ui/skeleton';
-export { Dialog, DialogTrigger, DialogContent } from './ui/dialog';
 
 // Layer 3: AI/Feature Components
 export {

package/src/primitives/chat-config.tsx

@@ -7,14 +7,14 @@ export interface ChatConfigValue {
   proseSize: Accessor<ProseSize>;
   /** Shiki theme for code blocks */
   codeTheme: Accessor<string>;
-  /** Node Kobalte overlays portal into; undefined → document.body */
+  /** Node the kit's overlays portal into; undefined → document.body */
   portalMount: Accessor<HTMLElement | undefined>;
   /** Whether code blocks are syntax-highlighted; false → plain text, no Shiki loaded */
   codeHighlight: Accessor<boolean>;
 }
 
 const defaultConfig: ChatConfigValue = {
-  proseSize: () => 'base' as ProseSize,
+  proseSize: () => 'sm' as ProseSize,
   codeTheme: () => 'github-dark-dimmed',
   portalMount: () => undefined,
   codeHighlight: () => true,
@@ -37,7 +37,7 @@ export interface ChatConfigProps {
  */
 export function ChatConfig(props: ChatConfigProps) {
   const value: ChatConfigValue = {
-    proseSize: () => props.proseSize ?? 'base',
+    proseSize: () => props.proseSize ?? 'sm',
     codeTheme: () => props.codeTheme ?? 'github-dark-dimmed',
     portalMount: () => props.portalMount,
     codeHighlight: () => props.codeHighlight ?? true,

package/src/stories/docs/Accessibility.mdx

@@ -0,0 +1,119 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/Accessibility" />
+
+# Accessibility
+
+`@kitnai/chat` targets **WCAG 2.1 Level AA**. The kit is audited with [axe-core](https://github.com/dequelabs/axe-core) (via `scripts/audit-a11y.mjs`) and ships with **0 axe violations** in both light and dark modes. Keyboard navigation is verified with a Playwright browser test suite.
+
+This page describes the accessibility posture, the keyboard model, known limitations, and what you need to do as an integrator.
+
+---
+
+## Color contrast
+
+All text and UI chrome meet WCAG 2.1 AA contrast requirements (4.5:1 for body text, 3:1 for large text and UI components) in the default light and dark palettes.
+
+The `theme` attribute on every element (`light | dark | auto`) controls which token set loads. `auto` (the default) follows the OS `prefers-color-scheme` media query, so users who configure dark mode at the OS level get it automatically. Override either set with `--kitn-color-*` tokens — if you do, verify contrast yourself; the kit cannot audit tokens it does not control.
+
+---
+
+## Keyboard operability
+
+Every interactive control is reachable and operable without a mouse.
+
+### Focus order
+
+Tab moves through all focusable controls in DOM order. The prompt textarea, send button, attachment button, toolbar controls (search, mic), header controls (model switcher, context meter), message action buttons, suggestion chips, and conversation list items are all included. Focus rings are always visible — they are not hidden on `:focus`, only on `:focus-visible`.
+
+### Dropdowns and select menus (ModelSwitcher, ChatScopePicker, …)
+
+| Key | Action |
+|---|---|
+| Enter / Space / ↓ | Open the menu |
+| ↑ / ↓ | Move between items |
+| Home / End | Jump to first / last item |
+| Typeahead (letter keys) | Jump to the first item starting with that letter |
+| Enter / Space | Select the focused item |
+| Esc | Close without selecting; focus returns to the trigger |
+| Tab | Close and move focus past the trigger |
+
+Focus always returns to the trigger element after the menu closes, whether closed by Esc, selection, or a click outside.
+
+### Collapsible panels (Reasoning, Tool calls, …)
+
+| Key | Action |
+|---|---|
+| Enter / Space | Toggle expanded / collapsed |
+| Tab | Move into the expanded content |
+| Esc | Collapse (if focused inside) |
+
+### Slash command palette
+
+Typing `/` in the prompt input opens the command palette.
+
+| Key | Action |
+|---|---|
+| ↑ / ↓ | Navigate items |
+| Home / End | Jump to first / last item |
+| Enter / Tab | Select the focused command (inserts `/label ` into the input with caret at end) |
+| Esc | Close the palette; focus stays in the input |
+
+### Conversation list
+
+| Key | Action |
+|---|---|
+| ↑ / ↓ | Move between conversations |
+| Enter | Select the focused conversation |
+| Tab | Move through action buttons (if any) |
+
+---
+
+## Accessible names on icon buttons
+
+Every icon-only button (attach, send, mic, search, copy, like, dislike, regenerate, close) carries an accessible name via `aria-label`. Screen readers announce the button's purpose rather than "button" or nothing. Labels use plain language: "Send message", "Attach file", "Copy message", "Thumbs up", and so on.
+
+---
+
+## Tooltips and hover cards
+
+Tooltips and hover cards (on sources, context meter, etc.) are dismissable and persistent per WCAG 2.1 SC 1.4.13 (Content on Hover or Focus):
+
+- They appear on both hover and keyboard focus.
+- Moving the pointer over the tooltip/card content keeps it visible (it does not vanish when the pointer leaves the trigger).
+- They can be dismissed with **Esc** without moving focus.
+
+---
+
+## ARIA landmarks and live regions
+
+- The message list is marked as a log region (`role="log"`, `aria-live="polite"`) so streaming tokens are announced to screen readers without being intrusive.
+- The prompt area is labelled; the textarea carries its placeholder as an accessible name fallback.
+- The conversation sidebar is a navigation landmark (`<nav>`).
+
+---
+
+## Shadow DOM and screen readers
+
+All elements render inside Shadow DOM. Modern screen readers (NVDA + Chrome, JAWS + Chrome, VoiceOver + Safari/Chrome) pierce Shadow DOM correctly. Accessible names, roles, and live regions work as expected.
+
+---
+
+## Audit tooling
+
+Accessibility is verified with:
+
+- **axe-core** (`scripts/audit-a11y.mjs`) — automated rule checks in both light and dark themes. Zero violations at the time of build.
+- **Playwright keyboard tests** — 21-scenario browser test suite covering focus order, dropdown/collapsible/palette keyboard nav, ArrowUp/Down/Home/End/typeahead/Enter/Escape/Tab, and focus-return after close.
+
+The kit does not carry a "WCAG AA certified" certification — no automated tool can certify that. What it does carry is a targeted AA design, an axe-core clean bill, and a passing Playwright keyboard suite.
+
+---
+
+## What integrators need to do
+
+1. **Do not hide focus rings.** The kit renders visible focus rings via `:focus-visible`. Do not add `outline: none` or `outline: 0` in your host-page CSS targeting `*` or the element host.
+2. **Verify contrast if you override tokens.** Use a contrast checker after overriding any `--kitn-color-*` token.
+3. **Provide meaningful conversation titles.** The conversation list announces the `title` field to screen readers. "Chat 1" is less useful than "React integration help".
+4. **Set a meaningful `placeholder`.** The textarea placeholder doubles as an accessible name when no label is associated.
+5. **Check your theme choice.** Using `theme="light"` in a page the user has set to dark mode (or vice versa) can create contrast mismatches between kit components and host-page content. `theme="auto"` (the default) avoids this.

package/src/stories/docs/ForAIAgents.mdx

@@ -0,0 +1,93 @@
+import { Meta } from '@storybook/addon-docs/blocks';
+
+<Meta title="Docs/For AI Agents" />
+
+# For AI Agents / LLMs
+
+`@kitnai/chat` ships machine-readable orientation files that follow the
+[llmstxt.org](https://llmstxt.org) convention, so coding agents (Claude Code,
+Copilot, Cursor, Codex, …) can wire up the components correctly without guessing.
+
+**View them now:** <a href="/llms.txt" target="_blank" rel="noreferrer">llms.txt</a> ·
+<a href="/llms-full.txt" target="_blank" rel="noreferrer">llms-full.txt</a>
+(open in a new tab)
+
+## The files
+
+| File | Audience | Where to find it |
+|---|---|---|
+| <a href="/llms.txt" target="_blank" rel="noreferrer"><code>llms.txt</code></a> | Agents + humans | Repo root, the npm package root (`node_modules/@kitnai/chat/llms.txt`), and `https://kitn.dev/llms.txt` |
+| <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>llms-full.txt</code></a> | Agents | Same locations; the per-element API reference for **every** `kitn-*` element |
+
+Both files are **auto-generated** from `dist/custom-elements.json` by
+`scripts/gen-llms.mjs` during `npm run build`, so they never drift from the
+shipped API. Do not edit them by hand.
+
+- **`llms.txt`** (~4 KB) — a dense orientation: install, the property-vs-attribute
+  rule, the two-layer architecture, theming, and framework wiring. Fast to read.
+- **`llms-full.txt`** (~32 KB) — everything in `llms.txt` plus a generated props/events
+  table for each element, a streaming recipe, and a "build a chat app" runbook.
+
+## The #1 rule agents get wrong
+
+**Array and object data must be set as JavaScript properties, not HTML attributes.**
+An HTML attribute is always a string, so passing `messages`, `models`, `context`,
+`suggestions`, or `slashCommands` as an attribute silently fails.
+
+```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 props (string / number / boolean) work as attributes — for example
+`placeholder`, `loading`, and `theme`.
+
+## How agents consume these files
+
+| Tool | How it finds them |
+|---|---|
+| Claude Code | Reference `@llms.txt` in `CLAUDE.md`, or read `node_modules/@kitnai/chat/llms-full.txt` |
+| GitHub Copilot | Workspace indexing picks up the file in `node_modules`; reference it from `.github/copilot-instructions.md` |
+| Cursor | Point `.cursorrules` at the installed `llms.txt` |
+| Codex / ChatGPT | Fetch https://kitn.dev/llms.txt directly |
+| Any agent | `npm install @kitnai/chat` → file is at `node_modules/@kitnai/chat/llms.txt` |
+
+## Build a chat app (the runbook agents follow)
+
+```js
+import '@kitnai/chat/elements';
+const chat = document.querySelector('kitn-chat');
+chat.messages = [];
+
+chat.addEventListener('submit', async (e) => {
+  const userText = e.detail.value;
+
+  // Append the user message (new array)
+  const history = [...chat.messages, { id: crypto.randomUUID(), role: 'user', content: userText }];
+  chat.messages = history;
+  chat.loading = true;
+
+  // Empty assistant placeholder to stream into
+  const aid = crypto.randomUUID();
+  chat.messages = [...history, { id: aid, role: 'assistant', content: '' }];
+
+  // Stream — reassign a NEW array with a NEW message object each chunk.
+  // Mutating in place will NOT re-render.
+  let answer = '';
+  for await (const token of streamFromYourAPI(history)) {
+    answer += token;
+    chat.messages = chat.messages.map((m) => (m.id === aid ? { ...m, content: answer } : m));
+  }
+  chat.loading = false;
+});
+```
+
+## Links
+
+- <a href="/llms.txt" target="_blank" rel="noreferrer"><code>llms.txt</code></a> — orientation (also published at `https://kitn.dev/llms.txt`)
+- <a href="/llms-full.txt" target="_blank" rel="noreferrer"><code>llms-full.txt</code></a> — full per-element reference (also `https://kitn.dev/llms-full.txt`)
+- Custom Elements Manifest — `dist/custom-elements.json` (published at `https://unpkg.com/@kitnai/chat/dist/custom-elements.json`)

package/src/stories/docs/GettingStarted.mdx

@@ -1,7 +1,7 @@
 import { Meta, Canvas } from '@storybook/addon-docs/blocks';
 import * as FullChat from '../full-chat.stories';
 
-<Meta title="Getting Started" />
+<Meta title="Docs/Getting Started" />
 
 # Getting Started
 
@@ -73,4 +73,4 @@ Everything assembled into a real app — a conversation sidebar, a message threa
 
 Open it full-screen under **Examples → Full Chat App**, then explore each building block on its own page in the sidebar.
 
-Ready to make it yours? See **[Theming](?path=/docs/theming--docs)**. Wiring a real model? See **[Integrations](?path=/docs/integrations--docs)**.
+Ready to make it yours? See **[Theming](?path=/docs/docs-theming--docs)**. Wiring a real model? See **[Integrations](?path=/docs/docs-frameworks-integrations--docs)**.

package/src/stories/docs/Installation.mdx

@@ -1,6 +1,6 @@
 import { Meta } from '@storybook/addon-docs/blocks';
 
-<Meta title="Installation" />
+<Meta title="Docs/Installation" />
 
 # Installation
 
@@ -45,4 +45,31 @@ npm run build   # emits dist/kitn-chat.es.js
 - **SolidJS is bundled in** — the host page needs nothing else.
 - The kit's CSS is injected into each element's Shadow DOM automatically; importing `theme.css` is optional and only needed if you want to override design tokens.
 
-Head to **[Getting Started](?path=/docs/getting-started--docs)** to render your first chat.
+### Via CDN (no build step, no npm)
+
+The element bundle is a self-contained ES module, so you can load it straight from a CDN — no install, no bundler, no import map. It's published on both <a href="https://www.jsdelivr.com/package/npm/@kitnai/chat" target="_blank" rel="noreferrer">jsDelivr</a> and <a href="https://unpkg.com/browse/@kitnai/chat/" target="_blank" rel="noreferrer">unpkg</a>:
+
+```html
+<!-- jsDelivr -->
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/@kitnai/chat/dist/kitn-chat.es.js';
+</script>
+
+<!-- …or unpkg -->
+<script type="module">
+  import 'https://unpkg.com/@kitnai/chat/dist/kitn-chat.es.js';
+</script>
+
+<kitn-chat></kitn-chat>
+```
+
+- The URLs above track the **latest** release (no version) — they never go stale, so they're ideal for demos and quick starts.
+- **For production, pin an exact version** — e.g. `.../npm/@kitnai/chat@0.4.0/dist/kitn-chat.es.js`. Pinned URLs are immutable and cached far more aggressively (floating "latest" tags get revalidated every few hours), and — since this package is **pre-1.0** — pinning shields you from breaking changes in a future minor release. A version *range* (`@0` / `@0.4`) won't: pre-1.0 it can still resolve to a breaking minor.
+- SolidJS and the kit's CSS are bundled in, and the lazy syntax-highlighting chunks load from the **same CDN** automatically (they're relative to the bundle) — so nothing else is needed.
+- To override design tokens, also pull in `theme.css`:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@kitnai/chat/theme.css">
+```
+
+Head to **[Getting Started](?path=/docs/docs-getting-started--docs)** to render your first chat.