@aleph-alpha/chat-kit 6.1.1 → 6.3.0

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

@@ -0,0 +1,238 @@
+<script setup lang="ts">
+import {
+  computed,
+  onBeforeUnmount,
+  onMounted,
+  ref,
+  useTemplateRef,
+  watch,
+} from 'vue';
+import { UiButton, UiIcon } from '@aleph-alpha/ui-library';
+import { useChatKitLabels } from '../../../handlers/useChatKitLabels';
+import type { CodeMirrorHandle } from './createCodeMirror';
+import type { CkCodeEditorEmits, CkCodeEditorProps } from './types';
+
+defineOptions({ name: 'CkCodeEditor' });
+
+const props = withDefaults(defineProps<CkCodeEditorProps>(), {
+  modelValue: '',
+  language: 'text',
+  filename: undefined,
+  placeholder: undefined,
+  readonly: false,
+  disabled: false,
+  ariaLabel: undefined,
+  showHeader: true,
+  showCopyButton: true,
+  showLineNumbers: true,
+  lineWrapping: false,
+  maxHeight: undefined,
+  autofocus: false,
+  writeToClipboard: undefined,
+});
+
+const emit = defineEmits<CkCodeEditorEmits>();
+
+const labels = useChatKitLabels();
+const rootRef = useTemplateRef<HTMLDivElement>('rootRef');
+const hostRef = useTemplateRef<HTMLDivElement>('hostRef');
+const isLocked = computed(() => props.readonly || props.disabled);
+const isReady = ref(false);
+const isCopied = ref(false);
+
+// `UiCodeBlock` labels the block with the filename when there is one and hides
+// the label entirely for plain text; mirror that so the two headers match.
+const headerLabel = computed(() => {
+  const label = props.filename || props.language;
+  return label === 'text' ? '' : label;
+});
+
+const copyLabel = computed(() =>
+  isCopied.value
+    ? (labels.value.codeEditorCopied ?? 'Copied')
+    : (labels.value.codeEditorCopy ?? 'Copy code'),
+);
+
+let editor: CodeMirrorHandle | undefined;
+let destroyed = false;
+// Last value emitted or applied, so an echo from the parent is not re-applied.
+let lastKnownCode = props.modelValue;
+let copyTimer: ReturnType<typeof setTimeout> | undefined;
+
+function handleChange(value: string): void {
+  if (value === lastKnownCode) return;
+  lastKnownCode = value;
+  emit('update:modelValue', value);
+}
+
+onMounted(async () => {
+  const parent = hostRef.value;
+  if (!parent) return;
+
+  // Lazy: CodeMirror and its grammars load only once an editor is shown.
+  const { createCodeMirror } = await import('./createCodeMirror');
+  if (destroyed) return;
+
+  const initialCode = props.modelValue;
+  lastKnownCode = initialCode;
+  const handle = await createCodeMirror({
+    parent,
+    doc: initialCode,
+    language: props.language,
+    placeholder: props.placeholder,
+    ariaLabel: props.ariaLabel,
+    readonly: isLocked.value,
+    showLineNumbers: props.showLineNumbers,
+    lineWrapping: props.lineWrapping,
+    onChange: handleChange,
+    onFocus: () => emit('focus'),
+    onBlur: () => emit('blur'),
+  });
+
+  // Unmounted while the grammar was loading.
+  if (destroyed) {
+    handle.destroy();
+    return;
+  }
+
+  editor = handle;
+  // Props may have moved on while the grammar loaded; catch up.
+  if (props.modelValue !== initialCode) handle.setCode(props.modelValue);
+  isReady.value = true;
+  if (props.autofocus) handle.focus();
+});
+
+watch(
+  () => props.modelValue,
+  (next) => {
+    if (next === lastKnownCode) return;
+    lastKnownCode = next;
+    editor?.setCode(next);
+  },
+);
+
+watch(
+  () => props.language,
+  (next) => {
+    // Loading a grammar is async; nothing waits on it, and a failure already
+    // falls back to plain text inside `setLanguage`.
+    editor?.setLanguage(next).catch(() => undefined);
+  },
+);
+watch(isLocked, (locked) => editor?.setReadonly(locked));
+watch(
+  () => props.showLineNumbers,
+  (show) => editor?.setShowLineNumbers(show),
+);
+watch(
+  () => props.lineWrapping,
+  (wrap) => editor?.setLineWrapping(wrap),
+);
+
+onBeforeUnmount(() => {
+  destroyed = true;
+  clearTimeout(copyTimer);
+  editor?.destroy();
+  editor = undefined;
+});
+
+async function handleCopy(): Promise<void> {
+  const write =
+    props.writeToClipboard ??
+    ((text: string) => globalThis.navigator.clipboard.writeText(text));
+  try {
+    await write(getCode());
+    isCopied.value = true;
+    clearTimeout(copyTimer);
+    copyTimer = setTimeout(() => {
+      isCopied.value = false;
+    }, 2000);
+    emit('copy', { success: true });
+  } catch {
+    emit('copy', { success: false });
+  }
+}
+
+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.
+function onFocusOut(event: FocusEvent): void {
+  if (!isInsideRoot(event.relatedTarget)) emit('blur');
+}
+
+function focus(): void {
+  editor?.focus();
+}
+
+function getCode(): string {
+  return editor?.getCode() ?? props.modelValue;
+}
+
+defineExpose({ focus, getCode });
+</script>
+
+<template>
+  <div
+    ref="rootRef"
+    :class="[
+      'ck-code-editor ck-code-surface border-border-surface-default min-w-0 overflow-hidden rounded-lg border',
+      isReady && 'ck-code-editor--ready',
+      isLocked && 'ck-code-editor--readonly',
+      disabled && 'ck-code-editor--disabled',
+    ]"
+    :aria-disabled="disabled || undefined"
+    @focusout="onFocusOut"
+  >
+    <div
+      v-if="showHeader"
+      class="border-border-surface-default bg-background-surface-muted flex items-center justify-between border-b px-4 py-2"
+    >
+      <span class="text-content-on-surface-secondary font-mono text-sm">
+        {{ headerLabel }}
+      </span>
+      <UiButton
+        v-if="showCopyButton"
+        variant="ghost"
+        size="icon-sm"
+        :aria-label="copyLabel"
+        @click="handleCopy"
+      >
+        <UiIcon :name="isCopied ? 'check' : 'copy'" :size="14" />
+      </UiButton>
+    </div>
+
+    <div
+      ref="hostRef"
+      class="ck-code-editor__host"
+      :style="maxHeight ? { '--ck-code-max-height': maxHeight } : undefined"
+    />
+  </div>
+</template>
+
+<style scoped>
+/* 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) {
+  background: var(--ck-cm-bg);
+  color: var(--ck-cm-foreground);
+}
+
+.ck-code-editor__host :deep(.cm-scroller) {
+  max-height: var(--ck-code-max-height, none);
+}
+
+/* Nothing is being edited, so the active-line band would only be noise. */
+.ck-code-editor--readonly .ck-code-editor__host :deep(.cm-activeLine),
+.ck-code-editor--readonly .ck-code-editor__host :deep(.cm-activeLineGutter) {
+  background: transparent;
+}
+
+.ck-code-editor--disabled {
+  opacity: 0.6;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+</style>

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

@@ -0,0 +1,188 @@
+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 '../../../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;
+  /** 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;
+  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 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 : []),
+      ],
+    }),
+  });
+
+  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 : []);
+    },
+    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,128 @@
+/**
+ * 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;
+  /**
+   * 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 {