@matdata/yasqe 5.20.2 → 6.0.0

package/src/editor/folding.ts

@@ -0,0 +1,225 @@
+/**
+ * Code folding for SPARQL: folds bracket blocks (`{ ... }`) and the block of PREFIX declarations.
+ *
+ * Replaces the CodeMirror 5 combination of `fold.brace` and the custom `fold.prefix` helper.
+ * Because the SPARQL grammar is a stream parser (no syntax tree with nesting), folding is
+ * implemented as a `foldService` working on the tokenizer output.
+ */
+import { EditorState, Extension, Text } from "@codemirror/state";
+import { EditorView } from "@codemirror/view";
+import { foldService, foldGutter, foldEffect, unfoldEffect, foldedRanges, foldable } from "@codemirror/language";
+import { TokenizerRunner, Position } from "./tokenizerRunner";
+
+export interface FoldRange {
+  from: number;
+  to: number;
+}
+
+const PREFIX_KEYWORD = "PREFIX ";
+
+function tokenTypeAt(runner: TokenizerRunner, doc: Text, pos: Position) {
+  return runner.getTokenAt(doc, pos).type;
+}
+
+/**
+ * Whether `type` denotes a real bracket/punctuation token (i.e. not a bracket character that is
+ * part of a string or comment). The tokenizer styles brackets as `bracket bracket-level-N` /
+ * `bracket bracket-paren`, so a plain `=== "punc"` check would miss `{ } ( ) [ ]`.
+ */
+function isBracketToken(type: string | null): boolean {
+  return !!type && (type === "punc" || type.split(/\s+/).some((t) => t === "punc" || t.startsWith("bracket")));
+}
+
+/**
+ * Finds the fold range for a block starting with a bracket on the given line. Mirrors the
+ * CodeMirror 5 `brace` range finder: the *last* opening bracket on the line is used.
+ */
+export function braceFoldRange(runner: TokenizerRunner, doc: Text, line: number): FoldRange | undefined {
+  const lineText = doc.line(line + 1).text;
+  const pairs: { [open: string]: string } = { "{": "}", "[": "]", "(": ")" };
+  let startCh = -1;
+  let open = "";
+  for (let ch = lineText.length - 1; ch >= 0; ch--) {
+    const c = lineText[ch];
+    if (pairs[c] && isBracketToken(tokenTypeAt(runner, doc, { line, ch: ch + 1 }))) {
+      startCh = ch;
+      open = c;
+      break;
+    }
+  }
+  if (startCh < 0) return;
+  const close = pairs[open];
+
+  // Scan forward for the matching bracket, taking nesting into account and ignoring brackets inside strings/comments
+  let depth = 1;
+  const lastLine = doc.lines - 1;
+  for (let l = line; l <= lastLine; l++) {
+    const text = doc.line(l + 1).text;
+    let ch = l === line ? startCh + 1 : 0;
+    for (; ch < text.length; ch++) {
+      const c = text[ch];
+      if (c !== open && c !== close) continue;
+      if (!isBracketToken(tokenTypeAt(runner, doc, { line: l, ch: ch + 1 }))) continue;
+      if (c === open) depth++;
+      else if (--depth === 0) {
+        if (l === line) return; // opening and closing bracket on the same line: nothing to fold
+        return { from: doc.line(line + 1).from + startCh + 1, to: doc.line(l + 1).from + ch };
+      }
+    }
+  }
+  return;
+}
+
+/** Returns the char index of the first PREFIX keyword on the line (or undefined) */
+export function findFirstPrefix(
+  runner: TokenizerRunner,
+  doc: Text,
+  line: number,
+  startFromCharIndex = 0,
+): number | undefined {
+  const lineText = doc.line(line + 1).text;
+  if (!lineText) return undefined;
+  const charIndex = lineText.toUpperCase().indexOf(PREFIX_KEYWORD, startFromCharIndex);
+  if (charIndex >= 0 && tokenTypeAt(runner, doc, { line, ch: charIndex + 1 }) === "keyword") {
+    return charIndex;
+  }
+  return undefined;
+}
+
+/** Returns the (0-based) line of the first PREFIX declaration in the document */
+export function findFirstPrefixLine(runner: TokenizerRunner, doc: Text): number | undefined {
+  for (let i = 0; i < doc.lines; i++) {
+    const firstPrefix = findFirstPrefix(runner, doc, i);
+    if (firstPrefix !== undefined && firstPrefix >= 0) return i;
+  }
+  return undefined;
+}
+
+/**
+ * Fold range for the block of PREFIX declarations. Only the first PREFIX declaration of the query
+ * starts a foldable block. Ported from the CodeMirror 5 `fold.prefix` helper.
+ */
+export function prefixFoldRange(runner: TokenizerRunner, doc: Text, line: number): FoldRange | undefined {
+  // Only the opening prefix declaration is foldable
+  for (let i = line - 1; i >= 0; i--) {
+    if (
+      doc
+        .line(i + 1)
+        .text.toUpperCase()
+        .indexOf(PREFIX_KEYWORD) >= 0
+    )
+      return;
+  }
+  const prefixStart = findFirstPrefix(runner, doc, line);
+  if (prefixStart === undefined) return;
+
+  const getNextNonWsToken = (l: number, ch: number) => {
+    let token = runner.getTokenAt(doc, { line: l, ch });
+    if (token.end < ch) return undefined;
+    while (token.type === "ws") {
+      const next = runner.getTokenAt(doc, { line: l, ch: token.end + 1 });
+      if (next.end < token.end + 1) return undefined;
+      token = next;
+    }
+    return token;
+  };
+  const getLastPrefixPos = (l: number, ch: number): number => {
+    const keyword = runner.getTokenAt(doc, { line: l, ch: ch + 1 });
+    if (keyword.type !== "keyword") return -1;
+    const shortname = getNextNonWsToken(l, keyword.end + 1);
+    if (!shortname || shortname.type !== "string-2") return -1;
+    const uri = getNextNonWsToken(l, shortname.end + 1);
+    if (!uri || uri.type !== "variable-3") return -1;
+    return uri.end;
+  };
+
+  let prefixEndChar = getLastPrefixPos(line, prefixStart);
+  let prefixEndLine = line;
+  let stopAtNextLine = false;
+  for (let i = line; i < doc.lines; i++) {
+    if (stopAtNextLine) break;
+    const text = doc.line(i + 1).text;
+    let pos = i === line ? prefixStart + 1 : 0;
+    for (;;) {
+      if (!stopAtNextLine && text.indexOf("{") >= 0) stopAtNextLine = true;
+      const nextPrefixDeclaration = text.toUpperCase().indexOf(PREFIX_KEYWORD, pos);
+      if (nextPrefixDeclaration < 0) break;
+      const endCh = getLastPrefixPos(i, nextPrefixDeclaration);
+      if (endCh > 0) {
+        prefixEndChar = endCh;
+        prefixEndLine = i;
+        pos = prefixEndChar;
+      }
+      pos++;
+    }
+  }
+  if (prefixEndChar < 0) return;
+  const from = doc.line(line + 1).from + prefixStart + PREFIX_KEYWORD.length;
+  const to = doc.line(prefixEndLine + 1).from + prefixEndChar;
+  if (to <= from) return;
+  return { from, to };
+}
+
+/** Combined range finder (brace first, then prefix block) for a given 0-based line */
+export function foldRangeForLine(runner: TokenizerRunner, doc: Text, line: number): FoldRange | undefined {
+  return braceFoldRange(runner, doc, line) || prefixFoldRange(runner, doc, line);
+}
+
+/** Folding extensions: fold service + fold gutter */
+export function sparqlFolding(runner: TokenizerRunner): Extension {
+  return [
+    foldService.of((state: EditorState, lineStart: number) => {
+      const line = state.doc.lineAt(lineStart).number - 1;
+      return foldRangeForLine(runner, state.doc, line) || null;
+    }),
+    foldGutter({
+      markerDOM(open) {
+        const el = document.createElement("span");
+        el.className = `cm-foldMarker CodeMirror-foldgutter-${open ? "open" : "folded"}`;
+        el.title = open ? "Fold" : "Unfold";
+        return el;
+      },
+    }),
+  ];
+}
+
+/** Fold (or unfold, when already folded) the block starting at the given position. */
+export function toggleFoldAt(view: EditorView, pos: number) {
+  const line = view.state.doc.lineAt(pos);
+  // Unfold when the line is (partly) hidden by a fold
+  let unfolded = false;
+  foldedRanges(view.state).between(line.from, line.to, (from, to) => {
+    if (from >= line.from && from <= line.to) {
+      view.dispatch({ effects: unfoldEffect.of({ from, to }) });
+      unfolded = true;
+      return false;
+    }
+    return;
+  });
+  if (unfolded) return;
+  const range = foldable(view.state, line.from, line.to);
+  if (range) view.dispatch({ effects: foldEffect.of(range) });
+}
+
+/** Fold the block starting at the given position (no-op if nothing foldable or already folded) */
+export function foldAt(view: EditorView, pos: number) {
+  const line = view.state.doc.lineAt(pos);
+  let alreadyFolded = false;
+  foldedRanges(view.state).between(line.from, line.to, () => {
+    alreadyFolded = true;
+    return false;
+  });
+  if (alreadyFolded) return;
+  const range = foldable(view.state, line.from, line.to);
+  if (range) view.dispatch({ effects: foldEffect.of(range) });
+}
+
+/** Unfold any fold that starts on the line of the given position (no-op if not folded) */
+export function unfoldAt(view: EditorView, pos: number) {
+  const line = view.state.doc.lineAt(pos);
+  const effects: ReturnType<typeof unfoldEffect.of>[] = [];
+  foldedRanges(view.state).between(line.from, line.to, (from, to) => {
+    if (from >= line.from && from <= line.to) effects.push(unfoldEffect.of({ from, to }));
+  });
+  if (effects.length) view.dispatch({ effects });
+}

package/src/editor/gutters.ts

@@ -0,0 +1,152 @@
+/**
+ * Marker gutters replacing the CodeMirror 5 `setGutterMarker` / `clearGutter` API.
+ *
+ * Two logical marker types are supported: `gutterErrorBar` (syntax errors) and
+ * `gutterConstructWarning` (undefined variables in CONSTRUCT templates). Both are rendered
+ * in one physical gutter lane to keep gutter width minimal.
+ */
+import { EditorState, StateEffect, StateField, RangeSet, Extension } from "@codemirror/state";
+import { EditorView, gutter, GutterMarker } from "@codemirror/view";
+
+export type GutterName = "gutterErrorBar" | "gutterConstructWarning";
+export const GUTTER_NAMES: GutterName[] = ["gutterErrorBar", "gutterConstructWarning"];
+const RENDER_GUTTER_NAME: GutterName = "gutterErrorBar";
+
+class ElementMarker extends GutterMarker {
+  constructor(readonly element: HTMLElement) {
+    super();
+  }
+  eq(other: ElementMarker) {
+    return other.element === this.element;
+  }
+  toDOM() {
+    // Return a fresh clone on every render. CodeMirror 6 owns (and may move/recreate) the node
+    // it gets from `toDOM`; handing out the same shared element across gutter re-renders detaches
+    // it from a previous gutter element, which later crashes with `nextSibling` of null.
+    const clone = this.element.cloneNode(true) as HTMLElement;
+    clone.onmouseover = this.element.onmouseover;
+    clone.onmouseout = this.element.onmouseout;
+    return clone;
+  }
+}
+
+interface SetMarkerSpec {
+  gutter: GutterName;
+  /** 0-based line number */
+  line: number;
+  element: HTMLElement | null;
+}
+
+const setMarkerEffect = StateEffect.define<SetMarkerSpec>();
+const clearGutterEffect = StateEffect.define<GutterName>();
+
+function createMarkerField(name: GutterName): StateField<RangeSet<ElementMarker>> {
+  const field = StateField.define<RangeSet<ElementMarker>>({
+    create() {
+      return RangeSet.empty;
+    },
+    update(markers, tr) {
+      markers = markers.map(tr.changes);
+      for (const effect of tr.effects) {
+        if (effect.is(clearGutterEffect) && effect.value === name) {
+          markers = RangeSet.empty;
+        } else if (effect.is(setMarkerEffect) && effect.value.gutter === name) {
+          const { line, element } = effect.value;
+          if (line < 0 || line >= tr.state.doc.lines) continue;
+          const pos = tr.state.doc.line(line + 1).from;
+          markers = markers.update({ filter: (from) => from !== pos });
+          if (element) {
+            markers = markers.update({ add: [new ElementMarker(element).range(pos)] });
+          }
+        }
+      }
+      return markers;
+    },
+  });
+  return field;
+}
+
+function spacerElement() {
+  const el = document.createElement("span");
+  el.className = "cm-gutter-spacer";
+  el.textContent = "\u00a0";
+  return el;
+}
+
+function mergeMarkersWithErrorPriority(
+  errorMarkers: RangeSet<ElementMarker>,
+  warningMarkers: RangeSet<ElementMarker>,
+): RangeSet<ElementMarker> {
+  const byPos = new Map<number, ElementMarker>();
+
+  const warningIter = warningMarkers.iter();
+  while (warningIter.value) {
+    byPos.set(warningIter.from, warningIter.value);
+    warningIter.next();
+  }
+
+  // Errors overwrite warnings on the same line.
+  const errorIter = errorMarkers.iter();
+  while (errorIter.value) {
+    byPos.set(errorIter.from, errorIter.value);
+    errorIter.next();
+  }
+
+  const ranges: ReturnType<ElementMarker["range"]>[] = [];
+  const sortedPos = Array.from(byPos.keys()).sort((a, b) => a - b);
+  for (const pos of sortedPos) {
+    const marker = byPos.get(pos);
+    if (marker) ranges.push(marker.range(pos));
+  }
+  return RangeSet.of(ranges, true);
+}
+
+// Fields are defined once so that they are shared between all editor instances.
+const gutterFields = new Map<GutterName, StateField<RangeSet<ElementMarker>>>();
+for (const name of GUTTER_NAMES) {
+  gutterFields.set(name, createMarkerField(name));
+}
+
+const gutterExtensions: Extension[] = [
+  gutterFields.get("gutterErrorBar")!,
+  gutterFields.get("gutterConstructWarning")!,
+  gutter({
+    class: `cm-gutter-${RENDER_GUTTER_NAME} CodeMirror-${RENDER_GUTTER_NAME}`,
+    markers: (view) =>
+      mergeMarkersWithErrorPriority(
+        view.state.field(gutterFields.get("gutterErrorBar")!),
+        view.state.field(gutterFields.get("gutterConstructWarning")!),
+      ),
+    initialSpacer: () => new ElementMarker(spacerElement()),
+  }),
+];
+
+/** Extension enabling the yasqe marker gutters */
+export function markerGutters(): Extension {
+  return gutterExtensions;
+}
+
+/** Set (or remove when `element` is null) the marker of `line` (0-based) in the given gutter */
+export function setGutterMarker(view: EditorView, line: number, name: GutterName, element: HTMLElement | null) {
+  view.dispatch({ effects: setMarkerEffect.of({ gutter: name, line, element }) });
+}
+
+/** Remove all markers from the given gutter */
+export function clearGutter(view: EditorView, name: GutterName) {
+  view.dispatch({ effects: clearGutterEffect.of(name) });
+}
+
+/** Returns the marker elements of the gutter, keyed by 0-based line number */
+export function getGutterMarkers(state: EditorState, name: GutterName): Map<number, HTMLElement> {
+  const result = new Map<number, HTMLElement>();
+  const field = gutterFields.get(name);
+  if (!field) return result;
+  const set = state.field(field, false);
+  if (!set) return result;
+  const iter = set.iter();
+  while (iter.value) {
+    result.set(state.doc.lineAt(iter.from).number - 1, iter.value.element);
+    iter.next();
+  }
+  return result;
+}

package/src/editor/keymap.ts

@@ -0,0 +1,133 @@
+/**
+ * Keymap helpers for the CodeMirror 6 based editor.
+ *
+ * Yasqe historically exposed key bindings using CodeMirror 5 key names
+ * (e.g. "Shift-Ctrl-K", "Cmd-Enter", "Esc"). To stay backwards compatible we
+ * accept those names in the `extraKeys` config option and convert them to the
+ * CodeMirror 6 keymap format.
+ */
+import { Extension, Prec } from "@codemirror/state";
+import { EditorView, KeyBinding, keymap } from "@codemirror/view";
+import { defaultKeymap, historyKeymap, indentWithTab, indentLess, indentMore, insertTab } from "@codemirror/commands";
+import { searchKeymap } from "@codemirror/search";
+import { foldKeymap } from "@codemirror/language";
+import { closeBracketsKeymap } from "@codemirror/autocomplete";
+
+/**
+ * A key handler in the (CM5-compatible) `extraKeys` config. It receives the
+ * Yasqe instance. Returning `false` lets the event propagate to the next
+ * binding; anything else is considered "handled".
+ */
+export type ExtraKeyHandler<T = any> = (yasqe: T) => any;
+export type ExtraKeys<T = any> = { [key: string]: ExtraKeyHandler<T> | string };
+
+const MODIFIERS = new Set(["shift", "ctrl", "cmd", "alt", "mod", "meta"]);
+
+const KEY_NAME_MAP: { [cm5: string]: string } = {
+  esc: "Escape",
+  space: "Space",
+  enter: "Enter",
+  tab: "Tab",
+  backspace: "Backspace",
+  delete: "Delete",
+  del: "Delete",
+  insert: "Insert",
+  home: "Home",
+  end: "End",
+  pageup: "PageUp",
+  pagedown: "PageDown",
+  left: "ArrowLeft",
+  right: "ArrowRight",
+  up: "ArrowUp",
+  down: "ArrowDown",
+};
+
+/**
+ * Convert a CodeMirror 5 style key name (e.g. "Shift-Ctrl-K") to a
+ * CodeMirror 6 key name ("Shift-Ctrl-k").
+ *
+ * CM6 uses `event.key` values, so single characters must be lower case
+ * (unless shift is pressed), and special keys use their DOM names.
+ */
+export function convertKeyName(cm5Name: string): string {
+  const parts = cm5Name.split(/-(?!$)/);
+  const modifiers: string[] = [];
+  let key = parts[parts.length - 1];
+  for (let i = 0; i < parts.length - 1; i++) {
+    const mod = parts[i].toLowerCase();
+    if (mod === "meta") modifiers.push("Cmd");
+    else if (MODIFIERS.has(mod)) modifiers.push(parts[i][0].toUpperCase() + mod.slice(1));
+  }
+  const lowerKey = key.toLowerCase();
+  if (KEY_NAME_MAP[lowerKey]) {
+    key = KEY_NAME_MAP[lowerKey];
+  } else if (/^f\d{1,2}$/i.test(key)) {
+    key = key.toUpperCase();
+  } else if (key.length === 1) {
+    // Letters are lower case in CM6 (they match event.key). When shift is part of
+    // the binding CM6 also accepts the lower case form and derives the shifted variant.
+    key = key.toLowerCase();
+  }
+  return [...modifiers, key].join("-");
+}
+
+/**
+ * Build a keymap extension from a CM5-style `extraKeys` object.
+ *
+ * @param extraKeys CM5-style key -> handler map
+ * @param getYasqe  returns the Yasqe instance (passed to the handler)
+ * @param commands  named commands that string handlers may refer to
+ */
+export function extraKeysExtension<T>(
+  extraKeys: ExtraKeys<T> | undefined,
+  getYasqe: () => T,
+  commands: { [name: string]: (yasqe: T) => any } = {},
+): Extension {
+  if (!extraKeys) return [];
+  const bindings: KeyBinding[] = [];
+  for (const cm5Key of Object.keys(extraKeys)) {
+    const handler = extraKeys[cm5Key];
+    const fn: ExtraKeyHandler<T> | undefined = typeof handler === "string" ? commands[handler] : handler;
+    if (!fn) continue;
+    bindings.push({
+      key: convertKeyName(cm5Key),
+      run: () => {
+        const result = fn(getYasqe());
+        return result !== false;
+      },
+      preventDefault: true,
+    });
+  }
+  // Highest precedence so user defined keys win over the built-in ones.
+  return Prec.highest(keymap.of(bindings));
+}
+
+/**
+ * Tab handling that mimics CM5's `tabMode: "indent"` behaviour: Tab indents,
+ * Shift-Tab dedents. When `tabMode` is anything else, tab inserts a tab
+ * character (or spaces when `indentWithTabs` is false).
+ */
+export function tabKeymap(tabMode: string | undefined): Extension {
+  if (tabMode === "indent") {
+    return keymap.of([
+      {
+        key: "Tab",
+        run: (view: EditorView) => {
+          // Indent selection when something is selected, otherwise behave like indentMore.
+          return indentMore(view);
+        },
+        shift: indentLess,
+      },
+    ]);
+  }
+  if (tabMode === "default") return keymap.of([indentWithTab]);
+  return keymap.of([{ key: "Tab", run: insertTab, shift: indentLess }]);
+}
+
+/**
+ * The default set of key bindings: standard editing, history, search, folding,
+ * bracket closing and autocompletion.
+ */
+export function defaultKeymaps(): Extension {
+  return keymap.of([...closeBracketsKeymap, ...defaultKeymap, ...searchKeymap, ...historyKeymap, ...foldKeymap]);
+}

package/src/editor/language.ts

@@ -0,0 +1,47 @@
+/**
+ * CodeMirror 6 language definition for SPARQL 1.1, built on top of the
+ * legacy (stream based) LL(1) tokenizer in ../../grammar/tokenizer.ts.
+ *
+ * Every token style emitted by the tokenizer gets its own lezer Tag and a
+ * matching `cm-<style>` CSS class so the existing style sheets keep working.
+ */
+import { StreamLanguage, HighlightStyle, syntaxHighlighting, LanguageSupport } from "@codemirror/language";
+import { Tag } from "@lezer/highlight";
+import type { Extension } from "@codemirror/state";
+import sparqlTokenizer, {
+  TOKEN_STYLES,
+  TokenStyle,
+  State as TokenizerState,
+  TokenizerConfig,
+} from "../../grammar/tokenizer";
+
+export type { TokenizerState };
+
+export const sparqlTags: Record<TokenStyle, Tag> = TOKEN_STYLES.reduce(
+  (acc, style) => {
+    acc[style] = Tag.define();
+    return acc;
+  },
+  {} as Record<TokenStyle, Tag>,
+);
+
+export function createSparqlParser(config: TokenizerConfig = {}) {
+  const parser = sparqlTokenizer(config);
+  parser.tokenTable = sparqlTags;
+  return parser;
+}
+
+export const sparqlLanguage = StreamLanguage.define<TokenizerState>(createSparqlParser());
+
+/**
+ * Highlight style mapping each SPARQL token tag to the classic CodeMirror 5 class name (`cm-keyword`, `cm-atom`, ...).
+ */
+export const sparqlHighlightStyle = HighlightStyle.define(
+  TOKEN_STYLES.map((style) => ({ tag: sparqlTags[style], class: `cm-${style}` })),
+);
+
+export function sparql(): LanguageSupport {
+  return new LanguageSupport(sparqlLanguage, [syntaxHighlighting(sparqlHighlightStyle)]);
+}
+
+export const sparqlExtensions = (): Extension => sparql();