@aleph-alpha/chat-kit 1.0.0 → 1.2.0

package/src/components/base/CkHistoryItem/CkHistoryItem.vue

@@ -0,0 +1,285 @@
+<script setup lang="ts">
+import { computed, ref, useAttrs, useSlots, watch } from 'vue';
+import {
+  Primitive,
+  UiIcon,
+  UiPopover,
+  UiPopoverContent,
+  UiPopoverTrigger,
+  UiTooltip,
+} from '@aleph-alpha/ui-library';
+import { CHAT_HISTORY_ACTIVE_INDICATOR_CLASS } from './activeIndicator';
+import type { CkHistoryItemEmits, CkHistoryItemOwnProps } from './types';
+
+defineOptions({
+  name: 'CkHistoryItem',
+  inheritAttrs: false,
+});
+
+const emit = defineEmits<CkHistoryItemEmits>();
+
+const props = withDefaults(defineProps<CkHistoryItemOwnProps>(), {
+  isActive: false,
+  showAction: true,
+  showActionOnHover: true,
+  actionTooltip: '',
+  actionAriaLabel: 'History item action',
+  actionPopover: false,
+  actionPopoverSide: 'right',
+  actionPopoverAlign: 'start',
+  actionPopoverSideOffset: 8,
+});
+
+const attrs = useAttrs();
+const slots = useSlots();
+
+const hasMeta = computed(() =>
+  Boolean(props.metaStart || props.metaEnd || slots.meta),
+);
+
+/**
+ * When true, pointer/focus is in the action column. The row-level hover
+ * fill is suppressed so the icon's own hover fill + outlined border
+ * don't stack on top of it.
+ */
+const pointerOnAction = ref(false);
+
+function onActionPointerEnter() {
+  pointerOnAction.value = true;
+}
+
+function onActionPointerLeave() {
+  pointerOnAction.value = false;
+}
+
+function onActionFocusIn() {
+  pointerOnAction.value = true;
+}
+
+function onActionFocusOut() {
+  pointerOnAction.value = false;
+}
+
+watch(
+  () => props.showAction,
+  (show) => {
+    if (!show) {
+      pointerOnAction.value = false;
+    }
+  },
+);
+
+const containerClass = computed(() => [
+  'group/ck-history-item relative flex w-full min-w-0 items-stretch gap-2 rounded-md border border-transparent px-2 py-1.5 transition-colors',
+  hasMeta.value ? 'h-12' : 'h-10',
+  // Whole-row focus ring: first tab lands on the main row control; second tab on the action button — both are inside this container.
+  // `:has(:focus-visible)` instead of `:focus-within` so mouse clicks on the row don't flash a keyboard focus ring.
+  'has-[:focus-visible]:border-border-surface-focus-ring has-[:focus-visible]:ring-[3px] has-[:focus-visible]:ring-ring/50',
+  // Row hover/active fill. Hover is suppressed while the
+  // pointer/focus is on the action column so the icon's own fill does not stack on top.
+  (props.isActive || !pointerOnAction.value) &&
+    'hover:bg-background-surface-muted-subtle',
+  props.isActive && 'bg-background-surface-muted-subtle',
+  CHAT_HISTORY_ACTIVE_INDICATOR_CLASS,
+]);
+
+const itemClass = computed(() => [
+  'text-left outline-hidden transition-colors',
+  'body-14-regular text-content-on-surface-primary',
+  '!hover:bg-transparent !active:bg-transparent',
+  // Suppress a second ring on the primary control; the row ring is on the outer container.
+  'focus-visible:ring-0 focus-visible:outline-none',
+  'data-[active=true]:text-content-on-surface-primary',
+  // Stretched-link: extend the primary control's hit area to cover the full row
+  // container (including its `px-2 py-1.5` padding and the gap before the action
+  // column) so clicks anywhere on the row activate the item. The action button
+  // stays interactive because it comes later in the DOM and is `relative`.
+  'before:content-[""] before:absolute before:inset-0 before:z-0',
+  'flex min-w-0 flex-1 items-center',
+  attrs.class as unknown,
+]);
+
+/**
+ * Wrapper column that owns the action button and the `pointerenter` /
+ * `pointerleave` hit area driving `pointerOnAction`. Uses `self-stretch` so
+ * the full row height reports pointer-enter on the column (not just the
+ * 32×32 button), and — when `showActionOnHover` is true — hides the inner
+ * button with `opacity-0` until the row is hovered or keyboard focus lands
+ * anywhere inside it.
+ */
+const actionColumnClass = computed(() => [
+  'ml-auto flex shrink-0 items-center self-stretch',
+  props.showActionOnHover
+    ? '[&_button]:opacity-0 [&_button]:transition-opacity group-hover/ck-history-item:[&_button]:opacity-100 group-focus-within/ck-history-item:[&_button]:opacity-100'
+    : '',
+]);
+
+/**
+ * Action control: same hover fill as the row, plus the
+ * `border/button/outlined` token so the icon picks up a visible outline on
+ * hover/focus (mirrors the outline button variant). Applied only while
+ * pointer/focus is on the action column so the row tint does not stack
+ * underneath the icon.
+ */
+const actionButtonClass = computed(() => [
+  'relative z-10 inline-flex size-8 shrink-0 items-center justify-center rounded-sm border border-transparent text-content-on-surface-primary outline-hidden transition-colors',
+  '[&_svg]:size-4 [&_svg]:shrink-0',
+  'focus-visible:ring-0 focus-visible:outline-none',
+  pointerOnAction.value &&
+    'bg-background-surface-muted-subtle border-border-button-outlined',
+]);
+
+// Popover panel surface is `background/surface/secondary` to match the
+// look of the original sidebar chat-history item popover. This is
+// intentional for visual parity and can be overridden via
+// `actionPopoverContentClass`.
+const actionPopoverPanelClass = computed(() => [
+  'w-auto min-w-48 max-w-sm p-0 bg-background-surface-secondary',
+  props.actionPopoverContentClass,
+]);
+
+const passthroughAttrs = computed(() => {
+  const {
+    class: _class,
+    as: _as,
+    asChild: _asChild,
+    'as-child': _asChildAttr,
+    ...rest
+  } = attrs as Record<string, unknown>;
+  return rest;
+});
+
+const primitiveAs = computed(() => attrs.as ?? 'button');
+const primitiveAsChild = computed(
+  () =>
+    attrs.asChild === true ||
+    attrs.asChild === '' ||
+    attrs['as-child'] === true ||
+    attrs['as-child'] === '',
+);
+
+function onActionClick(event: MouseEvent) {
+  event.stopPropagation();
+  const el = event.currentTarget;
+  if (el instanceof HTMLElement && el.focus) {
+    queueMicrotask(() => el.focus({ preventScroll: true }));
+  }
+  if (!props.actionPopover) {
+    // Public kebab-case event preserved for API parity.
+
+    emit('action-click', event);
+  }
+}
+</script>
+
+<template>
+  <div :data-active="props.isActive" :class="containerClass">
+    <Primitive
+      v-bind="passthroughAttrs"
+      :as="primitiveAs"
+      :as-child="primitiveAsChild"
+      :data-active="props.isActive"
+      :class="itemClass"
+    >
+      <div class="min-w-0 flex-1">
+        <div class="truncate body-14-regular text-content-on-surface-primary">
+          {{ props.title }}
+        </div>
+
+        <div
+          v-if="props.metaStart || props.metaEnd || $slots.meta"
+          class="mt-0.5 flex min-w-0 items-center gap-1 label-12-medium text-content-on-surface-muted"
+        >
+          <slot name="meta">
+            <span v-if="props.metaStart" class="truncate">{{
+              props.metaStart
+            }}</span>
+            <span v-if="props.metaStart && props.metaEnd" aria-hidden="true"
+              >|</span
+            >
+            <span v-if="props.metaEnd" class="truncate">{{
+              props.metaEnd
+            }}</span>
+          </slot>
+        </div>
+      </div>
+    </Primitive>
+
+    <div
+      v-if="props.showAction"
+      :class="actionColumnClass"
+      @pointerenter="onActionPointerEnter"
+      @pointerleave="onActionPointerLeave"
+    >
+      <UiPopover v-if="props.actionPopover">
+        <UiPopoverTrigger as-child>
+          <button
+            type="button"
+            :aria-label="props.actionAriaLabel"
+            :aria-haspopup="'dialog'"
+            :class="actionButtonClass"
+            @focusin="onActionFocusIn"
+            @focusout="onActionFocusOut"
+            @click.stop="onActionClick"
+          >
+            <component
+              :is="props.actionIcon"
+              v-if="props.actionIcon"
+              :size="16"
+              aria-hidden="true"
+            />
+            <UiIcon v-else name="more-vertical" :size="16" aria-hidden="true" />
+          </button>
+        </UiPopoverTrigger>
+        <UiPopoverContent
+          :side="props.actionPopoverSide"
+          :align="props.actionPopoverAlign"
+          :side-offset="props.actionPopoverSideOffset"
+          :class="actionPopoverPanelClass"
+        >
+          <slot name="action-popover" />
+        </UiPopoverContent>
+      </UiPopover>
+
+      <UiTooltip
+        v-else-if="props.actionTooltip"
+        :content="props.actionTooltip"
+        side="right"
+      >
+        <button
+          type="button"
+          :aria-label="props.actionAriaLabel"
+          :class="actionButtonClass"
+          @focusin="onActionFocusIn"
+          @focusout="onActionFocusOut"
+          @click.stop="onActionClick"
+        >
+          <component
+            :is="props.actionIcon"
+            v-if="props.actionIcon"
+            :size="16"
+            aria-hidden="true"
+          />
+          <UiIcon v-else name="more-vertical" :size="16" aria-hidden="true" />
+        </button>
+      </UiTooltip>
+      <button
+        v-else
+        type="button"
+        :aria-label="props.actionAriaLabel"
+        :class="actionButtonClass"
+        @focusin="onActionFocusIn"
+        @focusout="onActionFocusOut"
+        @click.stop="onActionClick"
+      >
+        <component
+          :is="props.actionIcon"
+          v-if="props.actionIcon"
+          :size="16"
+          aria-hidden="true"
+        />
+        <UiIcon v-else name="more-vertical" :size="16" aria-hidden="true" />
+      </button>
+    </div>
+  </div>
+</template>

package/src/components/base/CkHistoryItem/activeIndicator.ts

@@ -0,0 +1,15 @@
+/**
+ * Shared class string for the left-edge active indicator used by a chat
+ * history row.
+ *
+ * The `::before` pseudo-element is always mounted so CSS has something to
+ * transition. At rest it's painted from `scale-x-0` + `opacity-0` with its
+ * transform anchored on the left edge (`origin-left`); when the row's
+ * `data-active="true"` flips on, the bar paints in from left to right while
+ * fading in, using a 200ms linear curve.
+ *
+ * Kept as a string constant (rather than generated via `cn`) so UnoCSS's
+ * static scanner picks up every utility class for atomic CSS generation.
+ */
+export const CHAT_HISTORY_ACTIVE_INDICATOR_CLASS =
+  'before:absolute before:z-10 before:top-1/2 before:left-0 before:h-1/2 before:w-0.5 before:-translate-y-1/2 before:origin-left before:scale-x-0 before:rounded-full before:bg-background-accent-default before:opacity-0 before:transition-[transform,opacity] before:duration-200 before:ease-linear before:content-[""] data-[active=true]:before:scale-x-100 data-[active=true]:before:opacity-100';

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

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

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

@@ -0,0 +1,111 @@
+import type { Component, HTMLAttributes } from 'vue';
+import type { PrimitiveProps } from '@aleph-alpha/ui-library';
+
+/**
+ * A single chat history entry with title, optional meta line, active
+ * indicator, and a trailing action control (plain button or popover).
+ * Sidebar-agnostic: can be used anywhere, not only inside a sidebar.
+ *
+ * @category Actions
+ * @useCases chat history row, thread list entry, recent conversation item
+ * @keywords chat, history, item, row, conversation, thread
+ * @related CkHistoryWrapper
+ */
+export type CkHistoryItemProps = PrimitiveProps & CkHistoryItemOwnProps;
+
+export interface CkHistoryItemOwnProps {
+  /**
+   * Main title of the history item.
+   */
+  title: string;
+
+  /**
+   * First metadata label shown under the title.
+   */
+  metaStart?: string;
+
+  /**
+   * Second metadata label shown under the title.
+   */
+  metaEnd?: string;
+
+  /**
+   * Marks the item as active (shows the left-edge rail indicator and
+   * background tint).
+   * @default false
+   */
+  isActive?: boolean;
+
+  /**
+   * Whether to render the end action button.
+   * @default true
+   */
+  showAction?: boolean;
+
+  /**
+   * Whether the end action should only appear on hover/focus.
+   * @default true
+   */
+  showActionOnHover?: boolean;
+
+  /**
+   * Tooltip for the end action button.
+   */
+  actionTooltip?: string;
+
+  /**
+   * Accessible label for the end action button.
+   * @default 'History item action'
+   */
+  actionAriaLabel?: string;
+
+  /**
+   * Custom action icon rendered at the end of the row. Defaults to a
+   * `more-vertical` icon.
+   */
+  actionIcon?: Component;
+
+  /**
+   * When true, the action control opens a popover (use `#action-popover`
+   * slot for the body). Tooltip on the action is not used in this mode;
+   * set `actionAriaLabel` for accessibility.
+   * @default false
+   */
+  actionPopover?: boolean;
+
+  /**
+   * Popover side relative to the action trigger.
+   * @default 'right'
+   */
+  actionPopoverSide?: 'top' | 'right' | 'bottom' | 'left';
+
+  /**
+   * Popover alignment relative to the trigger.
+   * @default 'start'
+   */
+  actionPopoverAlign?: 'start' | 'center' | 'end';
+
+  /**
+   * Offset between trigger and popover content.
+   * @default 8
+   */
+  actionPopoverSideOffset?: number;
+
+  /**
+   * Extra classes for the popover panel (merged with pattern defaults).
+   */
+  actionPopoverContentClass?: HTMLAttributes['class'];
+}
+
+/**
+ * Emitted events for `CkHistoryItem`.
+ */
+export interface CkHistoryItemEmits {
+  /**
+   * Fired when the end action button is clicked.
+   * Not emitted when `actionPopover` is `true` — in that mode the click
+   * opens the popover and consumers react to interactions inside the
+   * `#action-popover` slot.
+   */
+  'action-click': [event: MouseEvent];
+}

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

@@ -0,0 +1,26 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, it } from 'vitest';
+import CkHistoryWrapper from './CkHistoryWrapper.vue';
+
+describe('CkHistoryWrapper', () => {
+  it('sets data-slot and applies gap class by default', () => {
+    const { container } = render(CkHistoryWrapper, {
+      slots: { default: '<span>x</span>' },
+    });
+
+    const root = container.querySelector('[data-slot="chat-history"]');
+    expect(root).toBeTruthy();
+    expect(root?.className).toMatch(/gap-1/);
+  });
+
+  it('omits gap class when withGap is false', () => {
+    const { container } = render(CkHistoryWrapper, {
+      props: { withGap: false },
+      slots: { default: '<span>y</span>' },
+    });
+
+    const root = container.querySelector('[data-slot="chat-history"]');
+    expect(root).toBeTruthy();
+    expect(root?.className).not.toMatch(/gap-1/);
+  });
+});

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

@@ -0,0 +1,149 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref } from 'vue';
+import CkHistoryWrapper from './CkHistoryWrapper.vue';
+import { CkHistoryItem } from '../CkHistoryItem';
+
+const meta: Meta<typeof CkHistoryWrapper> = {
+  title: 'Base/CkHistoryWrapper',
+  component: CkHistoryWrapper,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Vertical stack for chat history rows (`CkHistoryItem`). Sidebar-agnostic — use anywhere in the app. Toggle **`withGap`** to add spacing between items.',
+      },
+    },
+  },
+  argTypes: {
+    withGap: {
+      control: 'boolean',
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof CkHistoryWrapper>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { CkHistoryWrapper, CkHistoryItem } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <CkHistoryWrapper>
+    <CkHistoryItem title="Project Proposal Overview" meta-start="Today" meta-end="Innsbruck" />
+    <CkHistoryItem title="Project Proposal Overview" meta-start="Today" meta-end="Innsbruck" is-active />
+    <CkHistoryItem title="Project Proposal Overview" meta-start="Today" meta-end="Innsbruck" />
+    <CkHistoryItem title="Project Proposal Overview" meta-start="Today" meta-end="Innsbruck" />
+  </CkHistoryWrapper>
+</template>`;
+
+const withoutGapTemplateSource = `<script setup lang="ts">
+import { CkHistoryWrapper, CkHistoryItem } from '@aleph-alpha/chat-kit';
+</script>
+
+<template>
+  <CkHistoryWrapper :with-gap="false">
+    <CkHistoryItem title="Thread A" meta-start="Today" />
+    <CkHistoryItem title="Thread B" meta-start="Yesterday" />
+    <CkHistoryItem title="Thread C" meta-start="Last week" />
+  </CkHistoryWrapper>
+</template>`;
+
+/**
+ * Default wrapper with the small vertical gap (`gap-1`) applied between
+ * child rows. Use as the container for any list of `CkHistoryItem`s.
+ */
+export const Default: Story = {
+  render: () => ({
+    components: { CkHistoryWrapper, CkHistoryItem },
+    setup() {
+      const actionCount = ref(0);
+      const items = [
+        {
+          title: 'Project Proposal Overview',
+          metaStart: 'Today',
+          metaEnd: 'Innsbruck',
+        },
+        {
+          title: 'Project Proposal Overview',
+          metaStart: 'Today',
+          metaEnd: 'Innsbruck',
+          isActive: true,
+        },
+        {
+          title: 'Project Proposal Overview',
+          metaStart: 'Today',
+          metaEnd: 'Innsbruck',
+        },
+        {
+          title: 'Project Proposal Overview',
+          metaStart: 'Today',
+          metaEnd: 'Innsbruck',
+        },
+      ];
+
+      function handleActionClick() {
+        actionCount.value += 1;
+      }
+
+      return { actionCount, handleActionClick, items };
+    },
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[22rem]">
+        <CkHistoryWrapper>
+          <CkHistoryItem
+            v-for="(item, index) in items"
+            :key="index"
+            :title="item.title"
+            :meta-start="item.metaStart"
+            :meta-end="item.metaEnd"
+            :is-active="item.isActive"
+            action-tooltip="More actions"
+            @action-click="handleActionClick"
+          />
+        </CkHistoryWrapper>
+        <p class="label-12-regular mt-3 text-content-on-surface-muted">
+          Action clicks: {{ actionCount }}
+        </p>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * Disables the inter-item gap (`with-gap="false"`). Use for dense lists
+ * where items should sit flush against each other.
+ */
+export const WithoutGap: Story = {
+  args: {
+    withGap: false,
+  },
+  render: (args) => ({
+    components: { CkHistoryWrapper, CkHistoryItem },
+    setup() {
+      const items = [
+        { title: 'Thread A', metaStart: 'Today' },
+        { title: 'Thread B', metaStart: 'Yesterday' },
+        { title: 'Thread C', metaStart: 'Last week' },
+      ];
+      return { args, items };
+    },
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[22rem]">
+        <CkHistoryWrapper v-bind="args">
+          <CkHistoryItem
+            v-for="(item, index) in items"
+            :key="index"
+            :title="item.title"
+            :meta-start="item.metaStart"
+          />
+        </CkHistoryWrapper>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: withoutGapTemplateSource } } },
+};

package/src/components/base/CkHistoryWrapper/CkHistoryWrapper.vue

@@ -0,0 +1,36 @@
+<script setup lang="ts">
+import { computed, useAttrs } from 'vue';
+import type { CkHistoryWrapperProps } from './types';
+
+defineOptions({
+  name: 'CkHistoryWrapper',
+  inheritAttrs: false,
+});
+
+const props = withDefaults(defineProps<CkHistoryWrapperProps>(), {
+  withGap: true,
+});
+
+const attrs = useAttrs();
+
+const baseClass = 'flex w-full min-w-0 flex-col p-2';
+
+const rootClass = computed(() => {
+  const consumerClass =
+    typeof attrs.class === 'string' ? attrs.class : undefined;
+  return [baseClass, props.withGap ? 'gap-1' : undefined, consumerClass]
+    .filter(Boolean)
+    .join(' ');
+});
+
+const passthroughAttrs = computed(() => {
+  const { class: _class, ...rest } = attrs as Record<string, unknown>;
+  return rest;
+});
+</script>
+
+<template>
+  <div v-bind="passthroughAttrs" data-slot="chat-history" :class="rootClass">
+    <slot />
+  </div>
+</template>

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

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

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

@@ -0,0 +1,16 @@
+/**
+ * Vertical stack for chat history rows (`CkHistoryItem`). Sidebar-agnostic:
+ * can be used anywhere in the app, not only inside a sidebar.
+ *
+ * @category Layout
+ * @useCases chat history list, thread list container, recent conversations stack
+ * @keywords chat, history, list, stack, container
+ * @related CkHistoryItem
+ */
+export interface CkHistoryWrapperProps {
+  /**
+   * When true, applies a small vertical gap (`gap-1`) between child items.
+   * @default true
+   */
+  withGap?: boolean;
+}