@aleph-alpha/chat-kit 3.2.0 → 4.0.0

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

package/src/components/base/CkCitationCard/CkCitationCard.vue

@@ -0,0 +1,76 @@
+<script setup lang="ts">
+import { computed } from 'vue';
+import { UiFileType, UiButton, UiIcon } from '@aleph-alpha/ui-library';
+import {
+  defaultChatKitLabels,
+  useChatKitLabels,
+} from '../../../handlers/useChatKitLabels';
+import type { CkCitationCardProps } from './types';
+
+defineOptions({
+  name: 'CkCitationCard',
+});
+
+const props = withDefaults(defineProps<CkCitationCardProps>(), {
+  locationLabel: undefined,
+  url: undefined,
+  openSourceLabel: undefined,
+});
+
+const emit = defineEmits<{
+  'open-source': [url: string];
+}>();
+
+const labels = useChatKitLabels();
+
+// Resolution order: per-instance prop, injected label, English default.
+const openSourceAriaLabel = computed(
+  () =>
+    props.openSourceLabel ??
+    labels.value.citationOpenSource ??
+    defaultChatKitLabels.citationOpenSource!,
+);
+
+function handleOpen(): void {
+  if (props.url) {
+    emit('open-source', props.url);
+  }
+}
+</script>
+
+<template>
+  <div
+    class="ck-citation-card flex w-[22.5rem] max-w-[90vw] flex-col gap-2 rounded-md bg-background-surface-floating px-6 pb-6 pt-4 shadow-md"
+  >
+    <div class="flex items-center gap-3">
+      <UiFileType :filename="fileName" class="shrink-0" />
+      <p
+        class="min-w-0 flex-1 truncate text-sm font-medium text-content-on-surface-primary"
+        :title="fileName"
+      >
+        {{ fileName }}
+      </p>
+      <UiButton
+        v-if="url"
+        variant="ghost"
+        size="icon-sm"
+        :aria-label="openSourceAriaLabel"
+        class="shrink-0"
+        @click="handleOpen"
+      >
+        <UiIcon name="external-link" :size="16" aria-hidden="true" />
+      </UiButton>
+    </div>
+
+    <p class="break-words text-sm leading-5 text-content-on-surface-secondary">
+      {{ snippet }}
+    </p>
+
+    <p
+      v-if="locationLabel"
+      class="text-sm leading-5 text-content-on-surface-muted"
+    >
+      {{ locationLabel }}
+    </p>
+  </div>
+</template>

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

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

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

@@ -0,0 +1,51 @@
+/**
+ * The floating card that describes a single citation source: the source file,
+ * the cited excerpt, an optional location (e.g. page), and an optional
+ * external-link action. Rendered as the hover/focus content of `CkCitation`,
+ * but usable on its own wherever a source preview is needed.
+ *
+ * Purely presentational and prop-driven. The external-link action is exposed
+ * as an `open-source` event rather than a plain link, because the source URL
+ * is often auth-proxied and cannot be navigated to directly.
+ *
+ * @category Data Display
+ * @useCases citation source preview, hover card for an inline reference, show the cited file/page/excerpt
+ * @keywords citation, source, card, popover, reference, file, page, excerpt, preview
+ * @related CkCitation, CkMarkdownRenderer, CkAgentMessage
+ */
+export interface CkCitationCardProps {
+  /**
+   * Source file name. Rendered as the card title and used to derive the
+   * file-type badge icon/tone (pass the original name with its extension,
+   * e.g. `q3-report.pdf`).
+   */
+  fileName: string;
+  /** The cited chunk text, shown in the card body. */
+  snippet: string;
+  /**
+   * Location label shown in the footer, e.g. `"Page 3"`. Pass a fully
+   * formatted, localized string — the component does no number formatting.
+   * Omit for non-paginated sources to hide the footer.
+   */
+  locationLabel?: string;
+  /**
+   * When set, the external-link action is shown in the header. Activating it
+   * emits `open-source` with this value; the host opens it (it may be an
+   * auth-proxied URL that can't be a plain link). Omit to hide the action.
+   */
+  url?: string;
+  /**
+   * Accessible label for the external-link action. When omitted, resolves from
+   * `useChatKitLabels().citationOpenSource` (English default `"Open source"`).
+   * Set this to override per instance.
+   */
+  openSourceLabel?: string;
+}
+
+export interface CkCitationCardEmits {
+  /**
+   * Emitted when the user activates the header external-link action. The
+   * payload is `url`. Only emitted when `url` is set.
+   */
+  (e: 'open-source', url: string): void;
+}

package/src/components/base/{CkCopyMessageActionButton/CkCopyMessageActionButton.spec.ts → CkCopyMessageButton/CkCopyMessageButton.spec.ts}

@@ -1,10 +1,10 @@
-import CkCopyMessageActionButton from './CkCopyMessageActionButton.vue';
+import CkCopyMessageButton from './CkCopyMessageButton.vue';
 import userEvent from '@testing-library/user-event';
 import { render, screen, waitFor } from '@testing-library/vue';
 import { flushPromises } from '@vue/test-utils';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 
-describe('CkCopyMessageActionButton', () => {
+describe('CkCopyMessageButton', () => {
   const writeText = vi.fn((_: string) => Promise.resolve());
 
   beforeEach(() => {
@@ -14,7 +14,7 @@ describe('CkCopyMessageActionButton', () => {
 
   it('emits copy with success when clipboard succeeds', async () => {
     const user = userEvent.setup();
-    const { emitted } = render(CkCopyMessageActionButton, {
+    const { emitted } = render(CkCopyMessageButton, {
       props: { text: 'x', writeToClipboard: writeText },
     });
 
@@ -27,7 +27,7 @@ describe('CkCopyMessageActionButton', () => {
 
   it('copies text and updates the accessible name', async () => {
     const user = userEvent.setup();
-    render(CkCopyMessageActionButton, {
+    render(CkCopyMessageButton, {
       props: { text: 'Hello, world', writeToClipboard: writeText },
     });
 
@@ -50,7 +50,7 @@ describe('CkCopyMessageActionButton', () => {
 
     it('emits copy with success false', async () => {
       const user = userEvent.setup();
-      const { emitted } = render(CkCopyMessageActionButton, {
+      const { emitted } = render(CkCopyMessageButton, {
         props: { text: 'x', writeToClipboard: writeText },
       });
 
@@ -67,7 +67,7 @@ describe('CkCopyMessageActionButton', () => {
   it('reverts label after durationMs', async () => {
     vi.useFakeTimers();
     const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    render(CkCopyMessageActionButton, {
+    render(CkCopyMessageButton, {
       props: { text: 'x', durationMs: 1500, writeToClipboard: writeText },
     });
 

package/src/components/base/{CkCopyMessageActionButton/CkCopyMessageActionButton.stories.ts → CkCopyMessageButton/CkCopyMessageButton.stories.ts}

@@ -1,9 +1,9 @@
-import CkCopyMessageActionButton from './CkCopyMessageActionButton.vue';
+import CkCopyMessageButton from './CkCopyMessageButton.vue';
 import type { Meta, StoryObj } from '@storybook/vue3-vite';
 
-const meta: Meta<typeof CkCopyMessageActionButton> = {
-  title: 'Base/CkCopyMessageActionButton',
-  component: CkCopyMessageActionButton,
+const meta: Meta<typeof CkCopyMessageButton> = {
+  title: 'Base/CkCopyMessageButton',
+  component: CkCopyMessageButton,
   tags: ['autodocs'],
   argTypes: {
     text: {
@@ -31,19 +31,19 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 const defaultTemplateSource = `<script setup lang="ts">
-import { CkCopyMessageActionButton } from '@aleph-alpha/chat-kit';
+import { CkCopyMessageButton } from '@aleph-alpha/chat-kit';
 </script>
 
 <template>
-  <CkCopyMessageActionButton text="Sample assistant reply text to copy." />
+  <CkCopyMessageButton text="Sample assistant reply text to copy." />
 </template>`;
 
 const disabledTemplateSource = `<script setup lang="ts">
-import { CkCopyMessageActionButton } from '@aleph-alpha/chat-kit';
+import { CkCopyMessageButton } from '@aleph-alpha/chat-kit';
 </script>
 
 <template>
-  <CkCopyMessageActionButton text="Cannot copy when disabled." disabled />
+  <CkCopyMessageButton text="Cannot copy when disabled." disabled />
 </template>`;
 
 /**

package/src/components/base/{CkCopyMessageActionButton/CkCopyMessageActionButton.vue → CkCopyMessageButton/CkCopyMessageButton.vue}

@@ -1,14 +1,14 @@
 <script setup lang="ts">
-import { CkMessageActionButton } from '../CkMessageActionButton';
-import type { CkCopyMessageActionButtonProps } from './types';
+import { CkMessageButton } from '../CkMessageButton';
+import type { CkCopyMessageButtonProps } from './types';
 import { UiIcon, UiTooltip } from '@aleph-alpha/ui-library';
 import { onUnmounted, ref } from 'vue';
 
 defineOptions({
-  name: 'CkCopyMessageActionButton',
+  name: 'CkCopyMessageButton',
 });
 
-const props = withDefaults(defineProps<CkCopyMessageActionButtonProps>(), {
+const props = withDefaults(defineProps<CkCopyMessageButtonProps>(), {
   disabled: false,
   durationMs: 3000,
   ariaLabelCopy: 'Copy message',
@@ -68,7 +68,7 @@ async function handleClick() {
     align="center"
     :delay-duration="0"
   >
-    <CkMessageActionButton
+    <CkMessageButton
       v-bind="{ ariaLabel: copied ? ariaLabelCopied : ariaLabelCopy }"
       :disabled="disabled"
       @click="handleClick"
@@ -83,7 +83,7 @@ async function handleClick() {
         />
         <UiIcon v-else key="check" name="check" :size="16" aria-hidden="true" />
       </Transition>
-    </CkMessageActionButton>
+    </CkMessageButton>
     <span class="sr-only" aria-live="polite">
       {{ copied ? ariaLabelCopied : ariaLabelCopy }}
     </span>

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

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

package/src/components/base/{CkCopyMessageActionButton → CkCopyMessageButton}/types.ts

@@ -5,9 +5,9 @@
  * @category Actions
  * @useCases copy assistant reply, copy message to clipboard, chat message action, feedback action on message footer
  * @keywords copy, clipboard, action, message, button, icon, feedback
- * @related CkMessageActionButton, CkAgentMessage, CkConversation
+ * @related CkMessageButton, CkAgentMessage, CkConversation
  */
-export interface CkCopyMessageActionButtonProps {
+export interface CkCopyMessageButtonProps {
   /** Plain text to copy to the clipboard. */
   text: string;
   /**
@@ -37,7 +37,7 @@ export interface CkCopyMessageActionButtonProps {
   writeToClipboard?: (text: string) => Promise<void>;
 }
 
-export interface CkCopyMessageActionButtonEmits {
+export interface CkCopyMessageButtonEmits {
   /** Emitted after the clipboard operation finishes (success or failure). */
   (e: 'copy', payload: { success: boolean }): void;
 }

package/src/components/base/CkFeedbackButton/CkFeedbackButton.vue

@@ -3,7 +3,7 @@ import {
   defaultChatKitLabels,
   useChatKitLabels,
 } from '../../../handlers/useChatKitLabels';
-import { CkMessageActionButton } from '../CkMessageActionButton';
+import { CkMessageButton } from '../CkMessageButton';
 import type { CkFeedbackButtonProps, CkFeedbackValue } from './types';
 import { UiIcon, UiTooltip } from '@aleph-alpha/ui-library';
 import { computed } from 'vue';
@@ -81,7 +81,7 @@ function handleClick(target: 'up' | 'down'): void {
       align="center"
       :delay-duration="0"
     >
-      <CkMessageActionButton
+      <CkMessageButton
         v-bind="{ ariaLabel: thumbsUpLabel }"
         :aria-pressed="isUpSelected"
         :aria-disabled="locked || undefined"
@@ -98,7 +98,7 @@ function handleClick(target: 'up' | 'down'): void {
           aria-hidden="true"
           :class="isUpSelected ? 'fill-current' : undefined"
         />
-      </CkMessageActionButton>
+      </CkMessageButton>
     </UiTooltip>
     <UiTooltip
       :content="thumbsDownLabel"
@@ -106,7 +106,7 @@ function handleClick(target: 'up' | 'down'): void {
       align="center"
       :delay-duration="0"
     >
-      <CkMessageActionButton
+      <CkMessageButton
         v-bind="{ ariaLabel: thumbsDownLabel }"
         :aria-pressed="isDownSelected"
         :aria-disabled="locked || undefined"
@@ -123,7 +123,7 @@ function handleClick(target: 'up' | 'down'): void {
           aria-hidden="true"
           :class="isDownSelected ? 'fill-current' : undefined"
         />
-      </CkMessageActionButton>
+      </CkMessageButton>
     </UiTooltip>
   </div>
 </template>

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

@@ -10,7 +10,7 @@
  * @category Feedback
  * @useCases like or dislike an assistant reply, collect binary message rating, lock feedback after submission, rate AI response
  * @keywords feedback, thumbs up, thumbs down, like, dislike, rating, vote, action, message, button
- * @related CkMessageActionButton, CkCopyMessageActionButton, CkAgentMessage, CkConversation
+ * @related CkMessageButton, CkCopyMessageButton, CkAgentMessage, CkConversation
  */
 export type CkFeedbackValue = 'up' | 'down' | null;
 

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

@@ -18,7 +18,7 @@
  *   capture a free-text comment, drive a two-step rating flow
  * @keywords feedback, dialog, modal, reason codes, free text, qualitative,
  *   rating, comment
- * @related CkFeedbackButton, CkMessageActionButton, CkAgentMessage,
+ * @related CkFeedbackButton, CkMessageButton, CkAgentMessage,
  *   CkConversation, UiDialog, UiToggleGroup
  */
 export type CkFeedbackSentiment = 'positive' | 'negative';