@kitn.ai/ui 0.14.1

package/src/components/chat-thread.test.tsx

@@ -0,0 +1,58 @@
+import { describe, it, expect, afterEach } from 'vitest';
+import '@testing-library/jest-dom/vitest';
+import { render, cleanup } from '@solidjs/testing-library';
+import { ChatThread } from './chat-thread';
+
+// jsdom doesn't implement Element.scrollTo; the auto-scroll container calls it.
+if (!Element.prototype.scrollTo) (Element.prototype as unknown as { scrollTo: () => void }).scrollTo = () => {};
+
+afterEach(cleanup);
+
+describe('ChatThread header composition', () => {
+  it('hides the header with no title, models, context, or header slot', () => {
+    const { container } = render(() => <ChatThread messages={[]} />);
+    expect(container.querySelector('header')).toBeNull();
+  });
+
+  it('shows the header when only header-start content is present', () => {
+    const { container } = render(() => <ChatThread messages={[]} headerStart />);
+    expect(container.querySelector('header')).toBeTruthy();
+  });
+
+  it('renders header-start and header-end slots inside the header', () => {
+    const { container } = render(() => <ChatThread messages={[]} headerStart headerEnd />);
+    expect(container.querySelector('header slot[name="header-start"]')).toBeTruthy();
+    expect(container.querySelector('header slot[name="header-end"]')).toBeTruthy();
+  });
+
+  it('still shows the header for a chat title (back-compat)', () => {
+    const { container, getByText } = render(() => <ChatThread messages={[]} chatTitle="Assistant" />);
+    expect(container.querySelector('header')).toBeTruthy();
+    expect(getByText('Assistant')).toBeInTheDocument();
+  });
+});
+
+describe('ChatThread suggestions gating', () => {
+  const SUGGESTIONS = ['What can you do?', 'Tell me a joke'];
+  const oneMessage = [{ id: '1', role: 'user' as const, content: 'hi' }];
+
+  it('renders suggestions when the thread is empty', () => {
+    const { getByText } = render(() => <ChatThread messages={[]} suggestions={SUGGESTIONS} />);
+    expect(getByText('What can you do?')).toBeInTheDocument();
+    expect(getByText('Tell me a joke')).toBeInTheDocument();
+  });
+
+  it('hides suggestions once the conversation has messages (default)', () => {
+    const { queryByText } = render(() => <ChatThread messages={oneMessage} suggestions={SUGGESTIONS} />);
+    expect(queryByText('What can you do?')).toBeNull();
+    expect(queryByText('Tell me a joke')).toBeNull();
+  });
+
+  it('keeps suggestions visible with messages when persistSuggestions is set', () => {
+    const { getByText } = render(() => (
+      <ChatThread messages={oneMessage} suggestions={SUGGESTIONS} persistSuggestions />
+    ));
+    expect(getByText('What can you do?')).toBeInTheDocument();
+    expect(getByText('Tell me a joke')).toBeInTheDocument();
+  });
+});

package/src/components/chat-thread.tsx

@@ -0,0 +1,249 @@
+import { createSignal, For, Show } from 'solid-js';
+import { ChatConfig, useChatConfig } from '../primitives/chat-config';
+import { ChatContainer, ChatContainerContent, ChatContainerScrollAnchor } from './chat-container';
+import { Message, MessageAvatar, MessageContent, MessageActionBar } from './message';
+import { Reasoning, ReasoningTrigger, ReasoningContent } from './reasoning';
+import { Tool } from './tool';
+import { Attachments, Attachment, AttachmentPreview, AttachmentInfo, type AttachmentData } from './attachments';
+import { ModelSwitcher } from './model-switcher';
+import { ScrollButton } from './scroll-button';
+import {
+  Context, ContextTrigger, ContextContent, ContextContentHeader,
+  ContextContentBody, ContextContentFooter, ContextInputUsage, ContextOutputUsage,
+} from './context';
+import { DefaultPromptInput } from '../elements/default-input';
+import type { SlashCommandItem } from './slash-command';
+import type { ChatMessage } from '../elements/chat-types';
+import type { ProseSize } from '../primitives/chat-config';
+import type { ModelOption } from '../types';
+
+export interface ChatThreadContextUsage {
+  usedTokens: number;
+  maxTokens: number;
+  inputTokens?: number;
+  outputTokens?: number;
+  estimatedCost?: number;
+}
+
+export interface ChatThreadProps {
+  /** Extra classes for the thread root (e.g. `h-full`). */
+  class?: string;
+  /** The full message thread to render, newest last. Each entry carries its role,
+   *  content, and optional reasoning/tools/attachments/actions. Set as a JS
+   *  property (`el.messages = [...]`). */
+  messages: ChatMessage[];
+  /** Controlled value of the input. When set, the host owns the input text and
+   *  must update it on `kai-value-change`; leave unset for uncontrolled behavior. */
+  value?: string;
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** When true, shows the loading/streaming state and disables submit (use while
+   *  awaiting the assistant's reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input when the thread is empty. Clicking one
+   *  follows `suggestionMode`. Set as a JS property. */
+  suggestions?: string[];
+  /** What clicking a suggestion does: `'submit'` (default) sends it immediately
+   *  as if typed and submitted; `'fill'` just places it in the input. */
+  suggestionMode?: 'submit' | 'fill';
+  /** Keep suggestions visible after the conversation starts. By default
+   *  suggestions are conversation starters and hide once `messages` is
+   *  non-empty; set this to keep them always shown. Default false. */
+  persistSuggestions?: boolean;
+  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`).
+   *  Defaults to `'sm'`. */
+  proseSize?: ProseSize;
+  /** Shiki theme name for syntax-highlighted code blocks (e.g.
+   *  `'github-dark-dimmed'`). */
+  codeTheme?: string;
+  /** Enable Shiki syntax highlighting in code blocks. Turn off to render plain
+   *  `<pre>` blocks (lighter, no highlighter load). Default true. */
+  codeHighlight?: boolean;
+  /** Optional header title shown on the left of the header. */
+  chatTitle?: string;
+  /** Optional model list. When set (>1 model) a ModelSwitcher is shown in the
+   *  header and a `kai-model-change` event fires on selection. */
+  models?: ModelOption[];
+  /** The currently selected model id (pairs with `models`). */
+  currentModel?: string;
+  /** Optional context-window token usage. When set, a Context token meter is
+   *  shown in the header. */
+  context?: ChatThreadContextUsage;
+  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
+  scrollButton?: boolean;
+  /** Whether the host has `slot="header-start"` content (left of the title) —
+   *  set by the `<kai-chat>` facade so a custom control forces the header open. */
+  headerStart?: boolean;
+  /** Whether the host has `slot="header-end"` content (right of the controls). */
+  headerEnd?: boolean;
+  /** Show a Search (Globe) button in the input toolbar; fires a `search` event. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the input toolbar; fires a `voice` event. */
+  voice?: boolean;
+  /** Slash commands — when set, typing `/` in the input opens the command
+   *  palette and fires `kai-slash-select`. Set as a JS property. */
+  slashCommands?: SlashCommandItem[];
+  /** Command ids to highlight as active in the palette. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  /** Whether each message's action bar is always visible (`'always'`, default)
+   *  or only revealed on hover of that message row (`'hover'`). */
+  actionsReveal?: 'always' | 'hover';
+  // callbacks (the facade maps these to dispatch())
+  onValueChange?: (value: string) => void;
+  onSubmit?: (detail: { value: string; attachments: AttachmentData[] }) => void;
+  onSuggestionClick?: (value: string) => void;
+  onModelChange?: (modelId: string) => void;
+  onMessageAction?: (detail: { messageId: string; action: string }) => void;
+  onSearch?: () => void;
+  onVoice?: () => void;
+  onSlashSelect?: (command: SlashCommandItem) => void;
+}
+
+export function ChatThread(props: ChatThreadProps) {
+  const outer = useChatConfig();
+  const reveal = () => (props.actionsReveal === 'hover' ? 'hover' : 'always');
+  const [internal, setInternal] = createSignal(props.value ?? '');
+  const [attachments, setAttachments] = createSignal<AttachmentData[]>([]);
+  const current = () => props.value ?? internal();
+  const handleChange = (v: string) => { setInternal(v); props.onValueChange?.(v); };
+  const handleSubmit = () => { props.onSubmit?.({ value: current(), attachments: attachments() }); setAttachments([]); };
+  const handleSuggestionClick = (v: string) => {
+    if ((props.suggestionMode ?? 'submit') === 'fill') { handleChange(v); props.onSuggestionClick?.(v); }
+    else { props.onSubmit?.({ value: v, attachments: attachments() }); setAttachments([]); }
+  };
+  const showHeader = () => !!(props.chatTitle || props.models || props.context || props.headerStart || props.headerEnd);
+  // Suggestions are conversation starters: show only on an empty thread unless
+  // the host opts into persisting them.
+  const visibleSuggestions = () =>
+    props.persistSuggestions || props.messages.length === 0 ? props.suggestions : undefined;
+  const showScrollButton = () => props.scrollButton !== false;
+
+  return (
+    <ChatConfig proseSize={props.proseSize} codeTheme={props.codeTheme} codeHighlight={props.codeHighlight !== false} portalMount={outer.portalMount()}>
+      <div class={`flex h-full flex-col bg-background ${props.class ?? ''}`}>
+        <Show when={showHeader()}>
+          <header class="flex h-14 shrink-0 items-center justify-between border-b border-border px-5">
+            <div class="flex items-center gap-2">
+              {/* Consumer-injected leading controls (sidebar-toggle, compose, a
+                  popover title-button). Projects light-DOM `slot="header-start"`
+                  children of <kai-chat>; inert outside a shadow root. */}
+              <slot name="header-start" />
+              <Show when={props.chatTitle}>
+                <div class="text-sm font-semibold text-foreground">{props.chatTitle}</div>
+              </Show>
+            </div>
+            <div class="flex items-center gap-2">
+              <Show when={props.models}>
+                <ModelSwitcher
+                  models={props.models!}
+                  currentModelId={props.currentModel ?? props.models![0]?.id ?? ''}
+                  onModelChange={(modelId) => props.onModelChange?.(modelId)}
+                />
+              </Show>
+              <Show when={props.context}>
+                <Context
+                  usedTokens={props.context!.usedTokens} maxTokens={props.context!.maxTokens}
+                  inputTokens={props.context!.inputTokens} outputTokens={props.context!.outputTokens}
+                  estimatedCost={props.context!.estimatedCost}
+                >
+                  <ContextTrigger />
+                  <ContextContent>
+                    <ContextContentHeader />
+                    <ContextContentBody><div class="space-y-1.5"><ContextInputUsage /><ContextOutputUsage /></div></ContextContentBody>
+                    <ContextContentFooter />
+                  </ContextContent>
+                </Context>
+              </Show>
+              {/* Consumer-injected trailing controls (share, settings, …).
+                  Projects light-DOM `slot="header-end"` children of <kai-chat>. */}
+              <slot name="header-end" />
+            </div>
+          </header>
+        </Show>
+        <div class="relative flex-1 overflow-hidden">
+          <ChatContainer class="h-full px-4 py-3">
+            <ChatContainerContent class="mx-auto w-full max-w-3xl space-y-4">
+              <For each={props.messages}>
+                {(m) => {
+                  const body = (
+                    <>
+                      <Show when={m.reasoning}>
+                        <Reasoning class="mb-2 w-full">
+                          <ReasoningTrigger>{m.reasoning!.label ?? 'Reasoning'}</ReasoningTrigger>
+                          <ReasoningContent markdown>{m.reasoning!.text}</ReasoningContent>
+                        </Reasoning>
+                      </Show>
+                      <For each={m.tools ?? []}>{(tp) => <Tool toolPart={tp} class="mb-2 w-full" />}</For>
+                      <Show when={m.attachments?.length}>
+                        <Attachments variant="inline" class={m.role === 'user' ? 'mb-2 justify-end' : 'mb-2'}>
+                          <For each={m.attachments!}>
+                            {(att) => (<Attachment data={att}><AttachmentPreview /><AttachmentInfo /></Attachment>)}
+                          </For>
+                        </Attachments>
+                      </Show>
+                      <MessageContent
+                        markdown={m.role === 'assistant'}
+                        class={m.role === 'user' ? 'bg-muted text-primary max-w-[85%] rounded-2xl px-4 py-2' : 'bg-transparent p-0'}
+                      >
+                        {m.content}
+                      </MessageContent>
+                      <Show when={m.actions?.length}>
+                        <MessageActionBar
+                          actions={m.actions!}
+                          reveal={reveal()}
+                          onAction={(action) => props.onMessageAction?.({ messageId: m.id, action })}
+                        />
+                      </Show>
+                    </>
+                  );
+                  const rowGroup = reveal() === 'hover' ? 'group ' : '';
+                  return (
+                    <Show
+                      when={m.avatar}
+                      fallback={
+                        <Message class={`${rowGroup}${m.role === 'user' ? 'flex-col items-end' : 'flex-col items-start'}`}>
+                          {body}
+                        </Message>
+                      }
+                    >
+                      {(av) => (
+                        <Message class={rowGroup}>
+                          <MessageAvatar src={av().src ?? ''} alt={av().alt ?? ''} fallback={av().fallback} />
+                          <div class={`flex min-w-0 flex-1 flex-col ${m.role === 'user' ? 'items-end' : 'items-start'}`}>
+                            {body}
+                          </div>
+                        </Message>
+                      )}
+                    </Show>
+                  );
+                }}
+              </For>
+              <ChatContainerScrollAnchor />
+            </ChatContainerContent>
+            <Show when={showScrollButton()}>
+              <div class="absolute bottom-4 left-1/2 flex w-full max-w-3xl -translate-x-1/2 justify-center px-5">
+                <ScrollButton class="shadow-sm" />
+              </div>
+            </Show>
+          </ChatContainer>
+        </div>
+        <div class="shrink-0 px-4 pb-4">
+          <div class="mx-auto max-w-3xl">
+            <DefaultPromptInput
+              value={current()} placeholder={props.placeholder} loading={props.loading === true}
+              suggestions={visibleSuggestions()} attachments={attachments()}
+              search={props.search === true} voice={props.voice === true}
+              slashCommands={props.slashCommands} slashActiveIds={props.slashActiveIds} slashCompact={props.slashCompact === true}
+              onValueChange={handleChange} onSubmit={handleSubmit} onSuggestionClick={handleSuggestionClick}
+              onAttachmentsChange={setAttachments}
+              onSearch={() => props.onSearch?.()} onVoice={() => props.onVoice?.()}
+              onSlashSelect={(command) => props.onSlashSelect?.(command)}
+            />
+          </div>
+        </div>
+      </div>
+    </ChatConfig>
+  );
+}

package/src/components/checkpoint.stories.tsx

@@ -0,0 +1,102 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { fn } from 'storybook/test';
+import { Checkpoint, CheckpointIcon, CheckpointTrigger } from './checkpoint';
+import { componentDescription } from '../stories/docs/element-controls';
+
+const meta = {
+  title: 'Solid (Advanced)/Elements/Checkpoint',
+  component: Checkpoint,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: componentDescription([
+        'An inline marker that lets a user restore the conversation to a saved point. Composed of `Checkpoint` (row + separator) wrapping a `CheckpointIcon` and a `CheckpointTrigger` button.',
+        '**When to use:** to mark a restorable state in a transcript — e.g. before an edit or a branching action — so the user can revert to it.',
+        '**How to use:** place a `CheckpointIcon` and a `CheckpointTrigger` inside `Checkpoint`. Give the trigger an `onClick` handler and an optional `tooltip`; pass custom SVG children to `CheckpointIcon` to override the default flag.',
+        '**Placement:** between messages in a chat transcript, as a thin separator-style row.',
+      ]),
+      controls: { exclude: ['use:eventListener'] },
+    },
+  },
+  argTypes: {
+    children: {
+      control: false,
+      description: 'The `CheckpointIcon` and `CheckpointTrigger` contents.',
+    },
+    class: {
+      control: 'text',
+      description: 'Extra classes for the checkpoint row.',
+    },
+  },
+  args: {},
+  render: (args) => (
+    <div class="max-w-md">
+      <Checkpoint {...args}>
+        <CheckpointIcon />
+        <CheckpointTrigger tooltip="Restore to this point" onClick={fn()}>
+          Restore
+        </CheckpointTrigger>
+      </Checkpoint>
+    </div>
+  ),
+} satisfies Meta<typeof Checkpoint>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const IMPORT = `import { Checkpoint, CheckpointIcon, CheckpointTrigger } from '@kitn.ai/ui';`;
+const src = (code: string) => ({
+  parameters: { docs: { source: { code: `${IMPORT}\n\n${code}`, language: 'tsx' } } },
+});
+
+/** Interactive playground — the default flag icon with a restore trigger. */
+export const Playground: Story = {
+  ...src(`<Checkpoint>
+  <CheckpointIcon />
+  <CheckpointTrigger tooltip="Restore to this point" onClick={handleRestore}>
+    Restore
+  </CheckpointTrigger>
+</Checkpoint>`),
+};
+
+export const WithCustomIcon: Story = {
+  render: () => (
+    <div class="max-w-md">
+      <Checkpoint>
+        <CheckpointIcon>
+          <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" class="size-4">
+            <path d="M12 22c5.523 0 10-4.477 10-10S17.523 2 12 2 2 6.477 2 12s4.477 10 10 10z" />
+            <path d="M12 6v6l4 2" />
+          </svg>
+        </CheckpointIcon>
+        <CheckpointTrigger tooltip="Go back to this checkpoint" onClick={fn()}>
+          Revert to checkpoint
+        </CheckpointTrigger>
+      </Checkpoint>
+    </div>
+  ),
+  ...src(`<Checkpoint>
+  <CheckpointIcon>
+    <ClockIcon class="size-4" />
+  </CheckpointIcon>
+  <CheckpointTrigger tooltip="Go back to this checkpoint" onClick={handleRevert}>
+    Revert to checkpoint
+  </CheckpointTrigger>
+</Checkpoint>`),
+};
+
+export const NoTooltip: Story = {
+  render: () => (
+    <div class="max-w-md">
+      <Checkpoint>
+        <CheckpointIcon />
+        <CheckpointTrigger onClick={fn()}>Restore</CheckpointTrigger>
+      </Checkpoint>
+    </div>
+  ),
+  ...src(`<Checkpoint>
+  <CheckpointIcon />
+  <CheckpointTrigger onClick={handleRestore}>Restore</CheckpointTrigger>
+</Checkpoint>`),
+};

package/src/components/checkpoint.tsx

@@ -0,0 +1,88 @@
+import { type JSX, Show, splitProps } from 'solid-js';
+import { cn } from '../utils/cn';
+import { Button } from '../ui/button';
+import { Tooltip } from '../ui/tooltip';
+import { Separator } from '../ui/separator';
+
+export interface CheckpointProps extends JSX.HTMLAttributes<HTMLDivElement> {}
+
+export function Checkpoint(props: CheckpointProps) {
+  const [local, rest] = splitProps(props, ['class', 'children']);
+  return (
+    <div
+      class={cn(
+        'flex items-center gap-0.5 overflow-hidden text-muted-foreground',
+        local.class
+      )}
+      {...rest}
+    >
+      {local.children}
+      <Separator />
+    </div>
+  );
+}
+
+export interface CheckpointIconProps {
+  class?: string;
+  children?: JSX.Element;
+}
+
+export function CheckpointIcon(props: CheckpointIconProps) {
+  return (
+    <Show
+      when={!props.children}
+      fallback={props.children}
+    >
+      <svg
+        width="16"
+        height="16"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2"
+        class={cn('size-4 shrink-0', props.class)}
+      >
+        <path d="M19 21l-7-5-7 5V5a2 2 0 012-2h10a2 2 0 012 2z" />
+      </svg>
+    </Show>
+  );
+}
+
+export interface CheckpointTriggerProps {
+  tooltip?: string;
+  /** Accessible name for the button — required when it has no visible text (icon-only). */
+  'aria-label'?: string;
+  onClick?: () => void;
+  children?: JSX.Element;
+  class?: string;
+  variant?: 'ghost' | 'default' | 'outline';
+  size?: 'sm' | 'md' | 'lg' | 'icon' | 'icon-sm';
+}
+
+export function CheckpointTrigger(props: CheckpointTriggerProps) {
+  const variant = () => props.variant ?? 'ghost';
+  const size = () => props.size ?? 'sm';
+
+  // A factory (not a single shared node): the Show fallback and the Tooltip
+  // child each need their OWN element instance, otherwise Solid reuses one DOM
+  // node across both branches and throws HierarchyRequestError when the tooltip
+  // branch mounts it.
+  const renderButton = () => (
+    <Button
+      variant={variant()}
+      size={size()}
+      type="button"
+      aria-label={props['aria-label']}
+      onClick={props.onClick}
+      class={props.class}
+    >
+      {props.children}
+    </Button>
+  );
+
+  return (
+    <Show when={props.tooltip} fallback={renderButton()}>
+      <Tooltip content={props.tooltip!}>{renderButton()}</Tooltip>
+    </Show>
+  );
+}