@kitn.ai/ui 0.14.1

package/src/elements/chat-workspace.stories.tsx

@@ -0,0 +1,288 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount, createSignal } from 'solid-js';
+import './register'; // side effect: registers all kitn custom elements including <kai-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 {
+      'kai-workspace': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleGroups: ConversationGroup[] = [
+  { id: 'today', name: 'Today', sortOrder: 0, createdAt: '2026-06-13T00:00:00.000Z' },
+];
+
+const sampleConversations: ConversationSummary[] = [
+  {
+    id: '1',
+    title: 'Web component architecture',
+    groupId: 'today',
+    scope: { type: 'document' },
+    messageCount: 12,
+    lastMessageAt: '2026-06-13T15:30:00.000Z',
+    updatedAt: '2026-06-13T15:30:00.000Z',
+  },
+  {
+    id: '2',
+    title: 'Theming & tokens',
+    groupId: 'today',
+    scope: { type: 'document' },
+    messageCount: 5,
+    lastMessageAt: '2026-06-13T11:20:00.000Z',
+    updatedAt: '2026-06-13T11:20:00.000Z',
+  },
+];
+
+const sampleModels: ModelOption[] = [
+  { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+  { id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' },
+];
+
+const sampleMessages: ChatMessage[] = [
+  { id: 'm1', role: 'user', content: 'How do I drop the whole chat app in with one tag?' },
+  {
+    id: 'm2',
+    role: 'assistant',
+    content:
+      'Use `<kai-workspace>` — set `conversations`, `messages`, and `models` as properties and listen for `kai-conversation-select` + `kai-submit`.',
+    actions: ['copy', 'like'],
+  },
+];
+
+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;
+  defaultSidebarCollapsed?: boolean;
+  value?: string;
+};
+
+/** Live demo of the actual `<kai-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';
+      el.messages = sampleMessages;
+      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', 'defaultSidebarCollapsed', 'value',
+        ];
+        for (const name of scalarNames) {
+          if (name in args) (el as unknown as Record<string, unknown>)[name] = args[name];
+        }
+      }
+      el.addEventListener('kai-conversation-select', (e) => console.log('select', (e as CustomEvent).detail));
+      el.addEventListener('kai-submit', (e) => console.log('submit', (e as unknown as CustomEvent).detail));
+      el.addEventListener('kai-sidebar-toggle', (e) => console.log('kai-sidebar-toggle', (e as CustomEvent).detail));
+    }
+  });
+  return (
+    <div style={{ height: '720px', width: '100%' }}>
+      <kai-workspace
+        ref={(e) => (el = e as WorkspaceEl)}
+        style={{ display: 'block', height: '100%' }}
+      />
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-workspace id="workspace" style="display:block; height:100vh;"></kai-workspace>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const workspace = document.getElementById('workspace');
+  workspace.conversations = [
+    {
+      id: '1', title: 'Web component architecture',
+      scope: { type: 'document' }, messageCount: 12,
+      lastMessageAt: '2026-06-13T15:30:00Z', updatedAt: '2026-06-13T15:30:00Z',
+    },
+  ];
+  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 <kai-workspace> — set conversations, messages, and models as properties.' },
+  ];
+  workspace.models = [
+    { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+  ];
+
+  // events are CustomEvents on the element (they do not bubble)
+  workspace.addEventListener('kai-conversation-select', (e) => console.log('selected conversation:', e.detail.id));
+  workspace.addEventListener('kai-submit', (e) => console.log('user sent:', e.detail.value));
+  workspace.addEventListener('kai-sidebar-toggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
+</script>`;
+
+const SOLID_SNIPPET = `import '@kitn.ai/ui/elements'; // registers the custom elements
+import { onMount } from 'solid-js';
+import type { ConversationSummary, ModelOption } from '@kitn.ai/ui';
+import type { ChatMessage } from '@kitn.ai/ui/elements';
+
+function Workspace() {
+  let el: HTMLElement & {
+    conversations?: ConversationSummary[];
+    messages?: ChatMessage[];
+    models?: ModelOption[];
+    activeId?: string;
+  };
+  const conversations: ConversationSummary[] = [
+    {
+      id: '1', title: 'Web component architecture',
+      scope: { type: 'document' }, messageCount: 12,
+      lastMessageAt: '2026-06-13T15:30:00Z', updatedAt: '2026-06-13T15:30:00Z',
+    },
+  ];
+  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 <kai-workspace> — set conversations, messages, and models as properties.' },
+  ];
+  onMount(() => {
+    el.conversations = conversations;
+    el.messages = messages;
+    el.activeId = '1';
+    el.addEventListener('kai-conversation-select', (e) => console.log('selected:', e.detail.id));
+    el.addEventListener('kai-submit', (e) => console.log('user sent:', e.detail.value));
+    el.addEventListener('kai-sidebar-toggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
+  });
+  return (
+    <kai-workspace
+      ref={el}
+      style={{ display: 'block', height: '100vh' }}
+    />
+  );
+}`;
+
+const meta = {
+  title: 'Components/Workspace',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-workspace'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-workspace', [
+          '`<kai-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 \'@kitn.ai/ui/elements\'`, set rich data as JS **properties** (`el.conversations = [...]`, `el.messages = [...]`, `el.models = [...]`), and listen for **CustomEvents** (`kai-conversation-select`, `kai-submit`, `kai-sidebar-toggle`, `kai-new-chat`) directly on the element.',
+          '**Anatomy:** **sidebar panel** (a `<kai-conversations>` list with new-chat + collapse toggle, drag-resizable via an inner divider handle, collapses to a ghost reveal button) | **divider handle** (drag or click to resize; disappears when collapsed) | **chat panel** (the full `<ChatThread>`: header + message list + prompt composer; the thread node is stable across collapse/expand).',
+          '**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.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The element used the plain-HTML / any-framework way. */
+export const Default: Story = {
+  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>) => <WorkspaceElement args={args} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** The same element used inside a SolidJS component (properties via `ref` + `onMount`, events via `addEventListener`). */
+export const InSolidJS: Story = {
+  name: 'In SolidJS',
+  render: () => <WorkspaceElement />,
+  parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
+};
+
+const CONTROLLED_SNIPPET = `const ws = document.getElementById('workspace');
+let collapsed = false;
+ws.sidebarCollapsed = collapsed;            // app owns the state
+
+// react to the in-component toggle AND drive it from your own UI
+ws.addEventListener('kai-sidebar-toggle', (e) => {
+  collapsed = e.detail.collapsed;
+  ws.sidebarCollapsed = collapsed;          // persist / restore as you like
+});
+document.getElementById('toggle').onclick = () => {
+  collapsed = !collapsed;
+  ws.sidebarCollapsed = collapsed;          // collapse from outside the header
+};`;
+
+/**
+ * Controlled collapse: the app owns `sidebarCollapsed`, drives it as a property,
+ * and updates it from `kai-sidebar-toggle`. An external button collapses the
+ * sidebar from outside the workspace — only possible because the state is
+ * controlled (uncontrolled mode keeps collapse internal to the element).
+ */
+export const ControlledSidebar: Story = {
+  name: 'Controlled sidebar',
+  render: () => {
+    let el: WorkspaceEl | undefined;
+    const [collapsed, setCollapsed] = createSignal(false);
+    const drive = (next: boolean) => { setCollapsed(next); if (el) el.sidebarCollapsed = next; };
+    onMount(() => {
+      if (!el) return;
+      el.groups = sampleGroups;
+      el.conversations = sampleConversations;
+      el.activeId = '1';
+      el.messages = sampleMessages;
+      el.models = sampleModels;
+      el.currentModel = 'claude-4';
+      el.chatTitle = 'Web component architecture';
+      el.sidebarCollapsed = collapsed();
+      el.addEventListener('kai-sidebar-toggle', (e) => drive((e as CustomEvent<{ collapsed: boolean }>).detail.collapsed));
+    });
+    return (
+      <div style={{ height: '720px', width: '100%', display: 'flex', 'flex-direction': 'column', gap: '8px' }}>
+        <button type="button" onClick={() => drive(!collapsed())} style={{ 'align-self': 'flex-start', padding: '6px 12px', 'border-radius': '8px', border: '1px solid var(--color-border)', cursor: 'pointer' }}>
+          {collapsed() ? 'Expand' : 'Collapse'} sidebar (from the app)
+        </button>
+        <kai-workspace ref={(e) => (el = e as WorkspaceEl)} style={{ display: 'block', flex: '1', 'min-height': '0' }} />
+      </div>
+    );
+  },
+  parameters: { docs: { source: { code: CONTROLLED_SNIPPET, language: 'js' } } },
+};
+

package/src/elements/chat-workspace.tsx

@@ -0,0 +1,161 @@
+import { Show } from 'solid-js';
+import { defineWebComponent } from './define';
+import { createControllableSignal } from '../primitives/controllable';
+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 { ProseSize } from '../primitives/chat-config';
+import type { ModelOption, ConversationGroup, ConversationSummary } from '../types';
+
+interface Props extends Record<string, unknown> {
+  /** Pre-bucketed conversation groups for the sidebar. Set as a JS property. */
+  groups: ConversationGroup[];
+  /** Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property. */
+  conversations: ConversationSummary[];
+  /** Id of the open conversation, highlighted in the sidebar. */
+  activeId?: string;
+  /** The active conversation's message thread, newest last. Set as a JS property. */
+  messages: ChatMessage[];
+  value?: string;
+  placeholder?: string;
+  loading?: boolean;
+  suggestions?: string[];
+  suggestionMode?: 'submit' | 'fill';
+  proseSize?: ProseSize;
+  codeTheme?: string;
+  codeHighlight?: boolean;
+  chatTitle?: string;
+  models?: ModelOption[];
+  currentModel?: string;
+  context?: ChatThreadContextUsage;
+  scrollButton?: boolean;
+  search?: boolean;
+  voice?: boolean;
+  slashCommands?: SlashCommandItem[];
+  slashActiveIds?: string[];
+  slashCompact?: boolean;
+  /** Sidebar default width as a percent of the workspace (default 22). */
+  sidebarWidth?: number;
+  /** Sidebar min width in px (default 200). */
+  sidebarMinWidth?: number;
+  /** Sidebar max width in px (default 420). */
+  sidebarMaxWidth?: number;
+  /** Controlled collapsed state. Set this as a JS property (`el.sidebarCollapsed
+   *  = true`) to drive the sidebar from your app, updating it in response to the
+   *  `kai-sidebar-toggle` event. Omit for uncontrolled (the element manages it). */
+  sidebarCollapsed?: boolean;
+  /** Initial collapsed state when uncontrolled (default false). Use the
+   *  `default-sidebar-collapsed` attribute to start collapsed in plain HTML. */
+  defaultSidebarCollapsed?: boolean;
+}
+
+interface Events {
+  /** A conversation was selected in the sidebar. */
+  'kai-conversation-select': { id: string };
+  /** The "New chat" button was clicked. */
+  'kai-new-chat': Record<string, never>;
+  /** The sidebar was collapsed or expanded. */
+  'kai-sidebar-toggle': { collapsed: boolean };
+  /** User submitted a message. */
+  'kai-submit': { value: string; attachments: AttachmentData[] };
+  /** Fired on every input change. */
+  'kai-value-change': { value: string };
+  /** The header model switcher changed. */
+  'kai-model-change': { modelId: string };
+  /** An action button on a message was clicked. */
+  'kai-message-action': { messageId: string; action: string };
+  /** The Search button was clicked. */
+  'kai-search': Record<string, never>;
+  /** The Mic / voice button was clicked. */
+  'kai-voice': Record<string, never>;
+  /** A slash command was chosen from the palette. */
+  'kai-slash-select': { command: SlashCommandItem };
+  /** A suggestion chip was clicked (only in `suggestion-mode="fill"`). */
+  'kai-suggestion-click': { value: string };
+}
+
+defineWebComponent<Props, Events>('kai-workspace', {
+  groups: [], conversations: [], activeId: undefined, messages: [],
+  value: undefined, placeholder: 'Send a message...', loading: false,
+  suggestions: undefined, suggestionMode: 'submit', proseSize: 'sm',
+  codeTheme: 'github-dark-dimmed', codeHighlight: true, chatTitle: undefined,
+  models: undefined, currentModel: undefined, context: undefined, scrollButton: true,
+  search: false, voice: false, slashCommands: undefined, slashActiveIds: undefined, slashCompact: false,
+  sidebarWidth: 22, sidebarMinWidth: 200, sidebarMaxWidth: 420,
+  sidebarCollapsed: undefined, defaultSidebarCollapsed: undefined,
+}, (props, { dispatch, flag }) => {
+  // Controlled/uncontrolled collapse: `sidebarCollapsed` (when set) wins;
+  // otherwise the element manages its own state, seeded from
+  // `defaultSidebarCollapsed`. `toggle` always writes the internal value (a no-op
+  // visually while controlled) and emits `kai-sidebar-toggle` so a controlling app
+  // can update its own state.
+  const [collapsed, setCollapsed] = createControllableSignal(
+    () => props.sidebarCollapsed as boolean | undefined,
+    flag('defaultSidebarCollapsed'),
+  );
+  const toggle = () => { const next = !collapsed(); setCollapsed(next); dispatch('kai-sidebar-toggle', { collapsed: next }); };
+
+  // Create the thread ONCE and reference the same node in both <Show> branches.
+  // It's owned by this component root (not by a Show branch), so toggling the
+  // sidebar moves the node between branches without disposing it — the thread's
+  // own state (e.g. an uncontrolled draft) survives the collapse/expand.
+  const threadEl = (
+    <ChatThread
+      messages={props.messages} value={props.value as string | undefined} placeholder={props.placeholder as string}
+      loading={flag('loading')} suggestions={props.suggestions as string[] | undefined}
+      suggestionMode={props.suggestionMode as 'submit' | 'fill'} proseSize={props.proseSize as ProseSize}
+      codeTheme={props.codeTheme as string} codeHighlight={flag('codeHighlight')}
+      chatTitle={props.chatTitle as string | undefined} models={props.models as ModelOption[] | undefined}
+      currentModel={props.currentModel as string | undefined} context={props.context as ChatThreadContextUsage | undefined}
+      scrollButton={props.scrollButton !== false} search={flag('search')} voice={flag('voice')}
+      slashCommands={props.slashCommands as SlashCommandItem[] | undefined}
+      slashActiveIds={props.slashActiveIds as string[] | undefined} slashCompact={flag('slashCompact')}
+      onValueChange={(value) => dispatch('kai-value-change', { value })}
+      onSubmit={(detail) => dispatch('kai-submit', detail)}
+      onSuggestionClick={(value) => dispatch('kai-suggestion-click', { value })}
+      onModelChange={(modelId) => dispatch('kai-model-change', { modelId })}
+      onMessageAction={(detail) => dispatch('kai-message-action', detail)}
+      onSearch={() => dispatch('kai-search', {})}
+      onVoice={() => dispatch('kai-voice', {})}
+      onSlashSelect={(command) => dispatch('kai-slash-select', { command })}
+    />
+  );
+
+  return (
+    <div class="h-full w-full overflow-hidden bg-background">
+      <Show
+        when={!collapsed()}
+        fallback={
+          <div class="relative h-full">
+            <Button
+              variant="ghost" size="icon-sm" aria-label="Open sidebar"
+              class="absolute left-2 top-2 z-10 rounded-full bg-card/80 shadow-sm backdrop-blur"
+              onClick={toggle}
+            >
+              <PanelLeftOpen class="size-4" />
+            </Button>
+            {threadEl}
+          </div>
+        }
+      >
+        <ResizablePanelGroup orientation="horizontal">
+          <ResizablePanel defaultSize={props.sidebarWidth as number} data-min-size={String(props.sidebarMinWidth)} data-max-size={String(props.sidebarMaxWidth)}>
+            <ConversationList
+              groups={props.groups} conversations={props.conversations} activeId={props.activeId as string | undefined}
+              onSelect={(id) => dispatch('kai-conversation-select', { id })}
+              onNewChat={() => dispatch('kai-new-chat', {})}
+              onToggleSidebar={toggle}
+            />
+          </ResizablePanel>
+          <ResizableHandle withHandle />
+          <ResizablePanel>{threadEl}</ResizablePanel>
+        </ResizablePanelGroup>
+      </Show>
+    </div>
+  );
+});

package/src/elements/chat.stories.tsx

@@ -0,0 +1,151 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers <kai-chat>, <kai-conversations>, <kai-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 {
+      'kai-chat': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const sampleMessages: ChatMessage[] = [
+  { id: '1', role: 'user', content: 'How do I center a div?' },
+  {
+    id: '2',
+    role: 'assistant',
+    content:
+      'The modern way is a grid:\n\n```css\n.box {\n  display: grid;\n  place-items: center;\n}\n```\n\nThat centers the child on both axes.',
+    actions: ['copy', 'like', 'dislike'],
+  },
+];
+
+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 `<kai-chat>` custom element (Shadow DOM and all). */
+function ChatElement(props: { args?: Record<string, unknown> }) {
+  let el: ChatEl | undefined;
+  onMount(() => {
+    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 <kai-chat ref={(e) => (el = e as ChatEl)} style={{ display: 'block', height: '560px' }} />;
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-chat id="chat" style="display:block; height:100vh;"></kai-chat>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const chat = document.getElementById('chat');
+  chat.messages = [
+    { id: '1', role: 'user', content: 'How do I center a div?' },
+    { id: '2', role: 'assistant', content: 'Use \`display: grid; place-items: center;\`' },
+  ];
+
+  // events are CustomEvents on the element (they do not bubble)
+  chat.addEventListener('kai-submit', (e) => console.log('user sent:', e.detail.value));
+</script>`;
+
+const SOLID_SNIPPET = `import '@kitn.ai/ui/elements'; // registers the custom elements
+import { onMount } from 'solid-js';
+import type { ChatMessage } from '@kitn.ai/ui/elements';
+
+function Chat() {
+  let el: HTMLElement & { messages?: ChatMessage[] };
+  const messages: ChatMessage[] = [
+    { id: '1', role: 'user', content: 'How do I center a div?' },
+    { id: '2', role: 'assistant', content: 'Use \`display: grid; place-items: center;\`' },
+  ];
+  onMount(() => { el.messages = messages; });
+  return (
+    <kai-chat
+      ref={el}
+      style={{ display: 'block', height: '100vh' }}
+      on:kai-submit={(e) => console.log('user sent:', e.detail.value)}
+    />
+  );
+}`;
+
+const meta = {
+  title: 'Components/Chat',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-chat'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-chat', [
+          '`<kai-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 \'@kitn.ai/ui/elements\'`, set rich data as JS **properties** (`el.messages = [...]`), and listen for **CustomEvents** (`kai-submit`, `kai-message-action`, `kai-value-change`) directly on the element.',
+          '**Anatomy:** **header** (model switcher + context-meter, shown when `models`/`context` props are set) → **message list** (scrollable thread of `<Message>` rows, each rendered per `role`; a scroll-to-bottom button appears when scrolled up) → **prompt composer** (`<PromptInput>`: textarea + toolbar with suggestions, slash-command palette, voice/search buttons, and optional attachment area).',
+          '**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.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The element used the plain-HTML / any-framework way. */
+export const Default: Story = {
+  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' } } },
+};
+
+/** The same element used inside a SolidJS component (properties via `ref`, events via `on:`). */
+export const InSolidJS: Story = {
+  name: 'In SolidJS',
+  render: () => <ChatElement />,
+  parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
+};
+