@aleph-alpha/chat-kit 4.0.0 → 5.0.1

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

@@ -0,0 +1,21 @@
+/**
+ * Full-width header row for an assistant (agent) message. Owns the agent icon,
+ * a header text and an optional activity button, and is intended to be passed
+ * into the `header` slot of `CkAgentMessage`.
+ *
+ * It has two visual states, driven purely by whether the `activity` slot is
+ * provided:
+ * - **with `activity`** — vertical padding and a bottom border separate the
+ *   header from the message body;
+ * - **without `activity`** — a compact icon + text row with no padding or
+ *   border.
+ *
+ * Slots: `icon` (leading agent avatar/icon), default (header text, ellipsised
+ * on overflow), `activity` (typically a `CkHeaderActivityButton`).
+ *
+ * @category Messages
+ * @useCases agent message header, assistant turn header, chain-of-thought summary row, activity indicator row
+ * @keywords agent, assistant, message, header, icon, activity, conversation
+ * @related CkAgentMessage, CkHeaderActivityButton, CkConversation
+ */
+export type CkAgentMessageHeaderProps = Record<string, never>;

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

@@ -100,6 +100,18 @@ export const WithoutLink: Story = {
   args: { url: undefined },
 };
 
+/**
+ * A very long file name truncates with an ellipsis inside the hover card while
+ * the external-link action stays pinned to the right of the truncated name; the
+ * full name is exposed on hover via the `title` attribute.
+ */
+export const LongFileName: Story = {
+  args: {
+    fileName:
+      'Annual-Strategy-And-Operational-Review-And-Lessons-Learned-Digital-Transformation-Phase-1-FY2026-Final-APPROVED-v3.pdf',
+  },
+};
+
 /**
  * Non-paginated source — the card omits the page footer.
  */

package/src/components/base/CkCitation/CkCitation.vue

@@ -43,9 +43,11 @@ const triggerLabel = computed(
 const CLOSE_DELAY_MS = 80;
 
 const open = ref(false);
-// Tracks whether the current open was driven by the pointer (hover) rather than
-// the keyboard, so we can suppress the popover's focus management for hover only.
-const isPointerInteraction = ref(false);
+// Whether the current open session was initiated by the pointer (hover) rather
+// than the keyboard. Persists for the whole session — including the close — so
+// we can fully suppress the popover's focus management for hover while keeping
+// it for keyboard users.
+const openedByPointer = ref(false);
 let closeTimer: ReturnType<typeof setTimeout> | undefined;
 
 function show(): void {
@@ -65,20 +67,41 @@ function scheduleHide(): void {
 }
 
 function onPointerEnter(): void {
-  isPointerInteraction.value = true;
+  // Only mark the session pointer-driven on a closed → open transition. A stray
+  // mouseenter while the card is already open (e.g. it was opened via keyboard,
+  // then the pointer drifts over it) must not flip the flag, or onCloseAutoFocus
+  // would wrongly skip restoring focus and leave focus lost on close.
+  if (!open.value) openedByPointer.value = true;
   show();
 }
 
+// Don't reset `openedByPointer` here — the close fires one tick later
+// (CLOSE_DELAY_MS), and `onCloseAutoFocus` still needs to know the session was
+// hover-driven so it can skip restoring focus to the marker.
 function onPointerLeave(): void {
-  isPointerInteraction.value = false;
   scheduleHide();
 }
 
-// Suppress auto-focus for hover opens only (so hovering never steals focus or
-// scrolls). Keyboard opens keep it, moving focus into the card so the source
-// action is reachable.
+// Enter/Space activate the marker (opening the card) via keyboard; mark those
+// sessions keyboard-driven so focus management is restored (into the card on
+// open, back to the marker on close/Escape). Other keys (Tab, arrows) must not
+// flip the pointer/keyboard distinction.
+function onTriggerKeydown(event: KeyboardEvent): void {
+  if (event.key === 'Enter' || event.key === ' ') {
+    openedByPointer.value = false;
+  }
+}
+
+// For hover sessions, suppress the popover's focus management entirely: don't
+// pull focus into the card on open (it would steal focus / scroll), and don't
+// yank focus back to the marker on close. That close-time refocus is what
+// painted a stray focus-visible ring on the marker you'd just hovered away from.
 function onOpenAutoFocus(event: Event): void {
-  if (isPointerInteraction.value) event.preventDefault();
+  if (openedByPointer.value) event.preventDefault();
+}
+
+function onCloseAutoFocus(event: Event): void {
+  if (openedByPointer.value) event.preventDefault();
 }
 
 // Close once focus leaves the card entirely (keyboard users tabbing out). Moving
@@ -108,6 +131,7 @@ onBeforeUnmount(() => {
             ? 'bg-background-accent-soft text-black'
             : 'bg-background-accent-yellow text-background-status-warning',
         ]"
+        @keydown="onTriggerKeydown"
         @mouseenter="onPointerEnter"
         @mouseleave="onPointerLeave"
       >
@@ -119,6 +143,7 @@ onBeforeUnmount(() => {
       :side-offset="8"
       class="w-auto border-0 bg-transparent p-0 shadow-none"
       @open-auto-focus="onOpenAutoFocus"
+      @close-auto-focus="onCloseAutoFocus"
       @mouseenter="onPointerEnter"
       @mouseleave="onPointerLeave"
       @focusin="show"

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

@@ -60,6 +60,15 @@ describe('CkCitationCard', () => {
     expect(screen.getByText(snippet).className).toContain('break-words');
   });
 
+  it('clamps a long snippet to a bounded number of lines so card height does not grow with excerpt length', () => {
+    const snippet = Array(40)
+      .fill('A long sentence of citation excerpt text.')
+      .join(' ');
+    render(CkCitationCard, { props: { ...base, snippet } });
+
+    expect(screen.getByText(snippet).className).toContain('line-clamp-6');
+  });
+
   it('uses the injected citationOpenSource label via provideChatKitLabels', () => {
     const Wrapper = defineComponent({
       setup() {

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

@@ -92,10 +92,11 @@ export const MinimalSnippetOnly: Story = {
 };
 
 /**
- * A long file name truncates with an ellipsis (the badge and external-link
- * action stay pinned, the card keeps its width); the full name stays available
- * on hover via the `title` attribute. The `truncate` behaviour holds for any
- * length, including a single unbroken token with no separators.
+ * A long file name truncates with an ellipsis while the external-link action
+ * stays pinned to the right of the (truncated) name and the card keeps its
+ * width; the full name stays available on hover via the `title` attribute. The
+ * `truncate` behaviour holds for any length, including a single unbroken token
+ * with no separators.
  */
 export const LongFileName: Story = {
   args: {
@@ -105,12 +106,15 @@ export const LongFileName: Story = {
 };
 
 /**
- * A long excerpt wraps freely — the card grows vertically while keeping its
- * fixed width.
+ * A whole-document-length excerpt is clamped to a bounded number of lines
+ * (`line-clamp-6`) with a trailing ellipsis, so the card stays a compact preview
+ * and its height does not grow with the excerpt length — no matter how large a
+ * chunk `file_search` returns (it can be as large as the entire source file). The
+ * full text remains reachable via the external-link action.
  */
 export const LongSnippet: Story = {
   args: {
-    snippet: `${LOREM} ${LOREM}`,
+    snippet: `${LOREM} ${LOREM} ${LOREM} ${LOREM} ${LOREM}`,
   },
 };
 

package/src/components/base/CkCitationCard/CkCitationCard.vue

@@ -42,10 +42,10 @@ function handleOpen(): void {
   <div
     class="ck-citation-card flex w-[22.5rem] max-w-[90vw] flex-col gap-2 rounded-md bg-background-surface-floating px-6 pb-6 pt-4 shadow-md"
   >
-    <div class="flex items-center gap-3">
+    <div class="flex items-center gap-2">
       <UiFileType :filename="fileName" class="shrink-0" />
       <p
-        class="min-w-0 flex-1 truncate text-sm font-medium text-content-on-surface-primary"
+        class="min-w-0 truncate text-sm font-medium text-content-on-surface-primary"
         :title="fileName"
       >
         {{ fileName }}
@@ -62,7 +62,9 @@ function handleOpen(): void {
       </UiButton>
     </div>
 
-    <p class="break-words text-sm leading-5 text-content-on-surface-secondary">
+    <p
+      class="line-clamp-6 break-words text-sm leading-5 text-content-on-surface-secondary"
+    >
       {{ snippet }}
     </p>
 

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

@@ -181,7 +181,7 @@ watch(
 <template>
   <div
     ref="scrollContainerRef"
-    class="relative flex flex-col gap-4 overflow-y-auto"
+    class="relative flex flex-col gap-8 overflow-y-auto"
     @scroll="handleScroll"
   >
     <div

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

@@ -1,6 +1,6 @@
 import { render, screen, within } from '@testing-library/vue';
 import userEvent from '@testing-library/user-event';
-import { describe, expect, it } from 'vitest';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 import CkFileItemsList from './CkFileItemsList.vue';
 import type { CkFileEntry } from './types';
 
@@ -11,8 +11,34 @@ const files: CkFileEntry[] = [
   { id: 'd', filename: 'archive.zip' },
 ];
 
+// The inline capacity is derived purely from the measured container width: how
+// many items fit at `minItemWidth` each. JSDOM has no layout, so we stub
+// `clientWidth` (read in `onMounted`). The default 700px fits 3 inline items at
+// the default 200px `minItemWidth`, reproducing the typical "3 inline, rest
+// collapsed" behaviour for these specs.
+//
+// Note: width is measured in `onMounted`, which updates reactively *after* the
+// initial render. Assertions that depend on the *narrowed* (width-collapsed)
+// state must therefore await the re-render (e.g. via `findByRole`) rather than
+// querying synchronously.
+let clientWidthSpy: ReturnType<typeof vi.spyOn>;
+
+function setContainerWidth(px: number) {
+  clientWidthSpy.mockReturnValue(px);
+}
+
+beforeEach(() => {
+  clientWidthSpy = vi
+    .spyOn(Element.prototype, 'clientWidth', 'get')
+    .mockReturnValue(700);
+});
+
+afterEach(() => {
+  clientWidthSpy.mockRestore();
+});
+
 describe('CkFileItemsList', () => {
-  it('renders all files inline when count <= maxInline', () => {
+  it('renders all files inline when they fit the available width', () => {
     const { container } = render(CkFileItemsList, {
       props: { files: files.slice(0, 3) },
     });
@@ -25,34 +51,82 @@ describe('CkFileItemsList', () => {
     ).toBeNull();
   });
 
-  it('collapses into a popover trigger when count exceeds maxInline', () => {
+  it('collapses into a popover trigger when the files no longer fit', async () => {
     render(CkFileItemsList, { props: { files } });
 
-    const trigger = screen.getByRole('button', { name: /4 files/i });
+    const trigger = await screen.findByRole('button', { name: /4 files/i });
     expect(trigger).toBeInTheDocument();
     expect(trigger).toHaveTextContent('4 files');
   });
 
-  it('uses an explicit triggerLabel when provided', () => {
+  it('keeps every file inline on a wide wrapper (no upper cap)', () => {
+    setContainerWidth(2000);
+    const many: CkFileEntry[] = [
+      ...files,
+      { id: 'e', filename: 'slides.key' },
+      { id: 'f', filename: 'budget.xlsx' },
+    ];
+
+    const { container } = render(CkFileItemsList, { props: { files: many } });
+
+    const list = container.querySelector('[data-slot="file-items-list"]');
+    expect(list?.querySelectorAll('li')).toHaveLength(6);
+    expect(
+      container.querySelector('[data-slot="file-items-list-trigger"]'),
+    ).toBeNull();
+  });
+
+  it('reduces the inline count as the wrapper narrows', async () => {
+    // 360px fits only 1 item at the default 200px minItemWidth, so 3 files no
+    // longer fit and collapse. The narrowing is applied after the onMounted
+    // measurement, so await the collapsed trigger rather than querying
+    // synchronously.
+    setContainerWidth(360);
+
+    const { container } = render(CkFileItemsList, {
+      props: { files: files.slice(0, 3) },
+    });
+
+    expect(
+      await screen.findByRole('button', { name: /3 files/i }),
+    ).toBeInTheDocument();
+    expect(container.querySelector('[data-slot="file-items-list"]')).toBeNull();
+  });
+
+  it('constrains inline item width between minItemWidth and maxItemWidth', () => {
+    const { container } = render(CkFileItemsList, {
+      props: { files: files.slice(0, 2), minItemWidth: 140, maxItemWidth: 200 },
+    });
+
+    const item = container.querySelector<HTMLElement>(
+      '[data-slot="file-items-list"] li',
+    );
+    expect(item?.style.minWidth).toBe('140px');
+    expect(item?.style.maxWidth).toBe('200px');
+  });
+
+  it('uses an explicit triggerLabel when provided', async () => {
     render(CkFileItemsList, {
       props: { files, triggerLabel: '+1 more attachment' },
     });
 
-    expect(screen.getByRole('button')).toHaveTextContent('+1 more attachment');
+    expect(await screen.findByRole('button')).toHaveTextContent(
+      '+1 more attachment',
+    );
   });
 
-  it('keeps a single-line trigger (no count subtitle) when showStatus is off', () => {
+  it('keeps a single-line trigger (no count subtitle) when showStatus is off', async () => {
     render(CkFileItemsList, {
       props: { files, triggerLabel: 'Uploaded documents' },
     });
 
-    const trigger = screen.getByRole('button');
+    const trigger = await screen.findByRole('button');
     expect(trigger).toHaveTextContent('Uploaded documents');
     expect(trigger).not.toHaveTextContent('4 files');
   });
 
   describe('showStatus summary on the collapsed trigger', () => {
-    it('summarises the number of failed uploads in an error line', () => {
+    it('summarises the number of failed uploads in an error line', async () => {
       const withFailures: CkFileEntry[] = [
         { id: 'a', filename: 'a.pdf', error: 'Upload failed' },
         { id: 'b', filename: 'b.md', error: 'Upload failed' },
@@ -68,13 +142,13 @@ describe('CkFileItemsList', () => {
         },
       });
 
-      const trigger = screen.getByRole('button', {
+      const trigger = await screen.findByRole('button', {
         name: /Uploading documents, 2 uploads failed/i,
       });
       expect(trigger).toHaveTextContent('2 uploads failed');
     });
 
-    it('renders an aggregate progress bar while files are uploading', () => {
+    it('renders an aggregate progress bar while files are uploading', async () => {
       const uploading: CkFileEntry[] = [
         { id: 'a', filename: 'a.pdf', progress: 20 },
         { id: 'b', filename: 'b.md', progress: 60 },
@@ -90,10 +164,11 @@ describe('CkFileItemsList', () => {
         },
       });
 
+      await screen.findByRole('button');
       expect(container.querySelector('[data-slot="progress"]')).toBeTruthy();
     });
 
-    it('shows the file count once all uploads succeed', () => {
+    it('shows the file count once all uploads succeed', async () => {
       render(CkFileItemsList, {
         props: {
           files,
@@ -102,7 +177,7 @@ describe('CkFileItemsList', () => {
         },
       });
 
-      const trigger = screen.getByRole('button');
+      const trigger = await screen.findByRole('button');
       expect(trigger).toHaveTextContent('Uploaded documents');
       expect(trigger).toHaveTextContent('4 files');
     });

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

@@ -1,5 +1,5 @@
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
-import { ref } from 'vue';
+import { computed, ref } from 'vue';
 import CkFileItemsList from './CkFileItemsList.vue';
 import type { CkFileEntry } from './types';
 
@@ -12,12 +12,13 @@ const meta: Meta<typeof CkFileItemsList> = {
     docs: {
       description: {
         component:
-          'Compact horizontal row of file attachments. Renders up to `maxInline` `UiFileItem`s side-by-side; once that threshold is exceeded, the full list collapses into a single popover trigger.',
+          'Compact horizontal row of file attachments. Renders as many `UiFileItem`s inline as fit the available width — each kept between `minItemWidth` and `maxItemWidth` wide — and collapses the full list into a single popover trigger once they no longer fit.',
       },
     },
   },
   argTypes: {
-    maxInline: { control: { type: 'number', min: 1, max: 6, step: 1 } },
+    minItemWidth: { control: { type: 'number', min: 80, max: 320, step: 8 } },
+    maxItemWidth: { control: { type: 'number', min: 120, max: 480, step: 8 } },
     size: { control: { type: 'inline-radio' }, options: ['default', 'small'] },
     isRemovable: { control: 'boolean' },
     disabled: { control: 'boolean' },
@@ -97,15 +98,15 @@ function handleRemove(id: CkFileEntry['id']) {
 </template>`;
 
 /**
- * Up to `maxInline` (default `3`) files are rendered inline as a horizontal
- * row of `UiFileItem`s.
+ * As many files as fit the available width are rendered inline as a horizontal
+ * row of `UiFileItem`s (each kept between `minItemWidth` and `maxItemWidth`).
  */
 export const Inline: Story = {
   render: () => ({
     components: { CkFileItemsList },
     setup: () => ({ files: baseFiles }),
     template: `
-      <div class="bg-background-surface-primary p-4 w-[36rem]">
+      <div class="bg-background-surface-primary p-4 w-[44rem]">
         <CkFileItemsList :files="files" />
       </div>
     `,
@@ -114,15 +115,15 @@ export const Inline: Story = {
 };
 
 /**
- * When the list overflows `maxInline`, the component collapses to a single
- * popover trigger. Click it to reveal the full vertical list of files.
+ * When the files no longer fit the available width, the component collapses to
+ * a single popover trigger. Click it to reveal the full vertical list of files.
  */
 export const Collapsed: Story = {
   render: () => ({
     components: { CkFileItemsList },
     setup: () => ({ files: overflowFiles }),
     template: `
-      <div class="bg-background-surface-primary p-4 w-[36rem]">
+      <div class="bg-background-surface-primary p-4 w-[44rem]">
         <CkFileItemsList :files="files" />
       </div>
     `,
@@ -193,7 +194,7 @@ export const Removable: Story = {
       return { files, handleRemove };
     },
     template: `
-      <div class="bg-background-surface-primary p-4 w-[36rem]">
+      <div class="bg-background-surface-primary p-4 w-[44rem]">
         <CkFileItemsList :files="files" is-removable @remove="handleRemove" />
       </div>
     `,
@@ -232,7 +233,7 @@ export const CustomItem: Story = {
     components: { CkFileItemsList },
     setup: () => ({ files: baseFiles }),
     template: `
-      <div class="bg-background-surface-primary p-4 w-[36rem]">
+      <div class="bg-background-surface-primary p-4 w-[44rem]">
         <CkFileItemsList :files="files">
           <template #item="{ file }">
             <a
@@ -283,7 +284,7 @@ export const Clickable: Story = {
       return { files: overflowFiles, openFile, lastClicked };
     },
     template: `
-      <div class="bg-background-surface-primary p-4 w-[36rem]">
+      <div class="bg-background-surface-primary p-4 w-[44rem]">
         <CkFileItemsList
           :files="files"
           list-label="Attached files"
@@ -335,7 +336,7 @@ export const Disabled: Story = {
       ] as CkFileEntry[],
     }),
     template: `
-      <div class="flex flex-col gap-6 bg-background-surface-primary p-4 w-[36rem]">
+      <div class="flex flex-col gap-6 bg-background-surface-primary p-4 w-[44rem]">
         <div>
           <p class="label-12-medium text-content-on-surface-muted mb-2">
             Whole list disabled
@@ -353,3 +354,50 @@ export const Disabled: Story = {
   }),
   parameters: { docs: { source: { code: disabledTemplateSource } } },
 };
+
+/**
+ * The inline count adapts to the available width. There is no hard cap on the
+ * number of inline items — as many fit are kept, each between `minItemWidth`
+ * and `maxItemWidth` wide. As the wrapper narrows, fewer items stay inline
+ * until the whole list collapses into the popover trigger.
+ *
+ * Drag the bottom-right corner of the box to resize it and watch the list
+ * react. (The other stories use a fixed-width wrapper, so resizing the browser
+ * window alone won't change their layout.)
+ */
+export const Responsive: Story = {
+  args: {
+    minItemWidth: 200,
+    maxItemWidth: 256,
+    fileCount: 3,
+  } as never,
+  argTypes: {
+    fileCount: { control: { type: 'number', min: 1, max: 5, step: 1 } },
+  } as never,
+  render: (args) => ({
+    components: { CkFileItemsList },
+    setup() {
+      const argsWithCount = args as typeof args & { fileCount?: number };
+      const files = computed(() =>
+        overflowFiles.slice(
+          0,
+          Math.min(5, Math.max(1, argsWithCount.fileCount ?? 5)),
+        ),
+      );
+      const listArgs = computed(() => {
+        const rest = { ...argsWithCount };
+        delete rest.fileCount;
+        return rest;
+      });
+      return { args: listArgs, files };
+    },
+    template: `
+      <div
+        class="resize-x overflow-auto bg-background-surface-primary p-4"
+        style="resize: horizontal; overflow: auto; width: 44rem; min-width: 12rem; max-width: 100%;"
+      >
+        <CkFileItemsList v-bind="args" :files="files" />
+      </div>
+    `,
+  }),
+};