@aleph-alpha/chat-kit 3.2.0 → 3.3.0

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

@@ -1,4 +1,6 @@
 import CkAgentMessage from './CkAgentMessage.vue';
+import { CkMarkdownRenderer } from '../CkMarkdownRenderer';
+import type { CkCitationSource } from '../CkCitation';
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
 
 const meta: Meta<typeof CkAgentMessage> = {
@@ -213,3 +215,113 @@ export const WithoutIcon: Story = {
   }),
   parameters: { docs: { source: { code: withoutIconTemplateSource } } },
 };
+
+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: 'Support-Metrics-Q1.csv',
+    snippet:
+      'Ticket volume fell 18% quarter-over-quarter for the tailored-training cohorts versus the control group.',
+    locationLabel: 'Row 42',
+    url: '/api/v1/search-stores/ss_abc/files/file_456/public-urls',
+  },
+];
+
+const CITED_MARKDOWN = [
+  'Based on the internal documents, customized training drove measurably better outcomes.',
+  '',
+  'Departments with tailored sessions saw a **25% higher adoption rate** [1],',
+  'and reported markedly fewer support tickets in the first quarter [2].',
+].join('\n');
+
+const withCitationsTemplateSource = `<script setup lang="ts">
+import { CkAgentMessage, CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+import type { CkCitationSource } from '@aleph-alpha/chat-kit';
+
+// The reply body is markdown that contains inline [n] references.
+const content = [
+  'Based on the internal documents, customized training drove measurably better outcomes.',
+  '',
+  'Departments with tailored sessions saw a **25% higher adoption rate** [1],',
+  'and reported markedly fewer support tickets in the first quarter [2].',
+].join('\\n');
+
+// The numbered sources, mapped from the backend citations manifest.
+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',
+  },
+  {
+    index: 2,
+    fileName: 'Support-Metrics-Q1.csv',
+    snippet: 'Ticket volume fell 18% quarter-over-quarter for the tailored-training cohorts.',
+    locationLabel: 'Row 42',
+    url: '/api/v1/search-stores/ss_abc/files/file_456/public-urls',
+  },
+];
+
+function openSource(url: string) {
+  // Source URLs are auth-proxied; the host performs the navigation.
+  window.open(url, '_blank', 'noopener');
+}
+</script>
+
+<template>
+  <CkAgentMessage>
+    <template #icon>
+      <div class="bg-core-bg-tertiary flex size-6 items-center justify-center rounded-full text-xs">
+        AI
+      </div>
+    </template>
+    <CkMarkdownRenderer
+      :content="content"
+      :citations="citations"
+      @open-source="openSource"
+    />
+  </CkAgentMessage>
+</template>`;
+
+/**
+ * An assistant reply whose body is markdown containing inline `[n]` citations,
+ * rendered through `CkMarkdownRenderer` inside the message. Each `[n]` becomes
+ * an interactive `CkCitation` — hover a marker to preview its source. This is
+ * the end-to-end shape of a cited answer in a conversation.
+ */
+export const WithCitations: Story = {
+  render: () => ({
+    components: { CkAgentMessage, CkMarkdownRenderer },
+    setup() {
+      function openSource(url: string) {
+        window.open(url, '_blank', 'noopener');
+      }
+      return { content: CITED_MARKDOWN, citations: CITATIONS, openSource };
+    },
+    template: `
+      <CkAgentMessage>
+        <template #icon>
+          <div class="bg-core-bg-tertiary flex size-6 items-center justify-center rounded-full text-xs">
+            AI
+          </div>
+        </template>
+        <CkMarkdownRenderer
+          :content="content"
+          :citations="citations"
+          @open-source="openSource"
+        />
+      </CkAgentMessage>
+    `,
+  }),
+  parameters: { docs: { source: { code: withCitationsTemplateSource } } },
+};

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

@@ -0,0 +1,79 @@
+import CkCitation from './CkCitation.vue';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '@testing-library/vue';
+
+const base = {
+  index: 1,
+  fileName: 'q3-report.pdf',
+  snippet: 'The cited chunk text.',
+  locationLabel: 'Page 3',
+  url: '/api/v1/.../public-urls',
+};
+
+describe('CkCitation', () => {
+  it('renders a marker button showing the source number', () => {
+    render(CkCitation, { props: base });
+
+    const marker = screen.getByRole('button', { name: 'Source 1' });
+    expect(marker).toHaveTextContent('1');
+  });
+
+  it('derives the accessible name from the index by default', () => {
+    render(CkCitation, { props: { ...base, index: 7 } });
+
+    expect(
+      screen.getByRole('button', { name: 'Source 7' }),
+    ).toBeInTheDocument();
+  });
+
+  it('uses a custom ariaLabel when provided', () => {
+    render(CkCitation, { props: { ...base, ariaLabel: 'Quelle 1' } });
+
+    expect(
+      screen.getByRole('button', { name: 'Quelle 1' }),
+    ).toBeInTheDocument();
+  });
+
+  it('reveals the source card on activation and re-emits open-source', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkCitation, { props: base });
+
+    // The marker reveals its card on hover, matching the design.
+    await user.hover(screen.getByRole('button', { name: 'Source 1' }));
+
+    // The card content is rendered (in a popover portal) once open.
+    expect(await screen.findByText('q3-report.pdf')).toBeInTheDocument();
+    expect(screen.getByText('The cited chunk text.')).toBeInTheDocument();
+
+    await user.click(screen.getByRole('button', { name: 'Open source' }));
+
+    expect(emitted('open-source')).toEqual([['/api/v1/.../public-urls']]);
+  });
+
+  it('opens the card on keyboard activation of the marker', async () => {
+    const user = userEvent.setup();
+    render(CkCitation, { props: base });
+
+    const marker = screen.getByRole('button', { name: 'Source 1' });
+    marker.focus();
+    await user.keyboard('{Enter}');
+
+    expect(await screen.findByText('q3-report.pdf')).toBeInTheDocument();
+  });
+
+  it('renders the default (amber) marker state by default', () => {
+    render(CkCitation, { props: base });
+
+    const marker = screen.getByRole('button', { name: 'Source 1' });
+    expect(marker.className).toContain('bg-background-accent-yellow');
+    expect(marker.className).not.toContain('bg-background-accent-soft');
+  });
+
+  it('renders the selected (teal) marker state when `selected`', () => {
+    render(CkCitation, { props: { ...base, selected: true } });
+
+    const marker = screen.getByRole('button', { name: 'Source 1' });
+    expect(marker.className).toContain('bg-background-accent-soft');
+    expect(marker.className).not.toContain('bg-background-accent-yellow');
+  });
+});

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

@@ -0,0 +1,136 @@
+import CkCitation from './CkCitation.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+
+const SNIPPET =
+  'Departments that received customized training saw a 25% higher adoption rate of the new tools compared to those with generic training.';
+
+/**
+ * CkCitation is the inline marker rendered in place of a `[n]` reference in an
+ * assistant answer — a numbered chip that reveals a `CkCitationCard` describing
+ * the source on hover or keyboard activation (Enter/Space). Drive it through `CkMarkdownRenderer`'s
+ * `citations` prop to render cited answers; use `CkCitationCard` on its own for
+ * a standalone source preview.
+ */
+const meta: Meta<typeof CkCitation> = {
+  title: 'Base/CkCitation',
+  component: CkCitation,
+  tags: ['autodocs'],
+  argTypes: {
+    index: { control: 'number' },
+    selected: { control: 'boolean' },
+    fileName: { control: 'text' },
+    snippet: { control: 'text' },
+    locationLabel: { control: 'text' },
+    url: { control: 'text' },
+    ariaLabel: { control: 'text' },
+    openSourceLabel: { control: 'text' },
+  },
+  args: {
+    index: 1,
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet: SNIPPET,
+    locationLabel: 'Page 3',
+    url: '/api/v1/search-stores/ss_abc/files/file_123/public-urls',
+  },
+  decorators: [
+    () => ({
+      template:
+        '<div style="max-width: 640px; margin: 0 auto; padding: 96px 64px;"><story /></div>',
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/**
+ * A single marker in its default (amber) state. Hover the chip (or focus it and
+ * press Enter) to reveal the source card.
+ */
+export const Default: Story = {};
+
+/**
+ * The selected (teal) state — set `selected` when the citation's source is the
+ * one currently open/highlighted, so the active marker stands out.
+ */
+export const Selected: Story = {
+  args: { selected: true },
+};
+
+/**
+ * How markers read inside a sentence — two sources cited next to each other,
+ * the way they appear in an assistant answer.
+ */
+export const InlineInText: Story = {
+  render: (args) => ({
+    components: { CkCitation },
+    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.<CkCitation
+          v-bind="args"
+          :index="1"
+        /><CkCitation
+          v-bind="args"
+          :index="2"
+          file-name="Goal-planning-26.pdf"
+          location-label="Page 12"
+        />
+      </p>
+    `,
+  }),
+};
+
+/**
+ * Multi-digit indices keep the chip legible — the marker grows with its
+ * number while staying aligned to the surrounding text.
+ */
+export const MultiDigitIndex: Story = {
+  args: { index: 12 },
+};
+
+/**
+ * No `url` — the card still appears on hover but without the external-link
+ * action (e.g. an internal chunk with no servable file).
+ */
+export const WithoutLink: Story = {
+  args: { url: undefined },
+};
+
+/**
+ * Non-paginated source — the card omits the page footer.
+ */
+export const WithoutLocation: Story = {
+  args: { locationLabel: undefined },
+};
+
+/**
+ * A row of markers with different file types — the card's badge tone follows
+ * each source's extension.
+ */
+export const SourceTypes: Story = {
+  render: () => ({
+    components: { CkCitation },
+    setup() {
+      const sources = [
+        { index: 1, fileName: 'q3-report.pdf', locationLabel: 'Page 3' },
+        { index: 2, fileName: 'README.md' },
+        { index: 3, fileName: 'sales-2026.csv', locationLabel: 'Row 42' },
+      ];
+      return { sources, snippet: SNIPPET };
+    },
+    template: `
+      <p style="font-size: 14px; line-height: 20px;">
+        Multiple sources back this claim.<CkCitation
+          v-for="s in sources"
+          :key="s.index"
+          v-bind="s"
+          :snippet="snippet"
+        />
+      </p>
+    `,
+  }),
+};

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

@@ -0,0 +1,145 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, ref } from 'vue';
+import {
+  UiPopover,
+  UiPopoverTrigger,
+  UiPopoverContent,
+} from '@aleph-alpha/ui-library';
+import {
+  defaultChatKitLabels,
+  useChatKitLabels,
+} from '../../../handlers/useChatKitLabels';
+import { CkCitationCard } from '../CkCitationCard';
+import type { CkCitationProps } from './types';
+
+defineOptions({
+  name: 'CkCitation',
+});
+
+const props = withDefaults(defineProps<CkCitationProps>(), {
+  selected: false,
+  locationLabel: undefined,
+  url: undefined,
+  ariaLabel: undefined,
+  openSourceLabel: undefined,
+});
+
+const emit = defineEmits<{
+  'open-source': [url: string];
+}>();
+
+const labels = useChatKitLabels();
+
+// Resolution order: per-instance prop, then `"{citationSourceLabel} {index}"`
+// from the injected label, then the English default.
+const triggerLabel = computed(
+  () =>
+    props.ariaLabel ??
+    `${labels.value.citationSourceLabel ?? defaultChatKitLabels.citationSourceLabel!} ${props.index}`,
+);
+
+// Close delay so the pointer can cross the gap from the marker into the card
+// without it disappearing on the way.
+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);
+let closeTimer: ReturnType<typeof setTimeout> | undefined;
+
+function show(): void {
+  if (closeTimer) {
+    clearTimeout(closeTimer);
+    closeTimer = undefined;
+  }
+  open.value = true;
+}
+
+function scheduleHide(): void {
+  if (closeTimer) clearTimeout(closeTimer);
+  closeTimer = setTimeout(() => {
+    open.value = false;
+    closeTimer = undefined;
+  }, CLOSE_DELAY_MS);
+}
+
+function onPointerEnter(): void {
+  isPointerInteraction.value = true;
+  show();
+}
+
+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.
+function onOpenAutoFocus(event: Event): void {
+  if (isPointerInteraction.value) event.preventDefault();
+}
+
+// Close once focus leaves the card entirely (keyboard users tabbing out). Moving
+// focus between elements inside the card keeps it open.
+function onContentFocusOut(event: FocusEvent): void {
+  const nextTarget = event.relatedTarget as Node | null;
+  const content = event.currentTarget as HTMLElement;
+  if (!nextTarget || !content.contains(nextTarget)) {
+    scheduleHide();
+  }
+}
+
+onBeforeUnmount(() => {
+  if (closeTimer) clearTimeout(closeTimer);
+});
+</script>
+
+<template>
+  <UiPopover v-model:open="open">
+    <UiPopoverTrigger as-child>
+      <button
+        type="button"
+        :aria-label="triggerLabel"
+        :class="[
+          'ck-citation mx-px inline-flex h-5 min-w-5 select-none items-center justify-center rounded-sm px-1 align-middle text-sm leading-4 tabular-nums transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          selected
+            ? 'bg-background-accent-soft text-black'
+            : 'bg-background-accent-yellow text-background-status-warning',
+        ]"
+        @mouseenter="onPointerEnter"
+        @mouseleave="onPointerLeave"
+      >
+        {{ index }}
+      </button>
+    </UiPopoverTrigger>
+    <UiPopoverContent
+      align="start"
+      :side-offset="8"
+      class="w-auto border-0 bg-transparent p-0 shadow-none"
+      @open-auto-focus="onOpenAutoFocus"
+      @mouseenter="onPointerEnter"
+      @mouseleave="onPointerLeave"
+      @focusin="show"
+      @focusout="onContentFocusOut"
+    >
+      <CkCitationCard
+        :file-name="fileName"
+        :snippet="snippet"
+        :location-label="locationLabel"
+        :url="url"
+        :open-source-label="openSourceLabel"
+        @open-source="(u: string) => emit('open-source', u)"
+      />
+    </UiPopoverContent>
+  </UiPopover>
+</template>
+
+<style scoped>
+@media (prefers-reduced-motion: reduce) {
+  .ck-citation {
+    transition-duration: 0.01ms;
+  }
+}
+</style>

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

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

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

@@ -0,0 +1,80 @@
+/**
+ * A single citation source: the data needed to render a marker and its card.
+ * This is the per-source shape the host maps each backend citation into (the
+ * `index` matches the `[n]` reference in the answer text) and the element type
+ * of `CkMarkdownRenderer`'s `citations` prop.
+ *
+ * @category Data Display
+ * @useCases describe a cited source, build the citations map for an assistant reply
+ * @keywords citation, source, reference, file, page, snippet
+ * @related CkCitation, CkCitationCard, CkMarkdownRenderer
+ */
+export interface CkCitationSource {
+  /**
+   * 1-based source number rendered in the marker. Matches the `[n]`
+   * reference it replaces in the answer text.
+   */
+  index: number;
+  /**
+   * Source file name. Title of the card and basis for the file-type badge
+   * (pass the original name with its extension).
+   */
+  fileName: string;
+  /** The cited chunk text, shown in the card body. */
+  snippet: string;
+  /**
+   * Location label for the card footer, e.g. `"Page 3"`. Omit for
+   * non-paginated sources.
+   */
+  locationLabel?: string;
+  /**
+   * Source URL for the card's external-link action. Activating it emits
+   * `open-source`. Omit to hide the action.
+   */
+  url?: string;
+}
+
+/**
+ * An inline citation marker — the numbered chip rendered in place of a `[n]`
+ * reference inside an assistant answer. On hover, or when activated by
+ * keyboard (Enter/Space) or click, it reveals a `CkCitationCard` describing
+ * the source.
+ *
+ * The marker shows the bare source number (no brackets). Activating the
+ * card's external-link action re-emits `open-source` so the host can open
+ * the (possibly auth-proxied) source URL.
+ *
+ * @category Data Display
+ * @useCases inline citation in assistant reply, numbered source reference, hover to preview the cited file/page
+ * @keywords citation, source, reference, inline, marker, footnote, number, hover, popover
+ * @related CkCitationCard, CkMarkdownRenderer, CkAgentMessage
+ */
+export interface CkCitationProps extends CkCitationSource {
+  /**
+   * Marks the citation as selected/active (e.g. the source it points to is
+   * currently open or highlighted). Renders the marker in its selected (teal)
+   * state instead of the default amber.
+   * @default false
+   */
+  selected?: boolean;
+  /**
+   * Accessible label for the marker trigger. When omitted, resolves to
+   * `"{citationSourceLabel} {index}"` from `useChatKitLabels` (English default
+   * `"Source {index}"`). Set this to override per instance.
+   */
+  ariaLabel?: string;
+  /**
+   * Accessible label for the card's external-link action. When omitted,
+   * resolves from `useChatKitLabels().citationOpenSource` (English default
+   * `"Open source"`).
+   */
+  openSourceLabel?: string;
+}
+
+export interface CkCitationEmits {
+  /**
+   * Re-emitted from the card when the user opens the source. The payload is
+   * `url`.
+   */
+  (e: 'open-source', url: string): void;
+}

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

@@ -0,0 +1,77 @@
+import CkCitationCard from './CkCitationCard.vue';
+import { provideChatKitLabels } from '../../../handlers/useChatKitLabels';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '@testing-library/vue';
+import { defineComponent, h } from 'vue';
+
+const base = {
+  fileName: 'q3-report.pdf',
+  snippet: 'The cited chunk text.',
+};
+
+describe('CkCitationCard', () => {
+  it('renders the file name and snippet', () => {
+    render(CkCitationCard, { props: { ...base, locationLabel: 'Page 3' } });
+
+    expect(screen.getByText('q3-report.pdf')).toBeInTheDocument();
+    expect(screen.getByText('The cited chunk text.')).toBeInTheDocument();
+    expect(screen.getByText('Page 3')).toBeInTheDocument();
+  });
+
+  it('hides the location footer when no locationLabel is given', () => {
+    render(CkCitationCard, { props: base });
+
+    expect(screen.queryByText('Page 3')).not.toBeInTheDocument();
+  });
+
+  it('hides the external-link action when no url is provided', () => {
+    render(CkCitationCard, { props: base });
+
+    expect(
+      screen.queryByRole('button', { name: 'Open source' }),
+    ).not.toBeInTheDocument();
+  });
+
+  it('shows the external-link action and emits open-source with the url', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkCitationCard, {
+      props: { ...base, url: '/api/v1/.../public-urls' },
+    });
+
+    await user.click(screen.getByRole('button', { name: 'Open source' }));
+
+    expect(emitted('open-source')).toEqual([['/api/v1/.../public-urls']]);
+  });
+
+  it('uses a custom openSourceLabel for the action', () => {
+    render(CkCitationCard, {
+      props: { ...base, url: '/u', openSourceLabel: 'Quelle öffnen' },
+    });
+
+    expect(
+      screen.getByRole('button', { name: 'Quelle öffnen' }),
+    ).toBeInTheDocument();
+  });
+
+  it('wraps a long unbroken snippet so it cannot overflow the fixed-width card', () => {
+    const snippet = 'x'.repeat(200);
+    render(CkCitationCard, { props: { ...base, snippet } });
+
+    expect(screen.getByText(snippet).className).toContain('break-words');
+  });
+
+  it('uses the injected citationOpenSource label via provideChatKitLabels', () => {
+    const Wrapper = defineComponent({
+      setup() {
+        provideChatKitLabels(() => ({ citationOpenSource: 'Quelle öffnen' }));
+        return () => h(CkCitationCard, { ...base, url: '/u' });
+      },
+    });
+
+    render(Wrapper);
+
+    expect(
+      screen.getByRole('button', { name: 'Quelle öffnen' }),
+    ).toBeInTheDocument();
+  });
+});