@kitn.ai/ui 0.14.1

package/src/stories/examples/usage/empty-state.ts

@@ -0,0 +1,144 @@
+import type { ExampleUsage, StoryUsage } from './types';
+
+/** New Chat — a centered greeting (icon + title + description), starter suggestion chips, and a composer. */
+const newChat: StoryUsage = {
+  intro:
+    "The new-chat zero state. `<kai-empty>` renders the centered greeting from two scalar props — `emptyTitle` (DOM attribute `empty-title`, since `title` is a global HTML attribute) and `description`. The icon, the starter suggestion chips, and the composer below aren't part of `<kai-empty>` — compose those with the SolidJS `Empty` + `PromptSuggestion` + `PromptInput` primitives (see the Solid tab).",
+  snippets: {
+    html: `<!-- Register the elements once (CDN or bundler) -->
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
+</script>
+
+<!-- Scalars are plain attributes. Note the kebab-case empty-title. -->
+<kai-empty
+  empty-title="How can I help today?"
+  description="Ask anything, or start from one of these."
+></kai-empty>
+
+<!-- The icon, suggestion chips, and composer are not part of <kai-empty>;
+     compose them yourself (see the Solid tab). -->`,
+
+    react: `import { Empty } from '@kitn.ai/ui/react';
+
+export function NewChat() {
+  // Icon, suggestion chips, and composer aren't props on <Empty> —
+  // compose them yourself (see the Solid tab).
+  return (
+    <Empty
+      emptyTitle="How can I help today?"
+      description="Ask anything, or start from one of these."
+    />
+  );
+}`,
+
+    vue: `<script setup>
+import '@kitn.ai/ui/elements'; // register once (e.g. in main.ts)
+</script>
+
+<template>
+  <!-- Scalars as plain attributes; empty-title is kebab-case. -->
+  <kai-empty
+    empty-title="How can I help today?"
+    description="Ask anything, or start from one of these."
+  />
+  <!-- Icon, suggestions, and composer are composed separately. -->
+</template>`,
+
+    svelte: `<script>
+  import '@kitn.ai/ui/elements'; // register once
+</script>
+
+<!-- Scalars as attributes; empty-title is kebab-case. -->
+<kai-empty
+  empty-title="How can I help today?"
+  description="Ask anything, or start from one of these."
+></kai-empty>
+<!-- Icon, suggestions, and composer are composed separately. -->`,
+
+    angular: `// main.ts: import '@kitn.ai/ui/elements' before bootstrapApplication,
+// and add CUSTOM_ELEMENTS_SCHEMA to the component.
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-new-chat',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  // empty-title is kebab-case; both props are scalar strings.
+  template: \`
+    <kai-empty
+      empty-title="How can I help today?"
+      description="Ask anything, or start from one of these."
+    ></kai-empty>
+  \`,
+})
+export class NewChatComponent {}`,
+
+    solid: `import { createSignal } from 'solid-js';
+import {
+  ChatConfig, Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent,
+  PromptSuggestion, PromptInput, PromptInputTextarea, PromptInputActions, Button,
+} from '@kitn.ai/ui';
+import { Sparkles, Plus, Globe, ArrowUp } from 'lucide-solid';
+
+const SUGGESTIONS = [
+  'Summarize a document',
+  'Draft a product update',
+  'Explain a code snippet',
+  'Plan my week',
+];
+
+export function NewChat() {
+  const [input, setInput] = createSignal('');
+  return (
+    <ChatConfig proseSize="base">
+      <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>
+
+      {/* Composer fills from a clicked suggestion. */}
+      <PromptInput value={input()} onValueChange={setInput} onSubmit={() => setInput('')}>
+        <PromptInputTextarea placeholder="Ask anything…" />
+        <PromptInputActions class="flex items-center justify-between gap-2">
+          <div class="flex items-center gap-2">
+            <Button variant="outline" size="icon-sm" class="rounded-full" aria-label="Add"><Plus class="size-4" /></Button>
+            <Button variant="outline" size="sm" class="rounded-full gap-1" aria-label="Search the web"><Globe class="size-4" />Search</Button>
+          </div>
+          <Button size="icon-sm" class="rounded-full" disabled={!input().trim()} aria-label="Send message">
+            <ArrowUp class="size-4" />
+          </Button>
+        </PromptInputActions>
+      </PromptInput>
+    </ChatConfig>
+  );
+}`,
+  },
+};
+
+/**
+ * Pattern: Empty State — the new-chat zero state. `<kai-empty>` covers the
+ * centered greeting (`emptyTitle` + `description`); the icon, starter
+ * suggestion chips, and composer are SolidJS primitive composition. Per-story:
+ * the Usage tab shows the snippet for the story you're on; the example-level
+ * fields below are the fallback.
+ */
+const emptyState: ExampleUsage = {
+  title: 'Patterns/Empty State',
+  ...newChat, // example-level fallback = the primary "New Chat" story
+  stories: {
+    'New Chat': newChat,
+  },
+};
+
+export default emptyState;

package/src/stories/examples/usage/full-chat-app.ts

@@ -0,0 +1,277 @@
+import type { ExampleUsage, StoryUsage } from './types';
+
+// A small thread reused across the snippets — user + assistant, with actions,
+// reasoning, and a tool call on the second assistant message.
+const MESSAGES = `[
+    { id: 'u1', role: 'user', content: 'Can you explain how SolidJS reactivity differs from React hooks?' },
+    {
+      id: 'a1',
+      role: 'assistant',
+      content: 'SolidJS uses fine-grained signals: components run once and only the DOM nodes that read a signal update.',
+      actions: ['copy', 'like', 'dislike', 'regenerate'],
+    },
+    { id: 'u2', role: 'user', content: 'Can you benchmark SolidJS vs React for 10,000 items?' },
+    {
+      id: 'a2',
+      role: 'assistant',
+      content: 'Here are the benchmark results — SolidJS renders ~7x faster and updates ~42x faster.',
+      actions: ['copy', 'like', 'dislike', 'regenerate'],
+      reasoning: { label: 'Thought for 4 seconds', text: 'Render the same 10,000 items in both frameworks for a fair comparison.' },
+      tools: [
+        {
+          type: 'run_benchmark',
+          state: 'output-available',
+          input: { framework: ['solid', 'react'], itemCount: 10000 },
+          output: { solid: { avgRenderMs: 12.4 }, react: { avgRenderMs: 89.2 } },
+          toolCallId: 'call_abc123',
+        },
+      ],
+    },
+  ]`;
+
+const MODELS = `[
+    { id: 'claude-4', name: 'Claude 4 Opus', provider: 'Anthropic' },
+    { id: 'gpt-4o', name: 'GPT-4o', provider: 'OpenAI' },
+  ]`;
+
+const CONTEXT = `{ usedTokens: 12400, maxTokens: 200000, inputTokens: 8200, outputTokens: 4200, estimatedCost: 0.042 }`;
+
+const SUGGESTIONS = `['How does SolidJS handle context?', 'Show me a store example']`;
+
+/**
+ * Default — the entire chat experience in one element. `<kai-chat>` renders the
+ * message thread (markdown, reasoning, tool calls, per-message action bars), a
+ * header with the `models` switcher + `context` token meter, the `suggestions`
+ * chips, and the prompt input. The demo's resizable sidebar + conversation list
+ * are separate chrome that lives *outside* the element.
+ */
+const fullChat: StoryUsage = {
+  intro:
+    'Drop in the whole chat experience with one element. `<kai-chat>` renders the thread (markdown, reasoning, tool calls, action bars), an optional header model switcher + `context` token meter, `suggestions` chips, and the prompt input — set `messages` as a property and handle `submit` / `messageaction` / `modelchange`. The resizable conversation sidebar in the demo is separate chrome `<kai-chat>` does not include. (The live demo composes the SolidJS `ChatContainer`, `Message`, `PromptInput`, and `ConversationList` primitives directly.)',
+  snippets: {
+    html: `<!-- Register the elements once (CDN or bundler) -->
+<script type="module">
+  import 'https://cdn.jsdelivr.net/npm/@kitn.ai/ui/dist/kitn-chat.es.js';
+</script>
+
+<kai-chat
+  id="chat"
+  chat-title="SolidJS reactivity vs React hooks"
+  current-model="claude-4"
+  prose-size="base"
+  placeholder="Ask anything..."
+></kai-chat>
+
+<script type="module">
+  const chat = document.getElementById('chat');
+
+  // Object/array props are set as PROPERTIES, not attributes.
+  chat.messages = ${MESSAGES};
+  chat.models = ${MODELS};
+  chat.context = ${CONTEXT};
+  chat.suggestions = ${SUGGESTIONS};
+
+  chat.addEventListener('kai-submit', (e) => {
+    const { value, attachments } = e.detail; // append the user message / call your backend
+    console.log('send', value, attachments);
+  });
+  chat.addEventListener('kai-message-action', (e) => {
+    const { messageId, action } = e.detail; // 'copy' | 'like' | 'dislike' | 'regenerate' | 'edit'
+    console.log(messageId, action);
+  });
+  chat.addEventListener('kai-model-change', (e) => console.log(e.detail.modelId));
+</script>`,
+
+    react: `import { Chat } from '@kitn.ai/ui/react';
+
+export function ChatApp() {
+  return (
+    <Chat
+      chatTitle="SolidJS reactivity vs React hooks"
+      proseSize="base"
+      placeholder="Ask anything..."
+      currentModel="claude-4"
+      models={${MODELS}}
+      context={${CONTEXT}}
+      suggestions={${SUGGESTIONS}}
+      messages={${MESSAGES}}
+      onSubmit={(e) => console.log('send', e.detail.value, e.detail.attachments)}
+      onMessageAction={(e) => console.log(e.detail.messageId, e.detail.action)}
+      onModelChange={(e) => console.log(e.detail.modelId)}
+    />
+  );
+}`,
+
+    vue: `<script setup>
+import '@kitn.ai/ui/elements'; // register once (e.g. in main.ts)
+
+// Object/array props use the .prop modifier in the template.
+const messages = ${MESSAGES};
+const models = ${MODELS};
+const context = ${CONTEXT};
+const suggestions = ${SUGGESTIONS};
+
+function onSubmit(e) { console.log('send', e.detail.value, e.detail.attachments); }
+function onAction(e) { console.log(e.detail.messageId, e.detail.action); }
+</script>
+
+<template>
+  <kai-chat
+    chat-title="SolidJS reactivity vs React hooks"
+    prose-size="base"
+    placeholder="Ask anything..."
+    current-model="claude-4"
+    :messages.prop="messages"
+    :models.prop="models"
+    :context.prop="context"
+    :suggestions.prop="suggestions"
+    @kai-submit="onSubmit"
+    @kai-message-action="onAction"
+    @kai-model-change="(e) => console.log(e.detail.modelId)"
+  />
+</template>`,
+
+    svelte: `<script>
+  import '@kitn.ai/ui/elements';
+
+  let el;
+  // Object/array props are set as properties via bind:this.
+  const messages = ${MESSAGES};
+  const models = ${MODELS};
+  const context = ${CONTEXT};
+  const suggestions = ${SUGGESTIONS};
+  $: if (el) {
+    el.messages = messages;
+    el.models = models;
+    el.context = context;
+    el.suggestions = suggestions;
+  }
+
+  function onSubmit(e) { console.log('send', e.detail.value, e.detail.attachments); }
+  function onAction(e) { console.log(e.detail.messageId, e.detail.action); }
+</script>
+
+<kai-chat
+  bind:this={el}
+  chat-title="SolidJS reactivity vs React hooks"
+  prose-size="base"
+  placeholder="Ask anything..."
+  current-model="claude-4"
+  on:kai-submit={onSubmit}
+  on:kai-message-action={onAction}
+  on:kai-model-change={(e) => console.log(e.detail.modelId)}
+/>`,
+
+    angular: `// main.ts: import '@kitn.ai/ui/elements' before bootstrapApplication,
+// and add CUSTOM_ELEMENTS_SCHEMA to the component.
+import { Component, CUSTOM_ELEMENTS_SCHEMA } from '@angular/core';
+
+@Component({
+  selector: 'app-chat',
+  standalone: true,
+  schemas: [CUSTOM_ELEMENTS_SCHEMA],
+  template: \`
+    <kai-chat
+      chat-title="SolidJS reactivity vs React hooks"
+      prose-size="base"
+      placeholder="Ask anything..."
+      current-model="claude-4"
+      [messages]="messages"
+      [models]="models"
+      [context]="context"
+      [suggestions]="suggestions"
+      (kai-submit)="onSubmit($event)"
+      (kai-message-action)="onAction($event)"
+      (kai-model-change)="onModel($event)"
+    ></kai-chat>
+  \`,
+})
+export class ChatComponent {
+  messages = ${MESSAGES};
+  models = ${MODELS};
+  context = ${CONTEXT};
+  suggestions = ${SUGGESTIONS};
+  onSubmit(e: CustomEvent<{ value: string; attachments: unknown[] }>) {
+    console.log('send', e.detail.value, e.detail.attachments);
+  }
+  onAction(e: CustomEvent<{ messageId: string; action: string }>) {
+    console.log(e.detail.messageId, e.detail.action);
+  }
+  onModel(e: CustomEvent<{ modelId: string }>) { console.log(e.detail.modelId); }
+}`,
+
+    solid: `import { createSignal, For } from 'solid-js';
+import {
+  ChatContainer, ChatContainerContent, ChatContainerScrollAnchor,
+  Message, MessageContent, MessageActions,
+  PromptInput, PromptInputTextarea, PromptInputActions,
+  ConversationList, ModelSwitcher, PromptSuggestion, ScrollButton, Button,
+} from '@kitn.ai/ui';
+import { Copy, ThumbsUp, ThumbsDown, RefreshCw, ArrowUp } from 'lucide-solid';
+
+export function ChatApp() {
+  const [value, setValue] = createSignal('');
+  const [modelId, setModelId] = createSignal('claude-4');
+
+  return (
+    <div class="flex h-screen w-full bg-background">
+      {/* Sidebar — separate chrome from the thread */}
+      <ConversationList groups={groups} conversations={conversations} activeId="1" onSelect={() => {}} onNewChat={() => {}} />
+
+      <main class="flex flex-1 flex-col overflow-hidden">
+        <header class="flex h-14 items-center justify-between border-b border-border px-5">
+          <div class="text-sm font-semibold">SolidJS reactivity vs React hooks</div>
+          <ModelSwitcher models={models} currentModelId={modelId()} onModelChange={setModelId} />
+        </header>
+
+        <ChatContainer class="flex-1">
+          <ChatContainerContent class="px-5 pt-4">
+            <Message class="group items-start">
+              <MessageContent markdown class="prose">{assistantReply}</MessageContent>
+              <MessageActions class="opacity-0 group-hover:opacity-100 transition-opacity">
+                <Button variant="ghost" size="icon-sm" aria-label="Copy"><Copy class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Good response"><ThumbsUp class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Bad response"><ThumbsDown class="size-3.5" /></Button>
+                <Button variant="ghost" size="icon-sm" aria-label="Regenerate"><RefreshCw class="size-3.5" /></Button>
+              </MessageActions>
+            </Message>
+            <ChatContainerScrollAnchor />
+          </ChatContainerContent>
+          <ScrollButton />
+        </ChatContainer>
+
+        <div class="px-5 pb-5">
+          <div class="flex gap-2 pb-3">
+            <For each={['How does SolidJS handle context?', 'Show me a store example']}>
+              {(s) => <PromptSuggestion onClick={() => setValue(s)}>{s}</PromptSuggestion>}
+            </For>
+          </div>
+          <PromptInput value={value()} onValueChange={setValue} onSubmit={() => setValue('')}>
+            <PromptInputTextarea placeholder="Ask anything..." />
+            <PromptInputActions class="justify-end">
+              <Button size="icon-sm" disabled={!value().trim()} aria-label="Send message"><ArrowUp class="size-4" /></Button>
+            </PromptInputActions>
+          </PromptInput>
+        </div>
+      </main>
+    </div>
+  );
+}`,
+  },
+};
+
+/**
+ * Example: Full Chat App — the complete experience. As an embedder you reach for
+ * the single `<kai-chat>` element; the live demo composes the granular SolidJS
+ * primitives for full control. Per-story: the Usage tab shows the snippet for the
+ * story you're on; the example-level fields below are the fallback.
+ */
+const fullChatApp: ExampleUsage = {
+  title: 'Examples/Full Chat App',
+  ...fullChat, // example-level fallback = the "Default" story
+  stories: {
+    Default: fullChat,
+  },
+};
+
+export default fullChatApp;

package/src/stories/examples/usage/index.ts

@@ -0,0 +1,63 @@
+import type { ExampleUsage } from './types';
+import messageActions from './message-actions';
+import streamingResponse from './streaming-response';
+import conversationWithReasoning from './conversation-with-reasoning';
+import conversationWithSources from './conversation-with-sources';
+import promptInputVariants from './prompt-input-variants';
+import contextUsage from './context-usage';
+import checkpointRestore from './checkpoint-restore';
+import fullChatApp from './full-chat-app';
+import emptyState from './empty-state';
+import centeredConversation from './pattern-centered-conversation';
+import chatPanelLayout from './pattern-chat-panel-layout';
+import dockedWidget from './pattern-docked-widget';
+
+export type { ExampleUsage, FrameworkKey } from './types';
+
+/**
+ * Every Example/Pattern that has hand-authored "how to build this" code.
+ * Add a module here and it lights up its Code tab automatically.
+ *
+ * Element-centric examples first, then the 4 layout Patterns — each pattern
+ * module carries a `title` that exactly matches its Storybook group title so
+ * the Usage tab appears automatically via `exampleUsageStoryIdPrefixes`.
+ */
+export const exampleUsageList: ExampleUsage[] = [
+  messageActions,
+  streamingResponse,
+  conversationWithReasoning,
+  conversationWithSources,
+  promptInputVariants,
+  contextUsage,
+  checkpointRestore,
+  fullChatApp,
+  // Patterns — layout recipes showing how to compose the building blocks
+  emptyState,
+  centeredConversation,
+  chatPanelLayout,
+  dockedWidget,
+];
+
+/** Lookup by Storybook group title, e.g. `'Examples/Message Actions'`. */
+export const exampleUsageByTitle = new Map(exampleUsageList.map((u) => [u.title, u]));
+
+/**
+ * Storybook's `sanitize` (from `@storybook/csf`), inlined so the manager addon
+ * has no extra dependency. Turns a title into its story-id stem, e.g.
+ * `'Examples/Message Actions'` → `'examples-message-actions'`.
+ */
+const sanitize = (s: string): string =>
+  s
+    .toLowerCase()
+    .replace(/[ ’–—―′¿'`~!@#$%^&*()_|+\-=?;:'",.<>{}[\]\\/]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-+/, '')
+    .replace(/-+$/, '');
+
+/**
+ * Story-id prefixes (`<stem>--`) for entries that have a Code tab. `manager.ts`
+ * uses these to show the tab only where we've authored code.
+ */
+export const exampleUsageStoryIdPrefixes: string[] = exampleUsageList.map(
+  (u) => `${sanitize(u.title)}--`,
+);