@aleph-alpha/chat-kit 5.8.0 → 5.10.0

package/src/components/base/CkConversationLayout/CkConversationLayout.spec.ts

@@ -1,6 +1,15 @@
 import CkConversationLayout from './CkConversationLayout.vue';
 import { fireEvent, render, screen } from '@testing-library/vue';
-import { type Component, defineComponent, h } from 'vue';
+import {
+  type Component,
+  defineComponent,
+  h,
+  nextTick,
+  onMounted,
+  ref,
+} from 'vue';
+
+type LayoutInstance = { scrollToMessage: (index?: number) => void };
 
 const messages = [
   { role: 'user', content: 'Hello there' },
@@ -37,6 +46,46 @@ function renderLayout(
   return render(Wrapper);
 }
 
+/**
+ * Render the layout and capture the child component instance so the exposed
+ * `scrollToMessage` method can be invoked from the test.
+ */
+function renderWithInstance(
+  msgs: Array<{ role: string; content: string }> = messages,
+  { withFooter = false }: { withFooter?: boolean } = {},
+) {
+  let instance: LayoutInstance | undefined;
+  // eslint-disable-next-line vue/one-component-per-file
+  const Wrapper = defineComponent({
+    setup() {
+      const layoutRef = ref<LayoutInstance>();
+      onMounted(() => {
+        instance = layoutRef.value;
+      });
+      return () =>
+        h(
+          CkConversationLayout as unknown as Component,
+          { messages: msgs, ref: layoutRef },
+          {
+            'user-message': ({ message }: { message: (typeof msgs)[0] }) =>
+              h('p', { 'data-testid': 'user-msg' }, message.content),
+            'agent-message': ({ message }: { message: (typeof msgs)[0] }) =>
+              h('p', { 'data-testid': 'agent-msg' }, message.content),
+            ...(withFooter
+              ? {
+                  'thread-footer': () =>
+                    h('p', { 'data-testid': 'footer' }, 'footer'),
+                }
+              : {}),
+          },
+        );
+    },
+  });
+
+  const utils = render(Wrapper);
+  return { ...utils, getInstance: () => instance! };
+}
+
 describe('CkConversationLayout', () => {
   describe('message display', () => {
     it('displays all provided messages', () => {
@@ -127,6 +176,90 @@ describe('CkConversationLayout', () => {
     });
   });
 
+  describe('row spacing', () => {
+    it('gives the first row a smaller top margin than the following rows', () => {
+      const { container } = renderLayout();
+
+      const rows =
+        container.querySelectorAll<HTMLElement>('[data-message-row]');
+      expect(rows[0].className).toContain('mt-2xl');
+      expect(rows[0].className).not.toContain('mt-3xl');
+    });
+
+    it('gives every non-first row the larger top margin', () => {
+      const { container } = renderLayout();
+
+      const rows =
+        container.querySelectorAll<HTMLElement>('[data-message-row]');
+      for (const row of Array.from(rows).slice(1)) {
+        expect(row.className).toContain('mt-3xl');
+      }
+    });
+
+    it('does not use a flex gap for row spacing', () => {
+      const { container } = renderLayout();
+
+      const scrollEl = container.querySelector(
+        '[class*="overflow-y-auto"]',
+      ) as HTMLElement;
+      expect(scrollEl.className).not.toContain('gap-8');
+    });
+
+    it('gives the thread-footer the larger top margin when messages exist', () => {
+      // eslint-disable-next-line vue/one-component-per-file
+      const Wrapper = defineComponent({
+        setup() {
+          return () =>
+            h(
+              CkConversationLayout as unknown as Component,
+              { messages },
+              {
+                'user-message': () => h('p', 'user'),
+                'agent-message': () => h('p', 'agent'),
+                'thread-footer': () =>
+                  h('p', { 'data-testid': 'footer' }, 'footer'),
+              },
+            );
+        },
+      });
+
+      const { container } = render(Wrapper);
+
+      const footerRow = container.querySelector(
+        '[data-message-row="agent"]:last-of-type',
+      ) as HTMLElement;
+      expect(footerRow.querySelector('[data-testid="footer"]')).not.toBeNull();
+      expect(footerRow.className).toContain('mt-3xl');
+    });
+
+    it('gives the thread-footer the smaller top margin when there are no messages', () => {
+      // eslint-disable-next-line vue/one-component-per-file
+      const Wrapper = defineComponent({
+        setup() {
+          return () =>
+            h(
+              CkConversationLayout as unknown as Component,
+              { messages: [] },
+              {
+                'user-message': () => h('p', 'user'),
+                'agent-message': () => h('p', 'agent'),
+                'thread-footer': () =>
+                  h('p', { 'data-testid': 'footer' }, 'footer'),
+              },
+            );
+        },
+      });
+
+      const { container } = render(Wrapper);
+
+      const footerRow = container.querySelector(
+        '[data-message-row="agent"]',
+      ) as HTMLElement;
+      expect(footerRow.className).toContain('mt-2xl');
+      expect(footerRow.className).not.toContain('mt-3xl');
+    });
+  });
+
   describe('scroll fade indicators', () => {
     function getFadeElements(container: HTMLElement) {
       return {
@@ -209,4 +342,79 @@ describe('CkConversationLayout', () => {
       expect(bottomFade.className).toContain('opacity-0');
     });
   });
+
+  describe('scrollToMessage', () => {
+    // jsdom reports offsetTop as 0, so stub distinct positions per rendered row.
+    function stubRowOffsets(container: Element) {
+      container
+        .querySelectorAll<HTMLElement>('[data-message-row]')
+        .forEach((row, i) => {
+          Object.defineProperty(row, 'offsetTop', {
+            configurable: true,
+            value: (i + 1) * 100,
+          });
+        });
+    }
+
+    function setup(options?: { withFooter?: boolean }) {
+      const { container, getInstance } = renderWithInstance(messages, options);
+      const scrollEl = container.querySelector(
+        '[class*="overflow-y-auto"]',
+      ) as HTMLElement;
+      const scrollTo = vi.fn();
+      scrollEl.scrollTo = scrollTo;
+      stubRowOffsets(container);
+
+      return { getInstance, scrollTo };
+    }
+
+    it('scrolls to the last message by default', async () => {
+      // Four rows (user, agent, user, agent) → last row is at offsetTop 400.
+      const { getInstance, scrollTo } = setup();
+
+      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 } = setup();
+
+      getInstance().scrollToMessage(1);
+      await nextTick();
+
+      expect(scrollTo).toHaveBeenCalledWith(
+        expect.objectContaining({ top: 200, behavior: 'smooth' }),
+      );
+    });
+
+    it('treats the thread-footer as the trailing row', async () => {
+      // Four messages + footer → the footer is the fifth row at offsetTop 500.
+      const { getInstance, scrollTo } = setup({ withFooter: true });
+
+      getInstance().scrollToMessage();
+      await nextTick();
+
+      expect(scrollTo).toHaveBeenCalledWith(
+        expect.objectContaining({ top: 500, behavior: 'smooth' }),
+      );
+    });
+
+    it('does nothing when there are no messages', async () => {
+      const { container, getInstance } = renderWithInstance([]);
+      const scrollEl = container.querySelector(
+        '[class*="overflow-y-auto"]',
+      ) as HTMLElement;
+      const scrollTo = vi.fn();
+      scrollEl.scrollTo = scrollTo;
+
+      getInstance().scrollToMessage();
+      await nextTick();
+
+      expect(scrollTo).not.toHaveBeenCalled();
+    });
+  });
 });

package/src/components/base/CkConversationLayout/CkConversationLayout.stories.ts

@@ -99,6 +99,40 @@ function streamAgentReply(): void {
   </div>
 </template>`;
 
+const scrollToMessageTemplateSource = `<script setup lang="ts">
+import { CkConversationLayout } from '@aleph-alpha/chat-kit';
+import { ref, useTemplateRef } from 'vue';
+
+interface Message { role: string; content: string }
+const messages: Message[] = [/* ... */];
+
+const layout = useTemplateRef('layout');
+const index = ref(0);
+
+function scrollToMessage(): void {
+  // Zero-based index among all rows (a thread-footer counts as the last row).
+  layout.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>
+    <CkConversationLayout ref="layout" :messages="messages" class="min-h-0 flex-1">
+      <template #user-message="{ message }">
+        <div class="bg-core-bg-secondary rounded-md px-3 py-2 max-w-[400px]">{{ message.content }}</div>
+      </template>
+      <template #agent-message="{ message }">
+        <div class="px-3 py-2 max-w-[400px]">{{ message.content }}</div>
+      </template>
+    </CkConversationLayout>
+  </div>
+</template>`;
+
 const emptyTemplateSource = `<script setup lang="ts">
 import { CkConversationLayout } from '@aleph-alpha/chat-kit';
 
@@ -229,6 +263,56 @@ export const StreamingSimulation: Story = {
   parameters: { docs: { source: { code: streamingSimulationTemplateSource } } },
 };
 
+/**
+ * Programmatic navigation via the exposed `scrollToMessage(index)` method. Enter
+ * a zero-based row index and the layout 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: { CkConversationLayout },
+    setup() {
+      const messages = Array.from({ length: 12 }, (_, i) => ({
+        role: i % 2 === 0 ? 'user' : 'agent',
+        content: `[${i}] ${
+          i % 2 === 0 ? 'User' : 'Agent'
+        } message number ${i}. Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt.`,
+      }));
+      const layout = ref();
+      const index = ref(0);
+      function scrollToMessage() {
+        layout.value?.scrollToMessage(index.value);
+      }
+      return { messages, layout, 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>
+        <CkConversationLayout ref="layout" :messages="messages" style="flex: 1; min-height: 0;">
+          <template #user-message="{ message }">
+            <div style="background: #f0f0f0; padding: 8px 12px; border-radius: 12px 0 12px 12px; max-width: 400px;">
+              {{ message.content }}
+            </div>
+          </template>
+          <template #agent-message="{ message }">
+            <div style="padding: 8px 12px; max-width: 400px;">
+              {{ message.content }}
+            </div>
+          </template>
+        </CkConversationLayout>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: scrollToMessageTemplateSource } } },
+};
+
 /**
  * Empty state for when there are no messages. Use as an initial state before
  * the first user turn, or when history has been cleared.

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' }),
+      );
     });
   });
 });