@aleph-alpha/chat-kit 1.0.0 → 1.1.0

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

@@ -0,0 +1,129 @@
+import CkConversationLayout from './CkConversationLayout.vue';
+import { render, screen } from '@testing-library/vue';
+import { type Component, defineComponent, h } from 'vue';
+
+const messages = [
+  { role: 'user', content: 'Hello there' },
+  { role: 'agent', content: 'Hi! How can I help?' },
+  { role: 'user', content: 'Tell me a joke' },
+  { role: 'agent', content: 'Why did the chicken cross the road?' },
+];
+
+/**
+ * Helper to render CkConversationLayout with standard slot markup.
+ * Each message is rendered as a <p> with its content as text and a test-id
+ * indicating the slot it was routed through (user-msg or agent-msg).
+ */
+function renderLayout(
+  msgs: Array<{ role: string; content: string }> = messages,
+) {
+  // eslint-disable-next-line vue/one-component-per-file
+  const Wrapper = defineComponent({
+    setup() {
+      return () =>
+        h(
+          CkConversationLayout as unknown as Component,
+          { messages: msgs },
+          {
+            '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),
+          },
+        );
+    },
+  });
+
+  return render(Wrapper);
+}
+
+describe('CkConversationLayout', () => {
+  describe('message display', () => {
+    it('displays all provided messages', () => {
+      renderLayout();
+
+      for (const msg of messages) {
+        expect(screen.getByText(msg.content)).toBeInTheDocument();
+      }
+    });
+
+    it('shows no messages when the conversation is empty', () => {
+      renderLayout([]);
+
+      expect(screen.queryAllByTestId('user-msg')).toHaveLength(0);
+      expect(screen.queryAllByTestId('agent-msg')).toHaveLength(0);
+    });
+  });
+
+  describe('message routing', () => {
+    it('renders user messages through the user-message slot', () => {
+      renderLayout();
+
+      const userMessages = screen.getAllByTestId('user-msg');
+      expect(userMessages).toHaveLength(2);
+      expect(userMessages[0]).toHaveTextContent('Hello there');
+      expect(userMessages[1]).toHaveTextContent('Tell me a joke');
+    });
+
+    it('renders agent messages through the agent-message slot', () => {
+      renderLayout();
+
+      const agentMessages = screen.getAllByTestId('agent-msg');
+      expect(agentMessages).toHaveLength(2);
+      expect(agentMessages[0]).toHaveTextContent('Hi! How can I help?');
+      expect(agentMessages[1]).toHaveTextContent(
+        'Why did the chicken cross the road?',
+      );
+    });
+  });
+
+  describe('message order', () => {
+    it('preserves the order of messages from the input array', () => {
+      renderLayout();
+
+      const allMessages = screen.getAllByTestId(/msg$/);
+      expect(allMessages).toHaveLength(4);
+      expect(allMessages[0]).toHaveTextContent('Hello there');
+      expect(allMessages[1]).toHaveTextContent('Hi! How can I help?');
+      expect(allMessages[2]).toHaveTextContent('Tell me a joke');
+      expect(allMessages[3]).toHaveTextContent(
+        'Why did the chicken cross the road?',
+      );
+    });
+  });
+
+  describe('slot data', () => {
+    const customMessages = [
+      { role: 'user', content: 'Hi', id: '42', timestamp: '2026-02-13' },
+    ];
+
+    function renderCustomSlotWrapper() {
+      return h(
+        CkConversationLayout as unknown as Component,
+        { messages: customMessages },
+        {
+          'user-message': ({
+            message,
+          }: {
+            message: (typeof customMessages)[0];
+          }) =>
+            h(
+              'p',
+              null,
+              `${message.id}|${message.timestamp}|${message.content}`,
+            ),
+          'agent-message': () => null,
+        },
+      );
+    }
+
+    it('provides the full message object including custom fields to scoped slots', () => {
+      // eslint-disable-next-line vue/one-component-per-file
+      const Wrapper = defineComponent({ setup: () => renderCustomSlotWrapper });
+
+      render(Wrapper);
+
+      expect(screen.getByText('42|2026-02-13|Hi')).toBeInTheDocument();
+    });
+  });
+});

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

@@ -0,0 +1,251 @@
+import CkConversationLayoutComponent from './CkConversationLayout.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import type { DefineComponent } from 'vue';
+import { ref } from 'vue';
+
+// Generic Vue components need a type assertion for Storybook compatibility
+const CkConversationLayout =
+  CkConversationLayoutComponent as unknown as DefineComponent;
+
+const sampleMessages = [
+  { role: 'user', content: 'Hello! Can you help me with something?' },
+  {
+    role: 'agent',
+    content: 'Of course! I am here to help. What would you like to know?',
+  },
+  {
+    role: 'user',
+    content:
+      "Find the lessons learned and best practices from the 'Digital Transformation Phase 1' project.",
+  },
+  {
+    role: 'agent',
+    content:
+      'Based on a review of internal documents, here are the key lessons learned and best practices.',
+  },
+];
+
+const meta: Meta<typeof CkConversationLayout> = {
+  title: 'Base/CkConversationLayout',
+  component: CkConversationLayout,
+  tags: ['autodocs'],
+  decorators: [
+    () => ({
+      template:
+        '<div style="height: 400px; border: 1px solid #e0e0e0; border-radius: 8px; overflow: hidden;"><story /></div>',
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { CkConversationLayout } from '@aleph-alpha/chat-kit';
+
+interface Message { role: string; content: string }
+const messages: Message[] = [
+  { role: 'user', content: 'Hello! Can you help me with something?' },
+  { role: 'agent', content: 'Of course! What would you like to know?' },
+];
+</script>
+
+<template>
+  <CkConversationLayout :messages="messages" style="height: 400px;">
+    <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>
+</template>`;
+
+const streamingSimulationTemplateSource = `<script setup lang="ts">
+import { CkConversationLayout } from '@aleph-alpha/chat-kit';
+import { ref } from 'vue';
+
+interface Message { role: string; content: string }
+const messages = ref<Message[]>([]);
+
+function streamAgentReply(): void {
+  messages.value = [
+    ...messages.value,
+    { role: 'user', content: 'Tell me about Digital Transformation Phase 1.' },
+  ];
+  const text = 'Key lessons learned include stakeholder involvement, user training, and centralized feedback.';
+  let i = 0;
+  messages.value = [...messages.value, { role: 'agent', content: '' }];
+  const interval = setInterval(() => {
+    i = Math.min(i + 3, text.length);
+    const last = messages.value.length - 1;
+    messages.value[last] = { ...messages.value[last], content: text.slice(0, i) };
+    if (i >= text.length) clearInterval(interval);
+  }, 30);
+}
+</script>
+
+<template>
+  <div class="flex h-[400px] flex-col">
+    <CkConversationLayout :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="whitespace-pre-wrap px-3 py-2 max-w-[400px]">{{ message.content }}</div>
+      </template>
+    </CkConversationLayout>
+    <button @click="streamAgentReply">Send message + simulate stream</button>
+  </div>
+</template>`;
+
+const emptyTemplateSource = `<script setup lang="ts">
+import { CkConversationLayout } from '@aleph-alpha/chat-kit';
+
+interface Message { role: string; content: string }
+const messages: Message[] = [];
+</script>
+
+<template>
+  <CkConversationLayout :messages="messages" style="height: 400px;">
+    <template #user-message="{ message }"><div>{{ message.content }}</div></template>
+    <template #agent-message="{ message }"><div>{{ message.content }}</div></template>
+  </CkConversationLayout>
+</template>`;
+
+/**
+ * Default layout renders alternating user and agent messages with sticky-to-bottom
+ * scrolling. Use for most chat viewports where you need automatic follow-behavior.
+ */
+export const Default: Story = {
+  render: () => ({
+    components: { CkConversationLayout },
+    setup() {
+      return { messages: sampleMessages };
+    },
+    template: `
+      <CkConversationLayout :messages="messages" style="height: 100%;">
+        <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>
+    `,
+  }),
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * Demonstrates the layout's streaming behavior: the bottom spacer shrinks as
+ * the agent response grows so the user's last message stays pinned to the top.
+ * Use when streaming tokens from an LLM into the last agent message.
+ */
+export const StreamingSimulation: Story = {
+  render: () => ({
+    components: { CkConversationLayout },
+    setup() {
+      const messages = ref([
+        { role: 'user', content: 'Hello!' },
+        { role: 'agent', content: 'Hi there!' },
+      ]);
+
+      const streamingText =
+        'Based on a review of internal documents, here are the key lessons learned and best practices from the Digital Transformation Phase 1 project, broken down by category:\n\n' +
+        'Key Lessons Learned:\n' +
+        '• Stakeholder Involvement: Early and continuous stakeholder involvement from all affected departments.\n' +
+        '• User Training: Tailored, hands-on training was far more effective than generic sessions.\n' +
+        '• Centralized Feedback: Establishing a centralized feedback loop was crucial.\n\n' +
+        'Key Best Practices & Successes:\n' +
+        '• Phased Rollout: Minimized disruption and provided opportunities to refine processes.';
+
+      let streamInterval: ReturnType<typeof setInterval> | null = null;
+      let charIndex = 0;
+
+      function streamNextChunk() {
+        if (charIndex >= streamingText.length) {
+          if (streamInterval) clearInterval(streamInterval);
+          return;
+        }
+        // eslint-disable-next-line sonarjs/pseudo-random
+        const chunkSize = Math.floor(Math.random() * 5) + 3;
+        charIndex = Math.min(charIndex + chunkSize, streamingText.length);
+        const lastIdx = messages.value.length - 1;
+        messages.value[lastIdx] = {
+          ...messages.value[lastIdx],
+          content: streamingText.slice(0, charIndex),
+        };
+      }
+
+      function startStreaming() {
+        messages.value = [...messages.value, { role: 'agent', content: '' }];
+        charIndex = 0;
+        streamInterval = setInterval(streamNextChunk, 30);
+      }
+
+      function simulateStream() {
+        messages.value = [
+          ...messages.value,
+          {
+            role: 'user',
+            content:
+              'Tell me about Digital Transformation Phase 1 lessons learned.',
+          },
+        ];
+
+        // After a short delay, start streaming the agent response
+        setTimeout(startStreaming, 500);
+      }
+
+      return { messages, simulateStream };
+    },
+    template: `
+      <div style="display: flex; flex-direction: column; height: 100%;">
+        <CkConversationLayout :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; white-space: pre-wrap;">
+              {{ message.content }}
+            </div>
+          </template>
+        </CkConversationLayout>
+        <div style="padding: 8px; border-top: 1px solid #e0e0e0;">
+          <button @click="simulateStream" style="padding: 6px 16px; border-radius: 6px; background: #333; color: white; cursor: pointer;">
+            Send message + simulate stream
+          </button>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: streamingSimulationTemplateSource } } },
+};
+
+/**
+ * Empty state for when there are no messages. Use as an initial state before
+ * the first user turn, or when history has been cleared.
+ */
+export const Empty: Story = {
+  render: () => ({
+    components: { CkConversationLayout },
+    template: `
+      <CkConversationLayout :messages="[]" style="height: 100%;">
+        <template #user-message="{ message }">
+          <div>{{ message.content }}</div>
+        </template>
+        <template #agent-message="{ message }">
+          <div>{{ message.content }}</div>
+        </template>
+      </CkConversationLayout>
+    `,
+  }),
+  parameters: { docs: { source: { code: emptyTemplateSource } } },
+};

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

@@ -0,0 +1,206 @@
+<script setup lang="ts" generic="T extends { id: string; role: string }">
+import { ref, watch, nextTick, onMounted, onUnmounted } from 'vue';
+
+defineOptions({ name: 'CkConversationLayout' });
+
+const props = defineProps<{
+  messages: T[];
+}>();
+
+defineSlots<{
+  'user-message': (props: { message: T }) => void;
+  'agent-message': (props: { message: T }) => void;
+}>();
+
+const scrollContainerRef = ref<HTMLElement | null>(null);
+const containerHeight = ref(0);
+const isAutoScrollEnabled = ref(true);
+const hasBottomSpacer = ref(false);
+const spacerHeight = ref(0);
+
+let resizeObserver: ResizeObserver | null = null;
+
+onMounted(() => {
+  const container = scrollContainerRef.value;
+  if (container) {
+    containerHeight.value = container.clientHeight;
+    resizeObserver = new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        containerHeight.value = entry.contentRect.height;
+      }
+    });
+    resizeObserver.observe(container);
+
+    // Initially scroll to the bottom of the conversation without any spacer
+    nextTick(() => {
+      container.scrollTop = container.scrollHeight;
+    });
+  }
+});
+
+onUnmounted(() => {
+  resizeObserver?.disconnect();
+});
+
+/**
+ * Check if the viewport is currently showing the bottom of the last message.
+ * When the user manually scrolls up past the last message, auto-scroll is disabled.
+ */
+function isFollowingContent(): boolean {
+  const container = scrollContainerRef.value;
+  if (!container) return true;
+  const rows = container.querySelectorAll<HTMLElement>('[data-message-row]');
+  const lastRow = rows[rows.length - 1];
+  if (!lastRow) return true;
+
+  const lastRowBottom = lastRow.offsetTop + lastRow.offsetHeight;
+  const viewportBottom = container.scrollTop + container.clientHeight;
+  return viewportBottom >= lastRowBottom - 10;
+}
+
+function handleScroll(): void {
+  isAutoScrollEnabled.value = isFollowingContent();
+}
+
+/**
+ * Recalculate the bottom spacer height so that content below the last user
+ * message plus the spacer always equals one viewport height.
+ * As the agent message grows the spacer shrinks by the same amount,
+ * keeping the total scrollable height stable and the viewport still.
+ */
+function updateSpacerHeight(): void {
+  const container = scrollContainerRef.value;
+  if (!container || !hasBottomSpacer.value) {
+    spacerHeight.value = 0;
+    return;
+  }
+
+  const userRows = container.querySelectorAll<HTMLElement>(
+    '[data-message-row="user"]',
+  );
+  const lastUserRow = userRows[userRows.length - 1];
+  if (!lastUserRow) {
+    spacerHeight.value = 0;
+    return;
+  }
+
+  const rows = container.querySelectorAll<HTMLElement>('[data-message-row]');
+  const lastRow = rows[rows.length - 1];
+  if (!lastRow) {
+    spacerHeight.value = 0;
+    return;
+  }
+
+  const lastUserTop = lastUserRow.offsetTop;
+  const lastRowBottom = lastRow.offsetTop + lastRow.offsetHeight;
+  const contentFromUserToEnd = lastRowBottom - lastUserTop;
+  const gap = parseFloat(getComputedStyle(container).rowGap) || 0;
+
+  spacerHeight.value = Math.max(
+    0,
+    containerHeight.value - contentFromUserToEnd - gap,
+  );
+}
+
+/**
+ * Scroll so the last user message is at the top of the viewport.
+ * The bottom spacer ensures enough scroll room.
+ */
+function scrollUserMessageToTop(): void {
+  const container = scrollContainerRef.value;
+  if (!container) return;
+
+  hasBottomSpacer.value = true;
+  spacerHeight.value = containerHeight.value;
+
+  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;
+  });
+}
+
+/**
+ * Scroll only when the bottom of the last message overflows past the viewport.
+ * This keeps the viewport still while the agent message is short,
+ * and starts following once it grows past the visible area.
+ */
+function scrollToEndOfContent(): void {
+  const container = scrollContainerRef.value;
+  if (!container || !isAutoScrollEnabled.value) return;
+
+  const rows = container.querySelectorAll<HTMLElement>('[data-message-row]');
+  const lastRow = rows[rows.length - 1];
+  if (!lastRow) return;
+
+  const lastRowBottom = lastRow.offsetTop + lastRow.offsetHeight;
+  const viewportBottom = container.scrollTop + container.clientHeight;
+
+  if (lastRowBottom > viewportBottom) {
+    container.scrollTop = lastRowBottom - container.clientHeight;
+  }
+}
+
+// When a new user message is added, scroll it to the top of the viewport
+watch(
+  () => props.messages.length,
+  (newLen, oldLen) => {
+    if (newLen <= (oldLen ?? 0)) return;
+    const lastMessage = props.messages[newLen - 1];
+    if (lastMessage?.role === 'user') {
+      nextTick(() => scrollUserMessageToTop());
+    }
+  },
+);
+
+// Follow agent content: handles both new agent messages and streaming updates.
+// First shrinks the spacer to match the growing content, then scrolls when it overflows.
+watch(
+  () => props.messages,
+  () => {
+    if (props.messages.length === 0) return;
+    const lastMessage = props.messages[props.messages.length - 1];
+    if (lastMessage && lastMessage.role !== 'user') {
+      nextTick(() => {
+        updateSpacerHeight();
+        if (isAutoScrollEnabled.value) {
+          scrollToEndOfContent();
+        }
+      });
+    }
+  },
+  { deep: true },
+);
+</script>
+
+<template>
+  <div
+    ref="scrollContainerRef"
+    class="relative flex flex-col gap-4 overflow-y-auto"
+    @scroll="handleScroll"
+  >
+    <div
+      v-for="message in messages"
+      :key="message.id"
+      :data-message-row="message.role"
+    >
+      <div v-if="message.role === 'user'" class="flex justify-end">
+        <slot name="user-message" :message="message" />
+      </div>
+      <div v-else class="flex justify-start">
+        <slot name="agent-message" :message="message" />
+      </div>
+    </div>
+    <!-- Bottom spacer: shrinks as agent content grows to keep viewport stable -->
+    <div
+      v-if="hasBottomSpacer"
+      aria-hidden="true"
+      :style="{ minHeight: `${spacerHeight}px` }"
+    />
+  </div>
+</template>

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

@@ -0,0 +1,2 @@
+export { default as CkConversationLayout } from './CkConversationLayout.vue';
+export type { CkConversationLayoutProps } from './types';

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

@@ -0,0 +1,18 @@
+/**
+ * Scroll-aware container that renders a list of messages with sticky-to-bottom
+ * behavior, a shrinking spacer so streaming agent replies don't jitter the viewport,
+ * and slots for rendering user/agent messages.
+ *
+ * @category Layout
+ * @useCases conversation scroll container, streaming chat layout, chat viewport with auto-scroll, follow-the-bottom chat list
+ * @keywords conversation, layout, scroll, auto-scroll, streaming, chat, container
+ * @related CkConversation, CkAgentMessage, CkUserMessage
+ *
+ * @typeParam T - Message type; must have at least a `role` string property.
+ */
+export interface CkConversationLayoutProps<
+  T extends { role: string } = { role: string },
+> {
+  /** Array of messages to render in the conversation layout */
+  messages: T[];
+}

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

@@ -0,0 +1,89 @@
+import CkCopyMessageActionButton from './CkCopyMessageActionButton.vue';
+import userEvent from '@testing-library/user-event';
+import { render, screen, waitFor } from '@testing-library/vue';
+import { flushPromises } from '@vue/test-utils';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('CkCopyMessageActionButton', () => {
+  const writeText = vi.fn((_: string) => Promise.resolve());
+
+  beforeEach(() => {
+    writeText.mockReset();
+    writeText.mockResolvedValue(undefined);
+  });
+
+  it('emits copy with success when clipboard succeeds', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkCopyMessageActionButton, {
+      props: { text: 'x', writeToClipboard: writeText },
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Copy message' }));
+    await flushPromises();
+
+    expect(writeText).toHaveBeenCalledWith('x');
+    expect(emitted('copy')).toEqual([[{ success: true }]]);
+  });
+
+  it('copies text and updates the accessible name', async () => {
+    const user = userEvent.setup();
+    render(CkCopyMessageActionButton, {
+      props: { text: 'Hello, world', writeToClipboard: writeText },
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Copy message' }));
+    await flushPromises();
+
+    expect(writeText).toHaveBeenCalledWith('Hello, world');
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: 'Copied' }),
+      ).toBeInTheDocument();
+    });
+  });
+
+  describe('when clipboard rejects', () => {
+    beforeEach(() => {
+      writeText.mockReset();
+      writeText.mockRejectedValue(new Error('denied'));
+    });
+
+    it('emits copy with success false', async () => {
+      const user = userEvent.setup();
+      const { emitted } = render(CkCopyMessageActionButton, {
+        props: { text: 'x', writeToClipboard: writeText },
+      });
+
+      await user.click(screen.getByRole('button', { name: 'Copy message' }));
+      await flushPromises();
+
+      expect(emitted('copy')).toEqual([[{ success: false }]]);
+      expect(
+        screen.getByRole('button', { name: 'Copy message' }),
+      ).toBeInTheDocument();
+    });
+  });
+
+  it('reverts label after durationMs', async () => {
+    vi.useFakeTimers();
+    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
+    render(CkCopyMessageActionButton, {
+      props: { text: 'x', durationMs: 1500, writeToClipboard: writeText },
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Copy message' }));
+
+    await waitFor(() => {
+      expect(
+        screen.getByRole('button', { name: 'Copied' }),
+      ).toBeInTheDocument();
+    });
+
+    await vi.advanceTimersByTimeAsync(1500);
+
+    expect(
+      screen.getByRole('button', { name: 'Copy message' }),
+    ).toBeInTheDocument();
+    vi.useRealTimers();
+  });
+});