@kitn.ai/ui 0.14.1

package/llms.txt

@@ -0,0 +1,104 @@
+<!-- AUTO-GENERATED by scripts/gen-llms.mjs — do not edit by hand. Run `npm run build`. -->
+# @kitn.ai/ui
+
+> Framework-agnostic, Shadow-DOM web components for building AI chat interfaces — works in React, Vue, Angular, Svelte, or plain HTML. 44 `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 @kitn.ai/ui
+# 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('kai-chat');
+chat.messages = [{ id: '1', role: 'assistant', content: 'Hi!' }]; // ✅ property
+```
+```html
+<kai-chat messages="[...]"></kai-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 '@kitn.ai/ui/elements'`):
+Drop an element into any framework (React, Vue, plain HTML). Data in via JS properties; interactions out via non-bubbling CustomEvents.
+
+- `<kai-chat>` — full chat UI (message list + prompt input). The primary starting point.
+- `<kai-conversations>` — sidebar conversation browser with group support.
+- `<kai-prompt-input>` — standalone composer with send button.
+
+**Layer 2 — composable primitives** (`import { … } from '@kitn.ai/ui'`):
+All 44 elements are also exported individually. Use them for custom layouts or features `<kai-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('kai-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 `--kai-color-*` tokens on `:root`; they pierce Shadow DOM.
+
+## ChatMessage schema (required for `<kai-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/@kitn.ai/ui/elements"></script>
+<kai-chat style="display:block;height:100vh"></kai-chat>
+<script type="module">
+  const chat = document.querySelector('kai-chat');
+  chat.messages = [];
+</script>
+```
+
+**React** — typed wrappers auto-set properties and expose `on<Event>` props:
+```tsx
+import { Chat } from '@kitn.ai/ui/react';
+<Chat messages={messages} onSubmit={(e) => send(e.detail.value)} />
+```
+
+**Vue** — use the element directly; pass arrays via `.prop`:
+```vue
+<kai-chat :messages.prop="messages" @kai-submit="send" />
+```
+
+## Theming
+
+```css
+:root {
+  --kai-color-background: #0f0f0f;
+  --kai-color-primary: #7c3aed;
+  --kai-color-muted: #1e1e1e;
+}
+```
+
+For plain HTML/CDN: `<link rel="stylesheet" href="…/@kitn.ai/ui/theme.tokens.css">`.
+For Tailwind builds: `@import "@kitn.ai/ui/theme.css"` in your CSS.
+
+## Docs
+
+- Full element reference (all 44 elements, every prop/event): ./llms-full.txt — https://kitn.dev/llms-full.txt
+- Machine-readable Custom Elements Manifest: https://unpkg.com/@kitn.ai/ui/dist/custom-elements.json
+- Working examples: https://github.com/kitn-ai/ui/tree/main/examples
+- Storybook: https://storybook.kitn.dev
+- Repository: https://github.com/kitn-ai/ui

package/package.json

@@ -0,0 +1,141 @@
+{
+  "name": "@kitn.ai/ui",
+  "version": "0.14.1",
+  "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": [
+    "web-components",
+    "custom-elements",
+    "shadow-dom",
+    "ai",
+    "chat",
+    "chatbot",
+    "llm",
+    "chat-ui",
+    "streaming",
+    "markdown",
+    "framework-agnostic",
+    "react",
+    "vue",
+    "angular",
+    "svelte",
+    "solid-js"
+  ],
+  "license": "MIT",
+  "homepage": "https://ui.kitn.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kitn-ai/ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/kitn-ai/ui/issues"
+  },
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "unpkg": "./dist/kitn-chat.es.js",
+  "jsdelivr": "./dist/kitn-chat.es.js",
+  "customElements": "dist/custom-elements.json",
+  "exports": {
+    ".": "./src/index.ts",
+    "./elements": {
+      "types": "./src/elements/element-types.d.ts",
+      "default": "./dist/kitn-chat.es.js"
+    },
+    "./theme.css": "./theme.css",
+    "./theme.tokens.css": "./dist/theme.tokens.css",
+    "./react": "./frameworks/react/index.tsx",
+    "./provider": {
+      "types": "./dist/kitn-chat-provider.d.ts",
+      "default": "./dist/kitn-chat-provider.es.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "frameworks",
+    "theme.css",
+    "llms.txt",
+    "llms-full.txt"
+  ],
+  "scripts": {
+    "prepublishOnly": "npm run build",
+    "prebuild": "npm run build:css",
+    "build": "vite build --config vite.config.ts && vite build --config vite.config.provider.ts",
+    "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",
+    "dev": "npm run build:css && storybook dev -p 6006",
+    "storybook": "npm run build:css && storybook dev -p 6006",
+    "build-storybook": "npm run build:css && storybook build",
+    "build:css": "tailwindcss -i src/elements/styles.css -o src/elements/compiled.css --minify",
+    "build:css:watch": "tailwindcss -i src/elements/styles.css -o src/elements/compiled.css --watch",
+    "dev:provider": "vite examples/remote-provider --port 6007 --strictPort",
+    "dev:host": "vite examples/remote-host --port 6006 --strictPort",
+    "test:e2e": "playwright test"
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.7.6",
+    "@shikijs/langs": "^4.2.0",
+    "@shikijs/themes": "^4.2.0",
+    "class-variance-authority": "^0.7.0",
+    "clsx": "^2.1.0",
+    "lucide-solid": "^0.400.0",
+    "marked": "^18.0.0",
+    "shiki": "^4.0.2",
+    "solid-element": "^1.9.1",
+    "solid-js": "^1.9.0",
+    "tailwind-merge": "^2.5.0"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "@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",
+    "@tailwindcss/cli": "^4.3.0",
+    "@tailwindcss/postcss": "^4.2.2",
+    "@tailwindcss/typography": "^0.5.19",
+    "@testing-library/jest-dom": "^6.0.0",
+    "@testing-library/react": "^16.3.2",
+    "@types/react": "^19.2.17",
+    "@types/react-dom": "^19.2.3",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/browser-playwright": "4.1.2",
+    "@vitest/coverage-v8": "4.1.2",
+    "axe-core": "^4.12.1",
+    "concurrently": "^10.0.3",
+    "http-server": "^14.1.1",
+    "jsdom": "^24.0.0",
+    "playwright": "^1.59.1",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
+    "remark-gfm": "^4.0.1",
+    "storybook": "^10.3.5",
+    "storybook-dark-mode": "^5.0.0",
+    "storybook-solidjs-vite": "^10.0.12",
+    "tailwindcss": "^4.2.2",
+    "tw-animate-css": "^1.4.0",
+    "typescript": "^5.5.0",
+    "vite": "^6.0.0",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-solid": "^2.11.0",
+    "vitest": "^4.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18",
+    "solid-js": "^1.9.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  }
+}

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 = new URL('artifact-fixtures', document.baseURI).href;
+
+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: 'Solid (Advanced)/Elements/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 '@kitn.ai/ui';`;
+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(`kai-tab-change → ${t}`)}
+            onFileSelect={(p) => push(`kai-file-select → ${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>
+  ),
+};