@aleph-alpha/chat-kit 5.11.0 → 5.13.0

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/composables/useIsTruncated.ts

@@ -0,0 +1,82 @@
+/**
+ * Local copy of ui-library's internal probe of the same name. chat-kit's
+ * supported ui-library range (^5.3.0) does not export it, and it is too small
+ * to justify widening that package's public API. Drop this file once the range
+ * moves up to a version that exports it.
+ */
+
+import { onScopeDispose, ref, watch, type Ref, type ShallowRef } from 'vue';
+
+/** An element ref as produced by `useTemplateRef`. */
+type ElementRef = Readonly<ShallowRef<HTMLElement | null>>;
+
+/**
+ * One observer for every caller. `ResizeObserver` is built to watch many
+ * targets and delivers them in a single batched callback, so a list of rows
+ * costs one callback and one layout pass rather than one per row. Created
+ * lazily so importing this module never touches the DOM.
+ */
+const measurers = new WeakMap<Element, () => void>();
+let sharedObserver: ResizeObserver | undefined;
+
+function getSharedObserver(): ResizeObserver | undefined {
+  if (typeof ResizeObserver === 'undefined') return undefined;
+  sharedObserver ??= new ResizeObserver((entries) => {
+    for (const entry of entries) measurers.get(entry.target)?.();
+  });
+  return sharedObserver;
+}
+
+function watchElement(el: Element, measure: () => void): void {
+  measurers.set(el, measure);
+  getSharedObserver()?.observe(el);
+}
+
+function unwatchElement(el: Element): void {
+  measurers.delete(el);
+  getSharedObserver()?.unobserve(el);
+}
+
+/**
+ * Whether an element's text is currently clipped by `text-overflow: ellipsis`.
+ *
+ * Re-measures when the element resizes and whenever `watchSource` changes, so
+ * it stays correct as the container narrows or the text is swapped out. Use it
+ * to show a tooltip only for names that are actually cut off.
+ * @param elementRef - The element whose text may be clipped
+ * @param watchSource - Value to re-measure on, e.g. the rendered text
+ * @returns Reactive truncation state
+ */
+export function useIsTruncated(
+  elementRef: ElementRef,
+  watchSource?: () => unknown,
+): Ref<boolean> {
+  const isTruncated = ref(false);
+
+  function measure(): void {
+    const el = elementRef.value;
+    // Sub-pixel widths round differently per browser, so require a whole
+    // pixel of overflow before calling it truncated.
+    isTruncated.value = el ? el.scrollWidth - el.clientWidth >= 1 : false;
+  }
+
+  // A resize alone doesn't cover a text swap that keeps the box the same size.
+  if (watchSource) watch(watchSource, measure, { flush: 'post' });
+
+  // Runs on mount too, when the template ref goes null -> element.
+  watch(
+    elementRef,
+    (el, previous) => {
+      if (previous) unwatchElement(previous);
+      if (el) watchElement(el, measure);
+      measure();
+    },
+    { immediate: true, flush: 'post' },
+  );
+
+  onScopeDispose(() => {
+    if (elementRef.value) unwatchElement(elementRef.value);
+  });
+
+  return isTruncated;
+}

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;