surround fixup: switch for default mappings, update doc.

Author: sql-koala

README.md

@@ -511,6 +511,14 @@ Some examples:
 - `"test"` with cursor inside quotes type `ds"` to end up with `test`
 - `"test"` with cursor inside quotes type `cs"t` and enter `123>` to end up with `<123>test</123>`
 
+Surround mappings:
+since 1.20, we internally use special key notation for surround ( `<plugys>`, `<plugcs>`, `<plugds>` ), for which we create default mappings. This has two consequences:
+
+- custom mappings need to use these too.\
+  Example: `nnoremap s" <plugys>iw"`
+- the default mappings will not fit for users of custom keyboard layouts (workman, etc.).
+  They need to disable them using `vim.disableDefaultPluginMappings`
+
 ### vim-commentary
 
 Similar to [vim-commentary](https://github.com/tpope/vim-commentary), but uses the VS Code native _Toggle Line Comment_ and _Toggle Block Comment_ features.

src/actions/plugins/pluginDefaultMappings.ts

@@ -28,11 +28,30 @@ export class PluginDefaultMappings {
       configSwitch: 'surround',
       mapping: { before: ['d', 's'], after: ['<plugds>'] },
     },
+    // support some special cases with mappings
+    // see: https://github.com/tpope/vim-surround/blob/master/doc/surround.txt, TARGETS w,W,s
+    {
+      mode: 'normalModeKeyBindingsNonRecursive',
+      configSwitch: 'surround',
+      mapping: { before: ['c', 's', 'w'], after: ['<plugys>', 'i', 'w'] },
+    },
+    {
+      mode: 'normalModeKeyBindingsNonRecursive',
+      configSwitch: 'surround',
+      mapping: { before: ['c', 's', 'W'], after: ['<plugys>', 'i', 'W'] },
+    },
+    {
+      mode: 'normalModeKeyBindingsNonRecursive',
+      configSwitch: 'surround',
+      mapping: { before: ['c', 's', 's'], after: ['<plugys>', 'i', 's'] },
+    },
   ];
 
   public static getPluginDefaultMappings(mode: string, config: IConfiguration): IKeyRemapping[] {
-    return this.defaultMappings
-      .filter((m) => m.mode === mode && config[m.configSwitch])
-      .map((m) => m.mapping);
+    return config.disableDefaultPluginMappings
+      ? []
+      : this.defaultMappings
+          .filter((m) => m.mode === mode && config[m.configSwitch])
+          .map((m) => m.mapping);
   }
 }

src/configuration/configuration.ts

@@ -240,6 +240,8 @@ class Configuration implements IConfiguration {
 
   surround = true;
 
+  disableDefaultPluginMappings = false;
+
   argumentObjectSeparators = [','];
   argumentObjectOpeningDelimiters = ['(', '['];
   argumentObjectClosingDelimiters = [')', ']'];

src/configuration/iconfiguration.ts

@@ -166,6 +166,11 @@ export interface IConfiguration {
    */
   surround: boolean;
 
+  /**
+   * Do not create default mappings for surround plugin
+   */
+  disableDefaultPluginMappings: boolean;
+
   /**
    * Customize argument textobject delimiter and separator characters
    */

test/testConfiguration.ts

@@ -27,6 +27,7 @@ export class Configuration implements IConfiguration {
   sneakUseIgnorecaseAndSmartcase = false;
   sneakReplacesF = false;
   surround = false;
+  disableDefaultPluginMappings = false;
   argumentObjectSeparators = [','];
   argumentObjectOpeningDelimiters = ['(', '['];
   argumentObjectClosingDelimiters = [')', ']'];