@kitnai/chat 0.3.0 → 0.4.0

package/src/elements/kitn-text-shimmer.stories.tsx

@@ -0,0 +1,63 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-text-shimmer': JSX.HTMLAttributes<HTMLElement> & {
+        text?: string;
+        duration?: number;
+        spread?: number;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-text-shimmer text="Thinking…" duration="3" spread="20"></kitn-text-shimmer>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-text-shimmer',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-text-shimmer>` is the framework-agnostic **web component** for animated shimmering text — a gradient sweep across a label, isolated in **Shadow DOM**.',
+          '**When to use:** signalling a quiet, in-progress state ("Thinking…", "Generating…") inline. In SolidJS, use the `TextShimmer` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text` attribute, and tune `duration` (seconds) and `spread` (gradient width, 5–45).",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** Default shimmer. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'font-size': '18px' }}>
+      <kitn-text-shimmer text="Thinking…" />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Faster sweep with a wider gradient spread. */
+export const Tuned: Story = {
+  render: () => (
+    <div style={{ padding: '24px', 'font-size': '18px' }}>
+      <kitn-text-shimmer text="Generating response…" duration={2} spread={35} />
+    </div>
+  ),
+};

package/src/elements/kitn-thinking-bar.stories.tsx

@@ -0,0 +1,72 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-thinking-bar': JSX.HTMLAttributes<HTMLElement> & {
+        text?: string;
+        stoppable?: boolean | string;
+        'stop-label'?: string;
+        'on:stop'?: (e: CustomEvent) => void;
+      };
+    }
+  }
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-thinking-bar text="Thinking" stoppable stop-label="Answer now"></kitn-thinking-bar>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  document.querySelector('kitn-thinking-bar')
+    .addEventListener('stop', () => console.log('user asked to stop'));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-thinking-bar',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-thinking-bar>` is the framework-agnostic **web component** for an animated "thinking" indicator with an optional stop affordance — a pure leaf element isolated in **Shadow DOM**. (`<kitn-chat>` does not surface this; compose it yourself.)',
+          '**When to use:** showing that the assistant is reasoning, optionally letting the user interrupt with "Answer now". In SolidJS, use the `ThinkingBar` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the `text`/`stop-label` attributes, add the `stoppable` flag to show the stop button, and listen for the `stop` **CustomEvent**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A plain thinking indicator. */
+export const Default: Story = {
+  render: () => (
+    <div style={{ padding: '24px' }}>
+      <kitn-thinking-bar text="Thinking" />
+    </div>
+  ),
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** Stoppable — shows an "Answer now" affordance that fires a `stop` event. */
+export const Stoppable: Story = {
+  render: () => (
+    <div style={{ padding: '24px' }}>
+      <kitn-thinking-bar
+        text="Reasoning"
+        stoppable
+        stop-label="Answer now"
+        on:stop={() => console.log('stop')}
+      />
+    </div>
+  ),
+};

package/src/elements/kitn-tool.stories.tsx

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+import type { ToolPart } from '../components/tool';
+
+// 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 {
+      'kitn-tool': JSX.HTMLAttributes<HTMLElement>;
+    }
+  }
+}
+
+const completedTool: ToolPart = {
+  type: 'database_query',
+  state: 'output-available',
+  input: { table: 'users', limit: 10 },
+  output: { rows: 10, ms: 42 },
+};
+
+const runningTool: ToolPart = {
+  type: 'search',
+  state: 'input-available',
+  input: { query: 'kitn docs' },
+};
+
+/** Render the actual `<kitn-tool>` custom element with a `tool` property. */
+function ToolElement(props: { tool: ToolPart; open?: boolean }) {
+  let el: (HTMLElement & { tool?: ToolPart; open?: boolean }) | undefined;
+  onMount(() => {
+    if (el) {
+      el.tool = props.tool;
+      if (props.open) el.open = true;
+    }
+  });
+  return (
+    <kitn-tool ref={(e) => (el = e as HTMLElement)} style={{ display: 'block', padding: '16px', 'max-width': '720px' }} />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-tool id="tool" open></kitn-tool>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const tool = document.getElementById('tool');
+  tool.tool = {
+    type: 'database_query',
+    state: 'output-available',
+    input: { table: 'users', limit: 10 },
+    output: { rows: 10, ms: 42 },
+  };
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-tool',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-tool>` is the framework-agnostic **web component** for a single tool-call panel — a collapsible input/output inspector with a state badge — isolated in **Shadow DOM**.',
+          '**When to use:** rendering an agent/tool-call trace in a non-Solid app. In SolidJS, use the `Tool` primitive directly.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, set the call via the `tool` **property** (`el.tool = {...}`), and add the `open` flag to start it expanded.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A completed call with input and output, started expanded. */
+export const Completed: Story = {
+  render: () => <ToolElement tool={completedTool} open />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A call still awaiting output (collapsed). */
+export const Running: Story = {
+  render: () => <ToolElement tool={runningTool} />,
+};

package/src/elements/kitn-voice-input.stories.tsx

@@ -0,0 +1,87 @@
+import type { Meta, StoryObj } from 'storybook-solidjs-vite';
+import { onMount } from 'solid-js';
+import './register'; // side effect: registers the custom elements
+
+// 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 {
+      'kitn-voice-input': JSX.HTMLAttributes<HTMLElement> & {
+        disabled?: boolean | string;
+      };
+    }
+  }
+}
+
+/** Render `<kitn-voice-input>` with a stub `transcribe` function-property. */
+function VoiceElement(props: { disabled?: boolean }) {
+  let el: (HTMLElement & { transcribe?: (audio: Blob) => Promise<string> }) | undefined;
+  onMount(() => {
+    if (!el) return;
+    // transcribe MUST be set as a JS property — a value-returning callback
+    // can't be modelled as an attribute.
+    el.transcribe = async () => {
+      await new Promise((r) => setTimeout(r, 400));
+      return 'transcribed text';
+    };
+    el.addEventListener('transcription', (e) => {
+      const ev = e as CustomEvent<{ text: string }>;
+      console.log('transcription', ev.detail.text);
+    });
+  });
+  return (
+    <kitn-voice-input
+      ref={(e) => (el = e as HTMLElement)}
+      disabled={props.disabled ? true : undefined}
+      style={{ display: 'inline-block', padding: '40px' }}
+    />
+  );
+}
+
+const HTML_SNIPPET = `<!-- Works in any framework or plain HTML -->
+<kitn-voice-input id="voice"></kitn-voice-input>
+
+<script type="module">
+  import '@kitnai/chat/elements';   // registers the custom elements
+
+  const voice = document.getElementById('voice');
+  // transcribe is a FUNCTION property — your async transcriber
+  voice.transcribe = async (blob) => {
+    const text = await myTranscriptionApi(blob);
+    return text;
+  };
+  voice.addEventListener('transcription', (e) => console.log(e.detail.text));
+</script>`;
+
+const meta = {
+  title: 'Web Components/kitn-voice-input',
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'fullscreen',
+    docs: {
+      description: {
+        component: [
+          '`<kitn-voice-input>` is the framework-agnostic **web component** for a mic button that records and transcribes audio — isolated in **Shadow DOM**. It is the canonical **function-property** element.',
+          '**When to use:** adding voice dictation to an input in a non-Solid app. In SolidJS, use the `VoiceInput` primitive.',
+          "**How to use:** register once with `import '@kitnai/chat/elements'`, then set the `transcribe` **function property** (`el.transcribe = async blob => '...'`) — a value-returning callback can't be modelled as an event. It also emits `audiocaptured` (raw blob) and `transcription` (text) **CustomEvents**.",
+          'See the **Code** tab for HTML usage.',
+        ].join('\n\n'),
+      },
+    },
+  },
+} satisfies Meta;
+
+export default meta;
+type Story = StoryObj;
+
+/** A working mic button wired to a stub transcriber. */
+export const Default: Story = {
+  render: () => <VoiceElement />,
+  parameters: { docs: { source: { code: HTML_SNIPPET, language: 'html' } } },
+};
+
+/** A disabled mic button (non-interactive). */
+export const Disabled: Story = {
+  render: () => <VoiceElement disabled />,
+};

package/src/elements/loader.tsx

@@ -0,0 +1,25 @@
+import { defineKitnElement } from './define';
+import { Loader, type LoaderVariant, type LoaderSize } from '../components/loader';
+
+interface Props extends Record<string, unknown> {
+  /** The animation style: `'circular' | 'classic' | 'pulse' | 'pulse-dot' |
+   *  'dots' | 'typing' | 'wave' | 'bars' | 'terminal' | 'text-blink' |
+   *  'text-shimmer' | 'loading-dots'`. Defaults to `'circular'`. */
+  variant?: LoaderVariant;
+  /** Loader size: `'sm' | 'md' | 'lg'`. Defaults to `'md'`. */
+  size?: LoaderSize;
+  /** Label for the text-based variants. */
+  text?: string;
+}
+
+/**
+ * `<kitn-loader>` — an animated loader. `variant` selects the style (circular,
+ * dots, wave, text-shimmer, …); `size` and `text` are attributes.
+ */
+defineKitnElement<Props>('kitn-loader', {
+  variant: 'circular',
+  size: 'md',
+  text: undefined,
+}, (props) => (
+  <Loader variant={props.variant} size={props.size} text={props.text} />
+));

package/src/elements/markdown.tsx

@@ -0,0 +1,38 @@
+import { defineKitnElement } from './define';
+import { Markdown } from '../components/markdown';
+import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
+
+interface Props extends Record<string, unknown> {
+  /** The markdown source to render. */
+  content: string;
+  /** Text/markdown sizing. */
+  proseSize?: ProseSize;
+  /** Shiki theme for fenced code blocks. */
+  codeTheme?: string;
+  /** Disable syntax highlighting (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+/**
+ * `<kitn-markdown>` — renders markdown (with fenced-code syntax highlighting) as
+ * a standalone element. Content via the `content` property; sizing/highlighting
+ * via attributes.
+ */
+defineKitnElement<Props>('kitn-markdown', {
+  content: '',
+  proseSize: 'sm',
+  codeTheme: 'github-dark-dimmed',
+  codeHighlight: true,
+}, (props, { flag }) => {
+  const outer = useChatConfig();
+  return (
+    <ChatConfig
+      proseSize={props.proseSize}
+      codeTheme={props.codeTheme}
+      codeHighlight={flag('codeHighlight')}
+      portalMount={outer.portalMount()}
+    >
+      <Markdown content={props.content} />
+    </ChatConfig>
+  );
+});

package/src/elements/message-skills.tsx

@@ -0,0 +1,22 @@
+import { defineKitnElement } from './define';
+import { MessageSkills } from '../components/message-skills';
+
+interface Skill {
+  /** Stable identifier for the skill. */
+  id: string;
+  /** Human-readable skill name shown on the badge. */
+  name: string;
+}
+
+interface Props extends Record<string, unknown> {
+  /** The active skills to badge. Set as a JS property. */
+  skills: Skill[];
+}
+
+/**
+ * `<kitn-message-skills>` — badges showing which skills were active for a
+ * message. Data via the `skills` property.
+ */
+defineKitnElement<Props>('kitn-message-skills', {
+  skills: [],
+}, (props) => <MessageSkills skills={props.skills} />);

package/src/elements/message.tsx

@@ -0,0 +1,125 @@
+import { For, Show, type Component } from 'solid-js';
+import { defineKitnElement } from './define';
+import { ChatConfig, useChatConfig, type ProseSize } from '../primitives/chat-config';
+import { Message, MessageContent, MessageActions } from '../components/message';
+import { Reasoning, ReasoningTrigger, ReasoningContent } from '../components/reasoning';
+import { Tool } from '../components/tool';
+import { Attachments, Attachment, AttachmentPreview, AttachmentInfo } from '../components/attachments';
+import { Button } from '../ui/button';
+import { Copy, ThumbsUp, ThumbsDown, RefreshCw, Pencil } from 'lucide-solid';
+import type { ChatMessage, ChatMessageAction } from './chat-types';
+
+interface Props extends Record<string, unknown> {
+  /** The full message object. Set as a JS property. */
+  message?: ChatMessage;
+  /** 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?: ProseSize;
+  /** Shiki theme name used for fenced code blocks in the content. */
+  codeTheme?: string;
+  /** Disable syntax highlighting for code blocks (no Shiki loads). */
+  codeHighlight?: boolean;
+}
+
+/** Events fired by `<kitn-message>`. */
+interface Events {
+  /** An action button was clicked. */
+  messageaction: { messageId: string; action: ChatMessageAction };
+}
+
+const ACTION_LABEL: Record<ChatMessageAction, string> = {
+  copy: 'Copy', like: 'Like', dislike: 'Dislike', regenerate: 'Regenerate', edit: 'Edit',
+};
+const ACTION_ICON: Record<ChatMessageAction, Component<{ class?: string }>> = {
+  copy: Copy, like: ThumbsUp, dislike: ThumbsDown, regenerate: RefreshCw, edit: Pencil,
+};
+
+/**
+ * `<kitn-message>` — a single message row: markdown/plain content, reasoning,
+ * tool calls, attachments, and action buttons, rendered from one `message`
+ * object (the same shape `<kitn-chat>` uses per message). The keystone of the
+ * "compose your own message list" pattern. Emits `messageaction`.
+ */
+defineKitnElement<Props, Events>('kitn-message', {
+  message: undefined,
+  role: 'assistant',
+  content: undefined,
+  markdown: undefined,
+  proseSize: 'sm',
+  codeTheme: 'github-dark-dimmed',
+  codeHighlight: true,
+}, (props, { dispatch, flag, element }) => {
+  const outer = useChatConfig();
+  const msg = (): ChatMessage =>
+    props.message ?? { id: 'message', role: props.role ?? 'assistant', content: props.content ?? '' };
+  const isUser = () => msg().role === 'user';
+  // markdown: explicit prop/attribute wins; otherwise default by role.
+  const markdownExplicit = () =>
+    element.hasAttribute('markdown') || props.markdown === true || props.markdown === false;
+  const useMarkdown = () => (markdownExplicit() ? flag('markdown') : !isUser());
+
+  return (
+    <ChatConfig
+      proseSize={props.proseSize}
+      codeTheme={props.codeTheme}
+      codeHighlight={flag('codeHighlight')}
+      portalMount={outer.portalMount()}
+    >
+      <Message class={isUser() ? 'flex-col items-end' : 'flex-col items-start'}>
+        <Show when={msg().reasoning}>
+          <Reasoning class="mb-2 w-full">
+            <ReasoningTrigger>{msg().reasoning!.label ?? 'Reasoning'}</ReasoningTrigger>
+            <ReasoningContent markdown>{msg().reasoning!.text}</ReasoningContent>
+          </Reasoning>
+        </Show>
+        <For each={msg().tools ?? []}>
+          {(tp) => <Tool toolPart={tp} class="mb-2 w-full" />}
+        </For>
+        <Show when={msg().attachments?.length}>
+          <Attachments variant="inline" class={isUser() ? 'mb-2 justify-end' : 'mb-2'}>
+            <For each={msg().attachments!}>
+              {(att) => (
+                <Attachment data={att}>
+                  <AttachmentPreview />
+                  <AttachmentInfo />
+                </Attachment>
+              )}
+            </For>
+          </Attachments>
+        </Show>
+        <MessageContent
+          markdown={useMarkdown()}
+          class={isUser()
+            ? 'bg-muted text-primary max-w-[85%] rounded-2xl px-4 py-2'
+            : 'bg-transparent p-0'}
+        >
+          {msg().content}
+        </MessageContent>
+        <Show when={msg().actions?.length}>
+          <MessageActions class="mt-1 flex gap-0">
+            <For each={msg().actions!}>
+              {(a) => (
+                <Button
+                  variant="ghost" size="icon-sm" class="rounded-full"
+                  data-action={a}
+                  aria-label={ACTION_LABEL[a]}
+                  onClick={() => dispatch('messageaction', { messageId: msg().id, action: a })}
+                >
+                  {(() => {
+                    const Icon = ACTION_ICON[a];
+                    return <Icon class="size-3.5" />;
+                  })()}
+                </Button>
+              )}
+            </For>
+          </MessageActions>
+        </Show>
+      </Message>
+    </ChatConfig>
+  );
+});

package/src/elements/model-switcher.tsx

@@ -0,0 +1,35 @@
+import { defineKitnElement } from './define';
+import { ModelSwitcher } from '../components/model-switcher';
+import type { ModelOption } from '../types';
+
+interface Props extends Record<string, unknown> {
+  /** The selectable models. Set as a JS property (array). */
+  models: ModelOption[];
+  /** The currently-selected model id. Defaults to the first model. */
+  currentModel?: string;
+}
+
+/** Events fired by `<kitn-model-switcher>`. */
+interface Events {
+  /** A model was selected. */
+  modelchange: { modelId: string };
+}
+
+/**
+ * `<kitn-model-switcher>` — an event-emitting leaf element. Data in via the
+ * `models` property, selection out via a `modelchange` event. Mirrors the
+ * header switcher inside `<kitn-chat>` as a standalone, composable piece.
+ *
+ * Note: like the underlying primitive, this only renders when more than one
+ * model is provided.
+ */
+defineKitnElement<Props, Events>('kitn-model-switcher', {
+  models: [],
+  currentModel: undefined,
+}, (props, { dispatch }) => (
+  <ModelSwitcher
+    models={props.models}
+    currentModelId={props.currentModel ?? props.models[0]?.id ?? ''}
+    onModelChange={(modelId) => dispatch('modelchange', { modelId })}
+  />
+));