@aleph-alpha/chat-kit 3.3.0 → 4.0.0

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

@@ -0,0 +1,49 @@
+import CkRegenerateMessageButton from './CkRegenerateMessageButton.vue';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '@testing-library/vue';
+import { describe, expect, it } from 'vitest';
+
+describe('CkRegenerateMessageButton', () => {
+  it('renders an accessible button with the default label', () => {
+    render(CkRegenerateMessageButton);
+
+    expect(
+      screen.getByRole('button', { name: 'Regenerate response' }),
+    ).toBeInTheDocument();
+  });
+
+  it('uses a custom aria-label when provided', () => {
+    render(CkRegenerateMessageButton, {
+      props: { ariaLabel: 'Try again' },
+    });
+
+    expect(
+      screen.getByRole('button', { name: 'Try again' }),
+    ).toBeInTheDocument();
+  });
+
+  it('emits regenerate when clicked', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkRegenerateMessageButton);
+
+    await user.click(
+      screen.getByRole('button', { name: 'Regenerate response' }),
+    );
+
+    expect(emitted('regenerate')).toEqual([[]]);
+  });
+
+  it('does not emit regenerate when disabled', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkRegenerateMessageButton, {
+      props: { disabled: true },
+    });
+
+    const button = screen.getByRole('button', { name: 'Regenerate response' });
+    expect(button).toBeDisabled();
+
+    await user.click(button);
+
+    expect(emitted('regenerate')).toBeUndefined();
+  });
+});

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

@@ -0,0 +1,63 @@
+import CkRegenerateMessageButton from './CkRegenerateMessageButton.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+
+const meta: Meta<typeof CkRegenerateMessageButton> = {
+  title: 'Base/CkRegenerateMessageButton',
+  component: CkRegenerateMessageButton,
+  tags: ['autodocs'],
+  argTypes: {
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the button is disabled and ignores clicks.',
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible label and tooltip content for the button.',
+    },
+  },
+  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 { CkRegenerateMessageButton } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <CkRegenerateMessageButton @regenerate="() => {}" />
+</template>`;
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { CkRegenerateMessageButton } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <CkRegenerateMessageButton disabled />
+</template>`;
+
+/**
+ * Default regenerate action. Clicking emits a `regenerate` event so the host
+ * can request a new response for the message.
+ */
+export const Default: Story = {
+  args: {},
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * Disabled state — clicks are ignored and the button appears inactive.
+ * Use while a message is still streaming or in an error state.
+ */
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+  parameters: { docs: { source: { code: disabledTemplateSource } } },
+};

package/src/components/base/CkRegenerateMessageButton/CkRegenerateMessageButton.vue

@@ -0,0 +1,43 @@
+<script setup lang="ts">
+import { CkMessageButton } from '../CkMessageButton';
+import type { CkRegenerateMessageButtonProps } from './types';
+import { UiIcon, UiTooltip } from '@aleph-alpha/ui-library';
+
+defineOptions({
+  name: 'CkRegenerateMessageButton',
+});
+
+const props = withDefaults(defineProps<CkRegenerateMessageButtonProps>(), {
+  disabled: false,
+  ariaLabel: 'Regenerate response',
+});
+
+const emit = defineEmits<{
+  regenerate: [];
+}>();
+
+function handleClick() {
+  if (props.disabled) {
+    return;
+  }
+
+  emit('regenerate');
+}
+</script>
+
+<template>
+  <UiTooltip
+    :content="ariaLabel"
+    side="bottom"
+    align="center"
+    :delay-duration="0"
+  >
+    <CkMessageButton
+      v-bind="{ ariaLabel }"
+      :disabled="disabled"
+      @click="handleClick"
+    >
+      <UiIcon name="repeat" :size="16" aria-hidden="true" />
+    </CkMessageButton>
+  </UiTooltip>
+</template>

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

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

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

@@ -0,0 +1,27 @@
+/**
+ * Regenerate action button for chat messages. Lets the user request a new
+ * response for an assistant message. Renders an icon-only button with an
+ * accessible label and tooltip.
+ *
+ * @category Actions
+ * @useCases regenerate assistant reply, retry message, request new response, chat message action
+ * @keywords regenerate, retry, repeat, action, message, button, icon
+ * @related CkMessageButton, CkCopyMessageButton, CkAgentMessage, CkConversation
+ */
+export interface CkRegenerateMessageButtonProps {
+  /**
+   * Whether the button is disabled and ignores clicks.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Accessible label and tooltip content for the button.
+   * @default 'Regenerate response'
+   */
+  ariaLabel?: string;
+}
+
+export interface CkRegenerateMessageButtonEmits {
+  /** Emitted when the button is pressed and not disabled. */
+  (e: 'regenerate'): void;
+}

package/src/components/base/index.ts

@@ -13,7 +13,7 @@ export type {
 } from './CkCitationCard';
 export { CkConversationLayout } from './CkConversationLayout';
 export type { CkConversationLayoutProps } from './CkConversationLayout';
-export { CkCopyMessageActionButton } from './CkCopyMessageActionButton';
+export { CkCopyMessageButton } from './CkCopyMessageButton';
 export { CkDropZoneOverlay } from './CkDropZoneOverlay';
 export type {
   CkDropZoneOverlayProps,
@@ -50,7 +50,7 @@ export type {
   CkMarkdownRendererEmits,
   CkMarkdownElementClasses,
 } from './CkMarkdownRenderer';
-export { CkMessageActionButton } from './CkMessageActionButton';
+export { CkMessageButton } from './CkMessageButton';
 export { CkModelSelector } from './CkModelSelector';
 export type {
   CkModelOption,
@@ -63,5 +63,6 @@ export type { CkPromptMenuButtonProps } from './CkPromptMenuButton';
 export { CkPromptStopButton } from './CkPromptStopButton';
 export { CkPromptInput } from './CkPromptInput';
 export { CkPromptInputDisclaimer } from './CkPromptInputDisclaimer';
+export { CkRegenerateMessageButton } from './CkRegenerateMessageButton';
 export { CkUserMessage } from './CkUserMessage';
 export type { CkUserMessageProps } from './CkUserMessage';

package/src/components/composed/CkConversation/CkConversation.stories.ts

@@ -1,4 +1,4 @@
-import { CkCopyMessageActionButton } from '../../base/CkCopyMessageActionButton';
+import { CkCopyMessageButton } from '../../base/CkCopyMessageButton';
 import { CkFeedbackButton } from '../../base/CkFeedbackButton';
 import type { CkFeedbackValue } from '../../base/CkFeedbackButton';
 import type {
@@ -292,7 +292,7 @@ const withFooterActionsTemplateSource = `<script setup lang="ts">
 import { ref } from 'vue';
 import {
   CkConversation,
-  CkCopyMessageActionButton,
+  CkCopyMessageButton,
   CkFeedbackButton,
 } from '@aleph-alpha/chat-kit';
 import type { BaseMessage, CkFeedbackValue } from '@aleph-alpha/chat-kit';
@@ -315,7 +315,7 @@ function onFeedback(messageId: string, value: CkFeedbackValue) {
 <template>
   <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;">
     <template #agent-message-footer="{ message }">
-      <CkCopyMessageActionButton :text="getMessageText(message)" />
+      <CkCopyMessageButton :text="getMessageText(message)" />
       <CkFeedbackButton
         :value="feedback[message.id]?.value ?? null"
         :locked="feedback[message.id]?.locked ?? false"
@@ -590,7 +590,7 @@ export const WithCustomIcon: Story = {
 
 /**
  * Overrides `#agent-message-footer` to add real action buttons next to each
- * assistant reply: `CkCopyMessageActionButton` for clipboard copy and
+ * assistant reply: `CkCopyMessageButton` for clipboard copy and
  * `CkFeedbackButton` for binary thumbs up / thumbs down feedback. The
  * feedback state is owned by the host and locked once submitted.
  */
@@ -598,7 +598,7 @@ export const WithFooterActions: Story = {
   render: () => ({
     components: {
       CkConversation,
-      CkCopyMessageActionButton,
+      CkCopyMessageButton,
       CkFeedbackButton,
     },
     setup() {
@@ -618,7 +618,7 @@ export const WithFooterActions: Story = {
     template: `
       <CkConversation :messages="messages" agent-avatar-fallback="AI" style="height: 100%;">
         <template #agent-message-footer="{ message }">
-          <CkCopyMessageActionButton :text="getMessageText(message)" />
+          <CkCopyMessageButton :text="getMessageText(message)" />
           <CkFeedbackButton
             :value="feedback[message.id]?.value ?? null"
             :locked="feedback[message.id]?.locked ?? false"

package/src/components/composed/CkConversation/CkConversation.vue

@@ -3,7 +3,7 @@ import { useChatKitLabels } from '../../../handlers/useChatKitLabels';
 import type { BaseMessage, MessageTextContent } from '../../../types';
 import CkAgentMessage from '../../base/CkAgentMessage/CkAgentMessage.vue';
 import CkConversationLayout from '../../base/CkConversationLayout/CkConversationLayout.vue';
-import CkCopyMessageActionButton from '../../base/CkCopyMessageActionButton/CkCopyMessageActionButton.vue';
+import CkCopyMessageButton from '../../base/CkCopyMessageButton/CkCopyMessageButton.vue';
 import CkMarkdownRenderer from '../../base/CkMarkdownRenderer/CkMarkdownRenderer.vue';
 import CkUserMessage from '../../base/CkUserMessage/CkUserMessage.vue';
 import type { CkConversationProps } from './types';
@@ -143,7 +143,7 @@ function getMessageText(message: BaseMessage): string {
 
           <template #footer>
             <slot name="agent-message-footer" :message="message">
-              <CkCopyMessageActionButton
+              <CkCopyMessageButton
                 v-if="getMessageText(message) && !isLoading(message)"
                 :text="getMessageText(message)"
                 :aria-label-copy="labels.copyMessageAction"

package/src/components/composed/CkConversation/types.ts

@@ -10,7 +10,7 @@ import type { CkMarkdownElementClasses } from '../../base/CkMarkdownRenderer';
  * @category Messages
  * @useCases complete chat conversation ui, streaming chat with markdown, assistant chat view, llm conversation component, drop-in chat surface
  * @keywords conversation, chat, messages, assistant, agent, user, markdown, streaming, avatar
- * @related CkConversationLayout, CkAgentMessage, CkUserMessage, CkMarkdownRenderer, CkCopyMessageActionButton, CkInput
+ * @related CkConversationLayout, CkAgentMessage, CkUserMessage, CkMarkdownRenderer, CkCopyMessageButton, CkInput
  */
 export interface CkConversationProps {
   /** List of messages to display, in chronological order. */

package/src/components/index.ts

@@ -4,7 +4,7 @@ export {
   CkCitation,
   CkCitationCard,
   CkConversationLayout,
-  CkCopyMessageActionButton,
+  CkCopyMessageButton,
   CkDropZoneOverlay,
   CkFeedbackButton,
   CkFeedbackDialog,
@@ -12,13 +12,14 @@ export {
   CkHistoryItem,
   CkHistoryWrapper,
   CkMarkdownRenderer,
-  CkMessageActionButton,
+  CkMessageButton,
   CkModelSelector,
   CkPromptSendButton,
   CkPromptMenuButton,
   CkPromptStopButton,
   CkPromptInput,
   CkPromptInputDisclaimer,
+  CkRegenerateMessageButton,
   CkSendIcon,
   CkStopIcon,
   CkUserMessage,

package/src/handlers/useChatKitLabels.spec.ts

@@ -102,6 +102,7 @@ describe('useChatKitLabels', () => {
       inputPlaceholder: 'Custom placeholder',
       copyMessageAction: 'Custom copy',
       copyMessageActionCopied: 'Custom copied',
+      regenerateMessageAction: 'Custom regenerate',
       feedbackThumbsUp: 'Custom up',
       feedbackThumbsDown: 'Custom down',
       feedbackGroup: 'Custom group',

package/src/handlers/useChatKitLabels.ts

@@ -29,6 +29,8 @@ export type ChatKitLabels = {
   copyMessageAction: string;
   /** Accessible label / tooltip for the copy-message action button after a successful copy */
   copyMessageActionCopied: string;
+  /** Accessible label / tooltip for the regenerate-message action button */
+  regenerateMessageAction: string;
   /**
    * Accessible label / tooltip for the thumbs-up button in `CkFeedbackButton`.
    * Optional for backward compatibility; falls back to
@@ -114,6 +116,7 @@ export const defaultChatKitLabels: ChatKitLabels = {
   inputPlaceholder: 'Type a message...',
   copyMessageAction: 'Copy response',
   copyMessageActionCopied: 'Copied!',
+  regenerateMessageAction: 'Regenerate response',
   feedbackThumbsUp: 'Good response',
   feedbackThumbsDown: 'Bad response',
   feedbackGroup: 'Rate this response',

package/src/handlers/useMessageHandler.spec.ts

@@ -146,6 +146,36 @@ describe('useMessageHandler', () => {
       expect('metadata' in msg).toBe(false);
       expect('metadata' in handler.messages.value[0]).toBe(false);
     });
+
+    it('branches off an explicit parentId, updating the parent and activating the new branch', () => {
+      const handler = useMessageHandler();
+
+      handler.setCurrentUserMessage('First');
+      const first = handler.commitUserMessage();
+      handler.setCurrentUserMessage('Second');
+      const second = handler.commitUserMessage();
+
+      // Branch a sibling of `second` off their shared parent `first`.
+      handler.setCurrentUserMessage('Sibling');
+      const sibling = handler.commitUserMessage({ parentId: first.id });
+
+      const parent = handler.getTree().nodes[first.id];
+      expect(parent.childrenIds).toEqual([second.id, sibling.id]);
+      // The freshly created branch becomes the active path.
+      expect(parent.activeChildIndex).toBe(1);
+      expect(handler.messages.value.map((m) => m.id)).toEqual([
+        first.id,
+        sibling.id,
+      ]);
+    });
+
+    it('throws when branching off an unknown parentId', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      expect(() =>
+        handler.commitUserMessage({ parentId: 'does-not-exist' }),
+      ).toThrow('Unknown parent message id: does-not-exist');
+    });
   });
 
   describe('updateMessage', () => {
@@ -342,6 +372,55 @@ describe('useMessageHandler', () => {
       expect(handler.messages.value).toHaveLength(2);
       expect(getText(handler.messages.value[1].content)).toBe('Streaming...');
     });
+
+    it('branches a new node off an explicit parentId on create', () => {
+      const handler = useMessageHandler();
+      handler.setTree(
+        makeTree(
+          {
+            u1: makeTreeMessage({ id: 'u1', content: [text('Hello')] }),
+            a1: makeTreeMessage({
+              id: 'a1',
+              parentId: 'u1',
+              role: 'assistant',
+              content: [text('Hi')],
+            }),
+          },
+          'u1',
+        ),
+      );
+
+      // Regenerate: add a sibling assistant answer under the same user turn.
+      handler.updateMessage({
+        id: 'a2',
+        content: [text('Hi again')],
+        role: 'assistant',
+        status: 'completed',
+        parentId: 'u1',
+      });
+
+      const parent = handler.getTree().nodes.u1;
+      expect(parent.childrenIds).toEqual(['a1', 'a2']);
+      expect(parent.activeChildIndex).toBe(1);
+      expect(handler.messages.value.map((m) => m.id)).toEqual(['u1', 'a2']);
+    });
+
+    it('ignores parentId when the node already exists', () => {
+      const handler = useMessageHandler();
+      handler.setCurrentUserMessage('Hello');
+      const msg = handler.commitUserMessage();
+
+      handler.updateMessage({
+        id: msg.id,
+        content: [text('Updated')],
+        role: 'user',
+        status: 'completed',
+        parentId: 'does-not-exist',
+      });
+
+      expect(getText(handler.getMessageById(msg.id)!.content)).toBe('Updated');
+      expect(handler.getTree().nodes[msg.id].parentId).toBeNull();
+    });
   });
 
   describe('getMessageById', () => {

package/src/handlers/useMessageHandler.ts

@@ -3,6 +3,7 @@ import {
   addNode as treeAddNode,
   createEmptyTree,
   cutBranchAfter as treeCutBranchAfter,
+  cutBranchAt as treeCutBranchAt,
   getLinearPath,
   navigate as treeNavigate,
   updateNode,
@@ -30,6 +31,19 @@ export const useMessageHandler = () => {
     return list.length > 0 ? list[list.length - 1].id : null;
   });
 
+  /**
+   * Resolve the parent a new node should hang off. When an explicit
+   * `parentId` is given it must reference an existing node; otherwise the
+   * current leaf is used so messages append to the active branch.
+   */
+  function resolveParentId(parentId?: string): string | null {
+    if (parentId === undefined) return currentLeafId.value;
+    if (!tree.nodes[parentId]) {
+      throw new Error(`Unknown parent message id: ${parentId}`);
+    }
+    return parentId;
+  }
+
   function setCurrentUserMessage(text: string) {
     currentUserMessage.value = text;
   }
@@ -38,20 +52,31 @@ export const useMessageHandler = () => {
     currentUserMessage.value = '';
   }
 
+  /**
+   * Commit the pending user message as a new node.
+   *
+   * By default the node is appended to the current leaf. Pass `parentId` to
+   * branch off an arbitrary message instead: the new node becomes a sibling
+   * of that parent's existing children, the parent's `childrenIds` gains the
+   * new id, and the branch is made active.
+   */
   function commitUserMessage(opts?: {
     metadata?: MessageMetadata;
+    parentId?: string;
   }): BaseMessage {
     const id = generateId();
     const text = currentUserMessage.value.trim();
     if (!text) throw new Error('No message');
 
+    const parentId = resolveParentId(opts?.parentId);
+
     const content: MessageContent[] = [
       { type: 'text', id: generateId(), text, status: 'completed' },
     ];
 
     const node: TreeMessage = {
       id,
-      parentId: currentLeafId.value,
+      parentId,
       childrenIds: [],
       activeChildIndex: 0,
       role: 'user',
@@ -75,12 +100,20 @@ export const useMessageHandler = () => {
     return base;
   }
 
+  /**
+   * Upsert a message by id. When the node does not yet exist it is created;
+   * pass `parentId` to branch the new node off an arbitrary message instead
+   * of the current leaf (the parent's `childrenIds` is updated and the new
+   * branch is made active). `parentId` is ignored when the node already
+   * exists.
+   */
   function updateMessage(message: {
     id: string;
     content: MessageContent[];
     role: MessageRole;
     status: MessageStatus;
     metadata?: MessageMetadata;
+    parentId?: string;
   }) {
     const existing = tree.nodes[message.id];
 
@@ -96,7 +129,7 @@ export const useMessageHandler = () => {
     } else {
       const node: TreeMessage = {
         id: message.id,
-        parentId: currentLeafId.value,
+        parentId: resolveParentId(message.parentId),
         childrenIds: [],
         activeChildIndex: 0,
         role: message.role,
@@ -159,6 +192,19 @@ export const useMessageHandler = () => {
     treeCutBranchAfter(tree, messageId);
   }
 
+  /**
+   * Drop the message with `messageId` and its whole subtree, leaving sibling
+   * branches intact (the parent's active branch is clamped to a survivor).
+   * Use to discard one answer among several without cropping the others.
+   */
+  function cutBranchAt(messageId: string) {
+    treeCutBranchAt(tree, messageId);
+  }
+
+  function getTree() {
+    return readonly(tree);
+  }
+
   return {
     messages: messages as Ref<BaseMessage[]>,
     currentUserMessage: readonly(currentUserMessage),
@@ -173,5 +219,7 @@ export const useMessageHandler = () => {
     setTree,
     navigate,
     cutBranchAfter,
+    cutBranchAt,
+    getTree,
   };
 };