@aleph-alpha/chat-kit 6.3.0 → 6.4.1

package/src/components/base/CkCodeEditor/CkCodeEditor.vue

@@ -1,13 +1,14 @@
 <script setup lang="ts">
 import {
   computed,
+  nextTick,
   onBeforeUnmount,
   onMounted,
   ref,
   useTemplateRef,
   watch,
 } from 'vue';
-import { UiButton, UiIcon } from '@aleph-alpha/ui-library';
+import { UiButton, UiFadeMask, UiIcon } from '@aleph-alpha/ui-library';
 import { useChatKitLabels } from '../../../handlers/useChatKitLabels';
 import type { CodeMirrorHandle } from './createCodeMirror';
 import type { CkCodeEditorEmits, CkCodeEditorProps } from './types';
@@ -28,6 +29,8 @@ const props = withDefaults(defineProps<CkCodeEditorProps>(), {
   lineWrapping: false,
   maxHeight: undefined,
   autofocus: false,
+  scrollFade: true,
+  badge: undefined,
   writeToClipboard: undefined,
 });
 
@@ -53,6 +56,63 @@ const copyLabel = computed(() =>
     : (labels.value.codeEditorCopy ?? 'Copy code'),
 );
 
+// Whether there is code hidden above / below the visible area. Each fade is
+// shown only for the direction that can actually scroll, so a document that
+// fits its box shows none.
+const canScrollUp = ref(false);
+const canScrollDown = ref(false);
+let scrollTarget: HTMLElement | undefined;
+let scrollObserver: ResizeObserver | undefined;
+
+// 53px is the band height the design file uses for this mask, rather than
+// `UiFadeMask`'s own 4rem/6rem default, which is sized for page-level surfaces.
+const FADE_HEIGHT = '53px';
+
+function edgeToFade(up: boolean, down: boolean): 'top' | 'bottom' | 'both' {
+  if (up && down) return 'both';
+  return up ? 'top' : 'bottom';
+}
+
+// `UiFadeMask` takes the edges to draw rather than two independent flags, and
+// has no "neither" position, so a document that fits collapses the band to zero
+// height instead. Swapping the wrapper out for a plain `div` on every change
+// would remount the host element and take CodeMirror's DOM with it, so the mask
+// stays mounted for as long as `scrollFade` is on.
+const fadeProps = computed(() => {
+  if (!props.scrollFade) return {};
+  const up = canScrollUp.value;
+  const down = canScrollDown.value;
+  return {
+    position: edgeToFade(up, down),
+    background: 'secondary',
+    style: { '--ui-fade-mask-height': up || down ? FADE_HEIGHT : '0px' },
+  };
+});
+
+function syncScrollFades(): void {
+  if (!scrollTarget) return;
+  const { scrollTop, scrollHeight, clientHeight } = scrollTarget;
+  canScrollUp.value = scrollTop > 1;
+  // A pixel of slack: fractional layout sizes otherwise leave the bottom fade
+  // showing when the document is scrolled fully down.
+  canScrollDown.value = scrollTop + clientHeight < scrollHeight - 1;
+}
+
+function watchScrolling(scroller: HTMLElement, content: HTMLElement): void {
+  scrollTarget = scroller;
+  scroller.addEventListener('scroll', syncScrollFades, { passive: true });
+  if (typeof ResizeObserver !== 'undefined') {
+    // Neither of these fires a scroll event. The scroller covers the box being
+    // resized; the content is watched separately because once `maxHeight` caps
+    // the scroller, typing a new line grows only the content, and the bottom
+    // fade would otherwise never appear.
+    scrollObserver = new ResizeObserver(syncScrollFades);
+    scrollObserver.observe(scroller);
+    scrollObserver.observe(content);
+  }
+  syncScrollFades();
+}
+
 let editor: CodeMirrorHandle | undefined;
 let destroyed = false;
 // Last value emitted or applied, so an echo from the parent is not re-applied.
@@ -84,9 +144,9 @@ onMounted(async () => {
     readonly: isLocked.value,
     showLineNumbers: props.showLineNumbers,
     lineWrapping: props.lineWrapping,
+    badge: props.badge,
     onChange: handleChange,
     onFocus: () => emit('focus'),
-    onBlur: () => emit('blur'),
   });
 
   // Unmounted while the grammar was loading.
@@ -98,6 +158,7 @@ onMounted(async () => {
   editor = handle;
   // Props may have moved on while the grammar loaded; catch up.
   if (props.modelValue !== initialCode) handle.setCode(props.modelValue);
+  watchScrolling(handle.view.scrollDOM, handle.view.contentDOM);
   isReady.value = true;
   if (props.autofocus) handle.focus();
 });
@@ -108,6 +169,7 @@ watch(
     if (next === lastKnownCode) return;
     lastKnownCode = next;
     editor?.setCode(next);
+    void nextTick(syncScrollFades);
   },
 );
 
@@ -128,10 +190,17 @@ watch(
   () => props.lineWrapping,
   (wrap) => editor?.setLineWrapping(wrap),
 );
+watch(
+  () => props.badge,
+  (rule) => editor?.setBadge(rule),
+);
 
 onBeforeUnmount(() => {
   destroyed = true;
   clearTimeout(copyTimer);
+  scrollTarget?.removeEventListener('scroll', syncScrollFades);
+  scrollObserver?.disconnect();
+  scrollTarget = undefined;
   editor?.destroy();
   editor = undefined;
 });
@@ -157,8 +226,9 @@ function isInsideRoot(target: EventTarget | null): boolean {
   return target instanceof Node && (rootRef.value?.contains(target) ?? false);
 }
 
-// CodeMirror reports focus on its own content; the header's copy button is
-// outside that, so only a move out of the whole component counts as a blur.
+// The single source of `blur`. CodeMirror reports focus loss on its own
+// content, which would fire for a move to the header's copy button; only a move
+// out of the whole component counts, and only the root can see that.
 function onFocusOut(event: FocusEvent): void {
   if (!isInsideRoot(event.relatedTarget)) emit('blur');
 }
@@ -178,7 +248,7 @@ defineExpose({ focus, getCode });
   <div
     ref="rootRef"
     :class="[
-      'ck-code-editor ck-code-surface border-border-surface-default min-w-0 overflow-hidden rounded-lg border',
+      'ck-code-editor ck-code-surface border-border-surface-default bg-background-input-default min-w-0 overflow-hidden rounded-xl border',
       isReady && 'ck-code-editor--ready',
       isLocked && 'ck-code-editor--readonly',
       disabled && 'ck-code-editor--disabled',
@@ -188,9 +258,9 @@ defineExpose({ focus, getCode });
   >
     <div
       v-if="showHeader"
-      class="border-border-surface-default bg-background-surface-muted flex items-center justify-between border-b px-4 py-2"
+      class="bg-background-surface-muted-subtle flex h-9 items-center justify-between px-3"
     >
-      <span class="text-content-on-surface-secondary font-mono text-sm">
+      <span class="text-content-on-surface-secondary label-12-regular">
         {{ headerLabel }}
       </span>
       <UiButton
@@ -204,15 +274,33 @@ defineExpose({ focus, getCode });
       </UiButton>
     </div>
 
-    <div
-      ref="hostRef"
-      class="ck-code-editor__host"
-      :style="maxHeight ? { '--ck-code-max-height': maxHeight } : undefined"
-    />
+    <component
+      :is="scrollFade ? UiFadeMask : 'div'"
+      v-bind="fadeProps"
+      class="ck-code-editor__body min-w-0"
+    >
+      <div
+        ref="hostRef"
+        class="ck-code-editor__host"
+        :style="maxHeight ? { '--ck-code-max-height': maxHeight } : undefined"
+      />
+    </component>
   </div>
 </template>
 
 <style scoped>
+/* The body follows the design-system field rather than `UiCodeBlock`: body
+ * text in the primary content colour on the input surface, with muted mono
+ * line numbers. Only the syntax colours stay shared with `UiCodeBlock` (see
+ * `helpers/codemirror/code-palette.css`). The overrides live here, not in
+ * `theme.ts`, because `CkMilkdownEditor`'s code blocks use that theme too and
+ * must keep matching the rendered block. */
+.ck-code-editor {
+  --ck-cm-bg: transparent;
+  --ck-cm-foreground: oklch(var(--content-on-surface-primary));
+  --ck-cm-line-number: oklch(var(--content-on-surface-muted));
+}
+
 /* The editor fills the panel; `:deep` is needed because CodeMirror builds its
  * own DOM, which scoped styles do not reach. */
 .ck-code-editor__host :deep(.cm-editor) {
@@ -220,8 +308,43 @@ defineExpose({ focus, getCode });
   color: var(--ck-cm-foreground);
 }
 
+/* Same declarations as the `body-14-regular` typography utility. */
 .ck-code-editor__host :deep(.cm-scroller) {
   max-height: var(--ck-code-max-height, none);
+  font-family: Saans, sans-serif;
+  font-size: 0.875rem;
+  font-weight: 400;
+  line-height: 1.25rem;
+}
+
+/* 12px below the header, 16px above the bottom edge, and a 20px right inset,
+ * as in the design. */
+.ck-code-editor__host :deep(.cm-content) {
+  padding: 0.75rem 1.25rem 1rem 1rem;
+}
+
+/* The number column already carries the 1rem left inset, so the code must not
+ * pay for it a second time. The sibling selector only matches while the gutter
+ * is mounted, which is exactly when `showLineNumbers` is on. */
+.ck-code-editor__host :deep(.cm-gutters ~ .cm-content) {
+  padding-left: 0;
+}
+
+/* Numbers stay monospaced so the column does not jitter as digits change; the
+ * 12px right padding is the gap before the code. */
+.ck-code-editor__host :deep(.cm-lineNumbers .cm-gutterElement) {
+  min-width: 0;
+  padding: 0 0.75rem 0 1rem;
+  /* `CODE_FONT_FAMILY` from `theme.ts`, repeated because importing it here
+   * would pull CodeMirror out of its lazy chunk. */
+  font-family:
+    ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono',
+    monospace;
+  font-weight: 500;
+}
+
+.ck-code-editor__host :deep(.cm-placeholder) {
+  color: oklch(var(--content-on-surface-muted));
 }
 
 /* Nothing is being edited, so the active-line band would only be noise. */

package/src/components/base/CkCodeEditor/badgeDecoration.ts

@@ -0,0 +1,173 @@
+import type { Extension, Range } from '@codemirror/state';
+import {
+  Decoration,
+  type DecorationSet,
+  EditorView,
+  MatchDecorator,
+  ViewPlugin,
+  type ViewUpdate,
+  WidgetType,
+} from '@codemirror/view';
+import DOMPurify from 'dompurify';
+
+/** What a matched reference should look like once it is drawn as a pill. */
+export interface CkCodeEditorBadgeContent {
+  /** Text inside the pill. */
+  label: string;
+  /**
+   * Optional inline SVG markup for a leading icon, sized to 12px. This is
+   * developer-supplied configuration rather than document content, and it is
+   * sanitised before it reaches the DOM.
+   */
+  icon?: string;
+  /** Native tooltip, useful for showing the underlying reference. */
+  title?: string;
+  /**
+   * Classes replacing the default pill styling, which is the secondary badge
+   * the ChatKit design file specifies.
+   */
+  class?: string;
+}
+
+/** Rule turning matched text in the document into inline pills. */
+export interface CkCodeEditorBadgeRule {
+  /**
+   * Pattern matched within each line. A non-global pattern is promoted to a
+   * global one, and matching never crosses a line break.
+   */
+  pattern: RegExp;
+  /**
+   * Maps a match to its pill, or returns `null` to leave that occurrence as
+   * ordinary text. The match array carries any capture groups.
+   */
+  render: (match: RegExpExecArray) => CkCodeEditorBadgeContent | null;
+}
+
+// The badge as the ChatKit design file specifies it: the shadcn `secondary`
+// badge at a 6px radius, 8px/2px padding, a 4px gap and a 12px label. Written
+// out because a widget builds DOM imperatively and cannot mount a Vue component
+// cheaply; these class names sit in chat-kit source, so UnoCSS emits them into
+// the package stylesheet like any other.
+const DEFAULT_BADGE_CLASS =
+  'ck-code-badge inline-flex w-fit shrink-0 select-none items-center justify-center gap-1 ' +
+  'overflow-hidden whitespace-nowrap rounded-md border border-border-surface-default ' +
+  'bg-background-button-secondary-button text-content-on-surface-primary px-2 py-0.5 ' +
+  'label-12-regular align-middle';
+
+class BadgeWidget extends WidgetType {
+  constructor(private readonly content: CkCodeEditorBadgeContent) {
+    super();
+  }
+
+  // Decorations are rebuilt on every document and viewport change. Without a
+  // real comparison here every pill would be torn down and recreated on each
+  // keystroke, which flickers and drops any focus inside the widget.
+  override eq(other: BadgeWidget): boolean {
+    return (
+      other.content.label === this.content.label &&
+      other.content.icon === this.content.icon &&
+      other.content.title === this.content.title &&
+      other.content.class === this.content.class
+    );
+  }
+
+  toDOM(): HTMLElement {
+    const el = document.createElement('span');
+    el.className = this.content.class ?? DEFAULT_BADGE_CLASS;
+    if (this.content.title) el.title = this.content.title;
+
+    if (this.content.icon) {
+      const icon = document.createElement('span');
+      icon.className = 'ck-code-badge__icon inline-flex shrink-0';
+      // Config, not document content — but sanitised anyway, since it is the
+      // only markup in this file that does not originate here.
+      icon.innerHTML = DOMPurify.sanitize(this.content.icon, {
+        USE_PROFILES: { svg: true, svgFilters: true },
+      });
+      el.append(icon);
+    }
+
+    el.append(document.createTextNode(this.content.label));
+    return el;
+  }
+
+  /** The pill is decorative; let the editor handle every event over it. */
+  override ignoreEvent(): boolean {
+    return false;
+  }
+}
+
+/** `MatchDecorator` requires a global pattern and mutates `lastIndex`. */
+function toGlobal(pattern: RegExp): RegExp {
+  const flags = pattern.flags.includes('g')
+    ? pattern.flags
+    : `${pattern.flags}g`;
+  return new RegExp(pattern.source, flags);
+}
+
+/**
+ * Draw matched references as inline pills, the way a mention or a chip renders
+ * inside prose.
+ *
+ * The document keeps the original text: the decoration only replaces what is
+ * *drawn*, so reading the value, copying and pasting all still yield the raw
+ * reference. The matched range is also registered as atomic, so the caret
+ * treats a pill as a single unit and backspace removes the whole reference
+ * rather than one character of it.
+ */
+export function badgeExtension(rule: CkCodeEditorBadgeRule): Extension {
+  const matcher = new MatchDecorator({
+    regexp: toGlobal(rule.pattern),
+    decoration: (match) => {
+      const content = rule.render(match as RegExpExecArray);
+      return content
+        ? Decoration.replace({ widget: new BadgeWidget(content) })
+        : null;
+    },
+  });
+
+  return ViewPlugin.fromClass(
+    class {
+      badges: DecorationSet;
+
+      constructor(view: EditorView) {
+        this.badges = matcher.createDeco(view);
+      }
+
+      update(update: ViewUpdate): void {
+        this.badges = matcher.updateDeco(update, this.badges);
+      }
+    },
+    {
+      decorations: (plugin) => plugin.badges,
+      provide: (plugin) =>
+        EditorView.atomicRanges.of(
+          (view) => view.plugin(plugin)?.badges ?? Decoration.none,
+        ),
+    },
+  );
+}
+
+/** Exported for tests: the ranges a rule would decorate in a plain string. */
+export function matchBadgeRanges(
+  rule: CkCodeEditorBadgeRule,
+  text: string,
+): Range<Decoration>[] {
+  const pattern = toGlobal(rule.pattern);
+  const ranges: Range<Decoration>[] = [];
+  let match: RegExpExecArray | null;
+  while ((match = pattern.exec(text)) !== null) {
+    const content = rule.render(match);
+    if (content) {
+      ranges.push(
+        Decoration.replace({ widget: new BadgeWidget(content) }).range(
+          match.index,
+          match.index + match[0].length,
+        ),
+      );
+    }
+    // A zero-length match would spin forever otherwise.
+    if (match[0] === '') pattern.lastIndex += 1;
+  }
+  return ranges;
+}

package/src/components/base/CkCodeEditor/createCodeMirror.ts

@@ -22,6 +22,7 @@ import {
   placeholder as placeholderExt,
 } from '@codemirror/view';
 import { ckCodeMirrorTheme } from '../../../helpers/codemirror/theme';
+import { badgeExtension, type CkCodeEditorBadgeRule } from './badgeDecoration';
 import '../../../helpers/codemirror/code-palette.css';
 
 export interface CreateCodeMirrorOptions {
@@ -34,10 +35,16 @@ export interface CreateCodeMirrorOptions {
   readonly: boolean;
   showLineNumbers: boolean;
   lineWrapping: boolean;
+  /** Draws matched references as inline pills; see `badgeDecoration.ts`. */
+  badge?: CkCodeEditorBadgeRule;
   /** Called synchronously whenever the document changes. */
   onChange: (value: string) => void;
+  /**
+   * Called when the editing area takes focus. There is deliberately no `onBlur`
+   * counterpart: losing focus to the header's copy button is not leaving the
+   * editor, and only the component around this view can tell the difference.
+   */
   onFocus: () => void;
-  onBlur: () => void;
 }
 
 /** Imperative surface `CkCodeEditor` drives; keeps CodeMirror out of the SFC. */
@@ -50,6 +57,7 @@ export interface CodeMirrorHandle {
   setReadonly: (readonly: boolean) => void;
   setShowLineNumbers: (show: boolean) => void;
   setLineWrapping: (wrap: boolean) => void;
+  setBadge: (rule: CkCodeEditorBadgeRule | undefined) => void;
   focus: () => void;
   destroy: () => void;
 }
@@ -85,6 +93,22 @@ export async function resolveLanguage(
   }
 }
 
+/**
+ * Pick the line ending a document already uses.
+ *
+ * CodeMirror splits on `\n`, `\r\n` and `\r` alike, but `doc.toString()` always
+ * joins with `\n`. Left alone, opening a file with Windows line endings and
+ * typing one character would silently rewrite every line ending in it. Telling
+ * the editor which separator this document uses keeps it intact, both when
+ * reading the value back and when the user presses Enter.
+ */
+export function detectLineSeparator(doc: string): string {
+  const crlf = (doc.match(/\r\n/g) ?? []).length;
+  if (crlf === 0) return '\n';
+  const bareLf = (doc.match(/(?<!\r)\n/g) ?? []).length;
+  return crlf >= bareLf ? '\r\n' : '\n';
+}
+
 // `readOnly` rejects edits while keeping the text selectable; `editable`
 // additionally drops `contenteditable`, which hides the caret and keeps the
 // editor out of the tab order.
@@ -92,6 +116,11 @@ function readonlyState(readonly: boolean): Extension {
   return [EditorState.readOnly.of(readonly), EditorView.editable.of(!readonly)];
 }
 
+/** The document as text, with the line endings it came in with. */
+function readDoc(state: EditorState): string {
+  return state.doc.sliceString(0, state.doc.length, state.lineBreak);
+}
+
 function baseExtensions(options: CreateCodeMirrorOptions): Extension[] {
   return [
     // Deliberately not CodeMirror's `basicSetup`: it also brings autocomplete,
@@ -112,11 +141,8 @@ function baseExtensions(options: CreateCodeMirrorOptions): Extension[] {
       ...(options.ariaLabel ? { 'aria-label': options.ariaLabel } : {}),
     }),
     EditorView.updateListener.of((update) => {
-      if (update.docChanged) options.onChange(update.state.doc.toString());
-      if (update.focusChanged) {
-        if (update.view.hasFocus) options.onFocus();
-        else options.onBlur();
-      }
+      if (update.docChanged) options.onChange(readDoc(update.state));
+      if (update.focusChanged && update.view.hasFocus) options.onFocus();
     }),
     ...(options.placeholder ? [placeholderExt(options.placeholder)] : []),
   ];
@@ -135,8 +161,12 @@ export async function createCodeMirror(
   const readonlySlot = new Compartment();
   const lineNumbersSlot = new Compartment();
   const wrappingSlot = new Compartment();
+  const badgeSlot = new Compartment();
+  const lineSeparatorSlot = new Compartment();
 
   const support = await resolveLanguage(options.language);
+  // Guards against out-of-order grammar loads; see `setLanguage` below.
+  let languageRequestId = 0;
 
   const view = new EditorView({
     parent: options.parent,
@@ -148,6 +178,10 @@ export async function createCodeMirror(
         readonlySlot.of(readonlyState(options.readonly)),
         lineNumbersSlot.of(options.showLineNumbers ? lineNumbers() : []),
         wrappingSlot.of(options.lineWrapping ? EditorView.lineWrapping : []),
+        badgeSlot.of(options.badge ? badgeExtension(options.badge) : []),
+        lineSeparatorSlot.of(
+          EditorState.lineSeparator.of(detectLineSeparator(options.doc)),
+        ),
       ],
     }),
   });
@@ -158,9 +192,14 @@ export async function createCodeMirror(
 
   return {
     view,
-    getCode: () => view.state.doc.toString(),
+    getCode: () => readDoc(view.state),
     setCode: (value) => {
-      if (value === view.state.doc.toString()) return;
+      if (value === readDoc(view.state)) return;
+      // New content may use different line endings from what is loaded.
+      const separator = detectLineSeparator(value);
+      if (separator !== view.state.lineBreak) {
+        reconfigure(lineSeparatorSlot, EditorState.lineSeparator.of(separator));
+      }
       // Replacing the whole document would otherwise send the cursor home
       // whenever a parent echoes the value back; clamp it to the new length.
       const cursor = Math.min(view.state.selection.main.head, value.length);
@@ -170,7 +209,11 @@ export async function createCodeMirror(
       });
     },
     setLanguage: async (language) => {
+      // Grammars load over the network and out of order, so a slow one must not
+      // land on top of a language chosen after it.
+      const request = ++languageRequestId;
       const next = await resolveLanguage(language);
+      if (request !== languageRequestId) return;
       reconfigure(languageSlot, next ? [next] : []);
     },
     setReadonly: (readonly) => {
@@ -182,6 +225,9 @@ export async function createCodeMirror(
     setLineWrapping: (wrap) => {
       reconfigure(wrappingSlot, wrap ? EditorView.lineWrapping : []);
     },
+    setBadge: (rule) => {
+      reconfigure(badgeSlot, rule ? badgeExtension(rule) : []);
+    },
     focus: () => view.focus(),
     destroy: () => view.destroy(),
   };

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

@@ -1,3 +1,11 @@
+import type { CkCodeEditorBadgeRule } from './badgeDecoration';
+
+// Re-exported so consumers get the badge types from the component's entry point.
+export type {
+  CkCodeEditorBadgeContent,
+  CkCodeEditorBadgeRule,
+} from './badgeDecoration';
+
 /**
  * Single-document code editor built on [CodeMirror 6](https://codemirror.net/).
  * Its surface is the one `UiCodeBlock` renders for fenced code inside
@@ -94,12 +102,42 @@ export interface CkCodeEditorProps {
    * `'24rem'`. Unset, the editor grows with its content.
    */
   maxHeight?: string;
+  /**
+   * Fade the code out at the top and bottom edges when there is more of it
+   * scrolled out of view, so a clipped document reads as continuing rather than
+   * stopping mid-line.
+   *
+   * Each edge appears only when that direction can actually scroll, so a
+   * document that fits shows no fade at all. Relevant mainly alongside
+   * `maxHeight`, which is what makes the editor scroll in the first place.
+   *
+   * @default true
+   */
+  scrollFade?: boolean;
   /**
    * Move focus into the editor once it has been created.
    *
    * @default false
    */
   autofocus?: boolean;
+  /**
+   * Draws matched text as an inline pill, the way a mention renders in prose.
+   * Give a pattern and a callback mapping each match to a label and optional
+   * icon; return `null` from the callback to leave an occurrence alone.
+   *
+   * The document keeps the original text, so `getCode()`, copying and pasting
+   * still yield the raw reference. A pill behaves as one unit for the caret,
+   * so backspace removes the whole reference.
+   *
+   * @example
+   * ```ts
+   * const badge = {
+   *   pattern: /@collection:([\w-]+)/g,
+   *   render: (m) => ({ label: m[1], icon: folderSvg }),
+   * };
+   * ```
+   */
+  badge?: CkCodeEditorBadgeRule;
   /**
    * Clipboard writer for the copy button. Injected for tests and for hosts that
    * proxy clipboard access; defaults to `navigator.clipboard.writeText`.

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

@@ -470,3 +470,43 @@ describe('CkMarkdownRenderer', () => {
     });
   });
 });
+
+describe('breaks', () => {
+  it('collapses a single newline into one line by default', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: 'line one\nline two' },
+    });
+
+    expect(container.querySelectorAll('p')).toHaveLength(1);
+    expect(container.querySelector('br')).toBeNull();
+  });
+
+  it('keeps a single newline as a line break when `breaks` is set', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: 'line one\nline two', breaks: true },
+    });
+
+    expect(container.querySelectorAll('p')).toHaveLength(1);
+    expect(container.querySelectorAll('br')).toHaveLength(1);
+    expect(container.querySelector('p')?.textContent).toContain('line one');
+    expect(container.querySelector('p')?.textContent).toContain('line two');
+  });
+
+  it('still starts a new paragraph on a blank line', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: 'one\n\ntwo', breaks: true },
+    });
+
+    expect(container.querySelectorAll('p')).toHaveLength(2);
+  });
+
+  it('leaves newlines inside fenced code alone', () => {
+    const { container } = render(CkMarkdownRenderer, {
+      props: { content: '```\nfirst\nsecond\n```', breaks: true },
+    });
+
+    const code = container.querySelector('pre code');
+    expect(code?.textContent).toBe('first\nsecond\n');
+    expect(code?.querySelector('br')).toBeNull();
+  });
+});