@elabs-ai/components-editor 4.0.0

package/src/lib/editor-completions.test.ts

@@ -0,0 +1,156 @@
+/**
+ * Unit tests for the engine-neutral completion-provider helpers (#283) —
+ * `triggerQueryStart` / `resolveReplaceRange` (the pure range math both the
+ * Monaco and Milkdown adapters share) + `collectCompletions` (the provider
+ * fan-out that degrades safely on a throwing/rejecting `provide()`).
+ */
+import { describe, expect, it, vi } from "vitest";
+
+import {
+  collectCompletions,
+  resolveReplaceRange,
+  triggerQueryStart,
+  type EditorCompletionItem,
+  type EditorCompletionProvider,
+} from "./editor-completions";
+
+describe("triggerQueryStart", () => {
+  it("resolves to the column right after the LAST trigger char before the caret", () => {
+    // "[[no" — caret after "no" (column 5). The `[` at index 1 (0-based) is the
+    // one whose query we want to replace, so the query start is column 3
+    // (right after the second `[`), preserving the typed "[[".
+    expect(triggerQueryStart("[[no", 5, ["["])).toBe(3);
+  });
+
+  it("returns null when no trigger character precedes the caret", () => {
+    expect(triggerQueryStart("hello world", 6, ["["])).toBeNull();
+  });
+
+  it("returns null when triggerCharacters is undefined or empty", () => {
+    expect(triggerQueryStart("[[no", 5, undefined)).toBeNull();
+    expect(triggerQueryStart("[[no", 5, [])).toBeNull();
+  });
+
+  it("picks the LATEST of several distinct trigger characters", () => {
+    // "@user:na" with triggers "@" and ":" — the `:` (later) wins.
+    expect(triggerQueryStart("@user:na", 9, ["@", ":"])).toBe(7);
+  });
+
+  it("handles the trigger character sitting at column 1", () => {
+    expect(triggerQueryStart("[abc", 5, ["["])).toBe(2);
+  });
+});
+
+describe("resolveReplaceRange", () => {
+  const position = { lineNumber: 3, column: 5 };
+
+  it("uses item.replaceFrom when present, ignoring trigger detection", () => {
+    const item: EditorCompletionItem = { label: "x", insertText: "y", replaceFrom: 2 };
+    const range = resolveReplaceRange(item, position, "[[no", ["["]);
+    expect(range).toEqual({
+      startLineNumber: 3,
+      startColumn: 2,
+      endLineNumber: 3,
+      endColumn: 5,
+    });
+  });
+
+  it("falls back to the trigger-query start when replaceFrom is absent", () => {
+    const item: EditorCompletionItem = { label: "x", insertText: "y" };
+    const range = resolveReplaceRange(item, position, "[[no", ["["]);
+    expect(range).toEqual({
+      startLineNumber: 3,
+      startColumn: 3,
+      endLineNumber: 3,
+      endColumn: 5,
+    });
+  });
+
+  it("falls back to a bare insert at the caret when neither is available", () => {
+    const item: EditorCompletionItem = { label: "x", insertText: "y" };
+    const range = resolveReplaceRange(item, position, "no trigger here", ["["]);
+    expect(range).toEqual({
+      startLineNumber: 3,
+      startColumn: 5,
+      endLineNumber: 3,
+      endColumn: 5,
+    });
+  });
+
+  it("clamps an out-of-range replaceFrom into [1, column] rather than producing a backwards edit", () => {
+    const item: EditorCompletionItem = { label: "x", insertText: "y", replaceFrom: 999 };
+    const range = resolveReplaceRange(item, position, "[[no", ["["]);
+    expect(range.startColumn).toBe(5);
+    const negative: EditorCompletionItem = { label: "x", insertText: "y", replaceFrom: -3 };
+    expect(resolveReplaceRange(negative, position, "[[no", ["["]).startColumn).toBe(1);
+  });
+});
+
+describe("collectCompletions", () => {
+  const ctx = { source: "[[no", line: 1, column: 5, lineText: "[[no" };
+
+  it("pairs each returned item with its provider", async () => {
+    const providerA: EditorCompletionProvider = {
+      id: "a",
+      provide: () => [{ label: "Alpha", insertText: "alpha" }],
+    };
+    const providerB: EditorCompletionProvider = {
+      id: "b",
+      provide: () => [{ label: "Beta", insertText: "beta" }],
+    };
+    const matches = await collectCompletions([providerA, providerB], ctx);
+    expect(matches).toEqual([
+      { provider: providerA, item: { label: "Alpha", insertText: "alpha" } },
+      { provider: providerB, item: { label: "Beta", insertText: "beta" } },
+    ]);
+  });
+
+  it("awaits an async provide()", async () => {
+    const provider: EditorCompletionProvider = {
+      id: "async",
+      provide: async () => [{ label: "Async", insertText: "async" }],
+    };
+    const matches = await collectCompletions([provider], ctx);
+    expect(matches).toHaveLength(1);
+    expect(matches[0]?.item.label).toBe("Async");
+  });
+
+  it("a throwing provide() contributes zero items without affecting others", async () => {
+    const bad: EditorCompletionProvider = {
+      id: "bad",
+      provide: () => {
+        throw new Error("boom");
+      },
+    };
+    const good: EditorCompletionProvider = {
+      id: "good",
+      provide: () => [{ label: "Good", insertText: "good" }],
+    };
+    const matches = await collectCompletions([bad, good], ctx);
+    expect(matches).toHaveLength(1);
+    expect(matches[0]?.item.label).toBe("Good");
+  });
+
+  it("a rejecting async provide() contributes zero items without affecting others", async () => {
+    const bad: EditorCompletionProvider = {
+      id: "bad-async",
+      provide: async () => Promise.reject(new Error("nope")),
+    };
+    const good: EditorCompletionProvider = {
+      id: "good",
+      provide: () => [{ label: "Good", insertText: "good" }],
+    };
+    const matches = await collectCompletions([bad, good], ctx);
+    expect(matches).toHaveLength(1);
+  });
+
+  it("passes the context through to provide()", async () => {
+    const provide = vi.fn().mockReturnValue([]);
+    await collectCompletions([{ id: "spy", provide }], ctx);
+    expect(provide).toHaveBeenCalledWith(ctx);
+  });
+
+  it("an empty provider list resolves to an empty array", async () => {
+    expect(await collectCompletions([], ctx)).toEqual([]);
+  });
+});

package/src/lib/editor-completions.ts

@@ -0,0 +1,153 @@
+/**
+ * Engine-agnostic completion-provider contract (#283) — the `completions` prop
+ * on `MarkdownWorkspace` (and, via it, the WYSIWYG `MarkdownEditor`).
+ *
+ * ISOLATION INVARIANT (mirrors `editor-content-access.ts`): this file imports
+ * NOTHING engine-specific — no `monaco-editor`, no `@milkdown`. It is the
+ * dependency-light leaf both engine adapters (`editor-completions-monaco.ts` for
+ * Monaco, `markdown-editor/completions/` for Milkdown/ProseMirror) build on, so a
+ * consumer can import the TYPES with zero engine imports (#283 acceptance: "zero
+ * `monaco-editor` imports in app code").
+ *
+ * D5 / the calc `complete` hook precedent: the library only REGISTERS the
+ * provider and RENDERS its suggestions — candidate list, filtering/ranking, and
+ * insert text are entirely consumer-owned. Nothing here fetches anything; a
+ * throwing/rejecting `provide()` degrades to "no suggestions" (never blanks or
+ * throws), the same degrade-safely contract as `resolveResults`/`CalcBlock`.
+ */
+
+/** One completion candidate a provider offers at the caret. */
+export interface EditorCompletionItem {
+  /** Text shown in the suggestion list. */
+  label: string;
+  /** Text inserted when the item is chosen. */
+  insertText: string;
+  /** Secondary detail shown muted beside the label. */
+  detail?: string;
+  /**
+   * Start column (1-based, Monaco convention) of the already-typed token to
+   * replace. Defaults to the start of the "trigger query" — the run of text
+   * typed since the provider's trigger character (see {@link triggerQueryStart}).
+   */
+  replaceFrom?: number;
+}
+
+/** What a provider knows at the caret when it is asked for completions. */
+export interface EditorCompletionContext {
+  /** The full document text. */
+  source: string;
+  /** 1-based line number. */
+  line: number;
+  /** 1-based column. */
+  column: number;
+  /** The full text of the current line. */
+  lineText: string;
+}
+
+/**
+ * A declarative completion source. Registered ONCE per `MarkdownWorkspace` (or
+ * `MarkdownEditor`) tree via the `completions` prop — the library owns the
+ * engine registration lifecycle (Monaco's `registerCompletionItemProvider` is
+ * global-per-language, refcounted here; see `editor-completions-monaco.ts`).
+ */
+export interface EditorCompletionProvider {
+  /** Stable id — surfaced for consumer bookkeeping (not currently rendered). */
+  id: string;
+  /** Characters that (re)open the suggestion list, e.g. `["["]`. */
+  triggerCharacters?: string[];
+  /** Return the candidates for the caret described by `ctx`. May be async. */
+  provide(ctx: EditorCompletionContext): EditorCompletionItem[] | Promise<EditorCompletionItem[]>;
+}
+
+/**
+ * Find the 1-based column right after the LAST occurrence, before `column`, of
+ * any of `triggerCharacters` in `lineText` — the start of the "trigger query"
+ * (the text typed since the trigger character). `null` when no trigger
+ * character precedes the caret on this line (falls back to inserting at the
+ * bare caret — see {@link resolveReplaceRange}).
+ *
+ * Deliberately the LAST occurrence, not the first: `[[note` (triggerCharacters
+ * `["["]`) resolves the query start to right after the SECOND `[`, so the
+ * inserted text replaces only `note`, preserving the `[[` the user typed.
+ */
+export function triggerQueryStart(
+  lineText: string,
+  column: number,
+  triggerCharacters: string[] | undefined,
+): number | null {
+  if (!triggerCharacters || triggerCharacters.length === 0) return null;
+  const before = lineText.slice(0, Math.max(0, column - 1));
+  let bestIndex = -1;
+  for (const ch of triggerCharacters) {
+    if (!ch) continue;
+    const idx = before.lastIndexOf(ch);
+    if (idx > bestIndex) bestIndex = idx;
+  }
+  if (bestIndex === -1) return null;
+  return bestIndex + 2; // 0-based char index → 1-based column, then step past it
+}
+
+/** A 1-based, Monaco-`IRange`-shaped span (structural — no monaco import). */
+export interface CompletionReplaceRange {
+  startLineNumber: number;
+  startColumn: number;
+  endLineNumber: number;
+  endColumn: number;
+}
+
+/**
+ * Resolve the range an item's `insertText` replaces: `item.replaceFrom` when
+ * given, else the trigger-query start (see {@link triggerQueryStart}), else the
+ * bare caret (a pure insert, nothing replaced). Always ends at the caret, on
+ * the caret's line — a completion never spans multiple lines.
+ */
+export function resolveReplaceRange(
+  item: EditorCompletionItem,
+  position: { lineNumber: number; column: number },
+  lineText: string,
+  triggerCharacters: string[] | undefined,
+): CompletionReplaceRange {
+  const start =
+    item.replaceFrom ??
+    triggerQueryStart(lineText, position.column, triggerCharacters) ??
+    position.column;
+  return {
+    startLineNumber: position.lineNumber,
+    // Clamp into [1, column] — a bad/stale `replaceFrom` degrades to "insert at
+    // caret" rather than producing a backwards/out-of-range edit.
+    startColumn: Math.min(Math.max(1, start), position.column),
+    endLineNumber: position.lineNumber,
+    endColumn: position.column,
+  };
+}
+
+/** One resolved completion item, paired with the provider that produced it. */
+export interface CompletionMatch {
+  provider: EditorCompletionProvider;
+  item: EditorCompletionItem;
+}
+
+/**
+ * Call every provider's `provide(ctx)`, collect the results, and pair each item
+ * back with its provider (so a caller can resolve a per-provider replace range
+ * via that provider's `triggerCharacters`). Never throws: a provider whose
+ * `provide()` throws or whose returned promise rejects contributes zero items
+ * (mirrors `resolveResults`'s calc-hook degrade-safely contract) — one bad
+ * provider never blanks another's suggestions.
+ */
+export async function collectCompletions(
+  providers: EditorCompletionProvider[],
+  ctx: EditorCompletionContext,
+): Promise<CompletionMatch[]> {
+  const perProvider = await Promise.all(
+    providers.map(async (provider): Promise<CompletionMatch[]> => {
+      try {
+        const items = (await provider.provide(ctx)) ?? [];
+        return items.map((item) => ({ provider, item }));
+      } catch {
+        return [];
+      }
+    }),
+  );
+  return perProvider.flat();
+}