@aleph-alpha/chat-kit 6.2.0 → 6.4.0

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 mirrors `UiBadge`'s
+   * `outline` variant at `small` size.
+   */
+  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

@@ -0,0 +1,197 @@
+import {
+  defaultKeymap,
+  history,
+  historyKeymap,
+  indentWithTab,
+} from '@codemirror/commands';
+import {
+  bracketMatching,
+  indentOnInput,
+  indentUnit,
+  type LanguageSupport,
+} from '@codemirror/language';
+import { languages } from '@codemirror/language-data';
+import { Compartment, EditorState, type Extension } from '@codemirror/state';
+import {
+  EditorView,
+  drawSelection,
+  highlightActiveLine,
+  highlightSpecialChars,
+  keymap,
+  lineNumbers,
+  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 {
+  /** Element the view is mounted into. */
+  parent: HTMLElement;
+  doc: string;
+  language: string;
+  placeholder?: string;
+  ariaLabel?: string;
+  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;
+  onFocus: () => void;
+  onBlur: () => void;
+}
+
+/** Imperative surface `CkCodeEditor` drives; keeps CodeMirror out of the SFC. */
+export interface CodeMirrorHandle {
+  view: EditorView;
+  getCode: () => string;
+  /** Replace the whole document, keeping the cursor where it still fits. */
+  setCode: (value: string) => void;
+  setLanguage: (language: string) => Promise<void>;
+  setReadonly: (readonly: boolean) => void;
+  setShowLineNumbers: (show: boolean) => void;
+  setLineWrapping: (wrap: boolean) => void;
+  setBadge: (rule: CkCodeEditorBadgeRule | undefined) => void;
+  focus: () => void;
+  destroy: () => void;
+}
+
+/** Plain text, and the value `UiCodeBlock` also treats as "no language". */
+const PLAIN_ALIASES = new Set(['text', 'txt', 'plain', 'plaintext', '']);
+
+/**
+ * Resolve a language id the way a reader would expect: by name, by alias, or by
+ * file extension, all case-insensitively. Returns `null` for plain text and for
+ * anything CodeMirror does not know, so an unrecognised id degrades to
+ * unhighlighted code instead of throwing.
+ */
+export async function resolveLanguage(
+  language: string,
+): Promise<LanguageSupport | null> {
+  const id = language.trim().toLowerCase();
+  if (PLAIN_ALIASES.has(id)) return null;
+
+  const description = languages.find(
+    (candidate) =>
+      candidate.name.toLowerCase() === id ||
+      candidate.alias.includes(id) ||
+      candidate.extensions.includes(id),
+  );
+  if (!description) return null;
+
+  try {
+    return await description.load();
+  } catch {
+    // A grammar that fails to load must not take the editor down with it.
+    return null;
+  }
+}
+
+// `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.
+function readonlyState(readonly: boolean): Extension {
+  return [EditorState.readOnly.of(readonly), EditorView.editable.of(!readonly)];
+}
+
+function baseExtensions(options: CreateCodeMirrorOptions): Extension[] {
+  return [
+    // Deliberately not CodeMirror's `basicSetup`: it also brings autocomplete,
+    // search, folding and bracket closing, none of which suit a snippet field,
+    // and its fold gutter would sit next to the line numbers.
+    history(),
+    drawSelection(),
+    highlightSpecialChars(),
+    highlightActiveLine(),
+    bracketMatching(),
+    indentOnInput(),
+    indentUnit.of('  '),
+    keymap.of([...defaultKeymap, ...historyKeymap, indentWithTab]),
+    ckCodeMirrorTheme,
+    EditorView.contentAttributes.of({
+      role: 'textbox',
+      'aria-multiline': 'true',
+      ...(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();
+      }
+    }),
+    ...(options.placeholder ? [placeholderExt(options.placeholder)] : []),
+  ];
+}
+
+/**
+ * Build a CodeMirror view themed like `UiCodeBlock`. Loaded lazily by
+ * `CkCodeEditor` so CodeMirror stays out of the package's main chunk.
+ */
+export async function createCodeMirror(
+  options: CreateCodeMirrorOptions,
+): Promise<CodeMirrorHandle> {
+  // One set per view: a compartment is the key a reconfigure targets, so
+  // sharing them across editors would make the instances interfere.
+  const languageSlot = new Compartment();
+  const readonlySlot = new Compartment();
+  const lineNumbersSlot = new Compartment();
+  const wrappingSlot = new Compartment();
+  const badgeSlot = new Compartment();
+
+  const support = await resolveLanguage(options.language);
+
+  const view = new EditorView({
+    parent: options.parent,
+    state: EditorState.create({
+      doc: options.doc,
+      extensions: [
+        ...baseExtensions(options),
+        languageSlot.of(support ? [support] : []),
+        readonlySlot.of(readonlyState(options.readonly)),
+        lineNumbersSlot.of(options.showLineNumbers ? lineNumbers() : []),
+        wrappingSlot.of(options.lineWrapping ? EditorView.lineWrapping : []),
+        badgeSlot.of(options.badge ? badgeExtension(options.badge) : []),
+      ],
+    }),
+  });
+
+  function reconfigure(slot: Compartment, extension: Extension): void {
+    view.dispatch({ effects: slot.reconfigure(extension) });
+  }
+
+  return {
+    view,
+    getCode: () => view.state.doc.toString(),
+    setCode: (value) => {
+      if (value === view.state.doc.toString()) return;
+      // 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);
+      view.dispatch({
+        changes: { from: 0, to: view.state.doc.length, insert: value },
+        selection: { anchor: cursor },
+      });
+    },
+    setLanguage: async (language) => {
+      const next = await resolveLanguage(language);
+      reconfigure(languageSlot, next ? [next] : []);
+    },
+    setReadonly: (readonly) => {
+      reconfigure(readonlySlot, readonlyState(readonly));
+    },
+    setShowLineNumbers: (show) => {
+      reconfigure(lineNumbersSlot, show ? lineNumbers() : []);
+    },
+    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/index.ts

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

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

@@ -0,0 +1,154 @@
+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
+ * {@link CkMarkdownRenderer}: the same bordered, rounded panel, the same muted
+ * header carrying the language and a copy button, the same monospace metrics,
+ * and syntax colours approximating Shiki's `github-light` / `github-dark`. A
+ * snippet therefore looks the same whether it is being read in a reply or
+ * edited here.
+ *
+ * Use it wherever a whole document *is* code — a snippet field, a config or
+ * template editor, a "create skill" form. For prose that merely contains code,
+ * use {@link CkMilkdownEditor}, whose fenced blocks share this same theme.
+ *
+ * Grammars load on demand from CodeMirror's language data, so only the
+ * languages actually opened are fetched, and the editor itself loads lazily on
+ * mount so importing the component costs nothing until one is shown.
+ *
+ * @category Form Inputs
+ * @useCases edit a code snippet, config or template editor, code field in a form, review and tweak generated code
+ * @keywords code, editor, codemirror, syntax highlighting, snippet, v-model, monospace, language
+ * @related CkMilkdownEditor, CkMarkdownRenderer
+ */
+export interface CkCodeEditorProps {
+  /**
+   * The code. Supports `v-model`.
+   *
+   * Unlike {@link CkMilkdownEditor}, updates are emitted synchronously on every
+   * change, with no debounce and no reformatting of what you pass in.
+   *
+   * @default ''
+   */
+  modelValue?: string;
+  /**
+   * Language id used for both syntax highlighting and the header label, for
+   * example `typescript`, `python`, `json` or `bash`. Matching is on the names,
+   * aliases and extensions CodeMirror knows; an unknown value still renders as
+   * plain text rather than failing.
+   *
+   * @default 'text'
+   */
+  language?: string;
+  /**
+   * Filename shown in the header instead of the language, mirroring the prop of
+   * the same name on `UiCodeBlock`.
+   */
+  filename?: string;
+  /** Text shown while the document is empty. */
+  placeholder?: string;
+  /**
+   * Render the code without allowing edits. The caret and the active-line
+   * highlight are hidden, but the text stays selectable and copyable.
+   *
+   * @default false
+   */
+  readonly?: boolean;
+  /**
+   * Like `readonly`, but also mutes the editor and marks it `aria-disabled`.
+   *
+   * @default false
+   */
+  disabled?: boolean;
+  /** Accessible name for the editable region. */
+  ariaLabel?: string;
+  /**
+   * Show the header bar with the language or filename and the copy button. Set
+   * it to `false` for a bare editing surface.
+   *
+   * @default true
+   */
+  showHeader?: boolean;
+  /**
+   * Show the copy button in the header.
+   *
+   * @default true
+   */
+  showCopyButton?: boolean;
+  /**
+   * Show the line-number gutter. On by default, which is what a dedicated code
+   * editor is expected to do; `UiCodeBlock` and `CkMilkdownEditor` default to
+   * `false` because their code is being read rather than written.
+   *
+   * @default true
+   */
+  showLineNumbers?: boolean;
+  /**
+   * Wrap long lines instead of scrolling horizontally. `UiCodeBlock` scrolls,
+   * so the default keeps the two consistent.
+   *
+   * @default false
+   */
+  lineWrapping?: boolean;
+  /**
+   * Maximum height of the scrollable code area, as any CSS length, for example
+   * `'24rem'`. Unset, the editor grows with its content.
+   */
+  maxHeight?: string;
+  /**
+   * 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`.
+   */
+  writeToClipboard?: (text: string) => Promise<void>;
+}
+
+/** Events emitted by {@link CkCodeEditor}. */
+export interface CkCodeEditorEmits {
+  /** Emitted on every document change, with the full code. */
+  'update:modelValue': [value: string];
+  /** Emitted when the editing area gains focus. */
+  focus: [];
+  /** Emitted when focus leaves the editor entirely, header included. */
+  blur: [];
+  /** Emitted after the copy button runs, whether or not the write succeeded. */
+  copy: [payload: { success: boolean }];
+}
+
+/** Methods exposed by {@link CkCodeEditor} through a template ref. */
+export interface CkCodeEditorExposed {
+  /** Focus the editing area. No-op until the editor has been created. */
+  focus: () => void;
+  /** Read the current document synchronously. */
+  getCode: () => string;
+}

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

@@ -142,6 +142,19 @@ describe('CkMilkdownEditor', () => {
     ).toBe('false');
   });
 
+  it('toggles the line-number gutter with `showLineNumbers`', async () => {
+    const { container, rerender } = await renderEditor({
+      modelValue: 'Hello',
+      showLineNumbers: true,
+    });
+
+    const root = () => container.querySelector('.ck-milkdown');
+    expect(root()?.className).toContain('ck-milkdown--line-numbers');
+
+    await rerender({ modelValue: 'Hello', showLineNumbers: false });
+    expect(root()?.className).not.toContain('ck-milkdown--line-numbers');
+  });
+
   it('exposes the editable region as a labelled textbox', async () => {
     const { container } = await renderEditor({
       modelValue: 'Hello',

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

@@ -25,6 +25,7 @@ const meta: Meta<typeof CkMilkdownEditor> = {
     readonly: { control: 'boolean' },
     disabled: { control: 'boolean' },
     autofocus: { control: 'boolean' },
+    showLineNumbers: { control: 'boolean' },
   },
 };
 
@@ -109,6 +110,21 @@ const markdown = '# Read me\\n\\nThis document **cannot** be edited.';
   <CkMilkdownEditor :model-value="markdown" readonly aria-label="Read-only document" />
 </template>`;
 
+const withLineNumbersTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
+
+const markdown = ref('# Notes\\n\\nA fenced block with a gutter.');
+</script>
+
+<template>
+  <CkMilkdownEditor
+    v-model="markdown"
+    show-line-numbers
+    aria-label="Editor with line numbers"
+  />
+</template>`;
+
 const disabledTemplateSource = `<script setup lang="ts">
 import { CkMilkdownEditor } from '@aleph-alpha/chat-kit';
 
@@ -210,6 +226,24 @@ export const Readonly: Story = {
   parameters: { docs: { source: { code: readonlyTemplateSource } } },
 };
 
+/**
+ * `showLineNumbers` reveals the line-number gutter on fenced code blocks. It
+ * matches the prop of the same name on `UiCodeBlock`, so the same flag can keep
+ * the editor and the rendered message consistent.
+ */
+export const WithLineNumbers: Story = {
+  render: (args) => ({
+    components: { CkMilkdownEditor },
+    setup() {
+      const markdown = ref(args.modelValue ?? '');
+      return { args, markdown };
+    },
+    template: `<CkMilkdownEditor v-bind="args" v-model="markdown" aria-label="Editor with line numbers" />`,
+  }),
+  args: { modelValue: richContent, showLineNumbers: true },
+  parameters: { docs: { source: { code: withLineNumbersTemplateSource } } },
+};
+
 /**
  * `disabled` also mutes the content and blocks pointer interaction, and sets
  * `aria-disabled` on the root.

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

@@ -22,6 +22,7 @@ const props = withDefaults(defineProps<CkMilkdownEditorProps>(), {
   ariaLabel: undefined,
   classes: () => ({}),
   autofocus: false,
+  showLineNumbers: false,
 });
 
 const emit = defineEmits<CkMilkdownEditorEmits>();
@@ -132,9 +133,10 @@ defineExpose({ focus, getMarkdown });
   <div
     ref="rootRef"
     :class="[
-      'ck-milkdown min-w-0 break-words',
+      'ck-milkdown ck-code-surface min-w-0 break-words',
       isReady && 'ck-milkdown--ready',
       disabled && 'ck-milkdown--disabled',
+      showLineNumbers && 'ck-milkdown--line-numbers',
     ]"
     :aria-disabled="disabled || undefined"
     @focusin="onFocusIn"

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

@@ -6,7 +6,7 @@ import {
   type ChatKitLabels,
 } from '../../../handlers/useChatKitLabels';
 import type { CkMarkdownElementClasses } from '../CkMarkdownRenderer';
-import { ckCodeMirrorTheme } from './codeMirrorTheme';
+import { ckCodeMirrorTheme } from '../../../helpers/codemirror/theme';
 import { crepeIcons } from './crepeIcons';
 import { applyMarkdownClasses } from './markdownClassAttrs';
 
@@ -24,6 +24,7 @@ import '@milkdown/crepe/theme/common/list-item.css';
 import '@milkdown/crepe/theme/common/link-tooltip.css';
 import '@milkdown/crepe/theme/common/toolbar.css';
 import '@milkdown/crepe/theme/common/code-mirror.css';
+import '../../../helpers/codemirror/code-palette.css';
 import './milkdown-theme.css';
 
 export interface CreateCrepeEditorOptions {