@aleph-alpha/chat-kit 1.0.0 → 1.1.0

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

@@ -0,0 +1,373 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref } from 'vue';
+import CkHistory from './CkHistory.vue';
+import { CkHistoryItem } from '../../base/CkHistoryItem';
+import type { Conversation } from '../../../types';
+
+const NOW = Math.floor(Date.now() / 1000);
+const ONE_DAY = 60 * 60 * 24;
+
+const sampleConversations: Conversation[] = [
+  {
+    id: 'c-1',
+    title: 'Project Proposal Overview',
+    createdAt: NOW - ONE_DAY * 14,
+    updatedAt: NOW - 60 * 30,
+  },
+  {
+    id: 'c-2',
+    title: 'Customer onboarding flow',
+    createdAt: NOW - ONE_DAY * 10,
+    updatedAt: NOW - 60 * 60 * 5,
+  },
+  {
+    id: 'c-3',
+    title: 'Refactor notes',
+    createdAt: NOW - ONE_DAY * 7,
+    updatedAt: NOW - ONE_DAY,
+  },
+  {
+    id: 'c-4',
+    createdAt: NOW - ONE_DAY * 3,
+    updatedAt: NOW - ONE_DAY * 2,
+  },
+  {
+    id: 'c-5',
+    title: 'Quarterly review prep',
+    createdAt: NOW - ONE_DAY * 30,
+    updatedAt: NOW - ONE_DAY * 5,
+  },
+  {
+    id: 'c-6',
+    title: 'Travel plans 2026',
+    createdAt: NOW - ONE_DAY * 60,
+    updatedAt: NOW - ONE_DAY * 14,
+  },
+];
+
+const defaultHrefResolver = (id: string) => `/chat/${id}`;
+
+const meta: Meta<typeof CkHistory> = {
+  title: 'Composed/CkHistory',
+  component: CkHistory,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Drop-in conversation history list. Pass a sorted `conversations` array and an `hrefResolver(id)` and you get a list of real-link rows with native middle-click / cmd-click / right-click affordances. Plain left-clicks emit `select` so consumers can `router.push(...)` themselves. Per-row Edit / Delete actions emit `edit` and `delete`.\n\nLabels are sourced from `useChatKitLabels` and can be translated via `provideChatKitLabels`.',
+      },
+    },
+  },
+  argTypes: {
+    conversations: { control: false },
+    hrefResolver: { control: false },
+    activeId: { control: 'text' },
+    showAction: { control: 'boolean' },
+    showActionOnHover: { control: 'boolean' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof CkHistory>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { CkHistory, type Conversation } from '@aleph-alpha/chat-kit';
+
+const conversations: Conversation[] = [
+  {
+    id: 'c-1',
+    title: 'Project Proposal Overview',
+    createdAt: 1_714_000_000,
+    updatedAt: 1_714_900_000,
+  },
+  {
+    id: 'c-2',
+    title: 'Customer onboarding flow',
+    createdAt: 1_714_100_000,
+    updatedAt: 1_714_800_000,
+  },
+];
+
+const hrefResolver = (id: string) => \`/chat/\${id}\`;
+
+function onSelect(c: Conversation) {
+  // router.push({ name: 'chat', params: { id: c.id } })
+}
+function onEdit(c: Conversation) {
+  // open rename dialog
+}
+function onDelete(c: Conversation) {
+  // confirm + delete
+}
+</script>
+
+<template>
+  <CkHistory
+    :conversations="conversations"
+    :href-resolver="hrefResolver"
+    active-id="c-2"
+    @select="onSelect"
+    @edit="onEdit"
+    @delete="onDelete"
+  />
+</template>`;
+
+const withoutActionsTemplateSource = `<script setup lang="ts">
+import { CkHistory, type Conversation } from '@aleph-alpha/chat-kit';
+
+const conversations: Conversation[] = [/* ... */];
+const hrefResolver = (id: string) => \`/chat/\${id}\`;
+</script>
+
+<template>
+  <CkHistory
+    :conversations="conversations"
+    :href-resolver="hrefResolver"
+    active-id="c-2"
+    :show-action="false"
+  />
+</template>`;
+
+const routerLinkIntegrationTemplateSource = `<script setup lang="ts">
+import { CkHistory, type Conversation } from '@aleph-alpha/chat-kit';
+import { useRouter, useRoute } from 'vue-router';
+
+const router = useRouter();
+const route = useRoute();
+
+const conversations = /* fetched + sorted by updatedAt desc */ [] as Conversation[];
+
+const hrefResolver = (id: string) =>
+  router.resolve({ name: 'chat', params: { id } }).href;
+
+function onSelect(c: Conversation) {
+  router.push({ name: 'chat', params: { id: c.id } });
+}
+function onEdit(c: Conversation)   { /* open rename dialog */ }
+function onDelete(c: Conversation) { /* confirm + delete */ }
+</script>
+
+<template>
+  <CkHistory
+    :conversations="conversations"
+    :href-resolver="hrefResolver"
+    :active-id="route.params.id as string"
+    @select="onSelect"
+    @edit="onEdit"
+    @delete="onDelete"
+  />
+</template>`;
+
+const withCustomItemTemplateSource = `<script setup lang="ts">
+import {
+  CkHistory,
+  CkHistoryItem,
+  type Conversation,
+} from '@aleph-alpha/chat-kit';
+import { RouterLink, useRoute } from 'vue-router';
+
+const route = useRoute();
+const conversations: Conversation[] = [/* ... */];
+
+function onEdit(c: Conversation)   { /* open rename dialog */ }
+function onDelete(c: Conversation) { /* confirm + delete */ }
+</script>
+
+<template>
+  <CkHistory
+    :conversations="conversations"
+    :href-resolver="(id) => \\\`/chat/\\\${id}\\\`"
+    :active-id="route.params.id as string"
+    @edit="onEdit"
+    @delete="onDelete"
+  >
+    <template
+      #item="{ conversation, isActive, title, edit, delete: del }"
+    >
+      <RouterLink
+        :to="{ name: 'chat', params: { id: conversation.id } }"
+        custom
+        v-slot="{ href, navigate }"
+      >
+        <CkHistoryItem
+          as="a"
+          :href="href"
+          :is-active="isActive"
+          :title="title"
+          action-popover
+          @click="navigate"
+        >
+          <template #action-popover>
+            <button type="button" @click="edit">Edit</button>
+            <button type="button" @click="del">Delete</button>
+          </template>
+        </CkHistoryItem>
+      </RouterLink>
+    </template>
+  </CkHistory>
+</template>`;
+
+const renderStory = (args: Story['args']) => ({
+  components: { CkHistory },
+  setup() {
+    const lastEvent = ref<string>('');
+
+    function onSelect(c: Conversation) {
+      lastEvent.value = `select(${c.id})`;
+    }
+    function onEdit(c: Conversation) {
+      lastEvent.value = `edit(${c.id})`;
+    }
+    function onDelete(c: Conversation) {
+      lastEvent.value = `delete(${c.id})`;
+    }
+
+    return { args, lastEvent, onSelect, onEdit, onDelete };
+  },
+  template: `
+    <div class="bg-background-surface-primary p-4 w-[24rem]">
+      <CkHistory
+        v-bind="args"
+        @select="onSelect"
+        @edit="onEdit"
+        @delete="onDelete"
+      />
+      <p class="label-12-regular mt-3 text-content-on-surface-muted">
+        Last event: {{ lastEvent || '\u2014' }}
+      </p>
+    </div>
+  `,
+});
+
+/**
+ * Default list with per-row Edit / Delete actions and an active row. Plain
+ * left-clicks emit `select` (call `router.push(...)` in the handler);
+ * middle-click, cmd/ctrl-click, and right-click keep native browser
+ * behavior via the resolved `href`.
+ */
+export const Default: Story = {
+  args: {
+    conversations: sampleConversations,
+    hrefResolver: defaultHrefResolver,
+    activeId: 'c-2',
+  },
+  render: renderStory,
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * Hides the per-row kebab action (`show-action="false"`). Use when
+ * conversations are read-only or actions live elsewhere in the UI.
+ */
+export const WithoutActions: Story = {
+  args: {
+    conversations: sampleConversations,
+    hrefResolver: defaultHrefResolver,
+    activeId: 'c-2',
+    showAction: false,
+  },
+  render: renderStory,
+  parameters: { docs: { source: { code: withoutActionsTemplateSource } } },
+};
+
+/**
+ * Typical Vue Router integration. The `<a href>` produced by `hrefResolver`
+ * enables native middle-click / cmd-click "open in new tab" and right-click
+ * "Copy link address". Plain left-clicks are intercepted via the `select`
+ * event so you can call `router.push(...)`.
+ */
+export const RouterLinkIntegration: Story = {
+  args: {
+    conversations: sampleConversations,
+    hrefResolver: defaultHrefResolver,
+    activeId: 'c-3',
+  },
+  render: renderStory,
+  parameters: {
+    docs: { source: { code: routerLinkIntegrationTemplateSource } },
+  },
+};
+
+/**
+ * Replaces each row via the `#item` scoped slot. Use this when you want
+ * to wrap rows in `<RouterLink>` for native vue-router integration: the
+ * slot scope exposes the resolved row data plus `select` / `edit` /
+ * `delete` helpers, and you reuse `CkHistoryItem` to keep the default
+ * look while delegating navigation to the router.
+ */
+export const WithCustomItem: Story = {
+  args: {
+    conversations: sampleConversations,
+    hrefResolver: defaultHrefResolver,
+    activeId: 'c-2',
+  },
+  render: (args) => ({
+    components: { CkHistory, CkHistoryItem },
+    setup() {
+      const lastEvent = ref<string>('');
+
+      function onEdit(c: Conversation) {
+        lastEvent.value = `edit(${c.id})`;
+      }
+      function onDelete(c: Conversation) {
+        lastEvent.value = `delete(${c.id})`;
+      }
+      function onSelect(c: Conversation) {
+        lastEvent.value = `select(${c.id})`;
+      }
+
+      return { args, lastEvent, onEdit, onDelete, onSelect };
+    },
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[24rem]">
+        <CkHistory
+          v-bind="args"
+          @edit="onEdit"
+          @delete="onDelete"
+          @select="onSelect"
+        >
+          <template
+            #item="{ href, isActive, title, select, edit, delete: del }"
+          >
+            <CkHistoryItem
+              as="a"
+              :href="href"
+              :is-active="isActive"
+              :title="title"
+              action-popover
+              action-aria-label="Conversation options"
+              @click="select($event)"
+            >
+              <template #action-popover>
+                <div class="flex flex-col p-1">
+                  <button
+                    type="button"
+                    class="flex h-10 w-full items-center gap-3 rounded-md px-2 py-2 body-14-regular text-content-on-surface-primary outline-hidden transition-colors hover-layer hover-layer-default focus-visible:ring-[3px] focus-visible:ring-ring/50"
+                    @click="edit"
+                  >
+                    <span class="min-w-0 flex-1 truncate text-left">Edit</span>
+                  </button>
+                  <button
+                    type="button"
+                    class="flex h-10 w-full items-center gap-3 rounded-md px-2 py-2 body-14-regular text-content-on-surface-primary outline-hidden transition-colors hover-layer hover-layer-default focus-visible:ring-[3px] focus-visible:ring-ring/50"
+                    @click="del"
+                  >
+                    <span class="min-w-0 flex-1 truncate text-left">Delete</span>
+                  </button>
+                </div>
+              </template>
+            </CkHistoryItem>
+          </template>
+        </CkHistory>
+        <p class="label-12-regular mt-3 text-content-on-surface-muted">
+          Last event: {{ lastEvent || '\u2014' }}
+        </p>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: withCustomItemTemplateSource } },
+  },
+};

package/src/components/composed/CkHistory/CkHistory.vue

@@ -0,0 +1,126 @@
+<script setup lang="ts">
+import {
+  UiIcon,
+  UiSidebarPopoverMenu,
+  UiSidebarPopoverMenuItem,
+} from '@aleph-alpha/ui-library';
+import CkHistoryItem from '../../base/CkHistoryItem/CkHistoryItem.vue';
+import CkHistoryWrapper from '../../base/CkHistoryWrapper/CkHistoryWrapper.vue';
+import { useChatKitLabels } from '../../../handlers/useChatKitLabels';
+import type { Conversation } from '../../../types';
+import type { CkHistoryEmits, CkHistoryProps } from './types';
+
+defineOptions({ name: 'CkHistory' });
+
+const props = withDefaults(defineProps<CkHistoryProps>(), {
+  activeId: undefined,
+  showAction: true,
+  showActionOnHover: true,
+});
+
+const emit = defineEmits<CkHistoryEmits>();
+
+defineSlots<{
+  /**
+   * Replace the entire row rendering. Use this to wrap each row in your
+   * own navigation primitive (e.g. vue-router `<RouterLink>`) while still
+   * receiving the resolved row data and the standard event helpers.
+   *
+   * Slot scope:
+   *  - `conversation` — raw `Conversation` for this row
+   *  - `href` — URL produced by `hrefResolver(conversation.id)`
+   *  - `isActive` — whether this row matches `activeId`
+   *  - `title` — resolved title (falls back to `historyItemUntitled` label)
+   *  - `select(event)` — RouterLink-style click guard: `preventDefault()`
+   *    and emit `select` for plain left-clicks; ignores middle/modifier
+   *    clicks so native browser affordances still work.
+   *  - `edit()` / `delete()` — emit the corresponding event for this row
+   */
+  item: (props: {
+    conversation: Conversation;
+    href: string;
+    isActive: boolean;
+    title: string;
+    select: (event: MouseEvent) => void;
+    edit: () => void;
+    delete: () => void;
+  }) => void;
+}>();
+
+const labels = useChatKitLabels();
+
+function hrefFor(c: Conversation) {
+  return props.hrefResolver(c.id);
+}
+
+function titleFor(c: Conversation) {
+  const title = c.title?.trim();
+  return title ? title : labels.value.historyItemUntitled;
+}
+
+/**
+ * RouterLink-style click guard: only emit `select` for plain left-clicks.
+ * Middle-click, modifier-clicks, and right-click fall through to the
+ * browser so the `<a href>` provides native affordances (open in new tab,
+ * copy link, etc).
+ */
+function handleRowClick(c: Conversation, event: MouseEvent) {
+  if (event.defaultPrevented) return;
+  if (event.button !== 0) return;
+  if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) return;
+  event.preventDefault();
+  emit('select', c, event);
+}
+</script>
+
+<template>
+  <CkHistoryWrapper>
+    <template
+      v-for="conversation in props.conversations"
+      :key="conversation.id"
+    >
+      <slot
+        name="item"
+        :conversation="conversation"
+        :href="hrefFor(conversation)"
+        :is-active="conversation.id === props.activeId"
+        :title="titleFor(conversation)"
+        :select="(event: MouseEvent) => handleRowClick(conversation, event)"
+        :edit="() => emit('edit', conversation)"
+        :delete="() => emit('delete', conversation)"
+      >
+        <CkHistoryItem
+          as="a"
+          :href="hrefFor(conversation)"
+          :is-active="conversation.id === props.activeId"
+          :title="titleFor(conversation)"
+          :show-action="props.showAction"
+          :show-action-on-hover="props.showActionOnHover"
+          :action-popover="props.showAction"
+          :action-aria-label="labels.historyItemActionAriaLabel"
+          @click="handleRowClick(conversation, $event)"
+          ><template #action-popover>
+            <UiSidebarPopoverMenu :show-footer-separator="false">
+              <UiSidebarPopoverMenuItem
+                :label="labels.historyItemEditAction"
+                @click="emit('edit', conversation)"
+              >
+                <template #icon>
+                  <UiIcon name="pencil" size="s" />
+                </template>
+              </UiSidebarPopoverMenuItem>
+              <UiSidebarPopoverMenuItem
+                :label="labels.historyItemDeleteAction"
+                @click="emit('delete', conversation)"
+              >
+                <template #icon>
+                  <UiIcon name="trash" size="s" />
+                </template>
+              </UiSidebarPopoverMenuItem>
+            </UiSidebarPopoverMenu>
+          </template>
+        </CkHistoryItem>
+      </slot>
+    </template>
+  </CkHistoryWrapper>
+</template>

package/src/components/composed/CkHistory/index.ts

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

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

@@ -0,0 +1,72 @@
+import type { Conversation } from '../../../types';
+
+/**
+ * Composed conversation history list. Renders each conversation as a real
+ * `<a href>` row so middle-click, cmd/ctrl-click, and right-click "Copy link
+ * address" all work natively. Plain left-clicks are intercepted via a
+ * RouterLink-style guard and exposed as a `select` event so consumers can
+ * call `router.push(...)` (or any other navigation primitive) themselves.
+ *
+ * Per-row "Edit" and "Delete" actions are rendered internally; consumers
+ * receive `edit` / `delete` events with the corresponding conversation.
+ *
+ * Use the `#item` scoped slot to fully replace the row rendering — for
+ * example to wrap each row in `<RouterLink>` for native vue-router
+ * integration. The slot scope exposes the resolved row data
+ * (`conversation`, `href`, `isActive`, `title`) plus `select` / `edit` /
+ * `delete` helpers that emit the same events as the default rendering.
+ *
+ * @category Messages
+ * @useCases conversation history list, recent chats sidebar entry, thread navigation, chat history pane
+ * @keywords conversation, history, list, navigation, link, sidebar, threads, routerlink
+ * @related CkHistoryWrapper, CkHistoryItem
+ */
+export interface CkHistoryProps {
+  /** Conversations to display, in the order they should render. */
+  conversations: Conversation[];
+  /**
+   * Resolves a conversation id to the URL set on each row's `<a href>`.
+   * Required so middle-click / cmd-click / right-click-copy work natively.
+   * Gives the consumer full control over URL shape (nested routes, query
+   * params, hash routes, locale prefixes, etc).
+   *
+   * @example
+   * ```ts
+   * const router = useRouter();
+   * const hrefResolver = (id: string) =>
+   *   router.resolve({ name: 'chat', params: { id } }).href;
+   * ```
+   */
+  hrefResolver: (id: string) => string;
+  /** Id of the currently-active conversation; marks that row as active. */
+  activeId?: string;
+  /**
+   * Whether to show the trailing action kebab (edit / delete popover).
+   * @default true
+   */
+  showAction?: boolean;
+  /**
+   * Whether the trailing action is only revealed on row hover/focus-within.
+   * @default true
+   */
+  showActionOnHover?: boolean;
+}
+
+/**
+ * Emitted events for `CkHistory`.
+ */
+export interface CkHistoryEmits {
+  /**
+   * Fired on a plain left-click of a conversation row. Middle-click,
+   * cmd/ctrl/shift/alt-click, and right-click do NOT emit — they fall
+   * through to native browser behaviour so users can open the conversation
+   * in a new tab, copy the link, etc. The component calls
+   * `event.preventDefault()` before emitting so consumers can safely call
+   * `router.push(...)` in the handler.
+   */
+  select: [conversation: Conversation, event: MouseEvent];
+  /** Fired when the "Edit" action is selected from a row's popover menu. */
+  edit: [conversation: Conversation];
+  /** Fired when the "Delete" action is selected from a row's popover menu. */
+  delete: [conversation: Conversation];
+}