@aleph-alpha/chat-kit 5.13.0 → 6.1.0

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

@@ -0,0 +1,221 @@
+import { render, waitFor } from '@testing-library/vue';
+import { insert } from '@milkdown/kit/utils';
+import CkMilkdownEditor from './CkMilkdownEditor.vue';
+import { defaultMarkdownClasses } from '../CkMarkdownRenderer/defaultMarkdownClasses';
+import { applyMarkdownClasses, type AttrCtx } from './markdownClassAttrs';
+import { createCrepeEditor } from './createCrepeEditor';
+import { defaultChatKitLabels } from '../../../handlers/useChatKitLabels';
+
+// ProseMirror measures selections and positions during mount; jsdom lacks the
+// layout APIs it calls. Stubs are scoped to this spec (not `test-setup.ts`) so
+// other specs keep running against an unmodified jsdom.
+const EMPTY_RECT = {
+  x: 0,
+  y: 0,
+  top: 0,
+  left: 0,
+  right: 0,
+  bottom: 0,
+  width: 0,
+  height: 0,
+  toJSON: () => ({}),
+} as DOMRect;
+
+beforeAll(() => {
+  Range.prototype.getBoundingClientRect = () => EMPTY_RECT;
+  Range.prototype.getClientRects = () =>
+    ({
+      length: 0,
+      item: () => null,
+      *[Symbol.iterator]() {
+        // no rects
+      },
+    }) as unknown as DOMRectList;
+  Element.prototype.scrollIntoView ??= () => undefined;
+  document.elementFromPoint ??= () => null;
+});
+
+async function renderEditor(
+  props: InstanceType<typeof CkMilkdownEditor>['$props'] = {},
+) {
+  const utils = render(CkMilkdownEditor, { props });
+  // The editor loads lazily; the ready class is set once Crepe has created the
+  // view and the initial props have been applied.
+  await waitFor(() =>
+    expect(
+      utils.container.querySelector('.ck-milkdown--ready .ProseMirror'),
+    ).toBeInTheDocument(),
+  );
+  return utils;
+}
+
+describe('CkMilkdownEditor', () => {
+  it('renders the initial markdown as editable DOM', async () => {
+    const { container } = await renderEditor({
+      modelValue: '# Title\n\nSome *text*\n\n- one\n- two',
+    });
+
+    expect(container.querySelector('h1')?.textContent).toBe('Title');
+    expect(container.querySelector('em')?.textContent).toBe('text');
+    expect(container.querySelectorAll('li')).toHaveLength(2);
+  });
+
+  it('applies the CkMarkdownRenderer default classes to the nodes', async () => {
+    const { container } = await renderEditor({
+      modelValue:
+        '# Title\n\nA paragraph with `code` and a [link](https://a.b).',
+    });
+
+    expect(container.querySelector('h1')?.className).toContain(
+      defaultMarkdownClasses.h1,
+    );
+    expect(container.querySelector('p')?.className).toContain(
+      defaultMarkdownClasses.p,
+    );
+    expect(container.querySelector('code')?.className).toContain(
+      defaultMarkdownClasses.code,
+    );
+    expect(container.querySelector('a')?.className).toContain(
+      defaultMarkdownClasses.a,
+    );
+  });
+
+  it('lets `classes` override a tag while keeping the other defaults', async () => {
+    const { container } = await renderEditor({
+      modelValue: '# Title\n\nParagraph',
+      classes: { h1: 'custom-h1' },
+    });
+
+    const h1 = container.querySelector('h1');
+    expect(h1?.className).toContain('custom-h1');
+    expect(h1?.className).not.toContain(defaultMarkdownClasses.h1);
+    expect(container.querySelector('p')?.className).toContain(
+      defaultMarkdownClasses.p,
+    );
+  });
+
+  it('applies an external modelValue change without echoing it back', async () => {
+    const { container, rerender, emitted } = await renderEditor({
+      modelValue: '# One',
+    });
+
+    await rerender({ modelValue: '## Two' });
+
+    await waitFor(() =>
+      expect(container.querySelector('h2')?.textContent).toBe('Two'),
+    );
+    expect(container.querySelector('h1')).toBeNull();
+
+    // Give Milkdown's debounced listener time to fire, then make sure the value
+    // we applied was not emitted back to the parent.
+    await new Promise((resolve) => setTimeout(resolve, 300));
+    const updates = (emitted()['update:modelValue'] ?? []) as string[][];
+    expect(updates.map(([value]) => value)).not.toContain('## Two');
+  });
+
+  it('toggles contenteditable with `readonly`', async () => {
+    const { container, rerender } = await renderEditor({
+      modelValue: 'Hello',
+      readonly: true,
+    });
+
+    const pm = () => container.querySelector('.ProseMirror');
+    expect(pm()?.getAttribute('contenteditable')).toBe('false');
+
+    await rerender({ modelValue: 'Hello', readonly: false });
+    await waitFor(() =>
+      expect(pm()?.getAttribute('contenteditable')).toBe('true'),
+    );
+  });
+
+  it('marks the root disabled and locks editing with `disabled`', async () => {
+    const { container } = await renderEditor({
+      modelValue: 'Hello',
+      disabled: true,
+    });
+
+    expect(
+      container.querySelector('.ck-milkdown')?.getAttribute('aria-disabled'),
+    ).toBe('true');
+    expect(
+      container.querySelector('.ProseMirror')?.getAttribute('contenteditable'),
+    ).toBe('false');
+  });
+
+  it('exposes the editable region as a labelled textbox', async () => {
+    const { container } = await renderEditor({
+      modelValue: 'Hello',
+      ariaLabel: 'Reply editor',
+    });
+
+    const textbox = container.querySelector('[role="textbox"]');
+    expect(textbox).toBe(container.querySelector('.ProseMirror'));
+    expect(textbox?.getAttribute('aria-label')).toBe('Reply editor');
+    expect(textbox?.getAttribute('aria-multiline')).toBe('true');
+  });
+
+  it('does not throw when unmounted before or after the editor is created', async () => {
+    const early = render(CkMilkdownEditor, { props: { modelValue: 'x' } });
+    expect(() => early.unmount()).not.toThrow();
+
+    const late = await renderEditor({ modelValue: 'y' });
+    expect(() => late.unmount()).not.toThrow();
+  });
+});
+
+describe('createCrepeEditor', () => {
+  it('reports document changes through onMarkdownUpdated', async () => {
+    const root = document.createElement('div');
+    document.body.append(root);
+    const onMarkdownUpdated = vi.fn();
+
+    const handle = await createCrepeEditor({
+      root,
+      defaultValue: 'Hello',
+      classes: defaultMarkdownClasses,
+      labels: defaultChatKitLabels,
+      onMarkdownUpdated,
+    });
+
+    expect(handle.getMarkdown().trim()).toBe('Hello');
+
+    handle.crepe.editor.action(insert(' world', true));
+
+    await waitFor(() => expect(onMarkdownUpdated).toHaveBeenCalled());
+    expect(onMarkdownUpdated.mock.lastCall?.[0]).toContain('world');
+
+    handle.destroy();
+    root.remove();
+  });
+});
+
+describe('applyMarkdownClasses', () => {
+  function captureHooks(classes: Parameters<typeof applyMarkdownClasses>[1]) {
+    const hooks = new Map<unknown, (node: unknown) => unknown>();
+    const ctx = {
+      set: vi.fn((key: unknown, value: unknown) => {
+        hooks.set(key, value as (node: unknown) => unknown);
+      }),
+    } as unknown as AttrCtx;
+    applyMarkdownClasses(ctx, classes);
+    return { ctx, hooks: [...hooks.values()] };
+  }
+
+  it('maps heading levels to the matching h* class', () => {
+    const { hooks } = captureHooks({ h1: 'one', h2: 'two' });
+    const results = hooks.map((hook) => hook({ attrs: { level: 2 } }));
+    expect(results).toContainEqual({ class: 'two' });
+    expect(results).not.toContainEqual({ class: 'one' });
+  });
+
+  it('returns no attributes for tags without a class', () => {
+    const { hooks } = captureHooks({});
+    for (const hook of hooks) {
+      const result = hook({ attrs: { level: 1 } }) as Record<string, unknown>;
+      // The code block hook returns per-element maps; every other hook returns
+      // the element's attributes directly. Either way nothing should be set.
+      const values = 'pre' in result ? Object.values(result) : [result];
+      for (const value of values) expect(value).toEqual({});
+    }
+  });
+});

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

@@ -0,0 +1,274 @@
+import { ref } from 'vue';
+import { UiCodeBlock } from '@aleph-alpha/ui-library';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import CkMilkdownEditor from './CkMilkdownEditor.vue';
+import CkMarkdownRenderer from '../CkMarkdownRenderer/CkMarkdownRenderer.vue';
+
+const meta: Meta<typeof CkMilkdownEditor> = {
+  title: 'Base/CkMilkdownEditor',
+  component: CkMilkdownEditor,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: {
+      control: 'text',
+      description: 'Markdown source of the document (`v-model`).',
+    },
+    classes: {
+      control: 'object',
+      description:
+        'Per-tag class overrides, merged over the same defaults `CkMarkdownRenderer` uses.',
+    },
+    placeholder: {
+      control: 'text',
+      description: 'Shown when the document is empty. Read once at mount.',
+    },
+    readonly: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    autofocus: { control: 'boolean' },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const richContent = [
+  '# Release notes',
+  '',
+  'This build ships **bold** changes, a few *italic* remarks, ~~dropped~~ ideas and some `inline code`. Read the [documentation](https://example.com) for details.',
+  '',
+  '## Highlights',
+  '',
+  '- Faster streaming',
+  '- Smaller bundles',
+  '  - Lazy-loaded editor',
+  '  - Tree-shaken icons',
+  '',
+  '1. Install',
+  '2. Configure',
+  '3. Ship',
+  '',
+  '- [x] Write the code',
+  '- [ ] Write the docs',
+  '',
+  '> **Note:** the editor and the renderer share one class map.',
+  '',
+  '---',
+  '',
+  '```typescript',
+  'export function greet(name: string): string {',
+  '  const message = `Hello, ${name}!`; // template literal',
+  '  return message.toUpperCase();',
+  '}',
+  '```',
+].join('\n');
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+
+const markdown = ref('');
+</script>
+
+<template>
+  <CkMilkdownEditor
+    v-model="markdown"
+    placeholder="Write your reply…"
+    aria-label="Reply editor"
+  />
+</template>`;
+
+const withInitialContentTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+
+const markdown = ref(\`# Release notes
+
+This build ships **bold** changes and some \\\`inline code\\\`.
+
+- Faster streaming
+- Smaller bundles
+
+\\\`\\\`\\\`typescript
+export function greet(name: string): string {
+  return \\\`Hello, \\\${name}!\\\`;
+}
+\\\`\\\`\\\`\`);
+</script>
+
+<template>
+  <CkMilkdownEditor v-model="markdown" aria-label="Release notes" />
+</template>`;
+
+const readonlyTemplateSource = `<script setup lang="ts">
+import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+
+const markdown = '# Read me\\n\\nThis document **cannot** be edited.';
+</script>
+
+<template>
+  <CkMilkdownEditor :model-value="markdown" readonly aria-label="Read-only document" />
+</template>`;
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+
+const markdown = '# Unavailable\\n\\nThis editor is currently disabled.';
+</script>
+
+<template>
+  <CkMilkdownEditor
+    :model-value="markdown"
+    disabled
+    aria-label="Disabled document"
+  />
+</template>`;
+
+const customClassesTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+
+const markdown = ref('# Styled heading\\n\\nA paragraph with **bold** text.');
+const classes = {
+  h1: 'mt-6 mb-3 text-3xl font-black tracking-tight',
+  p: 'my-2 leading-8',
+};
+</script>
+
+<template>
+  <CkMilkdownEditor v-model="markdown" :classes="classes" aria-label="Styled editor" />
+</template>`;
+
+const sideBySideTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkMarkdownRenderer, CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+import { UiCodeBlock } from '@aleph-alpha/ui-library';
+
+const markdown = ref('# Hello\\n\\nEdit me on the left, watch the right.');
+</script>
+
+<template>
+  <div class="text-content-on-surface-primary grid gap-6 text-base leading-7 md:grid-cols-2">
+    <CkMilkdownEditor v-model="markdown" aria-label="Editor" />
+    <CkMarkdownRenderer :content="markdown">
+      <template #code-block="{ code, language }">
+        <UiCodeBlock :code="code" :language="language || 'text'" />
+      </template>
+    </CkMarkdownRenderer>
+  </div>
+</template>`;
+
+/**
+ * Empty editor with a placeholder. Select text to reveal the floating toolbar
+ * (bold, italic, strikethrough, inline code, link); type `- `, `1. `, `> ` or
+ * a fenced ``` block to create lists, quotes and code.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { CkMilkdownEditor },
+    setup() {
+      const markdown = ref(args.modelValue ?? '');
+      return { args, markdown };
+    },
+    template: `
+      <CkMilkdownEditor
+        v-bind="args"
+        v-model="markdown"
+        placeholder="Write your reply…"
+        aria-label="Reply editor"
+      />
+    `,
+  }),
+  args: { modelValue: '' },
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * A document exercising every enabled node: headings, inline marks, links,
+ * nested / ordered / task lists, a blockquote, a rule and a highlighted code
+ * block. Compare with `CkMarkdownRenderer`'s stories — the spacing and type
+ * scale are identical because both use the same class map.
+ */
+export const WithInitialContent: Story = {
+  render: (args) => ({
+    components: { CkMilkdownEditor },
+    setup() {
+      const markdown = ref(args.modelValue ?? '');
+      return { args, markdown };
+    },
+    template: `<CkMilkdownEditor v-bind="args" v-model="markdown" aria-label="Release notes" />`,
+  }),
+  args: { modelValue: richContent },
+  parameters: { docs: { source: { code: withInitialContentTemplateSource } } },
+};
+
+/**
+ * `readonly` renders the document without a caret or toolbar. Use it to show
+ * a message in the editor's layout while a request is in flight.
+ */
+export const Readonly: Story = {
+  args: { modelValue: richContent, readonly: true },
+  parameters: { docs: { source: { code: readonlyTemplateSource } } },
+};
+
+/**
+ * `disabled` also mutes the content and blocks pointer interaction, and sets
+ * `aria-disabled` on the root.
+ */
+export const Disabled: Story = {
+  args: {
+    modelValue: '# Unavailable\n\nThis editor is currently disabled.',
+    disabled: true,
+  },
+  parameters: { docs: { source: { code: disabledTemplateSource } } },
+};
+
+/**
+ * `classes` overrides individual tags while the rest keeps the defaults — the
+ * same contract as `CkMarkdownRenderer`'s `classes` prop, so one object can
+ * drive both components.
+ */
+export const CustomClasses: Story = {
+  render: (args) => ({
+    components: { CkMilkdownEditor },
+    setup() {
+      const markdown = ref(args.modelValue ?? '');
+      return { args, markdown };
+    },
+    template: `<CkMilkdownEditor v-bind="args" v-model="markdown" aria-label="Styled editor" />`,
+  }),
+  args: {
+    modelValue: '# Styled heading\n\nA paragraph with **bold** text.',
+    classes: {
+      h1: 'mt-6 mb-3 text-3xl font-black tracking-tight',
+      p: 'my-2 leading-8',
+    },
+  },
+  parameters: { docs: { source: { code: customClassesTemplateSource } } },
+};
+
+/**
+ * Live parity check: the editor on the left drives `CkMarkdownRenderer` on the
+ * right through one `v-model`. Toggle the theme toolbar to compare light and
+ * dark, including the code block against `UiCodeBlock`.
+ */
+export const SideBySideWithRenderer: Story = {
+  render: (args) => ({
+    components: { CkMilkdownEditor, CkMarkdownRenderer, UiCodeBlock },
+    setup() {
+      const markdown = ref(args.modelValue ?? '');
+      return { args, markdown };
+    },
+    template: `
+      <div class="text-content-on-surface-primary grid gap-6 text-base leading-7 md:grid-cols-2">
+        <CkMilkdownEditor v-bind="args" v-model="markdown" aria-label="Editor" />
+        <CkMarkdownRenderer :content="markdown">
+          <template #code-block="{ code, language }">
+            <UiCodeBlock :code="code" :language="language || 'text'" />
+          </template>
+        </CkMarkdownRenderer>
+      </div>
+    `,
+  }),
+  args: { modelValue: richContent },
+  parameters: { docs: { source: { code: sideBySideTemplateSource } } },
+};

package/src/components/base/CkMilkdownEditor/CkMilkdownEditor.vue

@@ -0,0 +1,151 @@
+<script setup lang="ts">
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  useTemplateRef,
+  watch,
+} from 'vue';
+import { useChatKitLabels } from '../../../handlers/useChatKitLabels';
+import { defaultMarkdownClasses } from '../CkMarkdownRenderer/defaultMarkdownClasses';
+import type { CrepeEditorHandle } from './createCrepeEditor';
+import type { CkMilkdownEditorEmits, CkMilkdownEditorProps } from './types';
+
+defineOptions({ name: 'CkMilkdownEditor' });
+
+const props = withDefaults(defineProps<CkMilkdownEditorProps>(), {
+  modelValue: '',
+  placeholder: undefined,
+  readonly: false,
+  disabled: false,
+  ariaLabel: undefined,
+  classes: () => ({}),
+  autofocus: false,
+});
+
+const emit = defineEmits<CkMilkdownEditorEmits>();
+
+const labels = useChatKitLabels();
+const rootRef = useTemplateRef<HTMLDivElement>('rootRef');
+const isLocked = computed(() => props.readonly || props.disabled);
+// Flips once Crepe has finished creating the view; exposed as a root class so
+// consumers (and tests) can tell the lazy-loaded editor apart from its shell.
+const isReady = ref(false);
+
+let editor: CrepeEditorHandle | undefined;
+let destroyed = false;
+// The last markdown we either emitted or applied from the prop. Comparing
+// against it (rather than a boolean "applying" flag) is what makes the echo
+// guard immune to Milkdown's ~200 ms debounce on `markdownUpdated`.
+let lastKnownMarkdown = props.modelValue;
+
+function handleMarkdownUpdated(markdown: string): void {
+  if (markdown === lastKnownMarkdown) return;
+  lastKnownMarkdown = markdown;
+  emit('update:modelValue', markdown);
+}
+
+onMounted(async () => {
+  const root = rootRef.value;
+  if (!root) return;
+
+  // Lazy: Milkdown, ProseMirror and CodeMirror only load once an editor is
+  // actually mounted, keeping them out of consumers' initial bundle.
+  const { createCrepeEditor } = await import('./createCrepeEditor');
+  if (destroyed) return;
+
+  const initialMarkdown = props.modelValue;
+  lastKnownMarkdown = initialMarkdown;
+  const handle = await createCrepeEditor({
+    root,
+    defaultValue: initialMarkdown,
+    placeholder: props.placeholder,
+    ariaLabel: props.ariaLabel,
+    readonly: isLocked.value,
+    classes: { ...defaultMarkdownClasses, ...props.classes },
+    labels: labels.value,
+    onMarkdownUpdated: handleMarkdownUpdated,
+  });
+
+  // Unmounted while `create()` was pending.
+  if (destroyed) {
+    handle.destroy();
+    return;
+  }
+
+  editor = handle;
+  // Props may have moved on while the editor was being created; the watchers
+  // below could not apply them yet, so catch up here.
+  if (props.modelValue !== initialMarkdown)
+    handle.setMarkdown(props.modelValue);
+  handle.setReadonly(isLocked.value);
+  isReady.value = true;
+  if (props.autofocus) handle.focus();
+});
+
+watch(
+  () => props.modelValue,
+  (next) => {
+    if (next === lastKnownMarkdown) return;
+    lastKnownMarkdown = next;
+    editor?.setMarkdown(next);
+  },
+);
+
+watch(isLocked, (locked) => {
+  editor?.setReadonly(locked);
+});
+
+onBeforeUnmount(() => {
+  destroyed = true;
+  editor?.destroy();
+  editor = undefined;
+});
+
+function isInsideRoot(target: EventTarget | null): boolean {
+  return target instanceof Node && (rootRef.value?.contains(target) ?? false);
+}
+
+// The floating toolbar and the link tooltip live inside the root, so moving
+// focus between them and the text must not count as leaving the editor.
+function onFocusIn(event: FocusEvent): void {
+  if (!isInsideRoot(event.relatedTarget)) emit('focus');
+}
+
+function onFocusOut(event: FocusEvent): void {
+  if (!isInsideRoot(event.relatedTarget)) emit('blur');
+}
+
+function focus(): void {
+  editor?.focus();
+}
+
+function getMarkdown(): string {
+  return editor?.getMarkdown() ?? props.modelValue;
+}
+
+defineExpose({ focus, getMarkdown });
+</script>
+
+<template>
+  <div
+    ref="rootRef"
+    :class="[
+      'ck-milkdown min-w-0 break-words',
+      isReady && 'ck-milkdown--ready',
+      disabled && 'ck-milkdown--disabled',
+    ]"
+    :aria-disabled="disabled || undefined"
+    @focusin="onFocusIn"
+    @focusout="onFocusOut"
+  />
+</template>
+
+<style scoped>
+.ck-milkdown--disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+</style>