@adecore/editor-core 0.43.0 → 0.44.1

package/dist/document.d.ts

@@ -3,6 +3,10 @@ import type { DocumentLine } from './rope.ts';
 import type { FindMatch, FindNextOptions, FindOptions } from './search.ts';
 import type { FoldingOptions, FoldingRange } from './structure.ts';
 import type { CommandOptions, Disposable, EditOptions, EditorCommand, EditorSnapshot, Position, Selection, TextEdit } from './types.ts';
+import { type TextPlace } from './text-places.ts';
+import { type PostfixOperand } from './postfix-operands.ts';
+import { type SurroundShape } from './surround-shape.ts';
+import { type UnwrapTarget } from './unwrap.ts';
 import { type TodoMatch, type TodoOptions } from './todo.ts';
 import { type WhitespaceCleanupOptions } from './whitespace-cleanup.ts';
 export type { DocumentLine, FindMatch, FindNextOptions, FindOptions, FoldingOptions, FoldingRange };
@@ -93,6 +97,7 @@ export declare class DocumentModel {
     typeText(text: string, options?: TypeTextOptions): boolean;
     private takeBackArrows;
     private completeArrows;
+    private completeTemplates;
     paste(text: string, options?: CommandOptions & {
         wholeLines?: boolean;
     }): boolean;
@@ -135,6 +140,10 @@ export declare class DocumentModel {
     private insertNewline;
     private startNewLineBefore;
     private editLines;
+    placeAt(offset: number, language: string): TextPlace;
+    postfixOperands(dot: number, language: string): PostfixOperand[];
+    surroundShape(from: number, to: number, language: string): SurroundShape | null;
+    unwrapTargets(offset: number, language: string, indentUnit: string): UnwrapTarget[];
     private editSource;
     private isUnclosedBrace;
     private scriptSource;

package/dist/document.js

@@ -14,7 +14,7 @@ import { blockFolds } from './block-folds.js';
 import { applyFoldHints, markFileHeader } from './fold-roles.js';
 import { lexicalFolds } from './lexical-folds.js';
 import { rangeOf, whitespaceOf } from './line-text.js';
-import { isQuote, replacesComparison, surround, swapQuotes } from './typing-handlers.js';
+import { isQuote, replacesComparison, surround, swapQuotes, templateLiteralEdits, templateString } from './typing-handlers.js';
 import { scanBrackets } from './brackets.js';
 import { BracketTracker } from './bracket-tracker.js';
 import { hasSmartSemicolon, isPhp } from './lexical.js';
@@ -22,6 +22,10 @@ import { clampInteger, TextRope, ROPE_CHUNK_SIZE } from './rope.js';
 import { findMatches, findMatchFrom, replacementText, splitsSurrogate } from './search.js';
 import { dedupeFoldingRanges, deriveFoldingRanges, indentationColumn, scanStructure, tabWidth } from './structure.js';
 import { TypingContexts } from './typing-context.js';
+import { placeAt } from './text-places.js';
+import { postfixOperands } from './postfix-operands.js';
+import { surroundShape } from './surround-shape.js';
+import { unwrapTargets } from './unwrap.js';
 import { todosInLines } from './todo.js';
 import { planConvertIndents, planLineOrder } from './line-order.js';
 import { ModifiedStretches, planWhitespaceCleanup } from './whitespace-cleanup.js';
@@ -54,6 +58,10 @@ function trailingBlankLength(text) {
 function changesText(rope, edit) {
     return edit.text.length !== edit.to - edit.from || rope.slice(edit.from, edit.to) !== edit.text;
 }
+/* Where an offset stands after edits that end at or before it moved it; an insertion at the offset pushes it on. */
+function shifted(edits, offset) {
+    return edits.reduce((moved, edit) => (edit.to <= offset ? moved + edit.text.length - (edit.to - edit.from) : moved), offset);
+}
 /* Merges the carets' edits into one simultaneous batch and works out where each caret lands in the result. */
 function selectionTransaction(plans) {
     const edits = [];
@@ -587,7 +595,8 @@ export class DocumentModel {
     /*
      * Types `text` at every caret as one keystroke would: it wraps a selection in a bracket or quote,
      * closes an opener, types over a closer that is already there and, in TypeScript, JavaScript and
-     * PHP, moves a `;` to the end of a statement. In PHP a `-` after a variable becomes `->`. Comments
+     * PHP, moves a `;` to the end of a statement. In PHP a `-` after a variable becomes `->`. In JavaScript and
+     * TypeScript a `{` that completes `${` in a quoted string makes it a template literal. Comments
      * and string contents are left alone. Returns whether anything changed, a swallowed closer included.
      */
     typeText(text, options = {}) {
@@ -613,6 +622,7 @@ export class DocumentModel {
             surround: options.surroundSelection !== false && single,
             smartSemicolon: options.smartSemicolon !== false && hasSmartSemicolon(language),
             smartArrow: options.smartArrow !== false && single && isPhp(language),
+            templateLiterals: options.templateLiterals !== false && text === '{',
             overArrows: text === '>' ? arrows : new Set(),
             dedent: options.smartEnter !== false
         };
@@ -626,6 +636,7 @@ export class DocumentModel {
             this.rememberStatementClosers(plans, transaction, language);
             this.rememberPairs(plans, transaction);
             this.completeArrows(plans, transaction);
+            this.completeTemplates(plans, transaction, language);
         }
         return changed || plans.some((plan) => plan.consumed);
     }
@@ -650,6 +661,23 @@ export class DocumentModel {
             this.arrows = new Set(at.map(moved));
         }
     }
+    /* Turns the quoted strings a `${` was typed in into template literals, as a step of their own so the first undo leaves the quotes back. */
+    completeTemplates(plans, transaction, language) {
+        // Carets in one string find the same quotes.
+        const strings = new Map();
+        for (const plan of plans) {
+            if (plan.template) {
+                strings.set(shifted(transaction.edits, plan.template.open), shifted(transaction.edits, plan.template.close));
+            }
+        }
+        const source = this.editSource(language);
+        const edits = [...strings].flatMap(([open, close]) => templateLiteralEdits(source, open, close));
+        if (edits.length > 0) {
+            // A caret right before a closing quote stays there, which the default mapping of an edit that replaces the quote would not do.
+            const selections = this.selections.map((selection) => ({ anchor: shifted(edits, selection.anchor), head: shifted(edits, selection.head) }));
+            this.applyEdits(edits, { source: 'input', selections });
+        }
+    }
     /*
      * Pastes `text` at every selection. With as many lines as carets each caret takes one; `wholeLines`
      * marks text copied from a bare caret, which goes above the lines of bare carets.
@@ -840,6 +868,12 @@ export class DocumentModel {
                 return wrapped;
             }
         }
+        if (input.templateLiterals && from === to) {
+            const template = templateString(this.editSource(language), from, language);
+            if (template) {
+                return { from, to, text: input.brackets ? '{}' : '{', anchor: 1, head: 1, paired: input.brackets, template };
+            }
+        }
         if (pairing && pairs[text] !== undefined && from === to && this.shouldClosePair(from, text, after, context, input)) {
             return { from, to, text: text + pairs[text], anchor: 1, head: 1, paired: true };
         }
@@ -1509,6 +1543,22 @@ export class DocumentModel {
             });
         return this.applyEdits(plan.edits, { source: 'command', selections });
     }
+    /* What the text at an offset is written in, with embedded regions resolved, and whether it is code, a comment or a string. */
+    placeAt(offset, language) {
+        return placeAt(this.editSource(language), offset, language);
+    }
+    /* Every expression that ends right before the `.` at `dot`, innermost first; empty where none does. */
+    postfixOperands(dot, language) {
+        return postfixOperands(this.editSource(language), dot, language);
+    }
+    /* What a range can be surrounded with: whole statements, one expression, both or neither. Null where the range is blank. */
+    surroundShape(from, to, language) {
+        return surroundShape(this.editSource(language), from, to, language);
+    }
+    /* What can be unwrapped or removed around an offset, innermost first, each with the edits that do it. */
+    unwrapTargets(offset, language, indentUnit) {
+        return unwrapTargets(this.editSource(language), offset, language, indentUnit);
+    }
     editSource(language) {
         return {
             lineCount: this.getLineCount(),

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export type { DocumentEditOptions, DocumentLine, OffsetRange, ReplaceAllOptions,
 export { scanBrackets, type BracketIndex, type BracketMatch } from './brackets.ts';
 export { findMatches, iterateMatches, findMatchFrom, replacementText, type FindMatch, type FindNextOptions, type FindOptions } from './search.ts';
 export { indentationColumn } from './structure.ts';
+export { commentSyntax, type CommentSyntax } from './languages.ts';
 export { findDocComments, MAX_DOC_COMMENTS, type DocComment } from './doc-comments.ts';
 export { DEFAULT_TODO_WORDS, findTodos, type TodoMatch, type TodoOptions } from './todo.ts';
 export { detectIndentation, type DetectedIndentation } from './line-order.ts';
@@ -10,3 +11,7 @@ export type { TrailingWhitespace, WhitespaceCleanupOptions } from './whitespace-
 export type { FoldHints, FoldRangeHint, FoldRole, FoldSymbolHint, FoldingOptions, FoldingRange } from './structure.ts';
 export type { ChangeSource, CommandOptions, ContentEdit, Disposable, DocumentChange, EditOptions, EditorCommand, EditorSnapshot, Position, Selection, TextEdit } from './types.ts';
 export { changedSpan, changedSpans, type TextSpan } from './text-span.ts';
+export type { TextPlace, TextPlaceKind } from './text-places.ts';
+export type { PostfixOperand } from './postfix-operands.ts';
+export type { SurroundShape } from './surround-shape.ts';
+export type { UnwrapKind, UnwrapTarget } from './unwrap.ts';

package/dist/index.js

@@ -2,6 +2,7 @@ export { DocumentModel } from './document.js';
 export { scanBrackets } from './brackets.js';
 export { findMatches, iterateMatches, findMatchFrom, replacementText } from './search.js';
 export { indentationColumn } from './structure.js';
+export { commentSyntax } from './languages.js';
 export { findDocComments, MAX_DOC_COMMENTS } from './doc-comments.js';
 export { DEFAULT_TODO_WORDS, findTodos } from './todo.js';
 export { detectIndentation } from './line-order.js';

package/dist/postfix-operands.d.ts

@@ -0,0 +1,6 @@
+import type { EditSource } from './edit-source.ts';
+export interface PostfixOperand {
+    readonly from: number;
+    readonly statement: boolean;
+}
+export declare function postfixOperands(source: EditSource, dot: number, language: string): PostfixOperand[];

package/dist/postfix-operands.js

@@ -0,0 +1,397 @@
+import { isPhp, isScript, isWordCharacter } from './lexical.js';
+import { atStatementStart } from './surround-shape.js';
+import { placeAt } from './text-places.js';
+import { skipTriviaBack } from './trivia.js';
+const TERNARY = 2;
+const LITERAL_LIMIT = 10_000;
+const MAX_OPERATOR_LENGTH = 4;
+const binary = (precedence, right = false) => ({ kind: 'binary', precedence, right });
+const stop = { kind: 'stop', precedence: 0, right: false };
+const SCRIPT_OPERATORS = new Map([
+    ['**', binary(15, true)],
+    ['*', binary(14)],
+    ['/', binary(14)],
+    ['%', binary(14)],
+    ['+', binary(13)],
+    ['-', binary(13)],
+    ['<<', binary(12)],
+    ['>>', binary(12)],
+    ['>>>', binary(12)],
+    ['<', binary(10)],
+    ['>', binary(10)],
+    ['<=', binary(10)],
+    ['>=', binary(10)],
+    ['==', binary(9)],
+    ['!=', binary(9)],
+    ['===', binary(9)],
+    ['!==', binary(9)],
+    ['&', binary(8)],
+    ['^', binary(7)],
+    ['|', binary(6)],
+    ['&&', binary(5)],
+    ['||', binary(4)],
+    ['??', binary(3, true)],
+    ['?:', binary(TERNARY, true)],
+    ['?', { kind: 'question', precedence: TERNARY, right: true }],
+    [':', { kind: 'colon', precedence: TERNARY, right: true }]
+]);
+// An assignment ends the operand, and they are listed so that `>>=` is not read as `>=`.
+for (const text of ['=', '=>', '+=', '-=', '*=', '/=', '%=', '&=', '|=', '^=', '**=', '<<=', '>>=', '>>>=', '&&=', '||=', '??=', '?.', '++', '--', '::']) {
+    SCRIPT_OPERATORS.set(text, stop);
+}
+const PHP_OPERATORS = new Map(SCRIPT_OPERATORS);
+PHP_OPERATORS.set('.', binary(11));
+PHP_OPERATORS.set('.=', stop);
+PHP_OPERATORS.set('<>', binary(10));
+PHP_OPERATORS.set('<=>', binary(9));
+PHP_OPERATORS.set('->', stop);
+PHP_OPERATORS.set('?->', stop);
+const SCRIPT_WORDS = new Map([
+    ['in', binary(10)],
+    ['instanceof', binary(10)]
+]);
+const PHP_WORDS = new Map([
+    ['instanceof', binary(10)],
+    ['and', binary(1.5)],
+    ['xor', binary(1.4)],
+    ['or', binary(1.3)]
+]);
+const UNARY_WORDS = new Set(['typeof', 'void', 'await', 'delete']);
+// Words that start a statement or a clause, so they are no operand and nothing to the left of them belongs to an expression.
+const KEYWORDS = new Set([
+    'return',
+    'throw',
+    'yield',
+    'case',
+    'default',
+    'const',
+    'let',
+    'var',
+    'echo',
+    'print',
+    'if',
+    'else',
+    'elseif',
+    'for',
+    'foreach',
+    'while',
+    'do',
+    'switch',
+    'try',
+    'catch',
+    'finally',
+    'function',
+    'class',
+    'import',
+    'export',
+    'of',
+    'as',
+    'use',
+    'new',
+    'extends',
+    'implements',
+    'global',
+    'include',
+    'require'
+]);
+const CAST = /^\s*(?:int|integer|bool|boolean|float|double|string|array|object|binary|unset)\s*$/i;
+function insideTemplate(context) {
+    for (let bracket = context.bracket; bracket !== undefined; bracket = bracket.previous) {
+        if (bracket.template === true) {
+            return true;
+        }
+    }
+    return false;
+}
+class Scanner {
+    source;
+    php;
+    typescript;
+    operators;
+    words;
+    constructor(source, place) {
+        this.source = source;
+        this.php = isPhp(place);
+        this.typescript = /^(?:typescript|ts|tsx|typescriptreact|mts|cts)$/i.test(place);
+        this.operators = this.php ? PHP_OPERATORS : SCRIPT_OPERATORS;
+        this.words = this.php ? PHP_WORDS : SCRIPT_WORDS;
+    }
+    skip(end) {
+        return skipTriviaBack(this.source, end);
+    }
+    wordStart(end) {
+        let from = end;
+        while (from > 0 && isWordCharacter(this.source.charAt(from - 1))) {
+            from--;
+        }
+        return from;
+    }
+    /* The start of the string, template or regex literal that ends at `end`. */
+    literalStart(end) {
+        const closing = this.source.context(end - 1);
+        if (closing.mode === 'code' && !insideTemplate(closing)) {
+            return null;
+        }
+        for (let at = end - 2; at >= 0 && end - at <= LITERAL_LIMIT; at--) {
+            const context = this.source.context(at);
+            if (context.mode === 'code' && !insideTemplate(context)) {
+                return at;
+            }
+        }
+        return null;
+    }
+    /* The word, group or literal that ends at `end`. A block, the parenthesis of a control statement and a stray character are none. */
+    atom(end) {
+        const { source } = this;
+        if (end <= 0) {
+            return null;
+        }
+        const char = source.charAt(end - 1);
+        if (isWordCharacter(char)) {
+            const from = this.wordStart(end);
+            const word = source.slice(from, end);
+            if (from > 0 && source.charAt(from - 1) === '/' && source.context(from - 1).mode === 'regex' && /^[a-z]+$/i.test(word)) {
+                const start = this.literalStart(from);
+                return start === null ? null : { from: start };
+            }
+            return { from, word };
+        }
+        if (char === '"' || char === "'" || char === '`' || char === '/') {
+            const start = this.literalStart(end);
+            return start === null ? null : { from: start };
+        }
+        if (char === ')' || char === ']' || char === '}') {
+            const context = source.context(end - 1);
+            const bracket = context.bracket;
+            if (context.mode !== 'code' || bracket === undefined || bracket.close !== char || bracket.control === true || bracket.template === true) {
+                return null;
+            }
+            return char === '}' && bracket.block === true ? null : { from: bracket.at, group: source.charAt(bracket.at) };
+        }
+        return null;
+    }
+    reserved(atom) {
+        return atom.word !== undefined && (KEYWORDS.has(atom.word) || UNARY_WORDS.has(atom.word) || this.words.has(atom.word));
+    }
+    /* An atom with the calls and indexes right behind it, down to its callee. */
+    unit(end, property = false) {
+        const { source } = this;
+        let at = end;
+        // The non-null assertion of TypeScript, as long as it is not the start of `!=`.
+        while (this.typescript && source.charAt(at - 1) === '!' && source.charAt(at) !== '=' && /[\p{L}\p{N}_$)\]]/u.test(source.charAt(at - 2))) {
+            at--;
+        }
+        let atom = this.atom(at);
+        // A keyword is a fine property name.
+        if (atom === null || (!property && this.reserved(atom))) {
+            return null;
+        }
+        let start = atom.from;
+        while (atom.group === '(' || atom.group === '[') {
+            const callee = this.atom(start);
+            if (callee === null || this.reserved(callee)) {
+                break;
+            }
+            start = callee.from;
+            atom = callee;
+        }
+        return start;
+    }
+    /* The length of the member operator that ends at `end`. */
+    member(end) {
+        const text = this.source.slice(Math.max(0, end - 3), end);
+        if (this.php) {
+            if (text.endsWith('?->')) {
+                return 3;
+            }
+            return text.endsWith('->') || text.endsWith('::') ? 2 : Number(text.endsWith('\\'));
+        }
+        if (text === '...') {
+            return 0;
+        }
+        return text.endsWith('?.') ? 2 : Number(text.endsWith('.'));
+    }
+    /* The start of the chain of members, calls and indexes that ends at `end`. */
+    chain(end) {
+        const first = this.unit(end);
+        if (first === null) {
+            return null;
+        }
+        let start = first;
+        for (;;) {
+            const before = this.skip(start);
+            const length = this.member(before);
+            if (length === 0) {
+                break;
+            }
+            // A namespace separator sits between its names without whitespace.
+            const separator = this.php && this.source.charAt(before - 1) === '\\';
+            const next = separator && before !== start ? null : this.unit(separator ? before - length : this.skip(before - length), true);
+            if (next === null) {
+                // A namespace may start with a backslash of its own.
+                if (this.source.charAt(before - 1) === '\\') {
+                    start = before - 1;
+                }
+                break;
+            }
+            start = next;
+        }
+        const before = this.skip(start);
+        const word = this.atom(before)?.word;
+        return word === 'new' ? before - 3 : start;
+    }
+    /* Whether the `.` after the operand is the decimal point of a number. */
+    decimalPoint(dot) {
+        const last = this.atom(dot);
+        return !this.php && last?.word !== undefined && /^\d/.test(last.word) && this.source.charAt(last.from - 1) !== '.';
+    }
+    operandEnd(end) {
+        const atom = this.atom(end);
+        return atom !== null && !this.reserved(atom);
+    }
+    /* The start of the prefix operator right before `end`, or -1. */
+    unaryBefore(end) {
+        const { source } = this;
+        const char = source.charAt(end - 1);
+        if (char === '!' || char === '~' || (this.php && char === '@')) {
+            return end - 1;
+        }
+        if (char === '-' || char === '+') {
+            const start = source.charAt(end - 2) === char ? end - 2 : end - 1;
+            return this.operandEnd(this.skip(start)) ? -1 : start;
+        }
+        const word = this.atom(end);
+        if (word?.word !== undefined) {
+            return UNARY_WORDS.has(word.word) ? word.from : -1;
+        }
+        if (this.php && word?.group === '(' && CAST.test(this.source.slice(word.from + 1, end - 1))) {
+            return word.from;
+        }
+        return -1;
+    }
+    /* Moves left over the prefix operators of an operand, reporting each start. */
+    unaries(start, report) {
+        let from = start;
+        for (;;) {
+            const found = this.unaryBefore(this.skip(from));
+            if (found < 0) {
+                return from;
+            }
+            from = found;
+            report?.(from);
+        }
+    }
+    operand(end) {
+        const start = this.chain(end);
+        return start === null ? null : this.unaries(start);
+    }
+    operatorEndingAt(end) {
+        const word = this.atom(end);
+        if (word?.word !== undefined) {
+            const operator = this.words.get(word.word);
+            return operator === undefined ? null : { text: word.word, operator };
+        }
+        for (let length = MAX_OPERATOR_LENGTH; length > 0; length--) {
+            const text = this.source.slice(Math.max(0, end - length), end);
+            const operator = this.operators.get(text);
+            if (text.length === length && operator !== undefined) {
+                return { text, operator };
+            }
+        }
+        return null;
+    }
+    /* The binary operator left of an expression that starts at `from`. */
+    operatorBefore(from) {
+        const end = this.skip(from);
+        const found = end === 0 ? null : this.operatorEndingAt(end);
+        if (found === null || (found.operator.kind !== 'binary' && found.operator.kind !== 'colon')) {
+            return null;
+        }
+        return { ...found.operator, start: end - found.text.length };
+    }
+    /* Whether a line break stands right before `index`, which ends the line of what is left of it. */
+    breaksBefore(index) {
+        return /[\n\r]/.test(this.source.slice(this.skip(index), index));
+    }
+    /* The `?` that belongs to the `:` at `colon`, past the ternaries nested between them. */
+    questionBefore(colon) {
+        let depth = 0;
+        let at = colon;
+        for (;;) {
+            at = this.skip(at);
+            if (at === 0) {
+                return null;
+            }
+            const atom = this.atom(at);
+            if (atom !== null) {
+                if (atom.word !== undefined && KEYWORDS.has(atom.word)) {
+                    return null;
+                }
+                at = atom.from;
+                continue;
+            }
+            const found = this.operatorEndingAt(at);
+            if (found === null || found.operator.kind === 'stop') {
+                return null;
+            }
+            if (found.operator.kind === 'question') {
+                if (depth === 0) {
+                    return at - 1;
+                }
+                depth--;
+            }
+            else if (found.operator.kind === 'colon') {
+                depth++;
+            }
+            at -= found.text.length;
+        }
+    }
+}
+/* Every expression that ends right before the `.` at `dot`, innermost first; empty where none does. */
+export function postfixOperands(source, dot, language) {
+    if (source.charAt(dot) !== '.') {
+        return [];
+    }
+    const place = placeAt(source, dot, language);
+    if (place.kind !== 'code' || !(isScript(place.language) || isPhp(place.language))) {
+        return [];
+    }
+    const scanner = new Scanner(source, place.language);
+    const end = scanner.skip(dot);
+    const start = end === 0 || scanner.decimalPoint(dot) ? null : scanner.chain(end);
+    if (start === null) {
+        return [];
+    }
+    const found = [start];
+    const report = (from) => {
+        if (from < found.at(-1)) {
+            found.push(from);
+        }
+    };
+    let from = scanner.unaries(start, report);
+    let minimum = Infinity;
+    for (;;) {
+        const operator = scanner.operatorBefore(from);
+        if (operator === null) {
+            break;
+        }
+        const operatorStart = operator.kind === 'colon' ? scanner.questionBefore(operator.start) : operator.start;
+        // A line has to end in the operator for the expression to go on over it.
+        if (operatorStart === null || scanner.breaksBefore(operatorStart)) {
+            break;
+        }
+        const left = scanner.operand(scanner.skip(operatorStart));
+        if (left === null) {
+            break;
+        }
+        from = left;
+        minimum = Math.min(minimum, operator.precedence);
+        // The expression is a subtree only when the operator on its left binds looser than everything inside it.
+        const next = scanner.operatorBefore(from);
+        if (next === null || scanner.breaksBefore(next.start) || next.precedence < minimum || (next.right && next.precedence <= minimum)) {
+            report(from);
+        }
+    }
+    const widest = found.length - 1;
+    return found.map((operandFrom, index) => ({ from: operandFrom, statement: index === widest && atStatementStart(source, operandFrom, language) }));
+}

package/dist/surround-shape.d.ts

@@ -0,0 +1,9 @@
+import type { EditSource } from './edit-source.ts';
+export interface SurroundShape {
+    readonly from: number;
+    readonly to: number;
+    readonly statements: boolean;
+    readonly expression: boolean;
+}
+export declare function atStatementStart(source: EditSource, offset: number, language: string): boolean;
+export declare function surroundShape(source: EditSource, from: number, to: number, language: string): SurroundShape | null;