@kitn.ai/ui 0.14.1

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

@@ -0,0 +1,33 @@
+/**
+ * Hand-authored "how you do this" code samples for the Examples / Patterns
+ * stories' **Usage** tab. Each Example is a granular SolidJS composition; the
+ * snippets teach how to do the same thing — the props you set and the events you
+ * handle — in each framework. They are representative, NOT a literal copy of the
+ * rendered demo.
+ *
+ * Keyed per **story** (variant): the Usage tab shows the entry for the story you
+ * clicked (eyebrow = example name, title = story name). An example-level
+ * `intro`/`snippets` is the fallback for any story without its own entry.
+ *
+ * Pure data (no imports) so it bundles cleanly into the Storybook manager addon.
+ */
+export type FrameworkKey = 'html' | 'react' | 'svelte' | 'vue' | 'angular' | 'solid';
+
+/** One story's (or the example's) intro + per-framework snippets. */
+export interface StoryUsage {
+  /** One-line "how you do this" framing (may use `inline code`). */
+  intro: string;
+  /** framework key → code snippet. Omit a framework to hide its tab. */
+  snippets: Partial<Record<FrameworkKey, string>>;
+}
+
+export interface ExampleUsage extends StoryUsage {
+  /** Storybook group title this attaches to, e.g. `'Examples/Message Actions'`. */
+  title: string;
+  /**
+   * Per-story overrides, keyed by the story's display **name**
+   * (e.g. `'Actions on Hover'`). A story without an entry falls back to the
+   * example-level `intro`/`snippets`.
+   */
+  stories?: Record<string, StoryUsage>;
+}

package/src/stories/full-chat.stories.tsx

@@ -0,0 +1,18 @@
+import type { Meta, StoryObj } from "storybook-solidjs-vite";
+import { ChatScene } from "./chat-scene";
+
+const meta: Meta = {
+  title: "Examples/Full Chat App",
+  parameters: {
+    // Render inline in docs so the embedded example inherits the dark-mode
+    // class (a non-inline iframe would stay light). Bounded to a sensible height.
+    docs: { story: { inline: true, height: "640px" } },
+  },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const Default: Story = {
+  render: () => <ChatScene />,
+};

package/src/stories/message-actions.stories.tsx

@@ -0,0 +1,230 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { createSignal } from 'solid-js';
+import {
+  Message, MessageAvatar, MessageContent, MessageActions,
+  FeedbackBar, Button,
+} from '../index';
+import { Tooltip } from '../ui/tooltip';
+import { Copy, ThumbsUp, ThumbsDown, RefreshCw, Share, Bookmark, Check } from 'lucide-solid';
+
+const meta: Meta = {
+  title: 'Examples/Message Actions',
+  parameters: { layout: 'padded' },
+};
+
+export default meta;
+type Story = StoryObj;
+
+export const HoverActions: Story = {
+  name: 'Actions on Hover',
+  render: () => (
+    <div class="space-y-6 max-w-2xl p-4">
+      <p class="text-sm text-muted-foreground">Hover over the assistant message to see action buttons appear.</p>
+
+      <Message>
+        <MessageAvatar src="" fallback="U" alt="User" />
+        <MessageContent>How do I handle errors in async Rust functions?</MessageContent>
+      </Message>
+
+      <Message>
+        <MessageAvatar src="" fallback="AI" alt="Assistant" />
+        <div class="group flex-1 space-y-2">
+          <MessageContent markdown>
+{`In Rust, async functions return \`Result\` types just like sync functions. The \`?\` operator works seamlessly:
+
+\`\`\`rust
+async fn fetch_user(id: u64) -> Result<User, AppError> {
+    let response = client.get(&format!("/users/{}", id))
+        .send()
+        .await?;          // propagates reqwest::Error
+    let user = response
+        .json::<User>()
+        .await?;           // propagates deserialization error
+    Ok(user)
+}
+\`\`\`
+
+Use \`anyhow::Result\` for applications and \`thiserror\` for libraries to define custom error types.`}
+          </MessageContent>
+          <MessageActions class="opacity-0 group-hover:opacity-100 transition-opacity">
+            <Button variant="ghost" size="icon-sm" aria-label="Copy message"><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 response"><RefreshCw class="size-3.5" /></Button>
+          </MessageActions>
+        </div>
+      </Message>
+    </div>
+  ),
+};
+
+export const AlwaysVisible: Story = {
+  name: 'Always Visible Actions',
+  render: () => (
+    <div class="space-y-6 max-w-2xl p-4">
+      <Message>
+        <MessageAvatar src="" fallback="AI" alt="Assistant" />
+        <div class="flex-1 space-y-2">
+          <MessageContent markdown>
+{`To install Tailwind CSS v4 in a Vite project:
+
+\`\`\`bash
+pnpm add tailwindcss @tailwindcss/vite
+\`\`\`
+
+Then add the plugin to your \`vite.config.ts\`:
+
+\`\`\`typescript
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+});
+\`\`\`
+
+Import Tailwind in your main CSS file:
+
+\`\`\`css
+@import "tailwindcss";
+\`\`\``}
+          </MessageContent>
+          <MessageActions>
+            <Button variant="ghost" size="icon-sm" aria-label="Copy message"><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 response"><RefreshCw class="size-3.5" /></Button>
+            <Button variant="ghost" size="icon-sm" aria-label="Share"><Share class="size-3.5" /></Button>
+            <Button variant="ghost" size="icon-sm" aria-label="Bookmark"><Bookmark class="size-3.5" /></Button>
+          </MessageActions>
+        </div>
+      </Message>
+    </div>
+  ),
+};
+
+export const WithCopyConfirmation: Story = {
+  name: 'Copy with Confirmation',
+  render: () => {
+    const [copied, setCopied] = createSignal(false);
+
+    const handleCopy = () => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    };
+
+    return (
+      <div class="space-y-6 max-w-2xl p-4">
+        <Message>
+          <MessageAvatar src="" fallback="AI" alt="Assistant" />
+          <div class="flex-1 space-y-2">
+            <MessageContent>
+              The current LTS version of Node.js is 22.x, which includes built-in support for the fetch API, test runner, and watch mode.
+            </MessageContent>
+            <MessageActions>
+              <Button variant="ghost" size="icon-sm" aria-label={copied() ? 'Copied' : 'Copy message'} onClick={handleCopy}>
+                {copied() ? <Check class="size-3.5 text-green-500" /> : <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>
+            </MessageActions>
+          </div>
+        </Message>
+      </div>
+    );
+  },
+};
+
+export const WithFeedbackBar: Story = {
+  name: 'Feedback Bar',
+  render: () => {
+    const [showFeedback, setShowFeedback] = createSignal(true);
+
+    return (
+      <div class="space-y-6 max-w-2xl p-4">
+        <Message>
+          <MessageAvatar src="" fallback="AI" alt="Assistant" />
+          <div class="flex-1 space-y-3">
+            <MessageContent markdown>
+{`Here are 3 ways to debounce in JavaScript:
+
+1. **setTimeout approach** -- simple but manual cleanup
+2. **lodash.debounce** -- battle-tested, configurable leading/trailing
+3. **AbortController** -- modern, cancellable, works with fetch`}
+            </MessageContent>
+
+            {showFeedback() && (
+              <FeedbackBar
+                title="Was this response helpful?"
+                collectDetail
+                categories={['Inaccurate', 'Not helpful', 'Unsafe', 'Other']}
+                onClose={() => setShowFeedback(false)}
+              />
+            )}
+          </div>
+        </Message>
+      </div>
+    );
+  },
+};
+
+export const FullExample: Story = {
+  name: 'Full Example',
+  render: () => {
+    const [copied, setCopied] = createSignal(false);
+    const [showFeedback, setShowFeedback] = createSignal(true);
+
+    const handleCopy = () => {
+      setCopied(true);
+      setTimeout(() => setCopied(false), 2000);
+    };
+
+    return (
+      <div class="space-y-6 max-w-2xl p-4">
+        <p class="text-sm text-muted-foreground">
+          Everything combined — avatar, markdown, built-in copy/regenerate plus custom
+          Share &amp; Bookmark (with copy→check confirmation), and a Feedback Bar below.
+        </p>
+
+        <Message>
+          <MessageAvatar src="" fallback="AI" alt="Assistant" />
+          <div class="flex-1 space-y-2">
+            <MessageContent markdown>
+{`Use \`anyhow::Result\` for application code and \`thiserror\` for libraries:
+
+\`\`\`rust
+async fn fetch_user(id: u64) -> anyhow::Result<User> {
+    let user = client.get(&format!("/users/{}", id)).send().await?.json().await?;
+    Ok(user)
+}
+\`\`\`
+
+The \`?\` operator propagates errors from any \`Result\`-returning call.`}
+            </MessageContent>
+            <MessageActions>
+              <Tooltip content={copied() ? 'Copied!' : 'Copy'}>
+                <Button variant="ghost" size="icon-sm" aria-label={copied() ? 'Copied' : 'Copy message'} onClick={handleCopy}>
+                  {copied() ? <Check class="size-3.5 text-green-500" /> : <Copy class="size-3.5" />}
+                </Button>
+              </Tooltip>
+              <Tooltip content="Regenerate">
+                <Button variant="ghost" size="icon-sm" aria-label="Regenerate response"><RefreshCw class="size-3.5" /></Button>
+              </Tooltip>
+              <Tooltip content="Share">
+                <Button variant="ghost" size="icon-sm" aria-label="Share"><Share class="size-3.5" /></Button>
+              </Tooltip>
+              <Tooltip content="Bookmark">
+                <Button variant="ghost" size="icon-sm" aria-label="Bookmark"><Bookmark class="size-3.5" /></Button>
+              </Tooltip>
+            </MessageActions>
+            {showFeedback() && (
+              <FeedbackBar
+                title="Was this response helpful?"
+                onClose={() => setShowFeedback(false)}
+              />
+            )}
+          </div>
+        </Message>
+      </div>
+    );
+  },
+};

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" aria-label="Copy message"><Copy class="size-3.5" /></Button>
+                      <Button variant="ghost" size="icon-sm" class="rounded-full" aria-label="Good response"><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()} aria-label="Send message">
+                    <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()} aria-label="Send message">
+                    <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" 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>
+            </div>
+          </div>
+        </div>
+      </ChatConfig>
+    );
+  },
+};