@aleph-alpha/chat-kit 1.1.0 → 1.3.0

package/dist/{useConversations-Ca242D2P.js → useConversationSessions-ulFhtpQr.js}

@@ -1,5 +1,6 @@
-import { g as generateId } from "./generateId-BHf0W4Rq.js";
+import { g as generateId, u as useMessageHandler } from "./useMessageHandler-BmBdu2EW.js";
 import { ref, shallowRef, computed, readonly } from "vue";
+import "./purify.es-md74IFlY.js";
 function secondsToDate(seconds) {
   return new Date(seconds * 1e3);
 }
@@ -189,7 +190,54 @@ function makePlaceholder(title) {
     updatedAt: now
   };
 }
+function useConversationSessions() {
+  const sessions = /* @__PURE__ */ new Map();
+  const focusedId = ref(null);
+  function createSession(conversationId) {
+    const existing = sessions.get(conversationId);
+    if (existing) return existing;
+    const session = {
+      id: conversationId,
+      messageHandler: useMessageHandler()
+    };
+    sessions.set(conversationId, session);
+    return session;
+  }
+  function getSession(conversationId) {
+    return sessions.get(conversationId);
+  }
+  function setActiveConversation(conversationId) {
+    if (conversationId === null) {
+      focusedId.value = null;
+      return;
+    }
+    createSession(conversationId);
+    focusedId.value = conversationId;
+  }
+  function removeSession(conversationId) {
+    sessions.delete(conversationId);
+    if (focusedId.value === conversationId) {
+      focusedId.value = null;
+    }
+  }
+  const activeSession = computed(() => {
+    const id = focusedId.value;
+    return id !== null ? sessions.get(id) ?? null : null;
+  });
+  const messageHandler = computed(
+    () => activeSession.value?.messageHandler ?? null
+  );
+  return {
+    activeSession,
+    messageHandler,
+    createSession,
+    getSession,
+    setActiveConversation,
+    removeSession
+  };
+}
 export {
-  useConversations as a,
+  useConversationSessions as a,
+  useConversations as b,
   useChat as u
 };

package/dist/{useMessageHandler-uLHNac39.js → useMessageHandler-BmBdu2EW.js}

@@ -1,4 +1,3 @@
-import { g as generateId } from "./generateId-BHf0W4Rq.js";
 import { reactive, ref, computed, readonly } from "vue";
 function createEmptyTree() {
   return { nodes: {}, rootId: null };
@@ -78,6 +77,9 @@ function navigate(tree, targetId) {
   if (idx === -1) return;
   parent.activeChildIndex = idx;
 }
+function generateId() {
+  return typeof crypto !== "undefined" && "randomUUID" in crypto ? crypto.randomUUID() : String(Date.now());
+}
 const useMessageHandler = () => {
   const tree = reactive(createEmptyTree());
   const currentUserMessage = ref("");
@@ -178,5 +180,6 @@ const useMessageHandler = () => {
   };
 };
 export {
+  generateId as g,
   useMessageHandler as u
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/chat-kit",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Chat kit package for building chat interfaces with Vue",
   "type": "module",
   "main": "./dist/index.js",
@@ -64,7 +64,7 @@
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
     "unified": "^11.0.5",
-    "@aleph-alpha/ui-library": "2.2.0"
+    "@aleph-alpha/ui-library": "2.3.0"
   },
   "devDependencies": {
     "@storybook/addon-a11y": "10.2.17",

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

@@ -0,0 +1,174 @@
+import {
+  defaultChatKitLabels,
+  provideChatKitLabels,
+} from '../../../handlers/useChatKitLabels';
+import CkFeedbackButton from './CkFeedbackButton.vue';
+import userEvent from '@testing-library/user-event';
+import { render, screen } from '@testing-library/vue';
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h } from 'vue';
+
+// Source expected labels from the canonical defaults so the suite asserts
+// behaviour (which button received which event) rather than English copy.
+// `feedbackThumbsUp` / `feedbackThumbsDown` are typed as optional on
+// `ChatKitLabels` (for backward-compatible consumer types), but the defaults
+// object always provides them, so we narrow to `string` for `getByRole`.
+const THUMBS_UP = defaultChatKitLabels.feedbackThumbsUp!;
+const THUMBS_DOWN = defaultChatKitLabels.feedbackThumbsDown!;
+
+describe('CkFeedbackButton', () => {
+  // AC (SPHER-4415): "Each completed assistant message shows thumbs up/down icons."
+  it('renders both thumbs unselected and interactive by default', () => {
+    render(CkFeedbackButton);
+
+    const up = screen.getByRole('button', { name: THUMBS_UP });
+    const down = screen.getByRole('button', { name: THUMBS_DOWN });
+
+    expect(up).not.toBeDisabled();
+    expect(down).not.toBeDisabled();
+    expect(up).toHaveAttribute('aria-pressed', 'false');
+    expect(down).toHaveAttribute('aria-pressed', 'false');
+  });
+
+  // AC (SPHER-4415): "Clicking a thumb submits binary feedback (positive/negative)."
+  it("emits 'up' when the thumbs-up button is clicked", async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkFeedbackButton);
+
+    await user.click(screen.getByRole('button', { name: THUMBS_UP }));
+
+    expect(emitted('update:value')).toEqual([['up']]);
+  });
+
+  it("emits 'down' when the thumbs-down button is clicked", async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkFeedbackButton);
+
+    await user.click(screen.getByRole('button', { name: THUMBS_DOWN }));
+
+    expect(emitted('update:value')).toEqual([['down']]);
+  });
+
+  // AC (SPHER-4452): "Selected (thumbs up active / thumbs down active)" must
+  // be communicated to assistive tech as well as visually.
+  it('reflects the current value via aria-pressed', () => {
+    render(CkFeedbackButton, { props: { value: 'up' } });
+
+    expect(screen.getByRole('button', { name: THUMBS_UP })).toHaveAttribute(
+      'aria-pressed',
+      'true',
+    );
+    expect(screen.getByRole('button', { name: THUMBS_DOWN })).toHaveAttribute(
+      'aria-pressed',
+      'false',
+    );
+  });
+
+  // Pre-lock UX: while feedback is still mutable, users can change their mind.
+  it('lets the user swap directly to the other thumb', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkFeedbackButton, { props: { value: 'up' } });
+
+    await user.click(screen.getByRole('button', { name: THUMBS_DOWN }));
+
+    expect(emitted('update:value')).toEqual([['down']]);
+  });
+
+  it('clears the choice when the selected thumb is clicked again', async () => {
+    const user = userEvent.setup();
+    const { emitted } = render(CkFeedbackButton, { props: { value: 'up' } });
+
+    await user.click(screen.getByRole('button', { name: THUMBS_UP }));
+
+    expect(emitted('update:value')).toEqual([[null]]);
+  });
+
+  // AC (SPHER-4415 + SPHER-4452): "Once submitted, feedback is locked"; the
+  // unselected thumb is non-interactive and the choice cannot be changed.
+  describe('when locked', () => {
+    it('disables the unselected thumb and ignores clicks on the selected one', async () => {
+      const user = userEvent.setup();
+      const { emitted } = render(CkFeedbackButton, {
+        props: { value: 'up', locked: true },
+      });
+
+      const up = screen.getByRole('button', { name: THUMBS_UP });
+      const down = screen.getByRole('button', { name: THUMBS_DOWN });
+
+      expect(up).not.toBeDisabled();
+      expect(down).toBeDisabled();
+
+      await user.click(up);
+      await user.click(down);
+
+      expect(emitted('update:value')).toBeUndefined();
+    });
+  });
+
+  // Documented prop: `disabled` suppresses interaction while the assistant
+  // message is still streaming or in an error state.
+  describe('when disabled', () => {
+    it('disables both thumbs and does not emit', async () => {
+      const user = userEvent.setup();
+      const { emitted } = render(CkFeedbackButton, {
+        props: { disabled: true },
+      });
+
+      const up = screen.getByRole('button', { name: THUMBS_UP });
+      const down = screen.getByRole('button', { name: THUMBS_DOWN });
+
+      expect(up).toBeDisabled();
+      expect(down).toBeDisabled();
+
+      await user.click(up);
+      await user.click(down);
+
+      expect(emitted('update:value')).toBeUndefined();
+    });
+  });
+
+  // Localisation: labels resolve through `useChatKitLabels`, with per-instance
+  // props as the override path for one-off custom strings.
+  describe('label resolution', () => {
+    it('uses labels injected via provideChatKitLabels', () => {
+      const translated = {
+        feedbackThumbsUp: 'Gute Antwort',
+        feedbackThumbsDown: 'Schlechte Antwort',
+      };
+      const Wrapper = defineComponent({
+        setup() {
+          provideChatKitLabels(() => translated);
+          return () => h(CkFeedbackButton);
+        },
+      });
+
+      render(Wrapper);
+
+      expect(
+        screen.getByRole('button', { name: translated.feedbackThumbsUp }),
+      ).toBeInTheDocument();
+      expect(
+        screen.getByRole('button', { name: translated.feedbackThumbsDown }),
+      ).toBeInTheDocument();
+    });
+
+    it('lets per-instance aria-label props override the injected labels', () => {
+      const Wrapper = defineComponent({
+        setup() {
+          provideChatKitLabels(() => ({ feedbackThumbsUp: 'Gute Antwort' }));
+          return () =>
+            h(CkFeedbackButton, { ariaLabelThumbsUp: 'Per-instance up' });
+        },
+      });
+
+      render(Wrapper);
+
+      expect(
+        screen.getByRole('button', { name: 'Per-instance up' }),
+      ).toBeInTheDocument();
+      expect(
+        screen.queryByRole('button', { name: 'Gute Antwort' }),
+      ).not.toBeInTheDocument();
+    });
+  });
+});

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

@@ -0,0 +1,179 @@
+import CkFeedbackButton from './CkFeedbackButton.vue';
+import type { CkFeedbackValue } from './types';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref } from 'vue';
+
+const meta: Meta<typeof CkFeedbackButton> = {
+  title: 'Base/CkFeedbackButton',
+  component: CkFeedbackButton,
+  tags: ['autodocs'],
+  argTypes: {
+    value: {
+      control: 'select',
+      options: [null, 'up', 'down'],
+      description:
+        'Currently selected feedback value. `null` means no choice has been made.',
+    },
+    locked: {
+      control: 'boolean',
+      description:
+        'When `true`, the current value is final: clicks are ignored and the unselected thumb becomes non-interactive.',
+    },
+    disabled: {
+      control: 'boolean',
+      description:
+        'When `true`, both thumbs are disabled regardless of `value`.',
+    },
+    ariaLabelThumbsUp: { control: 'text' },
+    ariaLabelThumbsDown: { control: 'text' },
+    ariaLabelGroup: { control: 'text' },
+  },
+  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 { ref } from 'vue';
+import { CkFeedbackButton } from '@aleph-alpha/chat-kit';
+import type { CkFeedbackValue } from '@aleph-alpha/chat-kit';
+
+const value = ref<CkFeedbackValue>(null);
+</script>
+
+<template>
+  <CkFeedbackButton v-model:value="value" />
+</template>`;
+
+const selectedUpTemplateSource = `<script setup lang="ts">
+import { CkFeedbackButton } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <CkFeedbackButton value="up" />
+</template>`;
+
+const selectedDownTemplateSource = `<script setup lang="ts">
+import { CkFeedbackButton } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <CkFeedbackButton value="down" />
+</template>`;
+
+const lockedTemplateSource = `<script setup lang="ts">
+import { CkFeedbackButton } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <!-- Choice has been submitted; user cannot change it. -->
+  <CkFeedbackButton value="up" locked />
+</template>`;
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { CkFeedbackButton } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <!-- e.g. while the assistant reply is still streaming. -->
+  <CkFeedbackButton disabled />
+</template>`;
+
+const submitOnSelectTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkFeedbackButton } from '@aleph-alpha/chat-kit';
+import type { CkFeedbackValue } from '@aleph-alpha/chat-kit';
+
+const value = ref<CkFeedbackValue>(null);
+const locked = ref(false);
+
+function onUpdate(next: CkFeedbackValue) {
+  value.value = next;
+  if (next !== null) {
+    // Persist to backend, then freeze the choice.
+    locked.value = true;
+  }
+}
+</script>
+
+<template>
+  <CkFeedbackButton :value="value" :locked="locked" @update:value="onUpdate" />
+</template>`;
+
+/**
+ * Default, idle state. Both thumbs are interactive and unfilled. Use this
+ * inside `CkConversation`'s `#agent-message-footer` slot to collect binary
+ * feedback on assistant replies.
+ */
+export const Default: Story = {
+  args: { value: null },
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * Thumbs-up is selected. The icon fills and the button shows a tinted
+ * background to mark the active choice. The host still receives
+ * `update:value` events; pass `locked` to make the choice final.
+ */
+export const SelectedUp: Story = {
+  args: { value: 'up' },
+  parameters: { docs: { source: { code: selectedUpTemplateSource } } },
+};
+
+/**
+ * Thumbs-down is selected. Same affordance as `SelectedUp`, on the other
+ * thumb.
+ */
+export const SelectedDown: Story = {
+  args: { value: 'down' },
+  parameters: { docs: { source: { code: selectedDownTemplateSource } } },
+};
+
+/**
+ * Locked after submission. The chosen thumb stays filled; the other becomes
+ * non-interactive. Clicks no longer emit `update:value`.
+ */
+export const Locked: Story = {
+  args: { value: 'up', locked: true },
+  parameters: { docs: { source: { code: lockedTemplateSource } } },
+};
+
+/**
+ * Both thumbs disabled, for example while the assistant message is still
+ * streaming or after a network error.
+ */
+export const Disabled: Story = {
+  args: { value: null, disabled: true },
+  parameters: { docs: { source: { code: disabledTemplateSource } } },
+};
+
+/**
+ * Realistic flow: the host listens for `update:value`, persists the choice,
+ * then sets `locked` to freeze the control. Click a thumb to see it lock.
+ */
+export const SubmitOnSelect: Story = {
+  render: () => ({
+    components: { CkFeedbackButton },
+    setup() {
+      const value = ref<CkFeedbackValue>(null);
+      const locked = ref(false);
+      function onUpdate(next: CkFeedbackValue) {
+        value.value = next;
+        if (next !== null) {
+          locked.value = true;
+        }
+      }
+      return { value, locked, onUpdate };
+    },
+    template: `
+      <CkFeedbackButton :value="value" :locked="locked" @update:value="onUpdate" />
+    `,
+  }),
+  parameters: { docs: { source: { code: submitOnSelectTemplateSource } } },
+};

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

@@ -0,0 +1,157 @@
+<script setup lang="ts">
+import {
+  defaultChatKitLabels,
+  useChatKitLabels,
+} from '../../../handlers/useChatKitLabels';
+import { CkMessageActionButton } from '../CkMessageActionButton';
+import type { CkFeedbackButtonProps, CkFeedbackValue } from './types';
+import { UiIcon, UiTooltip } from '@aleph-alpha/ui-library';
+import { computed } from 'vue';
+
+defineOptions({
+  name: 'CkFeedbackButton',
+});
+
+const props = withDefaults(defineProps<CkFeedbackButtonProps>(), {
+  value: null,
+  locked: false,
+  disabled: false,
+  ariaLabelThumbsUp: undefined,
+  ariaLabelThumbsDown: undefined,
+  ariaLabelGroup: undefined,
+});
+
+const emit = defineEmits<{
+  'update:value': [value: CkFeedbackValue];
+}>();
+
+const labels = useChatKitLabels();
+
+// Label resolution order: per-instance prop, then injected i18n label, then
+// the English default. The final fallback covers consumers who type their
+// labels object as `ChatKitLabels` without the (optional) feedback keys, so
+// the value is always a string at the call site.
+const thumbsUpLabel = computed(
+  () =>
+    props.ariaLabelThumbsUp ??
+    labels.value.feedbackThumbsUp ??
+    defaultChatKitLabels.feedbackThumbsUp!,
+);
+const thumbsDownLabel = computed(
+  () =>
+    props.ariaLabelThumbsDown ??
+    labels.value.feedbackThumbsDown ??
+    defaultChatKitLabels.feedbackThumbsDown!,
+);
+const groupLabel = computed(
+  () =>
+    props.ariaLabelGroup ??
+    labels.value.feedbackGroup ??
+    defaultChatKitLabels.feedbackGroup!,
+);
+
+const isUpSelected = computed(() => props.value === 'up');
+const isDownSelected = computed(() => props.value === 'down');
+
+// When locked, the unselected thumb is disabled and skipped in the tab order.
+// The selected thumb stays focusable (no native `disabled`) so assistive tech
+// can still announce the locked-in choice via `aria-pressed`, but both thumbs
+// carry `aria-disabled="true"` so screen readers communicate that the choice
+// is no longer interactive. Clicks on either are no-ops, gated by the early
+// return in `handleClick`.
+const isUpDisabled = computed(
+  () => props.disabled || (props.locked && !isUpSelected.value),
+);
+const isDownDisabled = computed(
+  () => props.disabled || (props.locked && !isDownSelected.value),
+);
+
+function handleClick(target: 'up' | 'down'): void {
+  if (props.disabled || props.locked) {
+    return;
+  }
+  const isCurrentlySelected =
+    target === 'up' ? isUpSelected.value : isDownSelected.value;
+  emit('update:value', isCurrentlySelected ? null : target);
+}
+</script>
+
+<template>
+  <div
+    role="group"
+    :aria-label="groupLabel"
+    class="ck-feedback-button flex items-center gap-1"
+  >
+    <UiTooltip
+      :content="thumbsUpLabel"
+      side="bottom"
+      align="center"
+      :delay-duration="0"
+    >
+      <CkMessageActionButton
+        v-bind="{ ariaLabel: thumbsUpLabel }"
+        :aria-pressed="isUpSelected"
+        :aria-disabled="locked || undefined"
+        :disabled="isUpDisabled"
+        :class="[
+          'ck-feedback-button__thumb',
+          { 'ck-feedback-button__thumb--selected': isUpSelected },
+        ]"
+        @click="handleClick('up')"
+      >
+        <UiIcon
+          name="thumbs-up"
+          :size="16"
+          aria-hidden="true"
+          :class="isUpSelected ? 'fill-current' : undefined"
+        />
+      </CkMessageActionButton>
+    </UiTooltip>
+    <UiTooltip
+      :content="thumbsDownLabel"
+      side="bottom"
+      align="center"
+      :delay-duration="0"
+    >
+      <CkMessageActionButton
+        v-bind="{ ariaLabel: thumbsDownLabel }"
+        :aria-pressed="isDownSelected"
+        :aria-disabled="locked || undefined"
+        :disabled="isDownDisabled"
+        :class="[
+          'ck-feedback-button__thumb',
+          { 'ck-feedback-button__thumb--selected': isDownSelected },
+        ]"
+        @click="handleClick('down')"
+      >
+        <UiIcon
+          name="thumbs-down"
+          :size="16"
+          aria-hidden="true"
+          :class="isDownSelected ? 'fill-current' : undefined"
+        />
+      </CkMessageActionButton>
+    </UiTooltip>
+  </div>
+</template>
+
+<style scoped>
+.ck-feedback-button__thumb :deep(button) {
+  transition: background-color 0.15s ease-out;
+}
+
+/* Selected thumbs stay visually emphasised on top of the default ghost
+   variant: the filled icon (via `fill-current`) carries the primary
+   affordance; the tinted background reinforces it without competing with
+   neighbouring action buttons. The token matches `bg-core-bg-tertiary`
+   used elsewhere in chat-kit. */
+.ck-feedback-button__thumb--selected :deep(button) {
+  background-color: var(--core-bg-tertiary);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .ck-feedback-button__thumb :deep(button) {
+    transition-duration: 0.01ms;
+  }
+}
+</style>

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

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

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

@@ -0,0 +1,61 @@
+/**
+ * Binary thumbs up / thumbs down feedback control for assistant messages.
+ * Fully prop-driven: the host application owns the selection and lock state
+ * and decides when (or if) to persist it to a backend.
+ *
+ * Labels default to those provided by `useChatKitLabels` (which can be
+ * translated via `provideChatKitLabels`). The `ariaLabel*` props override
+ * the injected labels on a per-instance basis when set.
+ *
+ * @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
+ */
+export type CkFeedbackValue = 'up' | 'down' | null;
+
+export interface CkFeedbackButtonProps {
+  /**
+   * Currently selected feedback value. `null` means no choice has been made.
+   * @default null
+   */
+  value?: CkFeedbackValue;
+  /**
+   * When `true`, the current `value` is final: clicks are ignored and the
+   * unselected thumb becomes non-interactive. Use after the host has
+   * persisted the user's choice.
+   * @default false
+   */
+  locked?: boolean;
+  /**
+   * When `true`, both thumbs are disabled regardless of `value`. Use while
+   * the parent message is still streaming or in an error state.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Overrides the injected `feedbackThumbsUp` label for the thumbs-up button.
+   * When omitted, falls back to `useChatKitLabels().feedbackThumbsUp`.
+   */
+  ariaLabelThumbsUp?: string;
+  /**
+   * Overrides the injected `feedbackThumbsDown` label for the thumbs-down
+   * button. When omitted, falls back to
+   * `useChatKitLabels().feedbackThumbsDown`.
+   */
+  ariaLabelThumbsDown?: string;
+  /**
+   * Overrides the injected `feedbackGroup` label for the surrounding group.
+   * When omitted, falls back to `useChatKitLabels().feedbackGroup`.
+   */
+  ariaLabelGroup?: string;
+}
+
+export interface CkFeedbackButtonEmits {
+  /**
+   * Emitted when the user clicks an enabled thumb. The payload is the new
+   * value: `'up'`, `'down'`, or `null` when toggling off the current choice.
+   * Not emitted while `locked` or `disabled`.
+   */
+  (e: 'update:value', value: CkFeedbackValue): void;
+}

package/src/components/base/index.ts

@@ -3,6 +3,11 @@ export { CkAgentMessage } from './CkAgentMessage';
 export { CkConversationLayout } from './CkConversationLayout';
 export type { CkConversationLayoutProps } from './CkConversationLayout';
 export { CkCopyMessageActionButton } from './CkCopyMessageActionButton';
+export { CkFeedbackButton } from './CkFeedbackButton';
+export type {
+  CkFeedbackButtonProps,
+  CkFeedbackValue,
+} from './CkFeedbackButton';
 export { CkHistoryItem } from './CkHistoryItem';
 export type { CkHistoryItemProps, CkHistoryItemEmits } from './CkHistoryItem';
 export { CkHistoryWrapper } from './CkHistoryWrapper';