@aleph-alpha/chat-kit 6.2.0 → 6.4.0

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

@@ -0,0 +1,405 @@
+import { ref } from 'vue';
+import { UiCodeBlock } from '@aleph-alpha/ui-library';
+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,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: { control: 'text', description: 'The code (`v-model`).' },
+    language: {
+      control: 'text',
+      description:
+        'Language id for highlighting and the header label, matched on names, aliases and extensions.',
+    },
+    filename: {
+      control: 'text',
+      description: 'Shown in the header instead of the language.',
+    },
+    maxHeight: {
+      control: 'text',
+      description: 'CSS length capping the scrollable area, e.g. `24rem`.',
+    },
+    placeholder: { control: 'text' },
+    readonly: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    showHeader: { control: 'boolean' },
+    showCopyButton: { control: 'boolean' },
+    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:
+        'Clipboard writer for tests or hosts that proxy clipboard access.',
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const typescriptSample = [
+  'export interface Greeting {',
+  '  name: string;',
+  '  formal?: boolean;',
+  '}',
+  '',
+  '// Returns a greeting suited to the audience.',
+  'export function greet({ name, formal = false }: Greeting): string {',
+  '  const opener = formal ? "Good day" : "Hello";',
+  '  return `${opener}, ${name}!`;',
+  '}',
+].join('\n');
+
+const pythonSample = [
+  'from dataclasses import dataclass',
+  '',
+  '',
+  '@dataclass',
+  'class Greeting:',
+  '    name: str',
+  '    formal: bool = False',
+  '',
+  '    def render(self) -> str:',
+  '        opener = "Good day" if self.formal else "Hello"',
+  '        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';
+
+const code = ref('export const answer = 42;');
+</script>
+
+<template>
+  <CkCodeEditor v-model="code" language="typescript" aria-label="Code" />
+</template>`;
+
+const withFilenameTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkCodeEditor } from '@aleph-alpha/chat-kit';
+
+const code = ref('print("hello")');
+</script>
+
+<template>
+  <CkCodeEditor
+    v-model="code"
+    language="python"
+    filename="main.py"
+    aria-label="main.py"
+  />
+</template>`;
+
+const plainTextTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkCodeEditor } from '@aleph-alpha/chat-kit';
+
+const notes = ref('');
+</script>
+
+<template>
+  <CkCodeEditor
+    v-model="notes"
+    placeholder="Paste your snippet…"
+    :show-line-numbers="false"
+    aria-label="Snippet"
+  />
+</template>`;
+
+const readonlyTemplateSource = `<script setup lang="ts">
+import { CkCodeEditor } from '@aleph-alpha/chat-kit';
+
+const code = 'export const answer = 42;';
+</script>
+
+<template>
+  <CkCodeEditor :model-value="code" language="typescript" readonly aria-label="Code" />
+</template>`;
+
+const bareTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkCodeEditor } from '@aleph-alpha/chat-kit';
+
+const code = ref('SELECT * FROM users;');
+</script>
+
+<template>
+  <CkCodeEditor
+    v-model="code"
+    language="sql"
+    :show-header="false"
+    aria-label="Query"
+  />
+</template>`;
+
+const scrollingTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkCodeEditor } from '@aleph-alpha/chat-kit';
+
+const code = ref(longFile);
+</script>
+
+<template>
+  <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';
+import { UiCodeBlock } from '@aleph-alpha/ui-library';
+
+const code = ref('export const answer = 42;');
+const asMarkdown = computed(() => '\\\`\\\`\\\`typescript\\n' + code.value + '\\n\\\`\\\`\\\`');
+</script>
+
+<template>
+  <div class="text-content-on-surface-primary grid gap-6 text-base leading-7 md:grid-cols-2">
+    <CkCodeEditor v-model="code" language="typescript" aria-label="Editor" />
+    <CkMarkdownRenderer :content="asMarkdown">
+      <template #code-block="{ code: c, language }">
+        <UiCodeBlock :code="c" :language="language || 'text'" />
+      </template>
+    </CkMarkdownRenderer>
+  </div>
+</template>`;
+
+/**
+ * A TypeScript snippet with the header, copy button and line numbers. Type in
+ * it — changes are emitted synchronously, with no debounce.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { CkCodeEditor },
+    setup() {
+      const code = ref(args.modelValue ?? '');
+      return { args, code };
+    },
+    template: `<CkCodeEditor v-bind="args" v-model="code" aria-label="Code" />`,
+  }),
+  args: { modelValue: typescriptSample, language: 'typescript' },
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+};
+
+/**
+ * `filename` replaces the language in the header, matching the prop of the same
+ * name on `UiCodeBlock`. The grammar still comes from `language`.
+ */
+export const WithFilename: Story = {
+  render: (args) => ({
+    components: { CkCodeEditor },
+    setup() {
+      const code = ref(args.modelValue ?? '');
+      return { args, code };
+    },
+    template: `<CkCodeEditor v-bind="args" v-model="code" aria-label="main.py" />`,
+  }),
+  args: { modelValue: pythonSample, language: 'python', filename: 'main.py' },
+  parameters: { docs: { source: { code: withFilenameTemplateSource } } },
+};
+
+/**
+ * With no language the header label is blank and nothing is highlighted, the
+ * same treatment `UiCodeBlock` gives plain text. Shown here with a placeholder
+ * and no gutter, as a lightweight snippet field.
+ */
+export const PlainText: Story = {
+  render: (args) => ({
+    components: { CkCodeEditor },
+    setup() {
+      const code = ref(args.modelValue ?? '');
+      return { args, code };
+    },
+    template: `<CkCodeEditor v-bind="args" v-model="code" aria-label="Snippet" />`,
+  }),
+  args: {
+    modelValue: '',
+    placeholder: 'Paste your snippet…',
+    showLineNumbers: false,
+  },
+  parameters: { docs: { source: { code: plainTextTemplateSource } } },
+};
+
+/**
+ * `readonly` keeps the code selectable and copyable but drops the caret and the
+ * active-line band. Use it while a request is in flight.
+ */
+export const Readonly: Story = {
+  args: {
+    modelValue: typescriptSample,
+    language: 'typescript',
+    readonly: true,
+  },
+  parameters: { docs: { source: { code: readonlyTemplateSource } } },
+};
+
+/**
+ * `showHeader: false` gives a bare editing surface, for forms that already
+ * label the field themselves.
+ */
+export const WithoutHeader: Story = {
+  args: {
+    modelValue: 'SELECT id, email\nFROM users\nWHERE active = true;',
+    language: 'sql',
+    showHeader: false,
+  },
+  parameters: { docs: { source: { code: bareTemplateSource } } },
+};
+
+/**
+ * `maxHeight` caps the scrollable area and `lineWrapping` folds long lines
+ * instead of scrolling sideways.
+ */
+export const ScrollingAndWrapping: Story = {
+  render: (args) => ({
+    components: { CkCodeEditor },
+    setup() {
+      const code = ref(args.modelValue ?? '');
+      return { args, code };
+    },
+    template: `<CkCodeEditor v-bind="args" v-model="code" aria-label="Long file" />`,
+  }),
+  args: {
+    modelValue: [
+      typescriptSample,
+      '',
+      '// A deliberately long line that has to wrap rather than scroll sideways, so you can see how lineWrapping behaves in a narrow column.',
+      '',
+      pythonSample,
+    ].join('\n'),
+    language: 'typescript',
+    maxHeight: '16rem',
+    lineWrapping: true,
+  },
+  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,
+ * font and syntax colours should read as one component in both themes.
+ */
+export const MatchesTheRenderer: Story = {
+  render: (args) => ({
+    components: { CkCodeEditor, CkMarkdownRenderer, UiCodeBlock },
+    setup() {
+      const code = ref(args.modelValue ?? '');
+      return { args, code };
+    },
+    template: `
+      <div class="text-content-on-surface-primary grid gap-6 text-base leading-7 md:grid-cols-2">
+        <CkCodeEditor v-bind="args" v-model="code" aria-label="Editor" />
+        <CkMarkdownRenderer :content="'\\\`\\\`\\\`typescript\\n' + code + '\\n\\\`\\\`\\\`'">
+          <template #code-block="{ code: c, language }">
+            <UiCodeBlock :code="c" :language="language || 'text'" />
+          </template>
+        </CkMarkdownRenderer>
+      </div>
+    `,
+  }),
+  args: {
+    modelValue: typescriptSample,
+    language: 'typescript',
+    showLineNumbers: false,
+  },
+  parameters: { docs: { source: { code: matchesRendererTemplateSource } } },
+};

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

@@ -0,0 +1,244 @@
+<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,
+  badge: undefined,
+  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,
+    badge: props.badge,
+    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),
+);
+watch(
+  () => props.badge,
+  (rule) => editor?.setBadge(rule),
+);
+
+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="bg-background-surface-muted-subtle flex h-9 items-center justify-between px-3"
+    >
+      <span class="text-content-on-surface-secondary label-12-regular">
+        {{ 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>