@adecore/editor-react 0.43.0 → 0.44.0

package/dist/postfix.d.ts

@@ -0,0 +1,21 @@
+import type { EditorPosition } from '@adecore/editor';
+import type { LocalCompletionItem } from './completion.ts';
+import type { EditorLanguage } from './editor-language.ts';
+interface PostfixKey {
+    readonly start: EditorPosition;
+    expand(): boolean;
+}
+export declare class PostfixFeature {
+    private readonly language;
+    constructor(language: EditorLanguage);
+    key(): PostfixKey | null;
+    rows(position: EditorPosition): readonly LocalCompletionItem[];
+    private row;
+    private candidates;
+    private expandKey;
+    private expand;
+    private run;
+    private rendered;
+    private expressionOf;
+}
+export {};

package/dist/postfix.js

@@ -0,0 +1,212 @@
+import { isIdentifierCharacter } from './completion-model.js';
+import { comparePositions } from './diagnostics-model.js';
+import { lineTextOf, textBeforeOf } from './line-text.js';
+import { bodyWithIndentUnit, dedentLines, indentUnitOf, insertSnippet } from './snippet-insert.js';
+import { compileSnippet } from './snippet.js';
+import { SNIPPET_KIND, sortAfterServer, templateContextAt } from './template-context.js';
+const MAX_ROW_LENGTH = 80;
+/* The identifier characters after the last dot of `before`, and where that dot is; null when no dot leads them. */
+function typedKey(before) {
+  let index = before.length;
+  while (index > 0 && isIdentifierCharacter(before[index - 1])) {
+    index--;
+  }
+  return index > 0 && before[index - 1] === '.' ? {
+    key: before.slice(index),
+    dot: index - 1
+  } : null;
+}
+/* One line of a chooser row: whitespace collapsed and cut short. */
+function rowLabel(text) {
+  const line = text.replace(/\s+/g, ' ').trim();
+  return line.length > MAX_ROW_LENGTH ? `${line.slice(0, MAX_ROW_LENGTH - 1)}…` : line;
+}
+/*
+ * Postfix completion: a dot and a key after an expression, and Tab or an accepted row wraps the expression in a
+ * template. The registry holds the templates and `TemplatesFeature` decides whether Tab is ours or a live template's.
+ */
+export class PostfixFeature {
+  language;
+  constructor(language) {
+    this.language = language;
+  }
+  /* The key before the caret that a template of the registry applies to; null where Tab has no postfix template to expand. */
+  key() {
+    const {
+      editor,
+      project
+    } = this.language;
+    if (!project.templates.settings.postfix) {
+      return null;
+    }
+    const caret = editor.getCaret();
+    const typed = typedKey(textBeforeOf(editor, caret));
+    if (typed === null || typed.key === '') {
+      return null;
+    }
+    const candidates = this.candidates({
+      line: caret.line,
+      character: typed.dot
+    }, template => template.key === typed.key);
+    if (candidates === null) {
+      return null;
+    }
+    return {
+      start: candidates.dot,
+      expand: () => this.expandKey(candidates, caret)
+    };
+  }
+  /* The rows of the suggestion list after a dot, for the templates whose key the typed characters can lead to. */
+  rows(position) {
+    const {
+      editor,
+      project
+    } = this.language;
+    const {
+      settings
+    } = project.templates;
+    const selections = editor.getSelections();
+    if (!settings.postfix || !settings.postfixInCompletion || selections.length !== 1 || comparePositions(selections[0].start, selections[0].end) !== 0) {
+      return [];
+    }
+    const typed = typedKey(textBeforeOf(editor, position));
+    if (typed === null) {
+      return [];
+    }
+    const candidates = this.candidates({
+      line: position.line,
+      character: typed.dot
+    }, template => template.key.startsWith(typed.key));
+    if (candidates === null) {
+      return [];
+    }
+    const range = {
+      start: {
+        line: position.line,
+        character: typed.dot + 1
+      },
+      end: position
+    };
+    return candidates.templates.map(template => this.row(template, candidates, range, sortAfterServer(template.key)));
+  }
+  row(template, candidates, range, sortText) {
+    const item = {
+      label: template.key,
+      kind: SNIPPET_KIND,
+      detail: template.example,
+      documentation: template.description,
+      filterText: template.key,
+      sortText,
+      textEdit: {
+        range,
+        newText: template.key
+      }
+    };
+    return {
+      item,
+      accept: () => this.expand(template, candidates, this.language.editor.getCaret())
+    };
+  }
+  /* The templates `matches` lets through that apply to the expressions before `dot`; null when none does. */
+  candidates(dot, matches) {
+    const {
+      editor,
+      project
+    } = this.language;
+    const operands = editor.postfixOperands?.(dot) ?? [];
+    if (operands.length === 0) {
+      return null;
+    }
+    const context = templateContextAt(this.language, dot);
+    if (context.place !== 'code') {
+      return null;
+    }
+    const widest = operands.at(-1);
+    const templates = project.templates.postfix.filter(template => matches(template) && template.languages.some(family => context.families.includes(family)) && (template.expression !== 'statement' || widest.statement));
+    return templates.length === 0 ? null : {
+      dot,
+      operands,
+      templates
+    };
+  }
+  /* Expands the one template of a key, or lists them when several share it. */
+  expandKey(candidates, caret) {
+    if (candidates.templates.length === 1) {
+      this.expand(candidates.templates[0], candidates, caret);
+      return true;
+    }
+    const start = {
+      line: candidates.dot.line,
+      character: candidates.dot.character + 1
+    };
+    this.language.completion.showItems(candidates.templates.map(template => this.row(template, candidates, {
+      start,
+      end: caret
+    }, template.id)), start);
+    return true;
+  }
+  /* Wraps the widest expression for a statement, the only one there is, or the one a person picks from the expressions. */
+  expand(template, candidates, caret) {
+    const {
+      operands
+    } = candidates;
+    if (template.expression === 'statement' || operands.length === 1) {
+      void this.run(template, template.expression === 'statement' ? operands.at(-1) : operands[0], caret);
+      return;
+    }
+    const {
+      editor,
+      completion,
+      pick,
+      project
+    } = this.language;
+    const rows = operands.map((operand, index) => ({
+      id: String(index),
+      label: rowLabel(editor.textInRange(operand.range)),
+      detail: ''
+    }));
+    completion.close();
+    pick.open({
+      anchor: caret,
+      title: project.i18n.t('editor:language.postfix.expressions'),
+      groups: [{
+        title: null,
+        rows
+      }],
+      accept: id => void this.run(template, operands[Number(id)], caret),
+      preview: id => Promise.resolve({
+        removed: [],
+        added: this.rendered(template, operands[Number(id)]).split('\n'),
+        note: null,
+        kind: 'text'
+      })
+    });
+  }
+  run(template, operand, caret) {
+    const {
+      editor
+    } = this.language;
+    const expression = this.expressionOf(operand);
+    return insertSnippet(this.language, bodyWithIndentUnit(template.body, indentUnitOf(editor)), [{
+      range: {
+        start: operand.range.start,
+        end: caret
+      }
+    }], name => name === 'EXPR' ? expression : undefined);
+  }
+  /* What the template would put in place of the expression, tab stops at their placeholders. */
+  rendered(template, operand) {
+    const expression = this.expressionOf(operand);
+    return compileSnippet(bodyWithIndentUnit(template.body, indentUnitOf(this.language.editor))).render(name => name === 'EXPR' ? expression : undefined, undefined, {
+      indentVariables: true
+    }).text;
+  }
+  /* The text of an expression, with the indentation of its first line taken off the lines after it. */
+  expressionOf(operand) {
+    const {
+      editor
+    } = this.language;
+    const indent = /^[\t ]*/.exec(lineTextOf(editor, operand.range.start.line))[0];
+    return dedentLines(editor.textInRange(operand.range).trimEnd(), indent);
+  }
+}

package/dist/project-language.d.ts

@@ -2,6 +2,7 @@ import { type i18n } from 'i18next';
 import { type ApplyWorkspaceEditResult, type LanguageService, type WorkspaceEdit } from '@adecore/lsp';
 import type { Editor, EditorPosition } from '@adecore/editor';
 import { ClipboardHistory } from './clipboard-history.ts';
+import { TemplateRegistry } from './templates.ts';
 import { EditLocations } from './edit-locations.ts';
 import { NavigationHistory, type Place } from './navigation-history.ts';
 import { ProjectProblems } from './project-problems.ts';
@@ -28,6 +29,7 @@ export declare class ProjectLanguage {
     readonly history: NavigationHistory;
     readonly edits: EditLocations;
     readonly clipboard: ClipboardHistory;
+    readonly templates: TemplateRegistry;
     private readonly holders;
     private readonly files;
     panelBodyHeight: number;

package/dist/project-language.js

@@ -2,6 +2,7 @@ import { disposeSnippetTransforms } from './snippet-transform-queue.js';
 import i18next from 'i18next';
 import { fileUriToPath, pathToFileUri, unservedLanguageService } from '@adecore/lsp';
 import { ClipboardHistory } from './clipboard-history.js';
+import { TemplateRegistry } from './templates.js';
 import { EditLocations } from './edit-locations.js';
 import { NavigationHistory } from './navigation-history.js';
 import { ProjectProblems, serviceProblems } from './project-problems.js';
@@ -91,6 +92,7 @@ export class ProjectLanguage {
   history = new NavigationHistory();
   edits;
   clipboard;
+  templates;
   holders = new Map();
   files;
   /* The body height of the peek and call hierarchy panels, shared by the editors of the project. */
@@ -110,6 +112,7 @@ export class ProjectLanguage {
     this.files = host.files ?? null;
     this.edits = new EditLocations(host.editHistoryLimit);
     this.clipboard = host.clipboard ?? new ClipboardHistory();
+    this.templates = host.templates ?? new TemplateRegistry();
     this.panelBodyHeight = host.panelBodyHeight ?? PANEL_BODY_HEIGHT;
     this.problems = new ProjectProblems(host.problemSource ?? serviceProblems(service, uri => this.pathOfLocation(uri) ?? uri));
     const shows = service.onShowDocument?.(params => this.showDocument(params));

package/dist/shortcut-keys.d.ts

@@ -52,6 +52,7 @@ export declare function shortcutsOf(keymap: Keymap, apple: boolean): {
     historyForward: LanguageShortcut | null;
     increaseFontSize: LanguageShortcut | null;
     inlineEdit: LanguageShortcut | null;
+    insertLiveTemplate: LanguageShortcut | null;
     joinLines: LanguageShortcut | null;
     lastEditLocation: LanguageShortcut | null;
     matchBrace: LanguageShortcut | null;
@@ -83,6 +84,7 @@ export declare function shortcutsOf(keymap: Keymap, apple: boolean): {
     resetFontSize: LanguageShortcut | null;
     reverseLines: LanguageShortcut | null;
     save: LanguageShortcut | null;
+    saveAsLiveTemplate: LanguageShortcut | null;
     selectAll: LanguageShortcut | null;
     selectAllOccurrences: LanguageShortcut | null;
     selectNextOccurrence: LanguageShortcut | null;
@@ -101,6 +103,8 @@ export declare function shortcutsOf(keymap: Keymap, apple: boolean): {
     startNewLine: LanguageShortcut | null;
     startNewLineBefore: LanguageShortcut | null;
     suggestInline: LanguageShortcut | null;
+    surroundWith: LanguageShortcut | null;
+    surroundWithLiveTemplate: LanguageShortcut | null;
     textEnd: LanguageShortcut | null;
     textStart: LanguageShortcut | null;
     toggleBlockComment: LanguageShortcut | null;
@@ -113,6 +117,7 @@ export declare function shortcutsOf(keymap: Keymap, apple: boolean): {
     undo: LanguageShortcut | null;
     uniqueLines: LanguageShortcut | null;
     unselectOccurrence: LanguageShortcut | null;
+    unwrap: LanguageShortcut | null;
     wordLeft: LanguageShortcut | null;
     wordRight: LanguageShortcut | null;
     wrapWithAbbreviation: LanguageShortcut | null;

package/dist/snippet-insert.d.ts

@@ -0,0 +1,10 @@
+import type { Editor, EditorRange } from '@adecore/editor';
+import type { EditorLanguage } from './editor-language.ts';
+export interface SnippetPlacement {
+    readonly range: EditorRange;
+    readonly selectedText?: string;
+}
+export declare function bodyWithIndentUnit(body: string, unit: string): string;
+export declare function indentUnitOf(editor: Editor): string;
+export declare function dedentLines(text: string, base?: string): string;
+export declare function insertSnippet(language: EditorLanguage, source: string, placements: readonly SnippetPlacement[], extra?: (name: string) => string | undefined): Promise<boolean>;

package/dist/snippet-insert.js

@@ -0,0 +1,217 @@
+import { SnippetTransformQueueError } from './snippet-transform-queue.js';
+import { comparePositions, shiftPosition } from './diagnostics-model.js';
+import { lineTextOf, textBeforeOf } from './line-text.js';
+import { wordRangeAt } from './rename-model.js';
+import { jobTable } from './snippet-field-transforms.js';
+import { indentSnippet } from './snippet-indent.js';
+import { positionInInsertion } from './snippet-session.js';
+import { SnippetTransformError } from './snippet-transform-client.js';
+import { MAX_TRANSFORM_JOBS, MAX_TRANSFORM_WORK } from './snippet-transform-protocol.js';
+import { compileSnippet, tabOrder } from './snippet.js';
+import { createSnippetResolver } from './snippet-variables.js';
+import { fileUriToPath } from '@adecore/lsp';
+/* The same limits as an inserted completion item. */
+const MAX_CHARACTERS = 2_000_000;
+const MAX_RANGES = 1_000;
+const TOAST_ID = 'language-completion';
+class LimitError extends Error {}
+/* Each line's leading tabs become the editor's own indentation unit. */
+export function bodyWithIndentUnit(body, unit) {
+  return unit === '\t' ? body : body.replace(/^\t+/gm, tabs => unit.repeat(tabs.length));
+}
+/* One level of the editor's indentation: spaces for a tab size, or a tab. */
+export function indentUnitOf(editor) {
+  const {
+    tabSize,
+    insertSpaces
+  } = editor.getIndentation();
+  return insertSpaces ? ' '.repeat(tabSize) : '\t';
+}
+/* The lines after the first without `base` in front of them, or without the shortest indentation among them. */
+export function dedentLines(text, base) {
+  const lines = text.split(/\r\n|\r|\n/).slice(1);
+  const indents = lines.filter(line => line.trim() !== '').map(line => /^[\t ]*/.exec(line)[0].length);
+  const removed = base?.length ?? (indents.length === 0 ? 0 : Math.min(...indents));
+  return removed === 0 ? text : text.replace(/(\r\n|\r|\n)([^\r\n]*)/g, (_match, lineBreak, line) => lineBreak + line.slice(Math.min(removed, /^[\t ]*/.exec(line)[0].length)));
+}
+function sizeOf(parsed) {
+  return (parsed.transforms?.length ?? 0) + (parsed.fields?.reduce((count, field) => count + field.ranges.length + (field.linked?.length ?? 0), 1) ?? parsed.stops.length);
+}
+/*
+ * Inserts a snippet at every placement, the last of them the primary one, and starts a session on its tab stops. The
+ * variables are resolved for each placement (`extra` first, then the host's and the built-in ones), the lines are indented
+ * to the text before the placement, and a running session takes the insertion as a nested one. False when nothing was inserted.
+ */
+export async function insertSnippet(language, source, placements, extra) {
+  const {
+    editor,
+    project,
+    uri,
+    snippets
+  } = language;
+  if (placements.length === 0 || editor.isReadOnly?.() === true) {
+    return false;
+  }
+  const template = compileSnippet(source);
+  const now = new Date();
+  const token = snippets.token;
+  const continuing = snippets.isActive;
+  let stale = false;
+  const off = editor.onTextChange(() => {
+    stale = true;
+  });
+  const current = () => !stale && snippets.token === token;
+  try {
+    let characters = 0;
+    let ranges = 0;
+    const drafts = placements.map((placement, index) => {
+      const line = lineTextOf(editor, placement.range.start.line);
+      const word = wordRangeAt(line, placement.range.start);
+      const resolver = createSnippetResolver({
+        uri,
+        languageId: language.languageId,
+        position: placement.range.start,
+        selection: placement.range,
+        selectedText: placement.selectedText ?? '',
+        currentLine: line,
+        currentWord: word === null ? '' : editor.textInRange(word),
+        cursorIndex: index,
+        cursorCount: placements.length,
+        folder: project.host.folder,
+        path: fileUriToPath(uri) ?? project.host.pathOfUri?.(uri) ?? undefined
+      }, project.host.resolveSnippetVariable?.bind(project.host), {
+        now
+      });
+      const resolve = name => extra?.(name) ?? resolver(name);
+      const raw = template.render(resolve, undefined, {
+        indentVariables: true
+      });
+      return {
+        placement,
+        resolve,
+        raw,
+        parsed: indentSnippet(raw, textBeforeOf(editor, placement.range.start))
+      };
+    });
+    for (const {
+      parsed
+    } of drafts) {
+      characters += parsed.text.length;
+      ranges += sizeOf(parsed);
+      if (parsed.limited === true || characters > MAX_CHARACTERS || ranges > MAX_RANGES) {
+        throw new LimitError();
+      }
+    }
+    await transformVariables(language, template, drafts, current);
+    if (!current()) {
+      return false;
+    }
+    const changes = drafts.map(draft => ({
+      range: draft.placement.range,
+      text: draft.parsed.text
+    }));
+    if (changes.reduce((total, change) => total + change.text.length, 0) > MAX_CHARACTERS) {
+      throw new LimitError();
+    }
+    // Insertions before one another move it, so each start is mapped through the changes in front of it.
+    const starts = changes.map(change => changes.filter(other => other !== change && comparePositions(other.range.end, change.range.start) <= 0).sort((left, right) => comparePositions(right.range.start, left.range.start)).reduce((place, other) => shiftPosition(place, other), change.range.start));
+    if (!(continuing ? snippets.applyEdits(changes, token) : editor.applyEdits(changes))) {
+      return false;
+    }
+    off();
+    place(language, drafts, starts, continuing && snippets.isActive && snippets.token === token);
+    editor.focus();
+    return true;
+  } catch (error) {
+    if (error instanceof LimitError || error instanceof SnippetTransformError && error.kind === 'range') {
+      project.host.notify?.({
+        id: TOAST_ID,
+        kind: 'error',
+        title: project.i18n.t('editor:language.completion.tooLarge')
+      });
+      return false;
+    }
+    if (error instanceof SnippetTransformQueueError) {
+      project.host.notify?.({
+        id: TOAST_ID,
+        kind: 'error',
+        title: project.i18n.t('editor:language.completion.transformBusy')
+      });
+      return false;
+    }
+    if (error instanceof SnippetTransformError) {
+      project.host.notify?.({
+        id: TOAST_ID,
+        kind: 'error',
+        title: project.i18n.t('editor:language.completion.transformFailed')
+      });
+      return false;
+    }
+    throw error;
+  } finally {
+    off();
+  }
+}
+/* Runs the transforms of variables through the worker, once for all placements, and renders them again with the answers. */
+async function transformVariables(language, template, drafts, current) {
+  const {
+    editor,
+    project,
+    snippets
+  } = language;
+  const {
+    jobs,
+    slotOf
+  } = jobTable();
+  const slots = drafts.map(draft => (draft.raw.transforms ?? []).map(range => slotOf({
+    ...range.transform,
+    value: draft.raw.text.slice(range.start, range.end)
+  })));
+  if (jobs.length === 0 || project.host.snippetTransformWorker === undefined) {
+    return;
+  }
+  if (jobs.length > MAX_TRANSFORM_JOBS || jobs.reduce((sum, job) => sum + job.value.length, 0) > MAX_TRANSFORM_WORK) {
+    throw new LimitError();
+  }
+  const values = await snippets.transformVariables(jobs, current);
+  if (values === null || !current()) {
+    return;
+  }
+  drafts.forEach((draft, index) => {
+    const raw = template.render(draft.resolve, slots[index].map(slot => values[slot]), {
+      indentVariables: true
+    });
+    const parsed = indentSnippet(raw, textBeforeOf(editor, draft.placement.range.start));
+    if (parsed.limited === true) {
+      throw new LimitError();
+    }
+    draft.raw = raw;
+    draft.parsed = parsed;
+  });
+}
+/* Starts the session on the tab stops, or puts the caret after the primary insertion when there are none. */
+function place(language, drafts, starts, nested) {
+  const {
+    editor,
+    snippets
+  } = language;
+  const primary = drafts.at(-1).parsed;
+  if (primary.stops.length > 0) {
+    snippets.beginInstances(drafts.map((draft, index) => ({
+      start: starts[index],
+      text: draft.parsed.text,
+      stops: tabOrder(draft.parsed),
+      fields: draft.parsed.fields
+    })), {
+      nested
+    });
+    return;
+  }
+  editor.setSelections(drafts.map((draft, index) => {
+    const end = positionInInsertion(starts[index], draft.parsed.text, draft.parsed.text.length);
+    return {
+      start: end,
+      end
+    };
+  }));
+}

package/dist/snippet.d.ts

@@ -28,11 +28,17 @@ export interface ParsedSnippet {
     })[];
 }
 export type SnippetVariableResolver = (name: string) => string | undefined;
+export interface SnippetRenderOptions {
+    readonly indentVariables?: boolean;
+}
 export interface SnippetTemplate {
     readonly source: string;
-    render(resolve?: SnippetVariableResolver, variableTransforms?: readonly string[]): ParsedSnippet;
+    render(resolve?: SnippetVariableResolver, variableTransforms?: readonly string[], options?: SnippetRenderOptions): ParsedSnippet;
 }
 export declare const MAX_SNIPPET_TEXT = 100000;
 export declare function compileSnippet(source: string): SnippetTemplate;
 export declare function parseSnippet(snippet: string, resolve?: SnippetVariableResolver): ParsedSnippet;
 export declare function tabOrder(parsed: ParsedSnippet): SnippetStop[];
+export declare function snippetVariables(source: string): ReadonlySet<string>;
+export declare function checkSnippet(source: string): string | null;
+export declare function escapeSnippetText(text: string): string;

package/dist/snippet.js

@@ -168,6 +168,11 @@ class SnippetParser {
     return values;
   }
 }
+/* The lines of a value after its first, behind the whitespace the last line of `before` starts with; blank lines stay blank. */
+function indentLines(value, before) {
+  const prefix = /^[\t ]*/.exec(before.slice(before.lastIndexOf('\n') + 1))[0];
+  return prefix === '' ? value : value.replace(/(\r\n|\r|\n)(?=[^\r\n])/g, `$1${prefix}`);
+}
 function renderSnippet(nodes, variableTransforms) {
   const definitions = new Map();
   const collect = nodes => {
@@ -216,7 +221,8 @@ function renderSnippet(nodes, variableTransforms) {
       const order = occurrence++;
       if (node.kind === 'text') {
         const start = text.length;
-        const value = node.transform === undefined || variableTransforms === undefined ? node.text : variableTransforms[transforms.length];
+        const given = node.transform === undefined || variableTransforms === undefined ? node.text : variableTransforms[transforms.length];
+        const value = node.indent === true && typeof given === 'string' ? indentLines(given, text) : given;
         if (typeof value !== 'string') {
           throw new RangeError('The variable transform count does not match the snippet.');
         }
@@ -352,7 +358,7 @@ function variableIndices(nodes) {
     return [name, highest];
   }));
 }
-function resolveVariables(nodes, indices, resolve) {
+function resolveVariables(nodes, indices, resolve, indentVariables = false) {
   const unknown = new Map();
   const values = new Map();
   const valueOf = name => {
@@ -408,10 +414,16 @@ function resolveVariables(nodes, indices, resolve) {
             transform: node.transform
           }];
         }
-        return value !== undefined && value !== '' ? [{
-          kind: 'text',
-          text: value
-        }] : normalize(node.body ?? [], visiting, depth + 1);
+        if (value !== undefined && value !== '') {
+          return [{
+            kind: 'text',
+            text: value,
+            ...(indentVariables ? {
+              indent: true
+            } : {})
+          }];
+        }
+        return normalize(node.body ?? [], visiting, depth + 1);
       }
       if (node.kind === 'field') {
         return [{
@@ -464,7 +476,7 @@ export function compileSnippet(source) {
   }
   return {
     source,
-    render: (resolve, variableTransforms) => {
+    render: (resolve, variableTransforms, options) => {
       if (nodes === null) {
         return {
           text: source,
@@ -473,7 +485,7 @@ export function compileSnippet(source) {
         };
       }
       try {
-        return renderSnippet(resolveVariables(nodes, indices, resolve), variableTransforms);
+        return renderSnippet(resolveVariables(nodes, indices, resolve, options?.indentVariables === true), variableTransforms);
       } catch (error) {
         if (!(error instanceof SnippetLimitError)) {
           throw error;
@@ -518,4 +530,49 @@ export function tabOrder(parsed) {
     start: parsed.text.length,
     end: parsed.text.length
   }];
+}
+/* The names of the variables a snippet uses, the editable ones that are no built-in too. A source that does not parse names none. */
+export function snippetVariables(source) {
+  const names = new Set();
+  const scan = nodes => {
+    for (const node of nodes) {
+      if (node.kind === 'variable') {
+        names.add(node.name);
+      }
+      if (node.kind !== 'text' && node.body !== undefined) {
+        scan(node.body);
+      }
+    }
+  };
+  if (source.length > MAX_SNIPPET_TEXT) {
+    return names;
+  }
+  try {
+    scan(new SnippetParser(source).parse());
+  } catch {
+    return new Set();
+  }
+  return names;
+}
+/* Why a snippet cannot be used, in English for a host to show, or null: it does not parse, or it is over the limits an insertion keeps. */
+export function checkSnippet(source) {
+  if (source.length > MAX_SNIPPET_TEXT) {
+    return `The text is longer than ${MAX_SNIPPET_TEXT} characters.`;
+  }
+  try {
+    new SnippetParser(source).parse();
+  } catch (error) {
+    if (error instanceof MalformedSnippetError) {
+      return 'A transform in the text is not valid.';
+    }
+    if (error instanceof SnippetLimitError) {
+      return 'The text has too many parts or is nested too deeply.';
+    }
+    throw error;
+  }
+  return compileSnippet(source).render().limited === true ? 'The text expands to more than a snippet can hold.' : null;
+}
+/* Escapes `\`, `$` and `}`, so the text reads back as itself in a snippet. */
+export function escapeSnippetText(text) {
+  return text.replace(/[\\$}]/g, '\\$&');
 }

package/dist/surround-constructs.d.ts

@@ -0,0 +1,10 @@
+import type { CommentSyntax } from '@adecore/editor';
+import type { TemplateLanguage } from './templates.ts';
+export interface Construct {
+    readonly id: string;
+    readonly label: string;
+    readonly body: string;
+}
+export declare function statementConstructs(families: readonly TemplateLanguage[]): readonly Construct[];
+export declare function expressionConstructs(families: readonly TemplateLanguage[]): readonly Construct[];
+export declare function regionConstructs(syntax: CommentSyntax): readonly Construct[];