@aleph-alpha/chat-kit 5.7.0 → 5.9.0

package/src/components/composed/CkConversation/CkConversation.stories.ts

@@ -9,7 +9,7 @@ import type {
 } from '../../../types';
 import CkConversation from './CkConversation.vue';
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
-import { ref } from 'vue';
+import { h, ref, type VNode } from 'vue';
 
 const now = new Date();
 
@@ -455,6 +455,17 @@ const customClasses = {
   />
 </template>`;
 
+const defaultCodeBlockTemplateSource = `<script setup lang="ts">
+import { CkConversation } from '@aleph-alpha/chat-kit';
+import type { BaseMessage } from '@aleph-alpha/chat-kit';
+
+const messages: BaseMessage[] = [/* ... */];
+</script>
+
+<template>
+  <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;" />
+</template>`;
+
 const withCustomCodeBlockTemplateSource = `<script setup lang="ts">
 import { CkConversation } from '@aleph-alpha/chat-kit';
 import type { BaseMessage } from '@aleph-alpha/chat-kit';
@@ -481,6 +492,60 @@ import { CkConversation } from '@aleph-alpha/chat-kit';
   <CkConversation :messages="[]" style="height: 100%;" />
 </template>`;
 
+const scrollToMessageTemplateSource = `<script setup lang="ts">
+import { CkConversation } from '@aleph-alpha/chat-kit';
+import type { BaseMessage } from '@aleph-alpha/chat-kit';
+import { ref, useTemplateRef } from 'vue';
+
+const messages: BaseMessage[] = [/* ... */];
+
+const conversation = useTemplateRef('conversation');
+const index = ref(0);
+
+function scrollToMessage(): void {
+  // Zero-based index among all rows; omit the argument to scroll to the last.
+  conversation.value?.scrollToMessage(index.value);
+}
+</script>
+
+<template>
+  <div class="flex h-[400px] flex-col">
+    <div class="flex items-center gap-2 border-b p-2">
+      <label for="msg-index">Message index</label>
+      <input id="msg-index" v-model.number="index" type="number" min="0" />
+      <button @click="scrollToMessage">Scroll to message</button>
+    </div>
+    <CkConversation
+      ref="conversation"
+      :messages="messages"
+      agent-avatar-fallback="AI"
+      class="min-h-0 flex-1"
+    />
+  </div>
+<template>`;
+
+const slotAnatomyTemplateSource = `<script setup lang="ts">
+import { CkConversation } from '@aleph-alpha/chat-kit';
+import type { BaseMessage } from '@aleph-alpha/chat-kit';
+
+const messages: BaseMessage[] = [/* ... */];
+</script>
+
+<template>
+  <!--
+    Each slot has a default rendering. Overriding a parent slot replaces
+    everything nested beneath it, so the child slots below it no longer apply.
+    The anatomy story visualizes this "folding" relationship.
+  -->
+  <CkConversation :messages="messages">
+    <!-- Replaces the whole agent row: the header / content / footer slots
+         nested under it are no longer rendered. -->
+    <template #agent-message="{ message }">
+      <MyAgentBubble :message="message" />
+    </template>
+  </CkConversation>
+</template>`;
+
 /**
  * Drop-in conversation UI. Pass `messages` with `role`, `content` (a list of
  * text / tool / reasoning parts), and `status` fields and CkConversation
@@ -506,6 +571,167 @@ export const Default: Story = {
   parameters: { docs: { source: { code: defaultTemplateSource } } },
 };
 
+/**
+ * A slot to which the consumer can pass content, describing what its default
+ * rendering is and which nested slots it supersedes when overridden.
+ */
+interface SlotDoc {
+  /** Slot name as used in `<template #name>`. */
+  name: string;
+  /** What overriding this slot replaces. */
+  summary: string;
+  /** Slots that live inside this one's default rendering. */
+  children?: SlotDoc[];
+}
+
+/**
+ * The slot hierarchy of `CkConversation`. Nesting mirrors the component's
+ * template: a child slot only renders as part of its parent's *default*
+ * rendering, so overriding a parent slot removes every child beneath it.
+ */
+const slotTree: SlotDoc[] = [
+  {
+    name: 'user-message',
+    summary: 'Replaces the entire user row.',
+    children: [
+      {
+        name: 'user-message-content',
+        summary: 'The content inside the default CkUserMessage bubble.',
+      },
+    ],
+  },
+  {
+    name: 'agent-message',
+    summary: 'Replaces the entire agent row.',
+    children: [
+      {
+        name: 'agent-message-header',
+        summary: 'Replaces the whole CkAgentMessageHeader.',
+        children: [
+          {
+            name: 'agent-message-icon',
+            summary: 'The avatar shown for a completed message.',
+          },
+          {
+            name: 'agent-message-loading-icon',
+            summary: 'The avatar shown while the message is being generated.',
+          },
+          {
+            name: 'agent-message-header-content',
+            summary: 'The header text (e.g. a reasoning trail).',
+          },
+          {
+            name: 'agent-message-header-activity',
+            summary: 'An activity control on the right of the header.',
+          },
+        ],
+      },
+      {
+        name: 'agent-message-content',
+        summary: 'Replaces the message body (the CkMarkdownRenderer).',
+        children: [
+          {
+            name: 'agent-message-code-block',
+            summary: 'Code blocks rendered inside the default markdown.',
+          },
+        ],
+      },
+      {
+        name: 'agent-message-footer',
+        summary: 'Footer actions (a copy button by default).',
+      },
+    ],
+  },
+  {
+    name: 'thread-footer',
+    summary: 'Trailing content appended after the last message.',
+  },
+];
+
+const slotPillStyle =
+  'font-family: monospace; font-size: 12px; background: #eef1fb; color: #33408a; ' +
+  'padding: 2px 6px; border-radius: 4px; white-space: nowrap;';
+const slotSummaryTextStyle = 'color: #666; font-size: 13px;';
+
+/** Recursively render a slot node as a foldable `<details>` tree. */
+function renderSlotNode(node: SlotDoc): VNode {
+  const children = node.children ?? [];
+  const label = h(
+    'span',
+    {
+      style:
+        'display: inline-flex; align-items: baseline; gap: 8px; flex-wrap: wrap;',
+    },
+    [
+      h('code', { style: slotPillStyle }, node.name),
+      h('span', { style: slotSummaryTextStyle }, node.summary),
+    ],
+  );
+
+  if (children.length === 0) {
+    return h('div', { style: 'padding: 6px 0 6px 20px;' }, [label]);
+  }
+
+  return h(
+    'details',
+    {
+      open: true,
+      style: 'padding: 6px 0;',
+    },
+    [
+      h('summary', { style: 'cursor: pointer; padding: 2px 0;' }, [label]),
+      h(
+        'div',
+        {
+          style:
+            'margin: 4px 0 0 8px; padding-left: 12px; border-left: 1px solid #e0e0e0;',
+        },
+        children.map(renderSlotNode),
+      ),
+    ],
+  );
+}
+
+/**
+ * A diagram of how CkConversation's slots nest. Every slot has a default
+ * rendering; overriding a parent slot replaces everything nested beneath it,
+ * so the child slots below it no longer apply. Collapse a node to see which
+ * slots "fold away" when you take over its parent.
+ */
+export const SlotAnatomy: Story = {
+  // Emoji prefix marks this out in the sidebar as a reference diagram rather
+  // than a rendered component example.
+  name: '🧩 Slot Anatomy',
+  render: () => ({
+    setup() {
+      return () =>
+        h(
+          'div',
+          {
+            // Fill and scroll within the meta decorator's fixed-height frame
+            // instead of being clipped by its `overflow: hidden`.
+            style:
+              'font-family: system-ui, sans-serif; padding: 16px; line-height: 1.5; ' +
+              'height: 100%; overflow-y: auto; box-sizing: border-box;',
+          },
+          [
+            h(
+              'p',
+              { style: 'margin: 0 0 12px; color: #444; font-size: 13px;' },
+              'Every slot has a default rendering. Overriding a parent slot ' +
+                'replaces everything nested beneath it — the child slots below ' +
+                'it no longer apply. Collapse a node to see which slots fold away.',
+            ),
+            ...slotTree.map(renderSlotNode),
+          ],
+        );
+    },
+  }),
+  parameters: {
+    docs: { source: { code: slotAnatomyTemplateSource } },
+  },
+};
+
 /**
  * Uses a remote avatar image (with fallback text). Use when you want a
  * branded agent identity in each reply.
@@ -826,9 +1052,61 @@ export const WithCustomMarkdownClasses: Story = {
 };
 
 /**
- * Integrates a custom code-block renderer (Shiki, Prism, etc.) via
- * `#agent-message-code-block`. Use when you want syntax highlighting or
- * inline copy buttons for assistant code.
+ * Fenced code blocks in agent markdown render with `UiCodeBlock` out of the
+ * box — syntax highlighting, a language label, and a copy button — without any
+ * slot wiring.
+ */
+export const DefaultCodeBlock: Story = {
+  render: () => ({
+    components: { CkConversation },
+    setup() {
+      const messages: BaseMessage[] = [
+        {
+          id: '1',
+          role: 'user',
+          content: [text('Show me a code example')],
+          createdAt: now,
+          status: 'completed',
+        },
+        {
+          id: '2',
+          role: 'assistant',
+          content: [
+            text(
+              [
+                'Here is an example:',
+                '',
+                '```typescript',
+                'const greeting = "Hello, world!";',
+                'console.log(greeting);',
+                '```',
+                '',
+                'And another one:',
+                '',
+                '```python',
+                'def greet(name: str) -> str:',
+                '    return f"Hello, {name}!"',
+                '```',
+              ].join('\n'),
+            ),
+          ],
+          createdAt: now,
+          status: 'completed',
+        },
+      ];
+      return { messages };
+    },
+    template: `
+      <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;" />
+    `,
+  }),
+  parameters: { docs: { source: { code: defaultCodeBlockTemplateSource } } },
+};
+
+/**
+ * Fenced code blocks render with `UiCodeBlock` (syntax highlighting + copy
+ * button) by default. Override that with a custom renderer (Prism, a bespoke
+ * theme, etc.) via `#agent-message-code-block`, as shown here.
  */
 export const WithCustomCodeBlock: Story = {
   render: () => ({
@@ -884,6 +1162,52 @@ export const WithCustomCodeBlock: Story = {
   parameters: { docs: { source: { code: withCustomCodeBlockTemplateSource } } },
 };
 
+/**
+ * Programmatic navigation via the exposed `scrollToMessage(index)` method. Enter
+ * a zero-based row index and the conversation scrolls that message to the top.
+ * Index counts all rows regardless of role (a `thread-footer`, when present, is
+ * the trailing row); omitting the index scrolls to the last row.
+ */
+export const ScrollToMessage: Story = {
+  render: () => ({
+    components: { CkConversation },
+    setup() {
+      const messages: BaseMessage[] = Array.from({ length: 10 }, (_, i) => ({
+        id: `m-${i}`,
+        role: i % 2 === 0 ? 'user' : 'assistant',
+        content: [
+          text(
+            `[${i}] ${
+              i % 2 === 0 ? 'User' : 'Agent'
+            } message number ${i}. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore.`,
+          ),
+        ],
+        createdAt: now,
+        status: 'completed',
+      }));
+      const conversation = ref();
+      const index = ref(0);
+      function scrollToMessage() {
+        conversation.value?.scrollToMessage(index.value);
+      }
+      return { messages, conversation, index, scrollToMessage };
+    },
+    template: `
+      <div style="display: flex; flex-direction: column; height: 100%;">
+        <div style="display: flex; align-items: center; gap: 8px; padding: 8px; border-bottom: 1px solid #e0e0e0;">
+          <label for="msg-index">Message index</label>
+          <input id="msg-index" v-model.number="index" type="number" min="0" style="width: 72px; padding: 4px 8px; border: 1px solid #ccc; border-radius: 6px;" />
+          <button @click="scrollToMessage" style="padding: 6px 16px; border-radius: 6px; background: #333; color: white; cursor: pointer;">
+            Scroll to message
+          </button>
+        </div>
+        <CkConversation ref="conversation" :messages="messages" agent-avatar-fallback="AI" style="flex: 1; min-height: 0;" />
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: scrollToMessageTemplateSource } } },
+};
+
 /**
  * Empty state — an initial view before the first turn. Use to show a welcome
  * screen, quick prompts, or onboarding content above this surface.

package/src/components/composed/CkConversation/CkConversation.vue

@@ -12,9 +12,17 @@ import {
   UiAvatar,
   UiAvatarFallback,
   UiAvatarImage,
+  UiCodeBlock,
   UiSpinner,
 } from '@aleph-alpha/ui-library';
-import { Comment, Fragment, Text, computed, type VNode } from 'vue';
+import {
+  Comment,
+  Fragment,
+  Text,
+  computed,
+  useTemplateRef,
+  type VNode,
+} from 'vue';
 
 defineOptions({ name: 'CkConversation' });
 
@@ -53,7 +61,11 @@ const slots = defineSlots<{
   'agent-message-content': (props: { message: BaseMessage }) => void;
   /** Provide footer actions for the agent message */
   'agent-message-footer': (props: { message: BaseMessage }) => void;
-  /** Replace the default code block rendering inside agent markdown */
+  /**
+   * Replace the default code block rendering inside agent markdown. When not
+   * provided, fenced code blocks render with `UiCodeBlock` (syntax highlighting
+   * + copy button).
+   */
   'agent-message-code-block': (props: {
     code: string;
     language: string;
@@ -122,10 +134,26 @@ function hasHeaderActivity(message: BaseMessage): boolean {
     | undefined;
   return slot ? slot({ message }).some((vnode) => !isVNodeEmpty(vnode)) : false;
 }
+
+const layoutRef = useTemplateRef('layoutRef');
+
+/**
+ * Scroll so the message at `index` sits at the top of the viewport. `index` is
+ * the zero-based position among the rendered rows (any `thread-footer` counts
+ * as the trailing row); when omitted it scrolls to the last row.
+ *
+ * This only performs the scroll — it does not focus the message. Any
+ * accompanying focus handling must be done separately by the caller.
+ */
+function scrollToMessage(index?: number): void {
+  layoutRef.value?.scrollToMessage(index);
+}
+
+defineExpose({ scrollToMessage });
 </script>
 
 <template>
-  <CkConversationLayout :messages="messages">
+  <CkConversationLayout ref="layoutRef" :messages="messages">
     <template #user-message="{ message }">
       <div :class="{ 'ml-8': hasIcon }">
         <slot name="user-message" :message="message">
@@ -213,11 +241,13 @@ function hasHeaderActivity(message: BaseMessage): boolean {
               :content="getMessageText(message)"
               :classes="agentMarkdownClasses"
             >
-              <template
-                v-if="$slots['agent-message-code-block']"
-                #code-block="codeBlockProps"
-              >
-                <slot name="agent-message-code-block" v-bind="codeBlockProps" />
+              <template #code-block="codeBlockProps">
+                <slot name="agent-message-code-block" v-bind="codeBlockProps">
+                  <UiCodeBlock
+                    :code="codeBlockProps.code"
+                    :language="codeBlockProps.language || 'text'"
+                  />
+                </slot>
               </template>
             </CkMarkdownRenderer>
           </slot>