@aleph-alpha/chat-kit 5.7.0 → 5.9.0

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/base/CkModelSelector/CkModelSelector.spec.ts

@@ -46,6 +46,29 @@ describe('CkModelSelector', () => {
     expect(emitted('update:selectedModelId')).toEqual([['kimi']]);
   });
 
+  it('renders a sublabel beneath the label when a model has one', async () => {
+    const user = userEvent.setup();
+    render(CkModelSelector, {
+      props: {
+        models: [
+          { id: 'kimi', label: 'Kimi' },
+          { id: 'phoenix', label: 'Phoenix', sublabel: '20260708-ash' },
+        ] satisfies CkModelOption[],
+        selectedModelId: 'phoenix',
+      },
+    });
+
+    await user.click(screen.getByRole('button', { name: TRIGGER_LABEL }));
+
+    // The sublabel sits inside the option row alongside its label.
+    const phoenix = await screen.findByRole('option', { name: /Phoenix/ });
+    expect(phoenix).toHaveTextContent('20260708-ash');
+    // A model without a sublabel shows only its label.
+    expect(
+      await screen.findByRole('option', { name: 'Kimi' }),
+    ).toHaveTextContent(/^Kimi$/);
+  });
+
   it('does not re-emit when the already-selected model is clicked', async () => {
     const user = userEvent.setup();
     const { emitted } = render(CkModelSelector, {

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

@@ -99,3 +99,23 @@ export const Disabled: Story = {
   args: { disabled: true },
   render: renderStory,
 };
+
+/**
+ * Rows can carry an optional `sublabel` — a muted second line for secondary
+ * metadata like a serving revision or provider. It shows only in the dropdown;
+ * the trigger stays label-only. Rows without one render just the label.
+ */
+export const WithSublabels: Story = {
+  args: {
+    models: [
+      { id: 'kimi', label: 'Kimi' },
+      { id: 'phoenix', label: 'Phoenix', sublabel: '20260708-ash' },
+      {
+        id: 'phoenix-no-think',
+        label: 'Phoenix (no thinking)',
+        sublabel: '20260708-ash',
+      },
+    ],
+  },
+  render: renderStory,
+};

package/src/components/base/CkModelSelector/CkModelSelector.vue

@@ -98,7 +98,14 @@ function select(id: string) {
             class="relative flex w-full items-center gap-2 rounded-sm py-2 pr-8 pl-3 text-left body-14-regular text-content-on-surface-primary outline-none hover:bg-background-surface-muted-subtle focus-visible:ring-2 focus-visible:ring-ring"
             @click="select(model.id)"
           >
-            <span class="min-w-0 flex-1 truncate">{{ model.label }}</span>
+            <span class="flex min-w-0 flex-1 flex-col">
+              <span class="min-w-0 truncate">{{ model.label }}</span>
+              <span
+                v-if="model.sublabel"
+                class="min-w-0 truncate text-xs text-content-on-surface-muted"
+                >{{ model.sublabel }}</span
+              >
+            </span>
             <UiIcon
               v-if="model.id === selectedModelId"
               name="check"

package/src/components/base/CkModelSelector/types.ts

@@ -19,6 +19,12 @@ export interface CkModelOption {
   id: string;
   /** Display name shown in the trigger and the option row. */
   label: string;
+  /**
+   * Optional secondary line shown muted beneath `label` in the dropdown row
+   * (e.g. a serving revision or provider). Not shown on the trigger, which
+   * stays label-only. Rows without one render just the label.
+   */
+  sublabel?: string;
 }
 
 export interface CkModelSelectorProps {

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