@aleph-alpha/chat-kit 3.1.3 → 3.3.0

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();
+  });
+});

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

@@ -0,0 +1,144 @@
+import CkCitationCard from './CkCitationCard.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+
+const LOREM =
+  'Lorem ipsum dolor sit amet consectetur. Phasellus ipsum nunc pellentesque diam donec id fermentum. Morbi amet lacus cras sagittis sagittis libero. Elit netus sodales in risus diam ut.';
+
+/**
+ * CkCitationCard is the floating card that describes a single citation source:
+ * the file, the cited excerpt, an optional location (e.g. page), and an
+ * optional external-link action. It is the hover/focus content of `CkCitation`,
+ * but can be used on its own wherever a source preview is needed. The
+ * external-link action is exposed as an `open-source` event rather than a plain
+ * link, because the source URL is often auth-proxied.
+ */
+const meta: Meta<typeof CkCitationCard> = {
+  title: 'Base/CkCitationCard',
+  component: CkCitationCard,
+  tags: ['autodocs'],
+  argTypes: {
+    fileName: { control: 'text' },
+    snippet: { control: 'text' },
+    locationLabel: { control: 'text' },
+    url: { control: 'text' },
+    openSourceLabel: { control: 'text' },
+  },
+  args: {
+    fileName: 'Q2_Business_Plan.pdf',
+    snippet: LOREM,
+    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: 24px;"><story /></div>',
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { CkCitationCard } from '@aleph-alpha/chat-kit';
+
+function openSource(url: string) {
+  // The source URL is often auth-proxied — the host opens it.
+  window.open(url, '_blank', 'noopener');
+}
+</script>
+
+<template>
+  <CkCitationCard
+    file-name="Q2_Business_Plan.pdf"
+    snippet="Lorem ipsum dolor sit amet consectetur…"
+    location-label="Page 3"
+    url="/api/v1/search-stores/ss_abc/files/file_123/public-urls"
+    @open-source="openSource"
+  />
+</template>`;
+
+/**
+ * Full card: file-type badge, title, external-link action, excerpt, and a
+ * page footer. Matches the Figma `citation card` frame.
+ */
+export const Default: Story = {
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * No `url` — the external-link action is hidden. Use for sources that can't
+ * be opened (e.g. an internal chunk with no servable file).
+ */
+export const WithoutLink: Story = {
+  args: { url: undefined },
+};
+
+/**
+ * No `locationLabel` — the footer is hidden. Use for non-paginated sources
+ * such as a plain web page or a whole-document citation.
+ */
+export const WithoutLocation: Story = {
+  args: { locationLabel: undefined },
+};
+
+/**
+ * Minimal: title + excerpt only (no link, no location). The leanest source a
+ * card can describe.
+ */
+export const MinimalSnippetOnly: Story = {
+  args: { url: undefined, locationLabel: undefined },
+};
+
+/**
+ * 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.
+ */
+export const LongFileName: Story = {
+  args: {
+    fileName:
+      'Annual-Strategy-And-Operational-Review-And-Lessons-Learned-Digital-Transformation-Phase-1-FY2026-Final-APPROVED-v3.pdf',
+  },
+};
+
+/**
+ * A long excerpt wraps freely — the card grows vertically while keeping its
+ * fixed width.
+ */
+export const LongSnippet: Story = {
+  args: {
+    snippet: `${LOREM} ${LOREM}`,
+  },
+};
+
+/**
+ * The file-type badge derives its icon and tone from the file extension:
+ * `.pdf`/`.docx` → pink, `.md`/`.html` → soft, `.csv`/`.xlsx` → yellow.
+ */
+export const FileTypeVariants: Story = {
+  render: (args) => ({
+    components: { CkCitationCard },
+    setup() {
+      const files = [
+        'q3-report.pdf',
+        'README.md',
+        'sales-2026.csv',
+        'notes.txt',
+      ];
+      return { args, files };
+    },
+    template: `
+      <div style="display: flex; flex-direction: column; gap: 16px;">
+        <CkCitationCard
+          v-for="f in files"
+          :key="f"
+          v-bind="args"
+          :file-name="f"
+        />
+      </div>
+    `,
+  }),
+};