@kitnai/chat 0.4.0 → 0.6.0

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

@@ -0,0 +1,195 @@
+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 type { ConversationGroup, ConversationSummary, ModelOption } from '../types';
+import type { ChatMessage } from './chat-types';
+
+// 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>;
+    }
+  }
+}
+
+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 `<kitn-chat-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;
+  onMount(() => {
+    if (el) {
+      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.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));
+    }
+  });
+  return (
+    <div style={{ height: '720px', width: '100%' }}>
+      <kitn-chat-workspace
+        ref={(e) => (el = e as HTMLElement)}
+        style={{ display: 'block', height: '100%' }}
+      />
+    </div>
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-chat-workspace id="workspace" style="display:block; height:100vh;"></kitn-chat-workspace>
+
+<script type="module">
+  import '@kitnai/chat/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 <kitn-chat-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('conversationselect', (e) => console.log('selected conversation:', e.detail.id));
+  workspace.addEventListener('submit', (e) => console.log('user sent:', e.detail.value));
+  workspace.addEventListener('sidebartoggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
+</script>`;
+
+const SOLID_SNIPPET = `import '@kitnai/chat/elements'; // registers the custom elements
+import { onMount } from 'solid-js';
+import type { ConversationSummary, ModelOption } from '@kitnai/chat';
+import type { ChatMessage } from '@kitnai/chat/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 <kitn-chat-workspace> — set conversations, messages, and models as properties.' },
+  ];
+  onMount(() => {
+    el.conversations = conversations;
+    el.messages = messages;
+    el.activeId = '1';
+    el.addEventListener('conversationselect', (e) => console.log('selected:', e.detail.id));
+    el.addEventListener('submit', (e) => console.log('user sent:', e.detail.value));
+    el.addEventListener('sidebartoggle', (e) => console.log('sidebar collapsed:', e.detail.collapsed));
+  });
+  return (
+    <kitn-chat-workspace
+      ref={el}
+      style={{ display: 'block', height: '100vh' }}
+    />
+  );
+}`;
+
+const meta = {
+  title: 'Web Components/kitn-chat-workspace',
+  tags: ['autodocs'],
+  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.',
+          '**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;
+
+export default meta;
+type Story = StoryObj;
+
+/** The element used the plain-HTML / any-framework way. */
+export const Default: Story = {
+  render: () => <WorkspaceElement />,
+  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' } } },
+};

package/src/elements/register.ts

@@ -3,6 +3,7 @@
 import './conversation-list';
 import './prompt-input';
 import './chat';
+import './chat-workspace';
 // Composable leaf elements (spike — see docs/handoff + examples/composable)
 import './thinking-bar';
 import './model-switcher';

package/src/elements/styles.css

@@ -9,4 +9,39 @@
 @layer base {
   :host { display: block; }
   * { border-color: var(--color-border); }
+
+  /* One token-driven focus ring for EVERY focusable element in the shadow root.
+     Blue by default (via --color-ring), consistent in light + dark, and
+     overridable through --kitn-color-ring. Uses `outline` (not a box-shadow
+     ring) so it never clips on overflow and follows the element's radius;
+     `:focus-visible` so it only appears for keyboard navigation, never on a
+     mouse click. Components that render their own ring set
+     `focus-visible:outline-none` (a utility in a later cascade layer) and win
+     over this — so there's no double ring, just a guaranteed blue fallback for
+     the many controls that have no explicit focus style. */
+  :focus-visible {
+    outline: 2px solid var(--color-ring);
+    outline-offset: 2px;
+  }
+
+  /* Consistent cross-platform scrollbars for EVERY scroll region inside the
+     shadow root (message list, conversation list, menus, hover cards, code
+     blocks, the prompt textarea …). Thin + rounded + subtle, themed via tokens
+     for light/dark, thumb stronger on hover. Track stays transparent and
+     overflow is untouched, so no scrollbar is forced where none is needed.
+     Scoped to the shadow root, so it never restyles the host page. */
+  * {
+    scrollbar-width: thin;
+    scrollbar-color: var(--color-scrollbar-thumb) transparent;
+  }
+  *::-webkit-scrollbar { width: 8px; height: 8px; }
+  *::-webkit-scrollbar-track { background: transparent; }
+  *::-webkit-scrollbar-thumb {
+    background-color: var(--color-scrollbar-thumb);
+    border-radius: 9999px;
+    border: 2px solid transparent;
+    background-clip: padding-box;
+  }
+  *::-webkit-scrollbar-thumb:hover { background-color: var(--color-scrollbar-thumb-hover); }
+  *::-webkit-scrollbar-corner { background: transparent; }
 }

package/src/primitives/chat-config.tsx

@@ -7,7 +7,7 @@ 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>;

package/src/stories/docs/Installation.mdx

@@ -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.
 
+### 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.

package/src/stories/docs/Integrations.mdx

@@ -30,6 +30,8 @@ Scalar values (strings, numbers, booleans) work as attributes: `placeholder`, `l
 
 Import the element bundle once as a side-effect (it registers all `kitn-*` custom elements), then set properties and listen for events in a `<script type="module">` block.
 
+> **Want the whole shell in one tag?** `<kitn-chat-workspace>` bundles the conversation-list sidebar, the drag-to-resize handle, and the full chat thread together. Set `conversations`, `messages`, and optionally `models` as properties; listen for `conversationselect` and `submit`. See the <a href="?path=/docs/web-components-kitn-chat-workspace--docs">kitn-chat-workspace story</a> and the <a href="https://github.com/kitn-ai/kitn-chat/blob/main/docs/web-components.md#kitn-chat-workspace--kitnchatworkspace">web-components.md reference</a> for the full API.
+
 ```html
 <!DOCTYPE html>
 <html>

package/src/stories/docs/Introduction.mdx

@@ -5,7 +5,7 @@ import * as ChatPanel from '../chat-panel-layout.stories';
 
 # @kitnai/chat
 
-**A SolidJS + Shadow-DOM web component kit for building AI chat interfaces.**
+**Framework-agnostic, Shadow-DOM web components for building AI chat interfaces.**
 
 Message threads, prompt inputs, streaming responses, markdown + code rendering, reasoning & tool-call panels, attachments, and a conversation sidebar — composable building blocks you can drop into any app.
 
@@ -13,12 +13,21 @@ Message threads, prompt inputs, streaming responses, markdown + code rendering,
 
 ## Why @kitnai/chat
 
-- **Two ways to use it** — import the SolidJS components for full compositional control, or drop in framework-agnostic **web components** (`<kitn-chat>`) that work in React, Vue, Svelte, or plain HTML.
+- **Works in any framework** — drop in the framework-agnostic **web components** (`<kitn-chat>`) and they just work in React, Vue, Angular, Svelte, or plain HTML. Authored in SolidJS, so SolidJS apps can also import the components natively for full compositional control.
 - **Zero style conflicts** — the web components render in **Shadow DOM**, so the host page's CSS can't leak in and the kit's Tailwind can't leak out.
 - **Lightweight** — a markdown-only `<kitn-chat>` is **~61 KB gzip**, a single file. Syntax highlighting loads **on demand, per language, with no WASM** — and never loads at all if you don't render code.
-- **~50 composable components** across three layers: headless primitives → UI primitives (built on [Kobalte](https://kobalte.dev)) → AI feature components.
+- **~50 composable components** across three layers: headless primitives → accessible UI primitives (built in-house, WCAG 2.1 AA — no third-party UI dependency) → AI feature components.
 - **Themeable** — restyle everything by overriding a handful of `--color-*` design tokens.
 
+## Browsing the sidebar — which group do I copy from?
+
+The kit ships at two layers, and the sidebar reflects that. **Use the right one for your stack:**
+
+- **Web Components** — the framework-agnostic `<kitn-*>` custom elements. **This is what to copy into a React, Vue, Angular, Svelte, or plain-HTML app.** Data goes on JS properties, interactions come back as events.
+- **Components · SolidJS** and **UI · SolidJS** — the **native SolidJS** components (feature components) and primitives (Button, Dropdown, HoverCard, …) that the web components are *built from*. Their snippets are SolidJS JSX, so **only copy these into a SolidJS app**.
+
+In other words: the `<kitn-chat>` web component is a thin facade over the SolidJS `ChatContainer`/`Message`/… components — same UI, different consumption model. When in doubt, reach for **Web Components**.
+
 ## Where to next
 
 - **[Installation](?path=/docs/docs-installation--docs)** — add it to your project

package/src/stories/pattern-centered-conversation.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import {
+  ChatConfig, ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  ModelSwitcher, Button,
+} from '../index';
+import type { ModelOption } from '../types';
+import { Copy, ThumbsUp, ArrowUp } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Patterns/Centered Conversation',
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A single, centered reading column with no sidebar (Claude.ai-style). The messages and composer share one `max-w` measure centered in the viewport — ideal for a focused, full-window chat. Contrast with **Chat Panel Layout** (a compact embedded panel) and the **Full Chat App** example (a resizable workspace).',
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+const models: ModelOption[] = [
+  { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+  { id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' },
+];
+
+const answer = `Sure — here's the gist:
+
+- **Signals** are fine-grained, so only the DOM that reads a signal updates.
+- **No re-renders** — components run once; reactive expressions do the work.
+- **No dependency arrays** — effects auto-track what they read.
+
+Want a code example next?`;
+
+export const Focused: Story = {
+  render: () => {
+    const [input, setInput] = createSignal('');
+    const [model, setModel] = createSignal('claude-4');
+    return (
+      <ChatConfig proseSize="base">
+        <div style={{ width: '860px', height: '680px' }} class="flex flex-col overflow-hidden rounded-xl border border-border bg-background">
+          <header class="flex h-14 shrink-0 items-center justify-between border-b border-border px-5">
+            <span class="text-sm font-semibold text-foreground">New conversation</span>
+            <ModelSwitcher models={models} currentModelId={model()} onModelChange={setModel} />
+          </header>
+
+          <div class="relative flex-1 overflow-y-auto">
+            <ChatContainer class="h-full">
+              <ChatContainerContent class="space-y-6 px-5 py-6">
+                <Message class="mx-auto flex w-full max-w-2xl flex-col items-end">
+                  <MessageContent class="bg-muted text-primary max-w-[85%] rounded-3xl px-5 py-2.5">
+                    In one paragraph, why is SolidJS reactivity fast?
+                  </MessageContent>
+                </Message>
+
+                <Message class="mx-auto flex w-full max-w-2xl flex-col items-start">
+                  <div class="group flex w-full flex-col">
+                    <MessageContent markdown class="bg-transparent p-0 text-foreground">
+                      {answer}
+                    </MessageContent>
+                    <MessageActions class="-ml-2.5 flex gap-0 opacity-0 transition-opacity duration-150 group-hover:opacity-100">
+                      <Button variant="ghost" size="icon-sm" class="rounded-full"><Copy class="size-3.5" /></Button>
+                      <Button variant="ghost" size="icon-sm" class="rounded-full"><ThumbsUp class="size-3.5" /></Button>
+                    </MessageActions>
+                  </div>
+                </Message>
+                <ChatContainerScrollAnchor />
+              </ChatContainerContent>
+            </ChatContainer>
+          </div>
+
+          <div class="shrink-0 px-5 pb-5">
+            <div class="mx-auto max-w-2xl">
+              <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
+                <PromptInputTextarea placeholder="Reply…" class="min-h-[44px] pt-3 pl-4" />
+                <PromptInputActions class="mt-2 flex w-full items-center justify-end gap-2 px-3 pb-3">
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                    <ArrowUp class="size-4" />
+                  </Button>
+                </PromptInputActions>
+              </PromptInput>
+            </div>
+          </div>
+        </div>
+      </ChatConfig>
+    );
+  },
+};

package/src/stories/pattern-docked-widget.stories.tsx

@@ -0,0 +1,93 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import {
+  ChatConfig, ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageAvatar, MessageContent,
+  PromptInput, PromptInputTextarea, PromptInputActions, Button,
+} from '../index';
+import { ArrowUp, X } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Patterns/Docked Widget',
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'A support-assistant widget docked to the bottom-right corner of a host page. The same building blocks (`ChatContainer` + `Message` + `PromptInput`) shrink into a compact floating card — the kit\'s Shadow-DOM isolation means it can sit over any app without CSS bleed.',
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+export const SupportAssistant: Story = {
+  render: () => {
+    const [input, setInput] = createSignal('');
+    return (
+      <ChatConfig proseSize="sm">
+        {/* Faux host page */}
+        <div style={{ width: '920px', height: '680px' }} class="relative overflow-hidden rounded-xl border border-border bg-gradient-to-br from-muted/40 to-background">
+          <div class="space-y-3 p-8">
+            <div class="h-7 w-48 rounded-md bg-muted" />
+            <div class="h-4 w-2/3 rounded bg-muted/70" />
+            <div class="h-4 w-1/2 rounded bg-muted/70" />
+            <div class="mt-6 grid grid-cols-3 gap-4">
+              <div class="h-28 rounded-lg bg-muted/60" />
+              <div class="h-28 rounded-lg bg-muted/60" />
+              <div class="h-28 rounded-lg bg-muted/60" />
+            </div>
+          </div>
+
+          {/* Docked chat widget */}
+          <div style={{ width: '360px', height: '460px' }} class="absolute bottom-5 right-5 flex flex-col overflow-hidden rounded-2xl border border-border bg-card shadow-xl">
+            <header class="flex shrink-0 items-center justify-between border-b border-border px-4 py-3">
+              <div class="flex items-center gap-2">
+                <span class="size-2 rounded-full bg-tool-green" />
+                <span class="text-sm font-semibold text-foreground">Support</span>
+              </div>
+              <Button variant="ghost" size="icon-sm" aria-label="Close"><X class="size-4" /></Button>
+            </header>
+
+            <div class="relative flex-1 overflow-y-auto">
+              <ChatContainer class="h-full">
+                <ChatContainerContent class="space-y-3 px-3 py-3">
+                  <Message>
+                    <MessageAvatar src="" alt="AI" fallback="AI" />
+                    <MessageContent markdown class="bg-transparent p-0 pt-1">
+                      Hi! 👋 How can I help you today?
+                    </MessageContent>
+                  </Message>
+                  <Message class="flex-col items-end">
+                    <MessageContent class="bg-muted text-primary max-w-[85%] rounded-xl px-3.5 py-2">
+                      How do I reset my password?
+                    </MessageContent>
+                  </Message>
+                  <Message>
+                    <MessageAvatar src="" alt="AI" fallback="AI" />
+                    <MessageContent markdown class="bg-transparent p-0 pt-1">
+                      Head to **Settings → Security** and click **Reset password** — you'll get an email link.
+                    </MessageContent>
+                  </Message>
+                  <ChatContainerScrollAnchor />
+                </ChatContainerContent>
+              </ChatContainer>
+            </div>
+
+            <div class="shrink-0 px-3 pb-3">
+              <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
+                <PromptInputTextarea placeholder="Message support…" class="min-h-[40px] pt-2.5 pl-3.5" />
+                <PromptInputActions class="mt-1.5 flex w-full items-center justify-end gap-2 px-2.5 pb-2.5">
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                    <ArrowUp class="size-4" />
+                  </Button>
+                </PromptInputActions>
+              </PromptInput>
+            </div>
+          </div>
+        </div>
+      </ChatConfig>
+    );
+  },
+};

package/src/stories/pattern-empty-state.stories.tsx

@@ -0,0 +1,76 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import {
+  ChatConfig, Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent,
+  PromptSuggestion, PromptInput, PromptInputTextarea, PromptInputActions, Button,
+} from '../index';
+import { Sparkles, Plus, Globe, ArrowUp } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Patterns/Empty State',
+  parameters: {
+    layout: 'centered',
+    docs: {
+      description: {
+        component:
+          'The new-chat zero state: a centered greeting with starter suggestions above the composer. Composed from `Empty` (+ `EmptyMedia`/`EmptyTitle`/`EmptyDescription`), `PromptSuggestion` chips, and `PromptInput`. Clicking a suggestion fills the composer.',
+      },
+    },
+  },
+};
+export default meta;
+type Story = StoryObj;
+
+const SUGGESTIONS = [
+  'Summarize a document',
+  'Draft a product update',
+  'Explain a code snippet',
+  'Plan my week',
+];
+
+export const NewChat: Story = {
+  render: () => {
+    const [input, setInput] = createSignal('');
+    return (
+      <ChatConfig proseSize="base">
+        <div style={{ width: '760px', height: '640px' }} class="flex flex-col overflow-hidden rounded-xl border border-border bg-background">
+          <Empty class="flex-1">
+            <EmptyHeader>
+              <EmptyMedia variant="icon">
+                <Sparkles class="size-6" />
+              </EmptyMedia>
+              <EmptyTitle>How can I help today?</EmptyTitle>
+              <EmptyDescription>
+                Ask anything, or start from one of these.
+              </EmptyDescription>
+            </EmptyHeader>
+            <EmptyContent>
+              <div class="flex max-w-md flex-wrap justify-center gap-2">
+                {SUGGESTIONS.map((s) => (
+                  <PromptSuggestion onClick={() => setInput(s)}>{s}</PromptSuggestion>
+                ))}
+              </div>
+            </EmptyContent>
+          </Empty>
+
+          <div class="shrink-0 px-4 pb-4">
+            <div class="mx-auto max-w-2xl">
+              <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
+                <PromptInputTextarea placeholder="Ask anything…" class="min-h-[44px] pt-3 pl-4" />
+                <PromptInputActions class="mt-2 flex w-full items-center justify-between gap-2 px-3 pb-3">
+                  <div class="flex items-center gap-2">
+                    <Button variant="outline" size="icon-sm" class="rounded-full"><Plus class="size-4" /></Button>
+                    <Button variant="outline" size="sm" class="rounded-full gap-1"><Globe class="size-4" />Search</Button>
+                  </div>
+                  <Button size="icon-sm" class="rounded-full" disabled={!input().trim()}>
+                    <ArrowUp class="size-4" />
+                  </Button>
+                </PromptInputActions>
+              </PromptInput>
+            </div>
+          </div>
+        </div>
+      </ChatConfig>
+    );
+  },
+};