@adecore/editor-react 0.42.0 → 0.44.0

package/src/snippet-session.ts

@@ -5,7 +5,7 @@ import { acquireSnippetTransforms, type SnippetTransformLease } from './snippet-
 import { realTimers, type Timers } from './timers.ts';
 import { KEY_PRIORITY } from './key-priority.ts';
 import { MAX_TRANSFORM_CHARACTERS, type SnippetTransformJob } from './snippet-transform-protocol.ts';
-import type { EditorContentChange, EditorPosition, EditorRange, EditorTextChange } from '@adecore/editor';
+import type { EditorApplyEditsOptions, EditorContentChange, EditorPosition, EditorRange, EditorTextChange } from '@adecore/editor';
 import { comparePositions, endOfInsertion, rangeHolds, sameRange, shiftPosition } from './diagnostics-model.ts';
 import type { EditorLanguage } from './editor-language.ts';
 import { textBeforeOf } from './line-text.ts';
@@ -367,7 +367,12 @@ export class SnippetFeature {
     }
 
     /* Imports can touch a hull's edge; their affinity must differ from edits inside its active field. */
-    applyEdits(changes: readonly EditorContentChange[], token: number, extras: readonly EditorContentChange[] = []): boolean {
+    applyEdits(
+        changes: readonly EditorContentChange[],
+        token: number,
+        extras: readonly EditorContentChange[] = [],
+        options?: EditorApplyEditsOptions
+    ): boolean {
         const frame = this.frames.at(-1);
 
         const fits =
@@ -385,14 +390,14 @@ export class SnippetFeature {
         if (token !== this.generation || !fits) {
             this.end();
 
-            return this.language.editor.applyEdits(changes);
+            return this.language.editor.applyEdits(changes, options);
         }
 
         this.applying = true;
         this.extras = extras;
 
         try {
-            return this.language.editor.applyEdits(changes);
+            return this.language.editor.applyEdits(changes, options);
         } finally {
             this.applying = false;
             this.extras = [];

package/src/snippet.ts

@@ -40,15 +40,21 @@ export interface ParsedSnippet {
 }
 
 type Node =
-    | { kind: 'text'; text: string; transform?: SnippetTransform }
+    // `indent` marks the value of a variable whose lines after the first take the indentation of the line it starts on.
+    | { kind: 'text'; text: string; transform?: SnippetTransform; indent?: true }
     | { kind: 'field'; index: number; body?: Node[]; choices?: string[]; transform?: SnippetTransform }
     | { kind: 'variable'; name: string; body?: Node[]; transform?: SnippetTransform };
 
 export type SnippetVariableResolver = (name: string) => string | undefined;
 
+export interface SnippetRenderOptions {
+    /* The way VS Code treats `TM_SELECTED_TEXT`: the lines of a value after its first take the leading whitespace of the output line the variable starts on. */
+    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;
 }
 
 type FieldNode = Extract<Node, { kind: 'field' }>;
@@ -235,6 +241,13 @@ class SnippetParser {
     }
 }
 
+/* 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: string, before: string): string {
+    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: readonly Node[], variableTransforms?: readonly string[]): ParsedSnippet {
     const definitions = new Map<number, FieldNode>();
 
@@ -304,7 +317,8 @@ function renderSnippet(nodes: readonly Node[], variableTransforms?: readonly str
 
             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.');
@@ -453,7 +467,7 @@ function variableIndices(nodes: readonly Node[]): ReadonlyMap<string, number> {
     );
 }
 
-function resolveVariables(nodes: readonly Node[], indices: ReadonlyMap<string, number>, resolve?: SnippetVariableResolver): Node[] {
+function resolveVariables(nodes: readonly Node[], indices: ReadonlyMap<string, number>, resolve?: SnippetVariableResolver, indentVariables = false): Node[] {
     const unknown = new Map<string, { index: number; body: Node[]; defaulted: boolean; definition: Node }>();
     const values = new Map<string, string | undefined>();
 
@@ -513,7 +527,11 @@ function resolveVariables(nodes: readonly Node[], indices: ReadonlyMap<string, n
                     return [{ kind: 'text', text: value ?? '', 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 as const } : {}) }];
+                }
+
+                return normalize(node.body ?? [], visiting, depth + 1);
             }
 
             if (node.kind === 'field') {
@@ -565,13 +583,13 @@ export function compileSnippet(source: string): SnippetTemplate {
 
     return {
         source,
-        render: (resolve, variableTransforms) => {
+        render: (resolve, variableTransforms, options) => {
             if (nodes === null) {
                 return { text: source, stops: [], limited: true };
             }
 
             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;
@@ -615,3 +633,60 @@ export function tabOrder(parsed: ParsedSnippet): SnippetStop[] {
 
     return [...visited, first.get(0) ?? { index: 0, 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: string): ReadonlySet<string> {
+    const names = new Set<string>();
+
+    const scan = (nodes: readonly Node[]): void => {
+        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: string): string | null {
+    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: string): string {
+    return text.replace(/[\\$}]/g, '\\$&');
+}

package/src/surround-constructs.ts

@@ -0,0 +1,85 @@
+import type { CommentSyntax } from '@adecore/editor';
+import { escapeSnippetText } from './snippet.ts';
+import type { TemplateLanguage } from './templates.ts';
+
+/* A row of Surround With that wraps the selection in a snippet. */
+export interface Construct {
+    readonly id: string;
+
+    /* Code, so it is not translated. */
+    readonly label: string;
+
+    /* Snippet syntax; a tab is one indentation unit. */
+    readonly body: string;
+}
+
+const SELECTED = '$TM_SELECTED_TEXT';
+
+function block(head: string, tail = ''): string {
+    return `${head} {\n\t${SELECTED}\n}${tail}`;
+}
+
+const JS_STATEMENTS: readonly Construct[] = [
+    { id: 'if', label: 'if', body: block('if ($1)') },
+    { id: 'ifElse', label: 'if / else', body: block('if ($1)', ' else {\n\t$2\n}') },
+    { id: 'while', label: 'while', body: block('while ($1)') },
+    { id: 'doWhile', label: 'do / while', body: `do {\n\t${SELECTED}\n} while ($1);` },
+    { id: 'for', label: 'for', body: block('for (let ${1:i} = 0; $1 < $2; $1++)') },
+    { id: 'tryCatch', label: 'try / catch', body: block('try', ' catch (${1:e}) {\n\t$0\n}') },
+    { id: 'tryFinally', label: 'try / finally', body: block('try', ' finally {\n\t$0\n}') },
+    { id: 'tryCatchFinally', label: 'try / catch / finally', body: block('try', ' catch (${1:e}) {\n\t$2\n} finally {\n\t$0\n}') },
+    { id: 'braces', label: '{ }', body: `{\n\t${SELECTED}\n}` },
+    { id: 'function', label: 'function', body: block('function ${1:name}()') }
+];
+
+const PHP_STATEMENTS: readonly Construct[] = [
+    JS_STATEMENTS[0]!,
+    JS_STATEMENTS[1]!,
+    JS_STATEMENTS[2]!,
+    JS_STATEMENTS[3]!,
+    { id: 'for', label: 'for', body: block('for (\\$${1:i} = 0; \\$$1 < $2; \\$$1++)') },
+    { id: 'foreach', label: 'foreach', body: block('foreach (\\$${1:array} as \\$${2:value})') },
+    { id: 'tryCatch', label: 'try / catch', body: block('try', ' catch (${1:\\\\Exception} \\$${2:e}) {\n\t$0\n}') },
+    JS_STATEMENTS[6]!,
+    JS_STATEMENTS[7]!,
+    JS_STATEMENTS[9]!
+];
+
+const EXPRESSIONS: readonly Construct[] = [
+    { id: 'parentheses', label: '(expr)', body: `(${SELECTED})` },
+    { id: 'not', label: '!(expr)', body: `!(${SELECTED})` }
+];
+
+/* The statement surrounders of the first of the families that has any; JavaScript and TypeScript share theirs. */
+export function statementConstructs(families: readonly TemplateLanguage[]): readonly Construct[] {
+    if (families.includes('javascript')) {
+        return JS_STATEMENTS;
+    }
+
+    return families.includes('php') ? PHP_STATEMENTS : [];
+}
+
+/* The surrounders of one expression, which JavaScript, TypeScript and PHP share. */
+export function expressionConstructs(families: readonly TemplateLanguage[]): readonly Construct[] {
+    return families.includes('javascript') || families.includes('php') ? EXPRESSIONS : [];
+}
+
+/*
+ * The two comment pairs that fold a region, written with the language's own comments: the line comment, or the block
+ * pair where there is none. There is no space after the marker, so the output reads `//region Description`.
+ */
+export function regionConstructs(syntax: CommentSyntax): readonly Construct[] {
+    const marker = syntax.line ?? syntax.block?.open;
+
+    if (marker === undefined) {
+        return [];
+    }
+
+    const start = escapeSnippetText(marker);
+    const end = syntax.line === null ? escapeSnippetText(syntax.block?.close ?? '') : '';
+
+    return [
+        { id: 'region', label: 'region...endregion', body: `${start}region \${1:Description}${end}\n${SELECTED}\n${start}endregion${end}` },
+        { id: 'editorFold', label: '<editor-fold...>', body: `${start}<editor-fold desc="\${1:Description}">${end}\n${SELECTED}\n${start}</editor-fold>${end}` }
+    ];
+}