@aleph-alpha/chat-kit 6.3.0 → 6.4.0

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

@@ -4,6 +4,32 @@ import type { Meta, StoryObj } from '@storybook/vue3-vite';
 import CkCodeEditor from './CkCodeEditor.vue';
 import CkMarkdownRenderer from '../CkMarkdownRenderer/CkMarkdownRenderer.vue';
 
+const folderIcon =
+  '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" ' +
+  'stroke="currentColor" stroke-width="2" stroke-linecap="round" ' +
+  'stroke-linejoin="round" width="12" height="12" aria-hidden="true">' +
+  '<path d="M20 20a2 2 0 0 0 2-2V8a2 2 0 0 0-2-2h-7.9a2 2 0 0 1-1.69-.9L9.6 3.9A2 2 0 0 0 7.93 3H4a2 2 0 0 0-2 2v13a2 2 0 0 0 2 2Z"/></svg>';
+
+/** Matches `@collection:<id>` and draws each one as a folder pill. */
+const collectionBadge = {
+  pattern: /@collection:([\w-]+)/g,
+  render: (match: RegExpExecArray) => ({
+    label: (match[1] ?? '').replace(/-/g, ' '),
+    icon: folderIcon,
+    title: match[0],
+  }),
+};
+
+/** Matches `{{ name }}`, showing that the trigger is whatever you pattern for. */
+const handlebarsBadge = {
+  pattern: /\{\{\s*([\w-]+)\s*\}\}/g,
+  render: (match: RegExpExecArray) => ({
+    label: match[1] ?? '',
+    icon: folderIcon,
+    title: match[0],
+  }),
+};
+
 const meta: Meta<typeof CkCodeEditor> = {
   title: 'Base/CkCodeEditor',
   component: CkCodeEditor,
@@ -31,6 +57,20 @@ const meta: Meta<typeof CkCodeEditor> = {
     showLineNumbers: { control: 'boolean' },
     lineWrapping: { control: 'boolean' },
     autofocus: { control: 'boolean' },
+    // A regex plus a callback cannot be typed into a control, so the rule is
+    // offered as named presets instead. Without this, badges could only be seen
+    // on the one story that hard-codes a rule.
+    badge: {
+      options: ['none', 'collections', 'handlebars'],
+      mapping: {
+        none: undefined,
+        collections: collectionBadge,
+        handlebars: handlebarsBadge,
+      },
+      control: { type: 'radio' },
+      description:
+        'Pattern plus a render callback turning matched text into inline pills. Pick a preset to try it on any story.',
+    },
     writeToClipboard: {
       control: false,
       description:
@@ -69,6 +109,14 @@ const pythonSample = [
   '        return f"{opener}, {self.name}!"',
 ].join('\n');
 
+const badgeSample = [
+  'You improve and draft work writing: emails, project summaries and status',
+  'updates, tightening structure and matching register to the audience.',
+  '',
+  'For analyses, use @collection:collection-name-3 and @collection:collection-name-4',
+  'and distinguish an opinion from a fact.',
+].join('\n');
+
 const defaultTemplateSource = `<script setup lang="ts">
 import { ref } from 'vue';
 import { CkCodeEditor } from '@aleph-alpha/chat-kit';
@@ -149,6 +197,29 @@ const code = ref(longFile);
   <CkCodeEditor v-model="code" language="typescript" max-height="16rem" line-wrapping />
 </template>`;
 
+const withBadgesTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkCodeEditor } from '@aleph-alpha/chat-kit';
+
+const prompt = ref('For analyses, use @collection:sales and @collection:support.');
+
+// The document keeps the raw text; only the drawing is replaced.
+const badge = {
+  pattern: /@collection:([\\w-]+)/g,
+  render: (m) => ({ label: m[1], icon: folderIcon, title: m[0] }),
+};
+</script>
+
+<template>
+  <CkCodeEditor
+    v-model="prompt"
+    language="markdown"
+    :badge="badge"
+    :line-wrapping="true"
+    aria-label="Prompt"
+  />
+</template>`;
+
 const matchesRendererTemplateSource = `<script setup lang="ts">
 import { ref } from 'vue';
 import { CkCodeEditor, CkMarkdownRenderer } from '@aleph-alpha/chat-kit';
@@ -279,6 +350,29 @@ export const ScrollingAndWrapping: Story = {
   parameters: { docs: { source: { code: scrollingTemplateSource } } },
 };
 
+/**
+ * `badge` draws matched references as inline pills, the way a mention renders in
+ * prose. The document still holds the raw `@collection:…` text, so `getCode()`
+ * and copy give the real reference; a pill deletes as one unit.
+ */
+export const WithBadges: Story = {
+  render: (args) => ({
+    components: { CkCodeEditor },
+    setup() {
+      const code = ref(args.modelValue ?? '');
+      return { args, code };
+    },
+    template: `<CkCodeEditor v-bind="args" v-model="code" aria-label="Prompt" />`,
+  }),
+  args: {
+    modelValue: badgeSample,
+    language: 'markdown',
+    badge: collectionBadge,
+    lineWrapping: true,
+  },
+  parameters: { docs: { source: { code: withBadgesTemplateSource } } },
+};
+
 /**
  * Parity check: the editor on the left, the same snippet rendered through
  * `CkMarkdownRenderer` and `UiCodeBlock` on the right. Border, radius, header,

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

@@ -28,6 +28,7 @@ const props = withDefaults(defineProps<CkCodeEditorProps>(), {
   lineWrapping: false,
   maxHeight: undefined,
   autofocus: false,
+  badge: undefined,
   writeToClipboard: undefined,
 });
 
@@ -84,6 +85,7 @@ onMounted(async () => {
     readonly: isLocked.value,
     showLineNumbers: props.showLineNumbers,
     lineWrapping: props.lineWrapping,
+    badge: props.badge,
     onChange: handleChange,
     onFocus: () => emit('focus'),
     onBlur: () => emit('blur'),
@@ -128,6 +130,10 @@ watch(
   () => props.lineWrapping,
   (wrap) => editor?.setLineWrapping(wrap),
 );
+watch(
+  () => props.badge,
+  (rule) => editor?.setBadge(rule),
+);
 
 onBeforeUnmount(() => {
   destroyed = true;
@@ -188,9 +194,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

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

@@ -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,6 +35,8 @@ 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;
   onFocus: () => void;
@@ -50,6 +53,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;
 }
@@ -135,6 +139,7 @@ export async function createCodeMirror(
   const readonlySlot = new Compartment();
   const lineNumbersSlot = new Compartment();
   const wrappingSlot = new Compartment();
+  const badgeSlot = new Compartment();
 
   const support = await resolveLanguage(options.language);
 
@@ -148,6 +153,7 @@ 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) : []),
       ],
     }),
   });
@@ -182,6 +188,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
@@ -100,6 +108,24 @@ export interface CkCodeEditorProps {
    * @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`.