@codingame/monaco-vscode-api 1.68.5 → 1.69.0

package/README.md

@@ -11,19 +11,114 @@ The VSCode api is composed of:
   - If it's some advanced features that don't make a lot of sense on Monaco (debug, tests...), it just throws an error when you try to use it.
 
 
-To implement by hands the optional features (type hierarchy, call hierarchy...), you can use the `Services` namespace from `vscode/services`:
+To implement by hands the optional features (file system, workspace folders, file...), you can use the `Services` namespace from `vscode/services`:
 ```typescript
 import { Services } from 'vscode/services'
 Services.install({
-   languages: {
-       registerTypeHierarchyProvider (documentSelector, provider) {
-           ...
-       }
-   }
+  workspace: {
+    workspaceFolders: ...,
+    createFileSystemWatcher (documentSelector, provider) {
+      ...
+    },
+    onDidSaveTextDocument
+  },
+  window: {
+    withProgress: ...
+  }
 })
 ```
 
+## Monaco standalone services
 
+Also, monaco-editor use `standalone` versions or the vscode services, which are much simpler.
+
+You may want to provide your custom implementations of them, especially for: `textModelService`, `codeEditorService` and `notificationService`. To do so, you can provide them as the third parameter while creating your first editor.
+This library allows you to use a more convenient way using `StandaloneService.initialize`.
+Also, monaco-editor doesn't provide good type for them, so this library does it.
+
+Example:
+```typescript
+import { StandaloneService, INotificationService } from 'vscode/services'
+
+class MyCustomNotificationService implements INotificationService { ... }
+StandaloneService.initialize({
+  get [INotificationService.toString()] () {
+    return new MyCustomNotificationService(...)
+  }
+})
+```
+
+Additionally, this library exposes 10 modules that include the vscode version of some services (with some glue to make it work with monaco):
+- Notification / Dialog: `vscode/service-override/messages`
+- Model / Editor: `vscode/service-override/modelEditor`
+- Configuration: `vscode/service-override/configuration`
+- Keybindings: `vscode/service-override/keybindings`
+- Language configuration: `vscode/service-override/languageConfiguration`
+- Languages: `vscode/service-override/languages`
+- Textmate: `vscode/service-override/textmate`
+- Snippets: `vscode/service-override/snippets`
+- VSCode themes: `vscode/service-override/theme`
+- Token classification: `vscode/service-override/tokenClassification`
+
+Usage:
+```typescript
+import { StandaloneService } from 'vscode/services'
+import getModelEditorServiceOverride from 'vscode/service-override/modelEditor'
+import getMessageServiceOverride from 'vscode/service-override/messages'
+import getConfigurationServiceOverride, { updateUserConfiguration, configurationRegistry } from 'vscode/service-override/configuration'
+
+StandaloneServices.initialize({
+  ...getModelEditorServiceOverride((model, input, sideBySide) => {
+    // Open a new editor here and return it
+    // It will be called when for instance the user ctrl+click on an import
+  }),
+  ...getMessageServiceOverride(document.body),
+  ...getConfigurationServiceOverride()
+})
+
+configurationRegistry.registerDefaultConfigurations([{
+  overrides: {
+    'editor.fontSize': 10
+  }
+}])
+
+updateUserConfiguration(`{
+  "editor.fontSize": 12,
+  "[java]": {
+    "editor.fontSize": 15,
+  }
+}`)
+```
+
+Note: using `vscode/service-override/modelEditor`, you'll be able to use the `vscode.workspace.registerTextDocumentContentProvider` api
+
+### Troubleshoot
+
+`StandaloneServices.initialize` can only be called once (note that `monaco.editor.create` calls `StandaloneServices.initialize`).
+
+Also, a service that is used cannot be overriden anymore. So `StandaloneServices.initialize` should be called as soon as possible to prevent most of the issues.
+
+## Editor configuration
+
+The editors created using `monaco.editor.create` don't use the configuration from the configurationService.
+
+This library exposes functions to create editors binded on the configuration:
+
+before:
+```typescript
+import * as monaco from 'monaco-editor'
+monaco.editor.create(...)
+```
+
+after:
+```typescript
+import { createConfiguredEditor } from 'vscode/monaco'
+
+createConfiguredEditor(...)
+```
+
+`createConfiguredEditor` returns a subclass of what is returned by `monaco.editor.create`, the `updateOptions` method can still be used.
+The only difference is that is will use the `configurationService` as a default configuration
 
 ### Installation
 
@@ -39,7 +134,7 @@ Just import it as if you were in a vscode extension:
 ```typescript
 import * as vscode from 'vscode'
 
-const range = new new vscode.Range(...)
+const range = new vscode.Range(...)
 vscode.languages.registerCompletionItemProvider(...)
 ```