feat: Client-side on-type formatting support

docs/LSPApi.md

@@ -383,13 +383,21 @@ public class MyLSPDocumentSymbolFeature extends LSPDocumentSymbolFeature {
 
 ## LSP Formatting Feature
 
-| API                                                   | Description                                                                                                                                                                                                                        | Default Behaviour           |
-|-------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|
-| boolean isEnabled(PsiFile file)                       | Returns `true` if the LSP feature is enabled for the given file and `false` otherwise.                                                                                                                                             | `true`                      |
-| boolean isSupported(PsiFile file)                     | Returns `true` if the LSP feature is supported for the given file and `false` otherwise. <br/>This supported state is called after starting the language server, which matches the file and user with the LSP server capabilities. | Check the server capability |
-| boolean isRangeFormattingSupported(PsiFile file)      | Returns `true` if the range formatting is supported for the given file and `false` otherwise.                                                                                                                                      | Check the server capability |
-| boolean isExistingFormatterOverrideable(PsiFile file) | Returns `true` if existing formatters are overrideable and `false` otherwise.                                                                                                                                                      | `false`                     |
-| boolean isOnTypeFormattingEnabled(PsiFile file)       | Whether or not server-side on-type formatting is enabled if `textDocument/onTypeFormatting` is supported by the server.                                                                                                            | `true`                      |
+| API                                                            | Description                                                                                                                                                                                                                        | Default Behaviour                                      |
+|----------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------|
+| boolean isEnabled(PsiFile file)                                | Returns `true` if the LSP feature is enabled for the given file and `false` otherwise.                                                                                                                                             | `true`                                                 |
+| boolean isSupported(PsiFile file)                              | Returns `true` if the LSP feature is supported for the given file and `false` otherwise. <br/>This supported state is called after starting the language server, which matches the file and user with the LSP server capabilities. | Check the server capability                            |
+| boolean isRangeFormattingSupported(PsiFile file)               | Returns `true` if the range formatting is supported for the given file and `false` otherwise.                                                                                                                                      | Check the server capability                            |
+| boolean isExistingFormatterOverrideable(PsiFile file)          | Returns `true` if existing formatters are overrideable and `false` otherwise.                                                                                                                                                      | `false`                                                |
+| boolean isOnTypeFormattingEnabled(PsiFile file)                | Whether or not server-side on-type formatting is enabled if `textDocument/onTypeFormatting` is supported by the server.                                                                                                            | `true`                                                 |
+| boolean isFormatOnCloseBrace(PsiFile file)                     | Whether or not to format the file when close braces are typed.                                                                                                                                                                     | `false`                                                |
+| boolean getFormatOnCloseBraceCharacters(PsiFile file)          | The specific close brace characters that should trigger on-type formatting in the file.                                                                                                                                            | The language's standard close brace characters.        |
+| boolean getFormatOnCloseBraceScope(PsiFile file)               | The scope that should be formatted when a close brace is typed. Allowed values are `CODE_BLOCK` and `FILE`.                                                                                                                        | `CODE_BLOCK`                                           |
+| boolean isFormatOnStatementTerminator(PsiFile file)            | Whether or not to format the file when statement terminators are typed.                                                                                                                                                            | `false`                                                |
+| boolean getFormatOnStatementTerminatorCharacters(PsiFile file) | The specific statement terminator characters that should trigger on-type formatting in the file.                                                                                                                                   | None.                                                  |
+| boolean getFormatOnStatementTerminatorScope(PsiFile file)      | The scope that should be formatted when a statement terminator is typed. Allowed values are `STATEMENT`, `CODE_BLOCK` and `FILE`.                                                                                                  | `STATEMENT`                                            |
+| boolean isFormatOnCompletionTrigger(PsiFile file)              | Whether or not to format the file when completion triggers are typed.                                                                                                                                                              | `false`                                                |
+| boolean getFormatOnCompletionTriggerCharacters(PsiFile file)   | The specific completion trigger characters that should trigger on-type formatting in the file.                                                                                                                                     | The language's standard completion trigger characters. |
 
 Here is an example of code that allows executing the LSP formatter even if there is a specific formatter registered by an IntelliJ plugin:
 

docs/LSPSupport.md

@@ -458,6 +458,67 @@ Here is an example with the [Java Language Server](https://github.com/eclipse-jd
 
 ![textDocument/onTypeFormatting](./images/lsp-support/textDocument_onTypeFormatting.gif)
 
+If desired — for example, for those who want to control when formatting is performed — server-side/LSP-based
+on-type formatting can be disabled via client configuration as follows:
+
+```json
+{
+  "format": {
+    "onTypeFormatting": {
+      "serverSide": {
+        "enabled": false
+      }
+    }
+  }
+}
+```
+
+#### Client-side On-Type Formatting
+
+Not all language servers support the `textDocument/onTypeFormatting` feature. To provide an improved editor experience
+for users of those that do not, LSP4IJ includes support for _client-side on-type formatting_. Client-side on-type
+formatting can be enabled via client configuration with the following settings:
+
+* `format.onTypeFormatting.clientSide.formatOnCloseBrace` - When set to `true`, formatting is automatically applied when a close brace character is typed. Defaults to `false`.
+* `format.onTypeFormatting.clientSide.formatOnCloseBraceCharacters` - Specifies the exact characters that should treated as a close brace character for purposes of client-side on-type formatting. Defaults to the close brace characters for the language, typically `}`, `]`, and `)`.
+* `format.onTypeFormatting.clientSide.formatOnCloseBraceScope` - Specifies the scope that should be formatted when a close brace is typed. Valid values are `CODE_BLOCK` and `FILE`. Defaults to `CODE_BLOCK`. `FILE` is most useful for language servers that do not support range formatting or yield incorrect results for range formatting.
+* `format.onTypeFormatting.clientSide.formatOnStatementTerminator` - When set to `true`, formatting is automatically applied when a statement terminator character is typed. Defaults to `false`.
+* `format.onTypeFormatting.clientSide.formatOnStatementTerminatorCharacters` - Specifies the exact characters that should treated as a statement terminator character for purposes of client-side on-type formatting. Defaults to empty and must be specified if `formatOnStatementTerminator` is enabled.
+* `format.onTypeFormatting.clientSide.formatOnStatementTerminatorScope` - Specifies the scope that should be formatted when a statement terminator is typed. Valid values are `STATEMENT`, `CODE_BLOCK` and `FILE`. Defaults to `STATEMENT`. The other values are most useful for language servers that do not support range formatting or yield incorrect results for range formatting.
+* `format.onTypeFormatting.clientSide.formatOnCompletionTrigger` - When set to `true`, formatting is automatically applied when a completion trigger character is typed. Defaults to `false`.
+* `format.onTypeFormatting.clientSide.formatOnCompletionTriggerCharacters` - Specifies the exact characters that should treated as a completion trigger character for purposes of client-side on-type formatting. Defaults to the completion trigger characters specified by the language server.
+* Note that there is no configurable scope for completion trigger-based formatting. Exactly the type completion trigger character is formatted. As above, support for this may vary by language server.
+
+For example, the [TypeScript Language Server](./user-defined-ls/typescript-language-server.md) does not support server-side on-type formatting, but client-side
+on-type formatting is included in its language server configuration template as:
+
+```json
+{
+  "format": {
+    "onTypeFormatting": {
+      "clientSide": {
+        "formatOnCloseBrace": true,
+        "formatOnStatementTerminator": true,
+        "formatOnStatementTerminatorCharacters": ";",
+        "formatOnCompletionTrigger": true
+      }
+    }
+  }
+}
+```
+
+Here is an example for client-side on-type formatting with that configuration showing automatic indentation of a
+statement continuation when the completion trigger character `.` is typed and automatic formatting of an entire code
+block when the closing brace character `}` is typed for a surrounding conditional statement:
+
+![Client-side on-type formatting](./images/lsp-support/clientSideOnTypeFormatting.gif)
+
+#### Server-side / Client-side On-Type Formatting Relationship
+
+If server-side on-type formatting is supported by the language server and enabled _and_ client-side on-type formatting
+is enabled for specific trigger characters, _only client-side on-type formatting will be applied_ when those specific
+trigger characters are typed.
+
 ### Show Message
 
 [window/showMessage](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#window_showMessage) supports Markdown messages and clickable links.

src/main/java/com/redhat/devtools/lsp4ij/client/features/LSPFormattingFeature.java

@@ -135,7 +135,7 @@ public void setServerCapabilities(@Nullable ServerCapabilities serverCapabilitie
         }
     }
 
-    // Client configuration settings
+    // Server-side on-type formatting
 
     /**
      * Whether or not server-side on-type formatting is enabled if <code>textDocument/onTypeFormatting</code> is
@@ -148,4 +148,123 @@ public boolean isOnTypeFormattingEnabled(@NotNull PsiFile file) {
         // Default to enabled
         return true;
     }
+
+    // Client-side on-type formatting
+
+    /**
+     * Supported formatting scopes.
+     */
+    public enum FormattingScope {
+        /**
+         * The current statement if one can be identified.
+         */
+        STATEMENT,
+        /**
+         * The current code block if one can be identified.
+         */
+        CODE_BLOCK,
+        /**
+         * The current file.
+         */
+        FILE
+    }
+
+    /**
+     * Whether or not to format on close brace using client-side on-type formatting. Defaults to false.
+     *
+     * @param file the file
+     * @return true if the file should be formatted when close braces are typed; otherwise false
+     */
+    public boolean isFormatOnCloseBrace(@NotNull PsiFile file) {
+        // Default to disabled
+        return false;
+    }
+
+    /**
+     * The specific close brace characters that should trigger client-side on-type formatting.
+     *
+     * @param file the file
+     * @return the close brace characters that should trigger on-type formatting or null if the language's standard
+     * close brace characters should be used
+     */
+    @Nullable
+    public String getFormatOnCloseBraceCharacters(@NotNull PsiFile file) {
+        // Default to the language's standard close brace characters
+        return null;
+    }
+
+    /**
+     * The scope that should be formatted using client-side on-type formatting when a close brace is typed. Allowed
+     * values are {@link FormattingScope#CODE_BLOCK CODE_BLOCK} and {@link FormattingScope#FILE FILE}. Defaults to
+     * {@link FormattingScope#CODE_BLOCK CODE_BLOCK}.
+     *
+     * @param file the file
+     * @return the format scope
+     */
+    @NotNull
+    public FormattingScope getFormatOnCloseBraceScope(@NotNull PsiFile file) {
+        // Default to CODE_BLOCK
+        return FormattingScope.CODE_BLOCK;
+    }
+
+    /**
+     * Whether or not to format on statement terminator using client-side on-type formatting. Defaults to false.
+     *
+     * @param file the file
+     * @return true if the file should be formatted when statement terminators are typed; otherwise false
+     */
+    public boolean isFormatOnStatementTerminator(@NotNull PsiFile file) {
+        // Default to disabled
+        return false;
+    }
+
+    /**
+     * The specific statement terminator characters that should trigger client-side on-type formatting.
+     *
+     * @param file the file
+     * @return the statement terminator characters that should trigger on-type formatting
+     */
+    @Nullable
+    public String getFormatOnStatementTerminatorCharacters(@NotNull PsiFile file) {
+        // Default to none
+        return null;
+    }
+
+    /**
+     * The scope that should be formatted using client-side on-type formatting when a statement terminator is typed.
+     * Allowed values are {@link FormattingScope#STATEMENT STATEMENT}, {@link FormattingScope#CODE_BLOCK CODE_BLOCK},
+     * and {@link FormattingScope#FILE FILE}. Defaults to {@link FormattingScope#STATEMENT STATEMENT}.
+     *
+     * @param file the file
+     * @return the format scope
+     */
+    @NotNull
+    public FormattingScope getFormatOnStatementTerminatorScope(@NotNull PsiFile file) {
+        // Default to STATEMENT
+        return FormattingScope.STATEMENT;
+    }
+
+    /**
+     * Whether or not to format using client-side on-type formatting on completion trigger. Defaults to false.
+     *
+     * @param file the file
+     * @return true if the file should be formatted when completion triggers are typed; otherwise false
+     */
+    public boolean isFormatOnCompletionTrigger(@NotNull PsiFile file) {
+        // Default to disabled
+        return false;
+    }
+
+    /**
+     * The specific completion trigger characters that should trigger client-side on-type formatting.
+     *
+     * @param file the file
+     * @return the completion trigger characters that should trigger on-type formatting or null if the language's
+     * standard completion trigger characters should be used
+     */
+    @Nullable
+    public String getFormatOnCompletionTriggerCharacters(@NotNull PsiFile file) {
+        // Default to the language's standard completion trigger characters
+        return null;
+    }
 }