@kitnai/chat 0.6.0 → 0.8.0

package/src/elements/{kitn-chain-of-thought.stories.tsx → chain-of-thought.stories.tsx}

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 interface Step {
   label: string;
@@ -12,7 +13,7 @@ declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
+      'kc-chain-of-thought': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -23,19 +24,19 @@ const steps: Step[] = [
   { label: 'Build & verify' },
 ];
 
-/** Render `<kitn-chain-of-thought>` with the `steps` set as a JS property. */
+/** Render `<kc-chain-of-thought>` with the `steps` set as a JS property. */
 function CotElement(props: { steps: Step[] }) {
   let el: (HTMLElement & { steps?: Step[] }) | undefined;
   onMount(() => {
     if (el) el.steps = props.steps;
   });
   return (
-    <kitn-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
+    <kc-chain-of-thought ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '24px', 'max-width': '560px' }} />
   );
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chain-of-thought id="cot"></kitn-chain-of-thought>
+<kc-chain-of-thought id="cot"></kc-chain-of-thought>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -48,19 +49,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-chain-of-thought',
+  title: 'Web Components/kc-chain-of-thought',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-chain-of-thought'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
-          '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
-          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `steps` **property** — an array of `{ label, content? }`. Steps with `content` become expandable.",
-          'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+      description: specDescription('kc-chain-of-thought', [
+        '`<kc-chain-of-thought>` is the framework-agnostic **web component** for step-by-step reasoning — a connected list of steps, each with optional collapsible detail — isolated in **Shadow DOM**. The compound primitive collapses to a single `steps` data model (Route 1).',
+        '**When to use:** surfacing an agent\'s plan or reasoning trace in a non-Solid app. In SolidJS, compose the `ChainOfThought` primitives for finer control.',
+        "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `steps` **property** — an array of `{ label, content? }`. Steps with `content` become expandable.",
+        'See the **Code** tab for HTML usage.',
+      ]),
     },
   },
 } satisfies Meta;

package/src/elements/chain-of-thought.tsx

@@ -1,5 +1,5 @@
 import { For, Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import {
   ChainOfThought,
   ChainOfThoughtStep,
@@ -22,10 +22,10 @@ interface Props extends Record<string, unknown> {
 }
 
 /**
- * `<kitn-chain-of-thought>` — step-by-step reasoning with connectors and
+ * `<kc-chain-of-thought>` — step-by-step reasoning with connectors and
  * per-step collapsible detail. Data via the `steps` property.
  */
-defineKitnElement<Props>('kitn-chain-of-thought', {
+defineWebComponent<Props>('kc-chain-of-thought', {
   steps: [],
 }, (props) => (
   <ChainOfThought>

package/src/elements/{kitn-chat-scope-picker.stories.tsx → chat-scope-picker.stories.tsx}

@@ -1,20 +1,21 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
 import './register'; // side effect: registers the custom elements
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chat-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
+      'kc-scope-picker': JSX.HTMLAttributes<HTMLElement> & {
         'current-label'?: string;
       };
     }
   }
 }
 
-/** Render `<kitn-chat-scope-picker>` with author/tag options set as properties. */
+/** Render `<kc-scope-picker>` with author/tag options set as properties. */
 function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
   let el: (HTMLElement & { availableAuthors?: string[]; availableTags?: string[] }) | undefined;
   onMount(() => {
@@ -27,12 +28,12 @@ function ScopePickerElement(props: { authors: string[]; tags: string[] }) {
     });
   });
   return (
-    <kitn-chat-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
+    <kc-scope-picker ref={(e) => (el = e as HTMLElement)} style={{ display: 'inline-block', padding: '40px' }} />
   );
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chat-scope-picker id="scope"></kitn-chat-scope-picker>
+<kc-scope-picker id="scope"></kc-scope-picker>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -45,19 +46,18 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
 </script>`;
 
 const meta = {
-  title: 'Web Components/kitn-chat-scope-picker',
+  title: 'Web Components/kc-scope-picker',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-scope-picker'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chat-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
+      description: specDescription('kc-scope-picker', [
+          '`<kc-scope-picker>` is the framework-agnostic **web component** for scoping a chat by author or tag — a dropdown that emits the chosen filters — isolated in **Shadow DOM**.',
           '**When to use:** letting users narrow a conversation/search to a subset of content. In SolidJS, use the `ChatScopePicker` primitive.',
           "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `availableAuthors` / `availableTags` **properties** (and optionally `current-label`), and listen for the `scopechange` **CustomEvent** (`undefined` filters = \"All Content\").",
           'See the **Code** tab for HTML usage.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;

package/src/elements/chat-scope-picker.tsx

@@ -1,4 +1,4 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatScopePicker } from '../components/chat-scope-picker';
 import type { SearchFilters } from '../types';
 
@@ -11,18 +11,18 @@ interface Props extends Record<string, unknown> {
   currentLabel?: string;
 }
 
-/** Events fired by `<kitn-chat-scope-picker>`. */
+/** Events fired by `<kc-scope-picker>`. */
 interface Events {
   /** A scope was chosen (`undefined` filters = "All Content"). */
   scopechange: { filters: SearchFilters | undefined };
 }
 
 /**
- * `<kitn-chat-scope-picker>` — a dropdown to scope a chat by author or tag.
+ * `<kc-scope-picker>` — a dropdown to scope a chat by author or tag.
  * Options via `available-authors`/`available-tags` properties; emits
  * `scopechange`.
  */
-defineKitnElement<Props, Events>('kitn-chat-scope-picker', {
+defineWebComponent<Props, Events>('kc-scope-picker', {
   availableAuthors: [],
   availableTags: [],
   currentLabel: 'All Content',

package/src/elements/{kitn-chat-workspace.stories.tsx → chat-workspace.stories.tsx}

@@ -1,15 +1,16 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
-import './register'; // side effect: registers all kitn custom elements including <kitn-chat-workspace>
+import './register'; // side effect: registers all kitn custom elements including <kc-workspace>
 import type { ConversationGroup, ConversationSummary, ModelOption } from '../types';
 import type { ChatMessage } from './chat-types';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chat-workspace': JSX.HTMLAttributes<HTMLElement>;
+      'kc-workspace': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -50,26 +51,42 @@ const sampleMessages: ChatMessage[] = [
     id: 'm2',
     role: 'assistant',
     content:
-      'Use `<kitn-chat-workspace>` — set `conversations`, `messages`, and `models` as properties and listen for `conversationselect` + `submit`.',
+      'Use `<kc-workspace>` — set `conversations`, `messages`, and `models` as properties and listen for `conversationselect` + `submit`.',
     actions: ['copy', 'like'],
   },
 ];
 
-/** Live demo of the actual `<kitn-chat-workspace>` custom element (Shadow DOM and all). */
-function WorkspaceElement() {
-  let el:
-    | (HTMLElement & {
-        groups?: ConversationGroup[];
-        conversations?: ConversationSummary[];
-        activeId?: string;
-        messages?: ChatMessage[];
-        models?: ModelOption[];
-        currentModel?: string;
-        chatTitle?: string;
-      })
-    | undefined;
+type WorkspaceEl = HTMLElement & {
+  groups?: ConversationGroup[];
+  conversations?: ConversationSummary[];
+  activeId?: string;
+  messages?: ChatMessage[];
+  models?: ModelOption[];
+  currentModel?: string;
+  chatTitle?: string;
+  placeholder?: string;
+  loading?: boolean;
+  suggestionMode?: string;
+  proseSize?: string;
+  codeTheme?: string;
+  codeHighlight?: boolean;
+  scrollButton?: boolean;
+  search?: boolean;
+  voice?: boolean;
+  slashCompact?: boolean;
+  sidebarWidth?: number;
+  sidebarMinWidth?: number;
+  sidebarMaxWidth?: number;
+  sidebarCollapsed?: boolean;
+  value?: string;
+};
+
+/** Live demo of the actual `<kc-workspace>` custom element (Shadow DOM and all). */
+function WorkspaceElement(props: { args?: Record<string, unknown> }) {
+  let el: WorkspaceEl | undefined;
   onMount(() => {
     if (el) {
+      // Fixed array/object data
       el.groups = sampleGroups;
       el.conversations = sampleConversations;
       el.activeId = '1';
@@ -77,6 +94,18 @@ function WorkspaceElement() {
       el.models = sampleModels;
       el.currentModel = 'claude-4';
       el.chatTitle = 'Web component architecture';
+      // Scalar args from Controls (override defaults above for scalar props)
+      const args = props.args;
+      if (args) {
+        const scalarNames = [
+          'placeholder', 'loading', 'suggestionMode', 'proseSize', 'codeTheme',
+          'codeHighlight', 'scrollButton', 'search', 'voice', 'slashCompact',
+          'sidebarWidth', 'sidebarMinWidth', 'sidebarMaxWidth', 'sidebarCollapsed', 'value',
+        ];
+        for (const name of scalarNames) {
+          if (name in args) (el as unknown as Record<string, unknown>)[name] = args[name];
+        }
+      }
       el.addEventListener('conversationselect', (e) => console.log('select', (e as CustomEvent).detail));
       el.addEventListener('submit', (e) => console.log('submit', (e as unknown as CustomEvent).detail));
       el.addEventListener('sidebartoggle', (e) => console.log('sidebartoggle', (e as CustomEvent).detail));
@@ -84,8 +113,8 @@ function WorkspaceElement() {
   });
   return (
     <div style={{ height: '720px', width: '100%' }}>
-      <kitn-chat-workspace
-        ref={(e) => (el = e as HTMLElement)}
+      <kc-workspace
+        ref={(e) => (el = e as WorkspaceEl)}
         style={{ display: 'block', height: '100%' }}
       />
     </div>
@@ -93,7 +122,7 @@ function WorkspaceElement() {
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chat-workspace id="workspace" style="display:block; height:100vh;"></kitn-chat-workspace>
+<kc-workspace id="workspace" style="display:block; height:100vh;"></kc-workspace>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -108,7 +137,7 @@ const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
   ];
   workspace.messages = [
     { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
-    { id: 'm2', role: 'assistant', content: 'Use <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+    { id: 'm2', role: 'assistant', content: 'Use <kc-workspace> — set conversations, messages, and models as properties.' },
   ];
   workspace.models = [
     { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
@@ -141,7 +170,7 @@ function Workspace() {
   ];
   const messages: ChatMessage[] = [
     { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
-    { id: 'm2', role: 'assistant', content: 'Use <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+    { id: 'm2', role: 'assistant', content: 'Use <kc-workspace> — set conversations, messages, and models as properties.' },
   ];
   onMount(() => {
     el.conversations = conversations;
@@ -152,7 +181,7 @@ function Workspace() {
     el.addEventListener('sidebartoggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
   });
   return (
-    <kitn-chat-workspace
+    <kc-workspace
       ref={el}
       style={{ display: 'block', height: '100vh' }}
     />
@@ -160,20 +189,19 @@ function Workspace() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-chat-workspace',
+  title: 'Web Components/kc-workspace',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-workspace'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chat-workspace>` is the full chat shell as a single **web component** — a resizable split layout with a collapsible conversation list on the left and a full message thread on the right, all isolated in **Shadow DOM**. SolidJS is bundled in, so the host needs nothing.',
+      description: specDescription('kc-workspace', [
+          '`<kc-workspace>` is the full chat shell as a single **web component** — a resizable split layout with a collapsible conversation list on the left and a full message thread on the right, all isolated in **Shadow DOM**. SolidJS is bundled in, so the host needs nothing.',
           '**When to use:** dropping an entire chat application shell into a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts and a ready-made list+chat layout. If you *are* in SolidJS and want fine-grained control, compose the `ConversationList` and `ChatThread` primitives directly.',
           '**How to use:** register once with `import \'@kitnai/chat/elements\'`, set rich data as JS **properties** (`el.conversations = [...]`, `el.messages = [...]`, `el.models = [...]`), and listen for **CustomEvents** (`conversationselect`, `submit`, `sidebartoggle`, `newchat`) directly on the element.',
           '**Placement:** as a full-page surface or large panel. Give it an explicit height (e.g. `height: 100vh`). The sidebar is drag-resizable and can be collapsed via the toggle button in its header.',
           'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -183,7 +211,20 @@ type Story = StoryObj;
 
 /** The element used the plain-HTML / any-framework way. */
 export const Default: Story = {
-  render: () => <WorkspaceElement />,
+  args: {
+    placeholder: 'Send a message...',
+    loading: false,
+    suggestionMode: 'submit',
+    proseSize: 'sm',
+    codeTheme: 'github-dark-dimmed',
+    codeHighlight: true,
+    scrollButton: true,
+    search: false,
+    voice: false,
+    slashCompact: false,
+    sidebarCollapsed: false,
+  },
+  render: (args: Record<string, unknown>) => <WorkspaceElement args={args} />,
   parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
 };
 
@@ -193,3 +234,4 @@ export const InSolidJS: Story = {
   render: () => <WorkspaceElement />,
   parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
 };
+

package/src/elements/chat-workspace.tsx

@@ -1,12 +1,13 @@
 import { createSignal, Show } from 'solid-js';
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatThread, type ChatThreadContextUsage } from '../components/chat-thread';
 import { ConversationList } from '../components/conversation-list';
 import { ResizablePanelGroup, ResizablePanel, ResizableHandle } from '../ui/resizable';
 import { Button } from '../ui/button';
 import { PanelLeftOpen } from 'lucide-solid';
+import type { AttachmentData } from '../components/attachments';
 import type { SlashCommandItem } from '../components/slash-command';
-import type { ChatMessage } from './chat-types';
+import type { ChatMessage, ChatMessageAction } from './chat-types';
 import type { ProseSize } from '../primitives/chat-config';
 import type { ModelOption, ConversationGroup, ConversationSummary } from '../types';
 
@@ -47,7 +48,32 @@ interface Props extends Record<string, unknown> {
   sidebarCollapsed?: boolean;
 }
 
-defineKitnElement<Props>('kitn-chat-workspace', {
+interface Events {
+  /** A conversation was selected in the sidebar. */
+  conversationselect: { id: string };
+  /** The "New chat" button was clicked. */
+  newchat: Record<string, never>;
+  /** The sidebar was collapsed or expanded. */
+  sidebartoggle: { collapsed: boolean };
+  /** User submitted a message. */
+  submit: { value: string; attachments: AttachmentData[] };
+  /** Fired on every input change. */
+  valuechange: { value: string };
+  /** The header model switcher changed. */
+  modelchange: { modelId: string };
+  /** An action button on a message was clicked. */
+  messageaction: { messageId: string; action: ChatMessageAction };
+  /** The Search button was clicked. */
+  search: Record<string, never>;
+  /** The Mic / voice button was clicked. */
+  voice: Record<string, never>;
+  /** A slash command was chosen from the palette. */
+  slashselect: { command: SlashCommandItem };
+  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
+  suggestionclick: { value: string };
+}
+
+defineWebComponent<Props, Events>('kc-workspace', {
   groups: [], conversations: [], activeId: undefined, messages: [],
   value: undefined, placeholder: 'Send a message...', loading: false,
   suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',

package/src/elements/{kitn-chat.stories.tsx → chat.stories.tsx}

@@ -1,14 +1,15 @@
 import type { Meta, StoryObj } from 'storybook-solidjs-vite';
 import { onMount } from 'solid-js';
-import './register'; // side effect: registers <kitn-chat>, <kitn-conversation-list>, <kitn-prompt-input>
+import './register'; // side effect: registers <kc-chat>, <kc-conversations>, <kc-prompt-input>
 import type { ChatMessage } from './chat-types';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
 
 // The web components are custom DOM elements, so declare the tags for JSX.
 declare module 'solid-js' {
   // eslint-disable-next-line @typescript-eslint/no-namespace
   namespace JSX {
     interface IntrinsicElements {
-      'kitn-chat': JSX.HTMLAttributes<HTMLElement>;
+      'kc-chat': JSX.HTMLAttributes<HTMLElement>;
     }
   }
 }
@@ -24,17 +25,49 @@ const sampleMessages: ChatMessage[] = [
   },
 ];
 
-/** Live demo of the actual `<kitn-chat>` custom element (Shadow DOM and all). */
-function ChatElement() {
-  let el: (HTMLElement & { messages?: ChatMessage[] }) | undefined;
+type ChatEl = HTMLElement & {
+  messages?: ChatMessage[];
+  value?: string;
+  placeholder?: string;
+  loading?: boolean;
+  suggestionMode?: string;
+  proseSize?: string;
+  codeTheme?: string;
+  codeHighlight?: boolean;
+  chatTitle?: string;
+  currentModel?: string;
+  scrollButton?: boolean;
+  search?: boolean;
+  voice?: boolean;
+  slashCompact?: boolean;
+};
+
+/** Live demo of the actual `<kc-chat>` custom element (Shadow DOM and all). */
+function ChatElement(props: { args?: Record<string, unknown> }) {
+  let el: ChatEl | undefined;
   onMount(() => {
-    if (el) el.messages = sampleMessages;
+    if (el) {
+      // Fixed array data
+      el.messages = sampleMessages;
+      // Scalar args from Controls
+      const args = props.args;
+      if (args) {
+        const scalarNames = [
+          'value', 'placeholder', 'loading', 'suggestionMode', 'proseSize',
+          'codeTheme', 'codeHighlight', 'chatTitle', 'currentModel',
+          'scrollButton', 'search', 'voice', 'slashCompact',
+        ];
+        for (const name of scalarNames) {
+          if (name in args) (el as unknown as Record<string, unknown>)[name] = args[name];
+        }
+      }
+    }
   });
-  return <kitn-chat ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', height: '560px' }} />;
+  return <kc-chat ref={(e) => (el = e as ChatEl)} style={{ display: 'block', height: '560px' }} />;
 }
 
 const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
-<kitn-chat id="chat" style="display:block; height:100vh;"></kitn-chat>
+<kc-chat id="chat" style="display:block; height:100vh;"></kc-chat>
 
 <script type="module">
   import '@kitnai/chat/elements';   // registers the custom elements
@@ -61,7 +94,7 @@ function Chat() {
   ];
   onMount(() => { el.messages = messages; });
   return (
-    <kitn-chat
+    <kc-chat
       ref={el}
       style={{ display: 'block', height: '100vh' }}
       on:submit={(e) => console.log('user sent:', e.detail.value)}
@@ -70,20 +103,19 @@ function Chat() {
 }`;
 
 const meta = {
-  title: 'Web Components/kitn-chat',
+  title: 'Web Components/kc-chat',
   tags: ['autodocs'],
+  argTypes: argTypesFor('kc-chat'),
   parameters: {
     layout: 'fullscreen',
     docs: {
-      description: {
-        component: [
-          '`<kitn-chat>` is the framework-agnostic **web component** version of the chat UI — a complete message thread plus prompt input, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
+      description: specDescription('kc-chat', [
+          '`<kc-chat>` is the framework-agnostic **web component** version of the chat UI — a complete message thread plus prompt input, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
           '**When to use:** dropping a full chat into a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts. If you *are* in SolidJS and want fine-grained control, compose the primitives (`ChatContainer`, `Message`, `PromptInput`) instead.',
           '**How to use:** register once with `import \'@kitnai/chat/elements\'`, set rich data as JS **properties** (`el.messages = [...]`), and listen for **CustomEvents** (`submit`, `messageaction`, `valuechange`) directly on the element.',
           '**Placement:** as a top-level panel or full-page surface. Give it an explicit height (e.g. `height: 100vh`).',
           'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
-        ].join('\n\n'),
-      },
+        ]),
     },
   },
 } satisfies Meta;
@@ -93,7 +125,19 @@ type Story = StoryObj;
 
 /** The element used the plain-HTML / any-framework way. */
 export const Default: Story = {
-  render: () => <ChatElement />,
+  args: {
+    placeholder: 'Send a message...',
+    loading: false,
+    suggestionMode: 'submit',
+    proseSize: 'sm',
+    codeTheme: 'github-dark-dimmed',
+    codeHighlight: true,
+    scrollButton: true,
+    search: false,
+    voice: false,
+    slashCompact: false,
+  },
+  render: (args: Record<string, unknown>) => <ChatElement args={args} />,
   parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
 };
 
@@ -103,3 +147,4 @@ export const InSolidJS: Story = {
   render: () => <ChatElement />,
   parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
 };
+

package/src/elements/chat.tsx

@@ -1,14 +1,35 @@
-import { defineKitnElement } from './define';
+import { defineWebComponent } from './define';
 import { ChatThread, type ChatThreadProps, type ChatThreadContextUsage } from '../components/chat-thread';
+import type { AttachmentData } from '../components/attachments';
 import type { SlashCommandItem } from '../components/slash-command';
 import type { ProseSize } from '../primitives/chat-config';
+import type { ChatMessageAction } from './chat-types';
 import type { ModelOption } from '../types';
 
 type Props = Omit<ChatThreadProps,
   'class' | 'onValueChange' | 'onSubmit' | 'onSuggestionClick' | 'onModelChange'
   | 'onMessageAction' | 'onSearch' | 'onVoice' | 'onSlashSelect'> & Record<string, unknown>;
 
-defineKitnElement<Props>('kitn-chat', {
+interface Events {
+  /** User submitted a message. */
+  submit: { value: string; attachments: AttachmentData[] };
+  /** Fired on every input change. */
+  valuechange: { value: string };
+  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
+  suggestionclick: { value: string };
+  /** An action button on a message was clicked. */
+  messageaction: { messageId: string; action: ChatMessageAction };
+  /** The header model switcher changed. */
+  modelchange: { modelId: string };
+  /** A slash command was chosen from the palette. */
+  slashselect: { command: SlashCommandItem };
+  /** The Search button was clicked. */
+  search: Record<string, never>;
+  /** The Mic / voice button was clicked. */
+  voice: Record<string, never>;
+}
+
+defineWebComponent<Props, Events>('kc-chat', {
   messages: [], value: undefined, placeholder: 'Send a message...', loading: false,
   suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',
   codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,