@kitn.ai/ui 0.14.1

package/src/elements/conversation-list.stories.tsx

@@ -0,0 +1,243 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers <kai-chat>, <kai-conversations>, <kai-prompt-input>
+import type { ConversationGroup, ConversationSummary } from '../types';
+import { argTypesFor, specDescription } from '../stories/docs/element-controls';
+
+// The web components are custom DOM elements, so declare the tags for JSX.
+declare module 'solid-js' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  namespace JSX {
+    interface IntrinsicElements {
+      'kai-conversations': JSX.HTMLAttributes<HTMLElement>;
+      'kai-conversation': JSX.HTMLAttributes<HTMLElement> & { id?: string; 'group-id'?: string };
+    }
+  }
+}
+
+const sampleGroups: ConversationGroup[] = [
+  { id: 'g-work', name: 'Work', sortOrder: 0, createdAt: '2026-06-01T09:00:00.000Z' },
+  { id: 'g-personal', name: 'Personal', sortOrder: 1, createdAt: '2026-06-02T09:00:00.000Z' },
+];
+
+const sampleConversations: ConversationSummary[] = [
+  {
+    id: 'c-1',
+    title: 'Q2 launch plan',
+    groupId: 'g-work',
+    scope: { type: 'collection' },
+    messageCount: 12,
+    lastMessageAt: '2026-06-09T14:20:00.000Z',
+    updatedAt: '2026-06-09T14:20:00.000Z',
+  },
+  {
+    id: 'c-2',
+    title: 'API migration notes',
+    groupId: 'g-work',
+    scope: { type: 'collection' },
+    messageCount: 5,
+    lastMessageAt: '2026-06-08T11:05:00.000Z',
+    updatedAt: '2026-06-08T11:05:00.000Z',
+  },
+  {
+    id: 'c-3',
+    title: 'Weekend trip ideas',
+    groupId: 'g-personal',
+    scope: { type: 'collection' },
+    messageCount: 8,
+    lastMessageAt: '2026-06-07T19:42:00.000Z',
+    updatedAt: '2026-06-07T19:42:00.000Z',
+  },
+  {
+    id: 'c-4',
+    title: 'Untitled chat',
+    scope: { type: 'collection' },
+    messageCount: 1,
+    lastMessageAt: '2026-06-10T08:00:00.000Z',
+    updatedAt: '2026-06-10T08:00:00.000Z',
+  },
+];
+
+type ConversationListEl = HTMLElement & {
+  groups?: ConversationGroup[];
+  conversations?: ConversationSummary[];
+  activeId?: string;
+};
+
+/** Live demo of the actual `<kai-conversations>` custom element (Shadow DOM and all). */
+function ConversationListElement(props: { args?: Record<string, unknown> }) {
+  let el: ConversationListEl | undefined;
+  onMount(() => {
+    if (el) {
+      // Fixed array data
+      el.groups = sampleGroups;
+      el.conversations = sampleConversations;
+      el.activeId = 'c-1';
+      // Scalar args from Controls
+      const args = props.args;
+      if (args) {
+        const scalarNames = ['activeId'];
+        for (const name of scalarNames) {
+          if (name in args) (el as unknown as Record<string, unknown>)[name] = args[name];
+        }
+      }
+    }
+  });
+  return (
+    <kai-conversations
+      ref={(e) => (el = e as ConversationListEl)}
+      style={{ display: 'block', width: '300px', height: '560px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kai-conversations id="list" style="display:block; width:300px; height:100vh;"></kai-conversations>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  const list = document.getElementById('list');
+  list.groups = [
+    { id: 'g-work', name: 'Work', sortOrder: 0, createdAt: '2026-06-01T09:00:00.000Z' },
+  ];
+  list.conversations = [
+    {
+      id: 'c-1', title: 'Q2 launch plan', groupId: 'g-work',
+      scope: { type: 'collection' }, messageCount: 12,
+      lastMessageAt: '2026-06-09T14:20:00.000Z', updatedAt: '2026-06-09T14:20:00.000Z',
+    },
+  ];
+  list.activeId = 'c-1';
+
+  // events are CustomEvents on the element (they do not bubble)
+  list.addEventListener('kai-conversation-select', (e) => console.log('opened:', e.detail.id));
+  list.addEventListener('kai-new-chat', () => console.log('new chat'));
+  list.addEventListener('kai-toggle-sidebar', () => console.log('toggle sidebar'));
+</script>`;
+
+const SOLID_SNIPPET = `import '@kitn.ai/ui/elements'; // registers the custom elements
+import { onMount } from 'solid-js';
+import type { ConversationGroup, ConversationSummary } from '@kitn.ai/ui';
+
+function Sidebar() {
+  let el: HTMLElement & {
+    groups?: ConversationGroup[];
+    conversations?: ConversationSummary[];
+    activeId?: string;
+  };
+  const groups: ConversationGroup[] = [
+    { id: 'g-work', name: 'Work', sortOrder: 0, createdAt: '2026-06-01T09:00:00.000Z' },
+  ];
+  const conversations: ConversationSummary[] = [
+    {
+      id: 'c-1', title: 'Q2 launch plan', groupId: 'g-work',
+      scope: { type: 'collection' }, messageCount: 12,
+      lastMessageAt: '2026-06-09T14:20:00.000Z', updatedAt: '2026-06-09T14:20:00.000Z',
+    },
+  ];
+  onMount(() => {
+    el.groups = groups;
+    el.conversations = conversations;
+    el.activeId = 'c-1';
+  });
+  return (
+    <kai-conversations
+      ref={el}
+      style={{ display: 'block', width: '300px', height: '100vh' }}
+      on:kai-conversation-select={(e) => console.log('opened:', e.detail.id)}
+      on:kai-new-chat={() => console.log('new chat')}
+      on:kai-toggle-sidebar={() => console.log('toggle sidebar')}
+    />
+  );
+}`;
+
+const meta = {
+  title: 'Components/Conversations',
+  tags: ['autodocs'],
+  argTypes: argTypesFor('kai-conversations'),
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: specDescription('kai-conversations', [
+          '`<kai-conversations>` is the framework-agnostic **web component** version of the chat sidebar — a searchable, grouped list of conversations with a "new chat" button, isolated in **Shadow DOM** so the host page\'s CSS can\'t leak in and the kit\'s styles can\'t leak out. SolidJS is bundled in, so the host needs nothing.',
+          '**When to use:** adding a conversation switcher to a non-Solid app (React, Vue, Svelte, plain HTML), or anywhere you want zero style conflicts. If you *are* in SolidJS and want fine-grained control, compose the `ConversationList` primitive instead.',
+          '**How to use — data-driven:** register once with `import \'@kitn.ai/ui/elements\'`, then set rich data as JS **properties** (`el.groups = [...]`, `el.conversations = [...]`, `el.activeId = \'c-1\'`) and listen for **CustomEvents** (`kai-conversation-select`, `kai-new-chat`, `kai-toggle-sidebar`) directly on the element.',
+          '**How to use — declarative:** alternatively, compose `<kai-conversation>` child elements directly in markup — each child carries its `id` as an attribute and its title as text content (`<kai-conversation id="c-1">Q2 plan</kai-conversation>`). No JS property wiring needed; the element reads them on mount and re-reads on DOM changes via MutationObserver. Events fire identically to the data-driven path.',
+          '**Anatomy:** **header** (collapse/sidebar toggle button + "New chat" button) → **group headers** (one per `ConversationGroup`, labelled by `group.name`) → **conversation rows** (`<kai-conversation>` items or JS-property rows; active row is highlighted; each row is a button firing `kai-conversation-select`). Declarative `<kai-conversation id="…">title</kai-conversation>` children are invisible data carriers (no shadow slot) merged with the `conversations` property list.',
+          '**Placement:** as a fixed-width side panel next to the chat surface. Give it an explicit width and height (e.g. `width: 300px; height: 100vh`).',
+          'See the **Code** tab below for the HTML usage; the *SolidJS* story shows the same element inside a Solid component.',
+        ]),
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** The element used the plain-HTML / any-framework way. */
+export const Default: Story = {
+  args: {
+    activeId: 'c-1',
+  },
+  render: (args: Record<string, unknown>) => <ConversationListElement args={args} />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** The same element used inside a SolidJS component (properties via `ref`, events via `on:`). */
+export const InSolidJS: Story = {
+  name: 'In SolidJS',
+  render: () => <ConversationListElement />,
+  parameters: { docs: { source: { code: SOLID_SNIPPET, language: 'tsx' } } },
+};
+
+const DECLARATIVE_HTML_SNIPPET = `<!-- Works in any framework or plain HTML — no JS property wiring needed -->
+<kai-conversations id="list" style="display:block; width:300px; height:560px;">
+  <kai-conversation id="c-1">Q2 launch plan</kai-conversation>
+  <kai-conversation id="c-2">API migration notes</kai-conversation>
+  <kai-conversation id="c-3">Weekend trip ideas</kai-conversation>
+</kai-conversations>
+
+<script type="module">
+  import '@kitn.ai/ui/elements';   // registers the custom elements
+
+  // Events fire exactly the same as the data-driven approach.
+  document.getElementById('list')
+    .addEventListener('kai-conversation-select', (e) => console.log('opened:', e.detail.id));
+</script>`;
+
+/** Declarative conversations — \`<kai-conversation>\` light-DOM children instead of
+ *  a \`conversations\` property. Each child carries its \`id\` as an attribute and
+ *  its title as text content. Great for plain HTML or server-rendered markup
+ *  where JS property wiring is inconvenient. */
+export const DeclarativeConversations: Story = {
+  name: 'Declarative Conversations (kai-conversation)',
+  render: () => {
+    let el: HTMLElement | undefined;
+    onMount(() => {
+      if (!el) return;
+      el.addEventListener('kai-conversation-select', (e: Event) => {
+        console.log('selected:', (e as CustomEvent<{ id: string }>).detail.id);
+      });
+    });
+    return (
+      <kai-conversations
+        ref={(e) => (el = e as HTMLElement)}
+        style={{ display: 'block', width: '300px', height: '560px' }}
+      >
+        <kai-conversation id="c-1">Q2 launch plan</kai-conversation>
+        <kai-conversation id="c-2">API migration notes</kai-conversation>
+        <kai-conversation id="c-3">Weekend trip ideas</kai-conversation>
+      </kai-conversations>
+    );
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: DECLARATIVE_HTML_SNIPPET,
+        language: 'html',
+      },
+    },
+  },
+};
+

package/src/elements/conversation-list.tsx

@@ -0,0 +1,80 @@
+import { createSignal, onMount, onCleanup } from 'solid-js';
+import { defineWebComponent } from './define';
+import { ConversationList } from '../components/conversation-list';
+import type { ConversationGroup, ConversationSummary, ConversationScope } from '../types';
+
+interface Props extends Record<string, unknown> {
+  /** Pre-bucketed conversation groups (e.g. "Today", "Yesterday"), each with its
+   *  own conversations. Use this when you want to control the grouping/headers
+   *  yourself; otherwise pass a flat `conversations` array. Set as a JS property. */
+  groups: ConversationGroup[];
+  /** A flat list of conversation summaries; the component buckets them by recency
+   *  for you. Ignored when `groups` is provided. Set as a JS property. */
+  conversations: ConversationSummary[];
+  /** The id of the currently-open conversation, highlighted in the list. */
+  activeId?: string;
+}
+
+interface Events {
+  /** A conversation was selected. */
+  'kai-conversation-select': { id: string };
+  /** The "New chat" button was clicked. */
+  'kai-new-chat': Record<string, never>;
+  /** The sidebar toggle was clicked. */
+  'kai-toggle-sidebar': Record<string, never>;
+}
+
+/** Parse a single light-DOM `<kai-conversation>` element into a `ConversationSummary`.
+ *  Attribute mapping:
+ *   - `id`       → ConversationSummary.id
+ *   - `group-id` → ConversationSummary.groupId (optional)
+ *   - textContent → ConversationSummary.title
+ *  Required fields not expressible as HTML attributes (`scope`, `messageCount`,
+ *  `lastMessageAt`, `updatedAt`) receive safe defaults so the rendered list item
+ *  is fully functional with just `id` + title text.
+ */
+export function parseKaiConversationElement(n: Element): ConversationSummary {
+  return {
+    id: n.getAttribute('id') ?? '',
+    title: n.textContent?.trim() ?? '',
+    groupId: n.getAttribute('group-id') ?? undefined,
+    scope: { type: 'collection' } as ConversationScope,
+    messageCount: 0,
+    lastMessageAt: new Date(0).toISOString(),
+    updatedAt: new Date(0).toISOString(),
+  };
+}
+
+defineWebComponent<Props, Events>('kai-conversations', {
+  groups: [],
+  conversations: [],
+  activeId: undefined,
+}, (props, { dispatch, element }) => {
+  // Read declarative <kai-conversation> children from light DOM.
+  // Shadow DOM with no <slot> suppresses them visually — they're invisible data carriers.
+  const [slottedConversations, setSlottedConversations] = createSignal<ConversationSummary[]>([]);
+  onMount(() => {
+    const read = () => {
+      const nodes = [...element.querySelectorAll('kai-conversation')];
+      setSlottedConversations(nodes.map(parseKaiConversationElement));
+    };
+    read();
+    const observer = new MutationObserver(read);
+    observer.observe(element, { childList: true, attributes: true, subtree: true });
+    onCleanup(() => observer.disconnect());
+  });
+
+  // Prop conversations take precedence; slotted children are appended after.
+  const allConversations = () => [...(props.conversations ?? []), ...slottedConversations()];
+
+  return (
+    <ConversationList
+      groups={props.groups}
+      conversations={allConversations()}
+      activeId={props.activeId}
+      onSelect={(id) => dispatch('kai-conversation-select', { id })}
+      onNewChat={() => dispatch('kai-new-chat')}
+      onToggleSidebar={() => dispatch('kai-toggle-sidebar')}
+    />
+  );
+});

package/src/elements/css.ts

@@ -0,0 +1,5 @@
+// Imports the compiled kit CSS as a raw string (Vite `?inline`) so it can be
+// injected into custom-element shadow roots. Run `npm run build:css` first.
+import compiled from './compiled.css?inline';
+
+export const ELEMENT_CSS: string = compiled;

package/src/elements/default-input.tsx

@@ -0,0 +1,247 @@
+import { For, Show } from 'solid-js';
+import { PromptInput, PromptInputTextarea, PromptInputActions } from '../components/prompt-input';
+import { PromptSuggestion } from '../components/prompt-suggestion';
+import { SlashCommand, type SlashCommandItem } from '../components/slash-command';
+import { Button } from '../ui/button';
+import { Tooltip } from '../ui/tooltip';
+import { Paperclip, Globe, Mic, Square } from 'lucide-solid';
+import {
+  Attachments,
+  Attachment,
+  AttachmentPreview,
+  AttachmentInfo,
+  AttachmentRemove,
+  type AttachmentData,
+} from '../components/attachments';
+import { actionIcon } from '../ui/action-icons';
+import type { CustomAction } from './chat-types';
+
+export interface DefaultPromptInputProps {
+  value: string;
+  placeholder?: string;
+  disabled?: boolean;
+  loading?: boolean;
+  suggestions?: string[];
+  /** Attachments staged in the input. Provide `onAttachmentsChange` to enable
+   *  the attach button + removable previews. */
+  attachments?: AttachmentData[];
+  /** Show a Search (Globe) button in the left toolbar; calls `onSearch`. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the left toolbar; calls `onVoice`. */
+  voice?: boolean;
+  /** Slash commands — when set, typing `/` opens the command palette. */
+  slashCommands?: SlashCommandItem[];
+  /** Currently-active command ids (highlighted in the palette). */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  onValueChange: (v: string) => void;
+  onSubmit: () => void;
+  onSuggestionClick: (v: string) => void;
+  onAttachmentsChange?: (attachments: AttachmentData[]) => void;
+  onSearch?: () => void;
+  onVoice?: () => void;
+  onSlashSelect?: (command: SlashCommandItem) => void;
+  /** When `true` and `loading` is also `true`, the send button is replaced by
+   *  a Stop button that calls `onStop`. */
+  stoppable?: boolean;
+  /** Called when the user clicks the Stop button. */
+  onStop?: () => void;
+  /** Custom toolbar action buttons declared as `<kai-action>` light-DOM children. */
+  toolbarActions?: CustomAction[];
+  /** Called when a custom toolbar action button is clicked, with the action id. */
+  onAction?: (id: string) => void;
+}
+
+function fileToAttachment(file: File): AttachmentData {
+  const id =
+    typeof crypto !== 'undefined' && crypto.randomUUID
+      ? crypto.randomUUID()
+      : `${file.name}-${file.size}-${file.lastModified}`;
+  return {
+    id,
+    type: 'file',
+    filename: file.name,
+    mediaType: file.type || undefined,
+    url: file.type.startsWith('image/') ? URL.createObjectURL(file) : undefined,
+  };
+}
+
+export function DefaultPromptInput(props: DefaultPromptInputProps) {
+  let fileInput: HTMLInputElement | undefined;
+  const attachments = () => props.attachments ?? [];
+  const canAttach = () => !!props.onAttachmentsChange;
+
+  const addFiles = (files: FileList | null) => {
+    if (!files?.length || !props.onAttachmentsChange) return;
+    props.onAttachmentsChange([...attachments(), ...Array.from(files).map(fileToAttachment)]);
+  };
+  const removeAttachment = (id: string) =>
+    props.onAttachmentsChange?.(attachments().filter((a) => a.id !== id));
+
+  const sendDisabled = () =>
+    props.disabled || props.loading || (!props.value.trim() && attachments().length === 0);
+
+  const showStop = () => !!props.loading && !!props.stoppable;
+
+  return (
+    <>
+      <Show when={props.suggestions?.length}>
+        <div class="mb-2 flex flex-wrap gap-2">
+          <For each={props.suggestions}>
+            {(s) => (
+              <PromptSuggestion onClick={() => props.onSuggestionClick(s)}>{s}</PromptSuggestion>
+            )}
+          </For>
+        </div>
+      </Show>
+      <PromptInput
+        value={props.value}
+        onValueChange={props.onValueChange}
+        onSubmit={props.onSubmit}
+        isLoading={props.loading}
+        disabled={props.disabled}
+        class="relative"
+      >
+        <Show when={props.slashCommands?.length}>
+          {/* Rendered inside PromptInput so SlashCommand's usePromptInput()
+              context (input value + textarea ref) resolves; the `relative` root
+              anchors its `absolute bottom-full` palette above the input. */}
+          <SlashCommand
+            commands={props.slashCommands!}
+            activeIds={props.slashActiveIds}
+            compact={props.slashCompact}
+            onSelect={(command) => props.onSlashSelect?.(command)}
+          />
+        </Show>
+        <Show when={canAttach() && attachments().length}>
+          <div class="px-3 pt-3">
+            <Attachments variant="inline">
+              <For each={attachments()}>
+                {(att) => (
+                  <Attachment data={att} onRemove={() => removeAttachment(att.id)}>
+                    <AttachmentPreview />
+                    <AttachmentInfo />
+                    <AttachmentRemove />
+                  </Attachment>
+                )}
+              </For>
+            </Attachments>
+          </div>
+        </Show>
+        {/* Consumer-injected controls rendered before the input area. Native
+            slot; inert outside a shadow root, projected by the custom element. */}
+        <slot name="leading" />
+        <PromptInputTextarea placeholder={props.placeholder} aria-label={props.placeholder || 'Message'} 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">
+            <Show when={canAttach()}>
+              <input
+                ref={fileInput}
+                type="file"
+                multiple
+                class="hidden"
+                onChange={(e) => {
+                  addFiles(e.currentTarget.files);
+                  e.currentTarget.value = ''; // allow re-picking the same file
+                }}
+              />
+              <Button
+                type="button"
+                variant="outline"
+                size="icon-sm"
+                class="rounded-full"
+                aria-label="Attach files"
+                disabled={props.disabled}
+                onClick={() => fileInput?.click()}
+              >
+                <Paperclip class="size-4" />
+              </Button>
+            </Show>
+            <Show when={props.search}>
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                class="rounded-full gap-1"
+                aria-label="Search the web"
+                disabled={props.disabled}
+                onClick={() => props.onSearch?.()}
+              >
+                <Globe class="size-4" />
+                Search
+              </Button>
+            </Show>
+            <Show when={props.voice}>
+              <Button
+                type="button"
+                variant="outline"
+                size="icon-sm"
+                class="rounded-full"
+                aria-label="Voice input"
+                disabled={props.disabled}
+                onClick={() => props.onVoice?.()}
+              >
+                <Mic class="size-4" />
+              </Button>
+            </Show>
+            <For each={props.toolbarActions ?? []}>
+              {(action) => {
+                const Icon = actionIcon(action.icon);
+                const label = action.tooltip ?? action.label;
+                const btn = (
+                  <Button
+                    type="button"
+                    variant="outline"
+                    size="icon-sm"
+                    class="rounded-full"
+                    aria-label={action.label}
+                    data-action={action.id}
+                    disabled={props.disabled}
+                    onClick={() => props.onAction?.(action.id)}
+                  >
+                    <Show when={Icon} fallback={<span class="px-1 text-xs">{action.label}</span>}>
+                      {(I) => { const C = I(); return <C class="size-4" />; }}
+                    </Show>
+                  </Button>
+                );
+                return Icon ? <Tooltip content={label}>{btn}</Tooltip> : btn;
+              }}
+            </For>
+          </div>
+          {/* Consumer-injected controls rendered after the input area, beside
+              the send button. Native slot; projected by the custom element. */}
+          <slot name="trailing" />
+          <Show
+            when={showStop()}
+            fallback={
+              <Button
+                size="icon-sm"
+                class="rounded-full"
+                data-testid="send"
+                aria-label="Send message"
+                disabled={sendDisabled()}
+                onClick={props.onSubmit}
+              >
+                <svg width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                  <line x1="12" y1="19" x2="12" y2="5" /><polyline points="5 12 12 5 19 12" />
+                </svg>
+              </Button>
+            }
+          >
+            <Button
+              size="icon-sm"
+              variant="outline"
+              class="rounded-full"
+              data-testid="stop"
+              aria-label="Stop"
+              onClick={props.onStop}
+            >
+              <Square class="size-3" />
+            </Button>
+          </Show>
+        </PromptInputActions>
+      </PromptInput>
+    </>
+  );
+}