@kitnai/chat 0.3.1 → 0.5.0

package/src/elements/define.tsx

@@ -1,7 +1,29 @@
 import { customElement } from 'solid-element';
 import { ChatConfig } from '../primitives/chat-config';
 import { KITN_CSS } from './css';
-import { createSignal, onCleanup, type JSX } from 'solid-js';
+import { createSignal, onCleanup, onMount, Show, type JSX } from 'solid-js';
+
+/**
+ * Shared constructable stylesheet, built once and adopted by every element's
+ * shadow root. This avoids duplicating the full compiled kit CSS (~77 KB) as an
+ * inline `<style>` in each instance — important now that composing many small
+ * elements on a page is a supported pattern. Falls back to `null` where
+ * Constructable Stylesheets aren't available, in which case the facade renders
+ * an inline `<style>` instead (see below).
+ */
+let sharedSheet: CSSStyleSheet | null | undefined;
+function getSharedSheet(): CSSStyleSheet | null {
+  if (sharedSheet !== undefined) return sharedSheet;
+  try {
+    if (typeof CSSStyleSheet === 'undefined') throw new Error('no CSSStyleSheet');
+    const sheet = new CSSStyleSheet();
+    sheet.replaceSync(KITN_CSS);
+    sharedSheet = sheet;
+  } catch {
+    sharedSheet = null;
+  }
+  return sharedSheet;
+}
 
 /** Resolve whether the element should render dark, given its `theme` and the
  *  system preference. `auto` (the default) follows `prefers-color-scheme`. */
@@ -20,15 +42,45 @@ function createDarkMode(getTheme: () => string | undefined) {
   };
 }
 
-export interface KitnElementContext {
+/**
+ * Context handed to every element facade. `E` is the element's event map —
+ * `{ eventName: detailType }` — which types `dispatch` so a facade can only fire
+ * its declared events with the right `detail` shape.
+ */
+export interface KitnElementContext<E = Record<string, unknown>> {
   /** The custom-element host node. */
   element: HTMLElement;
   /** Fire a non-bubbling, non-composed CustomEvent off the host. Consumers
-   *  listen directly on the element (`el.addEventListener(...)`). */
-  dispatch: (type: string, detail?: unknown) => void;
+   *  listen directly on the element (`el.addEventListener(...)`). Typed by the
+   *  element's event map `E`. */
+  dispatch: <K extends keyof E & string>(type: K, detail?: E[K]) => void;
+  /**
+   * Resolve a boolean flag from a prop the way HTML authors expect.
+   *
+   * `component-register` parses a *bare* boolean attribute (`<el removable>`) to
+   * `undefined`, not `true` — so a facade can't rely on the prop value alone.
+   * `flag('removable')` returns ON when the property is `true`, OR when the
+   * matching attribute is present and not explicitly `="false"`. So all of
+   * `<el removable>`, `<el removable="true">`, and `el.removable = true` turn it
+   * on; `<el removable="false">`, absent, and `el.removable = false` turn it off.
+   *
+   * `name` is the camelCase prop name; the matching kebab attribute is derived.
+   */
+  flag: (name: string) => boolean;
 }
 
-type FacadeComponent<P> = (props: P, ctx: KitnElementContext) => JSX.Element;
+/** camelCase prop name → kebab-case attribute (`hoverCard` → `hover-card`). */
+function toAttr(name: string): string {
+  return name.replace(/([A-Z])/g, '-$1').toLowerCase();
+}
+
+/** Underlying flag resolution; see `KitnElementContext.flag`. */
+function resolveFlag(element: HTMLElement, value: unknown, attribute: string): boolean {
+  if (value === true) return true;
+  return element.hasAttribute(attribute) && element.getAttribute(attribute) !== 'false';
+}
+
+type FacadeComponent<P, E> = (props: P, ctx: KitnElementContext<E>) => JSX.Element;
 
 /**
  * Register a Solid facade as a Shadow-DOM custom element.
@@ -36,19 +88,36 @@ type FacadeComponent<P> = (props: P, ctx: KitnElementContext) => JSX.Element;
  * - Renders into the element's shadow root (solid-element's default), with the
  *   compiled kit CSS injected via a `<style>` so Tailwind classes apply inside.
  * - Creates a portal mount node inside the shadow root and provides it through
- *   `ChatConfig` so Kobalte overlays stay inside the shadow root.
+ *   `ChatConfig` so the kit's overlays stay inside the shadow root.
  * - Gives the facade a `dispatch(type, detail)` helper that fires non-bubbling,
  *   non-composed CustomEvents off the host element (consumers listen directly on
  *   the element, so bubbling/composed would only cause consumer collisions).
  * - Idempotent: redefining an already-registered tag is a no-op.
  */
-export function defineKitnElement<P extends Record<string, unknown>>(
+export function defineKitnElement<P extends Record<string, unknown>, E = Record<string, unknown>>(
   tag: string,
   propDefaults: P,
-  Facade: FacadeComponent<P>,
+  Facade: FacadeComponent<P, E>,
 ): void {
   if (typeof customElements !== 'undefined' && customElements.get(tag)) return;
 
+  // Guard against prop names that collide with global reflected HTMLElement IDL
+  // attributes. component-register sets `this[prop] = undefined` in the element
+  // constructor; for these, the native setter coerces undefined → "undefined"
+  // and reflects it to an attribute — which is illegal in a CE constructor and
+  // throws a cryptic "result must not have attributes". Fail loud and early with
+  // a name + fix instead. (Use a prefixed attribute, e.g. `bar-title`/`headline`.)
+  const RESERVED = ['title', 'id', 'slot', 'lang'];
+  for (const key of Object.keys(propDefaults)) {
+    if (RESERVED.includes(key)) {
+      throw new Error(
+        `defineKitnElement(${tag}): prop "${key}" collides with a global HTMLElement ` +
+        `attribute and will break the element constructor. Rename it (e.g. ` +
+        `"bar-title" → barTitle, a source title → headline).`,
+      );
+    }
+  }
+
   // Every element gets a `theme` property/attribute: 'light' | 'dark' | 'auto'
   // (default 'auto' = follow the OS `prefers-color-scheme`). It drives a `.dark`
   // class on an inner wrapper, which the injected kit CSS already styles — so dark
@@ -59,16 +128,33 @@ export function defineKitnElement<P extends Record<string, unknown>>(
     const element = options.element as HTMLElement;
     let portalNode!: HTMLDivElement;
 
-    const dispatch = (type: string, detail?: unknown) =>
+    const dispatch = ((type: string, detail?: unknown) =>
       element.dispatchEvent(
         new CustomEvent(type, { detail, bubbles: false, composed: false }),
-      );
+      )) as KitnElementContext<E>['dispatch'];
+
+    // Reads `props[name]` (reactive) and falls back to attribute presence so
+    // bare boolean attributes behave like normal HTML. See KitnElementContext.
+    const flag = (name: string) =>
+      resolveFlag(element, (props as Record<string, unknown>)[name], toAttr(name));
 
     const isDark = createDarkMode(() => props.theme as string | undefined);
 
+    // Prefer a single shared stylesheet adopted into this shadow root; only emit
+    // an inline <style> when Constructable Stylesheets aren't supported.
+    const sheet = getSharedSheet();
+    onMount(() => {
+      const root = element.shadowRoot;
+      if (sheet && root && 'adoptedStyleSheets' in root) {
+        root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];
+      }
+    });
+
     return (
       <>
-        <style>{KITN_CSS}</style>
+        <Show when={!sheet}>
+          <style>{KITN_CSS}</style>
+        </Show>
         {/* display:contents — no layout box; carries the .dark token scope and
             re-roots the inherited `color` to the active mode's foreground, so text
             without an explicit color class (e.g. attachment filename labels) follows
@@ -76,7 +162,7 @@ export function defineKitnElement<P extends Record<string, unknown>>(
         <div classList={{ dark: isDark() }} style={{ display: 'contents', color: 'var(--color-foreground)' }}>
           <div ref={portalNode} />
           <ChatConfig portalMount={portalNode}>
-            {Facade(props as unknown as P, { element, dispatch })}
+            {Facade(props as unknown as P, { element, dispatch, flag })}
           </ChatConfig>
         </div>
       </>

package/src/elements/element-types.d.ts

@@ -0,0 +1,444 @@
+// AUTO-GENERATED by scripts/gen-element-api.mjs — do not edit by hand.
+// Typed custom-element interfaces + HTMLElementTagNameMap augmentation, so
+// `document.querySelector('kitn-message')` is typed and gets prop autocomplete.
+
+
+// Re-exports for `import { … } from '@kitnai/chat/elements'`.
+export type { ChatMessage, ChatMessageAction } from './chat-types';
+export { configureCodeHighlighting, isCodeHighlightingEnabled } from '../primitives/highlighter';
+export type { CodeHighlightingOptions } from '../primitives/highlighter';
+
+export interface KitnAttachmentsElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The attachments to render. Set as a JS property (array). */
+  items: { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[];
+  /** Layout: `grid` = visual tiles, `inline` = icon + label chips, `list` = rows. */
+  variant?: "grid" | "inline" | "list";
+  /** Wrap each item in a hover card that previews its details. */
+  hoverCard?: boolean;
+  /** Show a remove button per item; clicking it fires a `remove` event. */
+  removable?: boolean;
+  /** Also show the media type beneath the filename (non-grid variants). */
+  showMediaType?: boolean;
+  /** Text shown when `items` is empty. */
+  emptyText?: string;
+}
+
+export interface KitnChainOfThoughtElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The reasoning steps. Set as a JS property. Compound sub-parts collapse to this one data model (Route 1). */
+  steps: { label: string; content?: undefined | string }[];
+}
+
+export interface KitnChatElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** 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: { id: string; role: "user" | "assistant"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | ("copy" | "like" | "dislike" | "regenerate" | "edit")[] }[];
+  /** Controlled value of the input. When set, the host owns the input text and must update it on `valuechange`; 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";
+  /** Body/prose font scale for rendered markdown (`'xs' | 'sm' | 'base' | 'lg'`). Defaults to `'sm'`. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** 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 `modelchange` event fires on selection. */
+  models?: { id: string; name: string; provider?: string }[];
+  /** 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?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; estimatedCost?: number };
+  /** Show the scroll-to-bottom button inside the scroll area. Default true. */
+  scrollButton?: 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 `slashselect`. Set as a JS property. */
+  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
+  /** Command ids to highlight as active in the palette. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+}
+
+export interface KitnChatScopePickerElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Authors to offer as scope filters. Set as a JS property. */
+  availableAuthors: string[];
+  /** Tags to offer as scope filters. Set as a JS property. */
+  availableTags: string[];
+  /** The label shown on the trigger for the active scope. */
+  currentLabel?: string;
+}
+
+export interface KitnChatWorkspaceElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Pre-bucketed conversation groups for the sidebar. Set as a JS property. */
+  groups: { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[];
+  /** Flat conversation list (auto-bucketed if `groups` is empty). Set as a JS property. */
+  conversations: { id: string; title: string; groupId?: undefined | string; scope: { type: "document" | "collection"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string }[];
+  /** Id of the open conversation, highlighted in the sidebar. */
+  activeId?: string;
+  /** The active conversation's message thread, newest last. Set as a JS property. */
+  messages: { id: string; role: "user" | "assistant"; content: string; reasoning?: undefined | { text: string; label?: undefined | string }; tools?: undefined | { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: undefined | Record<string, unknown>; output?: undefined | Record<string, unknown>; toolCallId?: undefined | string; errorText?: undefined | string }[]; attachments?: undefined | { id: string; type: "file" | "source-document"; filename?: undefined | string; mediaType?: undefined | string; url?: undefined | string; title?: undefined | string }[]; actions?: undefined | ("copy" | "like" | "dislike" | "regenerate" | "edit")[] }[];
+  value?: string;
+  placeholder?: string;
+  loading?: boolean;
+  suggestions?: string[];
+  suggestionMode?: "submit" | "fill";
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  codeTheme?: string;
+  codeHighlight?: boolean;
+  chatTitle?: string;
+  models?: { id: string; name: string; provider?: string }[];
+  currentModel?: string;
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; estimatedCost?: number };
+  scrollButton?: boolean;
+  search?: boolean;
+  voice?: boolean;
+  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
+  slashActiveIds?: string[];
+  slashCompact?: boolean;
+  /** Sidebar default width as a percent of the workspace (default 22). */
+  sidebarWidth?: number;
+  /** Sidebar min width in px (default 200). */
+  sidebarMinWidth?: number;
+  /** Sidebar max width in px (default 420). */
+  sidebarMaxWidth?: number;
+  /** Initial collapsed state of the sidebar (default false). */
+  sidebarCollapsed?: boolean;
+}
+
+export interface KitnCheckpointElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Optional text beside the icon. */
+  label?: string;
+  /** Tooltip on hover. */
+  tooltip?: string;
+  /** Visual button style. */
+  variant?: "ghost" | "default" | "outline";
+  /** Button size (use an `icon*` size for an icon-only checkpoint). */
+  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+}
+
+export interface KitnCodeBlockElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The source code to render. */
+  code: string;
+  /** Language grammar (e.g. `js`, `python`). Defaults to `tsx`. */
+  language?: string;
+  /** Shiki theme name. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (renders plain text, no Shiki). */
+  codeHighlight?: boolean;
+  /** Code text sizing. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+}
+
+export interface KitnContextMeterElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Token-usage data. Set as a JS property. */
+  context?: { usedTokens: number; maxTokens: number; inputTokens?: number; outputTokens?: number; reasoningTokens?: number; cacheTokens?: number; estimatedCost?: number };
+}
+
+export interface KitnConversationListElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** 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: { id: string; userId?: undefined | string; teamId?: undefined | string; name: string; sortOrder: number; createdAt: string }[];
+  /** 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: { id: string; title: string; groupId?: undefined | string; scope: { type: "document" | "collection"; documentId?: undefined | string; filters?: undefined | { tags?: undefined | string[]; authors?: undefined | string[]; contentType?: undefined | "transcript" | "markdown"; dateRange?: undefined | { from: string; to: string } } }; messageCount: number; lastMessageAt: string; updatedAt: string }[];
+  /** The id of the currently-open conversation, highlighted in the list. */
+  activeId?: string;
+}
+
+export interface KitnEmptyElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Title text. Attribute: `empty-title` (`title` is a global HTML attribute). */
+  emptyTitle?: string;
+  /** Description text. */
+  description?: string;
+}
+
+export interface KitnFeedbackBarElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The banner label (e.g. "Was this helpful?"). Attribute: `bar-title` (`title` is avoided — it's a global HTML attribute). */
+  barTitle?: string;
+}
+
+export interface KitnFileUploadElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Allow selecting multiple files (default true). */
+  multiple?: boolean;
+  /** `accept` attribute for the file picker (e.g. `image/*`). */
+  accept?: string;
+  /** Disable the dropzone — no clicking, no drag-and-drop. */
+  disabled?: boolean;
+  /** Default dropzone label (overridable via the default slot). */
+  label?: string;
+}
+
+export interface KitnImageElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Base64-encoded image data (pair with `media-type`). */
+  base64?: string;
+  /** Raw image bytes (set as a JS property). */
+  bytes?: Uint8Array;
+  /** Alt text. */
+  alt?: string;
+  /** MIME type (default `image/png`). */
+  mediaType?: string;
+}
+
+export interface KitnLoaderElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The animation style: `'circular' | 'classic' | 'pulse' | 'pulse-dot' | 'dots' | 'typing' | 'wave' | 'bars' | 'terminal' | 'text-blink' | 'text-shimmer' | 'loading-dots'`. Defaults to `'circular'`. */
+  variant?: "circular" | "classic" | "pulse" | "pulse-dot" | "dots" | "typing" | "wave" | "bars" | "terminal" | "text-blink" | "text-shimmer" | "loading-dots";
+  /** Loader size: `'sm' | 'md' | 'lg'`. Defaults to `'md'`. */
+  size?: "sm" | "lg" | "md";
+  /** Label for the text-based variants. */
+  text?: string;
+}
+
+export interface KitnMarkdownElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The markdown source to render. */
+  content: string;
+  /** Text/markdown sizing. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme for fenced code blocks. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+export interface KitnMessageElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The full message object. Set as a JS property. */
+  message?: { id: string; role: "user" | "assistant"; content: string; reasoning?: { text: string; label?: string }; tools?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string }[]; attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[]; actions?: ("copy" | "like" | "dislike" | "regenerate" | "edit")[] };
+  /** Convenience for simple cases when not passing a `message` object. */
+  role?: "user" | "assistant";
+  /** Convenience content (used when `message` is not set). */
+  content?: string;
+  /** Force markdown on/off. Defaults to on for assistant, off for user. */
+  markdown?: boolean;
+  /** Text/markdown sizing for the message body. */
+  proseSize?: "xs" | "sm" | "base" | "lg";
+  /** Shiki theme name used for fenced code blocks in the content. */
+  codeTheme?: string;
+  /** Disable syntax highlighting for code blocks (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+export interface KitnMessageSkillsElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The active skills to badge. Set as a JS property. */
+  skills: { id: string; name: string }[];
+}
+
+export interface KitnModelSwitcherElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The selectable models. Set as a JS property (array). */
+  models: { id: string; name: string; provider?: undefined | string }[];
+  /** The currently-selected model id. Defaults to the first model. */
+  currentModel?: string;
+}
+
+export interface KitnPromptInputElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Controlled value of the input. When set, the host owns the text and must update it on `valuechange`; leave unset for uncontrolled behavior. */
+  value?: string;
+  /** Placeholder text shown in the empty input. */
+  placeholder?: string;
+  /** Disable the input and submit button entirely (non-interactive). */
+  disabled?: boolean;
+  /** Show the loading/streaming state and block submit (use while awaiting a reply). */
+  loading?: boolean;
+  /** Starter prompts shown above the input. 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";
+  /** Slash commands — when set, typing `/` opens the command palette. Set as a JS property. */
+  slashCommands?: { id: string; label: string; description?: string; category?: string }[];
+  /** Command ids to highlight as active. */
+  slashActiveIds?: string[];
+  /** Single-line palette rows. */
+  slashCompact?: boolean;
+  /** Show a Search (Globe) button in the left toolbar; clicking it fires a `search` event. */
+  search?: boolean;
+  /** Show a Voice (Mic) button in the left toolbar; clicking it fires a `voice` event. */
+  voice?: boolean;
+  /** Attachments to seed the input with (so a consumer can pre-populate staged files without an upload). Set as a JS property; the element then manages its own attachment state from there (add via the paperclip, remove per chip). */
+  attachments?: { id: string; type: "file" | "source-document"; filename?: string; mediaType?: string; url?: string; title?: string }[];
+}
+
+export interface KitnPromptSuggestionsElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The suggestions. Strings, or `{ label, value }` when the displayed text and the emitted value differ. Set as a JS property. */
+  suggestions: (string | { label: string; value?: undefined | string })[];
+  /** Chip style: `'outline'` (default), `'ghost'`, or `'default'` (filled). */
+  variant?: "ghost" | "default" | "outline";
+  /** Size preset for each chip. Defaults to the pill default (`'lg'`); pass `'sm'` for smaller pills (or `'md'`). */
+  size?: "sm" | "lg" | "md" | "icon" | "icon-sm";
+  /** Full-width left-aligned rows instead of pills. */
+  block?: boolean;
+  /** Substring to highlight within each suggestion. */
+  highlight?: string;
+}
+
+export interface KitnReasoningElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The reasoning text to display. */
+  text: string;
+  /** Trigger label. */
+  label?: string;
+  /** Controlled open state — set as a property (`el.open = true`). Omit for uncontrolled (the trigger toggles it). */
+  open?: boolean;
+  /** While true, auto-expands (and re-collapses when it flips false). */
+  streaming?: boolean;
+  /** Render `text` as markdown. */
+  markdown?: boolean;
+}
+
+export interface KitnResponseStreamElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Text to stream. A string, or an `AsyncIterable<string>` (set as a JS property — async iterables can't be HTML attributes). */
+  text?: string | AsyncIterable<string>;
+  /** Reveal animation. */
+  mode?: "typewriter" | "fade";
+  /** Characters/segments per tick. */
+  speed?: number;
+  /** Element tag to render as. */
+  as?: string;
+}
+
+export interface KitnSourceElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The URL this citation links to (the domain also seeds the default label/favicon). */
+  href?: string;
+  /** Trigger label (defaults to the domain). */
+  label?: string;
+  /** Hover-card headline. Attribute: `headline` (`title` is avoided — it's a global HTML attribute that reflects in a CE constructor and breaks it). */
+  headline?: string;
+  /** Hover-card body text describing the source. */
+  description?: string;
+  /** Show the source's favicon next to the trigger label. */
+  showFavicon?: boolean;
+}
+
+export interface KitnSourceListElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The sources to render. Set as a JS property. */
+  sources: { href: string; title?: undefined | string; description?: undefined | string; label?: undefined | string; showFavicon?: undefined | boolean }[];
+  /** Show favicons on all items (per-item `showFavicon` overrides). */
+  showFavicon?: boolean;
+}
+
+export interface KitnTextShimmerElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The text to shimmer. */
+  text?: string;
+  /** Element tag to render as (default `span`). */
+  as?: string;
+  /** Animation duration in seconds. */
+  duration?: number;
+  /** Gradient spread (5–45). */
+  spread?: number;
+}
+
+export interface KitnThinkingBarElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The shimmering label, e.g. "Thinking…". */
+  text?: string;
+  /** When true, show a "stop" affordance that fires a `stop` event. */
+  stoppable?: boolean;
+  /** Label for the stop affordance. */
+  stopLabel?: string;
+}
+
+export interface KitnToolElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** The tool-call to display. Set as a JS property. */
+  tool?: { type: string; state: "input-streaming" | "input-available" | "output-available" | "output-error"; input?: Record<string, unknown>; output?: Record<string, unknown>; toolCallId?: string; errorText?: string };
+  /** Start expanded. */
+  open?: boolean;
+}
+
+export interface KitnVoiceInputElement extends HTMLElement {
+  /** Color mode (`auto` follows prefers-color-scheme). */
+  theme?: 'light' | 'dark' | 'auto';
+  /** Transcriber the host supplies — records audio, returns the text. This is a **function-valued property** (`el.transcribe = async blob => '...'`) because a value-returning callback can't be modelled as a fire-and-forget event. */
+  transcribe?: (audio: Blob) => Promise<string>;
+  /** Disable the mic button (non-interactive). */
+  disabled?: boolean;
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    'kitn-attachments': KitnAttachmentsElement;
+    'kitn-chain-of-thought': KitnChainOfThoughtElement;
+    'kitn-chat': KitnChatElement;
+    'kitn-chat-scope-picker': KitnChatScopePickerElement;
+    'kitn-chat-workspace': KitnChatWorkspaceElement;
+    'kitn-checkpoint': KitnCheckpointElement;
+    'kitn-code-block': KitnCodeBlockElement;
+    'kitn-context-meter': KitnContextMeterElement;
+    'kitn-conversation-list': KitnConversationListElement;
+    'kitn-empty': KitnEmptyElement;
+    'kitn-feedback-bar': KitnFeedbackBarElement;
+    'kitn-file-upload': KitnFileUploadElement;
+    'kitn-image': KitnImageElement;
+    'kitn-loader': KitnLoaderElement;
+    'kitn-markdown': KitnMarkdownElement;
+    'kitn-message': KitnMessageElement;
+    'kitn-message-skills': KitnMessageSkillsElement;
+    'kitn-model-switcher': KitnModelSwitcherElement;
+    'kitn-prompt-input': KitnPromptInputElement;
+    'kitn-prompt-suggestions': KitnPromptSuggestionsElement;
+    'kitn-reasoning': KitnReasoningElement;
+    'kitn-response-stream': KitnResponseStreamElement;
+    'kitn-source': KitnSourceElement;
+    'kitn-source-list': KitnSourceListElement;
+    'kitn-text-shimmer': KitnTextShimmerElement;
+    'kitn-thinking-bar': KitnThinkingBarElement;
+    'kitn-tool': KitnToolElement;
+    'kitn-voice-input': KitnVoiceInputElement;
+  }
+}

package/src/elements/empty.tsx

@@ -0,0 +1,29 @@
+import { Show } from 'solid-js';
+import { defineKitnElement } from './define';
+import { Empty, EmptyHeader, EmptyMedia, EmptyTitle, EmptyDescription, EmptyContent } from '../components/empty';
+
+interface Props extends Record<string, unknown> {
+  /** Title text. Attribute: `empty-title` (`title` is a global HTML attribute). */
+  emptyTitle?: string;
+  /** Description text. */
+  description?: string;
+}
+
+/**
+ * `<kitn-empty>` — an empty-state block. `empty-title`/`description` via
+ * attributes; slot your own icon into `slot="media"` and actions into the
+ * default slot (Route 2 slots).
+ */
+defineKitnElement<Props>('kitn-empty', {
+  emptyTitle: '',
+  description: '',
+}, (props) => (
+  <Empty>
+    <EmptyHeader>
+      <EmptyMedia variant="icon"><slot name="media" /></EmptyMedia>
+      <Show when={props.emptyTitle}><EmptyTitle>{props.emptyTitle}</EmptyTitle></Show>
+      <Show when={props.description}><EmptyDescription>{props.description}</EmptyDescription></Show>
+    </EmptyHeader>
+    <EmptyContent><slot /></EmptyContent>
+  </Empty>
+));