@aleph-alpha/chat-kit 5.8.0 → 5.9.0

package/src/components/base/CkConversationLayout/CkConversationLayout.vue

@@ -125,34 +125,66 @@ function updateSpacerHeight(): void {
   const lastUserTop = lastUserRow.offsetTop;
   const lastRowBottom = lastRow.offsetTop + lastRow.offsetHeight;
   const contentFromUserToEnd = lastRowBottom - lastUserTop;
-  const gap = parseFloat(getComputedStyle(container).rowGap) || 0;
+  // The last user message carries a top margin (mt-3xl for non-first rows) that
+  // is scrolled into view above it, so it consumes viewport height just like the
+  // content does. Account for it here instead of the removed row gap.
+  const topMargin = parseFloat(getComputedStyle(lastUserRow).marginTop) || 0;
 
   spacerHeight.value = Math.max(
     0,
-    containerHeight.value - contentFromUserToEnd - gap,
+    containerHeight.value - contentFromUserToEnd - topMargin,
   );
 }
 
 /**
- * Scroll so the last user message is at the top of the viewport.
- * The bottom spacer ensures enough scroll room.
+ * Scroll so the message at `index` is at the top of the viewport, keeping its
+ * top margin in view. `index` is the zero-based position among the rendered
+ * rows — regardless of role, and with the `thread-footer` (when present)
+ * counting as the trailing row. When omitted it targets the last row.
+ *
+ * If there isn't a full viewport of content below the target, a bottom spacer
+ * is added so it can still reach the top, and auto-scroll resumes so streamed
+ * content keeps following — the newest-turn behaviour. Navigating to an earlier
+ * message (enough content already below it) adds no spacer and stops following.
+ *
+ * This only performs the scroll — it does not focus the message. Any
+ * accompanying focus handling must be done separately by the caller.
  */
-function scrollUserMessageToTop(): void {
+function scrollMessageToTop(index?: number): void {
   const container = scrollContainerRef.value;
   if (!container) return;
 
-  hasBottomSpacer.value = true;
-  spacerHeight.value = containerHeight.value;
+  const rows = container.querySelectorAll<HTMLElement>('[data-message-row]');
+  if (rows.length === 0) return;
+
+  const targetIndex = index ?? rows.length - 1;
+  const targetRow = rows[targetIndex];
+  if (!targetRow) return;
+
+  // Scroll to just above the row so its top margin stays in view.
+  const topMargin = parseFloat(getComputedStyle(targetRow).marginTop) || 0;
+  const targetTop = targetRow.offsetTop - topMargin;
+
+  const lastRow = rows[rows.length - 1];
+  const contentBottom = lastRow.offsetTop + lastRow.offsetHeight;
+  const contentBelowTarget = contentBottom - targetTop;
+  const needsSpacer = contentBelowTarget < containerHeight.value;
+
+  // Size the spacer so the target lands exactly at the top; skip it when there
+  // is already enough content below (avoids a trailing empty gap). Clear any
+  // spacer left over from a previous near-end navigation so it doesn't leave a
+  // gap at the bottom.
+  if (needsSpacer) {
+    hasBottomSpacer.value = true;
+    spacerHeight.value = containerHeight.value - contentBelowTarget;
+  } else {
+    hasBottomSpacer.value = false;
+    spacerHeight.value = 0;
+  }
 
   nextTick(() => {
-    const userRows = container.querySelectorAll<HTMLElement>(
-      '[data-message-row="user"]',
-    );
-    const lastUserRow = userRows[userRows.length - 1];
-    if (lastUserRow) {
-      lastUserRow.scrollIntoView({ behavior: 'smooth', block: 'start' });
-    }
-    isAutoScrollEnabled.value = true;
+    container.scrollTo({ top: targetTop, behavior: 'smooth' });
+    isAutoScrollEnabled.value = needsSpacer;
   });
 }
 
@@ -177,7 +209,9 @@ function scrollToEndOfContent(): void {
   }
 }
 
-// When a new user message is added, scroll it to the top of the viewport
+// When a new user message is added, scroll it to the top of the viewport.
+// Its row index matches its position in `messages` (any `thread-footer` is
+// appended after, so it never shifts earlier rows).
 watch(
   () => props.messages.length,
   (newLen, oldLen) => {
@@ -185,7 +219,7 @@ watch(
     const lastMessage = props.messages[newLen - 1];
     if (lastMessage?.role === 'user') {
       nextTick(() => {
-        scrollUserMessageToTop();
+        scrollMessageToTop(newLen - 1);
         updateFades();
       });
     }
@@ -198,8 +232,8 @@ watch(
 // The trailing content can also be the `thread-footer` slot (e.g. streaming
 // preference-comparison lanes), which continues the thread after a trunk whose
 // last message is the shared *user* prompt. That case must run the same
-// spacer-shrink/follow pass — otherwise the full-viewport spacer set by
-// `scrollUserMessageToTop` is never reduced, leaving a viewport-sized gap that
+// spacer-shrink/follow pass — otherwise the bottom spacer set by
+// `scrollMessageToTop` is never reduced, leaving a viewport-sized gap that
 // pushes the prompt and answers out of view. `updateSpacerHeight` already
 // measures the footer (it carries `data-message-row="agent"`, so it is the
 // `lastRow`); it just needs to be invoked here. The watch fires on every tree
@@ -222,6 +256,8 @@ watch(
   },
   { deep: true },
 );
+
+defineExpose({ scrollToMessage: scrollMessageToTop });
 </script>
 
 <template>
@@ -234,14 +270,15 @@ watch(
     />
     <div
       ref="scrollContainerRef"
-      class="relative flex min-h-0 flex-1 flex-col gap-8 overflow-y-auto"
+      class="relative flex min-h-0 flex-1 flex-col overflow-y-auto"
       @scroll="handleScroll"
     >
       <div
-        v-for="message in messages"
+        v-for="(message, index) in messages"
         :key="message.id"
         :data-message-row="message.role"
         class="min-w-0"
+        :class="index === 0 ? 'mt-2xl' : 'mt-3xl'"
       >
         <div v-if="message.role === 'user'" class="flex min-w-0 justify-end">
           <slot name="user-message" :message="message" />
@@ -256,6 +293,7 @@ watch(
         v-if="$slots['thread-footer']"
         data-message-row="agent"
         class="flex min-w-0 justify-start"
+        :class="messages.length === 0 ? 'mt-2xl' : 'mt-3xl'"
       >
         <slot name="thread-footer" />
       </div>

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

@@ -2,7 +2,16 @@ import type { BaseMessage, MessageContent } from '../../../types';
 import CkConversation from './CkConversation.vue';
 import { defaultMarkdownClasses } from '../../base/CkMarkdownRenderer/defaultMarkdownClasses';
 import { render, screen } from '@testing-library/vue';
-import { createCommentVNode, h } from 'vue';
+import {
+  createCommentVNode,
+  defineComponent,
+  h,
+  nextTick,
+  onMounted,
+  ref,
+} from 'vue';
+
+type ConversationInstance = { scrollToMessage: (index?: number) => void };
 
 const now = new Date();
 
@@ -649,16 +658,98 @@ describe('CkConversation', () => {
       expect(container.querySelector('pre > code')).toBeNull();
     });
 
-    it('renders default code block when agent-message-code-block slot is not provided', () => {
+    it('renders a UiCodeBlock by default when agent-message-code-block slot is not provided', () => {
+      const markdown = '```javascript\nconsole.log("hi");\n```';
+
+      const { container } = render(CkConversation, {
+        props: { messages: [agentMessage({ text: markdown })] },
+      });
+
+      // The default renderer is now UiCodeBlock, not a bare `pre > code`.
+      const codeBlock = container.querySelector('.ui-code-block');
+      expect(codeBlock).not.toBeNull();
+      expect(codeBlock?.textContent).toContain('console.log("hi");');
+    });
+
+    it('passes the fenced language through to the default UiCodeBlock', () => {
       const markdown = '```javascript\nconsole.log("hi");\n```';
 
+      render(CkConversation, {
+        props: { messages: [agentMessage({ text: markdown })] },
+      });
+
+      // UiCodeBlock surfaces the language as its header label.
+      expect(screen.getByText('javascript')).toBeInTheDocument();
+    });
+
+    it('falls back to "text" language when the fence has no language', () => {
+      const markdown = '```\nplain code\n```';
+
       const { container } = render(CkConversation, {
         props: { messages: [agentMessage({ text: markdown })] },
       });
 
-      const codeEl = container.querySelector('pre > code');
-      expect(codeEl).not.toBeNull();
-      expect(codeEl?.textContent).toContain('console.log("hi");');
+      const codeBlock = container.querySelector('.ui-code-block');
+      expect(codeBlock).not.toBeNull();
+      expect(codeBlock?.textContent).toContain('plain code');
+    });
+  });
+
+  describe('scrollToMessage', () => {
+    function renderWithInstance() {
+      let instance: ConversationInstance | undefined;
+
+      const Wrapper = defineComponent({
+        setup() {
+          const conversationRef = ref<ConversationInstance>();
+          onMounted(() => {
+            instance = conversationRef.value;
+          });
+          return () => h(CkConversation, { messages, ref: conversationRef });
+        },
+      });
+
+      const { container } = render(Wrapper);
+      const scrollEl = container.querySelector(
+        '[class*="overflow-y-auto"]',
+      ) as HTMLElement;
+      const scrollTo = vi.fn();
+      scrollEl.scrollTo = scrollTo;
+
+      // jsdom reports offsetTop as 0, so stub distinct positions per row.
+      container
+        .querySelectorAll<HTMLElement>('[data-message-row]')
+        .forEach((row, i) => {
+          Object.defineProperty(row, 'offsetTop', {
+            configurable: true,
+            value: (i + 1) * 100,
+          });
+        });
+
+      return { getInstance: () => instance!, scrollTo };
+    }
+
+    it('delegates to the layout and scrolls to the last message by default', async () => {
+      // Four rows (user, agent, user, agent) → last row is at offsetTop 400.
+      const { getInstance, scrollTo } = renderWithInstance();
+
+      getInstance().scrollToMessage();
+      await nextTick();
+
+      expect(scrollTo).toHaveBeenCalledWith(
+        expect.objectContaining({ top: 400, behavior: 'smooth' }),
+      );
+    });
+
+    it('scrolls to the message at the given index, regardless of role', async () => {
+      const { getInstance, scrollTo } = renderWithInstance();
+
+      getInstance().scrollToMessage(1);
+      await nextTick();
+
+      expect(scrollTo).toHaveBeenCalledWith(
+        expect.objectContaining({ top: 200, behavior: 'smooth' }),
+      );
     });
   });
 });

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.