@kitnai/chat 0.6.0 → 0.8.0

package/llms.txt

@@ -1,7 +1,7 @@
 <!-- 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.
+> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 38 `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
 
@@ -16,11 +16,11 @@ npm install solid-js
 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');
+const chat = document.querySelector('kc-chat');
 chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
 ```
 ```html
-<kitn-chat messages="[...]"></kitn-chat>  <!-- ❌ never works -->
+<kc-chat messages="[...]"></kc-chat>  <!-- ❌ never works -->
 ```
 
 Only scalar values (string/number/boolean) work as attributes (e.g. `placeholder`, `loading`, `theme`).
@@ -30,12 +30,12 @@ Only scalar values (string/number/boolean) work as attributes (e.g. `placeholder
 **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.
+- `<kc-chat>` — full chat UI (message list + prompt input). The primary starting point.
+- `<kc-conversations>` — sidebar conversation browser with group support.
+- `<kc-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.
+All 38 elements are also exported individually. Use them for custom layouts or features `<kc-chat>` does not expose (ChainOfThought, FeedbackBar, ThinkingBar, VoiceInput, …). Your bundler tree-shakes the rest.
 
 ## Key rules for the web components
 
@@ -43,9 +43,9 @@ All 28 elements are also exported individually. Use them for custom layouts or f
 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.
+4. **Theming via CSS custom properties** — override `--kc-color-*` tokens on `:root`; they pierce Shadow DOM.
 
-## ChatMessage schema (required for `<kitn-chat>`)
+## ChatMessage schema (required for `<kc-chat>`)
 
 ```ts
 interface ChatMessage {
@@ -64,31 +64,31 @@ interface ChatMessage {
 **Plain HTML / CDN**
 ```html
 <script type="module" src="https://unpkg.com/@kitnai/chat/elements"></script>
-<kitn-chat style="display:block;height:100vh"></kitn-chat>
+<kc-chat style="display:block;height:100vh"></kc-chat>
 <script type="module">
-  const chat = document.querySelector('kitn-chat');
+  const chat = document.querySelector('kc-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)} />
+import { KcChat } from '@kitnai/chat/react';
+<KcChat 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" />
+<kc-chat :messages.prop="messages" @submit="send" />
 ```
 
 ## Theming
 
 ```css
 :root {
-  --kitn-color-background: #0f0f0f;
-  --kitn-color-primary: #7c3aed;
-  --kitn-color-muted: #1e1e1e;
+  --kc-color-background: #0f0f0f;
+  --kc-color-primary: #7c3aed;
+  --kc-color-muted: #1e1e1e;
 }
 ```
 
@@ -97,7 +97,7 @@ 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
+- Full element reference (all 38 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kitnai/chat",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS.",
   "keywords": [
@@ -57,11 +57,13 @@
     "prepublishOnly": "npm run build",
     "prebuild": "npm run build:css",
     "build": "vite build --config vite.config.ts",
-    "postbuild": "npm run build:theme && npm run build:api",
+    "postbuild": "npm run build:theme && npm run build:api && npm run build:schemas",
     "build:theme": "node scripts/build-theme-tokens.mjs",
     "build:api": "node scripts/gen-element-api.mjs",
+    "build:schemas": "node scripts/copy-card-schemas.mjs",
     "test": "vitest run",
     "test:react": "vitest run --config vitest.react.config.ts",
+    "test:storybook": "vitest run --project=storybook",
     "test:watch": "vitest",
     "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.react.json && tsc --noEmit -p tsconfig.react.test.json",
     "examples": "echo 'Serving repo root on http://localhost:8000 — open http://localhost:8000/examples/composable/index.html' && python3 -m http.server 8000",
@@ -86,6 +88,7 @@
   },
   "devDependencies": {
     "@solidjs/testing-library": "^0.8.0",
+    "@storybook/addon-a11y": "^10.4.2",
     "@storybook/addon-docs": "^10.3.5",
     "@storybook/addon-themes": "^10.3.5",
     "@storybook/addon-vitest": "^10.3.5",

package/src/components/artifact.stories.tsx

@@ -0,0 +1,138 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import { Artifact, type ArtifactFile, type ArtifactTab } from './artifact';
+import { componentDescription } from '../stories/docs/element-controls';
+
+// Storybook serves examples/artifact-fixtures at /artifact-fixtures.
+const BASE = '/artifact-fixtures';
+
+const FILES: ArtifactFile[] = [
+  {
+    path: 'index.html',
+    url: `${BASE}/index.html`,
+    type: 'html',
+    language: 'html',
+    code: `<!DOCTYPE html>\n<html lang="en">\n  <head><link rel="stylesheet" href="css/site.css" /></head>\n  <body><h1>Starboard</h1><a href="about.html">About</a></body>\n</html>`,
+  },
+  {
+    path: 'about.html',
+    url: `${BASE}/about.html`,
+    type: 'html',
+    language: 'html',
+    code: `<!DOCTYPE html>\n<html lang="en">\n  <body data-page="about"><h1>About</h1><a href="index.html">Home</a></body>\n</html>`,
+  },
+  {
+    path: 'css/site.css',
+    url: `${BASE}/css/site.css`,
+    type: 'other',
+    language: 'css',
+    code: `:root { --accent: #6ea8fe; }\nbody { font-family: system-ui, sans-serif; }`,
+  },
+  { path: 'assets/logo.svg', url: `${BASE}/assets/logo.svg`, type: 'image' },
+  { path: 'assets/report.pdf', url: `${BASE}/assets/report.pdf`, type: 'pdf' },
+];
+
+const meta = {
+  title: 'Components/Artifact',
+  component: Artifact,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'A framed, switchable **generated-artifact viewer** — the "canvas / artifacts" pattern. A sandboxed `<iframe>` with a functional nav toolbar (back · forward · reload · home + editable path field) and a **Preview | Code** toggle; the Code tab shows a `FileTree` + the active file source via `CodeBlock`.',
+        '**When to use:** to show an AI-generated artifact your backend hosts (page, doc, image, PDF) beside the conversation. The component frames; your backend serves — so relative links, back/forward and multi-format work natively.',
+        '**How to use:** set `src` to the hosted URL and `files` (`{ path, url?, code?, language?, type? }[]`) for the Code tree. The iframe `sandbox` defaults to `allow-scripts allow-forms` (not `allow-same-origin`). Handle `onNavigate(url)`, `onTabChange(tab)`, `onFileSelect(path)`.',
+        '**Placement:** the preview/canvas panel of a chat shell (e.g. `list | chat | artifact`). It **fills** its container — give the parent a height.',
+      ]),
+    },
+  },
+  argTypes: {
+    files: { control: false },
+    src: { control: 'text' },
+    tab: { control: 'select', options: ['preview', 'code'] },
+    sandbox: { control: 'text' },
+  },
+  args: { src: `${BASE}/index.html`, files: FILES, tab: 'preview' as ArtifactTab },
+  render: (args) => (
+    <div class="h-[520px] w-full max-w-[900px]">
+      <Artifact
+        src={args.src}
+        files={args.files}
+        tab={args.tab}
+        sandbox={args.sandbox}
+        iframeTitle="Starboard artifact preview"
+      />
+    </div>
+  ),
+} satisfies Meta<typeof Artifact>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Artifact } from '@kitnai/chat';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+export const Playground: Story = {
+  ...src(`<Artifact src={src} files={files} tab="preview" />`),
+};
+
+export const CodeTab: Story = {
+  name: 'Code tab',
+  args: { tab: 'code' as ArtifactTab },
+  render: (args: { src?: string; files: ArtifactFile[] }) => (
+    <div class="h-[520px] w-full max-w-[900px]">
+      <Artifact src={args.src} files={args.files} tab="code" activeFile="index.html" iframeTitle="Starboard artifact preview" />
+    </div>
+  ),
+  ...src(`<Artifact src={src} files={files} tab="code" activeFile="index.html" />`),
+};
+
+/** Controlled — observe the emitted nav model. */
+export const Controlled: Story = {
+  render: () => {
+    const [log, setLog] = createSignal<string[]>([]);
+    const push = (s: string) => setLog((l) => [s, ...l].slice(0, 6));
+    return (
+      <div class="flex flex-col gap-2">
+        <div class="h-[420px] w-full max-w-[900px]">
+          <Artifact
+            src={`${BASE}/index.html`}
+            files={FILES}
+            iframeTitle="Starboard artifact preview"
+            onNavigate={(url) => push(`navigate → ${url}`)}
+            onTabChange={(t) => push(`tabchange → ${t}`)}
+            onFileSelect={(p) => push(`fileselect → ${p}`)}
+          />
+        </div>
+        <pre class="m-0 min-h-24 max-w-[900px] rounded-lg bg-muted px-3 py-2.5 text-xs text-muted-foreground">
+          {log().length ? log().join('\n') : '(navigate the preview / switch tabs / pick a file…)'}
+        </pre>
+      </div>
+    );
+  },
+  ...src(`<Artifact src={src} files={files}
+  onNavigate={(url) => …} onTabChange={(t) => …} onFileSelect={(p) => …} />`),
+};
+
+/** PDFs render inline via pdf.js (loaded on demand from a CDN). */
+export const PdfPreview: Story = {
+  name: 'PDF (inline)',
+  render: () => (
+    <div class="h-[520px] w-full max-w-[900px]">
+      <Artifact src={`${BASE}/assets/report.pdf`} files={FILES} />
+    </div>
+  ),
+};
+
+/** Fallback card when inline rendering can't work (here the src 404s). */
+export const PdfFallback: Story = {
+  name: 'PDF (fallback card)',
+  render: () => (
+    <div class="h-[520px] w-full max-w-[900px]">
+      <Artifact src={`${BASE}/assets/does-not-exist.pdf`} />
+    </div>
+  ),
+};