@aleph-alpha/chat-kit 5.11.0 → 5.13.0

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

@@ -0,0 +1,73 @@
+import CkCitationLabel from './CkCitationLabel.vue';
+import { render, screen } from '@testing-library/vue';
+import { describe, expect, it } from 'vitest';
+
+describe('CkCitationLabel', () => {
+  it('renders the source number as an inert span by default', () => {
+    const { container } = render(CkCitationLabel, { props: { index: 3 } });
+
+    const marker = container.querySelector('.ck-citation')!;
+    expect(marker.tagName).toBe('SPAN');
+    expect(marker).toHaveTextContent('3');
+  });
+
+  // Without a role of its own the digit is announced glued onto the preceding
+  // word ("reviews.[1][2]" → "reviews.12"). `role="img"` makes the chip one
+  // labelled object, while its text stays the plain number so it is still
+  // copied along with the surrounding prose (hence: no `select-none`).
+  it('exposes the static chip as a single labelled object', () => {
+    const { container } = render(CkCitationLabel, { props: { index: 3 } });
+
+    const marker = screen.getByRole('img', { name: 'Source 3' });
+    expect(marker).toHaveTextContent('3');
+    expect(marker).not.toHaveAttribute('tabindex');
+    expect(screen.queryByRole('button')).not.toBeInTheDocument();
+    expect(container.querySelector('.ck-citation')!.className).not.toContain(
+      'select-none',
+    );
+  });
+
+  it('honours a custom ariaLabel in span mode', () => {
+    render(CkCitationLabel, { props: { index: 3, ariaLabel: 'Quelle 3' } });
+
+    expect(screen.getByRole('img', { name: 'Quelle 3' })).toBeInTheDocument();
+  });
+
+  it('renders a button with a derived accessible name when `as="button"`', () => {
+    render(CkCitationLabel, { props: { index: 7, as: 'button' } });
+
+    const marker = screen.getByRole('button', { name: 'Source 7' });
+    expect(marker).toHaveAttribute('type', 'button');
+    expect(marker).toHaveTextContent('7');
+    // A control shouldn't start a text selection when clicked/dragged.
+    expect(marker.className).toContain('select-none');
+  });
+
+  it('uses a custom ariaLabel in button mode', () => {
+    render(CkCitationLabel, {
+      props: { index: 1, as: 'button', ariaLabel: 'Quelle 1' },
+    });
+
+    expect(
+      screen.getByRole('button', { name: 'Quelle 1' }),
+    ).toBeInTheDocument();
+  });
+
+  it('renders the default (neutral) state by default', () => {
+    const { container } = render(CkCitationLabel, { props: { index: 1 } });
+
+    const marker = container.querySelector('.ck-citation')!;
+    expect(marker.className).toContain('bg-background-surface-citation');
+    expect(marker.className).not.toContain('bg-background-accent-soft');
+  });
+
+  it('renders the selected (teal) state when `selected`', () => {
+    const { container } = render(CkCitationLabel, {
+      props: { index: 1, selected: true },
+    });
+
+    const marker = container.querySelector('.ck-citation')!;
+    expect(marker.className).toContain('bg-background-accent-soft');
+    expect(marker.className).not.toContain('bg-background-surface-citation');
+  });
+});

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

@@ -0,0 +1,86 @@
+import CkCitationLabel from './CkCitationLabel.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+
+/**
+ * CkCitationLabel is the numbered chip on its own — the citation marker
+ * without a popover. `CkCitation` composes it as its hover-card trigger
+ * (`as="button"`); use it directly, in its default static `span` form,
+ * wherever cited text should keep the marker styling but stay inert — the
+ * response preview in `CkFeedbackDialog` renders it that way.
+ */
+const meta: Meta<typeof CkCitationLabel> = {
+  title: 'Base/CkCitationLabel',
+  component: CkCitationLabel,
+  tags: ['autodocs'],
+  argTypes: {
+    index: { control: 'number' },
+    selected: { control: 'boolean' },
+    as: { control: 'inline-radio', options: ['span', 'button'] },
+    ariaLabel: { control: 'text' },
+  },
+  args: {
+    index: 1,
+  },
+  decorators: [
+    () => ({
+      template:
+        '<div style="max-width: 640px; margin: 0 auto; padding: 32px 64px;"><story /></div>',
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * The default: a static `span` in its amber state. Not focusable, no hover
+ * card — it just carries the marker styling.
+ */
+export const Default: Story = {};
+
+/**
+ * The selected (teal) state — set `selected` when the citation's source is the
+ * one currently open/highlighted.
+ */
+export const Selected: Story = {
+  args: { selected: true },
+};
+
+/**
+ * `as="button"` makes the chip an activatable control and gives it an
+ * accessible name (`"Source {index}"` by default, overridable with
+ * `ariaLabel`). This is the mode `CkCitation` uses for its popover trigger.
+ */
+export const AsButton: Story = {
+  args: { as: 'button' },
+};
+
+/**
+ * How static markers read inside a sentence — the way a cited answer looks in
+ * a read-only surface such as the feedback dialog's response preview.
+ */
+export const InlineInText: Story = {
+  render: (args) => ({
+    components: { CkCitationLabel },
+    setup() {
+      return { args };
+    },
+    template: `
+      <p style="font-size: 14px; line-height: 20px; max-width: 32rem;">
+        Departments that received customized training saw a 25% higher adoption
+        rate of the new tools compared to those with generic training.<CkCitationLabel
+          v-bind="args"
+          :index="1"
+        /><CkCitationLabel v-bind="args" :index="2" />
+      </p>
+    `,
+  }),
+};
+
+/**
+ * Multi-digit indices keep the chip legible — it grows with its number while
+ * staying aligned to the surrounding text.
+ */
+export const MultiDigitIndex: Story = {
+  args: { index: 12 },
+};

package/src/components/base/CkCitationLabel/CkCitationLabel.vue

@@ -0,0 +1,70 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import {
+  defaultChatKitLabels,
+  useChatKitLabels,
+} from '../../../handlers/useChatKitLabels';
+import type { CkCitationLabelProps } from './types';
+
+defineOptions({
+  name: 'CkCitationLabel',
+});
+
+const props = withDefaults(defineProps<CkCitationLabelProps>(), {
+  selected: false,
+  as: 'span',
+  ariaLabel: undefined,
+});
+
+const labels = useChatKitLabels();
+
+const isButton = computed(() => props.as === 'button');
+
+// Resolution order: per-instance prop, then `"{citationSourceLabel} {index}"`
+// from the injected label, then the English default.
+const resolvedAriaLabel = computed(
+  () =>
+    props.ariaLabel ??
+    `${labels.value.citationSourceLabel ?? defaultChatKitLabels.citationSourceLabel!} ${props.index}`,
+);
+</script>
+
+<template>
+  <!-- Single root element with attrs inheritance left on: `CkCitation` passes
+       this component to `UiPopoverTrigger as-child`, which clones the reka
+       trigger props (id, aria-expanded, data-state, onClick, …) onto it and
+       measures the popover anchor from the rendered element.
+
+       `role="img"` in span mode makes the chip one labelled object for
+       assistive tech ("Source 1") instead of a bare digit that gets read glued
+       onto the preceding word — "reviews.[1][2]" would otherwise come out as
+       "reviews.12". The rendered text stays the plain number, so a copy of the
+       surrounding prose still carries it. -->
+  <component
+    :is="as"
+    :type="isButton ? 'button' : undefined"
+    :role="isButton ? undefined : 'img'"
+    :aria-label="resolvedAriaLabel"
+    :class="[
+      'ck-citation ui-focus-ring mx-px inline-flex h-5 min-w-5 items-center justify-center rounded-sm border border-transparent px-1 align-middle text-sm leading-4 tabular-nums transition-colors',
+      // The static chip is part of the prose: it must stay selectable so the
+      // number survives a copy of the surrounding text. A control shouldn't
+      // start a text selection on click, so button mode keeps `select-none`.
+      // Only the control gets the hover layer; a static chip has no hover state.
+      isButton ? 'select-none hover-layer hover-layer-default' : '',
+      selected
+        ? 'bg-background-accent-soft text-content-on-accent-soft'
+        : 'bg-background-surface-citation text-content-on-surface-primary',
+    ]"
+  >
+    <span>{{ index }}</span>
+  </component>
+</template>
+
+<style scoped>
+@media (prefers-reduced-motion: reduce) {
+  .ck-citation {
+    transition-duration: 0.01ms;
+  }
+}
+</style>

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

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

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

@@ -0,0 +1,43 @@
+/**
+ * The bare citation marker — the numbered chip rendered in place of a `[n]`
+ * reference, with no popover attached. `CkCitation` composes it as its popover
+ * trigger (`as="button"`); use it directly, in its default static `span` form,
+ * wherever cited text should keep the marker styling without being interactive
+ * (e.g. the response preview in `CkFeedbackDialog`).
+ *
+ * @category Data Display
+ * @useCases static citation marker, read-only cited answer, popover trigger for CkCitation
+ * @keywords citation, source, reference, inline, marker, footnote, number, chip
+ * @related CkCitation, CkCitationCard, CkMarkdownRenderer, CkFeedbackDialog
+ */
+export interface CkCitationLabelProps {
+  /**
+   * 1-based source number shown in the chip. Matches the `[n]` reference it
+   * replaces in the answer text.
+   */
+  index: number;
+  /**
+   * Marks the citation as selected/active (e.g. the source it points to is
+   * currently open or highlighted). Renders the chip in its selected (teal)
+   * state instead of the default amber.
+   * @default false
+   */
+  selected?: boolean;
+  /**
+   * Element the chip renders as. `'span'` (the default) is inert: not
+   * focusable and not activatable. It is exposed to assistive tech as a single
+   * labelled object (`role="img"`) so the number is announced as
+   * `"Source {index}"` rather than being glued onto the preceding word, while
+   * the rendered text stays the plain number so it survives a copy of the
+   * surrounding prose. `'button'` makes it an activatable control — used by
+   * `CkCitation` as its popover trigger.
+   * @default 'span'
+   */
+  as?: 'span' | 'button';
+  /**
+   * Accessible label for the chip, in both modes. When omitted, resolves to
+   * `"{citationSourceLabel} {index}"` from `useChatKitLabels` (English default
+   * `"Source {index}"`).
+   */
+  ariaLabel?: string;
+}

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

@@ -241,6 +241,42 @@ describe('CkFeedbackDialog', () => {
     ).not.toBeInTheDocument();
   });
 
+  // The preview keeps the marker styling of the rated answer, but the markers
+  // are static: no hover card, nothing focusable inside the response column.
+  it('renders `[n]` references in the response as static citation markers', async () => {
+    renderDialog({
+      responseText: 'Adoption rose by 25%.[1]',
+      citations: [
+        { index: 1, fileName: 'q3-report.pdf', snippet: 'The cited chunk.' },
+      ],
+    });
+
+    await screen.findByRole('button', { name: SUBMIT });
+
+    // The dialog content is portaled to the body, so query from there.
+    const marker = document.body.querySelector('.ck-citation')!;
+    expect(marker.tagName).toBe('SPAN');
+    expect(marker).toHaveTextContent('1');
+    expect(marker.className).toContain('bg-background-surface-citation');
+    // Announced as its own labelled object, and never as a control.
+    expect(screen.getByRole('img', { name: 'Source 1' })).toBeInTheDocument();
+    expect(
+      screen.queryByRole('button', { name: /Source/ }),
+    ).not.toBeInTheDocument();
+  });
+
+  // Fully opt-in: without citations the response renders exactly as before.
+  it('leaves `[n]` references literal when no citations are given', async () => {
+    renderDialog({ responseText: 'Adoption rose by 25%.[1]' });
+
+    await screen.findByRole('button', { name: SUBMIT });
+
+    expect(document.body.querySelector('.ck-citation')).toBeNull();
+    expect(
+      await screen.findByText('Adoption rose by 25%.[1]'),
+    ).toBeInTheDocument();
+  });
+
   // When no response text is given the left preview column is omitted.
   it('omits the response heading when responseText is empty', async () => {
     renderDialog({ responseText: '' });

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

@@ -6,6 +6,7 @@ import type {
   CkFeedbackSentiment,
 } from './types';
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import type { CkCitationSource } from '../CkCitation';
 import type { CkFeedbackValue } from '../CkFeedbackButton';
 import { ref } from 'vue';
 
@@ -43,6 +44,30 @@ Key Lessons Learned:
 - **Stakeholder Involvement:** The most critical lesson was the need for early and **continuous stakeholder involvement** from all affected departments. A lack of initial engagement led to significant user resistance and process rework in the initial rollout.
 - **User Training:** Tailored, hands-on training was found to be far more effective than generic sessions. Departments that received customized training saw a **25% higher adoption rate** of the new tools compared to those with generic training.`;
 
+const CITED_RESPONSE = `Based on a review of internal documents, the rollout of the new tooling produced two measurable effects:
+
+- **Adoption:** Departments that received customized training saw a **25% higher adoption rate** of the new tools compared to 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]`;
+
+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',
+  },
+  {
+    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 LONG_RESPONSE = `Below is the complete corporate travel and expense policy. Several sections expand the original guidelines based on feedback from the 2026 internal audit.
 
 1. **General Travel Principles** – travel must serve clear business objectives, be cost-conscious, sustainable, and respect time and well-being. Short trips (e.g., Berlin → Heidelberg) are discouraged unless essential.
@@ -75,6 +100,7 @@ const meta: Meta<typeof CkFeedbackDialog> = {
       options: ['positive', 'negative'] satisfies CkFeedbackSentiment[],
     },
     responseText: { control: 'text' },
+    citations: { control: 'object' },
     reasons: { control: 'object' },
     maxFreeTextLength: { control: 'number' },
     reasonRequired: { control: 'boolean' },
@@ -177,6 +203,22 @@ export const Negative: Story = {
   },
 };
 
+/**
+ * Pass the same `citations` array the message was rendered with and the `[n]`
+ * references in the preview pick up the marker styling of the original answer.
+ * They are static here — no hover card, no focus stop — so the preview stays a
+ * preview.
+ */
+export const WithCitations: Story = {
+  args: {
+    open: true,
+    sentiment: 'positive',
+    reasons: POSITIVE_REASONS,
+    responseText: CITED_RESPONSE,
+    citations: CITATIONS,
+  },
+};
+
 /**
  * When no response text is provided, the left column collapses and the reasons
  * + free-text input fill the dialog.

package/src/components/base/CkFeedbackDialog/CkFeedbackDialog.vue

@@ -3,7 +3,9 @@ import {
   defaultChatKitLabels,
   useChatKitLabels,
 } from '../../../handlers/useChatKitLabels';
+import { CkCitationLabel } from '../CkCitationLabel';
 import { CkMarkdownRenderer } from '../CkMarkdownRenderer';
+import type { CkCitationSource } from '../CkCitation';
 import type {
   CkFeedbackDialogProps,
   CkFeedbackDialogSubmitPayload,
@@ -29,6 +31,7 @@ const {
   open = false,
   sentiment,
   responseText = '',
+  citations,
   reasons,
   maxFreeTextLength = 250,
   reasonRequired = true,
@@ -202,7 +205,14 @@ function handleSubmit(): void {
           <div
             class="ck-feedback-dialog__response min-h-0 flex-1 overflow-y-auto rounded-md border border-input bg-background-input-default px-3 py-2 shadow-xs"
           >
-            <CkMarkdownRenderer :content="responseText" />
+            <!-- Citations are rendered through the `citation` slot so the
+                 preview keeps the marker styling of the original answer
+                 without its hover cards — nothing here is interactive. -->
+            <CkMarkdownRenderer :content="responseText" :citations="citations">
+              <template #citation="{ source }: { source: CkCitationSource }">
+                <CkCitationLabel :index="source.index" />
+              </template>
+            </CkMarkdownRenderer>
           </div>
         </section>
 

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

@@ -1,3 +1,5 @@
+import type { CkCitationSource } from '../CkCitation';
+
 /**
  * Modal dialog for collecting qualitative feedback on an assistant response.
  * Opened after a binary thumbs-up / thumbs-down click (see `CkFeedbackButton`),
@@ -67,6 +69,24 @@ export interface CkFeedbackDialogProps {
    * @default undefined
    */
   responseText?: string;
+  /**
+   * Citation sources for inline `[n]` references in `responseText`. Pass the
+   * same array the message itself was rendered with, so the preview matches
+   * the answer the user is rating.
+   *
+   * The dialog renders the markers as **static** numbered chips
+   * (`CkCitationLabel`): styling only — no hover card, no focus stop, no
+   * `open-source`. Only each source's `index` is used; the rest of the shape
+   * is accepted so callers can forward their existing array unchanged.
+   * Omit it and `[n]` stays literal text.
+   *
+   * Same caveats as `CkMarkdownRenderer`'s `citations`: any numeric `[n]` in
+   * prose with a matching source is converted (wrap incidental ones in a code
+   * span to keep them literal), `index` must be unique, and the array
+   * reference should be stable/memoized.
+   * @default undefined
+   */
+  citations?: CkCitationSource[];
   /**
    * Available reasons to render as multi-select chips. The host fetches the
    * appropriate per-sentiment list from `GET /feedback/config` and passes it

package/src/components/base/CkUserMessage/CkUserMessage.vue

@@ -63,7 +63,7 @@ watch([() => props.message, () => props.collapsedLines], () => {
   <div class="inline-flex max-w-[536px] flex-col items-end justify-start gap-1">
     <div
       ref="contentRef"
-      class="ck-user-message__content text-content-on-surface-muted min-w-0 max-w-full self-stretch text-lg leading-7 font-medium break-words whitespace-pre-wrap [overflow-wrap:anywhere]"
+      class="ck-user-message__content select-text text-content-on-surface-muted min-w-0 max-w-full self-stretch text-lg leading-7 font-medium break-words whitespace-pre-wrap [overflow-wrap:anywhere]"
       :class="{
         'ck-user-message__content--clamped': clampEnabled && !expanded,
         'ck-user-message__content--faded':

package/src/components/base/index.ts

@@ -13,6 +13,8 @@ export type {
   CkCitationEmits,
   CkCitationSource,
 } from './CkCitation';
+export { CkCitationLabel } from './CkCitationLabel';
+export type { CkCitationLabelProps } from './CkCitationLabel';
 export { CkCitationCard } from './CkCitationCard';
 export type {
   CkCitationCardProps,

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', () => {