@aleph-alpha/chat-kit 1.0.0 → 1.2.0

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

@@ -0,0 +1,382 @@
+import CkMarkdownRenderer from './CkMarkdownRenderer.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+
+const meta: Meta<typeof CkMarkdownRenderer> = {
+  title: 'Base/CkMarkdownRenderer',
+  component: CkMarkdownRenderer,
+  tags: ['autodocs'],
+  argTypes: {
+    content: {
+      control: 'text',
+      description: 'Raw markdown string to render.',
+    },
+    classes: {
+      control: 'object',
+      description: 'Per-tag class overrides (e.g. `{ h1: "text-2xl" }`).',
+    },
+    plugins: {
+      control: false,
+      description: 'Additional `unified` plugins to extend Markdown parsing.',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+const content = 'Hello **world**! This is a *simple* paragraph with \`inline code\`.';
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" />
+</template>`;
+
+const withCodeBlocksTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+const content = [
+  '# Code Example',
+  '',
+  '\`\`\`javascript',
+  'function greet(name) {',
+  '  return \`Hello, \${name}!\`;',
+  '}',
+  '\`\`\`',
+].join('\\n');
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" />
+</template>`;
+
+const withCustomCodeBlockSlotTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+const content = 'Example:\\n\\n\`\`\`typescript\\nconst x: number = 42;\\n\`\`\`';
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content">
+    <template #code-block="{ code, language }">
+      <div class="rounded-lg bg-black p-4 font-mono text-white">
+        <div class="mb-2 text-xs opacity-60">{{ language }}</div>
+        <code>{{ code }}</code>
+      </div>
+    </template>
+  </CkMarkdownRenderer>
+</template>`;
+
+const complexMarkdownTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+const content = \`# Project Overview
+
+This document describes the **architecture** of the system.
+
+## Key Features
+
+- Real-time processing
+- Scalable infrastructure
+
+## Setup
+
+\\\`\\\`\\\`bash
+npm install && npm run build
+\\\`\\\`\\\`
+
+> **Note:** Restart the server after changing config.\`;
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" />
+</template>`;
+
+const withCustomClassesTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+const content = '# Styled Heading\\n\\nA paragraph with **bold** text.';
+const classes = {
+  h1: 'text-2xl font-bold mb-4',
+  p: 'text-base leading-7 mb-2',
+  strong: 'font-bold',
+};
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" :classes="classes" />
+</template>`;
+
+const gfmFeaturesTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+const content = [
+  '## Tables',
+  '| Feature | Status |',
+  '| --- | --- |',
+  '| Tables | Done |',
+  '',
+  '- [x] Add remark-gfm',
+  '- [ ] Ship to production',
+].join('\\n');
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" />
+</template>`;
+
+const withCustomPluginTemplateSource = `<script setup lang="ts">
+import { CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
+
+function visitTextNodes(node: any, transform: (value: string) => string): void {
+  if (node.type === 'text') node.value = transform(node.value);
+  if (node.children) node.children.forEach((c: any) => visitTextNodes(c, transform));
+}
+
+const uppercasePlugin = () => (tree: any) => visitTextNodes(tree, (v) => v.toUpperCase());
+
+const content = '# Important Notice\\n\\nThis will be **uppercased**.';
+const plugins = [uppercasePlugin];
+</script>
+
+<template>
+  <CkMarkdownRenderer :content="content" :plugins="plugins" />
+</template>`;
+
+/**
+ * Renders inline Markdown with bold, italic, and inline code. Use as the
+ * default way to display assistant prose replies.
+ */
+export const Default: Story = {
+  args: {
+    content:
+      'Hello **world**! This is a *simple* paragraph with `inline code`.',
+  },
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * Renders fenced code blocks with language hints. Use when replies contain
+ * code samples and you rely on the default `<pre><code>` styling.
+ */
+export const WithCodeBlocks: Story = {
+  args: {
+    content: [
+      '# Code Example',
+      '',
+      'Here is a JavaScript snippet:',
+      '',
+      '```javascript',
+      'function greet(name) {',
+      '  return `Hello, ${name}!`;',
+      '}',
+      '```',
+      '',
+      'And a Python one:',
+      '',
+      '```python',
+      'def greet(name: str) -> str:',
+      '    return f"Hello, {name}!"',
+      '```',
+    ].join('\n'),
+  },
+  parameters: { docs: { source: { code: withCodeBlocksTemplateSource } } },
+};
+
+/**
+ * Provides a custom `code-block` slot so you can integrate a syntax highlighter
+ * (Shiki, Prism, highlight.js) or render a copy button next to each block.
+ */
+export const WithCustomCodeBlockSlot: Story = {
+  render: () => ({
+    components: { CkMarkdownRenderer },
+    setup() {
+      const content = [
+        'Some text before the code.',
+        '',
+        '```typescript',
+        'const x: number = 42;',
+        'console.log(x);',
+        '```',
+        '',
+        'Some text after the code.',
+      ].join('\n');
+
+      return { content };
+    },
+    template: `
+      <CkMarkdownRenderer :content="content">
+        <template #code-block="{ code, language }">
+          <div style="background: #1e1e1e; color: #d4d4d4; padding: 16px; border-radius: 8px; font-family: monospace; white-space: pre; margin: 8px 0;">
+            <div style="color: #888; font-size: 12px; margin-bottom: 8px;">{{ language }}</div>
+            <code>{{ code }}</code>
+          </div>
+        </template>
+      </CkMarkdownRenderer>
+    `,
+  }),
+  parameters: {
+    docs: { source: { code: withCustomCodeBlockSlotTemplateSource } },
+  },
+};
+
+/**
+ * End-to-end example with headings, lists, code blocks, blockquotes, and a
+ * horizontal rule. Use as a reference for typical long-form assistant output.
+ */
+export const ComplexMarkdown: Story = {
+  args: {
+    content: [
+      '# Project Overview',
+      '',
+      'This document describes the **architecture** of the system.',
+      '',
+      '## Key Features',
+      '',
+      '- Real-time processing',
+      '- Scalable infrastructure',
+      '- Modular design with *pluggable* components',
+      '',
+      '## Setup',
+      '',
+      'Run the following command to install:',
+      '',
+      '```bash',
+      'npm install && npm run build',
+      '```',
+      '',
+      '### Configuration',
+      '',
+      'Edit `config.json` to set your preferences:',
+      '',
+      '```json',
+      '{',
+      '  "port": 3000,',
+      '  "debug": true',
+      '}',
+      '```',
+      '',
+      '> **Note:** Make sure to restart the server after changing configuration.',
+      '',
+      '---',
+      '',
+      'For more details, visit the documentation.',
+    ].join('\n'),
+  },
+  parameters: { docs: { source: { code: complexMarkdownTemplateSource } } },
+};
+
+/**
+ * Overrides default tag styles via the `classes` prop. Use to apply design-system
+ * tokens/Tailwind classes without introducing a code-block slot.
+ */
+export const WithCustomClasses: Story = {
+  render: () => ({
+    components: { CkMarkdownRenderer },
+    setup() {
+      const content = [
+        '# Styled Heading',
+        '',
+        'A paragraph with **bold**, *italic*, and ~~deleted~~ text.',
+        '',
+        '- First item',
+        '- Second item',
+        '',
+        '| Feature | Status |',
+        '| --- | --- |',
+        '| Tables | Done |',
+        '| Styling | Done |',
+        '',
+        '> A blockquote for emphasis.',
+        '',
+        'Visit https://example.com for details.',
+      ].join('\n');
+
+      const classes = {
+        h1: 'text-2xl font-bold mb-4',
+        p: 'text-base leading-7 mb-2',
+        strong: 'font-bold',
+        em: 'italic',
+        del: 'line-through opacity-50',
+        a: 'underline',
+        ul: 'list-disc pl-6 mb-2',
+        li: 'mb-1',
+        table: 'w-full border-collapse mb-4',
+        th: 'border p-2 font-bold text-left',
+        td: 'border p-2',
+        blockquote: 'border-l-4 pl-4 italic opacity-80',
+      };
+
+      return { content, classes };
+    },
+    template: '<CkMarkdownRenderer :content="content" :classes="classes" />',
+  }),
+  parameters: { docs: { source: { code: withCustomClassesTemplateSource } } },
+};
+
+/**
+ * Demonstrates GFM features (tables, task lists, strikethrough, autolinks).
+ * These are enabled by default because the renderer ships with `remark-gfm`.
+ */
+export const GfmFeatures: Story = {
+  args: {
+    content: [
+      '## Tables',
+      '',
+      '| Feature | Status | Priority |',
+      '| --- | :---: | ---: |',
+      '| Tables | Done | High |',
+      '| Strikethrough | Done | Medium |',
+      '| Task lists | Done | Medium |',
+      '| Autolinks | Done | Low |',
+      '',
+      '## Strikethrough',
+      '',
+      'This feature is ~~deprecated~~ and should not be used.',
+      '',
+      '## Task List',
+      '',
+      '- [x] Add remark-gfm',
+      '- [x] Write tests',
+      '- [ ] Ship to production',
+      '',
+      '## Autolinks',
+      '',
+      'Check out https://example.com for more info.',
+    ].join('\n'),
+  },
+  parameters: { docs: { source: { code: gfmFeaturesTemplateSource } } },
+};
+
+function visitTextNodes(node: any, transform: (value: string) => string): void {
+  if (node.type === 'text') {
+    node.value = transform(node.value);
+  }
+  if (node.children) {
+    node.children.forEach((child: any) => visitTextNodes(child, transform));
+  }
+}
+
+const uppercasePlugin = () => (tree: any) => {
+  visitTextNodes(tree, (value) => value.toUpperCase());
+};
+
+/**
+ * Supplies a custom remark/unified plugin through the `plugins` prop. Use to
+ * transform the AST before rendering (e.g. math, directive, custom nodes).
+ */
+export const WithCustomPlugin: Story = {
+  render: () => ({
+    components: { CkMarkdownRenderer },
+    setup() {
+      const content = [
+        '# Important Notice',
+        '',
+        'This text will be **uppercased** by a custom remark plugin.',
+        '',
+        '- List items too',
+        '- Everything gets transformed',
+      ].join('\n');
+
+      return { content, plugins: [uppercasePlugin] };
+    },
+    template: '<CkMarkdownRenderer :content="content" :plugins="plugins" />',
+  }),
+  parameters: { docs: { source: { code: withCustomPluginTemplateSource } } },
+};

package/src/components/base/CkMarkdownRenderer/CkMarkdownRenderer.vue

@@ -0,0 +1,89 @@
+<script lang="ts">
+import {
+  computed,
+  defineComponent,
+  h,
+  toRefs,
+  type PropType,
+  type Slots,
+  type VNode,
+} from 'vue';
+import type { PluggableList } from 'unified';
+import { useMarkdownParser } from '../../../handlers/useMarkdownParser';
+import type { CkMarkdownElementClasses } from './types';
+import { defaultMarkdownClasses } from './defaultMarkdownClasses';
+
+function domToVNode(
+  node: Node,
+  slots: Slots,
+  classes: CkMarkdownElementClasses,
+): VNode | string | null {
+  if (node.nodeType === Node.TEXT_NODE) return node.textContent;
+  if (node.nodeType !== Node.ELEMENT_NODE) return null;
+
+  const el = node as Element;
+
+  if (el.tagName === 'PRE' && el.firstElementChild?.tagName === 'CODE') {
+    const codeEl = el.firstElementChild;
+    const language = codeEl.className?.match(/language-(\S+)/)?.[1] ?? '';
+    const code = codeEl.textContent ?? '';
+
+    if (slots['code-block']) {
+      return slots['code-block']({ code, language }) as unknown as VNode;
+    }
+  }
+
+  const children = Array.from(node.childNodes)
+    .map((child) => domToVNode(child, slots, classes))
+    .filter((c): c is VNode | string => c != null);
+
+  const attrs: Record<string, string> = {};
+  for (const attr of el.attributes) {
+    attrs[attr.name] = attr.value;
+  }
+
+  const tag = el.tagName.toLowerCase();
+  const customClass = classes[tag as keyof CkMarkdownElementClasses];
+  if (customClass) {
+    attrs.class = attrs.class ? `${attrs.class} ${customClass}` : customClass;
+  }
+
+  return h(tag, attrs, children);
+}
+
+export default defineComponent({
+  name: 'CkMarkdownRenderer',
+  props: {
+    content: { type: String, required: true },
+    classes: {
+      type: Object as PropType<CkMarkdownElementClasses>,
+      default: () => ({}),
+    },
+    plugins: { type: Array as PropType<PluggableList>, default: undefined },
+  },
+  setup(props, { slots }) {
+    const { content, plugins } = toRefs(props);
+    const { html } = useMarkdownParser(content, plugins);
+
+    const parsedNodes = computed(() => {
+      const raw = html.value;
+      if (!raw) return [];
+      const doc = new DOMParser().parseFromString(raw, 'text/html');
+      return Array.from(doc.body.childNodes);
+    });
+
+    const mergedClasses = computed<CkMarkdownElementClasses>(() => ({
+      ...defaultMarkdownClasses,
+      ...props.classes,
+    }));
+
+    return () => {
+      const elementClasses = mergedClasses.value;
+      const children = parsedNodes.value
+        .map((node) => domToVNode(node, slots, elementClasses))
+        .filter((c): c is VNode | string => c != null);
+      return h('div', { class: 'markdown-renderer' }, children);
+    };
+  },
+});
+</script>

package/src/components/base/CkMarkdownRenderer/defaultMarkdownClasses.ts

@@ -0,0 +1,19 @@
+import type { CkMarkdownElementClasses } from './types';
+
+export const defaultMarkdownClasses: CkMarkdownElementClasses = {
+  p: 'my-1 leading-7',
+  a: 'underline underline-offset-4',
+  h1: 'mt-4 mb-2 text-2xl font-bold',
+  h2: 'mt-3 mb-2 text-xl font-semibold',
+  h3: 'mt-3 mb-1 text-lg font-semibold',
+  ul: 'my-1 ml-6 list-disc',
+  ol: 'my-1 ml-6 list-decimal',
+  li: 'my-0.5',
+  pre: 'my-2 overflow-x-auto rounded-lg p-4',
+  code: 'rounded px-1.5 py-0.5',
+  blockquote: 'my-2 border-l-2 pl-4 italic',
+  table: 'my-2 w-full border-collapse',
+  th: 'border p-2 text-left font-semibold',
+  td: 'border p-2',
+  hr: 'my-4',
+};

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

@@ -0,0 +1,5 @@
+export { default as CkMarkdownRenderer } from './CkMarkdownRenderer.vue';
+export type {
+  CkMarkdownRendererProps,
+  CkMarkdownElementClasses,
+} from './types';

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

@@ -0,0 +1,53 @@
+import type { PluggableList } from 'unified';
+
+export interface CkMarkdownElementClasses {
+  h1?: string;
+  h2?: string;
+  h3?: string;
+  h4?: string;
+  h5?: string;
+  h6?: string;
+  p?: string;
+  a?: string;
+  img?: string;
+  strong?: string;
+  em?: string;
+  del?: string;
+  blockquote?: string;
+  ul?: string;
+  ol?: string;
+  li?: string;
+  pre?: string;
+  code?: string;
+  hr?: string;
+  br?: string;
+  table?: string;
+  thead?: string;
+  tbody?: string;
+  tr?: string;
+  th?: string;
+  td?: string;
+  input?: string;
+}
+
+/**
+ * Renders a Markdown string as Vue VNodes with per-tag class overrides and an
+ * optional `code-block` slot. Use for assistant messages that contain prose,
+ * lists, tables, and code blocks.
+ *
+ * @category Data Display
+ * @useCases render assistant markdown reply, syntax-highlighted code blocks, GFM tables, chat message body
+ * @keywords markdown, renderer, gfm, remark, code block, prose
+ * @related CkAgentMessage, CkConversation
+ */
+export interface CkMarkdownRendererProps {
+  /** Raw Markdown string to render. */
+  content: string;
+  /**
+   * Per-tag class overrides. Provide Tailwind (or any) classes to style
+   * generated HTML elements (e.g. `h1`, `p`, `ul`).
+   */
+  classes?: CkMarkdownElementClasses;
+  /** Extra [unified](https://unifiedjs.com/) plugins to extend parsing. */
+  plugins?: PluggableList;
+}

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

@@ -0,0 +1,40 @@
+import CkMessageActionButton from './CkMessageActionButton.vue';
+import { render, screen } from '@testing-library/vue';
+import { describe, expect, it } from 'vitest';
+
+describe('CkMessageActionButton', () => {
+  it('renders slot content inside the button', () => {
+    render(CkMessageActionButton, {
+      props: { ariaLabel: 'Action' },
+      slots: { default: '<svg data-testid="icon"></svg>' },
+    });
+
+    expect(screen.getByTestId('icon')).toBeInTheDocument();
+  });
+
+  it('sets the accessible label on the button', () => {
+    render(CkMessageActionButton, {
+      props: { ariaLabel: 'Copy message' },
+    });
+
+    expect(
+      screen.getByRole('button', { name: 'Copy message' }),
+    ).toBeInTheDocument();
+  });
+
+  it('passes disabled state to the button', () => {
+    render(CkMessageActionButton, {
+      props: { ariaLabel: 'Action', disabled: true },
+    });
+
+    expect(screen.getByRole('button', { name: 'Action' })).toBeDisabled();
+  });
+
+  it('defaults to enabled', () => {
+    render(CkMessageActionButton, {
+      props: { ariaLabel: 'Action' },
+    });
+
+    expect(screen.getByRole('button', { name: 'Action' })).toBeEnabled();
+  });
+});

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

@@ -0,0 +1,56 @@
+import CkMessageActionButton from './CkMessageActionButton.vue';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { UiIcon } from '@aleph-alpha/ui-library';
+
+const meta: Meta<typeof CkMessageActionButton> = {
+  title: 'Base/CkMessageActionButton',
+  component: CkMessageActionButton,
+  tags: ['autodocs'],
+  argTypes: {
+    ariaLabel: {
+      control: 'text',
+      description:
+        'Accessible label for the button. Required because the button is icon-only.',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Whether the button is disabled and ignores clicks.',
+    },
+  },
+  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 { CkMessageActionButton } from '@aleph-alpha/chat-kit';
+import { UiIcon } from '@aleph-alpha/ui-library';
+</script>
+
+<template>
+  <CkMessageActionButton ariaLabel="Copy message">
+    <UiIcon name="copy" :size="16" aria-hidden="true" />
+  </CkMessageActionButton>
+</template>`;
+
+/**
+ * Generic icon-only action button used in message footers. Supply any icon
+ * in the default slot and a descriptive `ariaLabel` for screen readers.
+ */
+export const Default: Story = {
+  render: () => ({
+    components: { CkMessageActionButton, UiIcon },
+    template: `
+      <CkMessageActionButton ariaLabel="Copy message">
+        <UiIcon name="copy" :size="16" aria-hidden="true" />
+      </CkMessageActionButton>
+    `,
+  }),
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};

package/src/components/base/CkMessageActionButton/CkMessageActionButton.vue

@@ -0,0 +1,23 @@
+<script setup lang="ts">
+import type { CkMessageActionButtonProps } from './types';
+import { UiButton } from '@aleph-alpha/ui-library';
+
+defineOptions({
+  name: 'CkMessageActionButton',
+});
+
+withDefaults(defineProps<CkMessageActionButtonProps>(), {
+  disabled: false,
+});
+</script>
+
+<template>
+  <UiButton
+    v-bind="{ ariaLabel }"
+    :disabled="disabled"
+    variant="ghost"
+    size="icon-sm"
+  >
+    <slot />
+  </UiButton>
+</template>

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

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

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

@@ -0,0 +1,21 @@
+/**
+ * Small icon-only action button used in the footer of chat messages. Acts as
+ * a ghost-styled wrapper around `UiButton` with consistent chat-kit tokens.
+ *
+ * @category Actions
+ * @useCases message footer action, like/dislike reaction, share button on reply, secondary message action
+ * @keywords icon button, action, message, ghost, accessible, aria-label
+ * @related CkCopyMessageActionButton, CkAgentMessage, CkConversation
+ */
+export interface CkMessageActionButtonProps {
+  /**
+   * Accessible label for the button. **Required** because the button only
+   * renders an icon.
+   */
+  ariaLabel: string;
+  /**
+   * Whether the button is disabled and ignores clicks.
+   * @default false
+   */
+  disabled?: boolean;
+}