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

@@ -389,29 +389,31 @@ showing automatic folding of both the file header comment and imports when the f
 
 ![textDocument/foldingRange_collapseByDefault](./images/lsp-support/textDocument_foldingRange_collapseByDefault.gif)
 
-#### Code block provider
+### Selection range
+
+[textDocument/selectionRange](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_selectionRange) is implemented with
+the `extendWordSelectionHandler` extension point and used via the IDE's **Extend Selection** (**Ctrl+W** on Windows/Linux; **Opt+Up** on Mac) and **Shrink Selection** (**Ctrl+Shift+W** on Windows/Linux; **Opt+Down** on Mac) actions.
+
+Here is an example with the [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server) showing **Extend/Shrink Selection** using `textDocument/selectionRange`:
+
+![textDocument/selectionRange](./images/lsp-support/textDocument_selectionRange.gif)
 
-Additionally LSP4IJ registers the an implementation of the `codeBlockProvider` extension point with
+### Code block provider
+
+LSP4IJ registers the an implementation of the `codeBlockProvider` extension point with
 [LSPCodeBlockProvider](https://github.com/redhat-developer/lsp4ij/blob/main/src/main/java/com/redhat/devtools/lsp4ij/features/foldingRange/LSPCodeBlockProvider.java) for `TEXT` and `textmate` languages to provide block brace matching and easy navigation to
-the beginning/end of the containing block.
+the beginning/end of the containing block. For maximum flexibility in the absence of a true AST in the LSP client, code
+blocks are derived from `textDocument/selectionRange` first and, failing that, from `textDocument/foldingRange`.
 
-As with `lang.foldingBuilder`, if you use another language, you will have to declare `codeBlockProvider` with your language. 
+As with other language-specific EP implementations, if you use another language, you will have to declare
+`codeBlockProvider` with your language.
 
 Below is an example with the [TypeScript Language Server](./user-defined-ls/typescript-language-server.md) showing code
 block functionality. The IDE's Presentation Assistant shows the default keyboard shortcuts for each supported operating
 system to trigger these actions.
 
 ![codeBlockProvider](./images/lsp-support/codeBlockProvider.gif)
 
-### Selection range
-
-[textDocument/selectionRange](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_selectionRange) is implemented with
-the `extendWordSelectionHandler` extension point and used via the IDE's **Extend Selection** (**Ctrl+W** on Windows/Linux; **Opt+Up** on Mac) and **Shrink Selection** (**Ctrl+Shift+W** on Windows/Linux; **Opt+Down** on Mac) actions.
-
-Here is an example with the [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server) showing **Extend/Shrink Selection** using `textDocument/selectionRange`:
-
-![textDocument/selectionRange](./images/lsp-support/textDocument_selectionRange.gif)
-
 ### Publish Diagnostics
 
 [textDocument/publishDiagnostics](https://microsoft.github.io/language-server-protocol/specifications/lsp/3.17/specification/#textDocument_publishDiagnostics) is implemented with an `externalAnnotator` extension point. As this extension point supports `any` language, it works out-of-the-box.
@@ -458,6 +460,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.