@aleph-alpha/chat-kit 5.10.1 → 5.12.0

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

@@ -1,7 +1,13 @@
-import type { BaseMessage, MessageContent } from '../../../types';
+import type {
+  BaseMessage,
+  MessageContent,
+  MessageTextContent,
+} from '../../../types';
 import CkConversation from './CkConversation.vue';
+import { CkMarkdownRenderer } from '../../base/CkMarkdownRenderer';
 import { defaultMarkdownClasses } from '../../base/CkMarkdownRenderer/defaultMarkdownClasses';
-import { render, screen } from '@testing-library/vue';
+import type { CkCitationSource } from '../../base/CkCitation';
+import { fireEvent, render, screen } from '@testing-library/vue';
 import {
   createCommentVNode,
   defineComponent,
@@ -26,6 +32,11 @@ function text(value: string): MessageContent {
   };
 }
 
+const CITATIONS: CkCitationSource[] = [
+  { index: 1, fileName: 'q3-report.pdf', snippet: 'The cited chunk.' },
+  { index: 2, fileName: 'goals-26.pdf', snippet: 'Another cited chunk.' },
+];
+
 const messages: BaseMessage[] = [
   {
     id: '1',
@@ -258,6 +269,12 @@ describe('CkConversation', () => {
   });
 
   describe('copy action', () => {
+    // jsdom ships no Clipboard API, so the copy button's default write target
+    // has to be stubbed in. Removed again so the stub can't leak.
+    afterEach(() => {
+      Reflect.deleteProperty(globalThis.navigator, 'clipboard');
+    });
+
     it('exposes the joined text via the copy action button', () => {
       const message: BaseMessage = {
         id: 'mix2',
@@ -300,6 +317,52 @@ describe('CkConversation', () => {
         container.querySelector('button[aria-label="Copy response"]'),
       ).toBeNull();
     });
+
+    // A host that wires citations renders the `[n]` references as markers, so
+    // they are no longer part of the message text in the DOM. The copy action
+    // copies the message's own text, which must still carry every reference —
+    // pasting a cited answer keeps its citations.
+    it('copies the citation references of a cited answer', async () => {
+      const writeText = vi.fn(() => Promise.resolve());
+      Object.defineProperty(globalThis.navigator, 'clipboard', {
+        value: { writeText },
+        configurable: true,
+      });
+
+      const message: BaseMessage = {
+        id: 'cited',
+        role: 'assistant',
+        content: [text('Adoption rose by 25%.[1] Rework fell.[2]')],
+        createdAt: now,
+        status: 'completed',
+      };
+      const { container } = render(CkConversation, {
+        props: { messages: [message] },
+        slots: {
+          // How a host opts into citations: override the content slot and pass
+          // its sources to the renderer.
+          'agent-message-content': (slotProps: { message: BaseMessage }) =>
+            h(CkMarkdownRenderer, {
+              content: (slotProps.message.content[0] as MessageTextContent)
+                .text,
+              citations: CITATIONS,
+            }),
+        },
+      });
+
+      // Both references really did become markers rather than staying text.
+      expect(container.querySelectorAll('.ck-citation')).toHaveLength(2);
+
+      // `fireEvent`, not `userEvent`: the latter's `setup()` installs its own
+      // `navigator.clipboard` stub over the one under test here.
+      await fireEvent.click(
+        container.querySelector('button[aria-label="Copy response"]')!,
+      );
+
+      expect(writeText).toHaveBeenCalledWith(
+        'Adoption rose by 25%.[1] Rework fell.[2]',
+      );
+    });
   });
 
   describe('slot overrides', () => {

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

@@ -1,3 +1,5 @@
+import type { CkCitationSource } from '../../base/CkCitation';
+import { CkMarkdownRenderer } from '../../base/CkMarkdownRenderer';
 import { CkCopyMessageButton } from '../../base/CkCopyMessageButton';
 import { CkFeedbackButton } from '../../base/CkFeedbackButton';
 import type { CkFeedbackValue } from '../../base/CkFeedbackButton';
@@ -65,6 +67,53 @@ const markdownContent = [
   '| Feedback Integration | Planned | High |',
 ].join('\n');
 
+const citedAnswer = [
+  'Based on a review of internal documents, the rollout produced two measurable effects:',
+  '',
+  '- **Adoption:** Departments that received customized training saw a **25% higher adoption rate** of the new tools than those with generic training.[1]',
+  '- **Rework:** A lack of initial stakeholder engagement led to significant process rework during the first wave.[2]',
+  '',
+  'Both findings are consistent across the quarterly reviews.[1][2]',
+].join('\n');
+
+/** One entry per `[n]` reference in `citedAnswer`, keyed by `index`. */
+const citations: CkCitationSource[] = [
+  {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet:
+      'Departments that received customized training saw a 25% higher adoption rate of the new tools compared to those with generic training.',
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+  {
+    index: 2,
+    fileName: 'Goal-planning-26.pdf',
+    snippet:
+      'Early stakeholder involvement remains the single strongest predictor of a rollout that does not require process rework.',
+    locationLabel: 'Page 12',
+  },
+];
+
+const citedMessages: BaseMessage[] = [
+  {
+    id: 'c1',
+    role: 'user',
+    content: [
+      text('What did we learn from the Digital Transformation rollout?'),
+    ],
+    createdAt: now,
+    status: 'completed',
+  },
+  {
+    id: 'c2',
+    role: 'assistant',
+    content: [text(citedAnswer)],
+    createdAt: now,
+    status: 'completed',
+  },
+];
+
 const sampleMessages: BaseMessage[] = [
   {
     id: '1',
@@ -384,6 +433,51 @@ function getMessageText(message: BaseMessage): string {
   </CkConversation>
 </template>`;
 
+const withCitationsTemplateSource = `<script setup lang="ts">
+import { CkConversation, CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+import type { BaseMessage, CkCitationSource } from '@aleph-alpha/chat-kit';
+
+const messages: BaseMessage[] = [/* ... */];
+
+// One entry per \`[n]\` reference in the answer, keyed by \`index\`. Keep the
+// array reference stable so the markdown processor isn't rebuilt on every
+// render.
+const citations: CkCitationSource[] = [
+  {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet: 'Departments that received customized training saw a 25% higher adoption rate.',
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+];
+
+function getMessageText(message: BaseMessage): string {
+  return message.content
+    .filter((c) => c.type === 'text')
+    .map((c) => c.text)
+    .join('');
+}
+
+// The card's external-link action is only a request — the host performs the
+// (often auth-proxied) navigation.
+function openSource(url: string): void {
+  window.open(url, '_blank', 'noopener');
+}
+</script>
+
+<template>
+  <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;">
+    <template #agent-message-content="{ message }">
+      <CkMarkdownRenderer
+        :content="getMessageText(message)"
+        :citations="citations"
+        @open-source="openSource"
+      />
+    </template>
+  </CkConversation>
+</template>`;
+
 const streamingSimulationTemplateSource = `<script setup lang="ts">
 import { CkConversation } from '@aleph-alpha/chat-kit';
 import type { BaseMessage } from '@aleph-alpha/chat-kit';
@@ -910,6 +1004,48 @@ export const WithCustomAgentContent: Story = {
   },
 };
 
+/**
+ * Citations are opt-in: override `#agent-message-content` and hand the message's
+ * sources to `CkMarkdownRenderer`. Every `[n]` in the answer whose number
+ * matches a source's `index` becomes a marker that reveals the source on hover
+ * or keyboard activation; unmatched markers stay plain text. `open-source` is
+ * re-emitted for the host to perform the (often auth-proxied) navigation — the
+ * second source here has no `url`, so its card omits the action.
+ *
+ * The footer copy button is unaffected: it copies the message text, so the
+ * `[n]` references travel with a pasted answer.
+ */
+export const WithCitations: Story = {
+  render: () => ({
+    components: { CkConversation, CkMarkdownRenderer },
+    setup() {
+      function openSource(url: string) {
+        window.open(url, '_blank', 'noopener');
+      }
+      return {
+        messages: citedMessages,
+        citations,
+        getMessageText,
+        openSource,
+      };
+    },
+    template: `
+      <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;">
+        <template #agent-message-content="{ message }">
+          <CkMarkdownRenderer
+            :content="getMessageText(message)"
+            :citations="citations"
+            @open-source="openSource"
+          />
+        </template>
+      </CkConversation>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: withCitationsTemplateSource } },
+  },
+};
+
 /**
  * End-to-end streaming scenario: appending a new user message and then
  * streaming an assistant reply chunk-by-chunk. Use as a reference for wiring

package/src/components/index.ts

@@ -4,6 +4,7 @@ export {
   CkAgentMessageHeader,
   CkHeaderActivityButton,
   CkCitation,
+  CkCitationLabel,
   CkCitationCard,
   CkConversationLayout,
   CkCopyMessageButton,
@@ -34,6 +35,7 @@ export type {
   CkCitationProps,
   CkCitationEmits,
   CkCitationSource,
+  CkCitationLabelProps,
   CkCitationCardProps,
   CkCitationCardEmits,
   CkConversationLayoutProps,

package/src/index.ts

@@ -74,6 +74,7 @@ export {
   CkAgentMessageHeader,
   CkHeaderActivityButton,
   CkCitation,
+  CkCitationLabel,
   CkCitationCard,
   CkConversation,
   CkConversationLayout,
@@ -106,6 +107,7 @@ export type {
   CkCitationProps,
   CkCitationEmits,
   CkCitationSource,
+  CkCitationLabelProps,
   CkCitationCardProps,
   CkCitationCardEmits,
   CkConversationLayoutProps,

package/src/types.ts

@@ -68,6 +68,36 @@ export type MessageContent =
   | MessageToolContent
   | MessageReasoningContent;
 
+declare global {
+  /**
+   * Extension point for {@link MessageMetadata}. Consumers declare their
+   * well-known metadata keys here and get them typed on every message,
+   * without chat-kit knowing what any of them mean:
+   *
+   * ```ts
+   * // app/src/types/chat-kit.d.ts
+   * declare global {
+   *   interface ChatKitMessageMetadata {
+   *     responseId?: string;
+   *     citations?: CitationManifest;
+   *   }
+   * }
+   * export {};
+   * ```
+   *
+   * Declare every key **optional**: chat-kit itself never populates them, and
+   * a message can reach a consumer before its host has stamped anything (mid
+   * stream, or on an optimistic node).
+   *
+   * This is a `declare global` interface rather than a module augmentation
+   * because `MessageMetadata` is re-exported through the package barrel —
+   * `declare module '@aleph-alpha/chat-kit'` does not merge across a
+   * re-export, and would silently type nothing.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  interface ChatKitMessageMetadata {}
+}
+
 /**
  * Open-ended metadata bag carried alongside a message. chat-kit is
  * intentionally agnostic about its contents — adapter authors
@@ -75,11 +105,11 @@ export type MessageContent =
  * through the tree → linear path projection, but never inspect it.
  *
  * Consumers attach their own well-known keys (attachments, citations,
- * ratings, …) and define their own typed projections at the read site
- * rather than extending this base type. That keeps the handler API stable
- * even as the shape of what gets stored on a message evolves.
+ * ratings, …). Declaring them on {@link ChatKitMessageMetadata} types those
+ * reads everywhere; the retained index signature keeps any other key legal,
+ * so the handler API stays stable as the stored shape evolves.
  */
-export type MessageMetadata = Record<string, unknown>;
+export type MessageMetadata = ChatKitMessageMetadata & Record<string, unknown>;
 
 export interface BaseMessage {
   id: string;